@sema-agent/core 5.45.0 → 5.47.0

package/dist/core/memory-engine/delegation-settlement.js

@@ -0,0 +1,661 @@
+import { createHash } from "node:crypto";
+import { existsSync, linkSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { QUARANTINE_DIR, appendChallengeEvents, enqueueMemoryAnnouncement, ensureDirExists, lineageContributionsOfSession, lockedStrictUpdate, markSessionPolluted, readSessionPollution, readStrictSidecar, ControlPlaneCorruptError } from "./layout.js";
+export const DELEGATION_SETTLEMENT_FILE = "delegation-settlement.json";
+function reqStr(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function safeBasename(v) {
+    return typeof v === "string" && v.length > 0 && !v.includes("/") && !v.includes("\\") && v !== "." && v !== "..";
+}
+function safeRelPath(v) {
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("/") || v.startsWith("\\") || /^[A-Za-z]:/.test(v))
+        return false;
+    return v.split(/[\/\\]/).every((seg) => seg.length > 0 && seg !== "." && seg !== "..");
+}
+const SETTLEMENT_EVENT_STATUSES = new Set(["clean", "external", "expired", "void", "unattestable"]);
+function coerceSettlement(raw) {
+    if (raw === undefined)
+        return { version: 1, rows: [], events: [], effects: {} };
+    const rec = raw;
+    if (typeof rec !== "object" || rec === null || !Array.isArray(rec.rows) || !Array.isArray(rec.events) || typeof rec.effects !== "object" || rec.effects === null || Array.isArray(rec.effects)) {
+        throw new ControlPlaneCorruptError("memory delegation-settlement ledger has the wrong shape");
+    }
+    if (rec.version !== 1)
+        throw new ControlPlaneCorruptError(`memory delegation-settlement ledger has an unrecognized version (${String(rec.version)}) — refusing (fail-closed)`);
+    for (const r of rec.rows) {
+        const row = r;
+        if (typeof row !== "object" || row === null || !reqStr(row.settleId) || !reqStr(row.sessionId) || typeof row.launchedAt !== "number" || !Number.isFinite(row.launchedAt) || (row.lane !== "background" && row.lane !== "sync") || (row.status !== "pending" && row.status !== "unattestable") || (row.toolUseId !== undefined && !reqStr(row.toolUseId))) {
+            throw new ControlPlaneCorruptError("memory delegation-settlement ledger: a row is malformed (unknown status/lane, missing id, or a non-finite timestamp) — refusing (fail-closed; an unevaluable row must not fold as clean)");
+        }
+    }
+    for (const e of rec.events) {
+        const ev = e;
+        const kindOk = ev?.kind === "settle" || ev?.kind === "admin-resolve" || ev?.kind === "annotation";
+        const statusOk = ev?.status === undefined || SETTLEMENT_EVENT_STATUSES.has(ev.status);
+        if (typeof ev !== "object" || ev === null || !reqStr(ev.settleId) || !reqStr(ev.eventId) || typeof ev.at !== "number" || !Number.isFinite(ev.at) || !kindOk || !statusOk || (ev.kind === "settle" && ev.status === undefined) || (ev.kind === "admin-resolve" && (ev.status === undefined || !reqStr(ev.requestId)))) {
+            throw new ControlPlaneCorruptError("memory delegation-settlement ledger: an event is malformed (unknown kind/status, missing ids, an unattributed admin ruling, or a non-finite timestamp) — refusing (fail-closed)");
+        }
+    }
+    for (const [k, v] of Object.entries(rec.effects)) {
+        if (!reqStr(k) || !reqStr(v))
+            throw new ControlPlaneCorruptError("memory delegation-settlement ledger: an effects watermark entry is malformed — refusing (fail-closed)");
+    }
+    return rec;
+}
+export function syncSettleId(sessionId, toolCallId) {
+    return `sync:${encodeURIComponent(sessionId)}:${encodeURIComponent(toolCallId)}`;
+}
+export function registerDelegationLaunch(controlDir, input) {
+    lockedStrictUpdate(controlDir, DELEGATION_SETTLEMENT_FILE, "memory delegation-settlement ledger", coerceSettlement, (rec) => {
+        if (rec.rows.some((r) => r.settleId === input.settleId))
+            return { result: undefined };
+        rec.rows.push({ settleId: input.settleId, sessionId: input.sessionId, launchedAt: input.now(), lane: "background", status: "pending", ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}) });
+        return { next: rec, result: undefined };
+    });
+}
+export function recordSyncUnattestable(controlDir, input) {
+    const settleId = syncSettleId(input.sessionId, input.toolCallId);
+    lockedStrictUpdate(controlDir, DELEGATION_SETTLEMENT_FILE, "memory delegation-settlement ledger", coerceSettlement, (rec) => {
+        if (rec.rows.some((r) => r.settleId === settleId))
+            return { result: undefined };
+        rec.rows.push({ settleId, sessionId: input.sessionId, launchedAt: input.now(), lane: "sync", status: "unattestable" });
+        return { next: rec, result: undefined };
+    });
+}
+export function settleDelegation(controlDir, input) {
+    const eventId = input.eventId ?? `settle:${input.settleId}:${input.status}`;
+    lockedStrictUpdate(controlDir, DELEGATION_SETTLEMENT_FILE, "memory delegation-settlement ledger", coerceSettlement, (rec) => {
+        if (rec.events.some((e) => e.eventId === eventId))
+            return { result: undefined };
+        rec.events.push({ settleId: input.settleId, eventId, at: input.now(), kind: "settle", status: input.status, ...(input.note !== undefined ? { note: input.note } : {}) });
+        return { next: rec, result: undefined };
+    });
+}
+export function resolveSettlementRecord(controlDir, input) {
+    if (typeof input.requestId !== "string" || input.requestId.length === 0) {
+        const e = new Error("resolveSettlement requires a non-empty requestId (the audit attribution of who resolved) — refused, never defaulted.");
+        e.code = "memory.settlement_resolve_unattributed";
+        throw e;
+    }
+    if (input.to !== "clean" && input.to !== "external") {
+        const e = new Error(`resolveSettlement verdict must be "clean" or "external" (got ${JSON.stringify(input.to)}) — refused loudly, never folded.`);
+        e.code = "memory.settlement_resolve_invalid";
+        throw e;
+    }
+    const eventId = `admin:${input.requestId}:${input.settleId}:${input.to}`;
+    lockedStrictUpdate(controlDir, DELEGATION_SETTLEMENT_FILE, "memory delegation-settlement ledger", coerceSettlement, (rec) => {
+        if (!rec.rows.some((r) => r.settleId === input.settleId)) {
+            const e = new Error(`resolveSettlement: unknown settleId ${JSON.stringify(input.settleId)}`);
+            e.code = "memory.settlement_resolve_unknown";
+            throw e;
+        }
+        if (rec.events.some((e2) => e2.eventId === eventId))
+            return { result: undefined };
+        rec.events.push({ settleId: input.settleId, eventId, at: input.now(), kind: "admin-resolve", status: input.to, requestId: input.requestId });
+        return { next: rec, result: undefined };
+    });
+}
+function foldOne(row, events) {
+    let effective = row.status;
+    let everExternal = false;
+    let terminalEventId;
+    let adminRuled = false;
+    for (const e of events) {
+        const s = e.status;
+        if (s === undefined)
+            continue;
+        if (e.kind === "settle") {
+            if (s === "external") {
+                everExternal = true;
+                if (effective !== "external" && (effective !== "clean" || adminRuled)) {
+                    effective = "external";
+                    terminalEventId = e.eventId;
+                }
+            }
+            else if (s === "clean" || s === "void") {
+                if (effective === "pending") {
+                    effective = s;
+                    terminalEventId = e.eventId;
+                }
+            }
+            else if (s === "expired" || s === "unattestable") {
+                if (effective === "pending") {
+                    effective = s;
+                    terminalEventId = e.eventId;
+                }
+            }
+        }
+        else if (e.kind === "admin-resolve") {
+            adminRuled = true;
+            if (s === "external") {
+                everExternal = true;
+                effective = "external";
+                terminalEventId = e.eventId;
+            }
+            else if (s === "clean") {
+                effective = "clean";
+                terminalEventId = e.eventId;
+            }
+        }
+    }
+    return { row, effective, everExternal, ...(terminalEventId !== undefined ? { terminalEventId } : {}) };
+}
+export function effectiveSettlements(controlDir) {
+    const rec = coerceSettlement(readStrictSidecar(controlDir, DELEGATION_SETTLEMENT_FILE, "memory delegation-settlement ledger"));
+    const bySettle = new Map();
+    for (const e of rec.events) {
+        const arr = bySettle.get(e.settleId);
+        if (arr === undefined)
+            bySettle.set(e.settleId, [e]);
+        else
+            arr.push(e);
+    }
+    return rec.rows.map((row) => foldOne(row, bySettle.get(row.settleId) ?? []));
+}
+export function sessionSettlements(controlDir, sessionId) {
+    return effectiveSettlements(controlDir).filter((s) => s.row.sessionId === sessionId);
+}
+export function classifySessionSettlements(rows) {
+    let sawPending = false;
+    let exposedCause;
+    let reason;
+    for (const s of rows) {
+        if (s.effective === "external") {
+            exposedCause = "observed";
+            reason = "a delegated child of this session settled with an observed external-content attestation";
+            break;
+        }
+        if (s.effective === "unattestable" || s.effective === "expired") {
+            if (exposedCause === undefined) {
+                exposedCause = "static";
+                reason = s.effective === "unattestable" ? "a delegation of this session delivered without a provable attestation (permanently unprovable is not clean)" : "a delegation of this session never settled inside its evidence window (expired unprovable is not clean)";
+            }
+            continue;
+        }
+        if (s.effective === "pending")
+            sawPending = true;
+    }
+    if (exposedCause !== undefined)
+        return { state: "exposed", cause: exposedCause, ...(reason !== undefined ? { reason } : {}) };
+    if (sawPending)
+        return { state: "pending" };
+    return { state: "clean" };
+}
+export function expireOverdueSettlements(controlDir, input) {
+    const overdue = effectiveSettlements(controlDir).filter((s) => s.effective === "pending" && input.now() - s.row.launchedAt > input.timeoutMs);
+    for (const s of overdue)
+        settleDelegation(controlDir, { settleId: s.row.settleId, status: "expired", now: input.now });
+    return overdue.map((s) => s.row.settleId);
+}
+export function replayExternalSettlementEffects(controlDir, input) {
+    const applied = [];
+    const folded = effectiveSettlements(controlDir).filter((s) => s.effective === "external" && s.terminalEventId !== undefined);
+    if (folded.length === 0)
+        return applied;
+    const rec = coerceSettlement(readStrictSidecar(controlDir, DELEGATION_SETTLEMENT_FILE, "memory delegation-settlement ledger"));
+    for (const s of folded) {
+        if (rec.effects[s.row.settleId] === s.terminalEventId)
+            continue;
+        const sessionId = s.row.sessionId;
+        const outcome = markSessionPolluted(controlDir, sessionId, "a delegated child of this session settled external after launch (delegation settlement account)", input.now, "observed");
+        if (outcome === "unpersisted")
+            continue;
+        try {
+            const swept = lineageContributionsOfSession(controlDir, sessionId);
+            const contributions = input.carry ? swept.filter((c) => c.marked !== true) : swept;
+            appendChallengeEvents(controlDir, contributions.map((c) => ({
+                eventId: `settlement:${s.row.settleId}:${s.terminalEventId}:${c.entryId}`,
+                entryId: c.entryId,
+                reason: "challenged: the contributing session's delegation settled external",
+                challengedRev: c.lastRev,
+            })), input.now);
+        }
+        catch {
+            continue;
+        }
+        try {
+            enqueueMemoryAnnouncement(controlDir, {
+                kind: "gate",
+                at: input.now(),
+                items: [`delegation settlement: a background delegation of session ${JSON.stringify(sessionId)} settled EXTERNAL after launch — the session is marked and its unmarked committed contributions are challenged`],
+            });
+        }
+        catch {
+        }
+        lockedStrictUpdate(controlDir, DELEGATION_SETTLEMENT_FILE, "memory delegation-settlement ledger", coerceSettlement, (r) => {
+            r.effects[s.row.settleId] = s.terminalEventId;
+            return { next: r, result: undefined };
+        });
+        applied.push({ settleId: s.row.settleId, sessionId });
+    }
+    return applied;
+}
+export const SESSION_ACCOUNTS_FILE = "session-accounts.json";
+function coerceSessionAccounts(raw) {
+    if (raw === undefined)
+        return { version: 1, rows: [] };
+    const rec = raw;
+    if (typeof rec !== "object" || rec === null || !Array.isArray(rec.rows))
+        throw new ControlPlaneCorruptError("memory session-account ledger has the wrong shape");
+    if (rec.version !== 1)
+        throw new ControlPlaneCorruptError(`memory session-account ledger has an unrecognized version (${String(rec.version)}) — refusing (fail-closed)`);
+    for (const r of rec.rows) {
+        const row = r;
+        if (typeof row !== "object" ||
+            row === null ||
+            !reqStr(row.sessionId) ||
+            typeof row.openedAt !== "number" ||
+            !Number.isFinite(row.openedAt) ||
+            !Array.isArray(row.unattributed) ||
+            row.unattributed.some((x) => typeof x !== "string") ||
+            (row.closedAt !== undefined && (typeof row.closedAt !== "number" || !Number.isFinite(row.closedAt))) ||
+            (row.unadjudicated !== undefined && row.unadjudicated !== true)) {
+            throw new ControlPlaneCorruptError("memory session-account ledger: a row is malformed — refusing (fail-closed; an unevaluable row must not read as adjudicated)");
+        }
+    }
+    return rec;
+}
+export function foreignDanglingSessionAccounts(controlDir, selfSessionId) {
+    const rec = coerceSessionAccounts(readStrictSidecar(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger"));
+    return rec.rows.filter((r) => r.sessionId !== selfSessionId && (r.closedAt === undefined || r.unadjudicated === true));
+}
+export function openSessionAccount(controlDir, input) {
+    lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (rec) => {
+        const row = rec.rows.find((r) => r.sessionId === input.sessionId);
+        if (row === undefined) {
+            rec.rows.push({ sessionId: input.sessionId, openedAt: input.now(), unattributed: [...input.unattributed] });
+        }
+        else if (row.closedAt !== undefined && row.unadjudicated === undefined) {
+            row.openedAt = input.now();
+            delete row.closedAt;
+            row.unattributed = [...input.unattributed];
+        }
+        else {
+            row.openedAt = input.now();
+            delete row.closedAt;
+            delete row.unadjudicated;
+            row.unattributed = [...new Set([...row.unattributed, ...input.unattributed])];
+        }
+        return { next: rec, result: undefined };
+    });
+}
+export function sessionUnattributedSet(controlDir, sessionId) {
+    const rec = coerceSessionAccounts(readStrictSidecar(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger"));
+    return new Set(rec.rows.find((r) => r.sessionId === sessionId)?.unattributed ?? []);
+}
+export function closeSessionAccount(controlDir, input) {
+    lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (rec) => {
+        const row = rec.rows.find((r) => r.sessionId === input.sessionId);
+        if (row === undefined)
+            return { result: undefined };
+        row.closedAt = input.now();
+        delete row.unadjudicated;
+        for (const r of rec.rows)
+            delete r.unadjudicated;
+        return { next: rec, result: undefined };
+    });
+}
+export function resolveSessionAccountRecord(controlDir, input) {
+    if (typeof input.requestId !== "string" || input.requestId.length === 0) {
+        const e = new Error("resolveSessionAccount requires a non-empty requestId (the audit attribution of who closed) — refused, never defaulted.");
+        e.code = "memory.session_account_resolve_unattributed";
+        throw e;
+    }
+    lockedStrictUpdate(controlDir, SESSION_ACCOUNTS_FILE, "memory session-account ledger", coerceSessionAccounts, (rec) => {
+        const row = rec.rows.find((r) => r.sessionId === input.sessionId);
+        if (row === undefined) {
+            const e = new Error(`resolveSessionAccount: unknown sessionId ${JSON.stringify(input.sessionId)}`);
+            e.code = "memory.session_account_resolve_unknown";
+            throw e;
+        }
+        row.closedAt = input.now();
+        row.unadjudicated = true;
+        return { next: rec, result: undefined };
+    });
+}
+export const HOLDS_FILE = "holds.json";
+export const HOLD_DIR = "hold";
+const HOLD_STATUSES = new Set(["capturing", "held", "released", "disposed"]);
+const HOLD_TERMINALS = new Set(["dirty", "expired", "conflict", "discarded", "capture_lost"]);
+function coerceHolds(raw) {
+    if (raw === undefined)
+        return { version: 1, rows: [] };
+    const rec = raw;
+    if (typeof rec !== "object" || rec === null || !Array.isArray(rec.rows))
+        throw new ControlPlaneCorruptError("memory instruction-hold ledger has the wrong shape");
+    if (rec.version !== 1)
+        throw new ControlPlaneCorruptError(`memory instruction-hold ledger has an unrecognized version (${String(rec.version)}) — refusing (fail-closed)`);
+    for (const r of rec.rows) {
+        const row = r;
+        if (typeof row !== "object" ||
+            row === null ||
+            !reqStr(row.holdId) ||
+            !reqStr(row.sessionId) ||
+            (row.op !== "add" && row.op !== "update") ||
+            !reqStr(row.relPath) ||
+            !reqStr(row.slug) ||
+            !reqStr(row.scope) ||
+            !reqStr(row.captureName) ||
+            !reqStr(row.contentDigest) ||
+            typeof row.capturedAt !== "number" ||
+            !Number.isFinite(row.capturedAt) ||
+            !Array.isArray(row.settleIds) ||
+            row.settleIds.some((x) => typeof x !== "string") ||
+            !HOLD_STATUSES.has(row.status) ||
+            (row.disposition !== undefined && (typeof row.disposition !== "object" || row.disposition === null || !HOLD_TERMINALS.has(row.disposition.terminal) || (row.disposition.quarantineName !== undefined && !safeBasename(row.disposition.quarantineName)))) ||
+            (row.resolved !== undefined && row.resolved !== "release" && row.resolved !== "discard") ||
+            (row.entryId !== undefined && typeof row.entryId !== "string") ||
+            (row.baseRev !== undefined && typeof row.baseRev !== "string") ||
+            (row.op === "update" && (!reqStr(row.entryId) || !reqStr(row.baseRev))) ||
+            !safeRelPath(row.relPath) ||
+            !safeBasename(row.captureName)) {
+            throw new ControlPlaneCorruptError("memory instruction-hold ledger: a row is malformed — refusing (fail-closed; an unevaluable hold must not read as settled)");
+        }
+    }
+    return rec;
+}
+export function readHolds(controlDir) {
+    return coerceHolds(readStrictSidecar(controlDir, HOLDS_FILE, "memory instruction-hold ledger")).rows;
+}
+function sha256(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
+let stagingSeq = 0;
+function uniqueStagingName(holdId, now) {
+    stagingSeq += 1;
+    return `${holdId}.staging-${now()}-${process.pid}-${stagingSeq}`;
+}
+export function noReplaceRestore(stagingPath, destPath) {
+    try {
+        linkSync(stagingPath, destPath);
+    }
+    catch (err) {
+        if (err.code !== "EEXIST") {
+            try {
+                writeFileSync(destPath, readFileSync(stagingPath), { flag: "wx" });
+            }
+            catch (err2) {
+                return err2.code === "EEXIST" ? "kept" : "stranded";
+            }
+            try {
+                unlinkSync(stagingPath);
+            }
+            catch {
+            }
+            return "restored";
+        }
+        return "kept";
+    }
+    try {
+        unlinkSync(stagingPath);
+    }
+    catch {
+    }
+    return "restored";
+}
+export function openInstructionHold(controlDir, input) {
+    const holdId = `hold-${input.now()}-${createHash("sha256").update(`${input.sessionId}\n${input.relPath}\n${input.content}`).digest("hex").slice(0, 12)}`;
+    const buf = Buffer.from(input.content, "utf8");
+    const digest = sha256(buf);
+    const captureName = `${holdId}.md`;
+    const holdDir = join(controlDir, HOLD_DIR);
+    try {
+        lockedStrictUpdate(controlDir, HOLDS_FILE, "memory instruction-hold ledger", coerceHolds, (rec) => {
+            if (rec.rows.some((r) => r.holdId === holdId))
+                return { result: undefined };
+            rec.rows.push({
+                holdId,
+                sessionId: input.sessionId,
+                ...(input.entryId !== undefined ? { entryId: input.entryId } : {}),
+                op: input.op,
+                ...(input.baseRev !== undefined ? { baseRev: input.baseRev } : {}),
+                relPath: input.relPath,
+                slug: input.slug,
+                scope: input.scope,
+                captureName,
+                contentDigest: digest,
+                capturedAt: input.now(),
+                settleIds: [...input.settleIds],
+                status: "capturing",
+            });
+            return { next: rec, result: undefined };
+        });
+    }
+    catch (err) {
+        return { ok: false, reason: `hold ledger refused: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    try {
+        ensureDirExists(holdDir);
+        writeFileSync(join(holdDir, captureName), buf, { flag: "wx" });
+        const back = readFileSync(join(holdDir, captureName));
+        if (sha256(back) !== digest)
+            return { ok: false, holdId, reason: "hold capture verification failed (written bytes do not hash to the captured digest)" };
+    }
+    catch (err) {
+        return { ok: false, holdId, reason: `hold capture failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const stagingName = uniqueStagingName(holdId, input.now);
+    const stagingPath = join(holdDir, stagingName);
+    let thirdWriterStranded;
+    try {
+        renameSync(input.absPath, stagingPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+        }
+        else {
+            return { ok: false, holdId, reason: `hold removal failed (${code ?? "rename error"}): the plane file was not moved` };
+        }
+    }
+    if (existsSync(stagingPath)) {
+        const moved = readFileSync(stagingPath);
+        if (sha256(moved) === digest) {
+            try {
+                unlinkSync(stagingPath);
+            }
+            catch {
+            }
+        }
+        else {
+            if (noReplaceRestore(stagingPath, input.absPath) === "stranded") {
+                thirdWriterStranded = stagingName;
+            }
+        }
+    }
+    try {
+        lockedStrictUpdate(controlDir, HOLDS_FILE, "memory instruction-hold ledger", coerceHolds, (rec) => {
+            const row = rec.rows.find((r) => r.holdId === holdId);
+            if (row === undefined || row.status !== "capturing")
+                return { result: undefined };
+            row.status = "held";
+            return { next: rec, result: undefined };
+        });
+    }
+    catch (err) {
+        return { ok: false, holdId, reason: `hold ledger flip refused: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    return { ok: true, holdId, ...(thirdWriterStranded !== undefined ? { thirdWriterStranded } : {}) };
+}
+export function reconcileHolds(controlDir, input) {
+    const holdDir = join(controlDir, HOLD_DIR);
+    const discloseStranded = (holdId, relPath, stagingName) => {
+        try {
+            enqueueMemoryAnnouncement(controlDir, {
+                kind: "gate",
+                at: input.now(),
+                items: [`instruction hold ${holdId}: a concurrent writer's bytes for ${JSON.stringify(relPath)} could not be restored onto the plane — they are preserved at hold/${stagingName} in the memory control plane for host recovery`],
+            });
+        }
+        catch {
+            console.warn(`[sema] instruction hold ${holdId}: concurrent-writer bytes preserved at hold/${stagingName} could not be restored or announced`);
+        }
+    };
+    const rows = readHolds(controlDir).filter((r) => r.status === "capturing");
+    for (const row of rows) {
+        const custody = join(holdDir, row.captureName);
+        let terminalLost = false;
+        if (existsSync(custody)) {
+            const bytes = readFileSync(custody);
+            if (sha256(bytes) !== row.contentDigest) {
+                terminalLost = true;
+            }
+            else {
+                const plane = join(input.memoryDir, row.relPath);
+                if (existsSync(plane)) {
+                    try {
+                        const stagingName = uniqueStagingName(row.holdId, input.now);
+                        const staging = join(holdDir, stagingName);
+                        renameSync(plane, staging);
+                        if (sha256(readFileSync(staging)) === row.contentDigest) {
+                            unlinkSync(staging);
+                        }
+                        else if (noReplaceRestore(staging, plane) === "stranded") {
+                            discloseStranded(row.holdId, row.relPath, stagingName);
+                        }
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
+        else {
+            const plane = join(input.memoryDir, row.relPath);
+            if (existsSync(plane)) {
+                const bytes = readFileSync(plane);
+                if (sha256(bytes) === row.contentDigest) {
+                    try {
+                        ensureDirExists(holdDir);
+                        writeFileSync(custody, bytes, { flag: "wx" });
+                        const stagingName = uniqueStagingName(row.holdId, input.now);
+                        const staging = join(holdDir, stagingName);
+                        renameSync(plane, staging);
+                        if (sha256(readFileSync(staging)) === row.contentDigest) {
+                            try {
+                                unlinkSync(staging);
+                            }
+                            catch {
+                            }
+                        }
+                        else if (noReplaceRestore(staging, plane) === "stranded") {
+                            discloseStranded(row.holdId, row.relPath, stagingName);
+                        }
+                    }
+                    catch {
+                        terminalLost = true;
+                    }
+                }
+                else {
+                    terminalLost = true;
+                }
+            }
+            else {
+                terminalLost = true;
+            }
+        }
+        lockedStrictUpdate(controlDir, HOLDS_FILE, "memory instruction-hold ledger", coerceHolds, (rec) => {
+            const r = rec.rows.find((x) => x.holdId === row.holdId);
+            if (r === undefined || r.status !== "capturing")
+                return { result: undefined };
+            if (terminalLost) {
+                r.status = "disposed";
+                r.disposition = { terminal: "capture_lost" };
+            }
+            else {
+                r.status = "held";
+            }
+            return { next: rec, result: undefined };
+        });
+    }
+}
+export function disposeHold(controlDir, input) {
+    const rows = readHolds(controlDir);
+    const row = rows.find((r) => r.holdId === input.holdId);
+    if (row === undefined || row.status === "disposed" || row.status === "released")
+        return { ok: false };
+    const custody = join(controlDir, HOLD_DIR, row.captureName);
+    const quarantineName = `${input.now()}-hold-${row.captureName}`;
+    const qDir = join(controlDir, QUARANTINE_DIR);
+    let moved = false;
+    try {
+        ensureDirExists(qDir);
+        renameSync(custody, join(qDir, quarantineName));
+        moved = true;
+    }
+    catch {
+        moved = existsSync(join(qDir, quarantineName));
+    }
+    lockedStrictUpdate(controlDir, HOLDS_FILE, "memory instruction-hold ledger", coerceHolds, (rec) => {
+        const r = rec.rows.find((x) => x.holdId === input.holdId);
+        if (r === undefined || r.status === "disposed" || r.status === "released")
+            return { result: undefined };
+        r.status = "disposed";
+        r.disposition = { terminal: input.terminal, ...(moved ? { quarantineName } : {}) };
+        return { next: rec, result: undefined };
+    });
+    return { ok: true, ...(moved ? { quarantineName } : {}) };
+}
+export function markHoldReleased(controlDir, input) {
+    const captureName = lockedStrictUpdate(controlDir, HOLDS_FILE, "memory instruction-hold ledger", coerceHolds, (rec) => {
+        const r = rec.rows.find((x) => x.holdId === input.holdId);
+        if (r === undefined || (r.status !== "held" && !(r.status === "disposed" && r.disposition?.terminal === "expired")))
+            return { result: undefined };
+        r.status = "released";
+        delete r.resolved;
+        return { next: rec, result: r.captureName };
+    });
+    if (captureName === undefined)
+        return;
+    try {
+        unlinkSync(join(controlDir, HOLD_DIR, captureName));
+    }
+    catch {
+    }
+}
+export function resolveHoldRecord(controlDir, input) {
+    if (typeof input.requestId !== "string" || input.requestId.length === 0) {
+        const e = new Error("resolveHold requires a non-empty requestId (the audit attribution of who resolved) — refused, never defaulted.");
+        e.code = "memory.hold_resolve_unattributed";
+        throw e;
+    }
+    if (input.action !== "release" && input.action !== "discard") {
+        const e = new Error(`resolveHold action must be "release" or "discard" (got ${JSON.stringify(input.action)}) — refused loudly, never folded.`);
+        e.code = "memory.hold_resolve_invalid";
+        throw e;
+    }
+    lockedStrictUpdate(controlDir, HOLDS_FILE, "memory instruction-hold ledger", coerceHolds, (rec) => {
+        const r = rec.rows.find((x) => x.holdId === input.holdId);
+        if (r === undefined) {
+            const e = new Error(`resolveHold: unknown holdId ${JSON.stringify(input.holdId)}`);
+            e.code = "memory.hold_resolve_unknown";
+            throw e;
+        }
+        if (r.status !== "held" && !(r.status === "disposed" && r.disposition?.terminal === "expired" && input.action === "release")) {
+            const e = new Error(`resolveHold: hold ${JSON.stringify(input.holdId)} is ${r.status}${r.disposition !== undefined ? ` (${r.disposition.terminal})` : ""} — only a held row, or an expired disposition (release), can be resolved`);
+            e.code = "memory.hold_resolve_invalid_state";
+            throw e;
+        }
+        r.resolved = input.action;
+        return { next: rec, result: undefined };
+    });
+}
+export function readHoldCustody(controlDir, row) {
+    const seats = [join(controlDir, HOLD_DIR, row.captureName), ...(row.disposition?.quarantineName !== undefined ? [join(controlDir, QUARANTINE_DIR, row.disposition.quarantineName)] : [])];
+    for (const seat of seats) {
+        try {
+            const bytes = readFileSync(seat);
+            if (sha256(bytes) === row.contentDigest)
+                return bytes.toString("utf8");
+        }
+        catch {
+        }
+    }
+    return undefined;
+}
+export function sessionBlocksCleanRelease(controlDir, sessionId) {
+    if (readSessionPollution(controlDir, sessionId) !== undefined)
+        return true;
+    return sessionSettlements(controlDir, sessionId).some((s) => s.effective !== "clean" && s.effective !== "void");
+}