@sema-agent/server 7.134.0 → 7.136.0

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

@@ -1,17 +1,16 @@
-import { parkedApprovalCard, parkedFacetOf } from "../approval-content-kind.js";
+import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
-import { APPROVAL_GATE_KINDS_SQL_IN, denySweepOwns } from "../tool-approval.js";
-import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
+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, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
-import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, parkRowFacts, screenUncoveredDetailSeat } from "../approval-card.js";
+import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, parkRowCarriesSkillCardFacts, parkRowFacts, readRuleOfferList, skillCardFacts } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { durableRowIdentity } from "../checkpoint-identity.js";
+import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
-const REAP_CLASSIFY_BATCH = 200;
 const CTX_REWRITE_PAGE = 500;
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const MAX_TOOL_INPUT_CHARS = 8192;
@@ -82,36 +81,36 @@ function preboundBatchMembers(item) {
     return { ...candidate, rules: candidate.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS) };
 }
 export function boundedRuleOffers(raw, opts = {}) {
-    if (!Array.isArray(raw))
-        return undefined;
     const observe = opts.countRedactions ?? true;
     const scrub = (text) => redactSecrets(text, { observe }).slice(0, MAX_RULE_TEXT_CHARS);
+    const read = readRuleOfferList(Array.isArray(raw) ? raw.slice(0, MAX_RULE_OFFER_SCAN).map(preboundBatchMembers) : raw);
     const out = [];
-    for (const item of raw.slice(0, MAX_RULE_OFFER_SCAN)) {
+    for (const { offer } of read) {
         if (out.length >= MAX_RULE_OFFERS)
             break;
-        const parsed = RuleOfferRawSchema.safeParse(screenUncoveredDetailSeat(backfillLegacyBatchMemberKind(preboundBatchMembers(item))));
-        if (!parsed.success)
-            continue;
-        if (parsed.data.kind === "single") {
-            out.push({ kind: "single", rule: scrub(parsed.data.rule), match: parsed.data.match, command: scrub(parsed.data.command) });
-        }
-        else {
-            out.push({
-                kind: "batch",
-                rules: parsed.data.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS).map((r) => {
-                    switch (r.kind) {
-                        case "command":
-                            return { kind: "command", rule: scrub(r.rule), match: r.match, command: scrub(r.command), segment: scrub(r.segment) };
-                        case "directoryRead":
-                            return { kind: "directoryRead", rule: scrub(r.rule), directory: scrub(r.directory), segment: scrub(r.segment) };
-                        default:
-                            throw new Error(`unknown rule-offer batch member kind: ${JSON.stringify(r)}`);
-                    }
-                }),
-                uncoveredSegments: parsed.data.uncoveredSegments,
-                ...(parsed.data.uncoveredDetail !== undefined ? { uncoveredDetail: parsed.data.uncoveredDetail.map((d) => ({ segment: scrub(d.segment), reason: d.reason })) } : {}),
-            });
+        switch (offer.kind) {
+            case "single":
+                out.push({ kind: "single", rule: scrub(offer.rule), match: offer.match, command: scrub(offer.command) });
+                break;
+            case "batch":
+                out.push({
+                    kind: "batch",
+                    rules: offer.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS).map((r) => {
+                        switch (r.kind) {
+                            case "command":
+                                return { kind: "command", rule: scrub(r.rule), match: r.match, command: scrub(r.command), segment: scrub(r.segment) };
+                            case "directoryRead":
+                                return { kind: "directoryRead", rule: scrub(r.rule), directory: scrub(r.directory), segment: scrub(r.segment) };
+                            default:
+                                throw new Error(`unknown rule-offer batch member kind: ${JSON.stringify(r)}`);
+                        }
+                    }),
+                    uncoveredSegments: offer.uncoveredSegments,
+                    ...(offer.uncoveredDetail !== undefined ? { uncoveredDetail: offer.uncoveredDetail.map((d) => ({ segment: scrub(d.segment), reason: d.reason })) } : {}),
+                });
+                break;
+            default:
+                throw new Error(`unknown rule-offer kind: ${JSON.stringify(offer)}`);
         }
     }
     return out.length > 0 ? out : undefined;
@@ -171,18 +170,16 @@ function readRiskDescriptorCell(cell) {
         return null;
     }
 }
-function readParkRowFactsCell(cell) {
-    let pendingAction;
+function readParkRowActionCell(cell) {
     try {
-        pendingAction = decodeNullableJsonColumn(cell, readPendingActionMemberBody, "checkpoint.checkpoint $.pendingAction (operator queue row)");
+        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 {};
+        return undefined;
     }
-    return parkRowFacts(pendingAction);
 }
 const PARK_ROW_PENDING_ACTION = { key: "pendingAction", as: "pending_action" };
 const PARK_ROW_CHECKPOINT_ID = { key: "checkpointId", as: "checkpoint_id" };
@@ -197,28 +194,12 @@ function readCheckpointIdCell(cell) {
         return null;
     }
 }
-const PARK_ROW_GATE = { key: "gate", as: "park_gate" };
-function readParkGateCell(cell) {
-    try {
-        return decodeNullableJsonColumn(cell, readParkGateMemberBody, "checkpoint.checkpoint $.gate (approval card / expiry facet)");
-    }
-    catch (e) {
-        if (!isJsonColumnBodyProblem(e))
-            throw e;
-        recordFailOpen("server.approvals.park-row-blob-unreadable", "member=gate");
-        return undefined;
-    }
-}
-const readParkGateMemberBody = createObjectColumnReader();
 export function queueRowGateKind(kind) {
     if (isGateKind(kind))
         return kind;
     recordFailOpen("server.approvals.queue-row-gate-kind-missing", `gate_kind=${kind === null || kind === undefined ? "NULL" : redactSecrets(String(kind)).slice(0, 40)}`);
     return undefined;
 }
-function parkedGateOfRow(r) {
-    return { kind: r.gate_kind ?? undefined, approvalCard: readParkGateCell(r[PARK_ROW_GATE.as])?.approvalCard };
-}
 const readPendingActionMemberBody = createObjectColumnReader();
 export function boundedToolInput(args) {
     if (args === undefined)
@@ -400,34 +381,37 @@ export class SqlCheckpointStore {
         return { sql: `SELECT ${select} FROM checkpoint WHERE ${where.join(" AND ")} ORDER BY created_at_ms ${dir}, token ${dir} LIMIT 1`, params };
     }
     async put(token, cp) {
+        const judged = judgeCheckpointIndexCells(cp, this.db.dialect);
+        if (judged.kind !== "cells")
+            throw new CheckpointIndexRefusedError(cp.sessionId, judged);
+        const cells = judged.cells;
         const pa = cp.pendingAction;
-        const version = checkpointVersionOf(cp);
         const toolInput = boundedToolInput(pa?.args);
         const ruleOffers = boundedRuleOffers(pa?.ruleOffers);
-        const hasBidiControls = pa?.hasBidiControls === true ? 1 : null;
         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, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "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, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20::jsonb,$21)"), [
+            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) " +
+                "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) " +
+                "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)"), [
                 token,
-                cp.scope,
-                cp.sessionId,
-                version,
+                cells.scope,
+                cells.session_id,
+                cells.version,
                 cp.status,
-                pa?.toolName ?? null,
-                pa?.toolCallId ?? null,
+                cells.tool_name,
+                cells.tool_call_id,
                 toolInput === null ? null : this.json(toolInput, "approval tool_input"),
                 this.json(cp, "checkpoint"),
-                cp.deadline ?? null,
-                cp.createdAt,
+                cells.deadline,
+                cells.created_at_ms,
                 Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS),
-                cp.gate?.kind ?? null,
-                pa?.boundInputHash ?? null,
-                ((g) => (g?.riskDescriptor ? this.json(g.riskDescriptor, "risk descriptor") : null))(cp.gate),
+                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"),
-                hasBidiControls,
+                cells.has_bidi_controls,
                 cp.rev ?? 0,
                 cp.reopenReason ?? null,
                 executionOutcome,
@@ -555,54 +539,24 @@ export class SqlCheckpointStore {
     }
     async reapExpired(cutoff) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at_ms = ? " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN})) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN})) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
-        let n = res.affected;
-        const batch = await this.overdueApprovalRows(cutoff, REAP_CLASSIFY_BATCH, this.reapCursor);
-        for (const row of batch) {
-            if (!row.denySweeps && (await this.expire(row.token, row.scope)))
-                n++;
-        }
-        const last = batch.at(-1);
-        this.reapCursor = batch.length < REAP_CLASSIFY_BATCH || last === undefined ? undefined : { deadline: last.deadline, token: last.token };
-        return n;
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND COALESCE(${CHECKPOINT_FACET_SQL.tidb}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND COALESCE(${CHECKPOINT_FACET_SQL.pg}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
+        return res.affected;
     }
-    reapCursor;
     async listExpiredApprovalGates(cutoff, limit = 100) {
-        const hits = [];
-        let after;
-        while (hits.length < limit) {
-            const page = await this.overdueApprovalRows(cutoff, REAP_CLASSIFY_BATCH, after);
-            for (const r of page) {
-                if (hits.length < limit && r.denySweeps)
-                    hits.push({ sessionId: r.sessionId, scope: r.scope });
-            }
-            const last = page.at(-1);
-            if (page.length < REAP_CLASSIFY_BATCH || last === undefined)
-                break;
-            after = { deadline: last.deadline, token: last.token };
-        }
-        return hits;
-    }
-    async overdueApprovalRows(cutoff, limit, after) {
-        const head = `SELECT c.token, c.session_id, c.scope, c.gate_kind, c.deadline, ${jsonColumnText(this.db.dialect, "checkpoint", PARK_ROW_GATE)} FROM checkpoint c ` +
-            `WHERE c.status = 'pending' AND c.gate_kind IN ${APPROVAL_GATE_KINDS_SQL_IN} AND c.deadline IS NOT NULL AND `;
-        const { rows } = await this.db.query(after === undefined
-            ? head + this.q("c.deadline <= ? ORDER BY c.deadline ASC, c.token ASC LIMIT ?", "c.deadline <= $1 ORDER BY c.deadline ASC, c.token ASC LIMIT $2")
-            : head +
-                this.q("c.deadline <= ? AND (c.deadline > ? OR (c.deadline = ? AND c.token > ?)) ORDER BY c.deadline ASC, c.token ASC LIMIT ?", "c.deadline <= $1 AND (c.deadline > $2 OR (c.deadline = $3 AND c.token > $4)) ORDER BY c.deadline ASC, c.token ASC LIMIT $5"), after === undefined ? [cutoff, limit] : [cutoff, after.deadline, after.deadline, after.token, limit]);
-        return rows.map((r) => ({ token: String(r.token), sessionId: String(r.session_id), scope: String(r.scope), deadline: Number(r.deadline), denySweeps: denySweepOwns(parkedGateOfRow(r)) }));
+        const { rows } = await this.db.query(this.q(`SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ? AND ${CHECKPOINT_FACET_SQL.tidb} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= $1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $2`), [cutoff, limit]);
+        return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
     }
     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, ta.task_id, ` +
-            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_GATE)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)} ` +
+            `${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)} ` +
             "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])
             : await this.db.query(`${base} ORDER BY c.created_at_ms ASC`);
-        const out = rows.flatMap((r) => {
+        const entries = rows.flatMap((r) => {
             const gateKind = queueRowGateKind(r.gate_kind);
             if (gateKind === undefined)
                 return [];
@@ -610,36 +564,64 @@ export class SqlCheckpointStore {
             const toolCallId = r.tool_call_id ?? null;
             const boundInputHash = r.bound_input_hash ?? null;
             const ruleOffers = readRuleOffersCell(r.rule_suggestions);
-            const approvalCard = parkedApprovalCard(parkedGateOfRow(r));
-            return [{
-                    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: 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 } : {}),
-                    ...readParkRowFactsCell(r[PARK_ROW_PENDING_ACTION.as]),
-                }];
+            const approvalCard = parkedApprovalCard({ kind: gateKind, approvalCard: r.approval_card ?? undefined });
+            const pendingAction = readParkRowActionCell(r[PARK_ROW_PENDING_ACTION.as]);
+            const row = {
+                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: 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),
+            };
+            return [{ row, token: String(r.token), readSkillCard: parkRowCarriesSkillCardFacts(pendingAction) }];
         });
+        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("tidb", "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 {};
+        let cp;
+        try {
+            cp = decodeCheckpointColumn(r.checkpoint, "(operator queue row, skill-card facts)");
+        }
+        catch (e) {
+            if (!isJsonColumnBodyProblem(e))
+                throw e;
+            recordFailOpen("server.approvals.park-row-blob-unreadable");
+            return {};
+        }
+        try {
+            return skillCardFacts(summarizeCheckpoint(cp));
+        }
+        catch {
+            recordFailOpen("server.approvals.park-row-blob-unreadable");
+            return {};
+        }
+    }
     async listByScope(scope) {
         const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "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 out = [];
         for (const r of rows) {
             const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `in the ${scope} scheduler view`));
             cp.status = r.status;
-            out.push(summarizeCheckpoint(cp));
+            out.push(summarizeCheckpoint(cp, (sentence) => recordFailOpen("server.checkpoint.inbox-risk-axes-damaged", withoutCheckpointToken(sentence, cp.token))));
         }
         return out;
     }

package/dist/plugins/device-store-sql.d.ts

@@ -64,7 +64,7 @@ export declare const TIDB_DEVICE_STATEMENTS: readonly string[];
 /** {@link TIDB_DEVICE_STATEMENTS} 的遍历壳(集成测试用;生产装配由中央 ensureSchema 展开同一份数组)。 */
 export declare function ensureTiDBDeviceSchema(pool: MySqlPool): Promise<void>;
 type PgQuery = (sql: string, params?: unknown[]) => Promise<unknown>;
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgDeviceSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgDeviceSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const DEVICE_INDEXES: readonly IndexSpec[];
 export declare function ensurePgDeviceSchema(q: PgQuery): Promise<void>;
 /**
@@ -141,7 +141,7 @@ export declare class SqlDeviceStore implements DeviceStore {
      * 前提写在 {@link SqlTxConn.begin} 的 @contract txn.read-semantics。这把锁在 `devices` 表上,与下面
      * 被插入的 `device_session` 行不是同一行。
      *
-     * 🔴 形 B · cas-insert(S-127 / B-013)—— 本站点是全仓 `INSERT IGNORE` 的**正当用法**:
+     * 🔴 形 B · cas-insert([ref] / [ref])—— 本站点是全仓 `INSERT IGNORE` 的**正当用法**:
      * `INSERT IGNORE` / `ON CONFLICT DO NOTHING` 的 affected(1/0)是引擎对「谁赢」的**权威**回答,而
      * `ON DUPLICATE KEY UPDATE pk = pk` 的 affected 新行/既有行都是 1、分不出赢家 ⇒ 这里换不得动词。
      * 代价必须付清:**同一事务此后不得对被插入的那一行做加锁读**。InnoDB 下撞重复键的 IGNORE 在既有行
@@ -156,13 +156,13 @@ export declare class SqlDeviceStore implements DeviceStore {
      */
     bindSession(input: BindSessionInput): Promise<BindSessionResult>;
     /**
-     * 首绑 CAS 的**输家观察**(形 B 的后半,S-127)—— 独立事务,与那次 `INSERT IGNORE` 无锁关系。
+     * 首绑 CAS 的**输家观察**(形 B 的后半,[ref])—— 独立事务,与那次 `INSERT IGNORE` 无锁关系。
      *
      * 🔴 `FOR UPDATE`(**真库红修**,2026-08-28 双库跑当场抓到,mock 抓不到):TiDB 的悲观事务里**普通
      * SELECT 仍是快照读**(读的是本事务 start_ts 的视图),只有加锁读才是当前读。放在新事务里读同样要
      * 这把锁 —— 新事务的 start_ts 虽在赢家提交之后,但「读的是不是当前」这条判据不该靠时序巧合来满足。
      * 与旧形的**唯一**差别:此刻我们手上没有那一行的 S 锁,于是这把 X 是**直接取**的,不是升级 ⇒ 两个
-     * 并发输家不会互等(B-013 的死锁形正是那次升级)。
+     * 并发输家不会互等([ref] 的死锁形正是那次升级)。
      *
      * 行不在 = 赢家的绑定在这一瞬被 `unbindSession` 删了(真实可能,不是不变量破)。这仍然是**响亮**的:
      * 首绑既没成、也说不出冲突对象,折成任何一种业务回执都是撒谎([ref]:未知失败不伪装成正常拒绝)。
@@ -189,12 +189,13 @@ export declare class SqlDeviceStore implements DeviceStore {
     /**
      * 审计列表。
      *
-     * 🔴 **一行读不出形 ⇒ 整页拒,刻意不做逐行隔离**(S-550 修复验证轮,主会话裁定后入档):方向由设计
+     * 🔴 **一行读不出形 ⇒ 整页拒,刻意不做逐行隔离**([ref] 修复验证轮,主会话裁定后入档):方向由设计
      * §2「失败方向 = 拒(fail-closed),全店同向」定。逐行隔离(坏行跳过 / 占位)在**审计**面上尤其危险 ——
      * 它把「这一页少了一条」变得和「本来就没有那一条」同形,而审计面的全部意义就是「发生过的事都在」。
      * 一页 5xx 是响亮的运维事件,一条静默消失不是。
      *
-     * ⇒ 存量库里旧写腿留下的坏字节由**一次性迁移**清掉(`one-time-migrations.ts` M4),不靠读侧容忍。
+     * ⇒ 存量库里旧写腿留下的坏字节(JSON 文本 `null`)7.93.5 起由启动期一次性迁移清过、窗关后已删码,读侧不容忍:
+     *   跳过了那些版本直接升的库,含这种行的那一页读不出来,拒句点名行 id,出路是运维把那些行的 `detail` 置成 SQL NULL(MIGRATION 写了语句)。
      */
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
 }

package/dist/plugins/e2b-orphan-reclaim.d.ts

@@ -10,7 +10,7 @@
  * memory `capability-probe-fail-direction`;误杀的代价是杀死一个活任务的手,漏杀的代价只是钱):
  *   a. `metadata.semaManaged !== "1"`         → 非我方铸造,provider 侧 query 过滤已排除;防御性重验。
  *   b. `metadata.taskId` 缺席                 → 病态形(factory 恒打标),不杀 + failOpen 留痕。
- *   c. run 行在场(词 → 类问 `RUN_STATUS_CLASS` 属主,S-221):
+ *   c. run 行在场(词 → 类问 `RUN_STATUS_CLASS` 属主,[ref]):
  *        类 live / parked(行还能再动)        → 活,跳过;
  *        类 succeeded / unsuccessful(终局)   → 孤儿,kill;
  *        属主表外的词(类 undefined)          → 词表纪律([ref]):不杀 + failOpen(新词先安全后收编)。

package/dist/plugins/ensure-schema-lock-policy.d.ts

@@ -1,7 +1,7 @@
 /**
  * 两方言启动锁(`ensureSchema` / `oneTimeMigrations` 的 MySQL `GET_LOCK(?,0)` 与 PG `pg_try_advisory_lock`)的
  * **轮询策略唯一属主**(7.83.0 修复验证 车HC HC-1/HC-2 后收口:此前两只孪生各抄一份循环,一份改了「永不放弃」
- * 另一份还是「40 次放弃后无锁跑」,而 S-287 之后无锁跑的那条腿发的是不带 `IF NOT EXISTS` 的 `ADD INDEX`,两副本
+ * 另一份还是「40 次放弃后无锁跑」,而 [ref] 之后无锁跑的那条腿发的是不带 `IF NOT EXISTS` 的 `ADD INDEX`,两副本
  * 双发 ⇒ 输的那只拒启)。方言只提供「试一次」的探针,循环、抖动、退避、进展 warn、坏连接上抛全在这里。
  *
  * 三条律:

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

@@ -1,6 +1,6 @@
 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 } from "@sema-agent/core";
+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 SqlDriver } from "./sql-driver.js";
@@ -63,9 +63,9 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      * 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.
      *
-     * Shape A (S-127): the MySQL ensure verb is `ON DUPLICATE KEY UPDATE scope = scope`, NOT `INSERT IGNORE`.
+     * 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 (B-013). ON
+     * 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.
      */
     private lockScope;
@@ -82,7 +82,7 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     }): Promise<FileHistoryResult>;
     /** `forUpdate` = the {@link SqlTxConn.begin} `@contract txn.read-semantics` ③ arm: a collection read that
      *  runs inside a transaction must be a LOCKING read (a plain SELECT is pinned to the transaction's start on
-     *  TiDB, so the lock-wait window's commits are invisible — B-022). Pool-level callers pass nothing. */
+     *  TiDB, so the lock-wait window's commits are invisible — [ref]). Pool-level callers pass nothing. */
     private loadTracked;
     /** `forUpdate` — see {@link loadTracked}: inside a transaction this is a collection read, so it locks. */
     private loadVersions;
@@ -116,7 +116,7 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     protected duringRestorePlan(_scope: string, _entryId: string): Promise<void>;
     /** PROTECTED RACE SEAM (test-only override): runs inside the publish tx AFTER `begin()` and BEFORE
      *  the scope lock — the window where another replica's publish can commit while this tx's snapshot is
-     *  already pinned. That window is exactly what B-022 rode: a plain SELECT taken after the lock is still
+     *  already pinned. That window is exactly what [ref] rode: a plain SELECT taken after the lock is still
      *  pinned to the transaction's start, so this tx's collection reads are LOCKING reads
      *  ({@link SqlTxConn.begin} → `@contract txn.read-semantics`). Production body is empty. */
     protected beforePublishLock(_scope: string): Promise<void>;
@@ -160,9 +160,17 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** `forUpdate` — see {@link loadTracked}. Every in-transaction caller passes `true`: the four reads are
      *  one graph, and a graph materialized from a start-of-transaction snapshot disagrees with the LOCKING
      *  emptiness probe that decided to materialize it (that disagreement answered a legal idempotent
-     *  re-import as `conflict` — B-022). */
+     *  re-import as `conflict` — [ref]). */
     private exportOf;
-    exportHistory(scope: string): Promise<FileHistoryExport | null>;
+    /** core 7.55.0 `FileHistoryExportResult`:本店的图在 scope 锁内一事务物化,读得出就是整图(`{ ok: true, history }`;空 scope ⇒ `history: null`);
+     *  库读失败照常抛(读故障不是答案)—— 本店没有「撕裂 / 读不出的边界」这一形(边界与映射同事务落),所以不答 `{ ok: false }`。 */
+    exportHistory(scope: string): Promise<FileHistoryExportResult>;
+    /**
+     * Fetch + content-address verify EVERY blob the envelope references from the source, one at a time (memory bounded by one blob) —— 首推与同图重推共用的**唯一**取值校验;
+     * 任何一枚取不出 / 核不过 ⇒ 整信封典型拒,什么都不发布。`onVerified` = 校验过的这一枚拿来做什么:首推传「续租式 upsert」(delete-in-use 租约 —— 发布前的孤儿清扫不许收走
+     * 这次导入正要引用的字节);同图重推不传 —— 已发布的图的版本行本身就是引用,租约无事可护,而回写会把每只对象重传一遍(MinIO 的 `putBlob` 是整体 PUT)。
+     */
+    private verifySourceBlobs;
     importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
 }
 /** MySQL-protocol (TiDB) binding. */