From e3328725b400576c0985fde2c642884a7746cc99 Mon Sep 17 00:00:00 2001 From: Devin Date: Wed, 22 Apr 2026 18:10:51 +0000 Subject: [PATCH] Per-state PHASE_TIMEOUTS map + env overrides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes gap-analysis v2 §7.6 / §10.7. - Adds DEFAULT_PHASE_TIMEOUTS: Record to orchestrator/src/types/transactionState.ts, covering all 12 states of the §8 state machine with rationale-per-state comments. - getPhaseTimeoutMs(state) honours per-state env overrides (PHASE_TIMEOUT_=; '0' disables; invalid → default). - CLOSED is the only state with a null (no-timeout) value. - 9 unit tests; full suite passes. --- orchestrator/src/types/transactionState.ts | 60 +++++++++++++++ orchestrator/tests/unit/phaseTimeouts.test.ts | 75 +++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 orchestrator/tests/unit/phaseTimeouts.test.ts diff --git a/orchestrator/src/types/transactionState.ts b/orchestrator/src/types/transactionState.ts index 41b58dc..544c942 100644 --- a/orchestrator/src/types/transactionState.ts +++ b/orchestrator/src/types/transactionState.ts @@ -85,3 +85,63 @@ export const ROLE_FOR_TRANSITION: Readonly> = { "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_= + * 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> = { + 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_`). 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]; +} diff --git a/orchestrator/tests/unit/phaseTimeouts.test.ts b/orchestrator/tests/unit/phaseTimeouts.test.ts new file mode 100644 index 0000000..3152b04 --- /dev/null +++ b/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(); + }); +}); -- 2.34.1