open-multi-agent-kit 0.80.5 → 0.80.7

package/dist/core/orchestration/replay-ledger.js

@@ -0,0 +1,395 @@
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import path, { dirname } from "node:path";
+export function stableStringify(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("Cannot stableStringify non-finite number");
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    if (!isPlainObject(value)) {
+        throw new Error("Cannot stableStringify unsupported object");
+    }
+    const record = value;
+    const parts = [];
+    for (const key of Object.keys(record).sort()) {
+        const entryValue = record[key];
+        if (entryValue === undefined) {
+            throw new Error(`Cannot stableStringify undefined value at key ${key}`);
+        }
+        parts.push(`${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+export function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+export function computeEventHash(event) {
+    return sha256Hex(stableStringify(eventToJson(event)));
+}
+export function verifyReplayLedger(events) {
+    let previous;
+    for (let index = 0; index < events.length; index += 1) {
+        const current = events[index];
+        if (current.sequence !== index + 1) {
+            return { ok: false, error: `sequence mismatch at index ${index}: expected ${index + 1}` };
+        }
+        const expectedHash = computeEventHash(stripEventHash(current));
+        if (current.eventHash !== expectedHash) {
+            return { ok: false, error: `eventHash mismatch at sequence ${current.sequence}` };
+        }
+        const expectedPrevHash = previous?.eventHash ?? null;
+        if (current.prevEventHash !== expectedPrevHash) {
+            return { ok: false, error: `prevEventHash mismatch at sequence ${current.sequence}` };
+        }
+        if (previous !== undefined && current.beforeStateHash !== previous.afterStateHash) {
+            return { ok: false, error: `beforeStateHash mismatch at sequence ${current.sequence}` };
+        }
+        previous = current;
+    }
+    return { ok: true };
+}
+export function verifyArtifactReference(ref, resolver) {
+    const resolved = resolver(ref.path);
+    if (resolved === undefined) {
+        return { ok: false, error: `artifact not found: ${ref.path}` };
+    }
+    if (!resolved.isFile) {
+        return { ok: false, error: `artifact is not a file: ${ref.path}` };
+    }
+    if (!pathIsInside(ref.repoRoot, resolved.realPath)) {
+        return { ok: false, error: `artifact resolved outside repo root: ${resolved.realPath}` };
+    }
+    if (resolved.sha256 !== ref.sha256) {
+        return { ok: false, error: `artifact sha256 mismatch for ${ref.path}` };
+    }
+    return { ok: true };
+}
+// Canonicalize a base directory through realpath so symlinked roots (for example
+// macOS /tmp -> /private/tmp) compare consistently against realpath'd artifacts.
+// ── Persistence ────────────────────────────────────────────────────────────
+const LOCK_STALE_MS = 30000;
+/**
+ * Acquires an exclusive lock for the ledger file using O_CREAT|O_EXCL.
+ * Stale locks (older than LOCK_STALE_MS) are removed before retry.
+ */
+function acquireLock(lockPath, timeoutMs) {
+    const start = Date.now();
+    while (true) {
+        try {
+            return openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (existsSync(lockPath)) {
+                try {
+                    const stats = statSync(lockPath);
+                    if (Date.now() - stats.mtimeMs > LOCK_STALE_MS)
+                        rmSync(lockPath, { force: true });
+                }
+                catch {
+                    /* stale check best-effort */
+                }
+            }
+            if (Date.now() - start >= timeoutMs) {
+                throw error;
+            }
+        }
+    }
+}
+/**
+ * Appends a JSON line to the ledger file and fsyncs both the file and its
+ * parent directory so the write is durable on crash.
+ *
+ * Platform fallback: some filesystems (e.g. tmpfs, NFS) do not support
+ * directory fsync. In those cases the directory fsync is best-effort; the
+ * file fsync remains mandatory.
+ */
+function fsyncDirectory(dirPath) {
+    try {
+        const dirFd = openSync(dirPath, "r");
+        try {
+            fsyncSync(dirFd);
+        }
+        finally {
+            closeSync(dirFd);
+        }
+    }
+    catch {
+        // Directory fsync is not supported on all platforms/filesystems.
+        // File fsync remains the mandatory durability guarantee.
+    }
+}
+function enforcePrivateFilePermissions(filePath) {
+    try {
+        if (existsSync(filePath) && (statSync(filePath).mode & 0o777) !== 0o600) {
+            chmodSync(filePath, 0o600);
+        }
+    }
+    catch {
+        /* best-effort permission enforcement */
+    }
+}
+function appendJsonLineWithFsync(ledgerPath, line) {
+    const fd = openSync(ledgerPath, "a", 0o600);
+    try {
+        enforcePrivateFilePermissions(ledgerPath);
+        writeSync(fd, `${line}\n`, undefined, "utf-8");
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    fsyncDirectory(dirname(ledgerPath));
+}
+/**
+ * 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 function recordReplayLedgerEvent(event, options) {
+    const { ledgerPath } = options;
+    const lockPath = `${ledgerPath}.lock`;
+    let lockFd;
+    try {
+        // Create the ledger directory with owner-only permissions.
+        // mode is applied to the deepest directory; recursive parents use umask-adjusted defaults.
+        mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
+        // On platforms where mkdirSync with mode over umask can produce
+        // group/world-readable directories, re-apply the mode explicitly.
+        try {
+            const dirStats = statSync(dirname(ledgerPath));
+            if ((dirStats.mode & 0o777) !== 0o700) {
+                chmodSync(dirname(ledgerPath), 0o700);
+            }
+        }
+        catch {
+            /* best-effort permission enforcement */
+        }
+        lockFd = acquireLock(lockPath, options.lockTimeoutMs ?? 1000);
+        // Rotate if the ledger exceeds the size threshold.
+        if (Number.isFinite(options.maxLedgerBytes) && (options.maxLedgerBytes ?? 0) > 0 && existsSync(ledgerPath)) {
+            enforcePrivateFilePermissions(ledgerPath);
+            const stats = statSync(ledgerPath);
+            if (stats.size >= Math.floor(options.maxLedgerBytes)) {
+                // Simple rotation: rename current to .rotated, start fresh.
+                // The new ledger will start from genesis since we don't carry
+                // forward the previous hash chain across rotations for the
+                // orchestration replay ledger (unlike harness-control which uses anchors).
+                const rotatedPath = `${ledgerPath}.${new Date().toISOString().replace(/[:.]/g, "-")}.rotated`;
+                renameSync(ledgerPath, rotatedPath);
+                enforcePrivateFilePermissions(rotatedPath);
+                fsyncDirectory(dirname(ledgerPath));
+            }
+        }
+        appendJsonLineWithFsync(ledgerPath, JSON.stringify(event));
+        return { ok: true, path: ledgerPath, event };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            path: ledgerPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        if (lockFd !== undefined) {
+            try {
+                closeSync(lockFd);
+            }
+            catch {
+                /* fd may already be closed */
+            }
+            rmSync(lockPath, { force: true });
+        }
+    }
+}
+/**
+ * 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 function verifyReplayLedgerFromFile(ledgerPath) {
+    const errors = [];
+    const events = [];
+    const quarantinedLines = [];
+    if (!existsSync(ledgerPath))
+        return { ok: true, events, errors, quarantinedLines };
+    const content = readFileSync(ledgerPath, "utf-8");
+    const lines = content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    function quarantine(lineNumber, reason) {
+        quarantinedLines.push({ lineNumber, reason });
+        errors.push(`line ${lineNumber}: quarantined — ${reason}`);
+    }
+    for (let index = 0; index < lines.length; index++) {
+        const lineNumber = index + 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(lines[index]);
+        }
+        catch (jsonError) {
+            quarantine(lineNumber, `malformed JSON — ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`);
+            continue;
+        }
+        const requiredFields = [
+            "sequence",
+            "type",
+            "reducerVersion",
+            "payload",
+            "beforeStateHash",
+            "afterStateHash",
+            "prevEventHash",
+            "eventHash",
+        ];
+        const missingFields = requiredFields.filter((field) => !(field in parsed));
+        if (missingFields.length > 0) {
+            quarantine(lineNumber, `truncated or incomplete record — missing fields: ${missingFields.join(", ")}`);
+            continue;
+        }
+        if (typeof parsed.sequence !== "number" || !Number.isInteger(parsed.sequence) || parsed.sequence < 1) {
+            quarantine(lineNumber, "invalid sequence");
+            continue;
+        }
+        if (typeof parsed.eventHash !== "string" || !/^[a-f0-9]{64}$/.test(parsed.eventHash)) {
+            quarantine(lineNumber, "invalid eventHash");
+            continue;
+        }
+        if (typeof parsed.prevEventHash !== "string" && parsed.prevEventHash !== null) {
+            quarantine(lineNumber, "invalid prevEventHash");
+            continue;
+        }
+        if (typeof parsed.beforeStateHash !== "string") {
+            quarantine(lineNumber, "invalid beforeStateHash");
+            continue;
+        }
+        if (typeof parsed.afterStateHash !== "string") {
+            quarantine(lineNumber, "invalid afterStateHash");
+            continue;
+        }
+        if (typeof parsed.type !== "string") {
+            quarantine(lineNumber, "invalid type");
+            continue;
+        }
+        if (typeof parsed.reducerVersion !== "number" || !Number.isInteger(parsed.reducerVersion)) {
+            quarantine(lineNumber, "invalid reducerVersion");
+            continue;
+        }
+        const event = parsed;
+        const expectedSequence = events.length + 1;
+        if (event.sequence !== expectedSequence) {
+            quarantine(lineNumber, `sequence mismatch: expected ${expectedSequence}, got ${event.sequence}`);
+            continue;
+        }
+        const expectedHash = computeEventHash(stripEventHash(event));
+        if (event.eventHash !== expectedHash) {
+            quarantine(lineNumber, `eventHash mismatch at sequence ${event.sequence}`);
+            continue;
+        }
+        const previous = events.at(-1);
+        const expectedPrevHash = previous?.eventHash ?? null;
+        if (event.prevEventHash !== expectedPrevHash) {
+            quarantine(lineNumber, `prevEventHash mismatch at sequence ${event.sequence}`);
+            continue;
+        }
+        if (previous !== undefined && event.beforeStateHash !== previous.afterStateHash) {
+            quarantine(lineNumber, `beforeStateHash mismatch at sequence ${event.sequence}`);
+            continue;
+        }
+        events.push(event);
+    }
+    return { ok: errors.length === 0, events, errors, quarantinedLines };
+}
+export function canonicalizeBaseDir(baseDir) {
+    try {
+        return realpathSync(baseDir);
+    }
+    catch {
+        return path.resolve(baseDir);
+    }
+}
+// Filesystem-backed resolver that follows symlinks via realpath and uses lstat to
+// detect existence without following. Symlink escapes are caught downstream by
+// verifyArtifactReference's realpath containment check.
+export function createFsArtifactResolver(baseDir) {
+    return (artifactPath) => {
+        const resolved = path.resolve(baseDir, artifactPath);
+        try {
+            lstatSync(resolved);
+        }
+        catch {
+            return undefined;
+        }
+        let realPath;
+        try {
+            realPath = realpathSync(resolved);
+        }
+        catch {
+            return undefined;
+        }
+        let isFile = false;
+        try {
+            isFile = statSync(realPath).isFile();
+        }
+        catch {
+            return undefined;
+        }
+        return { realPath, isFile, sha256: isFile ? sha256File(realPath) : "" };
+    };
+}
+function sha256File(filePath) {
+    return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function stripEventHash(event) {
+    return {
+        sequence: event.sequence,
+        type: event.type,
+        reducerVersion: event.reducerVersion,
+        payload: event.payload,
+        beforeStateHash: event.beforeStateHash,
+        afterStateHash: event.afterStateHash,
+        prevEventHash: event.prevEventHash,
+    };
+}
+function eventToJson(event) {
+    return {
+        sequence: event.sequence,
+        type: event.type,
+        reducerVersion: event.reducerVersion,
+        payload: event.payload,
+        beforeStateHash: event.beforeStateHash,
+        afterStateHash: event.afterStateHash,
+        prevEventHash: event.prevEventHash,
+    };
+}
+function normalizePath(value) {
+    return path.resolve(value).replace(/\\/g, "/").replace(/\/$/, "");
+}
+function pathIsInside(root, candidate) {
+    const normalizedRoot = normalizePath(root);
+    const normalizedCandidate = normalizePath(candidate);
+    return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}/`);
+}
+//# sourceMappingURL=replay-ledger.js.map

package/dist/core/orchestration/replay-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-ledger.js","sourceRoot":"","sources":["../../../src/core/orchestration/replay-ledger.ts"],"names":[],"mappings":"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","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"]}

package/dist/core/orchestration/scheduler-state.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Pure scheduler state module for the durable DAG orchestrator.
+ *
+ * This module is intentionally free of I/O: it owns the node state machine,
+ * the read/write conflict model, the dispatchability predicate, and the
+ * deterministic dispatch selection. Persistence (SQLite WAL), leases, and
+ * dependency readiness live in sibling modules; this is the single source of
+ * truth for the *rules* those modules enforce.
+ *
+ * Erasable TypeScript only (no enum/namespace/parameter properties). All time
+ * values are epoch milliseconds so tests can use deterministic fake clocks.
+ */
+/** Lifecycle status of a DAG node (see foundation.md section 2.1). */
+export type SchedulerNodeStatus = "queued" | "leased" | "running" | "verifying" | "completed" | "retry_wait" | "compensating" | "rolled_back" | "in_doubt" | "blocked" | "cancelled" | "failed";
+/** A single resource touched by a node's read_set or write_set. */
+export interface AccessSetEntry {
+    /** Filesystem path. Equality is exact string match (no prefix containment here). */
+    path: string;
+    /** Optional symbol list for symbol-level conflict narrowing. */
+    symbols?: readonly string[];
+}
+/** A DAG node, narrowed to the fields the pure scheduler rules consume. */
+export interface SchedulerNode {
+    nodeId: string;
+    status: SchedulerNodeStatus;
+    /** Lower number dispatches sooner. */
+    priority: number;
+    /** false => must run alone (no siblings selected or in-flight alongside it). */
+    parallelizable: boolean;
+    readSet: readonly AccessSetEntry[];
+    writeSet: readonly AccessSetEntry[];
+    /** Epoch ms backoff deadline; consulted only when status === "retry_wait". */
+    retryWaitUntil?: number;
+    /** Upstream node ids. Not consulted by these pure functions (dependency readiness is external). */
+    dependsOn?: readonly string[];
+}
+/** Options driving a single dispatch selection pass. */
+export interface DispatchSelectionOptions {
+    /** Epoch ms "now"; used for retry_wait backoff comparison. */
+    now: number;
+    /** Total in-flight lease ceiling. Selection stops once in-flight + selected reaches this. */
+    maxLeases: number;
+    /** Optional per-tick cap on how many nodes may be selected. */
+    maxParallel?: number;
+    /** Nodes already leased/running/verifying, counted toward maxLeases and conflict checks. */
+    inFlight?: readonly SchedulerNode[];
+}
+/** True iff moving a node from `from` to `to` is a legal direct transition. */
+export declare function canTransitionNodeStatus(from: SchedulerNodeStatus, to: SchedulerNodeStatus): boolean;
+/**
+ * Two access entries conflict iff they reference the same path. When BOTH
+ * entries declare (non-empty) symbols, the conflict narrows to a shared symbol;
+ * otherwise the conflict is path-level (conservative).
+ */
+export declare function accessEntriesConflict(a: AccessSetEntry, b: AccessSetEntry): boolean;
+/**
+ * A candidate node conflicts with an in-flight node on write/write,
+ * write/read, or read/write overlap. read/read never conflicts.
+ */
+export declare function nodesConflict(candidate: SchedulerNode, inFlight: SchedulerNode): boolean;
+/**
+ * A node is dispatchable iff it is `queued`, or `retry_wait` whose backoff
+ * deadline has elapsed (retryWaitUntil <= now). Dependencies and leases are
+ * checked elsewhere; this predicate only answers the time/status question.
+ */
+export declare function isNodeDispatchable(node: SchedulerNode, now: number): boolean;
+/**
+ * Select dispatchable nodes for a single tick, deterministically.
+ *
+ * Ordering: priority ascending, then nodeId ascending. A candidate is excluded
+ * if it conflicts (write/write, write/read, read/write) with any in-flight node
+ * or any node already selected this tick. `parallelizable: false` nodes may be
+ * selected only when nothing is selected and nothing is in-flight, and once one
+ * is selected the tick stops (serialized lane). Selection stops once
+ * in-flight + selected reaches `maxLeases`, or `maxParallel` is hit.
+ */
+export declare function selectDispatchableNodes(nodes: readonly SchedulerNode[], options: DispatchSelectionOptions): SchedulerNode[];
+//# sourceMappingURL=scheduler-state.d.ts.map

package/dist/core/orchestration/scheduler-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-state.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/scheduler-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAC5B,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,WAAW,GACX,YAAY,GACZ,cAAc,GACd,aAAa,GACb,UAAU,GACV,SAAS,GACT,WAAW,GACX,QAAQ,CAAC;AAEZ,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC9B,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,mBAAmB,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mGAAmG;IACnG,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,wDAAwD;AACxD,MAAM,WAAW,wBAAwB;IACxC,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,6FAA6F;IAC7F,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACpC;AAyCD,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,mBAAmB,GAAG,OAAO,CAEnG;AAkBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAQnF;AAcD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAcxF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ5E;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,EAAE,wBAAwB,GAC/B,aAAa,EAAE,CAuCjB","sourcesContent":["/**\n * Pure scheduler state module for the durable DAG orchestrator.\n *\n * This module is intentionally free of I/O: it owns the node state machine,\n * the read/write conflict model, the dispatchability predicate, and the\n * deterministic dispatch selection. Persistence (SQLite WAL), leases, and\n * dependency readiness live in sibling modules; this is the single source of\n * truth for the *rules* those modules enforce.\n *\n * Erasable TypeScript only (no enum/namespace/parameter properties). All time\n * values are epoch milliseconds so tests can use deterministic fake clocks.\n */\n\n/** Lifecycle status of a DAG node (see foundation.md section 2.1). */\nexport type SchedulerNodeStatus =\n\t| \"queued\"\n\t| \"leased\"\n\t| \"running\"\n\t| \"verifying\"\n\t| \"completed\"\n\t| \"retry_wait\"\n\t| \"compensating\"\n\t| \"rolled_back\"\n\t| \"in_doubt\"\n\t| \"blocked\"\n\t| \"cancelled\"\n\t| \"failed\";\n\n/** A single resource touched by a node's read_set or write_set. */\nexport interface AccessSetEntry {\n\t/** Filesystem path. Equality is exact string match (no prefix containment here). */\n\tpath: string;\n\t/** Optional symbol list for symbol-level conflict narrowing. */\n\tsymbols?: readonly string[];\n}\n\n/** A DAG node, narrowed to the fields the pure scheduler rules consume. */\nexport interface SchedulerNode {\n\tnodeId: string;\n\tstatus: SchedulerNodeStatus;\n\t/** Lower number dispatches sooner. */\n\tpriority: number;\n\t/** false => must run alone (no siblings selected or in-flight alongside it). */\n\tparallelizable: boolean;\n\treadSet: readonly AccessSetEntry[];\n\twriteSet: readonly AccessSetEntry[];\n\t/** Epoch ms backoff deadline; consulted only when status === \"retry_wait\". */\n\tretryWaitUntil?: number;\n\t/** Upstream node ids. Not consulted by these pure functions (dependency readiness is external). */\n\tdependsOn?: readonly string[];\n}\n\n/** Options driving a single dispatch selection pass. */\nexport interface DispatchSelectionOptions {\n\t/** Epoch ms \"now\"; used for retry_wait backoff comparison. */\n\tnow: number;\n\t/** Total in-flight lease ceiling. Selection stops once in-flight + selected reaches this. */\n\tmaxLeases: number;\n\t/** Optional per-tick cap on how many nodes may be selected. */\n\tmaxParallel?: number;\n\t/** Nodes already leased/running/verifying, counted toward maxLeases and conflict checks. */\n\tinFlight?: readonly SchedulerNode[];\n}\n\n/**\n * Legal direct transitions, derived from foundation.md section 2.2.\n *\n * Terminal statuses (completed, failed, blocked, cancelled, rolled_back,\n * in_doubt) map to the empty set: once terminal, a node never moves again.\n * block/cancel are legal from every non-terminal status (\"any -> block\",\n * \"any except terminal -> cancel\"). running -> running encodes the heartbeat\n * self-update.\n */\nconst ALLOWED_TRANSITIONS: Readonly<Record<SchedulerNodeStatus, ReadonlySet<SchedulerNodeStatus>>> = {\n\tqueued: new Set<SchedulerNodeStatus>([\"leased\", \"blocked\", \"cancelled\"]),\n\tleased: new Set<SchedulerNodeStatus>([\"queued\", \"running\", \"blocked\", \"cancelled\"]),\n\trunning: new Set<SchedulerNodeStatus>([\n\t\t\"running\",\n\t\t\"verifying\",\n\t\t\"retry_wait\",\n\t\t\"failed\",\n\t\t\"compensating\",\n\t\t\"blocked\",\n\t\t\"cancelled\",\n\t]),\n\tverifying: new Set<SchedulerNodeStatus>([\n\t\t\"completed\",\n\t\t\"retry_wait\",\n\t\t\"failed\",\n\t\t\"compensating\",\n\t\t\"blocked\",\n\t\t\"cancelled\",\n\t]),\n\tcompleted: new Set<SchedulerNodeStatus>(),\n\tretry_wait: new Set<SchedulerNodeStatus>([\"queued\", \"blocked\", \"cancelled\"]),\n\tcompensating: new Set<SchedulerNodeStatus>([\"rolled_back\", \"in_doubt\", \"blocked\", \"cancelled\"]),\n\trolled_back: new Set<SchedulerNodeStatus>(),\n\tin_doubt: new Set<SchedulerNodeStatus>(),\n\tblocked: new Set<SchedulerNodeStatus>(),\n\tcancelled: new Set<SchedulerNodeStatus>(),\n\tfailed: new Set<SchedulerNodeStatus>(),\n};\n\n/** True iff moving a node from `from` to `to` is a legal direct transition. */\nexport function canTransitionNodeStatus(from: SchedulerNodeStatus, to: SchedulerNodeStatus): boolean {\n\treturn ALLOWED_TRANSITIONS[from].has(to);\n}\n\n/** True iff the entry narrows on at least one symbol (empty list counts as no narrowing). */\nfunction declaresSymbols(entry: AccessSetEntry): boolean {\n\treturn Array.isArray(entry.symbols) && entry.symbols.length > 0;\n}\n\n/** True iff two non-empty symbol lists share at least one symbol. */\nfunction sharesSymbol(a: readonly string[], b: readonly string[]): boolean {\n\tconst seen = new Set(a);\n\tfor (const symbol of b) {\n\t\tif (seen.has(symbol)) {\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n\n/**\n * Two access entries conflict iff they reference the same path. When BOTH\n * entries declare (non-empty) symbols, the conflict narrows to a shared symbol;\n * otherwise the conflict is path-level (conservative).\n */\nexport function accessEntriesConflict(a: AccessSetEntry, b: AccessSetEntry): boolean {\n\tif (a.path !== b.path) {\n\t\treturn false;\n\t}\n\tif (declaresSymbols(a) && declaresSymbols(b)) {\n\t\treturn sharesSymbol(a.symbols as readonly string[], b.symbols as readonly string[]);\n\t}\n\treturn true;\n}\n\n/** True iff any entry in `left` conflicts with any entry in `right`. */\nfunction setsOverlap(left: readonly AccessSetEntry[], right: readonly AccessSetEntry[]): boolean {\n\tfor (const l of left) {\n\t\tfor (const r of right) {\n\t\t\tif (accessEntriesConflict(l, r)) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t}\n\t}\n\treturn false;\n}\n\n/**\n * A candidate node conflicts with an in-flight node on write/write,\n * write/read, or read/write overlap. read/read never conflicts.\n */\nexport function nodesConflict(candidate: SchedulerNode, inFlight: SchedulerNode): boolean {\n\t// write/write\n\tif (setsOverlap(candidate.writeSet, inFlight.writeSet)) {\n\t\treturn true;\n\t}\n\t// write/read: candidate writes what in-flight reads\n\tif (setsOverlap(candidate.writeSet, inFlight.readSet)) {\n\t\treturn true;\n\t}\n\t// read/write: candidate reads what in-flight writes\n\tif (setsOverlap(candidate.readSet, inFlight.writeSet)) {\n\t\treturn true;\n\t}\n\treturn false;\n}\n\n/**\n * A node is dispatchable iff it is `queued`, or `retry_wait` whose backoff\n * deadline has elapsed (retryWaitUntil <= now). Dependencies and leases are\n * checked elsewhere; this predicate only answers the time/status question.\n */\nexport function isNodeDispatchable(node: SchedulerNode, now: number): boolean {\n\tif (node.status === \"queued\") {\n\t\treturn true;\n\t}\n\tif (node.status === \"retry_wait\") {\n\t\treturn node.retryWaitUntil !== undefined && node.retryWaitUntil <= now;\n\t}\n\treturn false;\n}\n\n/** Deterministic ordering: priority ascending, then nodeId ascending. */\nfunction compareDispatchOrder(a: SchedulerNode, b: SchedulerNode): number {\n\tif (a.priority !== b.priority) {\n\t\treturn a.priority - b.priority;\n\t}\n\tif (a.nodeId < b.nodeId) {\n\t\treturn -1;\n\t}\n\tif (a.nodeId > b.nodeId) {\n\t\treturn 1;\n\t}\n\treturn 0;\n}\n\n/**\n * Select dispatchable nodes for a single tick, deterministically.\n *\n * Ordering: priority ascending, then nodeId ascending. A candidate is excluded\n * if it conflicts (write/write, write/read, read/write) with any in-flight node\n * or any node already selected this tick. `parallelizable: false` nodes may be\n * selected only when nothing is selected and nothing is in-flight, and once one\n * is selected the tick stops (serialized lane). Selection stops once\n * in-flight + selected reaches `maxLeases`, or `maxParallel` is hit.\n */\nexport function selectDispatchableNodes(\n\tnodes: readonly SchedulerNode[],\n\toptions: DispatchSelectionOptions,\n): SchedulerNode[] {\n\tconst inFlight = options.inFlight ?? [];\n\tconst maxParallel = options.maxParallel ?? Number.POSITIVE_INFINITY;\n\n\t// Remaining lease headroom after accounting for in-flight occupancy.\n\tconst remaining = Math.max(0, options.maxLeases - inFlight.length);\n\tif (remaining === 0) {\n\t\treturn [];\n\t}\n\n\tconst candidates = nodes.filter((node) => isNodeDispatchable(node, options.now));\n\tconst ordered = [...candidates].sort(compareDispatchOrder);\n\n\tconst selected: SchedulerNode[] = [];\n\tfor (const candidate of ordered) {\n\t\tif (selected.length >= remaining || selected.length >= maxParallel) {\n\t\t\tbreak;\n\t\t}\n\t\t// Serialized lane: a non-parallelizable node needs the lane to itself.\n\t\tif (!candidate.parallelizable) {\n\t\t\tif (selected.length > 0 || inFlight.length > 0) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\t// Exclude candidates that conflict with anything already in flight or chosen.\n\t\tconst conflictsWithBusy =\n\t\t\tinFlight.some((busy) => nodesConflict(candidate, busy)) ||\n\t\t\tselected.some((chosen) => nodesConflict(candidate, chosen));\n\t\tif (conflictsWithBusy) {\n\t\t\tcontinue;\n\t\t}\n\t\tselected.push(candidate);\n\t\t// A non-parallelizable node claims the whole lane for this tick.\n\t\tif (!candidate.parallelizable) {\n\t\t\tbreak;\n\t\t}\n\t}\n\n\treturn selected;\n}\n"]}