1. Responsabilidad

TX es la capa transversal que hace que V3 sea durable, observable, idempotente y aprendible. Coordina procesos, persiste señales operacionales y mantiene la historia de cada documento / plan.

2. NO es su responsabilidad

• No contiene criterio contable. Un workflow no decide cuenta ni impuesto.
• No agrega validaciones ni guards. Las validaciones viven en sus capas (M1, I1).
• No mutates DB directamente. Toda escritura va vía activity que llama a un repository.
• No es la única forma de ejecutar el pipeline. Tests y evals invocan AccountingV3Pipeline directo, saltándose Temporal.
• No conoce semántica fiscal ni contable. Pasa estructuras opacas entre activities sin inspeccionarlas.

3. Señales first-class

V3 necesita eventos estructurados para poder aprender y auditar.

SignalSpec {
    code: str,                          # "DUDA_CUENTA", "EDITED_BY_HUMAN", ...
    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
    blocks_execution: bool,
    dedupe_key_template: str?,
}

4. Workflows principales

DocumentAccountingWorkflow {
    children: [
        MotorWorkflow (M1 fases 1-5),
        IntegratorWorkflow (I1: plan gen + validation + executor + final val)
    ],
    signals: emite/recibe del bus,
    output: ExecutionOutcome
}

ReverseSyncMonitorWorkflow {
    activities: [
        poll_holded_changes_activity,
        interpret_comments_activity (LLM),
        emit_signals_to_bus_activity
    ]
}

CalcificationLoopWorkflow {
    activities: [
        collect_evidence_activity,
        propose_rule_activity,
        shadow_test_activity (compara contra agente N=15),
        wait_for_intelia_ops_approval (signal-based),
        promote_rule_activity
    ]
}

5. Idempotencia por diseño

• workflow_id determinista por document_id + version.
• Reuse policy REJECT_DUPLICATE en producción. Dispara el mismo doc dos veces no duplica trabajo.
• Para reprocessing legítimo: workflow_id = f"doc-{document_id}-v{m1_version}". Nuevo workflow_id permite re-run sin colisión.
• Activities con dedupe_key propio para cada operación que toque Holded.

6. Estado y versionado

V3 evita overwrites conceptuales. Cada artefacto relevante tiene versión:

• internal_plan_v<N> por documento.
• execution_plan_v<N> por documento.
• motor_metadata con rule_versions, llm_versions, input_hash.
• signal_audit_log versionado.

No se sobrescribe nada silenciosamente. Re-decisión produce nuevo versión.

7. Retries por dominio de fallo

non_retryable=True para input validation errors, schema mismatches contractuales.

8. Aislamiento de entornos

Workers arrancan con dos namespaces:

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

Tests locales saltan Temporal completamente (pipeline invocable directo).

9. Contratos de actividades

Las actividades son estrechas y propiedad de cada capa:

Las actividades NO llaman servicios cruzados. Cada una pertenece a una capa.

10. Observabilidad

V3 debe responder:

• ¿Por qué se decidió esta cuenta? (M1 audit log + decision rationale + rule version)
• ¿Por qué se ejecutó este plan Holded? (I1 plan + ExecutionPlan + agent reasoning_trace)
• ¿Qué edición hizo el contable y cuándo? (T4 signals)
• ¿Qué reglas calcificadas aplicaron en este cliente este mes? (T3 audit)
• ¿Cuántos planes están pendientes ahora mismo? (Pending Plans state)
• ¿Cuál es el coste LLM por documento por madurez? (Métricas TX)

11. Fronteras

12. Riesgos y mitigaciones

13. Lo que puede salir mal

Patología 1: TX se convierte en sitio "por comodidad" para lógica que no encaja. Cuando una decisión no tiene lugar claro, se mete en workflow porque ahí "tiene state". Temporal absorbe decisiones. Mitigación: lint + code review obligatorio.

Patología 2: signal explosion. Cada capa empieza a emitir signals indiscriminadamente. 200+ tipos al año, contable ve 20 tags por documento. Mitigación: catálogo central con review obligatorio. Lint que prohíbe emit_signal("custom_code", ...) con código fuera del registry.

Patología 3: dedupe de comments rota. Comments duplicados en Holded porque dedupe_key incompleto. Mitigación: hash de signal bag completo, no per-signal. Si bag cambia → repost; si no → skip.

Patología 4: Temporal history excesivo. Cada signal añade evento al history. 1000 signals/workflow → history pesa MB. Mitigación: signals INTERNAL fuera del history.

14. Métricas operacionales

15. Open questions

• ¿Cuál es el schema mínimo común de signal para todo V3?
• Versionado del SIGNAL_REGISTRY: política de aliasing cuando se renombra signal.
• Granularidad de activities: ¿call_plan_generator es 1 activity o N (una por tool call)? Trade-off granularidad vs latencia.
• ¿Cada cuánto continue_as_new en monitor workflows? Propuesta: cada 1000 events.
• ¿Activities asíncronas tras workflow completion? Para projection a alert lento.
• Aislamiento per-tenant: ¿cada cliente tiene namespace propio o todos en intelia-prod? Trade-off seguridad y operacional.

Diferencias respecto al target V2 documentado

El target V2 ya tiene transversales Signals + Temporal bien diseñadas. V3 las conserva mayoritariamente, con cambios menores:

1. Adapter explícito Validation → Signals vía tabla declarativa.
2. Workflows nuevos para T3 y T4 (no existían en target V2).
3. Signal Registry como contrato versionado (no solo dict).
4. Persistencia de signals INTERNAL fuera del workflow history para mantener Temporal history compact.

El resto del diseño (parent + 2 children, durabilidad, retries por dominio, idempotencia por workflow_id, aislamiento de entornos, pipeline invocable sin Temporal) se mantiene.

Síntesis. Detalle granular en versiones originales.