open-multi-agent-kit 0.80.7 → 0.90.0

package/dist/core/orchestration/merge-queue.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"merge-queue.js","sourceRoot":"","sources":["../../../src/core/orchestration/merge-queue.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deterministic merge-queue pure algorithms for the OMK durable DAG scheduler.\n *\n * This module contains ONLY pure data transformations. It performs NO real git\n * execution and NO I/O. The durable SQLite scheduler (see foundation.md\n * `merge_queue` table) and the git worktree integration lane (see\n * worktree-merge.md) consume these helpers to decide ordering, promotion\n * gating, conflict recording, and orphan-worktree reclaim policy.\n *\n * Design contract (worktree-merge.md §3.1, §3.3, §4.2, §5):\n * - Merge is strictly serial: exactly one entry advances per selection.\n * - Selection order key is fully deterministic:\n *     priority ASC, dagDepth ASC, leaseFinishedAt ASC, queueId ASC.\n * - Verify gate: a merge_queue entry can only advance from `pending` once its\n *   owning node reached the completed state AND its VerificationContract passed.\n *   This module trusts `completedNodeIds` (the scheduler supplies the verified\n *   completed set); pure logic only enforces the membership check.\n * - Promotion gate: the canonical branch is promoted only when the entry is in\n *   `merging`, verification passed, the target branch is unchanged, and no\n *   conflict was detected.\n * - Worktree reclaim never removes outside `.omk/worktrees/`.\n */\n\nexport type MergeQueueStatus = \"pending\" | \"merging\" | \"merged\" | \"conflict\" | \"blocked\";\n\n/**\n * A single merge_queue row plus the ordering metadata derived from the owning\n * node and its lease. `leaseFinishedAt` mirrors the owning node's `finished_at`\n * (the moment its lease ended); it is `null` when the node has not finished.\n */\nexport interface MergeQueueEntry {\n\tqueueId: string;\n\trunId: string;\n\tnodeId: string;\n\tbranchName: string;\n\ttargetBranch: string;\n\tstatus: MergeQueueStatus;\n\tpriority: number;\n\tdagDepth: number;\n\tleaseFinishedAt: string | null;\n\tcreatedAt: string;\n}\n\n/**\n * Inputs to the canonical-branch promotion gate. The scheduler fills these from\n * the merge worktree preparation + re-verification step (worktree-merge.md §5).\n */\nexport interface MergePromotionDecision {\n\tqueueStatus: MergeQueueStatus;\n\tverificationPassed: boolean;\n\ttargetUnchanged: boolean;\n\tconflict: boolean;\n}\n\n/** One side of a path-level merge conflict (ours / theirs blob SHAs). */\nexport interface ConflictFile {\n\tpath: string;\n\tours: string;\n\ttheirs: string;\n}\n\n/** Deterministic conflict artifact persisted to the artifacts table. */\nexport interface ConflictArtifact {\n\ttype: \"merge-conflict\";\n\trunId: string;\n\tnodeId: string;\n\tbranch: string;\n\ttargetBranch: string;\n\tconflictedFiles: ConflictFile[];\n\tmergeBase: string;\n\tcreatedAt: string;\n}\n\n/** Caller-supplied raw conflict data; files may arrive in any order. */\nexport interface ConflictArtifactInput {\n\trunId: string;\n\tnodeId: string;\n\tbranch: string;\n\ttargetBranch: string;\n\tconflictedFiles: ConflictFile[];\n\tmergeBase: string;\n\tcreatedAt: string;\n}\n\n/** Worktree reclaim decision returned by {@link shouldReclaimWorktree}. */\nexport type WorktreeReclaimAction = \"preserve\" | \"remove\" | \"ignore\";\n\n/**\n * Choose exactly one pending merge_queue entry to advance next.\n *\n * Selection rules:\n *  1. Only `pending` entries are eligible.\n *  2. Verify gate: the owning node must be in `completedNodeIds` (the scheduler\n *     only adds nodes that reached `completed` AND passed VerificationContract).\n *  3. Among eligible entries, order by priority ASC, dagDepth ASC,\n *     leaseFinishedAt ASC (nulls last), queueId ASC. queueId is the unique\n *     final tie-break, so the result is fully deterministic.\n *\n * Returns `undefined` when no entry is eligible.\n */\nexport function selectNextMergeEntry(\n\tentries: readonly MergeQueueEntry[],\n\tcompletedNodeIds: ReadonlySet<string>,\n): MergeQueueEntry | undefined {\n\tconst eligible = entries.filter((entry) => entry.status === \"pending\" && completedNodeIds.has(entry.nodeId));\n\tif (eligible.length === 0) {\n\t\treturn undefined;\n\t}\n\tif (eligible.length === 1) {\n\t\treturn eligible[0];\n\t}\n\tconst ordered = [...eligible].sort(compareMergeEntryOrder);\n\treturn ordered[0];\n}\n\n/**\n * Promotion gate for the canonical (target) branch.\n *\n * Returns true only when every promotion precondition holds:\n * queue is `merging`, verification passed, the target branch is unchanged,\n * and no conflict was detected. Any failure leaves the target untouched.\n */\nexport function canPromoteMerge(decision: MergePromotionDecision): boolean {\n\treturn (\n\t\tdecision.queueStatus === \"merging\" &&\n\t\tdecision.verificationPassed === true &&\n\t\tdecision.targetUnchanged === true &&\n\t\tdecision.conflict === false\n\t);\n}\n\n/**\n * Build a deterministic conflict artifact. `conflictedFiles` are copied and\n * sorted by path (then ours, then theirs for total determinism); the input\n * array is never mutated.\n */\nexport function createConflictArtifact(input: ConflictArtifactInput): ConflictArtifact {\n\tconst conflictedFiles = [...input.conflictedFiles].sort(compareConflictFile);\n\treturn {\n\t\ttype: \"merge-conflict\",\n\t\trunId: input.runId,\n\t\tnodeId: input.nodeId,\n\t\tbranch: input.branch,\n\t\ttargetBranch: input.targetBranch,\n\t\tconflictedFiles,\n\t\tmergeBase: input.mergeBase,\n\t\tcreatedAt: input.createdAt,\n\t};\n}\n\n/**\n * Decide the reclaim fate of a worktree during startup recovery\n * (worktree-merge.md §2.3).\n *\n * - Outside `.omk/worktrees/`: always `ignore` (never remove user/foreign\n *   worktrees).\n * - Terminal node (completed/merged/failed/rolled_back/cancelled) under prefix:\n *   `remove` — the worktree is leftover and safe to clean up.\n * - Expired lease with a non-terminal node under prefix: `preserve` — orphan\n *   recovery keeps the worktree and requeues the node.\n * - Otherwise (active, healthy): `ignore`.\n */\nexport function shouldReclaimWorktree(\n\tnodeTerminal: boolean,\n\tleaseExpired: boolean,\n\tpathUnderOmkWorktrees: boolean,\n): WorktreeReclaimAction {\n\tif (!pathUnderOmkWorktrees) {\n\t\treturn \"ignore\";\n\t}\n\tif (nodeTerminal) {\n\t\treturn \"remove\";\n\t}\n\tif (leaseExpired) {\n\t\treturn \"preserve\";\n\t}\n\treturn \"ignore\";\n}\n\nfunction compareMergeEntryOrder(a: MergeQueueEntry, b: MergeQueueEntry): number {\n\tif (a.priority !== b.priority) {\n\t\treturn a.priority - b.priority;\n\t}\n\tif (a.dagDepth !== b.dagDepth) {\n\t\treturn a.dagDepth - b.dagDepth;\n\t}\n\tconst byTime = compareNullableTimestamp(a.leaseFinishedAt, b.leaseFinishedAt);\n\tif (byTime !== 0) {\n\t\treturn byTime;\n\t}\n\treturn compareString(a.queueId, b.queueId);\n}\n\nfunction compareConflictFile(a: ConflictFile, b: ConflictFile): number {\n\tconst byPath = compareString(a.path, b.path);\n\tif (byPath !== 0) {\n\t\treturn byPath;\n\t}\n\tconst byOurs = compareString(a.ours, b.ours);\n\tif (byOurs !== 0) {\n\t\treturn byOurs;\n\t}\n\treturn compareString(a.theirs, b.theirs);\n}\n\nfunction compareNullableTimestamp(a: string | null, b: string | null): number {\n\t// ISO-8601 strings sort lexicographically in chronological order; null\n\t// (node never finished) sorts after any real timestamp.\n\tif (a === null && b === null) {\n\t\treturn 0;\n\t}\n\tif (a === null) {\n\t\treturn 1;\n\t}\n\tif (b === null) {\n\t\treturn -1;\n\t}\n\treturn compareString(a, b);\n}\n\nfunction compareString(a: string, b: string): number {\n\tif (a < b) {\n\t\treturn -1;\n\t}\n\tif (a > b) {\n\t\treturn 1;\n\t}\n\treturn 0;\n}\n"]}

package/dist/core/orchestration/recovery.d.ts

@@ -1,106 +0,0 @@
-/**
- * Pure recovery + compensation algorithms for the durable orchestration layer.
- *
- * These functions classify the state of a partially-executed durable operation
- * (reconstructed from the ledger + scheduler store), plan idempotent
- * compensator execution in reverse order, and enforce fail-closed audit
- * semantics when the durable ledger cannot accept an event.
- *
- * Design principle: fail-closed. When the recorded state is ambiguous we
- * prefer "in_doubt" (human intervention) over an unsafe resume or rollback.
- *
- * Reference: .omk/runs/omk-orchestration-upgrade-plan/transaction-recovery.md
- */
-export type DurableStepStatus = "leased" | "prepared" | "started" | "applying" | "verifying" | "completed" | "rolled_back" | "in_doubt" | "failed" | "blocked";
-export type RecoveryAction = "resume" | "rollback" | "in_doubt" | "ignore";
-/**
- * Snapshot of what was durably recorded for a single operation, reconstructed
- * by replaying the harness-control ledger and reconciling with the scheduler
- * node/lease/attempt tables. The classifier is pure logic over this struct.
- */
-export interface PreparedOperationReceipt {
-    operationId: string;
-    /** Last durable step status observed in the ledger, or null if none. Informational. */
-    lastStatus: DurableStepStatus | null;
-    /** A "prepared" marker was durably recorded (S2). */
-    prepared: boolean;
-    /** A "started" marker was durably recorded (S3). */
-    started: boolean;
-    /** A terminal "completed" marker was durably recorded (S7). */
-    completed: boolean;
-    /** A compensator failure marker was recorded (compensation attempted and failed). */
-    compensatorFailure: boolean;
-    /** sha256 of the prepared state; required to resume or roll back deterministically. */
-    preparedStateHash: string | null;
-    /** Receipt ids the operation declares as required to resume safely. */
-    requiredReceipts: readonly string[];
-    /** Receipt ids actually present in the ledger (S5 step receipts). */
-    presentReceipts: readonly string[];
-    /** True when the lease expiration time is in the past at recovery time. */
-    leaseExpired: boolean;
-}
-/**
- * A single registered compensator and its execution status, as resolved from
- * the compensators table at recovery time.
- */
-export interface CompensatorStep {
-    id: string;
-    kind: string;
-    /** Forward execution sequence; higher means executed later. */
-    sequence: number;
-    /** Whether re-running the compensator is side-effect safe. */
-    idempotent: boolean;
-    /** Whether the forward step's side effect was already applied. */
-    applied: boolean;
-    /** sha256 of the prepared state the compensator restores from. */
-    preparedStateHash: string | null;
-}
-export interface CompensationPlan {
-    /** "rollback" runs the listed steps; "in_doubt" runs nothing and escalates. */
-    action: "rollback" | "in_doubt";
-    /** Idempotent steps in reverse execution order. Empty for in_doubt plans. */
-    steps: CompensatorStep[];
-    /** Human/machine-readable reason for the chosen action. */
-    reason: string;
-}
-/**
- * Coarse stage classification for fail-closed audit. State-changing stages
- * mutate durable node/lease/attempt/artifact state; read-only stages only
- * observe.
- */
-export type LedgerAuditStage = "prepare" | "apply" | "verify" | "read-only";
-export declare function isStateChangingStage(stage: LedgerAuditStage): boolean;
-/**
- * Fail-closed audit gate. A state-changing stage MUST abort (and propagate the
- * ledger error, rolling back any in-flight SQLite transaction) when the durable
- * ledger could not accept its event. Read-only stages tolerate a ledger
- * failure because their event is pure observability.
- */
-export declare function shouldAbortForLedgerFailure(stage: LedgerAuditStage, ledgerAppendOk: boolean): boolean;
-/**
- * Classify the recovery action for a partially-executed durable operation.
- *
- * Precedence (fail-closed overrides first):
- *  1. completed marker present        -> ignore   (definitive terminal success)
- *  2. compensator failure marker      -> in_doubt (state is untrustworthy)
- *  3. prepared but no preparedStateHash -> in_doubt (cannot verify state to resume/rollback)
- *  4. prepared + started + all required receipts -> resume (deterministic replay)
- *  5. prepared + not started          -> rollback (undo the prepared state)
- *  6. expired lease + no receipts     -> rollback (stale lease, nothing durable recorded)
- *  7. prepared + started, partial receipts, live lease -> in_doubt (ambiguous apply)
- *  8. otherwise (nothing durable, live lease) -> resume (clean re-dispatch)
- */
-export declare function classifyRecoveryAction(receipt: PreparedOperationReceipt): RecoveryAction;
-/**
- * Build a compensation plan from registered compensator steps.
- *
- * - If any NON-idempotent step was already applied, its side effect may or may
- *   not have completed, so we cannot safely compensate: return an in_doubt
- *   plan with no executable steps (escalate instead of auto-compensating).
- * - Otherwise, return only the idempotent steps in reverse execution order.
- *   Non-idempotent steps that were never applied are dropped.
- *
- * The input array is never mutated.
- */
-export declare function planCompensation(steps: readonly CompensatorStep[]): CompensationPlan;
-//# sourceMappingURL=recovery.d.ts.map

package/dist/core/orchestration/recovery.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,iBAAiB,GAC1B,QAAQ,GACR,UAAU,GACV,SAAS,GACT,UAAU,GACV,WAAW,GACX,WAAW,GACX,aAAa,GACb,UAAU,GACV,QAAQ,GACR,SAAS,CAAC;AAEb,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,kBAAkB,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uEAAuE;IACvE,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,qEAAqE;IACrE,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,UAAU,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAChC,+EAA+E;IAC/E,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;IAChC,6EAA6E;IAC7E,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AAI5E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAKrG;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,cAAc,CAuBxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,gBAAgB,CAkBpF","sourcesContent":["/**\n * Pure recovery + compensation algorithms for the durable orchestration layer.\n *\n * These functions classify the state of a partially-executed durable operation\n * (reconstructed from the ledger + scheduler store), plan idempotent\n * compensator execution in reverse order, and enforce fail-closed audit\n * semantics when the durable ledger cannot accept an event.\n *\n * Design principle: fail-closed. When the recorded state is ambiguous we\n * prefer \"in_doubt\" (human intervention) over an unsafe resume or rollback.\n *\n * Reference: .omk/runs/omk-orchestration-upgrade-plan/transaction-recovery.md\n */\n\nexport type DurableStepStatus =\n\t| \"leased\"\n\t| \"prepared\"\n\t| \"started\"\n\t| \"applying\"\n\t| \"verifying\"\n\t| \"completed\"\n\t| \"rolled_back\"\n\t| \"in_doubt\"\n\t| \"failed\"\n\t| \"blocked\";\n\nexport type RecoveryAction = \"resume\" | \"rollback\" | \"in_doubt\" | \"ignore\";\n\n/**\n * Snapshot of what was durably recorded for a single operation, reconstructed\n * by replaying the harness-control ledger and reconciling with the scheduler\n * node/lease/attempt tables. The classifier is pure logic over this struct.\n */\nexport interface PreparedOperationReceipt {\n\toperationId: string;\n\t/** Last durable step status observed in the ledger, or null if none. Informational. */\n\tlastStatus: DurableStepStatus | null;\n\t/** A \"prepared\" marker was durably recorded (S2). */\n\tprepared: boolean;\n\t/** A \"started\" marker was durably recorded (S3). */\n\tstarted: boolean;\n\t/** A terminal \"completed\" marker was durably recorded (S7). */\n\tcompleted: boolean;\n\t/** A compensator failure marker was recorded (compensation attempted and failed). */\n\tcompensatorFailure: boolean;\n\t/** sha256 of the prepared state; required to resume or roll back deterministically. */\n\tpreparedStateHash: string | null;\n\t/** Receipt ids the operation declares as required to resume safely. */\n\trequiredReceipts: readonly string[];\n\t/** Receipt ids actually present in the ledger (S5 step receipts). */\n\tpresentReceipts: readonly string[];\n\t/** True when the lease expiration time is in the past at recovery time. */\n\tleaseExpired: boolean;\n}\n\n/**\n * A single registered compensator and its execution status, as resolved from\n * the compensators table at recovery time.\n */\nexport interface CompensatorStep {\n\tid: string;\n\tkind: string;\n\t/** Forward execution sequence; higher means executed later. */\n\tsequence: number;\n\t/** Whether re-running the compensator is side-effect safe. */\n\tidempotent: boolean;\n\t/** Whether the forward step's side effect was already applied. */\n\tapplied: boolean;\n\t/** sha256 of the prepared state the compensator restores from. */\n\tpreparedStateHash: string | null;\n}\n\nexport interface CompensationPlan {\n\t/** \"rollback\" runs the listed steps; \"in_doubt\" runs nothing and escalates. */\n\taction: \"rollback\" | \"in_doubt\";\n\t/** Idempotent steps in reverse execution order. Empty for in_doubt plans. */\n\tsteps: CompensatorStep[];\n\t/** Human/machine-readable reason for the chosen action. */\n\treason: string;\n}\n\n/**\n * Coarse stage classification for fail-closed audit. State-changing stages\n * mutate durable node/lease/attempt/artifact state; read-only stages only\n * observe.\n */\nexport type LedgerAuditStage = \"prepare\" | \"apply\" | \"verify\" | \"read-only\";\n\nconst STATE_CHANGING_STAGES: ReadonlySet<LedgerAuditStage> = new Set<LedgerAuditStage>([\"prepare\", \"apply\", \"verify\"]);\n\nexport function isStateChangingStage(stage: LedgerAuditStage): boolean {\n\treturn STATE_CHANGING_STAGES.has(stage);\n}\n\n/**\n * Fail-closed audit gate. A state-changing stage MUST abort (and propagate the\n * ledger error, rolling back any in-flight SQLite transaction) when the durable\n * ledger could not accept its event. Read-only stages tolerate a ledger\n * failure because their event is pure observability.\n */\nexport function shouldAbortForLedgerFailure(stage: LedgerAuditStage, ledgerAppendOk: boolean): boolean {\n\tif (ledgerAppendOk) {\n\t\treturn false;\n\t}\n\treturn isStateChangingStage(stage);\n}\n\nfunction allRequiredReceiptsPresent(receipt: PreparedOperationReceipt): boolean {\n\tif (receipt.requiredReceipts.length === 0) {\n\t\treturn true;\n\t}\n\tconst present = new Set(receipt.presentReceipts);\n\tfor (const id of receipt.requiredReceipts) {\n\t\tif (!present.has(id)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\treturn true;\n}\n\nfunction hasAnyReceipt(receipt: PreparedOperationReceipt): boolean {\n\treturn receipt.presentReceipts.length > 0;\n}\n\n/**\n * Classify the recovery action for a partially-executed durable operation.\n *\n * Precedence (fail-closed overrides first):\n *  1. completed marker present        -> ignore   (definitive terminal success)\n *  2. compensator failure marker      -> in_doubt (state is untrustworthy)\n *  3. prepared but no preparedStateHash -> in_doubt (cannot verify state to resume/rollback)\n *  4. prepared + started + all required receipts -> resume (deterministic replay)\n *  5. prepared + not started          -> rollback (undo the prepared state)\n *  6. expired lease + no receipts     -> rollback (stale lease, nothing durable recorded)\n *  7. prepared + started, partial receipts, live lease -> in_doubt (ambiguous apply)\n *  8. otherwise (nothing durable, live lease) -> resume (clean re-dispatch)\n */\nexport function classifyRecoveryAction(receipt: PreparedOperationReceipt): RecoveryAction {\n\tif (receipt.completed) {\n\t\treturn \"ignore\";\n\t}\n\tif (receipt.compensatorFailure) {\n\t\treturn \"in_doubt\";\n\t}\n\tif (receipt.prepared && receipt.preparedStateHash === null) {\n\t\treturn \"in_doubt\";\n\t}\n\tif (receipt.prepared && receipt.started && allRequiredReceiptsPresent(receipt)) {\n\t\treturn \"resume\";\n\t}\n\tif (receipt.prepared && !receipt.started) {\n\t\treturn \"rollback\";\n\t}\n\tif (receipt.leaseExpired && !hasAnyReceipt(receipt)) {\n\t\treturn \"rollback\";\n\t}\n\tif (receipt.prepared && receipt.started) {\n\t\treturn \"in_doubt\";\n\t}\n\treturn \"resume\";\n}\n\n/**\n * Build a compensation plan from registered compensator steps.\n *\n * - If any NON-idempotent step was already applied, its side effect may or may\n *   not have completed, so we cannot safely compensate: return an in_doubt\n *   plan with no executable steps (escalate instead of auto-compensating).\n * - Otherwise, return only the idempotent steps in reverse execution order.\n *   Non-idempotent steps that were never applied are dropped.\n *\n * The input array is never mutated.\n */\nexport function planCompensation(steps: readonly CompensatorStep[]): CompensationPlan {\n\tfor (const s of steps) {\n\t\tif (!s.idempotent && s.applied) {\n\t\t\treturn {\n\t\t\t\taction: \"in_doubt\",\n\t\t\t\tsteps: [],\n\t\t\t\treason: `non-idempotent step \"${s.id}\" was already applied; state is ambiguous`,\n\t\t\t};\n\t\t}\n\t}\n\n\tconst reversed = steps.filter((s) => s.idempotent).sort((a, b) => b.sequence - a.sequence);\n\n\treturn {\n\t\taction: \"rollback\",\n\t\tsteps: reversed,\n\t\treason: \"compensate idempotent steps in reverse execution order\",\n\t};\n}\n"]}

package/dist/core/orchestration/recovery.js

@@ -1,110 +0,0 @@
-/**
- * Pure recovery + compensation algorithms for the durable orchestration layer.
- *
- * These functions classify the state of a partially-executed durable operation
- * (reconstructed from the ledger + scheduler store), plan idempotent
- * compensator execution in reverse order, and enforce fail-closed audit
- * semantics when the durable ledger cannot accept an event.
- *
- * Design principle: fail-closed. When the recorded state is ambiguous we
- * prefer "in_doubt" (human intervention) over an unsafe resume or rollback.
- *
- * Reference: .omk/runs/omk-orchestration-upgrade-plan/transaction-recovery.md
- */
-const STATE_CHANGING_STAGES = new Set(["prepare", "apply", "verify"]);
-export function isStateChangingStage(stage) {
-    return STATE_CHANGING_STAGES.has(stage);
-}
-/**
- * Fail-closed audit gate. A state-changing stage MUST abort (and propagate the
- * ledger error, rolling back any in-flight SQLite transaction) when the durable
- * ledger could not accept its event. Read-only stages tolerate a ledger
- * failure because their event is pure observability.
- */
-export function shouldAbortForLedgerFailure(stage, ledgerAppendOk) {
-    if (ledgerAppendOk) {
-        return false;
-    }
-    return isStateChangingStage(stage);
-}
-function allRequiredReceiptsPresent(receipt) {
-    if (receipt.requiredReceipts.length === 0) {
-        return true;
-    }
-    const present = new Set(receipt.presentReceipts);
-    for (const id of receipt.requiredReceipts) {
-        if (!present.has(id)) {
-            return false;
-        }
-    }
-    return true;
-}
-function hasAnyReceipt(receipt) {
-    return receipt.presentReceipts.length > 0;
-}
-/**
- * Classify the recovery action for a partially-executed durable operation.
- *
- * Precedence (fail-closed overrides first):
- *  1. completed marker present        -> ignore   (definitive terminal success)
- *  2. compensator failure marker      -> in_doubt (state is untrustworthy)
- *  3. prepared but no preparedStateHash -> in_doubt (cannot verify state to resume/rollback)
- *  4. prepared + started + all required receipts -> resume (deterministic replay)
- *  5. prepared + not started          -> rollback (undo the prepared state)
- *  6. expired lease + no receipts     -> rollback (stale lease, nothing durable recorded)
- *  7. prepared + started, partial receipts, live lease -> in_doubt (ambiguous apply)
- *  8. otherwise (nothing durable, live lease) -> resume (clean re-dispatch)
- */
-export function classifyRecoveryAction(receipt) {
-    if (receipt.completed) {
-        return "ignore";
-    }
-    if (receipt.compensatorFailure) {
-        return "in_doubt";
-    }
-    if (receipt.prepared && receipt.preparedStateHash === null) {
-        return "in_doubt";
-    }
-    if (receipt.prepared && receipt.started && allRequiredReceiptsPresent(receipt)) {
-        return "resume";
-    }
-    if (receipt.prepared && !receipt.started) {
-        return "rollback";
-    }
-    if (receipt.leaseExpired && !hasAnyReceipt(receipt)) {
-        return "rollback";
-    }
-    if (receipt.prepared && receipt.started) {
-        return "in_doubt";
-    }
-    return "resume";
-}
-/**
- * Build a compensation plan from registered compensator steps.
- *
- * - If any NON-idempotent step was already applied, its side effect may or may
- *   not have completed, so we cannot safely compensate: return an in_doubt
- *   plan with no executable steps (escalate instead of auto-compensating).
- * - Otherwise, return only the idempotent steps in reverse execution order.
- *   Non-idempotent steps that were never applied are dropped.
- *
- * The input array is never mutated.
- */
-export function planCompensation(steps) {
-    for (const s of steps) {
-        if (!s.idempotent && s.applied) {
-            return {
-                action: "in_doubt",
-                steps: [],
-                reason: `non-idempotent step "${s.id}" was already applied; state is ambiguous`,
-            };
-        }
-    }
-    const reversed = steps.filter((s) => s.idempotent).sort((a, b) => b.sequence - a.sequence);
-    return {
-        action: "rollback",
-        steps: reversed,
-        reason: "compensate idempotent steps in reverse execution order",
-    };
-}
-//# sourceMappingURL=recovery.js.map

package/dist/core/orchestration/recovery.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../../src/core/orchestration/recovery.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure recovery + compensation algorithms for the durable orchestration layer.\n *\n * These functions classify the state of a partially-executed durable operation\n * (reconstructed from the ledger + scheduler store), plan idempotent\n * compensator execution in reverse order, and enforce fail-closed audit\n * semantics when the durable ledger cannot accept an event.\n *\n * Design principle: fail-closed. When the recorded state is ambiguous we\n * prefer \"in_doubt\" (human intervention) over an unsafe resume or rollback.\n *\n * Reference: .omk/runs/omk-orchestration-upgrade-plan/transaction-recovery.md\n */\n\nexport type DurableStepStatus =\n\t| \"leased\"\n\t| \"prepared\"\n\t| \"started\"\n\t| \"applying\"\n\t| \"verifying\"\n\t| \"completed\"\n\t| \"rolled_back\"\n\t| \"in_doubt\"\n\t| \"failed\"\n\t| \"blocked\";\n\nexport type RecoveryAction = \"resume\" | \"rollback\" | \"in_doubt\" | \"ignore\";\n\n/**\n * Snapshot of what was durably recorded for a single operation, reconstructed\n * by replaying the harness-control ledger and reconciling with the scheduler\n * node/lease/attempt tables. The classifier is pure logic over this struct.\n */\nexport interface PreparedOperationReceipt {\n\toperationId: string;\n\t/** Last durable step status observed in the ledger, or null if none. Informational. */\n\tlastStatus: DurableStepStatus | null;\n\t/** A \"prepared\" marker was durably recorded (S2). */\n\tprepared: boolean;\n\t/** A \"started\" marker was durably recorded (S3). */\n\tstarted: boolean;\n\t/** A terminal \"completed\" marker was durably recorded (S7). */\n\tcompleted: boolean;\n\t/** A compensator failure marker was recorded (compensation attempted and failed). */\n\tcompensatorFailure: boolean;\n\t/** sha256 of the prepared state; required to resume or roll back deterministically. */\n\tpreparedStateHash: string | null;\n\t/** Receipt ids the operation declares as required to resume safely. */\n\trequiredReceipts: readonly string[];\n\t/** Receipt ids actually present in the ledger (S5 step receipts). */\n\tpresentReceipts: readonly string[];\n\t/** True when the lease expiration time is in the past at recovery time. */\n\tleaseExpired: boolean;\n}\n\n/**\n * A single registered compensator and its execution status, as resolved from\n * the compensators table at recovery time.\n */\nexport interface CompensatorStep {\n\tid: string;\n\tkind: string;\n\t/** Forward execution sequence; higher means executed later. */\n\tsequence: number;\n\t/** Whether re-running the compensator is side-effect safe. */\n\tidempotent: boolean;\n\t/** Whether the forward step's side effect was already applied. */\n\tapplied: boolean;\n\t/** sha256 of the prepared state the compensator restores from. */\n\tpreparedStateHash: string | null;\n}\n\nexport interface CompensationPlan {\n\t/** \"rollback\" runs the listed steps; \"in_doubt\" runs nothing and escalates. */\n\taction: \"rollback\" | \"in_doubt\";\n\t/** Idempotent steps in reverse execution order. Empty for in_doubt plans. */\n\tsteps: CompensatorStep[];\n\t/** Human/machine-readable reason for the chosen action. */\n\treason: string;\n}\n\n/**\n * Coarse stage classification for fail-closed audit. State-changing stages\n * mutate durable node/lease/attempt/artifact state; read-only stages only\n * observe.\n */\nexport type LedgerAuditStage = \"prepare\" | \"apply\" | \"verify\" | \"read-only\";\n\nconst STATE_CHANGING_STAGES: ReadonlySet<LedgerAuditStage> = new Set<LedgerAuditStage>([\"prepare\", \"apply\", \"verify\"]);\n\nexport function isStateChangingStage(stage: LedgerAuditStage): boolean {\n\treturn STATE_CHANGING_STAGES.has(stage);\n}\n\n/**\n * Fail-closed audit gate. A state-changing stage MUST abort (and propagate the\n * ledger error, rolling back any in-flight SQLite transaction) when the durable\n * ledger could not accept its event. Read-only stages tolerate a ledger\n * failure because their event is pure observability.\n */\nexport function shouldAbortForLedgerFailure(stage: LedgerAuditStage, ledgerAppendOk: boolean): boolean {\n\tif (ledgerAppendOk) {\n\t\treturn false;\n\t}\n\treturn isStateChangingStage(stage);\n}\n\nfunction allRequiredReceiptsPresent(receipt: PreparedOperationReceipt): boolean {\n\tif (receipt.requiredReceipts.length === 0) {\n\t\treturn true;\n\t}\n\tconst present = new Set(receipt.presentReceipts);\n\tfor (const id of receipt.requiredReceipts) {\n\t\tif (!present.has(id)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\treturn true;\n}\n\nfunction hasAnyReceipt(receipt: PreparedOperationReceipt): boolean {\n\treturn receipt.presentReceipts.length > 0;\n}\n\n/**\n * Classify the recovery action for a partially-executed durable operation.\n *\n * Precedence (fail-closed overrides first):\n *  1. completed marker present        -> ignore   (definitive terminal success)\n *  2. compensator failure marker      -> in_doubt (state is untrustworthy)\n *  3. prepared but no preparedStateHash -> in_doubt (cannot verify state to resume/rollback)\n *  4. prepared + started + all required receipts -> resume (deterministic replay)\n *  5. prepared + not started          -> rollback (undo the prepared state)\n *  6. expired lease + no receipts     -> rollback (stale lease, nothing durable recorded)\n *  7. prepared + started, partial receipts, live lease -> in_doubt (ambiguous apply)\n *  8. otherwise (nothing durable, live lease) -> resume (clean re-dispatch)\n */\nexport function classifyRecoveryAction(receipt: PreparedOperationReceipt): RecoveryAction {\n\tif (receipt.completed) {\n\t\treturn \"ignore\";\n\t}\n\tif (receipt.compensatorFailure) {\n\t\treturn \"in_doubt\";\n\t}\n\tif (receipt.prepared && receipt.preparedStateHash === null) {\n\t\treturn \"in_doubt\";\n\t}\n\tif (receipt.prepared && receipt.started && allRequiredReceiptsPresent(receipt)) {\n\t\treturn \"resume\";\n\t}\n\tif (receipt.prepared && !receipt.started) {\n\t\treturn \"rollback\";\n\t}\n\tif (receipt.leaseExpired && !hasAnyReceipt(receipt)) {\n\t\treturn \"rollback\";\n\t}\n\tif (receipt.prepared && receipt.started) {\n\t\treturn \"in_doubt\";\n\t}\n\treturn \"resume\";\n}\n\n/**\n * Build a compensation plan from registered compensator steps.\n *\n * - If any NON-idempotent step was already applied, its side effect may or may\n *   not have completed, so we cannot safely compensate: return an in_doubt\n *   plan with no executable steps (escalate instead of auto-compensating).\n * - Otherwise, return only the idempotent steps in reverse execution order.\n *   Non-idempotent steps that were never applied are dropped.\n *\n * The input array is never mutated.\n */\nexport function planCompensation(steps: readonly CompensatorStep[]): CompensationPlan {\n\tfor (const s of steps) {\n\t\tif (!s.idempotent && s.applied) {\n\t\t\treturn {\n\t\t\t\taction: \"in_doubt\",\n\t\t\t\tsteps: [],\n\t\t\t\treason: `non-idempotent step \"${s.id}\" was already applied; state is ambiguous`,\n\t\t\t};\n\t\t}\n\t}\n\n\tconst reversed = steps.filter((s) => s.idempotent).sort((a, b) => b.sequence - a.sequence);\n\n\treturn {\n\t\taction: \"rollback\",\n\t\tsteps: reversed,\n\t\treason: \"compensate idempotent steps in reverse execution order\",\n\t};\n}\n"]}

package/dist/core/orchestration/replay-ledger.d.ts

@@ -1,76 +0,0 @@
-export type JsonPrimitive = string | number | boolean | null;
-export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
-    readonly [key: string]: JsonValue;
-};
-export interface ReplayLedgerEventInput {
-    sequence: number;
-    type: string;
-    reducerVersion: number;
-    payload: JsonValue;
-    beforeStateHash: string;
-    afterStateHash: string;
-    prevEventHash: string | null;
-}
-export interface ReplayLedgerEvent extends ReplayLedgerEventInput {
-    eventHash: string;
-}
-export interface ReplayLedgerVerificationResult {
-    ok: boolean;
-    error?: string;
-}
-export interface ArtifactReference {
-    path: string;
-    repoRoot: string;
-    sha256: string;
-}
-export interface ResolvedArtifactReference {
-    realPath: string;
-    isFile: boolean;
-    sha256: string;
-}
-export type ArtifactReferenceResolver = (path: string) => ResolvedArtifactReference | undefined;
-export declare function stableStringify(value: JsonValue): string;
-export declare function sha256Hex(input: string): string;
-export declare function computeEventHash(event: ReplayLedgerEventInput): string;
-export declare function verifyReplayLedger(events: readonly ReplayLedgerEvent[]): ReplayLedgerVerificationResult;
-export declare function verifyArtifactReference(ref: ArtifactReference, resolver: ArtifactReferenceResolver): ReplayLedgerVerificationResult;
-export interface ReplayLedgerPersistOptions {
-    ledgerPath: string;
-    lockTimeoutMs?: number;
-    maxLedgerBytes?: number;
-}
-export interface ReplayLedgerWriteResult {
-    ok: boolean;
-    path?: string;
-    event?: ReplayLedgerEvent;
-    error?: string;
-}
-export interface ReplayLedgerQuarantineEntry {
-    lineNumber: number;
-    reason: string;
-}
-export interface ReplayLedgerFileVerificationResult {
-    ok: boolean;
-    events: ReplayLedgerEvent[];
-    errors: string[];
-    quarantinedLines: ReplayLedgerQuarantineEntry[];
-}
-/**
- * Persists a replay ledger event to disk with durable write (fsync),
- * directory permissions 0o700, and file permissions 0o600. Uses advisory
- * locking to serialize concurrent appends.
- */
-export declare function recordReplayLedgerEvent(event: ReplayLedgerEvent, options: ReplayLedgerPersistOptions): ReplayLedgerWriteResult;
-/**
- * Reads a replay ledger file and verifies every record against:
- * - Valid JSON (malformed lines are quarantined)
- * - Required fields present and well-formed (truncated records quarantined)
- * - Full hash-chain integrity (tampered records quarantined)
- *
- * Quarantined records are skipped so replay consumers only receive the
- * deterministic verified prefix/chain. Any quarantine still makes ok=false.
- */
-export declare function verifyReplayLedgerFromFile(ledgerPath: string): ReplayLedgerFileVerificationResult;
-export declare function canonicalizeBaseDir(baseDir: string): string;
-export declare function createFsArtifactResolver(baseDir: string): ArtifactReferenceResolver;
-//# sourceMappingURL=replay-ledger.d.ts.map

package/dist/core/orchestration/replay-ledger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"replay-ledger.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/replay-ledger.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,SAAS,EAAE,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAErG,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAChE,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,8BAA8B;IAC9C,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,yBAAyB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,yBAAyB,GAAG,SAAS,CAAC;AAEhG,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAiCxD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAEtE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,GAAG,8BAA8B,CAyBvG;AAED,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,yBAAyB,GACjC,8BAA8B,CAehC;AAQD,MAAM,WAAW,0BAA0B;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,2BAA2B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kCAAkC;IAClD,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB,EAAE,2BAA2B,EAAE,CAAC;CAChD;AAuED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,0BAA0B,GACjC,uBAAuB,CAwDzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,kCAAkC,CAsGjG;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM3D;AAKD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,yBAAyB,CAsBnF","sourcesContent":["import { createHash } from \"node:crypto\";\nimport {\n\tchmodSync,\n\tcloseSync,\n\texistsSync,\n\tfsyncSync,\n\tlstatSync,\n\tmkdirSync,\n\topenSync,\n\treadFileSync,\n\trealpathSync,\n\trenameSync,\n\trmSync,\n\tstatSync,\n\twriteSync,\n} from \"node:fs\";\nimport path, { dirname } from \"node:path\";\n\nexport type JsonPrimitive = string | number | boolean | null;\nexport type JsonValue = JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };\n\nexport interface ReplayLedgerEventInput {\n\tsequence: number;\n\ttype: string;\n\treducerVersion: number;\n\tpayload: JsonValue;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\tprevEventHash: string | null;\n}\n\nexport interface ReplayLedgerEvent extends ReplayLedgerEventInput {\n\teventHash: string;\n}\n\nexport interface ReplayLedgerVerificationResult {\n\tok: boolean;\n\terror?: string;\n}\n\nexport interface ArtifactReference {\n\tpath: string;\n\trepoRoot: string;\n\tsha256: string;\n}\n\nexport interface ResolvedArtifactReference {\n\trealPath: string;\n\tisFile: boolean;\n\tsha256: string;\n}\n\nexport type ArtifactReferenceResolver = (path: string) => ResolvedArtifactReference | undefined;\n\nexport function stableStringify(value: JsonValue): string {\n\tif (value === null) {\n\t\treturn \"null\";\n\t}\n\tif (typeof value === \"string\") {\n\t\treturn JSON.stringify(value);\n\t}\n\tif (typeof value === \"number\") {\n\t\tif (!Number.isFinite(value)) {\n\t\t\tthrow new Error(\"Cannot stableStringify non-finite number\");\n\t\t}\n\t\treturn JSON.stringify(value);\n\t}\n\tif (typeof value === \"boolean\") {\n\t\treturn value ? \"true\" : \"false\";\n\t}\n\tif (Array.isArray(value)) {\n\t\treturn `[${value.map((item) => stableStringify(item)).join(\",\")}]`;\n\t}\n\tif (!isPlainObject(value)) {\n\t\tthrow new Error(\"Cannot stableStringify unsupported object\");\n\t}\n\n\tconst record = value as { readonly [key: string]: JsonValue | undefined };\n\tconst parts: string[] = [];\n\tfor (const key of Object.keys(record).sort()) {\n\t\tconst entryValue = record[key];\n\t\tif (entryValue === undefined) {\n\t\t\tthrow new Error(`Cannot stableStringify undefined value at key ${key}`);\n\t\t}\n\t\tparts.push(`${JSON.stringify(key)}:${stableStringify(entryValue)}`);\n\t}\n\treturn `{${parts.join(\",\")}}`;\n}\n\nexport function sha256Hex(input: string): string {\n\treturn createHash(\"sha256\").update(input).digest(\"hex\");\n}\n\nexport function computeEventHash(event: ReplayLedgerEventInput): string {\n\treturn sha256Hex(stableStringify(eventToJson(event)));\n}\n\nexport function verifyReplayLedger(events: readonly ReplayLedgerEvent[]): ReplayLedgerVerificationResult {\n\tlet previous: ReplayLedgerEvent | undefined;\n\tfor (let index = 0; index < events.length; index += 1) {\n\t\tconst current = events[index];\n\t\tif (current.sequence !== index + 1) {\n\t\t\treturn { ok: false, error: `sequence mismatch at index ${index}: expected ${index + 1}` };\n\t\t}\n\n\t\tconst expectedHash = computeEventHash(stripEventHash(current));\n\t\tif (current.eventHash !== expectedHash) {\n\t\t\treturn { ok: false, error: `eventHash mismatch at sequence ${current.sequence}` };\n\t\t}\n\n\t\tconst expectedPrevHash = previous?.eventHash ?? null;\n\t\tif (current.prevEventHash !== expectedPrevHash) {\n\t\t\treturn { ok: false, error: `prevEventHash mismatch at sequence ${current.sequence}` };\n\t\t}\n\n\t\tif (previous !== undefined && current.beforeStateHash !== previous.afterStateHash) {\n\t\t\treturn { ok: false, error: `beforeStateHash mismatch at sequence ${current.sequence}` };\n\t\t}\n\n\t\tprevious = current;\n\t}\n\treturn { ok: true };\n}\n\nexport function verifyArtifactReference(\n\tref: ArtifactReference,\n\tresolver: ArtifactReferenceResolver,\n): ReplayLedgerVerificationResult {\n\tconst resolved = resolver(ref.path);\n\tif (resolved === undefined) {\n\t\treturn { ok: false, error: `artifact not found: ${ref.path}` };\n\t}\n\tif (!resolved.isFile) {\n\t\treturn { ok: false, error: `artifact is not a file: ${ref.path}` };\n\t}\n\tif (!pathIsInside(ref.repoRoot, resolved.realPath)) {\n\t\treturn { ok: false, error: `artifact resolved outside repo root: ${resolved.realPath}` };\n\t}\n\tif (resolved.sha256 !== ref.sha256) {\n\t\treturn { ok: false, error: `artifact sha256 mismatch for ${ref.path}` };\n\t}\n\treturn { ok: true };\n}\n\n// Canonicalize a base directory through realpath so symlinked roots (for example\n// macOS /tmp -> /private/tmp) compare consistently against realpath'd artifacts.\n// ── Persistence ────────────────────────────────────────────────────────────\n\nconst LOCK_STALE_MS = 30000;\n\nexport interface ReplayLedgerPersistOptions {\n\tledgerPath: string;\n\tlockTimeoutMs?: number;\n\tmaxLedgerBytes?: number;\n}\n\nexport interface ReplayLedgerWriteResult {\n\tok: boolean;\n\tpath?: string;\n\tevent?: ReplayLedgerEvent;\n\terror?: string;\n}\n\nexport interface ReplayLedgerQuarantineEntry {\n\tlineNumber: number;\n\treason: string;\n}\n\nexport interface ReplayLedgerFileVerificationResult {\n\tok: boolean;\n\tevents: ReplayLedgerEvent[];\n\terrors: string[];\n\tquarantinedLines: ReplayLedgerQuarantineEntry[];\n}\n\n/**\n * Acquires an exclusive lock for the ledger file using O_CREAT|O_EXCL.\n * Stale locks (older than LOCK_STALE_MS) are removed before retry.\n */\nfunction acquireLock(lockPath: string, timeoutMs: number): number {\n\tconst start = Date.now();\n\twhile (true) {\n\t\ttry {\n\t\t\treturn openSync(lockPath, \"wx\", 0o600);\n\t\t} catch (error) {\n\t\t\tif (existsSync(lockPath)) {\n\t\t\t\ttry {\n\t\t\t\t\tconst stats = statSync(lockPath);\n\t\t\t\t\tif (Date.now() - stats.mtimeMs > LOCK_STALE_MS) rmSync(lockPath, { force: true });\n\t\t\t\t} catch {\n\t\t\t\t\t/* stale check best-effort */\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (Date.now() - start >= timeoutMs) {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t}\n}\n\n/**\n * Appends a JSON line to the ledger file and fsyncs both the file and its\n * parent directory so the write is durable on crash.\n *\n * Platform fallback: some filesystems (e.g. tmpfs, NFS) do not support\n * directory fsync. In those cases the directory fsync is best-effort; the\n * file fsync remains mandatory.\n */\nfunction fsyncDirectory(dirPath: string): void {\n\ttry {\n\t\tconst dirFd = openSync(dirPath, \"r\");\n\t\ttry {\n\t\t\tfsyncSync(dirFd);\n\t\t} finally {\n\t\t\tcloseSync(dirFd);\n\t\t}\n\t} catch {\n\t\t// Directory fsync is not supported on all platforms/filesystems.\n\t\t// File fsync remains the mandatory durability guarantee.\n\t}\n}\n\nfunction enforcePrivateFilePermissions(filePath: string): void {\n\ttry {\n\t\tif (existsSync(filePath) && (statSync(filePath).mode & 0o777) !== 0o600) {\n\t\t\tchmodSync(filePath, 0o600);\n\t\t}\n\t} catch {\n\t\t/* best-effort permission enforcement */\n\t}\n}\n\nfunction appendJsonLineWithFsync(ledgerPath: string, line: string): void {\n\tconst fd = openSync(ledgerPath, \"a\", 0o600);\n\ttry {\n\t\tenforcePrivateFilePermissions(ledgerPath);\n\t\twriteSync(fd, `${line}\\n`, undefined, \"utf-8\");\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\tfsyncDirectory(dirname(ledgerPath));\n}\n\n/**\n * Persists a replay ledger event to disk with durable write (fsync),\n * directory permissions 0o700, and file permissions 0o600. Uses advisory\n * locking to serialize concurrent appends.\n */\nexport function recordReplayLedgerEvent(\n\tevent: ReplayLedgerEvent,\n\toptions: ReplayLedgerPersistOptions,\n): ReplayLedgerWriteResult {\n\tconst { ledgerPath } = options;\n\tconst lockPath = `${ledgerPath}.lock`;\n\tlet lockFd: number | undefined;\n\ttry {\n\t\t// Create the ledger directory with owner-only permissions.\n\t\t// mode is applied to the deepest directory; recursive parents use umask-adjusted defaults.\n\t\tmkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });\n\n\t\t// On platforms where mkdirSync with mode over umask can produce\n\t\t// group/world-readable directories, re-apply the mode explicitly.\n\t\ttry {\n\t\t\tconst dirStats = statSync(dirname(ledgerPath));\n\t\t\tif ((dirStats.mode & 0o777) !== 0o700) {\n\t\t\t\tchmodSync(dirname(ledgerPath), 0o700);\n\t\t\t}\n\t\t} catch {\n\t\t\t/* best-effort permission enforcement */\n\t\t}\n\n\t\tlockFd = acquireLock(lockPath, options.lockTimeoutMs ?? 1000);\n\n\t\t// Rotate if the ledger exceeds the size threshold.\n\t\tif (Number.isFinite(options.maxLedgerBytes) && (options.maxLedgerBytes ?? 0) > 0 && existsSync(ledgerPath)) {\n\t\t\tenforcePrivateFilePermissions(ledgerPath);\n\t\t\tconst stats = statSync(ledgerPath);\n\t\t\tif (stats.size >= Math.floor(options.maxLedgerBytes!)) {\n\t\t\t\t// Simple rotation: rename current to .rotated, start fresh.\n\t\t\t\t// The new ledger will start from genesis since we don't carry\n\t\t\t\t// forward the previous hash chain across rotations for the\n\t\t\t\t// orchestration replay ledger (unlike harness-control which uses anchors).\n\t\t\t\tconst rotatedPath = `${ledgerPath}.${new Date().toISOString().replace(/[:.]/g, \"-\")}.rotated`;\n\t\t\t\trenameSync(ledgerPath, rotatedPath);\n\t\t\t\tenforcePrivateFilePermissions(rotatedPath);\n\t\t\t\tfsyncDirectory(dirname(ledgerPath));\n\t\t\t}\n\t\t}\n\n\t\tappendJsonLineWithFsync(ledgerPath, JSON.stringify(event));\n\t\treturn { ok: true, path: ledgerPath, event };\n\t} catch (error) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tpath: ledgerPath,\n\t\t\terror: error instanceof Error ? error.message : String(error),\n\t\t};\n\t} finally {\n\t\tif (lockFd !== undefined) {\n\t\t\ttry {\n\t\t\t\tcloseSync(lockFd);\n\t\t\t} catch {\n\t\t\t\t/* fd may already be closed */\n\t\t\t}\n\t\t\trmSync(lockPath, { force: true });\n\t\t}\n\t}\n}\n\n/**\n * Reads a replay ledger file and verifies every record against:\n * - Valid JSON (malformed lines are quarantined)\n * - Required fields present and well-formed (truncated records quarantined)\n * - Full hash-chain integrity (tampered records quarantined)\n *\n * Quarantined records are skipped so replay consumers only receive the\n * deterministic verified prefix/chain. Any quarantine still makes ok=false.\n */\nexport function verifyReplayLedgerFromFile(ledgerPath: string): ReplayLedgerFileVerificationResult {\n\tconst errors: string[] = [];\n\tconst events: ReplayLedgerEvent[] = [];\n\tconst quarantinedLines: ReplayLedgerQuarantineEntry[] = [];\n\n\tif (!existsSync(ledgerPath)) return { ok: true, events, errors, quarantinedLines };\n\n\tconst content = readFileSync(ledgerPath, \"utf-8\");\n\tconst lines = content\n\t\t.split(\"\\n\")\n\t\t.map((line) => line.trim())\n\t\t.filter((line) => line.length > 0);\n\n\tfunction quarantine(lineNumber: number, reason: string): void {\n\t\tquarantinedLines.push({ lineNumber, reason });\n\t\terrors.push(`line ${lineNumber}: quarantined — ${reason}`);\n\t}\n\n\tfor (let index = 0; index < lines.length; index++) {\n\t\tconst lineNumber = index + 1;\n\t\tlet parsed: Record<string, unknown>;\n\t\ttry {\n\t\t\tparsed = JSON.parse(lines[index]!);\n\t\t} catch (jsonError) {\n\t\t\tquarantine(\n\t\t\t\tlineNumber,\n\t\t\t\t`malformed JSON — ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`,\n\t\t\t);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst requiredFields = [\n\t\t\t\"sequence\",\n\t\t\t\"type\",\n\t\t\t\"reducerVersion\",\n\t\t\t\"payload\",\n\t\t\t\"beforeStateHash\",\n\t\t\t\"afterStateHash\",\n\t\t\t\"prevEventHash\",\n\t\t\t\"eventHash\",\n\t\t] as const;\n\t\tconst missingFields = requiredFields.filter((field) => !(field in parsed));\n\t\tif (missingFields.length > 0) {\n\t\t\tquarantine(lineNumber, `truncated or incomplete record — missing fields: ${missingFields.join(\", \")}`);\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (typeof parsed.sequence !== \"number\" || !Number.isInteger(parsed.sequence) || parsed.sequence < 1) {\n\t\t\tquarantine(lineNumber, \"invalid sequence\");\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof parsed.eventHash !== \"string\" || !/^[a-f0-9]{64}$/.test(parsed.eventHash)) {\n\t\t\tquarantine(lineNumber, \"invalid eventHash\");\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof parsed.prevEventHash !== \"string\" && parsed.prevEventHash !== null) {\n\t\t\tquarantine(lineNumber, \"invalid prevEventHash\");\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof parsed.beforeStateHash !== \"string\") {\n\t\t\tquarantine(lineNumber, \"invalid beforeStateHash\");\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof parsed.afterStateHash !== \"string\") {\n\t\t\tquarantine(lineNumber, \"invalid afterStateHash\");\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof parsed.type !== \"string\") {\n\t\t\tquarantine(lineNumber, \"invalid type\");\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof parsed.reducerVersion !== \"number\" || !Number.isInteger(parsed.reducerVersion)) {\n\t\t\tquarantine(lineNumber, \"invalid reducerVersion\");\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst event = parsed as unknown as ReplayLedgerEvent;\n\t\tconst expectedSequence = events.length + 1;\n\t\tif (event.sequence !== expectedSequence) {\n\t\t\tquarantine(lineNumber, `sequence mismatch: expected ${expectedSequence}, got ${event.sequence}`);\n\t\t\tcontinue;\n\t\t}\n\t\tconst expectedHash = computeEventHash(stripEventHash(event));\n\t\tif (event.eventHash !== expectedHash) {\n\t\t\tquarantine(lineNumber, `eventHash mismatch at sequence ${event.sequence}`);\n\t\t\tcontinue;\n\t\t}\n\t\tconst previous = events.at(-1);\n\t\tconst expectedPrevHash = previous?.eventHash ?? null;\n\t\tif (event.prevEventHash !== expectedPrevHash) {\n\t\t\tquarantine(lineNumber, `prevEventHash mismatch at sequence ${event.sequence}`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (previous !== undefined && event.beforeStateHash !== previous.afterStateHash) {\n\t\t\tquarantine(lineNumber, `beforeStateHash mismatch at sequence ${event.sequence}`);\n\t\t\tcontinue;\n\t\t}\n\n\t\tevents.push(event);\n\t}\n\n\treturn { ok: errors.length === 0, events, errors, quarantinedLines };\n}\n\nexport function canonicalizeBaseDir(baseDir: string): string {\n\ttry {\n\t\treturn realpathSync(baseDir);\n\t} catch {\n\t\treturn path.resolve(baseDir);\n\t}\n}\n\n// Filesystem-backed resolver that follows symlinks via realpath and uses lstat to\n// detect existence without following. Symlink escapes are caught downstream by\n// verifyArtifactReference's realpath containment check.\nexport function createFsArtifactResolver(baseDir: string): ArtifactReferenceResolver {\n\treturn (artifactPath) => {\n\t\tconst resolved = path.resolve(baseDir, artifactPath);\n\t\ttry {\n\t\t\tlstatSync(resolved);\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t\tlet realPath: string;\n\t\ttry {\n\t\t\trealPath = realpathSync(resolved);\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t\tlet isFile = false;\n\t\ttry {\n\t\t\tisFile = statSync(realPath).isFile();\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn { realPath, isFile, sha256: isFile ? sha256File(realPath) : \"\" };\n\t};\n}\n\nfunction sha256File(filePath: string): string {\n\treturn createHash(\"sha256\").update(readFileSync(filePath)).digest(\"hex\");\n}\n\nfunction isPlainObject(value: object): boolean {\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nfunction stripEventHash(event: ReplayLedgerEvent): ReplayLedgerEventInput {\n\treturn {\n\t\tsequence: event.sequence,\n\t\ttype: event.type,\n\t\treducerVersion: event.reducerVersion,\n\t\tpayload: event.payload,\n\t\tbeforeStateHash: event.beforeStateHash,\n\t\tafterStateHash: event.afterStateHash,\n\t\tprevEventHash: event.prevEventHash,\n\t};\n}\n\nfunction eventToJson(event: ReplayLedgerEventInput): { readonly [key: string]: JsonValue } {\n\treturn {\n\t\tsequence: event.sequence,\n\t\ttype: event.type,\n\t\treducerVersion: event.reducerVersion,\n\t\tpayload: event.payload,\n\t\tbeforeStateHash: event.beforeStateHash,\n\t\tafterStateHash: event.afterStateHash,\n\t\tprevEventHash: event.prevEventHash,\n\t};\n}\n\nfunction normalizePath(value: string): string {\n\treturn path.resolve(value).replace(/\\\\/g, \"/\").replace(/\\/$/, \"\");\n}\n\nfunction pathIsInside(root: string, candidate: string): boolean {\n\tconst normalizedRoot = normalizePath(root);\n\tconst normalizedCandidate = normalizePath(candidate);\n\treturn normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}/`);\n}\n"]}