@sema-agent/server 7.142.0 → 7.144.0

package/dist/plugins/checkpoint-store-sql.js

@@ -1,10 +1,10 @@
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
 import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, judgeCheckpointIndexCells } from "./checkpoint-index-columns.js";
-import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
+import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
-import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, countKindlessBatchOffers, parkRowCarriesSkillCardFacts, parkRowFacts, readRuleOfferList, skillCardFacts } from "../approval-card.js";
-import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
+import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, countKindlessBatchOffers, parkRowFacts, readRuleOfferList, skillCardFacts } from "../approval-card.js";
+import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
@@ -21,6 +21,35 @@ export const TERMINAL_GRACE_MS = 3_600_000;
 export function tokenFingerprint(token) {
     return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
 }
+const STORED_ROW_MEMO_CAP = 8192;
+class StoredRowProjectionMemo {
+    rows = new Map();
+    keyOf(sha256) {
+        return `${sha256}@${CONTRACT_KIT_ENGINE_VERSION}`;
+    }
+    get(sha256) {
+        const key = this.keyOf(sha256);
+        const hit = this.rows.get(key);
+        if (hit !== undefined) {
+            this.rows.delete(key);
+            this.rows.set(key, hit);
+        }
+        return hit;
+    }
+    set(sha256, projection) {
+        const key = this.keyOf(sha256);
+        this.rows.delete(key);
+        this.rows.set(key, projection);
+        while (this.rows.size > STORED_ROW_MEMO_CAP) {
+            const oldest = this.rows.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.rows.delete(oldest);
+        }
+    }
+}
+const STORED_ROW_READ_BATCH = 100;
+const CHECKPOINT_SHA256_AS = "checkpoint_sha256";
 const GATE_KIND_IS_LIVE_RUN_PARK = {
     human: true,
     irreversible_ask: true,
@@ -236,15 +265,17 @@ export function approvalDecisionOfWinner(winner, boundCallId) {
         }
     }
 }
-export function pendingActionToolCallId(body) {
+function pendingActionToolCallId(body) {
     if (typeof body !== "object" || body === null)
         return { readable: false };
-    const rawSource = "sourceTaskId" in body ? body.sourceTaskId : null;
+    if ("sourceTaskId" in body)
+        return { readable: false };
+    const rawSource = "sourceSessionId" in body ? body.sourceSessionId : null;
     if (rawSource !== null && rawSource !== undefined && typeof rawSource !== "string")
         return { readable: false };
-    const sourceTaskId = typeof rawSource === "string" ? rawSource : null;
+    const sourceSessionId = typeof rawSource === "string" ? rawSource : null;
     if (!("pendingAction" in body))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceTaskId };
+        return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceSessionId };
     const pa = body.pendingAction;
     if (typeof pa !== "object" || pa === null)
         return { readable: false };
@@ -252,7 +283,7 @@ export function pendingActionToolCallId(body) {
     if (kind !== null && typeof kind !== "string")
         return { readable: false };
     if (!("toolCallId" in pa))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind, sourceTaskId };
+        return { readable: true, toolCallId: null, boundInputHash: null, kind, sourceSessionId };
     const id = pa.toolCallId;
     if (typeof id !== "string")
         return { readable: false };
@@ -261,19 +292,24 @@ export function pendingActionToolCallId(body) {
     const bih = "boundInputHash" in pa ? pa.boundInputHash : null;
     if (bih !== null && typeof bih !== "string")
         return { readable: false };
-    return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceTaskId };
+    return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceSessionId };
 }
-function pendingActionOfColumn(cell, where) {
-    let body;
+export function candidateIdentityOf(cp) {
+    if (judgeCheckpointRow(cp).kind === "lacking")
+        return { readable: false };
+    return pendingActionToolCallId(cp);
+}
+function candidateIdentityOfColumn(cell, where) {
+    let cp;
     try {
-        body = decodeJsonColumn(cell, readJsonObjectColumn, `checkpoint.checkpoint ${where}`);
+        cp = decodeCheckpointColumn(cell, where);
     }
     catch (e) {
         if (!isJsonColumnBodyProblem(e))
             throw e;
         return { readable: false };
     }
-    return pendingActionToolCallId(body);
+    return candidateIdentityOf(cp);
 }
 function readActorAssertion(v) {
     if (typeof v !== "object" || v === null)
@@ -344,6 +380,7 @@ export class SqlCheckpointStore {
     fidelity = "json";
     execution = { outcome: true };
     claims;
+    storedRowMemo = new StoredRowProjectionMemo();
     constructor(db, logger, opts = {}) {
         this.db = db;
         this.logger = logger;
@@ -431,16 +468,12 @@ export class SqlCheckpointStore {
         }
     }
     async get(token) {
-        const { rows } = await this.db.query(this.q(`SELECT version, status, ${jsonColumnText("mysql", "checkpoint")}, ${jsonColumnText("mysql", "outcome")}, reopen_reason, rev, ` +
-            `${jsonColumnText("mysql", "pending_steer_queue")}, ${jsonColumnText("mysql", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = ?`, `SELECT version, status, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnText("pg", "outcome")}, reopen_reason, rev, ` +
+        const { rows } = await this.db.query(this.q(`SELECT status, ${jsonColumnText("mysql", "checkpoint")}, ${jsonColumnText("mysql", "outcome")}, reopen_reason, rev, ` +
+            `${jsonColumnText("mysql", "pending_steer_queue")}, ${jsonColumnText("mysql", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = ?`, `SELECT status, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnText("pg", "outcome")}, reopen_reason, rev, ` +
             `${jsonColumnText("pg", "pending_steer_queue")}, ${jsonColumnText("pg", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = $1`), [token]);
         const r = rows[0];
         if (!r)
             return null;
-        const version = Number(r.version);
-        if (version > MAX_SUPPORTED_CHECKPOINT_VERSION) {
-            throw new Error(`checkpoint format version ${version} is newer than this build supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION}) — upgrade the service to resume it`);
-        }
         const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `for token ${tokenFingerprint(token)}`));
         cp.status = r.status;
         const outcomeRaw = refusing("a decision record nobody can read", () => decodeOutcomeColumn(r.outcome, `for token ${tokenFingerprint(token)}`));
@@ -466,7 +499,6 @@ export class SqlCheckpointStore {
         this.logger?.info?.("checkpoint_get", {
             tokenFp: tokenFingerprint(token),
             status: cp.status,
-            version,
             hasWorkspaceHandle: !!cp.state?.workspaceHandle,
             snapshotId: cp.state?.workspaceHandle?.snapshotId,
         });
@@ -556,7 +588,8 @@ export class SqlCheckpointStore {
         const d = this.db.dialect;
         const base = `SELECT c.session_id, c.token, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
             `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, c.approval_card, ta.task_id, ` +
-            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)} ` +
+            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)}, ` +
+            `${jsonColumnTextSha256(d, "checkpoint", CHECKPOINT_SHA256_AS)} ` +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
@@ -590,43 +623,77 @@ export class SqlCheckpointStore {
                 ...(approvalCard !== undefined ? { approvalCard } : {}),
                 ...parkRowFacts(pendingAction),
             };
-            return [{ row, token: String(r.token), readSkillCard: parkRowCarriesSkillCardFacts(pendingAction) }];
+            return [{ row, token: String(r.token), sha256: readJsonColumnTextSha256(r[CHECKPOINT_SHA256_AS], "checkpoint.checkpoint_sha256 (operator queue row)") }];
+        });
+        const projections = await this.storedRowProjections(entries);
+        const out = entries.map((e) => {
+            const p = projections.get(e.token);
+            return p === undefined ? e.row : { ...e.row, ...p.skillCardFacts, rowVerdict: p.rowVerdict };
         });
-        const out = [];
-        for (const e of entries)
-            out.push(e.readSkillCard ? { ...e.row, ...(await this.readParkedSkillCardFacts(e.token)) } : e.row);
         return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
     }
-    async readParkedSkillCardFacts(token) {
-        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "checkpoint")} FROM checkpoint WHERE token = ? AND status = 'pending'`, `SELECT ${jsonColumnText("pg", "checkpoint")} FROM checkpoint WHERE token = $1 AND status = 'pending'`), [token]);
-        const r = rows[0];
-        if (r === undefined)
-            return {};
+    async storedRowProjections(rows) {
+        const out = new Map();
+        const misses = [];
+        const expected = new Map();
+        for (const { token, sha256 } of rows) {
+            expected.set(token, sha256);
+            const hit = this.storedRowMemo.get(sha256);
+            if (hit === undefined)
+                misses.push(token);
+            else
+                out.set(token, hit);
+        }
+        for (let i = 0; i < misses.length; i += STORED_ROW_READ_BATCH) {
+            const batch = misses.slice(i, i + STORED_ROW_READ_BATCH);
+            const { rows: read } = await this.db.query(this.q(`SELECT token, ${jsonColumnText("mysql", "checkpoint")}, ${jsonColumnTextSha256("mysql", "checkpoint", CHECKPOINT_SHA256_AS)} FROM checkpoint ` +
+                `WHERE status = 'pending' AND token IN (${batch.map(() => "?").join(", ")})`, `SELECT token, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnTextSha256("pg", "checkpoint", CHECKPOINT_SHA256_AS)} FROM checkpoint ` +
+                `WHERE status = 'pending' AND token IN (${batch.map((_, j) => `$${j + 1}`).join(", ")})`), batch);
+            for (const r of read) {
+                const token = String(r.token);
+                const sha256 = readJsonColumnTextSha256(r[CHECKPOINT_SHA256_AS], "checkpoint.checkpoint_sha256 (whole-row read)");
+                const projection = this.projectStoredRow(r, sha256);
+                if (projection !== undefined && sha256 === expected.get(token))
+                    out.set(token, projection);
+            }
+        }
+        return out;
+    }
+    projectStoredRow(r, sha256) {
         let cp;
         try {
-            cp = decodeCheckpointColumn(r.checkpoint, "(operator queue row, skill-card facts)");
+            cp = decodeCheckpointColumn(r.checkpoint, "(operator queue row, whole-row read)");
         }
         catch (e) {
             if (!isJsonColumnBodyProblem(e))
                 throw e;
             recordFailOpen("server.approvals.park-row-blob-unreadable");
-            return {};
+            return undefined;
         }
+        let summary;
         try {
-            return skillCardFacts(summarizeCheckpoint(cp));
+            summary = summarizeCheckpoint(cp);
         }
         catch {
             recordFailOpen("server.approvals.park-row-blob-unreadable");
-            return {};
+            return { rowVerdict: judgeCheckpointRow(cp), skillCardFacts: {} };
         }
+        const projection = { rowVerdict: summary.rowVerdict, skillCardFacts: skillCardFacts(summary) };
+        this.storedRowMemo.set(sha256, projection);
+        return projection;
     }
     async listByScope(scope) {
-        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at_ms ASC LIMIT 500`, `SELECT ${jsonColumnText("pg", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at_ms ASC LIMIT 500`), [scope]);
+        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "checkpoint")}, ${jsonColumnTextSha256("mysql", "checkpoint", CHECKPOINT_SHA256_AS)}, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at_ms ASC LIMIT 500`, `SELECT ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnTextSha256("pg", "checkpoint", CHECKPOINT_SHA256_AS)}, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at_ms ASC LIMIT 500`), [scope]);
         const out = [];
         for (const r of rows) {
+            const sha256 = readJsonColumnTextSha256(r[CHECKPOINT_SHA256_AS], `checkpoint.checkpoint_sha256 in the ${scope} scheduler view`);
             const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `in the ${scope} scheduler view`));
             cp.status = r.status;
-            out.push(summarizeCheckpoint(cp, (sentence) => recordFailOpen("server.checkpoint.inbox-risk-axes-damaged", withoutCheckpointToken(sentence, cp.token))));
+            const memo = this.storedRowMemo.get(sha256);
+            const summary = summarizeCheckpoint(cp, (sentence) => recordFailOpen("server.checkpoint.inbox-risk-axes-damaged", withoutCheckpointToken(sentence, cp.token)), memo?.rowVerdict);
+            if (memo === undefined)
+                this.storedRowMemo.set(sha256, { rowVerdict: summary.rowVerdict, skillCardFacts: skillCardFacts(summary) });
+            out.push(summary);
         }
         return out;
     }
@@ -640,8 +707,8 @@ export class SqlCheckpointStore {
         return rows[0] ? String(rows[0].token) : null;
     }
     async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
-        const { rows } = await this.db.query(this.q(`SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, ${jsonColumnText("mysql", "checkpoint")} FROM checkpoint ` +
-            "WHERE scope=? AND session_id=? AND created_at_ms>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at_ms ASC", `SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, ${jsonColumnText("pg", "checkpoint")} FROM checkpoint ` +
+        const { rows } = await this.db.query(this.q(`SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, ${jsonColumnText("mysql", "checkpoint")} FROM checkpoint ` +
+            "WHERE scope=? AND session_id=? AND created_at_ms>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at_ms ASC", `SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, ${jsonColumnText("pg", "checkpoint")} FROM checkpoint ` +
             "WHERE scope=$1 AND session_id=$2 AND created_at_ms>=$3 AND (tool_call_id=$4 OR tool_call_id IS NULL) ORDER BY created_at_ms ASC"), [scope, sessionId, sinceMs, toolCallId]);
         const out = [];
         for (const r of rows) {
@@ -650,13 +717,9 @@ export class SqlCheckpointStore {
                 status: String(r.status),
                 createdAtMs: Number(r.created_at_ms),
                 boundInputHash: r.bound_input_hash == null ? null : String(r.bound_input_hash),
-                sourceTaskId: null,
+                sourceSessionId: null,
             };
-            if (Number(r.version) > MAX_SUPPORTED_CHECKPOINT_VERSION) {
-                out.push({ ...base, boundCallId: null, unparseable: true });
-                continue;
-            }
-            const derived = pendingActionOfColumn(r.checkpoint, `for token ${tokenFingerprint(String(r.token))}`);
+            const derived = candidateIdentityOfColumn(r.checkpoint, `for token ${tokenFingerprint(String(r.token))}`);
             if (!derived.readable) {
                 out.push({ ...base, boundCallId: null, unparseable: true });
                 continue;
@@ -673,7 +736,7 @@ export class SqlCheckpointStore {
             const effectiveHash = base.boundInputHash ?? derived.boundInputHash;
             const effective = col ?? derived.toolCallId;
             if (effective === toolCallId)
-                out.push({ ...base, boundInputHash: effectiveHash, sourceTaskId: derived.sourceTaskId, boundCallId: effective });
+                out.push({ ...base, boundInputHash: effectiveHash, sourceSessionId: derived.sourceSessionId, boundCallId: effective });
         }
         return out;
     }

package/dist/plugins/file-history-store-sql.d.ts

@@ -2,7 +2,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport, type FileHistoryExportResult } from "@sema-agent/core";
 import { type BlobBackend } from "./blob-backend.js";
-import type { SyncBlobPutResult } from "./store-backend.js";
+import type { ServiceBlobExchange } from "./store-backend.js";
 import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 /** The file-history blob domain's SQL table (BlobBackend `table`/MinIO index binding + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -24,12 +24,10 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** RAW native pool — handed to blob-backend.ts (outside the SqlDriver seam, dialect-switches on
      *  its own string). Not used for this class's own statements (those go through `db`). */
     protected readonly pool: MySqlPool | PgPool;
-    /** 2c sync blob-face MARKER (codex R2-high): the route/caps predicates gate on THIS, never on a
-     *  `typeof putBlob` duck-probe — core's local FileFileHistoryStore carries a PRIVATE synchronous
-     *  `putBlob(hash, bytes): void` helper whose name collides with the service face; a name probe
-     *  passes there, mutates core-owned blob storage out of contract, then dereferences `.ok` on
-     *  undefined. Presence of this literal = the full typed putBlob/getBlob/hasBlobs face exists. */
-    readonly syncBlobFaces: true;
+    /** The blob exchange (core's `FileHistoryStore.blobExchange` group, see {@link ServiceBlobExchange}): how another machine's bytes
+     *  come in ahead of an `importHistory`, go out to a puller, and are asked about. Its presence IS the capability — read through
+     *  `blobExchangeOf` (`session-sync.ts`), which defers to core's judge; there is no second word for it on this class. */
+    readonly blobExchange: ServiceBlobExchange;
     protected readonly blobs: BlobBackend;
     /** §10 S-6 in-process lease state (design v1 D2: NOT persisted). Keys = `${scope}\x00${entryId}`. */
     private readonly spentAttempts;
@@ -58,15 +56,25 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /**
      * Per-scope WRITE-SERIALIZATION lock (codex R1-critical): `SELECT … FOR UPDATE` over an EMPTY result
      * locks nothing on PG, so neither the empty-target law (import/adopt) nor a multi-statement graph
-     * write can be serialized by the data rows alone. Every graph-mutating tx therefore first ensures +
+     * write can be serialized by the data rows alone. Every graph transaction therefore first ensures +
      * row-locks the scope's sentinel row — one lock, both dialects, and disjoint-key writers can no
-     * longer interleave into a merged/torn graph. The ensure+lock loops because deleteBySession removes
-     * the sentinel: a waiter woken by that delete sees zero rows and must re-ensure.
+     * longer interleave into a merged/torn graph.
      *
      * Shape A ([ref]): the MySQL ensure verb is `ON DUPLICATE KEY UPDATE scope = scope`, NOT `INSERT IGNORE`.
      * On InnoDB a duplicate-key IGNORE takes an **S** lock on the existing sentinel and the `FOR UPDATE` right
      * below has to upgrade it to X — two concurrent scope writers each holding an S deadlock ([ref]). ON
      * DUPLICATE takes X on the duplicate key, the same mode the locking read wants, so they serialize instead.
+     *
+     * **This is the transaction's first statement** (every caller: `begin()` and then this — nothing of the
+     * transaction exists before it), and a lost arbitration here restarts the transaction from the top
+     * (rollback + begin + the same ensure-and-lock), through the repo's one bound ({@link retryOnDeadlock}). Two shapes:
+     *  · the engine picked this transaction as a deadlock victim. InnoDB only (REPEATABLE READ): when the sentinel
+     *    physically disappears while ≥ 2 transactions are queued on it — its minter rolled back, or a whole-scope
+     *    removal ({@link deleteBySession}) committed and purge took the delete-marked row — the queued locks are
+     *    inherited as GAP locks on the next record, and each queued ensure's insert-intention waits on the others'
+     *    gap locks. The engine kills all but one; the survivor's mint goes through and the others restart into it;
+     *  · the sentinel was gone at the locking read ({@link ScopeSentinelVanishedError}; PG, see there).
+     * The lock order itself stays single: sentinels first (sorted), then the scope's rows.
      */
     private lockScope;
     /** Returns the UPDATE's affected count — 0 = the record is gone (annulled) or was already observed;
@@ -147,14 +155,12 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** Async byte-GC: blobs referenced by NO version row (any scope), past the created_at grace window.
      *  Domain-isolated by construction (this store's blob table only — [ref] D1). Reaper-driven. */
     sweepOrphanBlobs(): Promise<number>;
-    /** Upload ONE content-addressed blob ahead of an importHistory (§5 streamed negotiation). Store-level
-     *  integrity re-check (the route pre-verifies too — the internal caller might not). Never-throw.
-     *  The SQL blob judge's refusal ({@link BlobTooLargeError}, judged on the connection that would have written the blob)
-     *  keeps its own code — the route answers it 413 (the sentence names that connection's walls), every other write failure 502 ("retry"). */
-    putBlob(hash: string, bytes: Uint8Array): Promise<SyncBlobPutResult>;
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    /** The subset of `hashes` already present — one SQL INDEX probe (the import presence pre-check). */
-    hasBlobs(hashes: string[]): Promise<Set<string>>;
+    /** Store ONE content-addressed blob ahead of an importHistory (§5 streamed negotiation). The content address is judged HERE and
+     *  nowhere else (core's `put` law: bytes whose sha256 is not `hash` are refused `adopt_failed` / `terminal`, nothing stored).
+     *  Never-throw. The SQL blob judge's refusal ({@link BlobTooLargeError}, judged on the connection that would have written the blob)
+     *  is a terminal refusal that carries `blobCap` — the route answers it 413 with the judge's sentence; every other write failure is
+     *  `snapshot_failed` with the store's judgment of the fault (the route answers 502, "retry"). */
+    private putExchangedBlob;
     adoptScope(fromScope: string, toScope: string): Promise<FileHistoryResult>;
     private scopeEmpty;
     /** `forUpdate` — see {@link loadTracked}. Every in-transaction caller passes `true`: the four reads are

package/dist/plugins/file-history-store-sql.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, annulProofFailure, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
 import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isMissingColumnError } from "./sql-errors.js";
+import { isMissingColumnError, retryOnDeadlock } from "./sql-errors.js";
 import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
@@ -12,6 +12,8 @@ const sha256hex = (s) => createHash("sha256").update(s).digest("hex");
 const truthy = (v) => v === true || v === 1 || v === "1";
 class StagedRefGoneError extends Error {
 }
+class ScopeSentinelVanishedError extends Error {
+}
 function reapedEntryRefusal(entryId) {
     return {
         ok: false,
@@ -24,7 +26,11 @@ function reapedEntryRefusal(entryId) {
 export class SqlFileHistoryStore {
     db;
     pool;
-    syncBlobFaces = true;
+    blobExchange = {
+        put: (hash, bytes) => this.putExchangedBlob(hash, bytes),
+        get: (hash) => this.blobs.getBlob(hash),
+        has: (hashes) => this.blobs.hasBlobs([...hashes]),
+    };
     blobs;
     spentAttempts = new Set();
     activeAttempts = new Set();
@@ -48,16 +54,21 @@ export class SqlFileHistoryStore {
     async beforeObserve(_scope, _keyHash) { }
     async beforePublish(_scope) { }
     async lockScope(conn, ...scopes) {
-        for (const scope of [...new Set(scopes)].sort()) {
-            let locked = false;
-            for (let i = 0; i < 3 && !locked; i++) {
+        const ordered = [...new Set(scopes)].sort();
+        let restart = false;
+        await retryOnDeadlock(this.db.dialect, async () => {
+            if (restart) {
+                await conn.rollback().catch(() => undefined);
+                await conn.begin();
+            }
+            restart = true;
+            for (const scope of ordered) {
                 await conn.query(this.q("INSERT INTO file_history_scope (scope, created_at_ms) VALUES (?,?) ON DUPLICATE KEY UPDATE scope = scope", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
                 const r = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
-                locked = Boolean(r.rows[0]);
+                if (!r.rows[0])
+                    throw new ScopeSentinelVanishedError(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
             }
-            if (!locked)
-                throw new Error(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
-        }
+        }, (err) => err instanceof ScopeSentinelVanishedError);
     }
     async markObserved(scope, keyHash) {
         const r = await this.db.query(this.q("UPDATE file_history_tracked SET observed_later = 1 WHERE scope = ? AND key_hash = ? AND observed_later = 0", "UPDATE file_history_tracked SET observed_later = TRUE WHERE scope = $1 AND key_hash = $2 AND observed_later = FALSE"), [scope, keyHash]);
@@ -585,9 +596,9 @@ export class SqlFileHistoryStore {
             return 0;
         return this.blobs.deleteBlobs(orphans);
     }
-    async putBlob(hash, bytes) {
+    async putExchangedBlob(hash, bytes) {
         if (sha256hex(bytes) !== hash) {
-            return { ok: false, error: { code: "unsupported_format", message: `putBlob ${hash} fails content-address integrity — nothing stored` } };
+            return { ok: false, error: { code: "adopt_failed", message: `blob ${hash}: the bytes do not hash to this address — nothing stored`, permanence: "terminal" } };
         }
         try {
             await this.blobs.putBlob(hash, bytes);
@@ -595,17 +606,11 @@ export class SqlFileHistoryStore {
         }
         catch (err) {
             if (err instanceof BlobTooLargeError)
-                return { ok: false, error: { code: err.code, message: err.message, wallSource: err.cap.source } };
+                return { ok: false, error: { code: "adopt_failed", message: err.message, permanence: "terminal", blobCap: { wallSource: err.cap.source } } };
             const f = foldCaughtFailure(err);
-            return { ok: false, error: { code: "snapshot_failed", message: `putBlob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
+            return { ok: false, error: { code: "snapshot_failed", message: `blob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
         }
     }
-    async getBlob(hash) {
-        return this.blobs.getBlob(hash);
-    }
-    async hasBlobs(hashes) {
-        return this.blobs.hasBlobs(hashes);
-    }
     async adoptScope(fromScope, toScope) {
         try {
             if (fromScope === toScope)

package/dist/plugins/file-run-store.d.ts

@@ -41,6 +41,14 @@ export declare class FileRunStore implements InProcessClaimFence {
     private readonly events;
     /** taskId → the open append log (one O_APPEND fd per run, lazily opened, held for lifetime). */
     private readonly eventLogs;
+    /** `<root>/run-blobs/` — one section-blob ledger per session (plane 4 of the header). */
+    private readonly blobsDir;
+    /** sessionId → (digest → section body): the index of plane 4 (hydrated per session that has run rows). */
+    private readonly sectionBlobs;
+    /** sessionId → the open section-blob ledger (lazily opened, held until the session is deleted / dispose). */
+    private readonly blobLogs;
+    /** `(taskId, seq)` of manifest rows already reported as unresolvable (one report per row per store instance = per process). */
+    private readonly unresolvedReported;
     /** [ref] the checkpoint-table stand-in (see memory-run-store.ts {@link RunStoreCheckpointProbe} — the full
      *  rationale lives on the interface); absent ⇒ the suspended-run reapers stay honest NO-OPs. */
     private checkpointProbe?;
@@ -61,6 +69,11 @@ export declare class FileRunStore implements InProcessClaimFence {
     private runJsonPath;
     private eventsPath;
     private activePath;
+    /** A session's section-blob ledger. The file name is core's `sanitizeScope` form (readable prefix + sha256 of the id), not the
+     *  bare id: two ids that differ only in letter case are one file on a case-insensitive file system (macOS by default), and a
+     *  deleted session must never take another session's blocks with it. `undefined` only for a run row read back from a damaged
+     *  run.json whose session id is not a string — such a row has no ledger (its manifest rows are stored whole). */
+    private blobLedgerPath;
     private spaceCommitPath;
     /** One space's commit record, or `undefined` (no file). A record that is not this store's shape is a loud read failure
      *  (the reader — the next run's connect — refuses; it never guesses that no commit is in flight). */
@@ -129,6 +142,22 @@ export declare class FileRunStore implements InProcessClaimFence {
     isPreemptRequested(taskId: string, owner: string | null): Promise<boolean>;
     heartbeat(taskId: string, owner: string | null): Promise<void>;
     appendEvent(taskId: string, seq: number, type: LedgerEventType, data: unknown): Promise<void>;
+    /**
+     * 写口里第四个盘面的那一段(与事件行的追加在**同一同步调用**里,块在前):帧经编解码拆成引用形 + 段体,本会话块账本里还没有的段体先追加
+     * (一批一次 fsync:事件行本身 fsync:false,而一只块被同会话之后每一条清单行引用 —— 丢一行丢一帧,丢一块丢一串帧),再把引用形交回给
+     * 事件行的追加。块追加抛 ⇒ 原样上抛:事件行不写,不退回整帧(与事件行自己写失败同一条路,汇点的串行写口留 seq 洞)。
+     * 这条 run 没有行(会话不详)⇒ 没有块账本可挂 ⇒ 帧原样存:和类型里「没有一段用引用」的合法实例,读口原样交出。
+     */
+    private storeSections;
+    private blobLogFor;
+    /** Drop a session's section-blob ledger: the file first, then the open fd and the index. The file removal is NOT best-effort
+     *  (unlike {@link dropRun}'s directory): it is the delete's first destructive step, so a removal that fails throws before
+     *  anything else changed — the session delete answers an error and a retry starts from the same state, instead of leaving
+     *  an index that no longer matches the disk. (`AppendLog.close` never throws: it swallows its own `closeSync`.) */
+    private dropSectionBlobs;
+    /** 读口的悬空引用臂:清单行有一段装不回 ⇒ 这一帧这一次不交出(永不交出缺段的清单),每 `(taskId, seq)` 每只店实例(= 每进程)留一次 F 类痕;
+     *  帧仍在索引里,`maxSeq` / `retainedFrom` 照旧按存位算(下一个写者的 seq 不会撞上它)。 */
+    private reportUnresolved;
     maxSeq(taskId: string): Promise<number>;
     retainedFrom(taskId: string): Promise<number>;
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;