@sema-agent/server 7.135.0 → 7.137.0

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

@@ -1,17 +1,30 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointGate, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolvedOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor, type StoreDurability, type StoreFidelity, type ToolApprovalCard } from "@sema-agent/core";
-import { type ParkRowFacts, type RuleOfferProjection } from "../approval-card.js";
+import { type ParkRowFacts, type RuleOfferProjection, type SkillCardFacts } from "../approval-card.js";
 import { type SqlDialect, type SqlDriver } from "./sql-driver.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
-/** M28 店腿的读数(两孪生同形;随 M28 删):扫到的可读行 · 回写成的行 · 回写成的行里被改写的值 · 读不出的行 · 封好之后一行装不下的行。 */
-export interface CtxRowsRewriteM28 {
+/** ctx 行改写店腿的读数(两孪生同形):扫到的可读行 · 回写成的行 · 回写成的行里改写函数报的改动数 · 读不出的行 · 改写之后一行装不下的行。 */
+export interface CtxRowsRewrite {
     readonly scanned: number;
     readonly rewritten: number;
     readonly valuesRewritten: number;
     readonly unreadable: number;
     readonly tooLarge: number;
 }
+/** 一行的改写:交回新的落盘形(只有封口模块的铸点产得出 —— 品牌型)与这一行的改动数;`undefined` = 这一行不写。 */
+export type CtxRowRewrite = (sessionId: string, ctx: object) => {
+    readonly ctx: SealedCheckpointCtx;
+    readonly values: number;
+} | undefined;
+/**
+ * 🔴 **一次性迁移的 ctx 行改写店腿**(两孪生:`SqlCheckpointStore` / `LocalCheckpointStore` 的 `rewriteCtxRows`;逐行判词两孪生同):扫全部 `checkpoint_ctx` 行、
+ * 交给 `rewrite`、交回新体的行原地回写(续跑时钟不动)。店不知道改写是什么 —— 用它的迁移各自带行改写:M28(凭据位明文封好)、M30(退役请求键改写)。
+ * 窗与删法逐条在 `plugins/one-time-migrations.ts` 登记表;登记表里最后一条用它的迁移删码时,本腿、读数型与扫描页一起删。
+ */
+export interface CheckpointCtxRowsRewriter {
+    rewriteCtxRows(rewrite: CtxRowRewrite): Promise<CtxRowsRewrite>;
+}
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 /**
  * [ref] D-1 (§3 invariant #3 — crash-safe reaper backstop): an ABSOLUTE upper bound on a pending
@@ -43,8 +56,11 @@ export declare function tokenFingerprint(token: string): string;
  *
  *  🔴 [ref]:行**顶层**另带 {@link ParkRowFacts}(`requiresRealApproval` / `ruleOffersAbsence`,真才带、缺席 ≠ false)——
  *  型与值都只有一个来源:`approval-card.ts` 的 {@link parkRowFacts}(两只店各读自己手里的那只寄存行 `pendingAction`,
- *  交给它、原样展开)。继承而不是在这里逐键再写一遍:core 给这一臂再加一位同类事实时,改的只有那张 Pick 表。 */
-export interface PendingCheckpoint extends ParkRowFacts {
+ *  交给它、原样展开)。继承而不是在这里逐键再写一遍:core 给这一臂再加一位同类事实时,改的只有那张 Pick 表。
+ *
+ *  技能卡三位({@link SkillCardFacts}:`boundGrantDigest` / `boundGrants` / `classifierNoRuling`)另有一只投影 {@link skillCardFacts},输入是 core 的检查点摘要而不是
+ *  寄存行原值(清单只在哈希等于摘要时才配上 wire,校验点单点在 core —— 见 {@link skillCardFacts} 顶注);同一张行上与收件箱行逐字同值,在场才带。 */
+export interface PendingCheckpoint extends ParkRowFacts, SkillCardFacts {
     sessionId: string;
     /**
      * 这道停驻门的**非秘密稳定身份**(core `Checkpoint.checkpointId`,引擎每次停驻铸)—— 三处 durable 读面(本行 = `GET /v1/approvals` 的 `pending[]`
@@ -660,6 +676,12 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * approval gate (facet `B`) is not here: core refuses `sla_timeout` on it pre-CAS, and reapExpired voids it. The filter is
      * in SQL, before the LIMIT: `limit` bounds the per-tick deny-resume work (each is a model run), never hides a row behind
      * rows the sweep does not own.
+     *
+     * Order ({@link CHECKPOINT_SWEEP_ORDER_SQL}): rows whose `approval_card` column carries a word come first, then rows whose card
+     * is NULL, each by deadline. A NULL card on an approval gate is either a gate the engine gave no card (a real SLA row) or a
+     * row a replica that does not know the column wrote during a mixed-version window — possibly a question, which the engine
+     * refuses to deny (`sla_timeout`) and which the next boot's M29 backfill settles. The column cannot tell the two apart, so the
+     * order does: rows whose facet is certain take the window first and a straggler cannot crowd them out.
      */
     listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
         sessionId: string;
@@ -676,6 +698,21 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * 真正需要它的读面是**已决行**的那一条:`findDecidedApprovalsForBinding`(decide 幂等回放),见那里。
      */
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
+    /**
+     * 🔴 [ref] —— 运维队列行的**技能卡三位**({@link SkillCardFacts})。值与收件箱行同源:core `summarizeCheckpoint` 对同一行投的摘要,经 {@link skillCardFacts} 这一只投影。
+     *
+     * 为什么不像 {@link parkRowFacts} 那几位一样直接读 `pendingAction` 子树原值:三位里的**清单** `boundGrants` 在寄存行上是未经哈希校验的原值,core 只在摘要里「哈希等于摘要」
+     * 才发布它(「never a list beside a digest that binds another」);校验读口与哈希函数都不在 core 的公开导出面上,本仓既算不出也不该再写一份 ——
+     * 于是要拿到校验过的清单,只有对这一行跑 core 的 `summarizeCheckpoint`,而它吃的是整只 {@link Checkpoint}(不是子树)。
+     *
+     * 读放大(如实):**只对行上真带三位之一的行**(摘要是串,或成因词键在场 —— {@link parkRowCarriesSkillCardFacts})多读该行一次整只快照;普通卡(绝大多数行)零额外读,
+     * 主 SELECT 仍只取 `pendingAction` 子树(NP-3 不退)。这是一个**只增不改的代价**:带三位之一的待决行数 × 读次数(`/stream` 每连接每 3s 一拍)。
+     * 🚧 清单校验读口成为 core 公开导出的那一版,本读口与门一并退役,三位改走 `parkRowFacts` 读原值经 core 的读口 —— 零额外读。
+     *
+     * 失败方向与 {@link readParkRowActionCell} 逐字同一条判据(展示/分诊材料、行级容忍 + 响亮、同一个 tag):整只快照在场却不是一只合法的检查点(读回的体坏了,或 core 的摘要读不动它)
+     * ⇒ 只丢**这一行**的三位;行已不在待决(两次读之间被决/过期)⇒ 三位缺席;`not-text`(读腿漏了投影)原样抛。
+     */
+    private readParkedSkillCardFacts;
     /**
      * [ref] #2 (scheduler seam, core 1.105): a scope's PENDING checkpoints as lightweight
      * {@link CheckpointSummary} rows in ONE query — the cross-task triage view a supervisor scheduler needs
@@ -808,17 +845,14 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
     getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
     /**
-     * 🔴 **一次性迁移 M28 的店腿**(窗与删法见 `plugins/one-time-migrations.ts` 登记表 M28;编排 = `checkpoint-ctx-seal-m28.ts`,行改写 =
-     * `http/checkpoint-ctx.ts` 的 `sealStoredCheckpointCtxM28`;本店不知道「封」是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`
+     * 🔴 **一次性迁移的 ctx 行改写店腿**({@link CheckpointCtxRowsRewriter};用它的迁移与各自的行改写见那里,窗与删法见 `plugins/one-time-migrations.ts` 登记表;
+     * 本店不知道改写是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`
      * (每页 {@link CTX_REWRITE_PAGE} 行,只取会话 id 与 ctx 文本),行体经读腿**同一只**判形({@link decodeCtxColumn})—— 读不出 ⇒ 计数、跳过、不动;
      * `rewrite` 交回新体 ⇒ 经写腿同一只编码与形闸,**按原文 CAS** 回写(MySQL 协议两边 `CAST(… AS BINARY)`,与 M17 / M18 同一条理由:连接排序规则大小写
      * 不敏感;PG `text` 等值)。`updated_at_ms` **不动**(收割按它判,迁移不许延长或缩短一行的寿命)。CAS 打空(扫描与回写之间这一行被续跑腿 / 别的副本写过)
-     * ⇒ 不计、不重试(新写者是本版就已封好;是旧版副本就由之后的起服再扫到)。一行装不下(封签比明文长)⇒ 计 `tooLarge`、那一行留原样,其余照扫。
+     * ⇒ 不计、不重试(新写者是本版写下的、已是新形;是旧版副本就由之后的起服再扫到)。一行装不下(如封签比明文长)⇒ 计 `tooLarge`、那一行留原样,其余照扫。
      */
-    rewriteCtxRowsM28(rewrite: (sessionId: string, ctx: object) => {
-        readonly ctx: SealedCheckpointCtx;
-        readonly values: number;
-    } | undefined): Promise<CtxRowsRewriteM28>;
+    rewriteCtxRows(rewrite: CtxRowRewrite): Promise<CtxRowsRewrite>;
     /**
      * GC ctx rows whose lifecycle is over (bound to the checkpoint, don't leak):
      * a session with NO pending checkpoint, NO active run, AND not touched since `cutoff`.

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

@@ -1,9 +1,9 @@
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
-import { CHECKPOINT_FACET_SQL, buildCheckpointIndexCells } 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 { 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 { redactDeep, redactSecrets } from "../trace/redact.js";
-import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, parkRowFacts, readRuleOfferList } 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, withoutCheckpointToken } from "../checkpoint-identity.js";
@@ -170,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" };
@@ -383,7 +381,10 @@ 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 cells = buildCheckpointIndexCells(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 toolInput = boundedToolInput(pa?.args);
         const ruleOffers = boundedRuleOffers(pa?.ruleOffers);
@@ -411,7 +412,7 @@ export class SqlCheckpointStore {
                 cells.risk_descriptor === null ? null : this.json(cells.risk_descriptor, "risk descriptor"),
                 ruleOffers === undefined ? null : this.json(ruleOffers, "rule offers"),
                 cells.has_bidi_controls,
-                cp.rev ?? 0,
+                checkpointRevOf(cp),
                 cp.reopenReason ?? null,
                 executionOutcome,
                 executionAtMs,
@@ -543,7 +544,7 @@ export class SqlCheckpointStore {
         return res.affected;
     }
     async listExpiredApprovalGates(cutoff, limit = 100) {
-        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 deadline ASC, token ASC 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 deadline ASC, token ASC LIMIT $2`), [cutoff, limit]);
+        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) {
@@ -555,7 +556,7 @@ export class SqlCheckpointStore {
         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 [];
@@ -564,28 +565,56 @@ export class SqlCheckpointStore {
             const boundInputHash = r.bound_input_hash ?? null;
             const ruleOffers = readRuleOffersCell(r.rule_suggestions);
             const approvalCard = parkedApprovalCard({ kind: gateKind, approvalCard: r.approval_card ?? undefined });
-            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 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 = [];
@@ -709,7 +738,7 @@ export class SqlCheckpointStore {
         const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);
         return rows[0] ? refusing("a resume context nobody can read", () => decodeCtxColumn(rows[0].ctx, `for session ${JSON.stringify(sessionId)}`)) : null;
     }
-    async rewriteCtxRowsM28(rewrite) {
+    async rewriteCtxRows(rewrite) {
         const out = { scanned: 0, rewritten: 0, valuesRewritten: 0, unreadable: 0, tooLarge: 0 };
         let after = "";
         for (;;) {
@@ -719,7 +748,7 @@ export class SqlCheckpointStore {
                 after = sessionId;
                 let ctx;
                 try {
-                    ctx = decodeCtxColumn(row.ctx, `for session ${JSON.stringify(sessionId)} (M28 scan)`);
+                    ctx = decodeCtxColumn(row.ctx, `for session ${JSON.stringify(sessionId)} (ctx row rewrite scan)`);
                 }
                 catch {
                     out.unreadable += 1;
@@ -730,13 +759,13 @@ export class SqlCheckpointStore {
                 if (next === undefined)
                     continue;
                 const text = this.json(next.ctx, "checkpoint ctx");
-                assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (M28 write)`);
+                assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (ctx row rewrite)`);
                 let affected;
                 try {
                     ({ affected } = await this.db.query(this.q("UPDATE checkpoint_ctx SET ctx = ? WHERE session_id = ? AND CAST(CAST(ctx AS CHAR) AS BINARY) = CAST(? AS BINARY)", "UPDATE checkpoint_ctx SET ctx = $1::jsonb WHERE session_id = $2 AND ctx::text = $3"), [text, sessionId, String(row.ctx)]));
                 }
                 catch (e) {
-                    const folded = rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (M28 write)`);
+                    const folded = rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (ctx row rewrite)`);
                     if (!(folded instanceof StoreRowTooLargeError))
                         throw folded;
                     out.tooLarge += 1;

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

@@ -165,6 +165,12 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /** 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. */

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

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
+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";
@@ -149,15 +149,8 @@ export class SqlFileHistoryStore {
                 const baseAvailable = truthy(t.rows[0].base_available);
                 const mintedBlobHash = v1.rows[0]?.blob_hash != null ? String(v1.rows[0].blob_hash) : null;
                 const proof = await worldStillMatchesMint(verify.env, absPath, root, baseAvailable, mintedBlobHash, verify.signal);
-                if (!proof.unchanged) {
-                    return {
-                        ok: false,
-                        error: {
-                            code: "conflict",
-                            message: `first-touch record for ${absPath} is NOT retractable: ${proof.reason} — the write this retraction compensates for may have changed the file, and deleting the only baseline of a modified file is worse than keeping a stale record`,
-                        },
-                    };
-                }
+                if (proof.verdict !== "unchanged")
+                    return annulProofFailure(proof, absPath);
             }
             const conn = await this.db.connect();
             try {
@@ -441,7 +434,7 @@ export class SqlFileHistoryStore {
                 let targetVersion = boundary.get(t.keyHash);
                 if (targetVersion === undefined) {
                     if (!t.baseAvailable) {
-                        ledger.refused.push({ path: t.trackKey, reason: "base_unavailable" });
+                        ledger.refused.push({ path: t.trackKey, reason: "base_unavailable", class: "base_unavailable" });
                         continue;
                     }
                     targetVersion = 1;
@@ -452,12 +445,12 @@ export class SqlFileHistoryStore {
                     continue;
                 }
                 if (rec.mode !== undefined && !(Number.isInteger(rec.mode) && rec.mode >= 0 && rec.mode <= 0o7777)) {
-                    ledger.refused.push({ path: t.trackKey, reason: `recorded mode ${String(rec.mode)} is not a valid POSIX permission value — refusing to apply a corrupted permission record` });
+                    ledger.failed.push({ path: t.trackKey, reason: `recorded mode ${String(rec.mode)} is not a valid POSIX permission value (store integrity) — refusing to apply a corrupted permission record` });
                     continue;
                 }
                 const resolved = fileHistoryResolveTrackKey(root, t.trackKey, t.keyDesc);
                 if (!resolved.ok) {
-                    ledger.refused.push({ path: t.trackKey, reason: resolved.reason });
+                    ledger.refused.push({ path: t.trackKey, reason: resolved.reason, class: resolved.class });
                     continue;
                 }
                 let applied;
@@ -488,7 +481,7 @@ export class SqlFileHistoryStore {
                 else if (applied.outcome === "identical")
                     ledger.identicalSkipped.push(t.trackKey);
                 else if (applied.outcome === "refused")
-                    ledger.refused.push({ path: t.trackKey, reason: applied.reason });
+                    ledger.refused.push({ path: t.trackKey, reason: applied.reason, class: applied.class });
                 else
                     ledger.failed.push({ path: t.trackKey, reason: applied.reason });
                 if ((applied.outcome === "applied" || applied.outcome === "identical") && applied.modeNotPreserved === true)
@@ -716,6 +709,29 @@ export class SqlFileHistoryStore {
             conn.release();
         }
     }
+    async verifySourceBlobs(data, srcGetBlob, onVerified) {
+        const needed = new Set();
+        for (const t of data.tracked)
+            for (const v of t.versions)
+                if (v.blobHash !== null)
+                    needed.add(v.blobHash);
+        for (const hash of needed) {
+            let bytes;
+            try {
+                bytes = await srcGetBlob(hash);
+            }
+            catch (err) {
+                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${foldCaughtFailure(err).text}` } };
+            }
+            if (bytes === undefined)
+                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
+            if (sha256hex(bytes) !== hash) {
+                return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fails content-address integrity — refused, nothing published` } };
+            }
+            await onVerified?.(hash, bytes);
+        }
+        return { ok: true };
+    }
     async importHistory(scope, data, srcGetBlob) {
         try {
             const shaped = validateFileHistoryExport(data);
@@ -733,31 +749,15 @@ export class SqlFileHistoryStore {
             if (!exported.ok)
                 return exported;
             const existing = exported.history;
-            if (existing !== null) {
-                if (fileHistoryExportDigest(existing) === fileHistoryExportDigest(data))
-                    return { ok: true };
+            const sameGraph = existing !== null && fileHistoryExportDigest(existing) === fileHistoryExportDigest(data);
+            if (existing !== null && !sameGraph) {
                 return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" already holds a DIFFERENT history — a first import requires an empty target and a retry is legal only for the identical envelope (atomic visibility prevents half-graphs; this law prevents publishing the wrong complete graph over locally-grown history)` } };
             }
-            const needed = new Set();
-            for (const t of data.tracked)
-                for (const v of t.versions)
-                    if (v.blobHash !== null)
-                        needed.add(v.blobHash);
-            for (const hash of needed) {
-                let bytes;
-                try {
-                    bytes = await srcGetBlob(hash);
-                }
-                catch (err) {
-                    return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${foldCaughtFailure(err).text}` } };
-                }
-                if (bytes === undefined)
-                    return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
-                if (sha256hex(bytes) !== hash) {
-                    return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fails content-address integrity — refused, nothing published` } };
-                }
-                await this.blobs.putBlob(hash, bytes);
-            }
+            const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.putBlob(hash, bytes));
+            if (!verified.ok)
+                return verified;
+            if (sameGraph)
+                return { ok: true };
             const conn = await this.db.connect();
             try {
                 await conn.begin();

package/dist/plugins/file-run-store.js

@@ -9,6 +9,7 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError, readLegacyHolderDeathCode } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
+import { readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 import { createInProcessSpaceCommitTable, fenceSpaceCommitAtTerminal, SPACE_COMMIT_RECORD_SCHEMA } from "../workspace-space-commit.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isParseableDate = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
@@ -140,16 +141,19 @@ export class FileRunStore {
         return this.spaceCommits.abandonSpaceCommit(spaceKey, taskId);
     }
     toRow(d) {
+        const { identitySource, identityScope, identityPrincipalInc, ...rest } = d;
         return {
-            ...d,
+            ...rest,
             idemKey: typeof d.idemKey === "string" ? d.idemKey : null,
             idemBodyFingerprint: typeof d.idemBodyFingerprint === "string" ? d.idemBodyFingerprint : null,
+            identity: readRunIdentityCells(identitySource, identityScope, identityPrincipalInc),
             createdAt: new Date(d.createdAt),
             updatedAt: new Date(d.updatedAt),
         };
     }
     toDisk(r) {
-        return { ...r, createdAt: r.createdAt.toISOString(), updatedAt: r.updatedAt.toISOString() };
+        const { identity, ...rest } = r;
+        return { ...rest, ...runIdentityCells(identity), createdAt: r.createdAt.toISOString(), updatedAt: r.updatedAt.toISOString() };
     }
     toRecord(r) {
         return {
@@ -162,6 +166,7 @@ export class FileRunStore {
             errorCode: r.errorCode,
             jobId: r.jobId,
             source: r.source,
+            identity: r.identity,
             instanceId: r.instanceId,
             cancelRequested: r.cancelRequested,
             objectivePreview: r.objectivePreview,
@@ -376,6 +381,7 @@ export class FileRunStore {
                 objectivePreview: meta.objectivePreview ?? null,
                 idemKey,
                 idemBodyFingerprint: meta.idem?.bodyFingerprint ?? null,
+                identity: meta.identity ?? null,
                 createdAt: now,
                 updatedAt: now,
                 cancelRequested: false,

package/dist/plugins/k8s-exec-protocol.d.ts

@@ -1,9 +1,51 @@
 /**
- * The confined, ADDITIVE pod-spec patch ({@link PodSpecPatch}/{@link applyPodSpecPatch}) + the exec-socket TLS
- * shape ({@link execSocketTlsOptions}) + the v4 channel status-frame parse ({@link exitCodeFromStatus}) — the
- * k8s adapter's protocol/patch layer, independent of pod lifecycle. Split out of `remote-env-k8s.ts` ([ref]
- * A13, internal-lossless — `remote-env-k8s.ts` re-exports every symbol below unchanged).
+ * The identity labels every sandbox pod carries — the ONE spelling (RBAC selectors, the reaper's listing and the egress self-check key on
+ * them; a pod-spec patch can add labels, never set or replace one of these).
  */
+export declare const SANDBOX_POD_LABELS: {
+    readonly app: "sema-sandbox";
+    readonly "managed-by": "sema-server";
+};
+/**
+ * The pod's owning run: label key, value = the server run id (the task id) of the TOP-LEVEL run whose env created the pod. Minted only by the
+ * adapter from `K8sEnvConfig.runId` (the per-run binding decides who has one); absent ⇒ the pod names no run, and the reaper removes it only once
+ * its containers have ended. An identity label: a patch can neither set nor replace it.
+ */
+export declare const SANDBOX_RUN_LABEL = "sema.io/run";
+/**
+ * The pod's own reaper hold: annotation key, value = the decimal milliseconds the reaper must wait after the owning run turned terminal before it
+ * removes the pod (`k8s-pod-reaper.ts` `sandboxRunEndHoldMs` of the CREATING replica's data bound). Written once, by the adapter, on every pod that
+ * carries {@link SANDBOX_RUN_LABEL} (the hold is only read for those); the reaper reads this and nothing else — never its own replica's config, so a
+ * rolling change of the snapshot bound never shortens another replica's pod. A pod-spec patch reaches labels only, never annotations.
+ */
+export declare const SANDBOX_RUN_END_HOLD_ANNOTATION = "sema.io/run-end-hold-ms";
+/** The two per-pod Secret seats: `env` = the pod's env Secret (the values `K8S_SANDBOX_ENV` names); `lease` = the member-credential broker's lease Secret. */
+export type SandboxSecretSeatKind = "env" | "lease";
+/**
+ * Per seat, the secrets verbs the adapter sends for it in the sandbox namespace — the ONE table, and each row is exactly that seat's calls:
+ * `env` = `create` (the env Secret, POSTed after its pod, never touched again); `lease` = `create` (the lease Secret) + `patch` (the lease rewrite,
+ * a merge-patch of `broker.json`). Nothing else: the adapter never reads a Secret back (no `get` — which would also let the service account read
+ * every Secret in the namespace) and never deletes one (no `delete`) — each Secret is owned by its pod (`ownerReferences`, `blockOwnerDeletion:
+ * false`), so the cluster's garbage collector removes it with the pod under its own identity. A seat in play asks only its own row: the boot gate
+ * (`K8S_SANDBOX_ENV` non-empty) asks `env`, the member-credential plane judge asks `lease` — an env-only deployment is never asked for `patch`.
+ * Readers: the SelfSubjectAccessReview (`readSandboxSecretSeat`), the refusal sentences that name the Role rule, the plane's off-reason text, the
+ * catalog sentence. `test/k8s-sandbox-secret.test.ts` pins row ≡ calls per seat, both directions.
+ */
+export declare const SANDBOX_SECRET_SEAT_VERBS: {
+    readonly env: readonly ["create"];
+    readonly lease: readonly ["create", "patch"];
+};
+export type SandboxSecretVerb = (typeof SANDBOX_SECRET_SEAT_VERBS)[SandboxSecretSeatKind][number];
+export declare function isLabelValue(v: string): boolean;
+/**
+ * The volume names the adapter itself mints on a sandbox pod — the ONE table (a patch volume / volumeMount must not reuse one: it would collide
+ * with, or mount, the adapter's own volume). Today: the space's build-cache claim and the member-credential broker's lease volume. A volume the
+ * adapter adds later is added HERE, and the patch judge below refuses it with no second guard.
+ */
+export declare const ADAPTER_VOLUME_NAMES: {
+    readonly cache: "ws-cache";
+    readonly brokerLease: "sema-broker-lease";
+};
 /**
  * The confined, ADDITIVE pod-spec patch. Every field is purely additive —
  * none can override the hard isolation invariants. This is the seam the RSI L8 immutable-mount probe + the
@@ -22,19 +64,32 @@ export interface PodSpecPatch {
     /** Extra labels merged into metadata.labels (e.g. a grader/probe tag). */
     labels?: Record<string, string>;
 }
-/**
- * Apply a {@link PodSpecPatch} to a sandbox pod object IN PLACE — purely ADDITIVE. Volumes + volumeMounts are
- * APPENDED (never replaced); securityContext objects are shallow-MERGED onto any existing; labels are merged. It
- * deliberately touches ONLY spec.volumes / spec.securityContext / containers[0].{volumeMounts,securityContext} /
- * metadata.labels — so the hard isolation invariants (runtimeClassName, automountServiceAccountToken,
- * restartPolicy, activeDeadlineSeconds, image, command) are preserved by construction. Pure + exported for testing.
- */
-export declare function applyPodSpecPatch(pod: {
+type SandboxPodShape = {
     metadata: {
         labels?: Record<string, string>;
     };
     spec: Record<string, unknown>;
-}, patch: PodSpecPatch): void;
+};
+/** Which pod a patch lands on: one that carries the broker container or not. */
+export interface PodPatchPresence {
+    readonly broker: boolean;
+}
+/**
+ * Apply a {@link PodSpecPatch} to a sandbox pod object IN PLACE — purely ADDITIVE, through the one field table
+ * ({@link POD_SPEC_PATCH_FIELDS}): a key outside the table is refused; EVERY present field is judged before ANY lands (a refusal leaves the pod
+ * byte-identical). Volumes + volumeMounts are APPENDED (never replaced); securityContext objects are shallow-MERGED onto any existing; labels are
+ * merged under the identity keys. It touches ONLY spec.volumes / spec.securityContext / containers[0].{volumeMounts,securityContext} /
+ * metadata.labels — so the hard isolation invariants (runtimeClassName, automountServiceAccountToken, restartPolicy, activeDeadlineSeconds, image,
+ * command) are preserved by construction. Throws (the caller surfaces it as a provisioning failure). Pure + exported for testing.
+ * `presence.broker` ⇒ the table's broker column judges first (see {@link POD_SPEC_PATCH_FIELDS}).
+ */
+export declare function applyPodSpecPatch(pod: SandboxPodShape, patch: PodSpecPatch, presence?: PodPatchPresence): void;
+/**
+ * The patch judge alone — the same one {@link applyPodSpecPatch} runs — for a pod that carries the broker: the refusal sentence, or `undefined`
+ * when the patch may land. The boot reads it on the deployment's static patch (a refusal turns the member-credential plane off,
+ * `pod_patch_reaches_broker`); the adapter runs it again on every pod it builds with the broker.
+ */
+export declare function podSpecPatchBrokerRefusal(patch: PodSpecPatch | undefined): string | undefined;
 /**
  * TLS options for the exec WebSocket, shaped for BOTH runtimes (2026-06-11 in-cluster drill finding):
  * Bun's `ws` shim IGNORES node-ws's top-level `ca`/`rejectUnauthorized` (handshake fails against a
@@ -50,4 +105,5 @@ export declare function exitCodeFromStatus(statusJson: string): {
 } | {
     error: string;
 };
+export {};
 //# sourceMappingURL=k8s-exec-protocol.d.ts.map