open-multi-agent-kit 0.80.5 → 0.80.7

package/dist/core/orchestration/transaction-coordinator.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Phase 1: fail-closed, ledger-gated transaction coordinator (pure algorithms).
+ *
+ * These functions are deterministic and side-effect free except through the
+ * injected in-memory transaction/store callbacks. No SQLite or filesystem is
+ * wired here; the real durable store is injected later. The invariant enforced
+ * is: no state-changing mutation commits unless its required ledger event was
+ * durably appended (JSONL fsync) and mirrored, in that order.
+ *
+ * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md
+ * (Phase 1) and audit-transaction.md.
+ */
+import { type TransactionPhase } from "./errors.ts";
+/**
+ * A canonical, content-addressed ledger event record. `eventHash` is derived
+ * deterministically from the identity + state hashes, which is what makes
+ * idempotency detection (same key + same hash => no-op) reliable.
+ */
+export interface LedgerRecord {
+    operationId: string;
+    runId: string;
+    nodeId: string;
+    eventType: string;
+    phase: TransactionPhase;
+    idempotencyKey: string;
+    beforeStateHash: string;
+    afterStateHash: string;
+    eventHash: string;
+    attemptId?: string;
+}
+/**
+ * Identity + intent for a single ledger-gated mutation. `mutate` is pure: it
+ * receives the snapshot and returns the staged next state without committing.
+ */
+export interface LedgerGatedTransactionRequest<S> {
+    runId: string;
+    nodeId: string;
+    operationId: string;
+    eventType: string;
+    phase: TransactionPhase;
+    idempotencyKey: string;
+    mutate: (before: S) => S;
+    attemptId?: string;
+}
+/**
+ * Injected transaction handle (a single `BEGIN IMMEDIATE` scope). The fake used
+ * in tests and the real SQLite-backed handle implement this surface.
+ *
+ * Contract:
+ * - `appendRequiredEvent` simulates the durable JSONL append + fsync. It escapes
+ *   transactional rollback (an appended event stays on disk).
+ * - `mirrorEvent` stages the SQLite mirror insert inside the open transaction.
+ * - `commit` applies the staged mirror + state; `rollback` discards them.
+ */
+export interface LedgerGatedTransactionHandle<S> {
+    snapshot: () => S;
+    findByIdempotencyKey: (key: string) => LedgerRecord | undefined;
+    appendRequiredEvent: (record: LedgerRecord) => void;
+    mirrorEvent: (record: LedgerRecord) => void;
+    commit: (state: S) => void;
+    rollback: () => void;
+}
+export interface LedgerGatedTransactionDeps<S> {
+    begin: () => LedgerGatedTransactionHandle<S>;
+    hashState?: (state: S) => string;
+}
+export type LedgerGatedTransactionStatus = "committed" | "noop";
+export interface LedgerGatedTransactionResult<S> {
+    status: LedgerGatedTransactionStatus;
+    applied: boolean;
+    record: LedgerRecord;
+    state: S;
+}
+/**
+ * Default state hash. Callers with non-JSON state must inject `hashState`.
+ */
+export declare function coordinatorStateHash(state: unknown): string;
+/**
+ * Deterministically derive a content hash for a ledger event from its identity
+ * and state transition. Volatile fields are excluded so replays are stable.
+ */
+export declare function computeCoordinatorEventHash(input: {
+    operationId: string;
+    runId: string;
+    nodeId: string;
+    eventType: string;
+    phase: TransactionPhase;
+    idempotencyKey: string;
+    beforeStateHash: string;
+    afterStateHash: string;
+    attemptId?: string;
+}): string;
+/**
+ * Build a complete ledger record (including `eventHash`) from a request and the
+ * computed before/after state hashes.
+ */
+export declare function buildLedgerRecord(request: {
+    operationId: string;
+    runId: string;
+    nodeId: string;
+    eventType: string;
+    phase: TransactionPhase;
+    idempotencyKey: string;
+    attemptId?: string;
+}, beforeStateHash: string, afterStateHash: string): LedgerRecord;
+/**
+ * Run one fail-closed, ledger-gated state-changing transaction.
+ *
+ * ```text
+ * BEGIN IMMEDIATE
+ * before = snapshot()
+ * staged = mutate(before)            # no commit yet
+ * record = ledger event with before/after state hashes
+ * idempotency:
+ *   same key + same eventHash  -> rollback, no-op
+ *   same key + different hash   -> rollback, IDEMPOTENCY_CONFLICT
+ * appendRequiredEvent(record)        # durable JSONL append + fsync
+ *   fail -> rollback, LEDGER_APPEND_REQUIRED_FAILED
+ * mirrorEvent(record)                # same transaction
+ *   fail -> rollback, SQLITE_MIRROR_FAILED (ledger durable; replay repairs)
+ * commit(staged)
+ *   fail -> rollback, SQLITE_COMMIT_AFTER_LEDGER_FAILED (ledger durable)
+ * ```
+ *
+ * Any failure leaves the injected store unmutated (transaction rolled back);
+ * only the durable ledger append can survive, which recovery/replay reconciles.
+ */
+export declare function runLedgerGatedTransaction<S>(deps: LedgerGatedTransactionDeps<S>, request: LedgerGatedTransactionRequest<S>): LedgerGatedTransactionResult<S>;
+/**
+ * A single side-effecting step that must record a receipt after its side effect.
+ * Each step declares a stable `receiptId` so a durable receipt can short-circuit
+ * re-execution on replay.
+ */
+export interface ReceiptedStep {
+    id: string;
+    receiptId: string;
+    sequence: number;
+    idempotent: boolean;
+    beforeStateHash: string;
+    afterStateHash: string;
+    run: () => void;
+}
+export interface ReceiptHandle {
+    findReceipt: (receiptId: string) => LedgerRecord | undefined;
+    appendReceiptEvent: (record: LedgerRecord) => void;
+}
+export interface ReceiptApplyRequest {
+    runId: string;
+    nodeId: string;
+    operationId: string;
+    attemptId?: string;
+    eventType?: string;
+    steps: readonly ReceiptedStep[];
+}
+export type ReceiptApplyStatus = "completed" | "in_doubt";
+export interface ReceiptApplyResult {
+    status: ReceiptApplyStatus;
+    executedStepIds: string[];
+    skippedStepIds: string[];
+    appliedReceipts: LedgerRecord[];
+    stoppedAtStepId?: string;
+    reason?: string;
+}
+/**
+ * Apply side-effecting steps in deterministic sequence order, recording a
+ * required receipt after each side effect.
+ *
+ * Fail-closed rule (algorithm-plan Phase 1, test 3): if a receipt append fails
+ * after its side effect ran, stop executing further side effects and return
+ * `in_doubt` — UNLESS a durable idempotent receipt for that step exists, in
+ * which case the side effect is provably recorded and execution continues.
+ *
+ * Steps whose receipt is already durably recorded are skipped (idempotent
+ * replay) and never re-run.
+ */
+export declare function applyReceiptedSteps(handle: ReceiptHandle, request: ReceiptApplyRequest): ReceiptApplyResult;
+/**
+ * A registered compensator and its forward-execution status.
+ */
+export interface CompensatorExecutionStep {
+    id: string;
+    sequence: number;
+    idempotent: boolean;
+    applied: boolean;
+    run: () => void;
+}
+export interface CompensationHandle {
+    appendCompensationStart: (record: LedgerRecord) => void;
+    appendCompensationReceipt: (record: LedgerRecord) => void;
+}
+export interface GatedCompensationRequest {
+    runId: string;
+    nodeId: string;
+    operationId: string;
+    idempotencyKey: string;
+    beforeStateHash: string;
+    afterStateHash: string;
+    attemptId?: string;
+    steps: readonly CompensatorExecutionStep[];
+}
+export interface GatedCompensationResult {
+    status: "rolled_back";
+    executedStepIds: string[];
+    receipts: LedgerRecord[];
+}
+/**
+ * Run compensation fail-closed (algorithm-plan Phase 1, test 4 + invariant I7).
+ *
+ * 1. Refuse to auto-compensate if any NON-idempotent step was already applied
+ *    (state is ambiguous): throw COMPENSATION_FAILED before anything runs.
+ * 2. The compensation start is itself ledger-gated: if its required event cannot
+ *    be appended, throw RequiredAuditWriteError and run NO compensators.
+ * 3. Only idempotent compensators run, in reverse execution order, each
+ *    recording a compensation receipt.
+ */
+export declare function runGatedCompensation(handle: CompensationHandle, request: GatedCompensationRequest): GatedCompensationResult;
+//# sourceMappingURL=transaction-coordinator.d.ts.map

package/dist/core/orchestration/transaction-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/transaction-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Phase 1: fail-closed, ledger-gated transaction coordinator (pure algorithms).\n *\n * These functions are deterministic and side-effect free except through the\n * injected in-memory transaction/store callbacks. No SQLite or filesystem is\n * wired here; the real durable store is injected later. The invariant enforced\n * is: no state-changing mutation commits unless its required ledger event was\n * durably appended (JSONL fsync) and mirrored, in that order.\n *\n * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md\n * (Phase 1) and audit-transaction.md.\n */\n\nimport {\n\tCoordinatorError,\n\ttype CoordinatorRecoverability,\n\tRequiredAuditWriteError,\n\ttype TransactionPhase,\n} from \"./errors.ts\";\nimport { type JsonValue, sha256Hex, stableStringify } from \"./replay-ledger.ts\";\n\n/**\n * A canonical, content-addressed ledger event record. `eventHash` is derived\n * deterministically from the identity + state hashes, which is what makes\n * idempotency detection (same key + same hash => no-op) reliable.\n */\nexport interface LedgerRecord {\n\toperationId: string;\n\trunId: string;\n\tnodeId: string;\n\teventType: string;\n\tphase: TransactionPhase;\n\tidempotencyKey: string;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\teventHash: string;\n\tattemptId?: string;\n}\n\n/**\n * Identity + intent for a single ledger-gated mutation. `mutate` is pure: it\n * receives the snapshot and returns the staged next state without committing.\n */\nexport interface LedgerGatedTransactionRequest<S> {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\teventType: string;\n\tphase: TransactionPhase;\n\tidempotencyKey: string;\n\tmutate: (before: S) => S;\n\tattemptId?: string;\n}\n\n/**\n * Injected transaction handle (a single `BEGIN IMMEDIATE` scope). The fake used\n * in tests and the real SQLite-backed handle implement this surface.\n *\n * Contract:\n * - `appendRequiredEvent` simulates the durable JSONL append + fsync. It escapes\n *   transactional rollback (an appended event stays on disk).\n * - `mirrorEvent` stages the SQLite mirror insert inside the open transaction.\n * - `commit` applies the staged mirror + state; `rollback` discards them.\n */\nexport interface LedgerGatedTransactionHandle<S> {\n\tsnapshot: () => S;\n\tfindByIdempotencyKey: (key: string) => LedgerRecord | undefined;\n\tappendRequiredEvent: (record: LedgerRecord) => void;\n\tmirrorEvent: (record: LedgerRecord) => void;\n\tcommit: (state: S) => void;\n\trollback: () => void;\n}\n\nexport interface LedgerGatedTransactionDeps<S> {\n\tbegin: () => LedgerGatedTransactionHandle<S>;\n\thashState?: (state: S) => string;\n}\n\nexport type LedgerGatedTransactionStatus = \"committed\" | \"noop\";\n\nexport interface LedgerGatedTransactionResult<S> {\n\tstatus: LedgerGatedTransactionStatus;\n\tapplied: boolean;\n\trecord: LedgerRecord;\n\tstate: S;\n}\n\n/**\n * Default state hash. Callers with non-JSON state must inject `hashState`.\n */\nexport function coordinatorStateHash(state: unknown): string {\n\treturn sha256Hex(stableStringify(state as JsonValue));\n}\n\n/**\n * Deterministically derive a content hash for a ledger event from its identity\n * and state transition. Volatile fields are excluded so replays are stable.\n */\nexport function computeCoordinatorEventHash(input: {\n\toperationId: string;\n\trunId: string;\n\tnodeId: string;\n\teventType: string;\n\tphase: TransactionPhase;\n\tidempotencyKey: string;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\tattemptId?: string;\n}): string {\n\tconst canonical: { readonly [key: string]: JsonValue } = {\n\t\toperationId: input.operationId,\n\t\trunId: input.runId,\n\t\tnodeId: input.nodeId,\n\t\teventType: input.eventType,\n\t\tphase: input.phase,\n\t\tidempotencyKey: input.idempotencyKey,\n\t\tbeforeStateHash: input.beforeStateHash,\n\t\tafterStateHash: input.afterStateHash,\n\t\tattemptId: input.attemptId ?? null,\n\t};\n\treturn sha256Hex(stableStringify(canonical));\n}\n\n/**\n * Build a complete ledger record (including `eventHash`) from a request and the\n * computed before/after state hashes.\n */\nexport function buildLedgerRecord(\n\trequest: {\n\t\toperationId: string;\n\t\trunId: string;\n\t\tnodeId: string;\n\t\teventType: string;\n\t\tphase: TransactionPhase;\n\t\tidempotencyKey: string;\n\t\tattemptId?: string;\n\t},\n\tbeforeStateHash: string,\n\tafterStateHash: string,\n): LedgerRecord {\n\tconst eventHash = computeCoordinatorEventHash({\n\t\toperationId: request.operationId,\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\teventType: request.eventType,\n\t\tphase: request.phase,\n\t\tidempotencyKey: request.idempotencyKey,\n\t\tbeforeStateHash,\n\t\tafterStateHash,\n\t\tattemptId: request.attemptId,\n\t});\n\treturn {\n\t\toperationId: request.operationId,\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\teventType: request.eventType,\n\t\tphase: request.phase,\n\t\tidempotencyKey: request.idempotencyKey,\n\t\tbeforeStateHash,\n\t\tafterStateHash,\n\t\teventHash,\n\t\t...(request.attemptId === undefined ? {} : { attemptId: request.attemptId }),\n\t};\n}\n\nfunction errorContext(\n\trequest: {\n\t\trunId: string;\n\t\tnodeId: string;\n\t\toperationId: string;\n\t\tphase: TransactionPhase;\n\t\teventType: string;\n\t\tattemptId?: string;\n\t},\n\trecoverability: CoordinatorRecoverability,\n\tcause?: unknown,\n): {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tphase: TransactionPhase;\n\teventType: string;\n\trecoverability: CoordinatorRecoverability;\n\tattemptId?: string;\n\tcause?: unknown;\n} {\n\treturn {\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\toperationId: request.operationId,\n\t\tphase: request.phase,\n\t\teventType: request.eventType,\n\t\trecoverability,\n\t\tattemptId: request.attemptId,\n\t\tcause,\n\t};\n}\n\n/**\n * Run one fail-closed, ledger-gated state-changing transaction.\n *\n * ```text\n * BEGIN IMMEDIATE\n * before = snapshot()\n * staged = mutate(before)            # no commit yet\n * record = ledger event with before/after state hashes\n * idempotency:\n *   same key + same eventHash  -> rollback, no-op\n *   same key + different hash   -> rollback, IDEMPOTENCY_CONFLICT\n * appendRequiredEvent(record)        # durable JSONL append + fsync\n *   fail -> rollback, LEDGER_APPEND_REQUIRED_FAILED\n * mirrorEvent(record)                # same transaction\n *   fail -> rollback, SQLITE_MIRROR_FAILED (ledger durable; replay repairs)\n * commit(staged)\n *   fail -> rollback, SQLITE_COMMIT_AFTER_LEDGER_FAILED (ledger durable)\n * ```\n *\n * Any failure leaves the injected store unmutated (transaction rolled back);\n * only the durable ledger append can survive, which recovery/replay reconciles.\n */\nexport function runLedgerGatedTransaction<S>(\n\tdeps: LedgerGatedTransactionDeps<S>,\n\trequest: LedgerGatedTransactionRequest<S>,\n): LedgerGatedTransactionResult<S> {\n\tconst hashState = deps.hashState ?? coordinatorStateHash;\n\tconst handle = deps.begin();\n\tlet settled = false;\n\tconst rollbackOnce = (): void => {\n\t\tif (!settled) {\n\t\t\tsettled = true;\n\t\t\thandle.rollback();\n\t\t}\n\t};\n\n\ttry {\n\t\tconst before = handle.snapshot();\n\t\tconst staged = request.mutate(before);\n\t\tconst record = buildLedgerRecord(request, hashState(before), hashState(staged));\n\n\t\tconst existing = handle.findByIdempotencyKey(request.idempotencyKey);\n\t\tif (existing !== undefined) {\n\t\t\trollbackOnce();\n\t\t\tif (existing.eventHash === record.eventHash) {\n\t\t\t\treturn { status: \"noop\", applied: false, record: existing, state: before };\n\t\t\t}\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"IDEMPOTENCY_CONFLICT\",\n\t\t\t\t`idempotency key \"${request.idempotencyKey}\" already recorded with a different event hash`,\n\t\t\t\terrorContext(request, \"operator\"),\n\t\t\t);\n\t\t}\n\n\t\ttry {\n\t\t\thandle.appendRequiredEvent(record);\n\t\t} catch (cause) {\n\t\t\trollbackOnce();\n\t\t\tthrow new RequiredAuditWriteError(\n\t\t\t\t`required ledger append failed for \"${request.eventType}\"`,\n\t\t\t\terrorContext(request, \"rollback\", cause),\n\t\t\t);\n\t\t}\n\n\t\ttry {\n\t\t\thandle.mirrorEvent(record);\n\t\t} catch (cause) {\n\t\t\trollbackOnce();\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"SQLITE_MIRROR_FAILED\",\n\t\t\t\t`sqlite mirror failed after ledger append for \"${request.eventType}\"`,\n\t\t\t\terrorContext(request, \"in_doubt\", cause),\n\t\t\t);\n\t\t}\n\n\t\ttry {\n\t\t\thandle.commit(staged);\n\t\t\tsettled = true;\n\t\t} catch (cause) {\n\t\t\trollbackOnce();\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"SQLITE_COMMIT_AFTER_LEDGER_FAILED\",\n\t\t\t\t`sqlite commit failed after ledger append for \"${request.eventType}\"`,\n\t\t\t\terrorContext(request, \"in_doubt\", cause),\n\t\t\t);\n\t\t}\n\n\t\treturn { status: \"committed\", applied: true, record, state: staged };\n\t} catch (error) {\n\t\trollbackOnce();\n\t\tthrow error;\n\t}\n}\n\n/**\n * A single side-effecting step that must record a receipt after its side effect.\n * Each step declares a stable `receiptId` so a durable receipt can short-circuit\n * re-execution on replay.\n */\nexport interface ReceiptedStep {\n\tid: string;\n\treceiptId: string;\n\tsequence: number;\n\tidempotent: boolean;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\trun: () => void;\n}\n\nexport interface ReceiptHandle {\n\tfindReceipt: (receiptId: string) => LedgerRecord | undefined;\n\tappendReceiptEvent: (record: LedgerRecord) => void;\n}\n\nexport interface ReceiptApplyRequest {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tattemptId?: string;\n\teventType?: string;\n\tsteps: readonly ReceiptedStep[];\n}\n\nexport type ReceiptApplyStatus = \"completed\" | \"in_doubt\";\n\nexport interface ReceiptApplyResult {\n\tstatus: ReceiptApplyStatus;\n\texecutedStepIds: string[];\n\tskippedStepIds: string[];\n\tappliedReceipts: LedgerRecord[];\n\tstoppedAtStepId?: string;\n\treason?: string;\n}\n\n/**\n * Apply side-effecting steps in deterministic sequence order, recording a\n * required receipt after each side effect.\n *\n * Fail-closed rule (algorithm-plan Phase 1, test 3): if a receipt append fails\n * after its side effect ran, stop executing further side effects and return\n * `in_doubt` — UNLESS a durable idempotent receipt for that step exists, in\n * which case the side effect is provably recorded and execution continues.\n *\n * Steps whose receipt is already durably recorded are skipped (idempotent\n * replay) and never re-run.\n */\nexport function applyReceiptedSteps(handle: ReceiptHandle, request: ReceiptApplyRequest): ReceiptApplyResult {\n\tconst eventType = request.eventType ?? \"scheduler.node.receipt\";\n\tconst ordered = [...request.steps].sort((a, b) => a.sequence - b.sequence);\n\tconst executedStepIds: string[] = [];\n\tconst skippedStepIds: string[] = [];\n\tconst appliedReceipts: LedgerRecord[] = [];\n\n\tfor (const step of ordered) {\n\t\tconst pre = handle.findReceipt(step.receiptId);\n\t\tif (pre !== undefined) {\n\t\t\t// Receipt already durable: idempotent replay, do not re-run the side effect.\n\t\t\tskippedStepIds.push(step.id);\n\t\t\tappliedReceipts.push(pre);\n\t\t\tcontinue;\n\t\t}\n\n\t\tstep.run();\n\t\texecutedStepIds.push(step.id);\n\n\t\tconst record = buildLedgerRecord(\n\t\t\t{\n\t\t\t\toperationId: request.operationId,\n\t\t\t\trunId: request.runId,\n\t\t\t\tnodeId: request.nodeId,\n\t\t\t\teventType,\n\t\t\t\tphase: \"receipt\",\n\t\t\t\tidempotencyKey: step.receiptId,\n\t\t\t\tattemptId: request.attemptId,\n\t\t\t},\n\t\t\tstep.beforeStateHash,\n\t\t\tstep.afterStateHash,\n\t\t);\n\n\t\ttry {\n\t\t\thandle.appendReceiptEvent(record);\n\t\t\tappliedReceipts.push(record);\n\t\t} catch {\n\t\t\tconst post = handle.findReceipt(step.receiptId);\n\t\t\tif (post !== undefined) {\n\t\t\t\t// Receipt persisted despite the append error: recoverable, keep going.\n\t\t\t\tappliedReceipts.push(post);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstatus: \"in_doubt\",\n\t\t\t\texecutedStepIds,\n\t\t\t\tskippedStepIds,\n\t\t\t\tappliedReceipts,\n\t\t\t\tstoppedAtStepId: step.id,\n\t\t\t\treason: `receipt append failed after side effect for step \"${step.id}\" with no durable receipt`,\n\t\t\t};\n\t\t}\n\t}\n\n\treturn { status: \"completed\", executedStepIds, skippedStepIds, appliedReceipts };\n}\n\n/**\n * A registered compensator and its forward-execution status.\n */\nexport interface CompensatorExecutionStep {\n\tid: string;\n\tsequence: number;\n\tidempotent: boolean;\n\tapplied: boolean;\n\trun: () => void;\n}\n\nexport interface CompensationHandle {\n\tappendCompensationStart: (record: LedgerRecord) => void;\n\tappendCompensationReceipt: (record: LedgerRecord) => void;\n}\n\nexport interface GatedCompensationRequest {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tidempotencyKey: string;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\tattemptId?: string;\n\tsteps: readonly CompensatorExecutionStep[];\n}\n\nexport interface GatedCompensationResult {\n\tstatus: \"rolled_back\";\n\texecutedStepIds: string[];\n\treceipts: LedgerRecord[];\n}\n\n/**\n * Run compensation fail-closed (algorithm-plan Phase 1, test 4 + invariant I7).\n *\n * 1. Refuse to auto-compensate if any NON-idempotent step was already applied\n *    (state is ambiguous): throw COMPENSATION_FAILED before anything runs.\n * 2. The compensation start is itself ledger-gated: if its required event cannot\n *    be appended, throw RequiredAuditWriteError and run NO compensators.\n * 3. Only idempotent compensators run, in reverse execution order, each\n *    recording a compensation receipt.\n */\nexport function runGatedCompensation(\n\thandle: CompensationHandle,\n\trequest: GatedCompensationRequest,\n): GatedCompensationResult {\n\tconst baseContext = {\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\toperationId: request.operationId,\n\t\tphase: \"compensate\" as TransactionPhase,\n\t\teventType: \"scheduler.node.compensating\",\n\t\tattemptId: request.attemptId,\n\t};\n\n\tfor (const step of request.steps) {\n\t\tif (!step.idempotent && step.applied) {\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"COMPENSATION_FAILED\",\n\t\t\t\t`cannot auto-compensate non-idempotent step \"${step.id}\" that was already applied`,\n\t\t\t\t{ ...baseContext, recoverability: \"in_doubt\" },\n\t\t\t);\n\t\t}\n\t}\n\n\tconst startRecord = buildLedgerRecord(\n\t\t{\n\t\t\toperationId: request.operationId,\n\t\t\trunId: request.runId,\n\t\t\tnodeId: request.nodeId,\n\t\t\teventType: \"scheduler.node.compensating\",\n\t\t\tphase: \"compensate\",\n\t\t\tidempotencyKey: request.idempotencyKey,\n\t\t\tattemptId: request.attemptId,\n\t\t},\n\t\trequest.beforeStateHash,\n\t\trequest.afterStateHash,\n\t);\n\n\ttry {\n\t\thandle.appendCompensationStart(startRecord);\n\t} catch (cause) {\n\t\tthrow new RequiredAuditWriteError(\"required compensation-start ledger append failed\", { ...baseContext, cause });\n\t}\n\n\tconst reversed = request.steps.filter((step) => step.idempotent).sort((a, b) => b.sequence - a.sequence);\n\tconst executedStepIds: string[] = [];\n\tconst receipts: LedgerRecord[] = [];\n\n\tfor (const step of reversed) {\n\t\ttry {\n\t\t\tstep.run();\n\t\t} catch (cause) {\n\t\t\tthrow new CoordinatorError(\"COMPENSATION_FAILED\", `compensator \"${step.id}\" failed`, {\n\t\t\t\t...baseContext,\n\t\t\t\trecoverability: \"in_doubt\",\n\t\t\t\tcause,\n\t\t\t});\n\t\t}\n\t\texecutedStepIds.push(step.id);\n\t\tconst receipt = buildLedgerRecord(\n\t\t\t{\n\t\t\t\toperationId: request.operationId,\n\t\t\t\trunId: request.runId,\n\t\t\t\tnodeId: request.nodeId,\n\t\t\t\teventType: \"scheduler.node.compensation.receipt\",\n\t\t\t\tphase: \"compensate\",\n\t\t\t\tidempotencyKey: `${request.idempotencyKey}:${step.id}`,\n\t\t\t\tattemptId: request.attemptId,\n\t\t\t},\n\t\t\trequest.beforeStateHash,\n\t\t\trequest.afterStateHash,\n\t\t);\n\t\thandle.appendCompensationReceipt(receipt);\n\t\treceipts.push(receipt);\n\t}\n\n\treturn { status: \"rolled_back\", executedStepIds, receipts };\n}\n"]}

package/dist/core/orchestration/transaction-coordinator.js

@@ -0,0 +1,281 @@
+/**
+ * Phase 1: fail-closed, ledger-gated transaction coordinator (pure algorithms).
+ *
+ * These functions are deterministic and side-effect free except through the
+ * injected in-memory transaction/store callbacks. No SQLite or filesystem is
+ * wired here; the real durable store is injected later. The invariant enforced
+ * is: no state-changing mutation commits unless its required ledger event was
+ * durably appended (JSONL fsync) and mirrored, in that order.
+ *
+ * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md
+ * (Phase 1) and audit-transaction.md.
+ */
+import { CoordinatorError, RequiredAuditWriteError, } from "./errors.js";
+import { sha256Hex, stableStringify } from "./replay-ledger.js";
+/**
+ * Default state hash. Callers with non-JSON state must inject `hashState`.
+ */
+export function coordinatorStateHash(state) {
+    return sha256Hex(stableStringify(state));
+}
+/**
+ * Deterministically derive a content hash for a ledger event from its identity
+ * and state transition. Volatile fields are excluded so replays are stable.
+ */
+export function computeCoordinatorEventHash(input) {
+    const canonical = {
+        operationId: input.operationId,
+        runId: input.runId,
+        nodeId: input.nodeId,
+        eventType: input.eventType,
+        phase: input.phase,
+        idempotencyKey: input.idempotencyKey,
+        beforeStateHash: input.beforeStateHash,
+        afterStateHash: input.afterStateHash,
+        attemptId: input.attemptId ?? null,
+    };
+    return sha256Hex(stableStringify(canonical));
+}
+/**
+ * Build a complete ledger record (including `eventHash`) from a request and the
+ * computed before/after state hashes.
+ */
+export function buildLedgerRecord(request, beforeStateHash, afterStateHash) {
+    const eventHash = computeCoordinatorEventHash({
+        operationId: request.operationId,
+        runId: request.runId,
+        nodeId: request.nodeId,
+        eventType: request.eventType,
+        phase: request.phase,
+        idempotencyKey: request.idempotencyKey,
+        beforeStateHash,
+        afterStateHash,
+        attemptId: request.attemptId,
+    });
+    return {
+        operationId: request.operationId,
+        runId: request.runId,
+        nodeId: request.nodeId,
+        eventType: request.eventType,
+        phase: request.phase,
+        idempotencyKey: request.idempotencyKey,
+        beforeStateHash,
+        afterStateHash,
+        eventHash,
+        ...(request.attemptId === undefined ? {} : { attemptId: request.attemptId }),
+    };
+}
+function errorContext(request, recoverability, cause) {
+    return {
+        runId: request.runId,
+        nodeId: request.nodeId,
+        operationId: request.operationId,
+        phase: request.phase,
+        eventType: request.eventType,
+        recoverability,
+        attemptId: request.attemptId,
+        cause,
+    };
+}
+/**
+ * Run one fail-closed, ledger-gated state-changing transaction.
+ *
+ * ```text
+ * BEGIN IMMEDIATE
+ * before = snapshot()
+ * staged = mutate(before)            # no commit yet
+ * record = ledger event with before/after state hashes
+ * idempotency:
+ *   same key + same eventHash  -> rollback, no-op
+ *   same key + different hash   -> rollback, IDEMPOTENCY_CONFLICT
+ * appendRequiredEvent(record)        # durable JSONL append + fsync
+ *   fail -> rollback, LEDGER_APPEND_REQUIRED_FAILED
+ * mirrorEvent(record)                # same transaction
+ *   fail -> rollback, SQLITE_MIRROR_FAILED (ledger durable; replay repairs)
+ * commit(staged)
+ *   fail -> rollback, SQLITE_COMMIT_AFTER_LEDGER_FAILED (ledger durable)
+ * ```
+ *
+ * Any failure leaves the injected store unmutated (transaction rolled back);
+ * only the durable ledger append can survive, which recovery/replay reconciles.
+ */
+export function runLedgerGatedTransaction(deps, request) {
+    const hashState = deps.hashState ?? coordinatorStateHash;
+    const handle = deps.begin();
+    let settled = false;
+    const rollbackOnce = () => {
+        if (!settled) {
+            settled = true;
+            handle.rollback();
+        }
+    };
+    try {
+        const before = handle.snapshot();
+        const staged = request.mutate(before);
+        const record = buildLedgerRecord(request, hashState(before), hashState(staged));
+        const existing = handle.findByIdempotencyKey(request.idempotencyKey);
+        if (existing !== undefined) {
+            rollbackOnce();
+            if (existing.eventHash === record.eventHash) {
+                return { status: "noop", applied: false, record: existing, state: before };
+            }
+            throw new CoordinatorError("IDEMPOTENCY_CONFLICT", `idempotency key "${request.idempotencyKey}" already recorded with a different event hash`, errorContext(request, "operator"));
+        }
+        try {
+            handle.appendRequiredEvent(record);
+        }
+        catch (cause) {
+            rollbackOnce();
+            throw new RequiredAuditWriteError(`required ledger append failed for "${request.eventType}"`, errorContext(request, "rollback", cause));
+        }
+        try {
+            handle.mirrorEvent(record);
+        }
+        catch (cause) {
+            rollbackOnce();
+            throw new CoordinatorError("SQLITE_MIRROR_FAILED", `sqlite mirror failed after ledger append for "${request.eventType}"`, errorContext(request, "in_doubt", cause));
+        }
+        try {
+            handle.commit(staged);
+            settled = true;
+        }
+        catch (cause) {
+            rollbackOnce();
+            throw new CoordinatorError("SQLITE_COMMIT_AFTER_LEDGER_FAILED", `sqlite commit failed after ledger append for "${request.eventType}"`, errorContext(request, "in_doubt", cause));
+        }
+        return { status: "committed", applied: true, record, state: staged };
+    }
+    catch (error) {
+        rollbackOnce();
+        throw error;
+    }
+}
+/**
+ * Apply side-effecting steps in deterministic sequence order, recording a
+ * required receipt after each side effect.
+ *
+ * Fail-closed rule (algorithm-plan Phase 1, test 3): if a receipt append fails
+ * after its side effect ran, stop executing further side effects and return
+ * `in_doubt` — UNLESS a durable idempotent receipt for that step exists, in
+ * which case the side effect is provably recorded and execution continues.
+ *
+ * Steps whose receipt is already durably recorded are skipped (idempotent
+ * replay) and never re-run.
+ */
+export function applyReceiptedSteps(handle, request) {
+    const eventType = request.eventType ?? "scheduler.node.receipt";
+    const ordered = [...request.steps].sort((a, b) => a.sequence - b.sequence);
+    const executedStepIds = [];
+    const skippedStepIds = [];
+    const appliedReceipts = [];
+    for (const step of ordered) {
+        const pre = handle.findReceipt(step.receiptId);
+        if (pre !== undefined) {
+            // Receipt already durable: idempotent replay, do not re-run the side effect.
+            skippedStepIds.push(step.id);
+            appliedReceipts.push(pre);
+            continue;
+        }
+        step.run();
+        executedStepIds.push(step.id);
+        const record = buildLedgerRecord({
+            operationId: request.operationId,
+            runId: request.runId,
+            nodeId: request.nodeId,
+            eventType,
+            phase: "receipt",
+            idempotencyKey: step.receiptId,
+            attemptId: request.attemptId,
+        }, step.beforeStateHash, step.afterStateHash);
+        try {
+            handle.appendReceiptEvent(record);
+            appliedReceipts.push(record);
+        }
+        catch {
+            const post = handle.findReceipt(step.receiptId);
+            if (post !== undefined) {
+                // Receipt persisted despite the append error: recoverable, keep going.
+                appliedReceipts.push(post);
+                continue;
+            }
+            return {
+                status: "in_doubt",
+                executedStepIds,
+                skippedStepIds,
+                appliedReceipts,
+                stoppedAtStepId: step.id,
+                reason: `receipt append failed after side effect for step "${step.id}" with no durable receipt`,
+            };
+        }
+    }
+    return { status: "completed", executedStepIds, skippedStepIds, appliedReceipts };
+}
+/**
+ * Run compensation fail-closed (algorithm-plan Phase 1, test 4 + invariant I7).
+ *
+ * 1. Refuse to auto-compensate if any NON-idempotent step was already applied
+ *    (state is ambiguous): throw COMPENSATION_FAILED before anything runs.
+ * 2. The compensation start is itself ledger-gated: if its required event cannot
+ *    be appended, throw RequiredAuditWriteError and run NO compensators.
+ * 3. Only idempotent compensators run, in reverse execution order, each
+ *    recording a compensation receipt.
+ */
+export function runGatedCompensation(handle, request) {
+    const baseContext = {
+        runId: request.runId,
+        nodeId: request.nodeId,
+        operationId: request.operationId,
+        phase: "compensate",
+        eventType: "scheduler.node.compensating",
+        attemptId: request.attemptId,
+    };
+    for (const step of request.steps) {
+        if (!step.idempotent && step.applied) {
+            throw new CoordinatorError("COMPENSATION_FAILED", `cannot auto-compensate non-idempotent step "${step.id}" that was already applied`, { ...baseContext, recoverability: "in_doubt" });
+        }
+    }
+    const startRecord = buildLedgerRecord({
+        operationId: request.operationId,
+        runId: request.runId,
+        nodeId: request.nodeId,
+        eventType: "scheduler.node.compensating",
+        phase: "compensate",
+        idempotencyKey: request.idempotencyKey,
+        attemptId: request.attemptId,
+    }, request.beforeStateHash, request.afterStateHash);
+    try {
+        handle.appendCompensationStart(startRecord);
+    }
+    catch (cause) {
+        throw new RequiredAuditWriteError("required compensation-start ledger append failed", { ...baseContext, cause });
+    }
+    const reversed = request.steps.filter((step) => step.idempotent).sort((a, b) => b.sequence - a.sequence);
+    const executedStepIds = [];
+    const receipts = [];
+    for (const step of reversed) {
+        try {
+            step.run();
+        }
+        catch (cause) {
+            throw new CoordinatorError("COMPENSATION_FAILED", `compensator "${step.id}" failed`, {
+                ...baseContext,
+                recoverability: "in_doubt",
+                cause,
+            });
+        }
+        executedStepIds.push(step.id);
+        const receipt = buildLedgerRecord({
+            operationId: request.operationId,
+            runId: request.runId,
+            nodeId: request.nodeId,
+            eventType: "scheduler.node.compensation.receipt",
+            phase: "compensate",
+            idempotencyKey: `${request.idempotencyKey}:${step.id}`,
+            attemptId: request.attemptId,
+        }, request.beforeStateHash, request.afterStateHash);
+        handle.appendCompensationReceipt(receipt);
+        receipts.push(receipt);
+    }
+    return { status: "rolled_back", executedStepIds, receipts };
+}
+//# sourceMappingURL=transaction-coordinator.js.map

package/dist/core/orchestration/transaction-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-coordinator.js","sourceRoot":"","sources":["../../../src/core/orchestration/transaction-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Phase 1: fail-closed, ledger-gated transaction coordinator (pure algorithms).\n *\n * These functions are deterministic and side-effect free except through the\n * injected in-memory transaction/store callbacks. No SQLite or filesystem is\n * wired here; the real durable store is injected later. The invariant enforced\n * is: no state-changing mutation commits unless its required ledger event was\n * durably appended (JSONL fsync) and mirrored, in that order.\n *\n * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md\n * (Phase 1) and audit-transaction.md.\n */\n\nimport {\n\tCoordinatorError,\n\ttype CoordinatorRecoverability,\n\tRequiredAuditWriteError,\n\ttype TransactionPhase,\n} from \"./errors.ts\";\nimport { type JsonValue, sha256Hex, stableStringify } from \"./replay-ledger.ts\";\n\n/**\n * A canonical, content-addressed ledger event record. `eventHash` is derived\n * deterministically from the identity + state hashes, which is what makes\n * idempotency detection (same key + same hash => no-op) reliable.\n */\nexport interface LedgerRecord {\n\toperationId: string;\n\trunId: string;\n\tnodeId: string;\n\teventType: string;\n\tphase: TransactionPhase;\n\tidempotencyKey: string;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\teventHash: string;\n\tattemptId?: string;\n}\n\n/**\n * Identity + intent for a single ledger-gated mutation. `mutate` is pure: it\n * receives the snapshot and returns the staged next state without committing.\n */\nexport interface LedgerGatedTransactionRequest<S> {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\teventType: string;\n\tphase: TransactionPhase;\n\tidempotencyKey: string;\n\tmutate: (before: S) => S;\n\tattemptId?: string;\n}\n\n/**\n * Injected transaction handle (a single `BEGIN IMMEDIATE` scope). The fake used\n * in tests and the real SQLite-backed handle implement this surface.\n *\n * Contract:\n * - `appendRequiredEvent` simulates the durable JSONL append + fsync. It escapes\n *   transactional rollback (an appended event stays on disk).\n * - `mirrorEvent` stages the SQLite mirror insert inside the open transaction.\n * - `commit` applies the staged mirror + state; `rollback` discards them.\n */\nexport interface LedgerGatedTransactionHandle<S> {\n\tsnapshot: () => S;\n\tfindByIdempotencyKey: (key: string) => LedgerRecord | undefined;\n\tappendRequiredEvent: (record: LedgerRecord) => void;\n\tmirrorEvent: (record: LedgerRecord) => void;\n\tcommit: (state: S) => void;\n\trollback: () => void;\n}\n\nexport interface LedgerGatedTransactionDeps<S> {\n\tbegin: () => LedgerGatedTransactionHandle<S>;\n\thashState?: (state: S) => string;\n}\n\nexport type LedgerGatedTransactionStatus = \"committed\" | \"noop\";\n\nexport interface LedgerGatedTransactionResult<S> {\n\tstatus: LedgerGatedTransactionStatus;\n\tapplied: boolean;\n\trecord: LedgerRecord;\n\tstate: S;\n}\n\n/**\n * Default state hash. Callers with non-JSON state must inject `hashState`.\n */\nexport function coordinatorStateHash(state: unknown): string {\n\treturn sha256Hex(stableStringify(state as JsonValue));\n}\n\n/**\n * Deterministically derive a content hash for a ledger event from its identity\n * and state transition. Volatile fields are excluded so replays are stable.\n */\nexport function computeCoordinatorEventHash(input: {\n\toperationId: string;\n\trunId: string;\n\tnodeId: string;\n\teventType: string;\n\tphase: TransactionPhase;\n\tidempotencyKey: string;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\tattemptId?: string;\n}): string {\n\tconst canonical: { readonly [key: string]: JsonValue } = {\n\t\toperationId: input.operationId,\n\t\trunId: input.runId,\n\t\tnodeId: input.nodeId,\n\t\teventType: input.eventType,\n\t\tphase: input.phase,\n\t\tidempotencyKey: input.idempotencyKey,\n\t\tbeforeStateHash: input.beforeStateHash,\n\t\tafterStateHash: input.afterStateHash,\n\t\tattemptId: input.attemptId ?? null,\n\t};\n\treturn sha256Hex(stableStringify(canonical));\n}\n\n/**\n * Build a complete ledger record (including `eventHash`) from a request and the\n * computed before/after state hashes.\n */\nexport function buildLedgerRecord(\n\trequest: {\n\t\toperationId: string;\n\t\trunId: string;\n\t\tnodeId: string;\n\t\teventType: string;\n\t\tphase: TransactionPhase;\n\t\tidempotencyKey: string;\n\t\tattemptId?: string;\n\t},\n\tbeforeStateHash: string,\n\tafterStateHash: string,\n): LedgerRecord {\n\tconst eventHash = computeCoordinatorEventHash({\n\t\toperationId: request.operationId,\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\teventType: request.eventType,\n\t\tphase: request.phase,\n\t\tidempotencyKey: request.idempotencyKey,\n\t\tbeforeStateHash,\n\t\tafterStateHash,\n\t\tattemptId: request.attemptId,\n\t});\n\treturn {\n\t\toperationId: request.operationId,\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\teventType: request.eventType,\n\t\tphase: request.phase,\n\t\tidempotencyKey: request.idempotencyKey,\n\t\tbeforeStateHash,\n\t\tafterStateHash,\n\t\teventHash,\n\t\t...(request.attemptId === undefined ? {} : { attemptId: request.attemptId }),\n\t};\n}\n\nfunction errorContext(\n\trequest: {\n\t\trunId: string;\n\t\tnodeId: string;\n\t\toperationId: string;\n\t\tphase: TransactionPhase;\n\t\teventType: string;\n\t\tattemptId?: string;\n\t},\n\trecoverability: CoordinatorRecoverability,\n\tcause?: unknown,\n): {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tphase: TransactionPhase;\n\teventType: string;\n\trecoverability: CoordinatorRecoverability;\n\tattemptId?: string;\n\tcause?: unknown;\n} {\n\treturn {\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\toperationId: request.operationId,\n\t\tphase: request.phase,\n\t\teventType: request.eventType,\n\t\trecoverability,\n\t\tattemptId: request.attemptId,\n\t\tcause,\n\t};\n}\n\n/**\n * Run one fail-closed, ledger-gated state-changing transaction.\n *\n * ```text\n * BEGIN IMMEDIATE\n * before = snapshot()\n * staged = mutate(before)            # no commit yet\n * record = ledger event with before/after state hashes\n * idempotency:\n *   same key + same eventHash  -> rollback, no-op\n *   same key + different hash   -> rollback, IDEMPOTENCY_CONFLICT\n * appendRequiredEvent(record)        # durable JSONL append + fsync\n *   fail -> rollback, LEDGER_APPEND_REQUIRED_FAILED\n * mirrorEvent(record)                # same transaction\n *   fail -> rollback, SQLITE_MIRROR_FAILED (ledger durable; replay repairs)\n * commit(staged)\n *   fail -> rollback, SQLITE_COMMIT_AFTER_LEDGER_FAILED (ledger durable)\n * ```\n *\n * Any failure leaves the injected store unmutated (transaction rolled back);\n * only the durable ledger append can survive, which recovery/replay reconciles.\n */\nexport function runLedgerGatedTransaction<S>(\n\tdeps: LedgerGatedTransactionDeps<S>,\n\trequest: LedgerGatedTransactionRequest<S>,\n): LedgerGatedTransactionResult<S> {\n\tconst hashState = deps.hashState ?? coordinatorStateHash;\n\tconst handle = deps.begin();\n\tlet settled = false;\n\tconst rollbackOnce = (): void => {\n\t\tif (!settled) {\n\t\t\tsettled = true;\n\t\t\thandle.rollback();\n\t\t}\n\t};\n\n\ttry {\n\t\tconst before = handle.snapshot();\n\t\tconst staged = request.mutate(before);\n\t\tconst record = buildLedgerRecord(request, hashState(before), hashState(staged));\n\n\t\tconst existing = handle.findByIdempotencyKey(request.idempotencyKey);\n\t\tif (existing !== undefined) {\n\t\t\trollbackOnce();\n\t\t\tif (existing.eventHash === record.eventHash) {\n\t\t\t\treturn { status: \"noop\", applied: false, record: existing, state: before };\n\t\t\t}\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"IDEMPOTENCY_CONFLICT\",\n\t\t\t\t`idempotency key \"${request.idempotencyKey}\" already recorded with a different event hash`,\n\t\t\t\terrorContext(request, \"operator\"),\n\t\t\t);\n\t\t}\n\n\t\ttry {\n\t\t\thandle.appendRequiredEvent(record);\n\t\t} catch (cause) {\n\t\t\trollbackOnce();\n\t\t\tthrow new RequiredAuditWriteError(\n\t\t\t\t`required ledger append failed for \"${request.eventType}\"`,\n\t\t\t\terrorContext(request, \"rollback\", cause),\n\t\t\t);\n\t\t}\n\n\t\ttry {\n\t\t\thandle.mirrorEvent(record);\n\t\t} catch (cause) {\n\t\t\trollbackOnce();\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"SQLITE_MIRROR_FAILED\",\n\t\t\t\t`sqlite mirror failed after ledger append for \"${request.eventType}\"`,\n\t\t\t\terrorContext(request, \"in_doubt\", cause),\n\t\t\t);\n\t\t}\n\n\t\ttry {\n\t\t\thandle.commit(staged);\n\t\t\tsettled = true;\n\t\t} catch (cause) {\n\t\t\trollbackOnce();\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"SQLITE_COMMIT_AFTER_LEDGER_FAILED\",\n\t\t\t\t`sqlite commit failed after ledger append for \"${request.eventType}\"`,\n\t\t\t\terrorContext(request, \"in_doubt\", cause),\n\t\t\t);\n\t\t}\n\n\t\treturn { status: \"committed\", applied: true, record, state: staged };\n\t} catch (error) {\n\t\trollbackOnce();\n\t\tthrow error;\n\t}\n}\n\n/**\n * A single side-effecting step that must record a receipt after its side effect.\n * Each step declares a stable `receiptId` so a durable receipt can short-circuit\n * re-execution on replay.\n */\nexport interface ReceiptedStep {\n\tid: string;\n\treceiptId: string;\n\tsequence: number;\n\tidempotent: boolean;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\trun: () => void;\n}\n\nexport interface ReceiptHandle {\n\tfindReceipt: (receiptId: string) => LedgerRecord | undefined;\n\tappendReceiptEvent: (record: LedgerRecord) => void;\n}\n\nexport interface ReceiptApplyRequest {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tattemptId?: string;\n\teventType?: string;\n\tsteps: readonly ReceiptedStep[];\n}\n\nexport type ReceiptApplyStatus = \"completed\" | \"in_doubt\";\n\nexport interface ReceiptApplyResult {\n\tstatus: ReceiptApplyStatus;\n\texecutedStepIds: string[];\n\tskippedStepIds: string[];\n\tappliedReceipts: LedgerRecord[];\n\tstoppedAtStepId?: string;\n\treason?: string;\n}\n\n/**\n * Apply side-effecting steps in deterministic sequence order, recording a\n * required receipt after each side effect.\n *\n * Fail-closed rule (algorithm-plan Phase 1, test 3): if a receipt append fails\n * after its side effect ran, stop executing further side effects and return\n * `in_doubt` — UNLESS a durable idempotent receipt for that step exists, in\n * which case the side effect is provably recorded and execution continues.\n *\n * Steps whose receipt is already durably recorded are skipped (idempotent\n * replay) and never re-run.\n */\nexport function applyReceiptedSteps(handle: ReceiptHandle, request: ReceiptApplyRequest): ReceiptApplyResult {\n\tconst eventType = request.eventType ?? \"scheduler.node.receipt\";\n\tconst ordered = [...request.steps].sort((a, b) => a.sequence - b.sequence);\n\tconst executedStepIds: string[] = [];\n\tconst skippedStepIds: string[] = [];\n\tconst appliedReceipts: LedgerRecord[] = [];\n\n\tfor (const step of ordered) {\n\t\tconst pre = handle.findReceipt(step.receiptId);\n\t\tif (pre !== undefined) {\n\t\t\t// Receipt already durable: idempotent replay, do not re-run the side effect.\n\t\t\tskippedStepIds.push(step.id);\n\t\t\tappliedReceipts.push(pre);\n\t\t\tcontinue;\n\t\t}\n\n\t\tstep.run();\n\t\texecutedStepIds.push(step.id);\n\n\t\tconst record = buildLedgerRecord(\n\t\t\t{\n\t\t\t\toperationId: request.operationId,\n\t\t\t\trunId: request.runId,\n\t\t\t\tnodeId: request.nodeId,\n\t\t\t\teventType,\n\t\t\t\tphase: \"receipt\",\n\t\t\t\tidempotencyKey: step.receiptId,\n\t\t\t\tattemptId: request.attemptId,\n\t\t\t},\n\t\t\tstep.beforeStateHash,\n\t\t\tstep.afterStateHash,\n\t\t);\n\n\t\ttry {\n\t\t\thandle.appendReceiptEvent(record);\n\t\t\tappliedReceipts.push(record);\n\t\t} catch {\n\t\t\tconst post = handle.findReceipt(step.receiptId);\n\t\t\tif (post !== undefined) {\n\t\t\t\t// Receipt persisted despite the append error: recoverable, keep going.\n\t\t\t\tappliedReceipts.push(post);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstatus: \"in_doubt\",\n\t\t\t\texecutedStepIds,\n\t\t\t\tskippedStepIds,\n\t\t\t\tappliedReceipts,\n\t\t\t\tstoppedAtStepId: step.id,\n\t\t\t\treason: `receipt append failed after side effect for step \"${step.id}\" with no durable receipt`,\n\t\t\t};\n\t\t}\n\t}\n\n\treturn { status: \"completed\", executedStepIds, skippedStepIds, appliedReceipts };\n}\n\n/**\n * A registered compensator and its forward-execution status.\n */\nexport interface CompensatorExecutionStep {\n\tid: string;\n\tsequence: number;\n\tidempotent: boolean;\n\tapplied: boolean;\n\trun: () => void;\n}\n\nexport interface CompensationHandle {\n\tappendCompensationStart: (record: LedgerRecord) => void;\n\tappendCompensationReceipt: (record: LedgerRecord) => void;\n}\n\nexport interface GatedCompensationRequest {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tidempotencyKey: string;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\tattemptId?: string;\n\tsteps: readonly CompensatorExecutionStep[];\n}\n\nexport interface GatedCompensationResult {\n\tstatus: \"rolled_back\";\n\texecutedStepIds: string[];\n\treceipts: LedgerRecord[];\n}\n\n/**\n * Run compensation fail-closed (algorithm-plan Phase 1, test 4 + invariant I7).\n *\n * 1. Refuse to auto-compensate if any NON-idempotent step was already applied\n *    (state is ambiguous): throw COMPENSATION_FAILED before anything runs.\n * 2. The compensation start is itself ledger-gated: if its required event cannot\n *    be appended, throw RequiredAuditWriteError and run NO compensators.\n * 3. Only idempotent compensators run, in reverse execution order, each\n *    recording a compensation receipt.\n */\nexport function runGatedCompensation(\n\thandle: CompensationHandle,\n\trequest: GatedCompensationRequest,\n): GatedCompensationResult {\n\tconst baseContext = {\n\t\trunId: request.runId,\n\t\tnodeId: request.nodeId,\n\t\toperationId: request.operationId,\n\t\tphase: \"compensate\" as TransactionPhase,\n\t\teventType: \"scheduler.node.compensating\",\n\t\tattemptId: request.attemptId,\n\t};\n\n\tfor (const step of request.steps) {\n\t\tif (!step.idempotent && step.applied) {\n\t\t\tthrow new CoordinatorError(\n\t\t\t\t\"COMPENSATION_FAILED\",\n\t\t\t\t`cannot auto-compensate non-idempotent step \"${step.id}\" that was already applied`,\n\t\t\t\t{ ...baseContext, recoverability: \"in_doubt\" },\n\t\t\t);\n\t\t}\n\t}\n\n\tconst startRecord = buildLedgerRecord(\n\t\t{\n\t\t\toperationId: request.operationId,\n\t\t\trunId: request.runId,\n\t\t\tnodeId: request.nodeId,\n\t\t\teventType: \"scheduler.node.compensating\",\n\t\t\tphase: \"compensate\",\n\t\t\tidempotencyKey: request.idempotencyKey,\n\t\t\tattemptId: request.attemptId,\n\t\t},\n\t\trequest.beforeStateHash,\n\t\trequest.afterStateHash,\n\t);\n\n\ttry {\n\t\thandle.appendCompensationStart(startRecord);\n\t} catch (cause) {\n\t\tthrow new RequiredAuditWriteError(\"required compensation-start ledger append failed\", { ...baseContext, cause });\n\t}\n\n\tconst reversed = request.steps.filter((step) => step.idempotent).sort((a, b) => b.sequence - a.sequence);\n\tconst executedStepIds: string[] = [];\n\tconst receipts: LedgerRecord[] = [];\n\n\tfor (const step of reversed) {\n\t\ttry {\n\t\t\tstep.run();\n\t\t} catch (cause) {\n\t\t\tthrow new CoordinatorError(\"COMPENSATION_FAILED\", `compensator \"${step.id}\" failed`, {\n\t\t\t\t...baseContext,\n\t\t\t\trecoverability: \"in_doubt\",\n\t\t\t\tcause,\n\t\t\t});\n\t\t}\n\t\texecutedStepIds.push(step.id);\n\t\tconst receipt = buildLedgerRecord(\n\t\t\t{\n\t\t\t\toperationId: request.operationId,\n\t\t\t\trunId: request.runId,\n\t\t\t\tnodeId: request.nodeId,\n\t\t\t\teventType: \"scheduler.node.compensation.receipt\",\n\t\t\t\tphase: \"compensate\",\n\t\t\t\tidempotencyKey: `${request.idempotencyKey}:${step.id}`,\n\t\t\t\tattemptId: request.attemptId,\n\t\t\t},\n\t\t\trequest.beforeStateHash,\n\t\t\trequest.afterStateHash,\n\t\t);\n\t\thandle.appendCompensationReceipt(receipt);\n\t\treceipts.push(receipt);\n\t}\n\n\treturn { status: \"rolled_back\", executedStepIds, receipts };\n}\n"]}