Filosofía

Las capas emiten eventos tipados sin saber quién los consumirá. El bus dedupea, valida tipado, y proyecta a las superficies correspondientes al final del pipeline (no en runtime).

"Sistema nervioso del pipeline; las fases emiten signals como side-channel observacional y la transversal los proyecta al final una sola vez."

Catálogo central

SIGNAL_REGISTRY central con todos los signals válidos. Cada uno tiene SignalSpec:

SignalSpec {
    code: str,                          # "DUDA_CUENTA", "ERROR_LINEAS_VS_TOTAL", ...
    severity: ERROR | WARNING | INFO,
    intent: REVIEW | INFORM | BLOCK,
    audience: list[INTERNAL | CLIENT_VIA_ERP_TAG | CLIENT_VIA_ERP_COMMENT | AUDIT_LOG],
    template_message_es: str,           # i18n string template
    blocks_execution: bool,
    dedupe_key_template: str?,
}

Cuando una capa emite un signal con código no registrado en SIGNAL_REGISTRY → falla. Tipado runtime.

Tipos de signals (categorías)

Dedupe

Cada signal tiene dedupe_key (template parametrizado por document_id, plan_id, etc.). El bus mantiene seen_dedupe_keys por workflow execution. Si un signal con la misma key se emite dos veces → segundo emit se descarta.

Esto previene duplicación cuando una capa emite el mismo signal varias veces durante un workflow.

Proyección a surfaces

Al final del workflow (después del Executor, antes de cerrar el WF), un componente signal_projector consume el SignalBag y proyecta:

La projection es idempotente (al re-ejecutarse, no duplica tags ni comments). Esto es importante porque la lógica de signal lives in different layers — solo se materializa una vez al final.

Frontera con T1 (signals existente del target V2)

Esta sección hereda el diseño de transversal-signals.md del target V2. Cambios menores:

• Adapter explícito para convertir ValidationFinding (Fase 5) y FinalValidationFinding (Fase 9) a signals via tabla declarativa (validation_code → SignalSpec).
• Audience filter enforced: signal con audience=INTERNAL NO sale a Holded.
• Mensajes humanos i18n: castellano en messages_es.py, no en if/elif del código.

Filosofía

El pipeline corre como parent workflow + child workflows durables. Cada bloque racional de side effect (LLM call, group provider idempotente, DB read/write) es un activity. Crashes a mid-pipeline reanudan desde último boundary exitoso.

"Es plumería, no lógica de negocio. La pipeline real es invocable desde tests, evals y los activities — todos por igual."

Estructura

                    AccountingV3OrchestrationWorkflow (parent)
                                  │
                ┌─────────────────┴────────────────┐
                │                                  │
        MotorWorkflow (child)            IntegratorWorkflow (child)
        (M1: fases 1-5)                  (I1: plan gen + executor + final val)
                │                                  │
        ┌───────┴───────┐                  ┌───────┴───────┐
        │ activities    │                  │ activities    │
        │ - prepare_    │                  │ - lookup_plan_│
        │   facts       │                  │   store       │
        │ - decide_     │                  │ - call_plan_  │
        │   account     │                  │   generator   │
        │ - decide_cost_│                  │ - execute_    │
        │   center      │                  │   provider_   │
        │ - decide_     │                  │   group       │
        │   fiscal      │                  │ - capture_    │
        │ - compose_    │                  │   readback    │
        │   plan        │                  │ - validate_   │
        │ - validate_   │                  │   final       │
        │   invariants  │                  └───────────────┘
        └───────────────┘
                                                  │
                                                  ▼
                                  ┌────────────────────────────┐
                                  │  HighConfidence?           │
                                  │     ├─ Yes → executor      │
                                  │     └─ No  → dashboard wait │
                                  └────────────────────────────┘

Para reverse-sync (T4), hay un workflow distinto que corre asíncrono:

ReverseSyncMonitorWorkflow (independiente, continuous)
        │
        ├── poll_holded_changes_activity
        ├── interpret_comments_activity (LLM)
        └── emit_signals_to_bus_activity

Para calcificación (T3), workflow más complejo:

CalcificationLoopWorkflow (independiente, scheduled)
        │
        ├── collect_evidence_activity
        ├── propose_rule_activity (genera candidates)
        ├── shadow_test_activity (compara contra agente N=15 ejecuciones)
        ├── wait_for_intelia_ops_approval (signal-based)
        └── promote_rule_activity

Retries por dominio de fallo

non_retryable=True para errores de input validation, schema mismatch, etc.

Idempotencia por workflow_id

workflow_id determinista por document_id + version. Reuse policy REJECT_DUPLICATE en prod. Disparar el mismo documento dos veces no duplica trabajo.

Para reprocessing (e.g. re-run con nueva versión de M1): workflow_id = f"doc-{document_id}-v{m1_version}". Nuevo workflow_id permite re-run sin colisión.

Aislamiento de entornos

Workers arrancan con dos namespaces:

• intelia-prod (o intelia-stage): para workflows productivos.
• evals: aislado, para batch evals sin contaminar history productivo.

Tests locales saltan Temporal completamente.