@sema-agent/server 7.150.0 → 7.152.0

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

@@ -1,24 +1,33 @@
-import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
 import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, checkpointSweepAfterSql, hostSessionOf, judgeCheckpointIndexCells } from "../plugins/checkpoint-index-columns.js";
 import { CheckpointError, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, readCheckpointSessionQuery, selectSessionPage, } from "@sema-agent/core";
-import { parkRowFacts, skillCardFacts } from "../approval-card.js";
-import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, isJsonObject, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
+import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, isJsonObject, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, StoreCorruptError, } from "../plugins/sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
+import { withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "../plugins/sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "../plugins/sql-errors.js";
 import { probedMissingColumnRefusal } from "../plugins/schema-drift-sentence.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { approvalPayloadFingerprint } from "../plugins/approval-payload-fingerprint.js";
-import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DECIDED_REPLAY_SCAN_CAP, DENY_SWEEP_PAGE_ROWS, isUnreadableSummaryForm, parkedLegTaskId, queueRowGateKind, queueTriageOrder, readRiskDescriptorBody, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, UnreadableCheckpointRowError, } from "../plugins/checkpoint-store-face.js";
+import { approvalDecisionOfWinner, buildQueueActionFacts, buildQueueRow, createCardScopeRootSeat, candidateIdentityOf, DECIDED_REPLAY_SCAN_CAP, DENY_SWEEP_PAGE_ROWS, isUnreadableSummaryForm, queueRowGateKind, queueTriageOrder, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, UnreadableCheckpointRowError, } from "../plugins/checkpoint-store-face.js";
 const CTX_REWRITE_PAGE = 500;
 export function tokenFingerprint(token) {
     return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
 }
-const STORED_ROW_MEMO_CAP = 8192;
-class StoredRowProjectionMemo {
+export const STORED_ROW_MEMO_MAX_BYTES = 64 * 1024 * 1024;
+export const STORED_ROW_MEMO_MAX_ENTRIES = 8192;
+export class StoredRowProjectionMemo {
+    maxBytes;
+    maxEntries;
     rows = new Map();
+    total = 0;
+    constructor(maxBytes = STORED_ROW_MEMO_MAX_BYTES, maxEntries = STORED_ROW_MEMO_MAX_ENTRIES) {
+        this.maxBytes = maxBytes;
+        this.maxEntries = maxEntries;
+    }
+    get bytes() {
+        return this.total;
+    }
     keyOf(sha256) {
         return `${sha256}@${CONTRACT_KIT_ENGINE_VERSION}`;
     }
@@ -29,28 +38,34 @@ class StoredRowProjectionMemo {
             this.rows.delete(key);
             this.rows.set(key, hit);
         }
-        return hit;
+        return hit?.actionFacts;
     }
-    set(sha256, projection) {
+    set(sha256, actionFacts) {
+        const bytes = Buffer.byteLength(JSON.stringify(actionFacts), "utf8");
+        if (bytes > this.maxBytes)
+            return;
         const key = this.keyOf(sha256);
-        this.rows.delete(key);
-        this.rows.set(key, projection);
-        while (this.rows.size > STORED_ROW_MEMO_CAP) {
+        this.evict(key);
+        this.rows.set(key, { actionFacts, bytes });
+        this.total += bytes;
+        while (this.rows.size > this.maxEntries || this.total > this.maxBytes) {
             const oldest = this.rows.keys().next().value;
             if (oldest === undefined)
                 break;
-            this.rows.delete(oldest);
+            this.evict(oldest);
         }
     }
+    evict(key) {
+        const gone = this.rows.get(key);
+        if (gone === undefined)
+            return;
+        this.rows.delete(key);
+        this.total -= gone.bytes;
+    }
 }
 const STORED_ROW_READ_BATCH = 100;
 const CHECKPOINT_SHA256_AS = "checkpoint_sha256";
 export const CHECKPOINT_ADDED_COLUMNS = [
-    {
-        column: "has_bidi_controls",
-        breaksAt: "the park-mint write (put) and the operator-queue reads (GET /v1/approvals, /v1/approvals/stream) name it " +
-            "unconditionally, so every durable suspend fails at first park and every queue poll 500s",
-    },
     {
         column: "execution_outcome",
         breaksAt: "the execution-outcome record (CheckpointStore.recordExecutionOutcome, core 7.7.0 #602) writes it under a CAS and " +
@@ -61,6 +76,10 @@ export const CHECKPOINT_ADDED_COLUMNS = [
         column: "execution_at_ms",
         breaksAt: "it is written in the same CAS as `execution_outcome` (the record and its stamp are one write group)",
     },
+    {
+        column: "card_scope_root",
+        breaksAt: "the park-mint write (put) stamps it and the decide door's rule redemption reads it, so every durable suspend fails at first park",
+    },
     {
         column: "host_session_id",
         breaksAt: "the park-mint write (put) stamps it, the one-time backfill M49 (which runs right after this check) fills it on the rows already parked, " +
@@ -107,9 +126,6 @@ function decodeOutcomeColumn(cell, where) {
 function decodeExecutionOutcomeColumn(cell, where) {
     return decodeNullableJsonColumn(cell, readGateOutcomeBody, `checkpoint.execution_outcome ${where}`);
 }
-function decodeToolInputColumn(cell) {
-    return decodeNullableJsonColumn(cell, readNonNullJsonValueColumn, "checkpoint.tool_input (operator queue row)");
-}
 function decodeCtxColumn(cell, where) {
     return decodeJsonColumn(cell, createObjectColumnReader(), `checkpoint_ctx.ctx ${where}`);
 }
@@ -121,71 +137,6 @@ function refusing(what, read) {
         throw foldJsonColumn(e, (m) => `SqlCheckpointStore: ${m} — refusing rather than serve ${what}`);
     }
 }
-function readRuleOffersCell(cell) {
-    if (cell === null)
-        return undefined;
-    let parsed;
-    try {
-        parsed = decodeJsonColumn(cell, readJsonArrayColumn, "checkpoint.rule_suggestions (operator queue row)");
-    }
-    catch (e) {
-        if (!isJsonColumnBodyProblem(e))
-            throw e;
-        recordFailOpen("server.approvals.rule-suggestions-cell-unreadable");
-        return undefined;
-    }
-    return boundedRuleOffers(parsed, { countRedactions: false });
-}
-function readRiskDescriptorCell(cell) {
-    if (cell === null)
-        return null;
-    try {
-        return decodeJsonColumn(cell, readRiskDescriptorBody, "checkpoint.risk_descriptor (operator queue row)");
-    }
-    catch (e) {
-        if (!isJsonColumnBodyProblem(e))
-            throw e;
-        recordFailOpen("server.approvals.risk-descriptor-cell-unreadable");
-        return null;
-    }
-}
-function readParkRowActionCell(cell) {
-    try {
-        return decodeNullableJsonColumn(cell, readPendingActionMemberBody, "checkpoint.checkpoint $.pendingAction (operator queue row)");
-    }
-    catch (e) {
-        if (!isJsonColumnBodyProblem(e))
-            throw e;
-        recordFailOpen("server.approvals.park-row-blob-unreadable");
-        return undefined;
-    }
-}
-const PARK_ROW_PENDING_ACTION = { path: ["pendingAction"], as: "pending_action" };
-const PARK_ROW_CHECKPOINT_ID = { path: ["checkpointId"], as: "checkpoint_id" };
-const readCheckpointIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "checkpointId is not a JSON string" });
-function readCheckpointIdCell(cell) {
-    try {
-        return decodeNullableJsonColumn(cell, readCheckpointIdMemberBody, "checkpoint.checkpoint $.checkpointId (operator queue row)");
-    }
-    catch (e) {
-        if (!isJsonColumnBodyProblem(e))
-            throw e;
-        return null;
-    }
-}
-const PARK_ROW_RECORDED_TASK_ID = { path: ["state", "rowTaskId"], as: "row_task_id" };
-const readRecordedTaskIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "state.rowTaskId is not a JSON string" });
-function readRecordedTaskIdCell(cell) {
-    try {
-        return decodeNullableJsonColumn(cell, readRecordedTaskIdMemberBody, "checkpoint.checkpoint $.state.rowTaskId (operator queue row)");
-    }
-    catch (e) {
-        if (!isJsonColumnBodyProblem(e))
-            throw e;
-        return undefined;
-    }
-}
-const readPendingActionMemberBody = createObjectColumnReader();
 function candidateIdentityOfColumn(cell, where) {
     let cp;
     try {
@@ -260,6 +211,13 @@ export class SqlCheckpointStore {
         this.db = db;
         this.logger = logger;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
+        this.cardScopeRoot = opts.cardScopeRoot ?? createCardScopeRootSeat();
+    }
+    cardScopeRoot;
+    async cardScopeRootOf(token) {
+        const { rows } = await this.db.query(this.q("SELECT card_scope_root FROM checkpoint WHERE token = ?", "SELECT card_scope_root FROM checkpoint WHERE token = $1"), [token]);
+        const cell = rows[0]?.card_scope_root;
+        return typeof cell === "string" && cell !== "" ? cell : null;
     }
     q(mysql, pg) {
         return this.db.dialect === "mysql" ? mysql : pg;
@@ -302,23 +260,18 @@ export class SqlCheckpointStore {
             throw new CheckpointIndexRefusedError(cp.sessionId, judged);
         const cells = judged.cells;
         const hostSessionId = hostSessionOf(cp);
-        const pa = cp.pendingAction;
-        const toolInput = boundedToolInput(pa?.args);
-        const ruleOffers = boundedRuleOffers(pa?.ruleOffers);
         const executionOutcome = cp.executionOutcome === undefined ? null : this.json(cp.executionOutcome, "execution outcome");
         const executionAtMs = cp.executionOutcome === undefined ? null : (cp.executionAtMs ?? null);
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id) " +
-                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id) " +
-                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21::jsonb,$22,$23)"), [
+            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_call_id, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id, card_scope_root) " +
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_call_id, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id, card_scope_root) " +
+                "VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,$8,$9,$10,$11,$12,$13,$14,$15,$16::jsonb,$17,$18,$19)"), [
                 token,
                 cells.scope,
                 cells.session_id,
                 cells.version,
                 cp.status,
-                cells.tool_name,
                 cells.tool_call_id,
-                toolInput === null ? null : this.json(toolInput, "approval tool_input"),
                 this.json(cp, "checkpoint"),
                 cells.deadline,
                 cells.created_at_ms,
@@ -326,14 +279,12 @@ export class SqlCheckpointStore {
                 cells.gate_kind,
                 cells.approval_card,
                 cells.bound_input_hash,
-                cells.risk_descriptor === null ? null : this.json(cells.risk_descriptor, "risk descriptor"),
-                ruleOffers === undefined ? null : this.json(ruleOffers, "rule offers"),
-                cells.has_bidi_controls,
                 checkpointRevOf(cp),
                 cp.reopenReason ?? null,
                 executionOutcome,
                 executionAtMs,
                 hostSessionId,
+                this.cardScopeRoot.of(cp.sessionId) ?? null,
             ]);
         }
         catch (e) {
@@ -547,10 +498,7 @@ export class SqlCheckpointStore {
     }
     async listPending(scope) {
         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_RECORDED_TASK_ID)}, ` +
-            `${jsonColumnTextSha256(d, "checkpoint", CHECKPOINT_SHA256_AS)} ` +
+        const base = `SELECT c.session_id, c.token, c.scope, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id, ${jsonColumnTextSha256(d, "checkpoint", CHECKPOINT_SHA256_AS)} ` +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.host_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])
@@ -559,46 +507,29 @@ export class SqlCheckpointStore {
             const gateKind = queueRowGateKind(r.gate_kind);
             if (gateKind === undefined)
                 return [];
-            const toolName = r.tool_name ?? null;
-            const toolCallId = r.tool_call_id ?? null;
-            const boundInputHash = r.bound_input_hash ?? null;
-            const ruleOffers = readRuleOffersCell(r.rule_suggestions);
-            const approvalCard = parkedApprovalCard({ kind: gateKind, approvalCard: r.approval_card ?? undefined });
-            const pendingAction = readParkRowActionCell(r[PARK_ROW_PENDING_ACTION.as]);
-            const row = {
+            const token = String(r.token);
+            const address = {
+                token,
                 sessionId: String(r.session_id),
-                ...durableRowIdentity("approvals-queue", readCheckpointIdCell(r[PARK_ROW_CHECKPOINT_ID.as]), r.token),
                 scope: String(r.scope),
-                toolName,
-                toolCallId,
-                ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
-                ...(boundInputHash !== null ? { boundInputHash } : {}),
                 gateKind,
-                taskId: parkedLegTaskId(readRecordedTaskIdCell(r[PARK_ROW_RECORDED_TASK_ID.as]), r.task_id ?? null),
-                input: refusing("a tool input the operator would be approving unseen", () => decodeToolInputColumn(r.tool_input)) ?? null,
                 createdAt: Number(r.created_at_ms),
                 deadline: r.deadline == null ? null : Number(r.deadline),
-                riskDescriptor: readRiskDescriptorCell(r.risk_descriptor),
-                ...(ruleOffers !== undefined ? { ruleOffers } : {}),
-                ...(Number(r.has_bidi_controls) === 1 ? { hasBidiControls: true } : {}),
-                ...(approvalCard !== undefined ? { approvalCard } : {}),
-                ...parkRowFacts(pendingAction),
+                claimHolder: r.task_id ?? null,
             };
-            return [{ row, token: String(r.token), sha256: readJsonColumnTextSha256(r[CHECKPOINT_SHA256_AS], "checkpoint.checkpoint_sha256 (operator queue row)") }];
+            return [{ address, 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 facts = await this.storedRowProjections(entries);
+        const out = entries.flatMap((e) => {
+            const f = facts.get(e.token);
+            return f === undefined ? [] : [buildQueueRow(e.address, f)];
         });
         return out.sort(queueTriageOrder);
     }
     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);
@@ -611,19 +542,12 @@ export class SqlCheckpointStore {
                 `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 (sha256 === expected.get(token))
-                    out.set(token, projection);
+                out.set(String(r.token), this.readStoredRow(r, "(operator queue row, whole-row read)", sha256).actionFacts);
             }
         }
         return out;
     }
-    projectStoredRow(r, sha256) {
-        const read = this.readStoredRow(r, "(operator queue row, whole-row read)", sha256);
-        return read.summary === undefined ? { rowVerdict: read.rowVerdict, skillCardFacts: {} } : { rowVerdict: read.rowVerdict, skillCardFacts: skillCardFacts(read.summary) };
-    }
     readStoredRow(r, where, sha256, discloseFor) {
         const memo = this.storedRowMemo.get(sha256);
         let cp;
@@ -634,31 +558,33 @@ export class SqlCheckpointStore {
             if (!isJsonColumnBodyProblem(e))
                 throw e;
             recordFailOpen("server.approvals.park-row-blob-unreadable");
-            return { rowVerdict: verdictOfUnreadableBody(r.checkpoint) };
+            return { actionFacts: buildQueueActionFacts({ rowVerdict: verdictOfUnreadableBody(r.checkpoint) }) };
         }
         let summary;
         const disclosed = [];
         try {
-            summary = summarizeCheckpoint(cp, (sentence) => disclosed.push(sentence), memo?.rowVerdict);
+            summary = summarizeCheckpoint(cp, (sentence) => disclosed.push(sentence), memo?.row.rowVerdict);
         }
         catch {
             recordFailOpen("server.approvals.park-row-blob-unreadable");
-            return { rowVerdict: judgeCheckpointRow(cp) };
+            return { actionFacts: buildQueueActionFacts({ rowVerdict: judgeCheckpointRow(cp), cp }) };
         }
         if (isUnreadableSummaryForm(summary)) {
             recordFailOpen("server.approvals.park-row-blob-unreadable");
-            return { rowVerdict: summary.rowVerdict };
+            return { actionFacts: buildQueueActionFacts({ rowVerdict: summary.rowVerdict, cp, summary }) };
         }
         const seat = discloseFor?.(cp);
         for (const sentence of disclosed)
             seat?.(sentence);
-        if (memo === undefined)
-            this.storedRowMemo.set(sha256, { rowVerdict: summary.rowVerdict, skillCardFacts: skillCardFacts(summary) });
-        return { rowVerdict: summary.rowVerdict, summary };
+        if (memo !== undefined)
+            return { summary, actionFacts: memo };
+        const actionFacts = buildQueueActionFacts({ rowVerdict: summary.rowVerdict, cp, summary });
+        this.storedRowMemo.set(sha256, actionFacts);
+        return { summary, actionFacts };
     }
     async listByScope(scope) {
         const d = this.db.dialect;
-        const { rows } = await this.db.query(`SELECT ${jsonColumnText(d, "checkpoint")}, ${jsonColumnTextSha256(d, "checkpoint", CHECKPOINT_SHA256_AS)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)}, ` +
+        const { rows } = await this.db.query(`SELECT ${jsonColumnText(d, "checkpoint")}, ${jsonColumnTextSha256(d, "checkpoint", CHECKPOINT_SHA256_AS)}, ` +
             `token, session_id, scope, created_at_ms, deadline, gate_kind FROM checkpoint WHERE status = 'pending' AND scope = ${this.q("?", "$1")} ORDER BY created_at_ms ASC LIMIT 500`, [scope]);
         const out = [];
         for (const r of rows) {
@@ -671,11 +597,9 @@ export class SqlCheckpointStore {
             const gateKind = queueRowGateKind(r.gate_kind);
             if (gateKind === undefined)
                 continue;
-            const checkpointId = readCheckpointIdCell(r[PARK_ROW_CHECKPOINT_ID.as]);
             out.push({
                 token: String(r.token),
-                rowVerdict: read.rowVerdict,
-                ...(typeof checkpointId === "string" ? { checkpointId } : {}),
+                rowVerdict: read.actionFacts.row.rowVerdict,
                 sessionId: String(r.session_id),
                 scope: String(r.scope),
                 gateKind,

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

@@ -1,15 +1,33 @@
 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 FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryError, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport, type FileHistoryExportResult } from "@sema-agent/core";
 import type { BlobBackend } from "../plugins/blob-backend.js";
 import { SqlBlobIndex } from "./blob-index-sql.js";
-import type { ServiceBlobExchange } from "../plugins/store-backend.js";
-import { type SqlDriver, type SqlDialect } from "../plugins/sql-driver.js";
+import type { ServiceBlobExchange, ServiceBlobLanding, SqlBlobPutResult, SyncLanding } from "../plugins/store-backend.js";
+import { type SqlDriver, type SqlTxConn, type SqlDialect } from "../plugins/sql-driver.js";
 /** The file-history blob domain's SQL table (this store's blob index + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
-/** MinIO object-key prefix for this domain (snapshot epoch used "blobs/"; a separate prefix keeps the
- *  two domains' objects disjoint so neither sweep can see the other's keys). */
-export declare const FILE_HISTORY_BLOB_KEY_PREFIX = "file-history/";
+/** The per-landing provenance rows beside it ({@link SqlFileHistoryStore.blobLanding}). */
+export declare const FILE_HISTORY_BLOB_GRANT_TABLE = "file_history_blob_grant";
+/**
+ * Every file-history table keyed by `scope` (= the session id) — the ONE list every scope-wide deleter reads: this store's `deleteBySession` (E21 purge /
+ * overwrite-dst wipe) and its statement source on a caller's transaction (`deleteScopeOn` — the landed section's wipe), the replace arm of a landed
+ * replay (all but the sentinel), and the SQL retention executor's session-tree leg (`stores-sql/retention-store-sql.ts`). Order = delete order:
+ * children first, the scope sentinel LAST (a transaction queued on the sentinel restarts from its own ensure — see `lockScope`); every deleter holds
+ * the sentinel lock before the first DELETE. The byte index (`file_history_blob`) is NOT scope-keyed: bytes leave by the orphan sweep.
+ */
+export declare const FILE_HISTORY_SCOPED_TABLES: readonly ["file_history_boundary_file", "file_history_boundary", "file_history_reaped_entry", "file_history_version", "file_history_tracked", "file_history_blob_grant", "file_history_scope"];
+/**
+ * {@link SqlFileHistoryStore.prepareImport} 的答:门 / 取值校验的拒(`ok: false`,店码),或这一份信封落进目标要做什么 —— `same`(目标已是这一张图:不写)/
+ * `publish`(目标空,或 `replace` 下目标是另一张图:发布步写)。发布步({@link SqlFileHistoryStore.publishImportOn})在调用方的事务里按它做。
+ */
+export type FileHistoryImportPlan = {
+    readonly ok: false;
+    readonly error: FileHistoryError;
+} | {
+    readonly ok: true;
+    readonly mode: "same" | "publish";
+};
 /**
  * [ref] twin 保留条款(core 7.0.0 [ref] §片2 的 SQL 孪生)—— 构造期旋钮,键形与 core 内置后端
  * `FileFileHistoryStoreOptions.retention` / `FileStorageBackendOptions.fileHistory.retention` **同域同名**。
@@ -29,16 +47,60 @@ export interface SqlFileHistoryStoreOptions {
         warn(msg: string, meta?: Record<string, unknown>): void;
     };
 }
+/**
+ * The blob exchange (core's `FileHistoryStore.blobExchange` group — `put` / `get` / `has`, all three or none — narrowed per {@link ServiceBlobExchange})
+ * over the store's blob index. `get` / `has` are the index's own reads (`has` = SQL INDEX probes, batched, no bytes read).
+ */
+export declare class SqlBlobExchange implements ServiceBlobExchange {
+    private readonly blobs;
+    constructor(blobs: SqlBlobIndex);
+    /** 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) — the domain's
+     *  one byte write path ({@link SqlBlobLanding.putAt} writes through it).
+     *  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"). */
+    put(hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
+    get(hash: string): Promise<Uint8Array | undefined>;
+    has(hashes: readonly string[]): Promise<ReadonlySet<string>>;
+}
+/**
+ * Per-landing provenance over the same blob domain ({@link ServiceBlobLanding}): the session-sync routes' only blob face. Bytes go through the
+ * exchange (its `put` is the one write path, its `has` the one presence read); this face adds the grant rows (`file_history_blob_grant`) and the
+ * graph read that decide what a landing may see.
+ */
+export declare class SqlBlobLanding implements ServiceBlobLanding {
+    private readonly db;
+    private readonly exchange;
+    constructor(db: SqlDriver, exchange: ServiceBlobExchange);
+    /** Pick the dialect's SQL text (both statements stay written out at the call site, as in the store). */
+    private q;
+    /** The landing's owner cell as stored: the principal string, or the ownerless cell's domain key `""` (a principal is never the empty string). */
+    private static ownerKey;
+    /** `putAt`: verify the address → write the bytes (the exchange's one write path) → ONLY THEN upsert this landing's grant (`granted_at` refreshed
+     *  monotonically). A refused / failed byte write grants nothing — otherwise a landing whose own write was refused (a per-connection 413) would
+     *  see bytes another landing stored on a higher wall: an existence oracle again. A grant write that fails answers the write-fault arm (the bytes
+     *  are then an ungranted orphan the sweep collects — harmless). Never-throw, like the exchange's `put`: a failure is a value. */
+    putAt(landing: SyncLanding, hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
+    /** `visibleAt`: ((occupied ? this session's graph : ∅) ∪ this landing's grants) ∩ `hashes` ∩ present — three separate reads ON PURPOSE, so the
+     *  statement shape pins "only candidates are asked about presence" (a JOIN would let the optimizer probe the global index with the whole input
+     *  first): ① the graph's hashes, one read by the scope prefix (no IN; not repeated per batch); ② this landing's grants by PK, batched;
+     *  ③ presence of the candidates only, batched — none of these reads depends on what OTHER landings stored, so the time it takes doesn't
+     *  either. Read faults throw — out of this sealed exit as the store-boundary form (the routes map it by its fault class; never read as "not visible"). */
+    visibleAt(landing: SyncLanding, hashes: readonly string[]): Promise<ReadonlySet<string>>;
+}
 /** Dual-dialect durable FileHistoryStore. See the file header for posture + dialect-delta ledger. */
 export declare class SqlFileHistoryStore implements FileHistoryStore {
     protected readonly db: SqlDriver;
     /** RAW native pool — handed to the blob index (`blob-index-sql.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;
-    /** The blob exchange (core's `FileHistoryStore.blobExchange` group, see {@link ServiceBlobExchange}): how another machine's bytes
+    /** The blob exchange (core's `FileHistoryStore.blobExchange` group, see {@link SqlBlobExchange}): 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;
+    /** Per-landing provenance over the same blob domain ({@link SqlBlobLanding}): the session-sync routes' only blob face. */
+    readonly blobLanding: ServiceBlobLanding;
     /** This store's blob index (the `file_history_blob` rows; the byte port, when given, behind it). */
     protected readonly blobs: SqlBlobIndex;
     /** §10 S-6 in-process lease state (design v1 D2: NOT persisted). Keys = `${scope}\x00${entryId}`. */
@@ -89,6 +151,13 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      * The lock order itself stays single: sentinels first (sorted), then the scope's rows.
      */
     private lockScope;
+    /**
+     * The ensure-and-lock of {@link lockScope} **without** its restart — the statement source a transaction someone else opened runs (the
+     * landed section: its first statements lock the session's root row and judge the occupant, so a restart here would drop that lock and
+     * that judgement). A lost arbitration (a deadlock victim, or {@link ScopeSentinelVanishedError}, a `SqlArbitrationLostError`) propagates;
+     * the transaction's owner restarts from ITS top. Order: sentinels sorted, then the scope's rows (the one lock order).
+     */
+    lockScopeOn(conn: SqlTxConn, scopes: readonly string[]): Promise<void>;
     /** Returns the UPDATE's affected count — 0 = the record is gone (annulled) or was already observed;
      *  the caller disambiguates by re-reading (codex R1-high: answering minted:false after the baseline
      *  vanished would let a later touch mint already-modified bytes as pristine). */
@@ -164,15 +233,18 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      *  collected by the async grace-window sweep (never a synchronous external-store delete on the purge
      *  path). Also the overwrite-dst session-sync wipe seam (import requires an EMPTY target graph). */
     deleteBySession(scope: string): Promise<number>;
-    /** 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. */
+    /** The whole-scope removal as a statement source on the caller's transaction ({@link lockScopeOn} + {@link FILE_HISTORY_SCOPED_TABLES}, sentinel last):
+     *  {@link deleteBySession}'s body, and the landed section's wipe (one transaction with the session's root-row lock). Returns rows removed. */
+    deleteScopeOn(conn: SqlTxConn, scope: string): Promise<number>;
+    /** Delete one scope's rows from `tables` (caller holds the scope's sentinel lock). 第六表 `file_history_reaped_entry`(spent-entry 台账)与按落点的授予行随 scope 一起走:
+     *  E21 是删除权,台账 / 授予不是例外(表单 = {@link FILE_HISTORY_SCOPED_TABLES})。 */
+    private deleteScopeRowsOn;
+    /** Async byte-GC: one sweep = ONE cutoff (`now − BLOB_GC_GRACE_MS`, the index's single grace source) for both legs —
+     *  ① grant rows past the cutoff are dropped (an upload lease outlives the grace window, never less; a late / failed sweep only lengthens it,
+     *  and only at that same landing); ② orphans = blobs referenced by NO version row (any scope) AND by NO grant row (a live grant is an explicit
+     *  GC root — not inferred from timestamps), removed past the same cutoff on created_at. Domain-isolated by construction (this store's blob
+     *  tables only — [ref] D1). Reaper-driven. */
     sweepOrphanBlobs(): Promise<number>;
-    /** 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
@@ -190,6 +262,32 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      */
     private verifySourceBlobs;
     importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
+    /**
+     * 导入接住的一只故障的**唯一**折法(本店的图事务、准备步与落定段的发布步同读):core 7.55.0 —— `unsupported_format` 只说坏信封(或它的形驱动的活),
+     * 门之后撞上的故障(库拒了一份好图 / 重来用尽 / 连接断)是 `adopt_failed`,带接住的那只故障判得出的 `permanence`(判不出 ⇒ 不带)。
+     */
+    importFailureOf(err: unknown): FileHistoryError;
+    /**
+     * 导入的**事务外半**(`importHistory` 与落定段的重放同经它):门(core 的共享校验 + 本店的 mode 值域)→ 预读目标图(读不铸哨兵)判同图 / 异图 → 取值校验信封引用的每一枚 blob
+     * (首推 / 替换:校验过的字节续租进 blob 后端,发布前的孤儿清扫不收走它们;同图:只校验不回写)。`replace`(consented overwrite-dst 的落定重放)⇒ 异图不拒,按首推准备。
+     * 任何拒 ⇒ `ok: false`(店码);一个字节没发布。
+     */
+    prepareImport(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>, opts: {
+        readonly replace: boolean;
+    }): Promise<FileHistoryImportPlan>;
+    /**
+     * 导入的**发布步**,一只语句源跑在调用方的事务里(`importHistory` 自己的图事务 / 落定段):`same` ⇒ 不写;`publish` ⇒ scope 锁({@link lockScopeOn},不自己重开事务)→
+     * 事务内空目标复判(非破坏性目标律的 TOCTOU 关)→ 空 ⇒ 整图一步插入;已是这张图 ⇒ 不写;另一张图 ⇒ `replace` 下先删这一 scope 的图行(五表,哨兵留着 —— 本事务持着它)
+     * 再插(删与插同一事务:替换不会把目标留成空),否则 `conflict`、一个字节没写。
+     */
+    publishImportOn(conn: SqlTxConn, scope: string, data: FileHistoryExport, plan: Extract<FileHistoryImportPlan, {
+        ok: true;
+    }>, opts: {
+        readonly replace: boolean;
+    }): Promise<FileHistoryResult>;
+    /** The publish step's body under a held scope lock ({@link importHistory}: {@link lockScope} in the store's own transaction · {@link publishImportOn}:
+     *  {@link lockScopeOn} in the landed section). */
+    private publishImportLockedOn;
 }
 /** MySQL-protocol (TiDB) binding. */
 export declare class TiDBFileHistoryStore extends SqlFileHistoryStore {