open-multi-agent-kit 0.80.6 → 0.80.7

package/dist/core/orchestration/checkpoint.js

@@ -0,0 +1,152 @@
+export const CHECKPOINT_SCHEMA_VERSION = "omk.checkpoint.v1";
+export function renderCheckpointMarkdown(checkpoint) {
+    const lines = [
+        `# OMK Checkpoint ${checkpoint.checkpointId}`,
+        `Run: ${checkpoint.runId}`,
+        `Timestamp: ${checkpoint.timestamp}`,
+        `Goal: ${checkpoint.currentGoal.summary} (${checkpoint.currentGoal.status})`,
+        "",
+        "## Constraints",
+        ...formatBullets(checkpoint.constraints),
+        "",
+        "## Decisions",
+        ...checkpoint.decisions.map((decision) => `- ${decision.id}: ${decision.summary} [hashes: ${decision.artifactHashes.join(",") || "none"}]`),
+        "",
+        "## Open Tasks",
+        ...checkpoint.openTasks.map((task) => `- ${task.id} p${task.priority}: ${task.summary}`),
+        "",
+        "## Blockers",
+        ...checkpoint.blockers.map((blocker) => `- ${blocker.id} ${blocker.severity}: ${blocker.summary}`),
+        "",
+        "## Files",
+        `- read: ${checkpoint.files.read.join(",") || "none"}`,
+        `- modified: ${checkpoint.files.modified.join(",") || "none"}`,
+        "",
+        "## Commands",
+        ...checkpoint.commands.map((command) => `- ${command.command} => exitCode=${command.exitCode}, outputHash=${command.outputHash}`),
+        "",
+        "## Artifacts",
+        ...checkpoint.artifacts.map((artifact) => `- ${artifact.kind}: ${artifact.path} sha256=${artifact.sha256}`),
+        "",
+        "## Failed Approaches",
+        ...checkpoint.failedApproaches.map((approach) => `- ${approach.summary}: ${approach.reason}`),
+        "",
+        `Resume: ${checkpoint.resumeAction.summary}${checkpoint.resumeAction.targetTaskId ? ` (${checkpoint.resumeAction.targetTaskId})` : ""}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function validateCheckpoint(checkpoint, authoritative) {
+    const errors = [];
+    validateCommands(checkpoint, authoritative, errors);
+    validateBlockers(checkpoint, authoritative, errors);
+    validateFiles(checkpoint, authoritative, errors);
+    validateArtifacts(checkpoint, authoritative, errors);
+    return { valid: errors.length === 0, errors };
+}
+export function deriveResumePlan(checkpoint) {
+    const blocker = [...checkpoint.blockers].sort(compareBlockerPriority)[0];
+    if (blocker !== undefined) {
+        return { kind: "blocker", summary: blocker.summary, targetId: blocker.id };
+    }
+    const task = [...checkpoint.openTasks].sort(compareTaskPriority)[0];
+    if (task !== undefined) {
+        return { kind: "task", summary: task.summary, targetId: task.id };
+    }
+    return {
+        kind: "resumeAction",
+        summary: checkpoint.resumeAction.summary,
+        targetId: checkpoint.resumeAction.targetTaskId,
+    };
+}
+export function enforceCheckpointBudget(markdown, maxChars) {
+    if (markdown.length <= maxChars) {
+        return markdown;
+    }
+    const goal = findLine(markdown, "Goal:") ?? "Goal: unknown";
+    const resume = findLine(markdown, "Resume:") ?? "Resume: unknown";
+    const compact = [`# OMK Checkpoint`, goal, "Evidence hashes preserved.", resume].join("\n");
+    if (compact.length <= maxChars) {
+        return compact;
+    }
+    return compact.slice(0, Math.max(0, maxChars));
+}
+function validateCommands(checkpoint, authoritative, errors) {
+    const byCommand = new Map(authoritative.commands.map((command) => [command.command, command]));
+    for (const command of checkpoint.commands) {
+        const expected = byCommand.get(command.command);
+        if (expected === undefined) {
+            errors.push(`command missing from authoritative source: ${command.command}`);
+            continue;
+        }
+        if (command.exitCode !== expected.exitCode) {
+            errors.push(`command exitCode mismatch for ${command.command}: ${command.exitCode} != ${expected.exitCode}`);
+        }
+        if (command.outputHash !== expected.outputHash) {
+            errors.push(`command outputHash mismatch for ${command.command}: ${command.outputHash} != ${expected.outputHash}`);
+        }
+    }
+}
+function validateBlockers(checkpoint, authoritative, errors) {
+    const authoritativeIds = new Set(authoritative.blockerIds);
+    for (const blocker of checkpoint.blockers) {
+        if (!authoritativeIds.has(blocker.id)) {
+            errors.push(`blocker not present in authoritative source: ${blocker.id}`);
+        }
+    }
+}
+function validateFiles(checkpoint, authoritative, errors) {
+    const authoritativePaths = new Set(authoritative.filePaths);
+    for (const filePath of [...checkpoint.files.read, ...checkpoint.files.modified]) {
+        if (!authoritativePaths.has(filePath)) {
+            errors.push(`file path not present in authoritative source: ${filePath}`);
+        }
+    }
+}
+function validateArtifacts(checkpoint, authoritative, errors) {
+    const byPath = new Map(authoritative.artifacts.map((artifact) => [artifact.path, artifact]));
+    for (const artifact of checkpoint.artifacts) {
+        const expected = byPath.get(artifact.path);
+        if (expected === undefined) {
+            errors.push(`artifact missing from authoritative source: ${artifact.path}`);
+            continue;
+        }
+        if (artifact.sha256 !== expected.sha256) {
+            errors.push(`artifact sha256 mismatch for ${artifact.path}: ${artifact.sha256} != ${expected.sha256}`);
+        }
+    }
+}
+function formatBullets(values) {
+    if (values.length === 0) {
+        return ["- none"];
+    }
+    return values.map((value) => `- ${value}`);
+}
+function blockerRank(severity) {
+    if (severity === "high")
+        return 0;
+    if (severity === "medium")
+        return 1;
+    return 2;
+}
+function compareBlockerPriority(a, b) {
+    const rank = blockerRank(a.severity) - blockerRank(b.severity);
+    if (rank !== 0)
+        return rank;
+    return compareString(a.id, b.id);
+}
+function compareTaskPriority(a, b) {
+    if (a.priority !== b.priority)
+        return a.priority - b.priority;
+    return compareString(a.id, b.id);
+}
+function compareString(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+function findLine(markdown, prefix) {
+    return markdown.split("\n").find((line) => line.startsWith(prefix));
+}
+//# sourceMappingURL=checkpoint.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../../src/core/orchestration/checkpoint.ts"],"names":[],"mappings":"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","sourcesContent":["export const CHECKPOINT_SCHEMA_VERSION = \"omk.checkpoint.v1\";\n\nexport type CheckpointStatus = \"intake\" | \"running\" | \"blocked\" | \"complete\" | \"failed\";\nexport type BlockerSeverity = \"low\" | \"medium\" | \"high\";\n\nexport interface GoalState {\n\tsummary: string;\n\tstatus: CheckpointStatus;\n}\n\nexport interface DecisionRecord {\n\tid: string;\n\tsummary: string;\n\tartifactHashes: readonly string[];\n}\n\nexport interface OpenTaskRecord {\n\tid: string;\n\tsummary: string;\n\tpriority: number;\n}\n\nexport interface BlockerRecord {\n\tid: string;\n\tsummary: string;\n\tseverity: BlockerSeverity;\n}\n\nexport interface FileState {\n\tread: readonly string[];\n\tmodified: readonly string[];\n}\n\nexport interface CommandRecord {\n\tcommand: string;\n\texitCode: number;\n\toutputHash: string;\n}\n\nexport interface ArtifactRecord {\n\tpath: string;\n\tsha256: string;\n\tkind: string;\n}\n\nexport interface FailedApproachRecord {\n\tsummary: string;\n\treason: string;\n}\n\nexport interface ResumeActionRecord {\n\tsummary: string;\n\ttargetTaskId?: string;\n}\n\nexport interface Checkpoint {\n\tschemaVersion: typeof CHECKPOINT_SCHEMA_VERSION;\n\tcheckpointId: string;\n\trunId: string;\n\ttimestamp: string;\n\tcurrentGoal: GoalState;\n\tconstraints: readonly string[];\n\tdecisions: readonly DecisionRecord[];\n\topenTasks: readonly OpenTaskRecord[];\n\tblockers: readonly BlockerRecord[];\n\tfiles: FileState;\n\tcommands: readonly CommandRecord[];\n\tartifacts: readonly ArtifactRecord[];\n\tfailedApproaches: readonly FailedApproachRecord[];\n\tresumeAction: ResumeActionRecord;\n}\n\nexport interface AuthoritativeCheckpointSource {\n\tcommands: readonly CommandRecord[];\n\tblockerIds: readonly string[];\n\tfilePaths: readonly string[];\n\tartifacts: readonly { path: string; sha256: string }[];\n}\n\nexport interface CheckpointValidationResult {\n\tvalid: boolean;\n\terrors: string[];\n}\n\nexport interface ResumePlan {\n\tkind: \"blocker\" | \"task\" | \"resumeAction\";\n\tsummary: string;\n\ttargetId?: string;\n}\n\nexport function renderCheckpointMarkdown(checkpoint: Checkpoint): string {\n\tconst lines: string[] = [\n\t\t`# OMK Checkpoint ${checkpoint.checkpointId}`,\n\t\t`Run: ${checkpoint.runId}`,\n\t\t`Timestamp: ${checkpoint.timestamp}`,\n\t\t`Goal: ${checkpoint.currentGoal.summary} (${checkpoint.currentGoal.status})`,\n\t\t\"\",\n\t\t\"## Constraints\",\n\t\t...formatBullets(checkpoint.constraints),\n\t\t\"\",\n\t\t\"## Decisions\",\n\t\t...checkpoint.decisions.map(\n\t\t\t(decision) => `- ${decision.id}: ${decision.summary} [hashes: ${decision.artifactHashes.join(\",\") || \"none\"}]`,\n\t\t),\n\t\t\"\",\n\t\t\"## Open Tasks\",\n\t\t...checkpoint.openTasks.map((task) => `- ${task.id} p${task.priority}: ${task.summary}`),\n\t\t\"\",\n\t\t\"## Blockers\",\n\t\t...checkpoint.blockers.map((blocker) => `- ${blocker.id} ${blocker.severity}: ${blocker.summary}`),\n\t\t\"\",\n\t\t\"## Files\",\n\t\t`- read: ${checkpoint.files.read.join(\",\") || \"none\"}`,\n\t\t`- modified: ${checkpoint.files.modified.join(\",\") || \"none\"}`,\n\t\t\"\",\n\t\t\"## Commands\",\n\t\t...checkpoint.commands.map(\n\t\t\t(command) => `- ${command.command} => exitCode=${command.exitCode}, outputHash=${command.outputHash}`,\n\t\t),\n\t\t\"\",\n\t\t\"## Artifacts\",\n\t\t...checkpoint.artifacts.map((artifact) => `- ${artifact.kind}: ${artifact.path} sha256=${artifact.sha256}`),\n\t\t\"\",\n\t\t\"## Failed Approaches\",\n\t\t...checkpoint.failedApproaches.map((approach) => `- ${approach.summary}: ${approach.reason}`),\n\t\t\"\",\n\t\t`Resume: ${checkpoint.resumeAction.summary}${checkpoint.resumeAction.targetTaskId ? ` (${checkpoint.resumeAction.targetTaskId})` : \"\"}`,\n\t];\n\treturn `${lines.join(\"\\n\")}\\n`;\n}\n\nexport function validateCheckpoint(\n\tcheckpoint: Checkpoint,\n\tauthoritative: AuthoritativeCheckpointSource,\n): CheckpointValidationResult {\n\tconst errors: string[] = [];\n\tvalidateCommands(checkpoint, authoritative, errors);\n\tvalidateBlockers(checkpoint, authoritative, errors);\n\tvalidateFiles(checkpoint, authoritative, errors);\n\tvalidateArtifacts(checkpoint, authoritative, errors);\n\treturn { valid: errors.length === 0, errors };\n}\n\nexport function deriveResumePlan(checkpoint: Checkpoint): ResumePlan {\n\tconst blocker = [...checkpoint.blockers].sort(compareBlockerPriority)[0];\n\tif (blocker !== undefined) {\n\t\treturn { kind: \"blocker\", summary: blocker.summary, targetId: blocker.id };\n\t}\n\n\tconst task = [...checkpoint.openTasks].sort(compareTaskPriority)[0];\n\tif (task !== undefined) {\n\t\treturn { kind: \"task\", summary: task.summary, targetId: task.id };\n\t}\n\n\treturn {\n\t\tkind: \"resumeAction\",\n\t\tsummary: checkpoint.resumeAction.summary,\n\t\ttargetId: checkpoint.resumeAction.targetTaskId,\n\t};\n}\n\nexport function enforceCheckpointBudget(markdown: string, maxChars: number): string {\n\tif (markdown.length <= maxChars) {\n\t\treturn markdown;\n\t}\n\n\tconst goal = findLine(markdown, \"Goal:\") ?? \"Goal: unknown\";\n\tconst resume = findLine(markdown, \"Resume:\") ?? \"Resume: unknown\";\n\tconst compact = [`# OMK Checkpoint`, goal, \"Evidence hashes preserved.\", resume].join(\"\\n\");\n\tif (compact.length <= maxChars) {\n\t\treturn compact;\n\t}\n\treturn compact.slice(0, Math.max(0, maxChars));\n}\n\nfunction validateCommands(\n\tcheckpoint: Checkpoint,\n\tauthoritative: AuthoritativeCheckpointSource,\n\terrors: string[],\n): void {\n\tconst byCommand = new Map(authoritative.commands.map((command) => [command.command, command]));\n\tfor (const command of checkpoint.commands) {\n\t\tconst expected = byCommand.get(command.command);\n\t\tif (expected === undefined) {\n\t\t\terrors.push(`command missing from authoritative source: ${command.command}`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (command.exitCode !== expected.exitCode) {\n\t\t\terrors.push(`command exitCode mismatch for ${command.command}: ${command.exitCode} != ${expected.exitCode}`);\n\t\t}\n\t\tif (command.outputHash !== expected.outputHash) {\n\t\t\terrors.push(\n\t\t\t\t`command outputHash mismatch for ${command.command}: ${command.outputHash} != ${expected.outputHash}`,\n\t\t\t);\n\t\t}\n\t}\n}\n\nfunction validateBlockers(\n\tcheckpoint: Checkpoint,\n\tauthoritative: AuthoritativeCheckpointSource,\n\terrors: string[],\n): void {\n\tconst authoritativeIds = new Set(authoritative.blockerIds);\n\tfor (const blocker of checkpoint.blockers) {\n\t\tif (!authoritativeIds.has(blocker.id)) {\n\t\t\terrors.push(`blocker not present in authoritative source: ${blocker.id}`);\n\t\t}\n\t}\n}\n\nfunction validateFiles(checkpoint: Checkpoint, authoritative: AuthoritativeCheckpointSource, errors: string[]): void {\n\tconst authoritativePaths = new Set(authoritative.filePaths);\n\tfor (const filePath of [...checkpoint.files.read, ...checkpoint.files.modified]) {\n\t\tif (!authoritativePaths.has(filePath)) {\n\t\t\terrors.push(`file path not present in authoritative source: ${filePath}`);\n\t\t}\n\t}\n}\n\nfunction validateArtifacts(\n\tcheckpoint: Checkpoint,\n\tauthoritative: AuthoritativeCheckpointSource,\n\terrors: string[],\n): void {\n\tconst byPath = new Map(authoritative.artifacts.map((artifact) => [artifact.path, artifact]));\n\tfor (const artifact of checkpoint.artifacts) {\n\t\tconst expected = byPath.get(artifact.path);\n\t\tif (expected === undefined) {\n\t\t\terrors.push(`artifact missing from authoritative source: ${artifact.path}`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (artifact.sha256 !== expected.sha256) {\n\t\t\terrors.push(`artifact sha256 mismatch for ${artifact.path}: ${artifact.sha256} != ${expected.sha256}`);\n\t\t}\n\t}\n}\n\nfunction formatBullets(values: readonly string[]): string[] {\n\tif (values.length === 0) {\n\t\treturn [\"- none\"];\n\t}\n\treturn values.map((value) => `- ${value}`);\n}\n\nfunction blockerRank(severity: BlockerSeverity): number {\n\tif (severity === \"high\") return 0;\n\tif (severity === \"medium\") return 1;\n\treturn 2;\n}\n\nfunction compareBlockerPriority(a: BlockerRecord, b: BlockerRecord): number {\n\tconst rank = blockerRank(a.severity) - blockerRank(b.severity);\n\tif (rank !== 0) return rank;\n\treturn compareString(a.id, b.id);\n}\n\nfunction compareTaskPriority(a: OpenTaskRecord, b: OpenTaskRecord): number {\n\tif (a.priority !== b.priority) return a.priority - b.priority;\n\treturn compareString(a.id, b.id);\n}\n\nfunction compareString(a: string, b: string): number {\n\tif (a < b) return -1;\n\tif (a > b) return 1;\n\treturn 0;\n}\n\nfunction findLine(markdown: string, prefix: string): string | undefined {\n\treturn markdown.split(\"\\n\").find((line) => line.startsWith(prefix));\n}\n"]}

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

@@ -0,0 +1,74 @@
+/**
+ * Phase 0 safety contracts for the fail-closed orchestration control plane.
+ *
+ * These are pure type/value definitions shared by the transaction coordinator,
+ * recovery classifier, and (later) the SQLite scheduler store. They encode the
+ * invariant that no state-changing mutation may commit unless its required
+ * ledger event was durably appended and mirrored.
+ *
+ * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md
+ * (Phase 0 + Phase 1) and audit-transaction.md.
+ */
+/**
+ * Coarse transaction phase for a single durable operation. Carried on every
+ * typed coordinator error so operators and recovery can locate the crash point.
+ */
+export type TransactionPhase = "prepare" | "start" | "apply" | "receipt" | "verify" | "commit" | "rollback" | "compensate";
+/**
+ * Whether a ledger event is mandatory before the surrounding mutation commits
+ * ("required", fail-closed) or best-effort observability ("optional-readonly").
+ */
+export type LedgerRequirement = "required" | "optional-readonly";
+/**
+ * Execution mode is derived from print/json/RPC/SDK invocation, independent of
+ * whether an interactive UI is available. Headless never auto-confirms.
+ */
+export type ExecutionMode = "interactive" | "headless";
+/**
+ * How a typed coordinator failure should be handled by recovery/operators.
+ */
+export type CoordinatorRecoverability = "retry" | "rollback" | "in_doubt" | "operator";
+/**
+ * Closed set of typed coordinator error codes (algorithm-plan Phase 0).
+ */
+export type CoordinatorErrorCode = "LEDGER_APPEND_REQUIRED_FAILED" | "LEDGER_INTEGRITY_FAILED" | "SQLITE_MIRROR_FAILED" | "SQLITE_COMMIT_AFTER_LEDGER_FAILED" | "IDEMPOTENCY_CONFLICT" | "VERIFY_GATE_FAILED" | "COMPENSATION_FAILED";
+/**
+ * Structured metadata attached to every coordinator error. Preserving this
+ * across throws is what lets recovery map a crash to resume/rollback/in_doubt.
+ */
+export interface CoordinatorErrorContext {
+    runId: string;
+    nodeId: string;
+    operationId: string;
+    phase: TransactionPhase;
+    recoverability: CoordinatorRecoverability;
+    attemptId?: string;
+    eventType?: string;
+    cause?: unknown;
+}
+/**
+ * Base typed error for the orchestration control plane. Always carries the
+ * operation identity, phase, and recoverability so failures are auditable.
+ */
+export declare class CoordinatorError extends Error {
+    readonly code: CoordinatorErrorCode;
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly operationId: string;
+    readonly phase: TransactionPhase;
+    readonly recoverability: CoordinatorRecoverability;
+    readonly attemptId?: string;
+    readonly eventType?: string;
+    constructor(code: CoordinatorErrorCode, message: string, context: CoordinatorErrorContext);
+}
+/**
+ * Required-audit-write failure: a mandatory ledger event could not be appended,
+ * so the surrounding mutation must roll back fail-closed. This is the canonical
+ * `LEDGER_APPEND_REQUIRED_FAILED` error and defaults to `rollback` recovery.
+ */
+export declare class RequiredAuditWriteError extends CoordinatorError {
+    constructor(message: string, context: Omit<CoordinatorErrorContext, "recoverability" | "code"> & {
+        recoverability?: CoordinatorRecoverability;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACzB,SAAS,GACT,OAAO,GACP,OAAO,GACP,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,YAAY,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,mBAAmB,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,UAAU,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAEvF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC7B,+BAA+B,GAC/B,yBAAyB,GACzB,sBAAsB,GACtB,mCAAmC,GACnC,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,CAAC;AAEzB;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,gBAAgB,CAAC;IACxB,cAAc,EAAE,yBAAyB,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAAC;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,YAAY,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,EAWxF;CACD;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,gBAAgB;IAC5D,YACC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,gBAAgB,GAAG,MAAM,CAAC,GAAG;QACnE,cAAc,CAAC,EAAE,yBAAyB,CAAC;KAC3C,EAOD;CACD","sourcesContent":["/**\n * Phase 0 safety contracts for the fail-closed orchestration control plane.\n *\n * These are pure type/value definitions shared by the transaction coordinator,\n * recovery classifier, and (later) the SQLite scheduler store. They encode the\n * invariant that no state-changing mutation may commit unless its required\n * ledger event was durably appended and mirrored.\n *\n * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md\n * (Phase 0 + Phase 1) and audit-transaction.md.\n */\n\n/**\n * Coarse transaction phase for a single durable operation. Carried on every\n * typed coordinator error so operators and recovery can locate the crash point.\n */\nexport type TransactionPhase =\n\t| \"prepare\"\n\t| \"start\"\n\t| \"apply\"\n\t| \"receipt\"\n\t| \"verify\"\n\t| \"commit\"\n\t| \"rollback\"\n\t| \"compensate\";\n\n/**\n * Whether a ledger event is mandatory before the surrounding mutation commits\n * (\"required\", fail-closed) or best-effort observability (\"optional-readonly\").\n */\nexport type LedgerRequirement = \"required\" | \"optional-readonly\";\n\n/**\n * Execution mode is derived from print/json/RPC/SDK invocation, independent of\n * whether an interactive UI is available. Headless never auto-confirms.\n */\nexport type ExecutionMode = \"interactive\" | \"headless\";\n\n/**\n * How a typed coordinator failure should be handled by recovery/operators.\n */\nexport type CoordinatorRecoverability = \"retry\" | \"rollback\" | \"in_doubt\" | \"operator\";\n\n/**\n * Closed set of typed coordinator error codes (algorithm-plan Phase 0).\n */\nexport type CoordinatorErrorCode =\n\t| \"LEDGER_APPEND_REQUIRED_FAILED\"\n\t| \"LEDGER_INTEGRITY_FAILED\"\n\t| \"SQLITE_MIRROR_FAILED\"\n\t| \"SQLITE_COMMIT_AFTER_LEDGER_FAILED\"\n\t| \"IDEMPOTENCY_CONFLICT\"\n\t| \"VERIFY_GATE_FAILED\"\n\t| \"COMPENSATION_FAILED\";\n\n/**\n * Structured metadata attached to every coordinator error. Preserving this\n * across throws is what lets recovery map a crash to resume/rollback/in_doubt.\n */\nexport interface CoordinatorErrorContext {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tphase: TransactionPhase;\n\trecoverability: CoordinatorRecoverability;\n\tattemptId?: string;\n\teventType?: string;\n\tcause?: unknown;\n}\n\n/**\n * Base typed error for the orchestration control plane. Always carries the\n * operation identity, phase, and recoverability so failures are auditable.\n */\nexport class CoordinatorError extends Error {\n\treadonly code: CoordinatorErrorCode;\n\treadonly runId: string;\n\treadonly nodeId: string;\n\treadonly operationId: string;\n\treadonly phase: TransactionPhase;\n\treadonly recoverability: CoordinatorRecoverability;\n\treadonly attemptId?: string;\n\treadonly eventType?: string;\n\n\tconstructor(code: CoordinatorErrorCode, message: string, context: CoordinatorErrorContext) {\n\t\tsuper(message, context.cause === undefined ? undefined : { cause: context.cause });\n\t\tthis.name = \"CoordinatorError\";\n\t\tthis.code = code;\n\t\tthis.runId = context.runId;\n\t\tthis.nodeId = context.nodeId;\n\t\tthis.operationId = context.operationId;\n\t\tthis.phase = context.phase;\n\t\tthis.recoverability = context.recoverability;\n\t\tthis.attemptId = context.attemptId;\n\t\tthis.eventType = context.eventType;\n\t}\n}\n\n/**\n * Required-audit-write failure: a mandatory ledger event could not be appended,\n * so the surrounding mutation must roll back fail-closed. This is the canonical\n * `LEDGER_APPEND_REQUIRED_FAILED` error and defaults to `rollback` recovery.\n */\nexport class RequiredAuditWriteError extends CoordinatorError {\n\tconstructor(\n\t\tmessage: string,\n\t\tcontext: Omit<CoordinatorErrorContext, \"recoverability\" | \"code\"> & {\n\t\t\trecoverability?: CoordinatorRecoverability;\n\t\t},\n\t) {\n\t\tsuper(\"LEDGER_APPEND_REQUIRED_FAILED\", message, {\n\t\t\t...context,\n\t\t\trecoverability: context.recoverability ?? \"rollback\",\n\t\t});\n\t\tthis.name = \"RequiredAuditWriteError\";\n\t}\n}\n"]}

package/dist/core/orchestration/errors.js

@@ -0,0 +1,52 @@
+/**
+ * Phase 0 safety contracts for the fail-closed orchestration control plane.
+ *
+ * These are pure type/value definitions shared by the transaction coordinator,
+ * recovery classifier, and (later) the SQLite scheduler store. They encode the
+ * invariant that no state-changing mutation may commit unless its required
+ * ledger event was durably appended and mirrored.
+ *
+ * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md
+ * (Phase 0 + Phase 1) and audit-transaction.md.
+ */
+/**
+ * Base typed error for the orchestration control plane. Always carries the
+ * operation identity, phase, and recoverability so failures are auditable.
+ */
+export class CoordinatorError extends Error {
+    code;
+    runId;
+    nodeId;
+    operationId;
+    phase;
+    recoverability;
+    attemptId;
+    eventType;
+    constructor(code, message, context) {
+        super(message, context.cause === undefined ? undefined : { cause: context.cause });
+        this.name = "CoordinatorError";
+        this.code = code;
+        this.runId = context.runId;
+        this.nodeId = context.nodeId;
+        this.operationId = context.operationId;
+        this.phase = context.phase;
+        this.recoverability = context.recoverability;
+        this.attemptId = context.attemptId;
+        this.eventType = context.eventType;
+    }
+}
+/**
+ * Required-audit-write failure: a mandatory ledger event could not be appended,
+ * so the surrounding mutation must roll back fail-closed. This is the canonical
+ * `LEDGER_APPEND_REQUIRED_FAILED` error and defaults to `rollback` recovery.
+ */
+export class RequiredAuditWriteError extends CoordinatorError {
+    constructor(message, context) {
+        super("LEDGER_APPEND_REQUIRED_FAILED", message, {
+            ...context,
+            recoverability: context.recoverability ?? "rollback",
+        });
+        this.name = "RequiredAuditWriteError";
+    }
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/core/orchestration/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4DH;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACjC,IAAI,CAAuB;IAC3B,KAAK,CAAS;IACd,MAAM,CAAS;IACf,WAAW,CAAS;IACpB,KAAK,CAAmB;IACxB,cAAc,CAA4B;IAC1C,SAAS,CAAU;IACnB,SAAS,CAAU;IAE5B,YAAY,IAA0B,EAAE,OAAe,EAAE,OAAgC,EAAE;QAC1F,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAAA,CACnC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,gBAAgB;IAC5D,YACC,OAAe,EACf,OAEC,EACA;QACD,KAAK,CAAC,+BAA+B,EAAE,OAAO,EAAE;YAC/C,GAAG,OAAO;YACV,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,UAAU;SACpD,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAAA,CACtC;CACD","sourcesContent":["/**\n * Phase 0 safety contracts for the fail-closed orchestration control plane.\n *\n * These are pure type/value definitions shared by the transaction coordinator,\n * recovery classifier, and (later) the SQLite scheduler store. They encode the\n * invariant that no state-changing mutation may commit unless its required\n * ledger event was durably appended and mirrored.\n *\n * Reference: .omk/runs/omk-autonomous-harness-remediation-plan/algorithm-plan.md\n * (Phase 0 + Phase 1) and audit-transaction.md.\n */\n\n/**\n * Coarse transaction phase for a single durable operation. Carried on every\n * typed coordinator error so operators and recovery can locate the crash point.\n */\nexport type TransactionPhase =\n\t| \"prepare\"\n\t| \"start\"\n\t| \"apply\"\n\t| \"receipt\"\n\t| \"verify\"\n\t| \"commit\"\n\t| \"rollback\"\n\t| \"compensate\";\n\n/**\n * Whether a ledger event is mandatory before the surrounding mutation commits\n * (\"required\", fail-closed) or best-effort observability (\"optional-readonly\").\n */\nexport type LedgerRequirement = \"required\" | \"optional-readonly\";\n\n/**\n * Execution mode is derived from print/json/RPC/SDK invocation, independent of\n * whether an interactive UI is available. Headless never auto-confirms.\n */\nexport type ExecutionMode = \"interactive\" | \"headless\";\n\n/**\n * How a typed coordinator failure should be handled by recovery/operators.\n */\nexport type CoordinatorRecoverability = \"retry\" | \"rollback\" | \"in_doubt\" | \"operator\";\n\n/**\n * Closed set of typed coordinator error codes (algorithm-plan Phase 0).\n */\nexport type CoordinatorErrorCode =\n\t| \"LEDGER_APPEND_REQUIRED_FAILED\"\n\t| \"LEDGER_INTEGRITY_FAILED\"\n\t| \"SQLITE_MIRROR_FAILED\"\n\t| \"SQLITE_COMMIT_AFTER_LEDGER_FAILED\"\n\t| \"IDEMPOTENCY_CONFLICT\"\n\t| \"VERIFY_GATE_FAILED\"\n\t| \"COMPENSATION_FAILED\";\n\n/**\n * Structured metadata attached to every coordinator error. Preserving this\n * across throws is what lets recovery map a crash to resume/rollback/in_doubt.\n */\nexport interface CoordinatorErrorContext {\n\trunId: string;\n\tnodeId: string;\n\toperationId: string;\n\tphase: TransactionPhase;\n\trecoverability: CoordinatorRecoverability;\n\tattemptId?: string;\n\teventType?: string;\n\tcause?: unknown;\n}\n\n/**\n * Base typed error for the orchestration control plane. Always carries the\n * operation identity, phase, and recoverability so failures are auditable.\n */\nexport class CoordinatorError extends Error {\n\treadonly code: CoordinatorErrorCode;\n\treadonly runId: string;\n\treadonly nodeId: string;\n\treadonly operationId: string;\n\treadonly phase: TransactionPhase;\n\treadonly recoverability: CoordinatorRecoverability;\n\treadonly attemptId?: string;\n\treadonly eventType?: string;\n\n\tconstructor(code: CoordinatorErrorCode, message: string, context: CoordinatorErrorContext) {\n\t\tsuper(message, context.cause === undefined ? undefined : { cause: context.cause });\n\t\tthis.name = \"CoordinatorError\";\n\t\tthis.code = code;\n\t\tthis.runId = context.runId;\n\t\tthis.nodeId = context.nodeId;\n\t\tthis.operationId = context.operationId;\n\t\tthis.phase = context.phase;\n\t\tthis.recoverability = context.recoverability;\n\t\tthis.attemptId = context.attemptId;\n\t\tthis.eventType = context.eventType;\n\t}\n}\n\n/**\n * Required-audit-write failure: a mandatory ledger event could not be appended,\n * so the surrounding mutation must roll back fail-closed. This is the canonical\n * `LEDGER_APPEND_REQUIRED_FAILED` error and defaults to `rollback` recovery.\n */\nexport class RequiredAuditWriteError extends CoordinatorError {\n\tconstructor(\n\t\tmessage: string,\n\t\tcontext: Omit<CoordinatorErrorContext, \"recoverability\" | \"code\"> & {\n\t\t\trecoverability?: CoordinatorRecoverability;\n\t\t},\n\t) {\n\t\tsuper(\"LEDGER_APPEND_REQUIRED_FAILED\", message, {\n\t\t\t...context,\n\t\t\trecoverability: context.recoverability ?? \"rollback\",\n\t\t});\n\t\tthis.name = \"RequiredAuditWriteError\";\n\t}\n}\n"]}

package/dist/core/orchestration/merge-queue.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Deterministic merge-queue pure algorithms for the OMK durable DAG scheduler.
+ *
+ * This module contains ONLY pure data transformations. It performs NO real git
+ * execution and NO I/O. The durable SQLite scheduler (see foundation.md
+ * `merge_queue` table) and the git worktree integration lane (see
+ * worktree-merge.md) consume these helpers to decide ordering, promotion
+ * gating, conflict recording, and orphan-worktree reclaim policy.
+ *
+ * Design contract (worktree-merge.md §3.1, §3.3, §4.2, §5):
+ * - Merge is strictly serial: exactly one entry advances per selection.
+ * - Selection order key is fully deterministic:
+ *     priority ASC, dagDepth ASC, leaseFinishedAt ASC, queueId ASC.
+ * - Verify gate: a merge_queue entry can only advance from `pending` once its
+ *   owning node reached the completed state AND its VerificationContract passed.
+ *   This module trusts `completedNodeIds` (the scheduler supplies the verified
+ *   completed set); pure logic only enforces the membership check.
+ * - Promotion gate: the canonical branch is promoted only when the entry is in
+ *   `merging`, verification passed, the target branch is unchanged, and no
+ *   conflict was detected.
+ * - Worktree reclaim never removes outside `.omk/worktrees/`.
+ */
+export type MergeQueueStatus = "pending" | "merging" | "merged" | "conflict" | "blocked";
+/**
+ * A single merge_queue row plus the ordering metadata derived from the owning
+ * node and its lease. `leaseFinishedAt` mirrors the owning node's `finished_at`
+ * (the moment its lease ended); it is `null` when the node has not finished.
+ */
+export interface MergeQueueEntry {
+    queueId: string;
+    runId: string;
+    nodeId: string;
+    branchName: string;
+    targetBranch: string;
+    status: MergeQueueStatus;
+    priority: number;
+    dagDepth: number;
+    leaseFinishedAt: string | null;
+    createdAt: string;
+}
+/**
+ * Inputs to the canonical-branch promotion gate. The scheduler fills these from
+ * the merge worktree preparation + re-verification step (worktree-merge.md §5).
+ */
+export interface MergePromotionDecision {
+    queueStatus: MergeQueueStatus;
+    verificationPassed: boolean;
+    targetUnchanged: boolean;
+    conflict: boolean;
+}
+/** One side of a path-level merge conflict (ours / theirs blob SHAs). */
+export interface ConflictFile {
+    path: string;
+    ours: string;
+    theirs: string;
+}
+/** Deterministic conflict artifact persisted to the artifacts table. */
+export interface ConflictArtifact {
+    type: "merge-conflict";
+    runId: string;
+    nodeId: string;
+    branch: string;
+    targetBranch: string;
+    conflictedFiles: ConflictFile[];
+    mergeBase: string;
+    createdAt: string;
+}
+/** Caller-supplied raw conflict data; files may arrive in any order. */
+export interface ConflictArtifactInput {
+    runId: string;
+    nodeId: string;
+    branch: string;
+    targetBranch: string;
+    conflictedFiles: ConflictFile[];
+    mergeBase: string;
+    createdAt: string;
+}
+/** Worktree reclaim decision returned by {@link shouldReclaimWorktree}. */
+export type WorktreeReclaimAction = "preserve" | "remove" | "ignore";
+/**
+ * Choose exactly one pending merge_queue entry to advance next.
+ *
+ * Selection rules:
+ *  1. Only `pending` entries are eligible.
+ *  2. Verify gate: the owning node must be in `completedNodeIds` (the scheduler
+ *     only adds nodes that reached `completed` AND passed VerificationContract).
+ *  3. Among eligible entries, order by priority ASC, dagDepth ASC,
+ *     leaseFinishedAt ASC (nulls last), queueId ASC. queueId is the unique
+ *     final tie-break, so the result is fully deterministic.
+ *
+ * Returns `undefined` when no entry is eligible.
+ */
+export declare function selectNextMergeEntry(entries: readonly MergeQueueEntry[], completedNodeIds: ReadonlySet<string>): MergeQueueEntry | undefined;
+/**
+ * Promotion gate for the canonical (target) branch.
+ *
+ * Returns true only when every promotion precondition holds:
+ * queue is `merging`, verification passed, the target branch is unchanged,
+ * and no conflict was detected. Any failure leaves the target untouched.
+ */
+export declare function canPromoteMerge(decision: MergePromotionDecision): boolean;
+/**
+ * Build a deterministic conflict artifact. `conflictedFiles` are copied and
+ * sorted by path (then ours, then theirs for total determinism); the input
+ * array is never mutated.
+ */
+export declare function createConflictArtifact(input: ConflictArtifactInput): ConflictArtifact;
+/**
+ * Decide the reclaim fate of a worktree during startup recovery
+ * (worktree-merge.md §2.3).
+ *
+ * - Outside `.omk/worktrees/`: always `ignore` (never remove user/foreign
+ *   worktrees).
+ * - Terminal node (completed/merged/failed/rolled_back/cancelled) under prefix:
+ *   `remove` — the worktree is leftover and safe to clean up.
+ * - Expired lease with a non-terminal node under prefix: `preserve` — orphan
+ *   recovery keeps the worktree and requeues the node.
+ * - Otherwise (active, healthy): `ignore`.
+ */
+export declare function shouldReclaimWorktree(nodeTerminal: boolean, leaseExpired: boolean, pathUnderOmkWorktrees: boolean): WorktreeReclaimAction;
+//# sourceMappingURL=merge-queue.d.ts.map

package/dist/core/orchestration/merge-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-queue.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/merge-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAEzF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CACf;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,YAAY,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,YAAY,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACnC,eAAe,GAAG,SAAS,CAU7B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,CAYrF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACpC,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,OAAO,EACrB,qBAAqB,EAAE,OAAO,GAC5B,qBAAqB,CAWvB","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/merge-queue.js

@@ -0,0 +1,149 @@
+/**
+ * Deterministic merge-queue pure algorithms for the OMK durable DAG scheduler.
+ *
+ * This module contains ONLY pure data transformations. It performs NO real git
+ * execution and NO I/O. The durable SQLite scheduler (see foundation.md
+ * `merge_queue` table) and the git worktree integration lane (see
+ * worktree-merge.md) consume these helpers to decide ordering, promotion
+ * gating, conflict recording, and orphan-worktree reclaim policy.
+ *
+ * Design contract (worktree-merge.md §3.1, §3.3, §4.2, §5):
+ * - Merge is strictly serial: exactly one entry advances per selection.
+ * - Selection order key is fully deterministic:
+ *     priority ASC, dagDepth ASC, leaseFinishedAt ASC, queueId ASC.
+ * - Verify gate: a merge_queue entry can only advance from `pending` once its
+ *   owning node reached the completed state AND its VerificationContract passed.
+ *   This module trusts `completedNodeIds` (the scheduler supplies the verified
+ *   completed set); pure logic only enforces the membership check.
+ * - Promotion gate: the canonical branch is promoted only when the entry is in
+ *   `merging`, verification passed, the target branch is unchanged, and no
+ *   conflict was detected.
+ * - Worktree reclaim never removes outside `.omk/worktrees/`.
+ */
+/**
+ * Choose exactly one pending merge_queue entry to advance next.
+ *
+ * Selection rules:
+ *  1. Only `pending` entries are eligible.
+ *  2. Verify gate: the owning node must be in `completedNodeIds` (the scheduler
+ *     only adds nodes that reached `completed` AND passed VerificationContract).
+ *  3. Among eligible entries, order by priority ASC, dagDepth ASC,
+ *     leaseFinishedAt ASC (nulls last), queueId ASC. queueId is the unique
+ *     final tie-break, so the result is fully deterministic.
+ *
+ * Returns `undefined` when no entry is eligible.
+ */
+export function selectNextMergeEntry(entries, completedNodeIds) {
+    const eligible = entries.filter((entry) => entry.status === "pending" && completedNodeIds.has(entry.nodeId));
+    if (eligible.length === 0) {
+        return undefined;
+    }
+    if (eligible.length === 1) {
+        return eligible[0];
+    }
+    const ordered = [...eligible].sort(compareMergeEntryOrder);
+    return ordered[0];
+}
+/**
+ * Promotion gate for the canonical (target) branch.
+ *
+ * Returns true only when every promotion precondition holds:
+ * queue is `merging`, verification passed, the target branch is unchanged,
+ * and no conflict was detected. Any failure leaves the target untouched.
+ */
+export function canPromoteMerge(decision) {
+    return (decision.queueStatus === "merging" &&
+        decision.verificationPassed === true &&
+        decision.targetUnchanged === true &&
+        decision.conflict === false);
+}
+/**
+ * Build a deterministic conflict artifact. `conflictedFiles` are copied and
+ * sorted by path (then ours, then theirs for total determinism); the input
+ * array is never mutated.
+ */
+export function createConflictArtifact(input) {
+    const conflictedFiles = [...input.conflictedFiles].sort(compareConflictFile);
+    return {
+        type: "merge-conflict",
+        runId: input.runId,
+        nodeId: input.nodeId,
+        branch: input.branch,
+        targetBranch: input.targetBranch,
+        conflictedFiles,
+        mergeBase: input.mergeBase,
+        createdAt: input.createdAt,
+    };
+}
+/**
+ * Decide the reclaim fate of a worktree during startup recovery
+ * (worktree-merge.md §2.3).
+ *
+ * - Outside `.omk/worktrees/`: always `ignore` (never remove user/foreign
+ *   worktrees).
+ * - Terminal node (completed/merged/failed/rolled_back/cancelled) under prefix:
+ *   `remove` — the worktree is leftover and safe to clean up.
+ * - Expired lease with a non-terminal node under prefix: `preserve` — orphan
+ *   recovery keeps the worktree and requeues the node.
+ * - Otherwise (active, healthy): `ignore`.
+ */
+export function shouldReclaimWorktree(nodeTerminal, leaseExpired, pathUnderOmkWorktrees) {
+    if (!pathUnderOmkWorktrees) {
+        return "ignore";
+    }
+    if (nodeTerminal) {
+        return "remove";
+    }
+    if (leaseExpired) {
+        return "preserve";
+    }
+    return "ignore";
+}
+function compareMergeEntryOrder(a, b) {
+    if (a.priority !== b.priority) {
+        return a.priority - b.priority;
+    }
+    if (a.dagDepth !== b.dagDepth) {
+        return a.dagDepth - b.dagDepth;
+    }
+    const byTime = compareNullableTimestamp(a.leaseFinishedAt, b.leaseFinishedAt);
+    if (byTime !== 0) {
+        return byTime;
+    }
+    return compareString(a.queueId, b.queueId);
+}
+function compareConflictFile(a, b) {
+    const byPath = compareString(a.path, b.path);
+    if (byPath !== 0) {
+        return byPath;
+    }
+    const byOurs = compareString(a.ours, b.ours);
+    if (byOurs !== 0) {
+        return byOurs;
+    }
+    return compareString(a.theirs, b.theirs);
+}
+function compareNullableTimestamp(a, b) {
+    // ISO-8601 strings sort lexicographically in chronological order; null
+    // (node never finished) sorts after any real timestamp.
+    if (a === null && b === null) {
+        return 0;
+    }
+    if (a === null) {
+        return 1;
+    }
+    if (b === null) {
+        return -1;
+    }
+    return compareString(a, b);
+}
+function compareString(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=merge-queue.js.map