@sema-agent/server 7.148.0 → 7.150.0

package/dist/store-posture.d.ts

@@ -4,6 +4,7 @@ import type { StoreBackend } from "./plugins/store-backend.js";
 import type { SqlEngineFacts } from "./plugins/sql-driver.js";
 import { type SqlEngineCapability } from "./sql-engine-posture.js";
 import { type MountRow, type MountTable } from "./mountinfo.js";
+import type { LocalStoreDeclaration } from "./local-store-declaration.js";
 /**
  * 降级词闭集(**按后端族**,不按失败发生在哪一步):
  *  · `local_unwritable` —— **缺省推导**的 local 文件店在**空 / 不存在**的数据根上构造期失败(mkdir / 权限 / 只读挂载 / 磁盘满)。
@@ -124,10 +125,13 @@ export interface StorePosture {
     readonly durability: StoreDurability;
     /** 逐根明细:恒以数据根开头;有起服证据时再接封签钥匙目录与(接线时的)file 记忆根。 */
     readonly roots: readonly StoreRootDurability[];
+    /** local 店交给两半店的声明(present-iff 装配出 local 后端;值 = 后端构造时 `localStoreDeclarationOf` 的那一份,装配方从后端读回,不重算)。 */
+    readonly localDeclaration?: LocalStoreDeclaration;
 }
 /**
  * `build*`(纯数据)。`assembled` = 装配出的 `StoreBackend.kind`;缺席 = 没装出后端 ⇒ `memory`。`evidence` 缺席 = 这个宿主没有起服证据(测试夹具 / 桩):
  * 只判数据根、且只按后端规则判(local 无证据即抛)。`memoryRootWired` = file 记忆引擎在本部署上真接了线(配了才算;没接线的记忆根不进最弱律)。
+ * `localDeclaration` = 装配出的 local 后端交给两半店的那一份声明(装配出 local 而缺席 = 装配缺陷,响亮抛;别的后端递了也不收)。
  */
 export declare function buildStorePosture(a: {
     readonly declared: StoreBackendWord;
@@ -135,6 +139,7 @@ export declare function buildStorePosture(a: {
     readonly degradedReason: StoreDegradedReason | undefined;
     readonly evidence: StoreEvidence | undefined;
     readonly memoryRootWired: boolean;
+    readonly localDeclaration: LocalStoreDeclaration | undefined;
 }): StorePosture;
 /** 读面桩的诚实下限(没有装配值的宿主:声明 = 配置词,后端 = memory ⇒ `ephemeral`)。caps 与 `/health` 同调这一只。 */
 export declare function unwiredStorePosture(declared: StoreBackendWord): StorePosture;

package/dist/store-posture.js

@@ -176,10 +176,27 @@ export function buildStorePosture(a) {
         ...(a.degradedReason !== undefined ? { degradedReason: a.degradedReason } : {}),
         durability: weakestDurability(roots.map((r) => r.verdict)),
         roots,
+        ...localDeclarationOf(backend, a.localDeclaration),
     };
 }
+function localDeclarationOf(backend, declaration) {
+    switch (backend) {
+        case "local":
+            if (declaration === undefined)
+                throw new Error("store posture: a local backend was assembled without the declaration it handed its stores — wiring defect (read it back from the backend)");
+            return { localDeclaration: declaration };
+        case "memory":
+        case "mysql":
+        case "pg":
+            return {};
+        default: {
+            const unhandled = backend;
+            throw new Error(`store posture: unknown backend kind ${String(unhandled)}`);
+        }
+    }
+}
 export function unwiredStorePosture(declared) {
-    return buildStorePosture({ declared, assembled: undefined, degradedReason: undefined, evidence: undefined, memoryRootWired: false });
+    return buildStorePosture({ declared, assembled: undefined, degradedReason: undefined, evidence: undefined, memoryRootWired: false, localDeclaration: undefined });
 }
 export function buildStoreFreshStartLine(posture, evidence) {
     if (posture.backend !== "local" || evidence.dataRootHeldData)

package/dist/stores-sql/checkpoint-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 ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
+import { type CheckpointPage, type CheckpointRowRead, type CheckpointSessionCursor, type CheckpointSessionQuery, type ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
 import { type SqlDialect, type SqlDriver } from "../plugins/sql-driver.js";
 import type { CtxWriteClaim } from "../plugins/store-contracts.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
@@ -40,7 +40,7 @@ export declare const CHECKPOINT_ADDED_COLUMNS: ReadonlyArray<{
  *
  * 判据 = **能力探测**(恒空的 `WHERE 1=0` 读)+ **方言的缺列错误码**({@link isMissingColumnError},
  * 判据属主 `sql-errors.ts`);其余错误**原样 rethrow**,一个字都不加工 —— 把一次瞬时故障诊断成「缺列」的拒因
- * 比它要挡的缺陷更贵([ref] 两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift}),
+ * 比它要挡的缺陷更贵([ref] 两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link probedMissingColumnRefusal}),
  * 没有销毁性的一条:这张表里是在飞的停驻,出路是原表上加列。
  *
  * 位置:与三条先例同款,不在 `ensureSchema` 里(那条通道的契约是「只发 CREATE」),放在 boot 的
@@ -72,7 +72,6 @@ interface SteerColumnRead {
  * 列有内容却读不出 ⇒ `lossy`(两个调用点对它的处置见 {@link SteerColumnRead})。
  */
 export declare function readPendingSteerQueueColumn(queueRaw: unknown): SteerColumnRead;
-/** SQL checkpoint 店的装配选项:托管留存声明。(ctx 栅栏写口的认领由调用方每次交进来 —— [ref]:栅栏的来源是认领本身,店不另绑 run 店。) */
 export interface SqlCheckpointStoreOptions {
     readonly retention?: RetentionDeclaration;
 }
@@ -162,7 +161,27 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     private pendingRowQuery;
     /** Create-once. core mints the token (`mintCheckpointToken`) and calls this during suspend. */
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
+    /** 一行的列组 —— `get` 与按会话列表读同一份投影、交同一只解码({@link readStoredCheckpoint})。 */
+    private storedCheckpointColumns;
     get(token: CheckpointToken): Promise<Checkpoint | null>;
+    /**
+     * 一行字节 → 检查点 —— **`get` 与按会话列表({@link listBySession})的唯一解码**(列组 = {@link storedCheckpointColumns})。读不成的格交回 `damaged`
+     * (`get` 原样抛那只拒绝,列表把这一行答 `unreadable`);非体问题(读腿漏投影 `not-text` / 连接)原样抛 —— 码坏不冒充一行数据坏。
+     */
+    private readStoredCheckpoint;
+    /**
+     * core `CheckpointStore.listBySession`(可选动词,按在不在探;core 7.66.0 契约):一只会话的行,任何状态,按查询的成员收窄、按 `createdAt` 再按令牌排、键集分页。
+     * **读法只有 core 那一只**:查询经 `readCheckpointSessionQuery` 读(坏查询在任何 SQL 之前带码拒),过滤 / 排序 / 游标 / 截断 / 损坏判 全由 core 的 `selectSessionPage` 答
+     * (内存店与文件店同调它);本店只交「这只会话的行」—— 按会话列(`session_id`,本店每一只按会话的读口同读这一列)取行,经 `get` 的同一只解码({@link readStoredCheckpoint})成检查点。
+     * SQL 只按会话收窄,别的成员(状态 / scope / 门型 / 工具调用 / 建行时刻)一律由 core 判 —— 列上的比较不是 core 的比较(MySQL 协议的 `utf8mb4_bin` 按补空格比,
+     * 带尾空格的集外状态词会被 SQL 当成三词之一排除,而 core 要把它答成 `unreadable`),所以 SQL 不预筛任何一格,预筛不可能排除 core 会留下的行。
+     * 读成本:这只会话的每一行读一份字节(检查点体 + 旁格)—— 只在页里的行交出去;会话的行数由留存扫车道界住。
+     * 一行读不成(体不是一只检查点 / 决议或执行记录那一格读不出 / 体没说出它归在的这只会话)⇒ 这一行**照列**为 `unreadable`(令牌 / scope / 会话 / 状态 / 建行时刻取本店在字节之外
+     * 握着的列组;体读成、归属对而旁格坏 ⇒ 过滤器照读体上的成员),不跳过、不让整页失败;拿它的令牌去 `get` 撞见同一只拒。体是对象而成员形读不动 ⇒ core 自己答 `unreadable`。
+     * 页里每一只这样的行计一次 `server.approvals.park-row-blob-unreadable`(本店停驻行读者的那一条律:一行的字节只坏它自己那一行):core 判的经它给的座(句子去掉令牌后作探针),
+     * 本店判、core 看着读得动的那几行由本店计。只读:列表不改任何一行;交出的行是这一次解码的新对象,改它不改库。
+     */
+    listBySession(query: CheckpointSessionQuery): Promise<CheckpointPage<CheckpointRowRead, CheckpointSessionCursor>>;
     /**
      * Atomic CAS: pending → resolved, scoped. Returns true for the single winner, false if already
      * resolved/expired (AlreadyResolved → caller no-ops, never re-executes). `outcome` is persisted atomically

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

@@ -1,14 +1,14 @@
 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, } from "@sema-agent/core";
+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, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
+import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, isJsonObject, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { durableRowIdentity, 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 { describeProbedTableDrift } from "../plugins/schema-drift-sentence.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";
@@ -77,12 +77,10 @@ export async function assertCheckpointColumnSchema(query, dialect) {
         catch (err) {
             if (!isMissingColumnError(err, dialect))
                 throw err;
-            throw new Error(`checkpoint is missing the column ${column} — refusing to start. ` +
+            throw await probedMissingColumnRefusal(query, dialect, ["checkpoint"], `checkpoint is missing the column ${column} — refusing to start. ` +
                 `On this table ${breaksAt} — at runtime, after a healthy-looking boot. ` +
                 "The table holds IN-FLIGHT durable parks (suspended approvals/reviews awaiting a decision), so the way forward is an in-place " +
-                "ALTER that keeps them; `checkpoint_ctx`, run rows and every other persistent face are untouched.\n" +
-                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-                (await describeProbedTableDrift(query, dialect, ["checkpoint"])));
+                "ALTER that keeps them; `checkpoint_ctx`, run rows and every other persistent face are untouched.", err);
         }
     }
 }
@@ -244,6 +242,12 @@ export function readPendingSteerQueueColumn(queueRaw) {
 }
 const STEER_CAS_ATTEMPTS = 8;
 const EXECUTION_RECORD_CAS_ATTEMPTS = 8;
+const STORED_ROW_DAMAGE = {
+    body: "its stored body is not a checkpoint object",
+    decision: "its stored decision record cannot be read",
+    execution: "its stored execution record cannot be read",
+    filing: "its stored body does not name the session the row is filed under",
+};
 export class SqlCheckpointStore {
     db;
     logger;
@@ -339,21 +343,62 @@ export class SqlCheckpointStore {
             throw rowTooLargeOrSelf(this.db.dialect, e, `the checkpoint row for session ${JSON.stringify(cp.sessionId)}`);
         }
     }
+    storedCheckpointColumns() {
+        const d = this.db.dialect;
+        return (`status, ${jsonColumnText(d, "checkpoint")}, ${jsonColumnText(d, "outcome")}, reopen_reason, rev, ` +
+            `${jsonColumnText(d, "pending_steer_queue")}, ${jsonColumnText(d, "execution_outcome")}, execution_at_ms`);
+    }
     async get(token) {
-        const { rows } = await this.db.query(this.q(`SELECT status, ${jsonColumnText("mysql", "checkpoint")}, ${jsonColumnText("mysql", "outcome")}, reopen_reason, rev, ` +
-            `${jsonColumnText("mysql", "pending_steer_queue")}, ${jsonColumnText("mysql", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = ?`, `SELECT status, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnText("pg", "outcome")}, reopen_reason, rev, ` +
-            `${jsonColumnText("pg", "pending_steer_queue")}, ${jsonColumnText("pg", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = $1`), [token]);
+        const { rows } = await this.db.query(`SELECT ${this.storedCheckpointColumns()} FROM checkpoint WHERE token = ${this.ph(1)}`, [token]);
         const r = rows[0];
         if (!r)
             return null;
-        const cp = readCheckpointBodyOrRefuse(r.checkpoint, `for token ${tokenFingerprint(token)}`);
+        const read = this.readStoredCheckpoint(r, token);
+        if (read.kind === "damaged")
+            throw read.error;
+        const cp = read.checkpoint;
+        this.logger?.info?.("checkpoint_get", {
+            tokenFp: tokenFingerprint(token),
+            status: cp.status,
+            hasWorkspaceHandle: !!cp.state?.workspaceHandle,
+            snapshotId: cp.state?.workspaceHandle?.snapshotId,
+        });
+        return cp;
+    }
+    readStoredCheckpoint(r, token) {
+        const where = `for token ${tokenFingerprint(token)}`;
+        let cp;
+        try {
+            cp = readCheckpointBodyOrRefuse(r.checkpoint, where);
+        }
+        catch (e) {
+            if (e instanceof StoreCorruptError)
+                return { kind: "damaged", member: "body", error: e };
+            throw e;
+        }
         cp.status = r.status;
-        const outcomeRaw = refusing("a decision record nobody can read", () => decodeOutcomeColumn(r.outcome, `for token ${tokenFingerprint(token)}`));
+        let outcomeRaw;
+        try {
+            outcomeRaw = refusing("a decision record nobody can read", () => decodeOutcomeColumn(r.outcome, where));
+        }
+        catch (e) {
+            if (e instanceof StoreCorruptError)
+                return { kind: "damaged", member: "decision", error: e, body: cp };
+            throw e;
+        }
         if (outcomeRaw)
             cp.resolvedOutcome = winnerFromOutcome(outcomeRaw);
         cp.reopenReason = r.reopen_reason ?? undefined;
         cp.rev = r.rev == null ? 0 : Number(r.rev);
-        const executionOutcome = refusing("an execution record nobody can read", () => decodeExecutionOutcomeColumn(r.execution_outcome, `for token ${tokenFingerprint(token)}`));
+        let executionOutcome;
+        try {
+            executionOutcome = refusing("an execution record nobody can read", () => decodeExecutionOutcomeColumn(r.execution_outcome, where));
+        }
+        catch (e) {
+            if (e instanceof StoreCorruptError)
+                return { kind: "damaged", member: "execution", error: e, body: cp };
+            throw e;
+        }
         if (executionOutcome !== undefined) {
             cp.executionOutcome = executionOutcome;
             if (r.execution_at_ms != null)
@@ -364,17 +409,58 @@ export class SqlCheckpointStore {
             recordFailOpen("server.sql-json.checkpoint.pending-steer-queue-lossy");
             this.logger?.info?.("checkpoint_pending_steer_unreadable", { tokenFp: tokenFingerprint(token) });
         }
-        if (cp.state) {
-            if (steer.state.pendingSteerQueue !== undefined)
-                cp.state.pendingSteerQueue = steer.state.pendingSteerQueue;
-        }
-        this.logger?.info?.("checkpoint_get", {
-            tokenFp: tokenFingerprint(token),
-            status: cp.status,
-            hasWorkspaceHandle: !!cp.state?.workspaceHandle,
-            snapshotId: cp.state?.workspaceHandle?.snapshotId,
+        if (isJsonObject(cp.state) && steer.state.pendingSteerQueue !== undefined)
+            cp.state.pendingSteerQueue = steer.state.pendingSteerQueue;
+        return { kind: "row", checkpoint: cp };
+    }
+    async listBySession(query) {
+        const read = readCheckpointSessionQuery(query);
+        const { rows } = await this.db.query(`SELECT token, scope, session_id, created_at_ms, ${this.storedCheckpointColumns()} FROM checkpoint WHERE session_id = ${this.ph(1)}`, [read.sessionId]);
+        const tokens = rows.map((r) => String(r.token));
+        const withoutTokens = (sentence) => tokens.reduce((out, t) => withoutCheckpointToken(out, t), sentence);
+        const damaged = new Map();
+        const candidates = [];
+        rows.forEach((r, i) => {
+            const token = tokens[i];
+            const got = this.readStoredCheckpoint(r, token);
+            const body = got.kind === "row" ? got.checkpoint : got.member === "body" ? undefined : got.body;
+            const filedHere = body !== undefined && body.sessionId === String(r.session_id);
+            if (got.kind === "row" && filedHere) {
+                candidates.push([token, body]);
+                return;
+            }
+            damaged.set(token, { problem: STORED_ROW_DAMAGE[got.kind === "damaged" ? got.member : "filing"], r, counted: filedHere });
+            if (filedHere) {
+                candidates.push([token, body]);
+                return;
+            }
+            const filing = { token: token, sessionId: String(r.session_id), scope: String(r.scope), status: String(r.status), createdAt: Number(r.created_at_ms) };
+            candidates.push([token, filing]);
         });
-        return cp;
+        const page = selectSessionPage(candidates, read, (cp) => cp, (sentence) => recordFailOpen("server.approvals.park-row-blob-unreadable", withoutTokens(sentence)));
+        if (damaged.size === 0)
+            return page;
+        return {
+            ...page,
+            rows: page.rows.map((row) => {
+                const token = row.kind === "row" ? row.checkpoint.token : row.token;
+                const hit = damaged.get(token);
+                if (hit === undefined)
+                    return row;
+                if (hit.counted && row.kind === "row")
+                    recordFailOpen("server.approvals.park-row-blob-unreadable", `session listing, session ${JSON.stringify(String(hit.r.session_id))}: ${hit.problem} — listed as unreadable`);
+                const createdAt = Number(hit.r.created_at_ms);
+                return {
+                    kind: "unreadable",
+                    token: token,
+                    scope: String(hit.r.scope),
+                    sessionId: String(hit.r.session_id),
+                    status: String(hit.r.status),
+                    createdAt: Number.isFinite(createdAt) ? createdAt : null,
+                    problem: hit.problem,
+                };
+            }),
+        };
     }
     async resolve(token, scope, outcome, expect) {
         const params = [this.json(outcome, "checkpoint outcome"), Date.now(), token, scope];

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

@@ -208,7 +208,7 @@ export declare class PgFileHistoryStore extends SqlFileHistoryStore {
  * ONLY a provable missing-column error gets the missing-column refusal — everything else
  * (timeout / reset / permission / missing table) rethrows untouched: diagnosing a connection blip as a
  * schema drift is more expensive than the defect this gate exists to stop. The refusal's ways out are the
- * closed set of three shared with the whole-database check (`describeProbedTableDrift`); none of them
+ * closed set of three shared with the whole-database check (`probedMissingColumnRefusal`); none of them
  * is destructive. Honest cost statement: the history lives in these tables (per-file REWIND history,
  * working-tree convenience state) — session transcripts and every other durable subsystem are untouched.
  */

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

@@ -3,7 +3,7 @@ import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenD
 import { BlobTooLargeError, SqlBlobIndex } from "./blob-index-sql.js";
 import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
 import { isMissingColumnError, retryOnDeadlock } from "../plugins/sql-errors.js";
-import { describeProbedTableDrift } from "../plugins/schema-drift-sentence.js";
+import { probedMissingColumnRefusal } from "../plugins/schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
 export const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -844,12 +844,10 @@ export async function assertFileHistorySchema(query, dialect) {
         catch (err) {
             if (!isMissingColumnError(err, dialect))
                 throw err;
-            throw new Error(`${table} is missing required columns — refusing to start. This build's per-file rewind history (S-15) ` +
+            throw await probedMissingColumnRefusal(query, dialect, [table], `${table} is missing required columns — refusing to start. This build's per-file rewind history (S-15) ` +
                 `references every probed column unconditionally; a partial table would fail mid-write and could publish a ` +
                 `half-shaped history graph. The file_history_* tables hold the per-file REWIND history (working-tree convenience ` +
-                `state); session transcripts and all other durable subsystems are untouched, and an in-place ALTER keeps the history.\n` +
-                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-                (await describeProbedTableDrift(query, dialect, [table])));
+                `state); session transcripts and all other durable subsystems are untouched, and an in-place ALTER keeps the history.`, err);
         }
     }
 }

package/dist/stores-sql/retention-store-sql.d.ts

@@ -1,7 +1,7 @@
 /**
  * 托管留存(managed retention)的**执行器** —— 引擎座表那一半(阶段三逐字搬进 `@sema-agent/core-stores-sql` 的那一半)。
  * SINGLE-FILE DUAL-DIALECT([ref] A12 定型半场;先例 = `checkpoint-store-sql.ts`)。[ref] 车1,设计稿
- * `docs/DESIGN-270-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的 `core/retention.d.ts`
+ * `docs/[ref]-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的 `core/retention.d.ts`
  * (`ManagedRetentionCapability` / `RetentionReceipt`);事务内钩表的形 = core-stores-sql 的 `SqlTransactionHooks`(本文件的同名型是它的形,见下)。
  *
  * ── 一个事务、两个属主:执行器 + 部署钩 ─────────────────────────────────────────────────────────────

package/dist/stores-sql/tool-result-store-sql.d.ts

@@ -22,7 +22,7 @@ export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>
  * 一句看不出根因的话。这正是「响亮或 fail-closed,禁静默降级」那条要挡的形态。
  *
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
- * 探针读抛且是**可证**的缺列 ⇒ 拒启(其余错误原样上抛,与兄弟探针同一条规则)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift} / {@link schemaWaysOut}),没有销毁性的一条:
+ * 探针读抛且是**可证**的缺列 ⇒ 拒启(其余错误原样上抛,与兄弟探针同一条规则)。拒因的出路是**闭集三条**(与整库对账同一份,{@link probedMissingColumnRefusal} / {@link schemaWaysOut}),没有销毁性的一条:
  * 缺的出处两列由对账同一套件逐条打印 `ALTER TABLE tool_result ADD COLUMN …`;键宽不够则第 (2) 条是部署者自己把 `ref` 加宽到本构建的定义。
  */
 export declare function assertToolResultProvenanceSchema(query: (sql: string) => Promise<{

package/dist/stores-sql/tool-result-store-sql.js

@@ -3,7 +3,7 @@ import { pgSanitizeText } from "../plugins/pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { ensureIndexes } from "../plugins/ensure-index.js";
-import { describeProbedTableDrift, schemaWaysOut } from "../plugins/schema-drift-sentence.js";
+import { probedMissingColumnRefusal, schemaMismatchRefusal, schemaWaysOut } from "../plugins/schema-drift-sentence.js";
 import { isMissingColumnError } from "../plugins/sql-errors.js";
 export const PG_TOOL_RESULT_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS tool_result (
@@ -29,7 +29,7 @@ export async function assertToolResultProvenanceSchema(query, dialect) {
         : "SELECT character_maximum_length AS len FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = 'tool_result' AND column_name = 'ref'").catch(() => ({ rows: [] }));
     const width = Number(widthRow.rows[0]?.len ?? NaN);
     if (Number.isFinite(width) && width < MAX_MINTED_TOOL_RESULT_REF_CHARS) {
-        throw new Error(`tool_result.ref is VARCHAR(${width}) but core 5.26.0 mints refs up to ${MAX_MINTED_TOOL_RESULT_REF_CHARS} characters ` +
+        throw schemaMismatchRefusal(`tool_result.ref is VARCHAR(${width}) but core 5.26.0 mints refs up to ${MAX_MINTED_TOOL_RESULT_REF_CHARS} characters ` +
             `(#119 made the ref injective: four \`~\`-separated segments) — refusing to start. A truncating primary key aliases two distinct refs onto ` +
             `one row — one run's tool output reads back from another run's ref. ` +
             `The ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database is behind this build on that key column; offloaded results are a recoverable-window cache, ` +
@@ -46,13 +46,11 @@ export async function assertToolResultProvenanceSchema(query, dialect) {
     catch (err) {
         if (!isMissingColumnError(err, dialect))
             throw err;
-        throw new Error(`tool_result is missing the #119 provenance columns (owner_session_id / owner_task_id) — refusing to start. ` +
+        throw await probedMissingColumnRefusal(query, dialect, ["tool_result"], `tool_result is missing the #119 provenance columns (owner_session_id / owner_task_id) — refusing to start. ` +
             `This release picks up @sema-agent/core 5.26.0, which changed how an offloaded tool result is addressed ` +
             `(the ref grew past the old VARCHAR(190) key) and made the store record who wrote each row. Without the columns every offload write ` +
             `fails with unknown column and core's failure arm turns it into an inline placeholder — the service keeps running and the tool output is lost. ` +
-            `Offloaded tool results are a recoverable-window cache (the inline previews in transcripts are unaffected).\n` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-            (await describeProbedTableDrift(query, dialect, ["tool_result"])));
+            `Offloaded tool results are a recoverable-window cache (the inline previews in transcripts are unaffected).`, err);
     }
 }
 function toolResultAgeCutoff(now, opts) {

package/dist/task-a2a.d.ts

@@ -57,7 +57,7 @@ export declare const A2A_PEER_DISPOSITION: {
     readonly toolAxes: "engine";
 };
 /** 请求体 `a2aPeers[i]` 的键闭集 = 处置表的键(书写序即判序)。 */
-export declare const A2A_PEER_ENTRY_KEYS: readonly ("url" | "name" | "headers" | "cardUrl" | "principalHeader" | "allowSkills" | "toolAxes")[];
+export declare const A2A_PEER_ENTRY_KEYS: readonly ("url" | "name" | "headers" | "toolAxes" | "principalHeader" | "cardUrl" | "allowSkills")[];
 /**
  * **请求入口的一次读**(`boot/resolve-spec.ts` 在腿首铸一份,受理门与读器——续跑重放腿只有读器——都吃这一份):`body.a2aPeers` 若是数组,返回同形数组
  * (每个对象条目换成它的 {@link PeerSnapshot};非对象条目原样;长度保真 —— 界外的条数仍是受理门撞帽拒与读器丢弃留声的依据,只快照界内的条目);不是数组(缺席 / `null` / 别的形)原样返回。
@@ -68,8 +68,6 @@ export declare const A2A_PEER_ENTRY_KEYS: readonly ("url" | "name" | "headers" |
 export declare function snapshotRequestA2a(raw: unknown, options: {
     readonly reread: boolean;
 }): unknown;
-/** 读这条对端的是哪条腿:`fresh` = 新提交;`resume` = 续跑重放升级前存下的请求体(`boot/resolve-spec.ts` 的 `opts.leg` 分流,同一个读法)。 */
-type A2aRequestLeg = "fresh" | "resume";
 /** 请求面对端 → 草稿:按 {@link A2A_PEER_DISPOSITION} 拆(`headers` 进件,其余进声明;拆法与 MCP 请求腿同一只 `splitDeclaration`)。件缺席或空 ⇒ 草稿不带件。纯函数,不登记。 */
 export declare function toA2aDraft(peer: RequestA2aPeer): A2aDraft;
 /**
@@ -81,8 +79,8 @@ export declare function validateRequestA2a(raw: unknown): {
     dropped: A2aInjectionDrop[];
 } | null;
 /**
- * 一份请求的 `a2aPeers` 里,读器挂得上、`headers` 却剔掉了成员的那些坐标(`a2aPeers[<下标>].headers.__proto__`:成员名过回显清洗,只会是读器的保留名,不带值、不带调用方写的对端名)——
- * 「请求成员读不出」那一只判据(`unread-request-members.ts`)的 A2A 一座。读器与挂载同一只({@link normalizeA2aPeer},续跑重放腿的读法;新提交腿上同一形由判官表 400)。
+ * 一份请求的 `a2aPeers` 里,读器挂得上、`headers` 却剔掉了成员的那些坐标(`a2aPeers[<下标>].headers.<保留名>`:成员名只会是契约包保留成员名表里的名字,不带值、不带调用方写的对端名)——
+ * 「请求成员读不出」那一只判据(`unread-request-members.ts`)的 A2A 一座。读器与挂载同一只({@link normalizeA2aPeer},只有一种读法;新提交腿上同一形先由判官表 400)。
  * 挂不上的对端不算(整条不进,有自己的留声)。`storedToolAxes` = 续跑重放腿递的 M19 重读座。不是数组 ⇒ 空。
  */
 export declare function requestA2aHeadersUnread(raw: unknown, storedToolAxes?: StoredToolAxesRereadM19): string[];
@@ -123,9 +121,6 @@ desk: Pick<PeerDesk, "declare">, lease: PeerLease, logger?: {
     info?(m: string, meta?: unknown): void;
     warn(m: string, meta?: unknown): void;
 }, 
-/** 哪条腿在读(`boot/resolve-spec.ts` 按 `opts.leg` 递;缺省 = 新提交,最严的读法):只决定 `headers` 里 `__proto__` 名成员的处置(见 {@link normalizeA2aPeer})。 */
-leg?: A2aRequestLeg, 
 /** 一次性迁移 M19 的重读座(窗口见 `plugins/one-time-migrations.ts` 登记表):只在续跑重放腿、只在窗开着时由 `boot/resolve-spec.ts` 递进来 —— 与 MCP 请求腿同一份。 */
 storedToolAxes?: StoredToolAxesRereadM19): A2aServerSpec[] | undefined;
-export {};
 //# sourceMappingURL=task-a2a.d.ts.map

package/dist/task-a2a.js

@@ -1,11 +1,11 @@
 import { types } from "node:util";
 import { resolveComplianceDenies } from "@sema-agent/core";
-import { describeNotStringArray, describeValueShape, findUrlCredential, isStringArray } from "@sema-agent/settings-schema";
+import { describeNotStringArray, describeValueShape, findUrlCredential, isStringArray, readPlainStringRecord } from "@sema-agent/settings-schema";
 import { errorKindOf } from "./observability/err-text.js";
-import { declarationKeys, readPlainStringRecord, splitDeclaration } from "./plain-string-record.js";
+import { declarationKeys, splitDeclaration } from "./request-declaration-disposition.js";
 import { mintDeclaration, peerSentence } from "./peer-seat.js";
 import { readRequestToolAxes } from "./request-tool-axes.js";
-import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyNames } from "./request-key-closure.js";
+import { MAX_KEY_ECHO, keyClosureClause, scanKeyNames } from "./request-key-closure.js";
 import { urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential-refusal.js";
 import { createMountSeat, declarationEntryNotObject, declarationIssueFacts, declarationNameIssue, declarationOverCapFacts, declaredName, judgeDeclarationKeys, requestDeclarationRefusal, throwDeclarationRefusal, } from "./request-declaration-refusal.js";
 import { sendHeaderOwnershipIssue } from "./task-mcp.js";
@@ -53,7 +53,12 @@ function peerUrlIssue(key) {
     };
 }
 const A2A_SEND_HEADER_PATHS = { headers: "headers", principalHeader: "principalHeader" };
-const HEADERS_RESERVED_MEMBER_PATH = "headers.__proto__";
+function readPeerHeaders(raw) {
+    const read = readPlainStringRecord(raw);
+    if (!read.ok)
+        return { record: undefined, issues: [{ path: "headers", reason: `must be a plain object of string values — ${read.detail}` }] };
+    return { record: read.record, issues: read.reservedMembers.map((name) => ({ path: `headers.${name}`, reason: `no member of a declaration may be named "${name}"` })) };
+}
 const PEER_SNAPSHOT = Symbol("a2aPeerSnapshot");
 function openCloneNode(v, ancestors) {
     if (v === null || v === undefined || typeof v === "string" || typeof v === "number" || typeof v === "boolean")
@@ -134,7 +139,7 @@ function mintPeerSnapshot(entry, reread) {
         cardUrl: source.cardUrl,
         principalHeader: source.principalHeader,
         allowSkills: Array.isArray(allowSkills) ? Array.from(allowSkills) : allowSkills,
-        headers: headers === undefined ? undefined : readPlainStringRecord(headers),
+        headers: headers === undefined ? undefined : readPeerHeaders(headers),
         toolAxes: toolAxesRead,
         toolAxesDeclared: reread && toolAxesRead !== undefined && !toolAxesRead.ok ? cloneDeclaration(toolAxes) : undefined,
         unknownKeys: Object.keys(source).filter((name) => !A2A_PEER_ENTRY_KEY_SET.has(name)),
@@ -162,18 +167,10 @@ const A2A_PEER_KEY_JUDGES = {
     name: declarationNameIssue,
     url: peerUrlIssue("url"),
     cardUrl: peerUrlIssue("cardUrl"),
-    headers: (o) => {
-        const read = o.headers;
-        if (read === undefined)
-            return undefined;
-        if (!read.ok)
-            return { path: "headers", reason: `must be a plain object of string values — ${read.member === undefined ? read.fault : `its member "${echoKeyName("", read.member)}" ${read.fault}`}` };
-        const reserved = read.stripped[0];
-        return reserved === undefined ? undefined : { path: HEADERS_RESERVED_MEMBER_PATH, reason: reserved.fault };
-    },
+    headers: (o) => o.headers?.issues[0],
     principalHeader: (o) => o.principalHeader !== undefined && typeof o.principalHeader !== "string"
         ? { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }
-        : sendHeaderOwnershipIssue({ headers: o.headers?.ok === true ? o.headers.record : undefined, principalHeader: o.principalHeader }, "a2a", A2A_SEND_HEADER_PATHS),
+        : sendHeaderOwnershipIssue({ headers: o.headers?.record, principalHeader: o.principalHeader }, "a2a", A2A_SEND_HEADER_PATHS),
     allowSkills: (o) => o.allowSkills === undefined || isStringArray(o.allowSkills)
         ? undefined
         : { path: "allowSkills", reason: `must be an array of strings (omit the key to leave the peer's skills unrestricted) — got ${describeNotStringArray(o.allowSkills)}` },
@@ -182,19 +179,20 @@ const A2A_PEER_KEY_JUDGES = {
         return read === undefined || read.ok ? undefined : toolAxesIssue(read);
     },
 };
-function normalizeA2aPeer(e, leg, at, storedToolAxes) {
+function normalizeA2aPeer(e, at, storedToolAxes) {
     const dropBecause = (issue) => ({ draft: null, because: declarationIssueFacts(at, issue) });
     const notObject = declarationEntryNotObject(A2A_SEAT, e, at);
     if (notObject !== undefined)
         return { draft: null, because: { field: at, reason: notObject } };
     const o = snapshotPeer(e, storedToolAxes !== undefined);
+    const lost = o.headers?.record === undefined ? [] : o.headers.issues;
     for (const key of A2A_PEER_ENTRY_KEYS) {
         const issue = A2A_PEER_KEY_JUDGES[key](o, at);
         if (issue === undefined)
             continue;
         if (issue.credential !== undefined)
             continue;
-        if (leg === "resume" && issue.path === HEADERS_RESERVED_MEMBER_PATH)
+        if (lost.includes(issue))
             continue;
         if (key === "toolAxes" && storedToolAxes !== undefined)
             continue;
@@ -204,9 +202,9 @@ function normalizeA2aPeer(e, leg, at, storedToolAxes) {
     if (o.cardUrl !== undefined)
         spec.cardUrl = o.cardUrl;
     const { headers, toolAxes: axes } = o;
-    if (headers?.ok === true)
+    if (headers?.record !== undefined)
         spec.headers = headers.record;
-    const lost = headers?.ok === true && headers.stripped.length > 0 ? { headersLost: headers.stripped.map((m) => echoKeyName("headers.", m.name)) } : {};
+    const headersLost = lost.length > 0 ? { headersLost: lost.map((issue) => issue.path) } : {};
     if (o.principalHeader !== undefined)
         spec.principalHeader = o.principalHeader;
     if (o.allowSkills !== undefined)
@@ -227,22 +225,22 @@ function normalizeA2aPeer(e, leg, at, storedToolAxes) {
                 return unread;
             if (again.toolAxes !== undefined)
                 spec.toolAxes = again.toolAxes;
-            return { draft: toA2aDraft(spec), toolAxesReread: peerSentence(axes.problem), ...lost };
+            return { draft: toA2aDraft(spec), toolAxesReread: peerSentence(axes.problem), ...headersLost };
         }
         if (axes.toolAxes !== undefined)
             spec.toolAxes = axes.toolAxes;
     }
-    return { draft: toA2aDraft(spec), ...lost };
+    return { draft: toA2aDraft(spec), ...headersLost };
 }
 export function toA2aDraft(peer) {
     const split = splitDeclaration(peer, A2A_PEER_DISPOSITION);
     return { spec: split.engine, ...(split.pieces === undefined ? {} : { pieces: split.pieces }) };
 }
 export function validateRequestA2a(raw) {
-    const v = validateRequestA2aEntries(raw, "fresh");
+    const v = validateRequestA2aEntries(raw);
     return v === null ? null : { ok: v.ok, dropped: v.dropped };
 }
-function validateRequestA2aEntries(raw, leg, storedToolAxes) {
+function validateRequestA2aEntries(raw, storedToolAxes) {
     if (raw === undefined || raw === null)
         return { ok: [], dropped: [], toolAxesReread: [] };
     if (!Array.isArray(raw))
@@ -251,7 +249,7 @@ function validateRequestA2aEntries(raw, leg, storedToolAxes) {
     const dropped = [];
     const toolAxesReread = [];
     for (const [i, e] of raw.slice(0, MAX_REQUEST_A2A_PEERS).entries()) {
-        const read = normalizeA2aPeer(e, leg, `${A2A_SEAT.list}[${i}]`, storedToolAxes);
+        const read = normalizeA2aPeer(e, `${A2A_SEAT.list}[${i}]`, storedToolAxes);
         if (read.draft !== null) {
             ok.push(read.draft);
             if (read.toolAxesReread !== undefined)
@@ -271,7 +269,7 @@ export function requestA2aHeadersUnread(raw, storedToolAxes) {
     const out = [];
     for (const [i, e] of raw.slice(0, MAX_REQUEST_A2A_PEERS).entries()) {
         const at = `${A2A_SEAT.list}[${i}]`;
-        const read = normalizeA2aPeer(e, "resume", at, storedToolAxes);
+        const read = normalizeA2aPeer(e, at, storedToolAxes);
         if (read.draft !== null)
             for (const member of read.headersLost ?? [])
                 out.push(`${at}.${member}`);
@@ -307,14 +305,14 @@ export function mergeRequestA2a(baseline, drafts, desk, lease) {
     const winners = drafts.filter((d) => !taken.has(d.spec.name));
     return winners.length === 0 ? baseline : [...(baseline ?? []), ...winners.map((d) => mintDeclaration(desk, d, lease))];
 }
-export function resolveRequestA2a(baseline, bodyA2a, config, desk, lease, logger, leg = "fresh", storedToolAxes) {
+export function resolveRequestA2a(baseline, bodyA2a, config, desk, lease, logger, storedToolAxes) {
     if (bodyA2a === undefined || bodyA2a === null)
         return baseline;
     if (!a2aInjectionHonored(config)) {
         logger?.warn("a2a_injection_ignored", { reason: "gate_closed (per-request A2A peers honored only on a single-user, unlocked, compliance-permitted deployment)" });
         return baseline;
     }
-    const v = validateRequestA2aEntries(bodyA2a, leg, storedToolAxes);
+    const v = validateRequestA2aEntries(bodyA2a, storedToolAxes);
     if (v === null) {
         logger?.warn("a2a_injection_ignored", { reason: "a2aPeers not an array" });
         return baseline;