orchestrator/src/types/transactionState.ts

@@ -85,3 +85,63 @@ export const ROLE_FOR_TRANSITION: Readonly<Record<string, ActorRole>> = {
   "VALIDATING->COMMITTED": "approver",
   "ABORTED->UNWIND_PENDING": "exception_manager",
 };
+
+/**
+ * Per-state phase timeouts (arch §12.1 timing exceptions, gap v2 §7.6 / §10.7).
+ *
+ * Each state has its own watchdog: if a plan sits in `state` for longer than
+ * `PHASE_TIMEOUTS[state]` ms, the exception manager raises a timing exception
+ * from arch §12.1 and transitions the plan toward ABORTED (or whatever the
+ * policy dictates for that state).
+ *
+ * Terminal states (COMMITTED → CLOSED path; CLOSED) have no timeout — they
+ * are end-of-lifecycle and not supposed to be aged out.
+ *
+ * Values are defaults. Each entry can be individually overridden via env:
+ *   PHASE_TIMEOUT_<STATE>=<ms>
+ * e.g. PHASE_TIMEOUT_EXECUTING=180000. Unit: milliseconds.
+ *
+ * Rationale for defaults:
+ *   DRAFT                    — long; plans can sit in draft for days.
+ *   INITIATED                — short; identity + terms hashing is deterministic.
+ *   PRECONDITIONS_PENDING    — long; human KYC / control approvals.
+ *   READY_FOR_PREPARE        — short; just awaits programmatic prepare.
+ *   PREPARED                 — medium; both legs confirm readiness.
+ *   EXECUTING                — medium; dispatch timeouts from arch §12.1.
+ *   PARTIALLY_EXECUTED       — medium; waits for the lagging leg.
+ *   VALIDATING               — medium; reconciliation + ack/settle evidence.
+ *   ABORTED                  — short; decision of unwind-vs-close should be prompt.
+ *   UNWIND_PENDING           — long; recovery procedures can be slow/manual.
+ */
+export const DEFAULT_PHASE_TIMEOUTS: Readonly<Record<TransactionState, number | null>> = {
+  DRAFT: 24 * 60 * 60 * 1000,              // 24 h
+  INITIATED: 5 * 60 * 1000,                //  5 min
+  PRECONDITIONS_PENDING: 4 * 60 * 60 * 1000, // 4 h
+  READY_FOR_PREPARE: 15 * 60 * 1000,       // 15 min
+  PREPARED: 30 * 60 * 1000,                // 30 min
+  EXECUTING: 10 * 60 * 1000,               // 10 min (dispatch_timeout §12.1)
+  PARTIALLY_EXECUTED: 15 * 60 * 1000,      // 15 min (settlement_timeout §12.1)
+  VALIDATING: 10 * 60 * 1000,              // 10 min
+  COMMITTED: 60 * 60 * 1000,               //  1 h (waiting to be CLOSED)
+  ABORTED: 10 * 60 * 1000,                 // 10 min
+  UNWIND_PENDING: 12 * 60 * 60 * 1000,     // 12 h
+  CLOSED: null,                            // terminal
+};
+
+/**
+ * Read the effective timeout (ms) for a given state, honouring per-state
+ * env overrides (`PHASE_TIMEOUT_<STATE>`). Returns `null` when the state
+ * has no timeout (terminal / explicitly disabled via override of "0").
+ */
+export function getPhaseTimeoutMs(state: TransactionState): number | null {
+  const override = process.env[`PHASE_TIMEOUT_${state}`];
+  if (override !== undefined) {
+    const parsed = Number(override);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+      // Fall through to default when env value is invalid.
+      return DEFAULT_PHASE_TIMEOUTS[state];
+    }
+    return parsed === 0 ? null : parsed;
+  }
+  return DEFAULT_PHASE_TIMEOUTS[state];
+}

orchestrator/tests/unit/phaseTimeouts.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Tests for per-state phase timeouts (arch §12.1 / gap v2 §7.6 / §10.7).
+ */
+
+import {
+  DEFAULT_PHASE_TIMEOUTS,
+  TRANSACTION_STATES,
+  getPhaseTimeoutMs,
+} from "../../src/types/transactionState";
+
+describe("PHASE_TIMEOUTS", () => {
+  const savedEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...savedEnv };
+  });
+
+  it("has a mapping for every declared transaction state", () => {
+    for (const s of TRANSACTION_STATES) {
+      expect(DEFAULT_PHASE_TIMEOUTS).toHaveProperty(s);
+    }
+  });
+
+  it("CLOSED is the only state without a timeout", () => {
+    const nullStates = TRANSACTION_STATES.filter(
+      (s) => DEFAULT_PHASE_TIMEOUTS[s] === null,
+    );
+    expect(nullStates).toEqual(["CLOSED"]);
+  });
+
+  it("all non-terminal timeouts are strictly positive integers", () => {
+    for (const s of TRANSACTION_STATES) {
+      const v = DEFAULT_PHASE_TIMEOUTS[s];
+      if (v === null) continue;
+      expect(v).toBeGreaterThan(0);
+      expect(Number.isInteger(v)).toBe(true);
+    }
+  });
+
+  it("getPhaseTimeoutMs honours a valid env override", () => {
+    process.env.PHASE_TIMEOUT_EXECUTING = "123456";
+    expect(getPhaseTimeoutMs("EXECUTING")).toBe(123456);
+  });
+
+  it("getPhaseTimeoutMs treats override '0' as 'no timeout' (null)", () => {
+    process.env.PHASE_TIMEOUT_EXECUTING = "0";
+    expect(getPhaseTimeoutMs("EXECUTING")).toBeNull();
+  });
+
+  it("getPhaseTimeoutMs falls back to default when override is invalid", () => {
+    process.env.PHASE_TIMEOUT_EXECUTING = "not-a-number";
+    expect(getPhaseTimeoutMs("EXECUTING")).toBe(
+      DEFAULT_PHASE_TIMEOUTS.EXECUTING,
+    );
+  });
+
+  it("getPhaseTimeoutMs falls back to default when override is negative", () => {
+    process.env.PHASE_TIMEOUT_PREPARED = "-1";
+    expect(getPhaseTimeoutMs("PREPARED")).toBe(
+      DEFAULT_PHASE_TIMEOUTS.PREPARED,
+    );
+  });
+
+  it("returns the default when no env override exists", () => {
+    delete process.env.PHASE_TIMEOUT_VALIDATING;
+    expect(getPhaseTimeoutMs("VALIDATING")).toBe(
+      DEFAULT_PHASE_TIMEOUTS.VALIDATING,
+    );
+  });
+
+  it("CLOSED stays null even with no env override", () => {
+    delete process.env.PHASE_TIMEOUT_CLOSED;
+    expect(getPhaseTimeoutMs("CLOSED")).toBeNull();
+  });
+});