@sema-agent/server 7.93.4 → 7.93.5

package/dist/boot/exit-boundary.d.ts

@@ -0,0 +1,22 @@
+import type { Logger } from "../observability/logger.js";
+/** {@link installProcessExitBoundary} 的把手。 */
+export interface ProcessExitBoundary {
+    /**
+     * **优化点**,不承担不变量:受控退的收尾链在它自己的终点早按一次子进程腿(理由逐字写在
+     * `boot/shutdown.ts` 的调用点上 —— 那之后进程还活十秒量级,后台腿的软→硬梯子跑得完)。
+     * 工作区腿**刻意不给**这条早按:停机中段 `rm -rf` 会把在飞 turn 正在写的目录从它脚下抽掉。
+     */
+    reapChildProcessesEarly(): void;
+    /** 摘掉本次装配的 `exit` 钩。幂等(同进程内反复装配的调用方=测试必须用它收尾)。 */
+    dispose(): void;
+}
+/**
+ * 装上本进程的退出边界(`process.once("exit")`)。返回 {@link ProcessExitBoundary}。
+ *
+ * **进程级注册表是全局单例** ⇒ 装两次就是两只钩(两个写者)。生产里每条车道只装一次、装到死;
+ * 同进程内反复装配的调用方(测试)必须 `dispose()`。
+ */
+export declare function installProcessExitBoundary({ logger }: {
+    logger: Logger;
+}): ProcessExitBoundary;
+//# sourceMappingURL=exit-boundary.d.ts.map

package/dist/boot/exit-boundary.js

@@ -0,0 +1,73 @@
+import { defaultTaskRegistry } from "@sema-agent/core";
+import { liveHostForegroundChildCount, reapHostForegroundChildren } from "../plugins/host-platform.js";
+import { liveEphemeralHostWorkspaceCount, reapEphemeralHostWorkspaces } from "../plugins/host-workspace-registry.js";
+export function installProcessExitBoundary({ logger }) {
+    const reapOwnChildProcesses = () => {
+        try {
+            const reaped = defaultTaskRegistry.reapAllSessionBackground();
+            if (reaped > 0)
+                logger.info("shutdown_background_reaped", { reaped });
+        }
+        catch (err) {
+            logger.warn("shutdown_background_reap_failed", { err: String(err) });
+        }
+        try {
+            const fg = reapHostForegroundChildren();
+            if (fg.signalled > 0 || fg.alreadyDead > 0)
+                logger.info("shutdown_foreground_reaped", { signalled: fg.signalled, alreadyDead: fg.alreadyDead });
+            if (fg.failed.length > 0)
+                logger.warn("shutdown_foreground_reap_incomplete", { groups: fg.failed });
+        }
+        catch (err) {
+            logger.warn("shutdown_foreground_reap_failed", { err: String(err) });
+        }
+    };
+    const reapOwnHostWorkspaces = () => {
+        try {
+            const { removed, failed } = reapEphemeralHostWorkspaces();
+            if (removed.length > 0)
+                logger.info("shutdown_host_workspaces_reaped", { removed: removed.length });
+            if (failed.length > 0)
+                logger.warn("shutdown_host_workspace_reap_incomplete", { dirs: failed.map((f) => f.dir) });
+        }
+        catch (err) {
+            logger.warn("shutdown_host_workspace_reap_failed", { err: String(err) });
+        }
+    };
+    const onProcessExit = () => {
+        const onBooks = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
+        try {
+            reapOwnChildProcesses();
+        }
+        catch (err) {
+            console.error("shutdown_exit_boundary_child_reap_threw", err);
+        }
+        try {
+            reapOwnHostWorkspaces();
+        }
+        catch (err) {
+            console.error("shutdown_exit_boundary_workspace_reap_threw", err);
+        }
+        const left = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
+        try {
+            logger.info("shutdown_exit_boundary", { ...onBooks, leftForegroundChildren: left.foregroundChildren, leftHostWorkspaces: left.hostWorkspaces });
+            if (left.foregroundChildren > 0 || left.hostWorkspaces > 0)
+                logger.warn("shutdown_exit_boundary_incomplete", left);
+        }
+        catch (err) {
+            console.error("shutdown_exit_boundary_log_threw", err);
+        }
+    };
+    process.once("exit", onProcessExit);
+    let disposed = false;
+    return {
+        reapChildProcessesEarly: reapOwnChildProcesses,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            process.removeListener("exit", onProcessExit);
+        },
+    };
+}
+//# sourceMappingURL=exit-boundary.js.map

package/dist/boot/shutdown.d.ts

@@ -12,8 +12,8 @@
  *     "第二个信号"的语义读数。
  *  3. `clearInterval(reaper)` 必须是 hardShutdown 的第一件事(在 `server.close()` 之前),否则
  *     收尾期还会有 reaper tick 打向正在关闭的池。
- *  4. **进程级监听一律成对**([ref] 二轮件4):本函数装的六只(三信号 + [ref]① 双钩 + S-557 退出边界钩)
- *     只能经返回的
+ *  4. **进程级监听一律成对**([ref] 二轮件4):本函数装的六只(三信号 + [ref]① 双钩 + S-557 退出边界钩
+ *     —— S-560 起后者由 {@link installProcessExitBoundary} 代装,摘除仍并进同一把手)只能经返回的
  *     {@link ShutdownHandle} 摘 —— 调用方手写「摘三信号」的收尾会把双钩漏在进程上,而陈旧的那只
  *     rejection 钩仍握着 `process.exit(1)`,会对后续无关的 rejection 把进程打掉。
  */

package/dist/boot/shutdown.js

@@ -1,9 +1,8 @@
-import { Runner, defaultTaskRegistry } from "@sema-agent/core";
+import { Runner } from "@sema-agent/core";
 import { writeCrashLast, clearCrashLast, readCrashLast } from "./crash-last.js";
 import { createSighupIdleHandler } from "../sighup-idle.js";
 import { createParentWatch } from "../parent-watch.js";
-import { liveHostForegroundChildCount, reapHostForegroundChildren } from "../plugins/host-platform.js";
-import { liveEphemeralHostWorkspaceCount, reapEphemeralHostWorkspaces } from "../plugins/host-workspace-registry.js";
+import { installProcessExitBoundary } from "./exit-boundary.js";
 import { createEngineLeaseTracker } from "./engine-lease.js";
 import { writeExitLast, readExitLast, clearExitLast } from "./exit-last.js";
 import { isScriptRealmRejection, describeRejectionReason } from "../orchestration/hardened-vm-runner.js";
@@ -32,63 +31,7 @@ export function installShutdownHandlers(ctx) {
         if (dataRoot)
             writeCrashLast(dataRoot, { version, inflight: drainState.inflight?.(), err });
     };
-    const reapOwnChildProcesses = () => {
-        try {
-            const reaped = defaultTaskRegistry.reapAllSessionBackground();
-            if (reaped > 0)
-                logger.info("shutdown_background_reaped", { reaped });
-        }
-        catch (err) {
-            logger.warn("shutdown_background_reap_failed", { err: String(err) });
-        }
-        try {
-            const fg = reapHostForegroundChildren();
-            if (fg.signalled > 0 || fg.alreadyDead > 0)
-                logger.info("shutdown_foreground_reaped", { signalled: fg.signalled, alreadyDead: fg.alreadyDead });
-            if (fg.failed.length > 0)
-                logger.warn("shutdown_foreground_reap_incomplete", { groups: fg.failed });
-        }
-        catch (err) {
-            logger.warn("shutdown_foreground_reap_failed", { err: String(err) });
-        }
-    };
-    const reapOwnHostWorkspaces = () => {
-        try {
-            const { removed, failed } = reapEphemeralHostWorkspaces();
-            if (removed.length > 0)
-                logger.info("shutdown_host_workspaces_reaped", { removed: removed.length });
-            if (failed.length > 0)
-                logger.warn("shutdown_host_workspace_reap_incomplete", { dirs: failed.map((f) => f.dir) });
-        }
-        catch (err) {
-            logger.warn("shutdown_host_workspace_reap_failed", { err: String(err) });
-        }
-    };
-    const onProcessExit = () => {
-        const onBooks = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
-        try {
-            reapOwnChildProcesses();
-        }
-        catch (err) {
-            console.error("shutdown_exit_boundary_child_reap_threw", err);
-        }
-        try {
-            reapOwnHostWorkspaces();
-        }
-        catch (err) {
-            console.error("shutdown_exit_boundary_workspace_reap_threw", err);
-        }
-        const left = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
-        try {
-            logger.info("shutdown_exit_boundary", { ...onBooks, leftForegroundChildren: left.foregroundChildren, leftHostWorkspaces: left.hostWorkspaces });
-            if (left.foregroundChildren > 0 || left.hostWorkspaces > 0)
-                logger.warn("shutdown_exit_boundary_incomplete", left);
-        }
-        catch (err) {
-            console.error("shutdown_exit_boundary_log_threw", err);
-        }
-    };
-    process.once("exit", onProcessExit);
+    const exitBoundary = installProcessExitBoundary({ logger });
     const onUncaughtException = (err) => {
         try {
             writeLastWords(err);
@@ -151,7 +94,7 @@ export function installShutdownHandlers(ctx) {
         subRunner.sessions.dispose();
         void lspManager?.dispose?.();
         void workflowNotifyJournal?.close?.();
-        reapOwnChildProcesses();
+        exitBoundary.reapChildProcessesEarly();
         void fleetClient?.stop();
         server.close(() => {
             void retentionTeardown.then(() => (backend ? backend.close() : Promise.resolve())).finally(() => process.exit(0));
@@ -248,7 +191,7 @@ export function installShutdownHandlers(ctx) {
             if (disposed)
                 return;
             disposed = true;
-            process.removeListener("exit", onProcessExit);
+            exitBoundary.dispose();
             process.removeListener("uncaughtException", onUncaughtException);
             process.removeListener("unhandledRejection", onUnhandledRejection);
             process.removeListener("SIGTERM", drainThenShutdown);

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -515,7 +515,7 @@ export declare function ensurePgApprovalAskSchema(q: PgQueryFn): Promise<void>;
  *
  * 病:本仓不发 `ALTER TABLE`(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升上来
  * 的部署,`CREATE TABLE IF NOT EXISTS` 对存量 `approval_ask` 是空操作 —— 本车新加的
- * `rule_command` / `rule_scope_root` 两列不在,而 `ensureAsk` 的 INSERT 与 `ASK_COLS` 的每一条读
+ * `rule_command` / `rule_scope_root` 两列不在,而 `ensureAsk` 的 INSERT 与 `askCols` 的每一条读
  * **无条件**引用它们。后果不是「少一个新功能」,是**整条流内审批协议**在那台机器上是坏的:
  *  · 每一只 ask 的 `ensureAsk` 撞 unknown column ⇒ 被 `noteStoreError` 吞掉 ⇒ 整只 ask 退回 park 路由
  *    (卡不落库、`GET /v1/approvals` 的重放面恒空、迟到决议腿恒 404);

package/dist/plugins/approval-ask-store-sql.js

@@ -1,6 +1,7 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { canAskTransition } from "../approval-ask-machine.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readAnyJsonValueColumn, readJsonObjectColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
 export function assertIntegralEpochMs(field, value) {
     if (!Number.isSafeInteger(value)) {
@@ -211,7 +212,7 @@ export async function ensurePgApprovalAskSchema(q) {
 }
 export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
     try {
-        await query(`SELECT rule_command, rule_scope_root, updated_input FROM ${APPROVAL_ASK_TABLE} WHERE 1=0`);
+        await query(`SELECT rule_command, rule_scope_root, ${jsonColumnText(dialect, "updated_input")} FROM ${APPROVAL_ASK_TABLE} WHERE 1=0`);
     }
     catch (err) {
         if (!isMissingColumnError(err, dialect))
@@ -231,14 +232,21 @@ export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
             `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-const ASK_COLS = "ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, " +
-    "provisional, rev, decision, decision_actor, decision_note, settled_by, updated_input, decided_at_ms, denied_reason, gate_token, " +
-    "gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, " +
-    "created_at_ms, updated_at_ms";
-const BATCH_COLS = "batch_id, task_id, state, bound_ask_id, rev, created_at_ms, updated_at_ms";
-function parseJsonColumn(v) {
-    return JSON.parse(String(v));
+function askCols(dialect) {
+    return [
+        "ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state",
+        "provisional, rev, decision",
+        jsonColumnText(dialect, "decision_actor"),
+        "decision_note, settled_by",
+        jsonColumnText(dialect, "updated_input"),
+        "decided_at_ms, denied_reason, gate_token",
+        "gate_bound_call_id, gate_bound_input_hash, idempotency_key",
+        jsonColumnText(dialect, "card_json"),
+        "rule_command, rule_scope_root, schema_version, expires_at_ms",
+        "created_at_ms, updated_at_ms",
+    ].join(", ");
 }
+const BATCH_COLS = "batch_id, task_id, state, bound_ask_id, rev, created_at_ms, updated_at_ms";
 function toBool(v) {
     return Boolean(Number(v));
 }
@@ -249,6 +257,15 @@ function strOrNull(v) {
     return v === null || v === undefined ? null : String(v);
 }
 function mapAskRow(r) {
+    const askId = String(r.ask_id);
+    try {
+        return mapAskRowBody(r, askId);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`approval-ask-store: ${m} — refusing rather than serve an ask row nobody can read`));
+    }
+}
+function mapAskRowBody(r, askId) {
     return {
         askId: String(r.ask_id),
         taskId: String(r.task_id),
@@ -264,17 +281,17 @@ function mapAskRow(r) {
         provisional: toBool(r.provisional),
         rev: Number(r.rev),
         decision: strOrNull(r.decision) ?? null,
-        decisionActor: r.decision_actor == null ? null : parseJsonColumn(r.decision_actor),
+        decisionActor: r.decision_actor == null ? null : decodeJsonColumn(r.decision_actor, readJsonObjectColumn, `${APPROVAL_ASK_TABLE}.decision_actor for ask ${askId}`),
         decisionNote: strOrNull(r.decision_note),
         settledBy: strOrNull(r.settled_by),
-        ...(r.updated_input == null ? {} : { updatedInput: parseJsonColumn(r.updated_input) }),
+        ...(r.updated_input == null ? {} : { updatedInput: decodeJsonColumn(r.updated_input, readAnyJsonValueColumn, `${APPROVAL_ASK_TABLE}.updated_input for ask ${askId}`) }),
         decidedAtMs: numOrNull(r.decided_at_ms),
         deniedReason: strOrNull(r.denied_reason),
         gateToken: strOrNull(r.gate_token),
         gateBoundCallId: strOrNull(r.gate_bound_call_id),
         gateBoundInputHash: strOrNull(r.gate_bound_input_hash),
         idempotencyKey: strOrNull(r.idempotency_key),
-        cardJson: parseJsonColumn(r.card_json),
+        cardJson: decodeJsonColumn(r.card_json, readJsonObjectColumn, `${APPROVAL_ASK_TABLE}.card_json for ask ${askId}`),
         ruleCommand: strOrNull(r.rule_command),
         ruleScopeRoot: strOrNull(r.rule_scope_root),
         schemaVersion: Number(r.schema_version),
@@ -337,7 +354,7 @@ export class SqlApprovalAskStore {
         return isDupKeyError(this.db.dialect, e);
     }
     async getAskOn(conn, askId) {
-        const { rows } = await conn.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [askId]);
+        const { rows } = await conn.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [askId]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async getBatchOn(conn, batchId) {
@@ -485,7 +502,7 @@ export class SqlApprovalAskStore {
             }
             const askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 2)} WHERE ${pendingClaimWhere(dialect, 3)}`, [to, now, askId, batchId]);
             if (askRes.affected !== 1) {
-                const sel = await conn.query(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ${ph(dialect, 1)} AND batch_id = ${ph(dialect, 2)} FOR UPDATE`, [askId, batchId]);
+                const sel = await conn.query(`SELECT ${askCols(dialect)} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ${ph(dialect, 1)} AND batch_id = ${ph(dialect, 2)} FOR UPDATE`, [askId, batchId]);
                 await conn.rollback();
                 return { claimed: false, current: projectAskTerminalClaimTruth(sel.rows[0] ? mapAskRow(sel.rows[0]) : null) };
             }
@@ -614,32 +631,32 @@ export class SqlApprovalAskStore {
         }
     }
     async listByState(state, limit) {
-        const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE state = ? ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE state = $1 ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT $2`), [state, limit]);
+        const { rows } = await this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE state = ? ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE state = $1 ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT $2`), [state, limit]);
         return rows.map(mapAskRow);
     }
     async listPendingByTask(taskId, signal) {
         if (signal?.aborted === true)
             throw abortedReadError("listPendingByTask");
-        const { rows } = await withReadSignal(this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`), [taskId]), signal, "listPendingByTask");
+        const { rows } = await withReadSignal(this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND state = 'STREAM_PENDING' ORDER BY created_at_ms ASC`), [taskId]), signal, "listPendingByTask");
         return rows.map(mapAskRow);
     }
     async listPendingBySession(sessionId, owner, signal) {
         if (signal?.aborted === true)
             throw abortedReadError("listPendingBySession");
         const { rows } = await withReadSignal(this.db.query(owner === null
-            ? this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`)
-            : this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner = ? ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner = $2 ORDER BY created_at_ms ASC`), owner === null ? [sessionId] : [sessionId, owner]), signal, "listPendingBySession");
+            ? this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`)
+            : this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner = ? ORDER BY created_at_ms ASC`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner = $2 ORDER BY created_at_ms ASC`), owner === null ? [sessionId] : [sessionId, owner]), signal, "listPendingBySession");
         return rows.map(mapAskRow);
     }
     async getAsk(askId) {
-        const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [
+        const { rows } = await this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [
             askId,
         ]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async getByIdempotencyKey(taskId, key) {
         assertIdempotencyKeyShape(key);
-        const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND idempotency_key = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND idempotency_key = $2`), [taskId, key]);
+        const { rows } = await this.db.query(this.q(`SELECT ${askCols("tidb")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND idempotency_key = ?`, `SELECT ${askCols("pg")} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND idempotency_key = $2`), [taskId, key]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async deferReconcile(askId, expectedState, expectedRev, nowMs) {

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

@@ -186,6 +186,16 @@ export declare class SqlDeviceStore implements DeviceStore {
     appendAudit(input: AppendAuditInput): Promise<void>;
     /** 审计写的**唯一**语句(池级与事务内共用;`SqlExec` 是两者的公共面)。 */
     private insertAuditOn;
+    /**
+     * 审计列表。
+     *
+     * 🔴 **一行读不出形 ⇒ 整页拒,刻意不做逐行隔离**(S-550 修复验证轮,主会话裁定后入档):方向由设计
+     * §2「失败方向 = 拒(fail-closed),全店同向」定。逐行隔离(坏行跳过 / 占位)在**审计**面上尤其危险 ——
+     * 它把「这一页少了一条」变得和「本来就没有那一条」同形,而审计面的全部意义就是「发生过的事都在」。
+     * 一页 5xx 是响亮的运维事件,一条静默消失不是。
+     *
+     * ⇒ 存量库里旧写腿留下的坏字节由**一次性迁移**清掉(`one-time-migrations.ts` M4),不靠读侧容忍。
+     */
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
 }
 /** 方言绑定薄壳(A12 形:ctor 收池,行为全在基类)。 */

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

@@ -2,6 +2,7 @@ import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isCheckViolationError } from "./sql-errors.js";
 import { DEVICE_AUDIT_EVENTS, assertAcquireShape, assertDeviceIdShape, assertDeviceOwnerShape, assertEnrollTokenHashShape, assertIssueTokenShape, assertNewDeviceShape, assertRebindShape, assertRevokeShape, assertRootSessionIdShape, assertWholeSeconds, parseDeviceAuditEvent, parseDevicePlatformOs, parseDeviceStatus, } from "../device-store.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn } from "./sql-json-column.js";
 export const DEVICES_TABLE = "device";
 export const DEVICE_ENROLL_TOKENS_TABLE = "device_enroll_token";
 export const DEVICE_SESSIONS_TABLE = "device_session";
@@ -237,7 +238,7 @@ function sessionCols(dialect) {
     return ["root_session_id", "device_id", "owner_tenant", "owner_subject", ms(dialect, "bound_at", "bound_at_ms"), "rev"].join(", ");
 }
 function auditCols(dialect) {
-    return ["id", ms(dialect, "at", "at_ms"), "event", "device_id", "owner_tenant", "owner_subject", "detail"].join(", ");
+    return ["id", ms(dialect, "at", "at_ms"), "event", "device_id", "owner_tenant", "owner_subject", jsonColumnText(dialect, "detail")].join(", ");
 }
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
@@ -295,9 +296,6 @@ function mapSessionRow(r) {
         rev: Number(r.rev),
     };
 }
-function parseJsonColumn(v) {
-    return JSON.parse(v);
-}
 function mapAuditRow(r) {
     const tenant = strOrNull(r.owner_tenant);
     const subject = strOrNull(r.owner_subject);
@@ -308,9 +306,17 @@ function mapAuditRow(r) {
         event: parseDeviceAuditEvent(bufToStr(r.event)),
         deviceId: strOrNull(r.device_id),
         owner: tenant !== null && subject !== null ? { tenant, subject } : null,
-        detail: rawDetail === null || rawDetail === undefined ? null : typeof rawDetail === "string" ? parseJsonColumn(rawDetail) : rawDetail,
+        detail: rawDetail === null || rawDetail === undefined ? null : readAuditDetail(rawDetail, String(r.id)),
     };
 }
+function readAuditDetail(raw, id) {
+    try {
+        return decodeJsonColumn(raw, readJsonObjectColumn, `${DEVICE_AUDIT_TABLE}.detail for audit row ${id}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`device-store: ${m} — refusing rather than serve an audit row whose detail nobody can read`));
+    }
+}
 function ph(dialect, n) {
     return dialect === "tidb" ? "?" : `$${n}`;
 }
@@ -637,7 +643,7 @@ export class SqlDeviceStore {
             assertDeviceIdShape(input.deviceId);
         if (input.owner)
             assertDeviceOwnerShape(input.owner);
-        await exec.query(this.q(`INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (NOW(3), ?, ?, ?, ?, ?)`, `INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (now(), $1, $2, $3, $4, $5::jsonb)`), [input.event, input.deviceId ?? null, input.owner?.tenant ?? null, input.owner?.subject ?? null, input.detail === undefined ? null : this.json(input.detail)]);
+        await exec.query(this.q(`INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (NOW(3), ?, ?, ?, ?, ?)`, `INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (now(), $1, $2, $3, $4, $5::jsonb)`), [input.event, input.deviceId ?? null, input.owner?.tenant ?? null, input.owner?.subject ?? null, input.detail == null ? null : this.json(input.detail)]);
     }
     async listAudit(filter) {
         const dialect = this.db.dialect;

package/dist/plugins/host-platform.d.ts

@@ -75,8 +75,10 @@ export interface ForegroundReapReading {
  * 收割簿上全部前台子进程组。返回**发出**信号的读数,不是确认死亡数 —— 确认要等,而本函数的调用点之一
  * 是 uncaught 出口。
  *
- * **同步形、一次到位、不等宽限**(S-557 起自述与实现同一句):承重的调用点是收尾链的
- * `process.once("exit")` 钩 —— `exit` 之后**没有续段**,`await` 一个宽限梯就是把收割赌在一个永远等不到的
+ * **同步形、一次到位、不等宽限**(S-557 起自述与实现同一句):承重的调用点是退出边界装配器
+ * (`boot/exit-boundary.ts`)那只 `process.once("exit")` 钩 —— S-560 起它由**两条车道共用**(HTTP 服务的
+ * 收尾链 + `run-local` 一次性 CLI;后者另装 SIGINT/SIGTERM 处理器,因为前台 CLI 的 Ctrl-C 若走默认终止,
+ * `exit` 钩不触发)。`exit` 之后**没有续段**,`await` 一个宽限梯就是把收割赌在一个永远等不到的
  * 时刻上(`hardShutdown` 终点那次早按只是优化,见 `boot/shutdown.ts` 的两处注)。上界 = 簿上条数 ×
  * 一次 `kill(-pid)` syscall(簿条数被 host lane 的在飞 turn 数界住),没有定时器、没有 promise。
  *

package/dist/plugins/one-time-migrations.d.ts

@@ -13,6 +13,9 @@ export interface OneTimeMigrationReport {
     readonly retiredSteerSeatStaleRows: number;
     /** M3:改名的行数(账本 `tool_end` 行 + 已决 checkpoint 的执行判词列,两者相加)。 */
     readonly askOriginRowsMigrated: number;
+    /** M4:`device_audit.detail` 里 JSON 文本 `null` 被改成列 NULL 的行数(表不在 ⇒ 恒 0)。
+     *  非零 = 这次迁移真改写了存量字节,必须让运维看见(与 M1 的 `retiredSnapshotRows` 同一条纪律)。 */
+    readonly auditDetailJsonNullRows: number;
 }
 /** 三条迁移都不适用的载体(local 车道没有 SQL 表)。 */
 export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "askOriginRowsMigrated">;

package/dist/plugins/one-time-migrations.js

@@ -1,16 +1,20 @@
 import { acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
 import { acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
+import { jsonColumnTextExpr } from "./sql-json-column.js";
 export const NO_SQL_MIGRATIONS = {
     retiredSnapshotTable: "absent",
     retiredSnapshotRows: 0,
-    retiredSteerSeatColumn: "absent",
     retiredSteerSeatStaleRows: 0,
+    retiredSteerSeatColumn: "absent",
+    auditDetailJsonNullRows: 0,
 };
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT_COLUMN = "pending_steer";
 const DELIVERABLE_STEER_SEAT_WHERE = "(status = 'pending' OR (status = 'resolved' AND execution_outcome IS NULL))";
 const RETIRED_ASK_ORIGIN = { from: "unresolvable", to: "ancestor_marked" };
 const GATE_BEARING_LEDGER_EVENT_TYPE = "tool_end";
+const AUDIT_TABLE = "device_audit";
+const AUDIT_DETAIL_COLUMN = "detail";
 export class RetiredSteerSeatError extends Error {
     rows;
     code = "checkpoint.pending_steer_seat_retired";
@@ -130,6 +134,11 @@ async function migrateOn(db, dialect) {
                 `WHERE type = '${GATE_BEARING_LEDGER_EVENT_TYPE}' AND data->'gate'->>'origin' = '${RETIRED_ASK_ORIGIN.from}'`)) +
                 (await db.exec(`UPDATE checkpoint SET execution_outcome = jsonb_set(execution_outcome, '{origin}', '"${RETIRED_ASK_ORIGIN.to}"') ` +
                     `WHERE execution_outcome->>'origin' = '${RETIRED_ASK_ORIGIN.from}'`));
+    const auditTablePresent = await tableExists(db, dialect, AUDIT_TABLE);
+    const auditDetailJsonNullRows = !auditTablePresent
+        ? 0
+        : await db.exec(`UPDATE ${AUDIT_TABLE} SET ${AUDIT_DETAIL_COLUMN} = NULL ` +
+            `WHERE ${AUDIT_DETAIL_COLUMN} IS NOT NULL AND ${jsonColumnTextExpr(dialect, AUDIT_DETAIL_COLUMN)} = 'null'`);
     let retiredSnapshotTable = "absent";
     let retiredSnapshotRows = 0;
     let retiredSteerSeatColumn = "absent";
@@ -160,7 +169,7 @@ async function migrateOn(db, dialect) {
         throw new Error(`one-time migration failed AFTER completing destructive steps — record these before retrying, a retry cannot ` +
             `report them again: ${destroyed.join("; ")}. Underlying failure: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
     }
-    return { retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, retiredSteerSeatStaleRows, askOriginRowsMigrated };
+    return { retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, retiredSteerSeatStaleRows, askOriginRowsMigrated, auditDetailJsonNullRows };
 }
 export function migrateRetiredAskOrigin(type, data) {
     if (type !== GATE_BEARING_LEDGER_EVENT_TYPE)
@@ -177,7 +186,7 @@ export function migrateRetiredAskOrigin(type, data) {
     return { ...d, gate: { ...g, origin: RETIRED_ASK_ORIGIN.to } };
 }
 export function logOneTimeMigrations(log, backend, report) {
-    const changed = report.retiredSnapshotTable === "dropped" || report.retiredSteerSeatColumn === "dropped" || report.askOriginRowsMigrated > 0;
+    const changed = report.retiredSnapshotTable === "dropped" || report.retiredSteerSeatColumn === "dropped" || report.askOriginRowsMigrated > 0 || report.auditDetailJsonNullRows > 0;
     (changed ? log.warn : log.info).call(log, "one_time_migrations_applied", {
         backend,
         retiredSnapshotTable: report.retiredSnapshotTable,
@@ -185,8 +194,11 @@ export function logOneTimeMigrations(log, backend, report) {
         retiredSteerSeatColumn: report.retiredSteerSeatColumn,
         retiredSteerSeatStaleRows: report.retiredSteerSeatStaleRows,
         askOriginRowsMigrated: report.askOriginRowsMigrated,
+        auditDetailJsonNullRows: report.auditDetailJsonNullRows,
         note: "one-time persisted-data migrations for this version's retirements (retired whole-tree snapshot index table " +
-            "dropped; retired single-seat steering column dropped; retired ask-origin spelling rewritten in place). This " +
+            "dropped; retired single-seat steering column dropped; retired ask-origin spelling rewritten in place; audit " +
+            "details written as the JSON text `null` by an earlier version folded to a SQL NULL, so \"no detail\" has exactly " +
+            "one on-disk spelling). This " +
             "whole migration step is removed in the next minor — start this version at least once before upgrading past it.",
     });
 }

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -157,6 +157,7 @@ export declare class SqlRuleApprovalRecordStore implements RuleApprovalRecordSto
     private q;
     private enc;
     get(id: string): Promise<RuleApprovalRecord | StaleRuleApprovalRecord | undefined>;
+    private readApprovalRow;
     create(record: RuleApprovalRecord): Promise<void>;
     /**
      * 丢弃一条**从未被确认**的记录(codex 交叉复审 round8 [medium],可控半场)。

package/dist/plugins/permission-rule-store-sql.js

@@ -6,6 +6,7 @@ import { isMissingColumnError } from "./sql-errors.js";
 import { canonicalJson } from "../canonical-json.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, isPersistedRuleTool, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn } from "./sql-json-column.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -211,7 +212,7 @@ export async function ensureTiDBPermissionRuleSchema(pool) {
 }
 export async function assertPermissionRuleApprovalSchema(query, dialect) {
     try {
-        await query(`SELECT command, edited_json, version, offers_json, selected_offer FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE 1=0`);
+        await query(`SELECT command, ${jsonColumnText(dialect, "edited_json")}, version, ${jsonColumnText(dialect, "offers_json")}, selected_offer FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE 1=0`);
     }
     catch (err) {
         if (!isMissingColumnError(err, dialect))
@@ -231,7 +232,7 @@ export async function assertPermissionRuleApprovalSchema(query, dialect) {
 }
 export async function assertPermissionRuleTicketSchema(query, dialect) {
     try {
-        await query(`SELECT redeemed_outcome, claim_id, purpose, settled_at_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE 1=0`);
+        await query(`SELECT ${jsonColumnText(dialect, "redeemed_outcome")}, claim_id, purpose, settled_at_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE 1=0`);
     }
     catch (err) {
         if (!isMissingColumnError(err, dialect))
@@ -332,21 +333,21 @@ export function buildRuleBucketChecksum(body) {
 }
 const NEXT_DOT_MAX_ATTEMPTS = 8;
 const EMPTY_BUCKET = { actor: "", counter: 0, rev: 0, rules: [], tombstones: [], quarantined: [] };
-function parseColumn(schema, raw, column, ownerKey) {
-    const text = typeof raw === "string" ? raw : raw === null || raw === undefined ? undefined : String(raw);
-    if (text === undefined)
-        throw new Error(`permission_rule.${column} is absent for bucket ${ownerKey}; refusing to guess its content`);
-    let json;
+const readRulesJson = createZodColumnReader(z.array(PersistedRuleRowSchema));
+const readTombstonesJson = createZodColumnReader(z.array(RuleTombstoneSchema));
+const readQuarantinedJson = createZodColumnReader(z.array(QuarantinedRuleAddRowSchema));
+const readObservedVectorJson = createZodColumnReader(FrontierSchema);
+const readCandidatesJson = createZodColumnReader(z.array(RuleCandidateSchema));
+const readOffersJson = createZodColumnReader(z.array(RuleOffer2Schema));
+const readRedeemedDotsJson = createZodColumnReader(RedeemedDotsSchema);
+const readEditedJson = createZodColumnReader(RuleEditedSchema);
+async function refusingUnreadableColumns(what, fn) {
     try {
-        json = JSON.parse(text);
+        return await fn();
     }
-    catch (err) {
-        throw new Error(`permission_rule.${column} for bucket ${ownerKey} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`${m} — the ${what} does not carry a readable shape; refusing the whole of it rather than report a partial one`));
     }
-    const parsed = schema.safeParse(json);
-    if (!parsed.success)
-        throw new Error(`permission_rule.${column} for bucket ${ownerKey} does not carry a readable shape: ${parsed.error.message}`);
-    return parsed.data;
 }
 class SqlDurableRulePartition {
     db;
@@ -368,14 +369,18 @@ class SqlDurableRulePartition {
         return this.db.dialect === "tidb" ? tidbSql : pgSql;
     }
     async read() {
-        const { rows } = await this.db.query(this.q(`SELECT actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
+        return refusingUnreadableColumns(`bucket ${this.ownerKey}`, () => this.readBucketRow());
+    }
+    async readBucketRow() {
+        const { rows } = await this.db.query(this.q(`SELECT actor, counter, rev, ${jsonColumnText("tidb", "rules_json")}, ${jsonColumnText("tidb", "tombstones_json")}, ${jsonColumnText("tidb", "quarantined_json")}, ${jsonColumnText("tidb", "observed_vector_json")}, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter, rev, ${jsonColumnText("pg", "rules_json")}, ${jsonColumnText("pg", "tombstones_json")}, ${jsonColumnText("pg", "quarantined_json")}, ${jsonColumnText("pg", "observed_vector_json")}, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
         const row = rows[0];
         if (row === undefined)
             return { ...EMPTY_BUCKET, rules: [], tombstones: [], quarantined: [] };
-        const rulesRaw = parseColumn(z.array(PersistedRuleRowSchema), row.rules_json, "rules_json", this.ownerKey);
-        const tombstonesRaw = parseColumn(z.array(RuleTombstoneSchema), row.tombstones_json, "tombstones_json", this.ownerKey);
-        const quarantinedRaw = parseColumn(z.array(QuarantinedRuleAddRowSchema), row.quarantined_json, "quarantined_json", this.ownerKey);
-        const observedVector = row.observed_vector_json === null || row.observed_vector_json === undefined ? undefined : parseColumn(FrontierSchema, row.observed_vector_json, "observed_vector_json", this.ownerKey);
+        const at = `${PERMISSION_RULE_TABLE} bucket ${this.ownerKey}`;
+        const rulesRaw = decodeJsonColumn(row.rules_json, readRulesJson, `${at}.rules_json`);
+        const tombstonesRaw = decodeJsonColumn(row.tombstones_json, readTombstonesJson, `${at}.tombstones_json`);
+        const quarantinedRaw = decodeJsonColumn(row.quarantined_json, readQuarantinedJson, `${at}.quarantined_json`);
+        const observedVector = row.observed_vector_json === null || row.observed_vector_json === undefined ? undefined : decodeJsonColumn(row.observed_vector_json, readObservedVectorJson, `${at}.observed_vector_json`);
         const expected = buildRuleBucketChecksum({ rules: rulesRaw, tombstones: tombstonesRaw, quarantined: quarantinedRaw, ...(observedVector !== undefined ? { observedVector } : {}) });
         if (String(row.checksum ?? "") !== expected) {
             throw new Error(`permission_rule bucket ${this.ownerKey} failed its integrity check (stored ${String(row.checksum)}, computed ${expected}) — ` +
@@ -548,7 +553,10 @@ export class SqlRuleApprovalRecordStore {
         return dialectProtocolJsonEncoder(this.db.dialect)(v, label);
     }
     async get(id) {
-        const { rows } = await this.db.query(this.q(`SELECT record_id, owner_kind, principal, kind, state, version, rev, candidates_json, offers_json, selected_offer, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ?`, `SELECT record_id, owner_kind, principal, kind, state, version, rev, candidates_json, offers_json, selected_offer, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1`), [id]);
+        return refusingUnreadableColumns(`approval record ${id}`, () => this.readApprovalRow(id));
+    }
+    async readApprovalRow(id) {
+        const { rows } = await this.db.query(this.q(`SELECT record_id, owner_kind, principal, kind, state, version, rev, ${jsonColumnText("tidb", "candidates_json")}, ${jsonColumnText("tidb", "offers_json")}, selected_offer, ${jsonColumnText("tidb", "redeemed_dots_json")}, tool_call_id, bound_input_hash, command, ${jsonColumnText("tidb", "edited_json")}, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ?`, `SELECT record_id, owner_kind, principal, kind, state, version, rev, ${jsonColumnText("pg", "candidates_json")}, ${jsonColumnText("pg", "offers_json")}, selected_offer, ${jsonColumnText("pg", "redeemed_dots_json")}, tool_call_id, bound_input_hash, command, ${jsonColumnText("pg", "edited_json")}, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1`), [id]);
         const row = rows[0];
         if (row === undefined)
             return undefined;
@@ -558,10 +566,11 @@ export class SqlRuleApprovalRecordStore {
         if (Number(row.version) !== RULE_APPROVAL_RECORD_SCHEMA) {
             return { staleSchema: true, id: String(row.record_id), ...identity };
         }
-        const candidates = parseColumn(z.array(RuleCandidateSchema), row.candidates_json, "candidates_json", id);
-        const offers = parseColumn(z.array(RuleOffer2Schema), row.offers_json, "offers_json", id);
-        const dotsRaw = row.redeemed_dots_json === null || row.redeemed_dots_json === undefined ? undefined : parseColumn(RedeemedDotsSchema, row.redeemed_dots_json, "redeemed_dots_json", id);
-        const edited = row.edited_json === null || row.edited_json === undefined ? undefined : parseColumn(RuleEditedSchema, row.edited_json, "edited_json", id);
+        const at = `${PERMISSION_RULE_APPROVAL_TABLE} row ${id}`;
+        const candidates = decodeJsonColumn(row.candidates_json, readCandidatesJson, `${at}.candidates_json`);
+        const offers = decodeJsonColumn(row.offers_json, readOffersJson, `${at}.offers_json`);
+        const dotsRaw = row.redeemed_dots_json === null || row.redeemed_dots_json === undefined ? undefined : decodeJsonColumn(row.redeemed_dots_json, readRedeemedDotsJson, `${at}.redeemed_dots_json`);
+        const edited = row.edited_json === null || row.edited_json === undefined ? undefined : decodeJsonColumn(row.edited_json, readEditedJson, `${at}.edited_json`);
         const kind = z.enum(["card", "import", "starter"]).safeParse(row.kind);
         const state = z.enum(["pending", "approved", "redeemed"]).safeParse(row.state);
         if (!kind.success || !state.success) {
@@ -716,10 +725,10 @@ export class SqlRuleImportTicketStore {
         if (row.redeemedOutcome !== undefined) {
             let outcome;
             try {
-                outcome = JSON.parse(row.redeemedOutcome);
+                outcome = decodeJsonColumn(row.redeemedOutcome, readJsonObjectColumn, `${PERMISSION_RULE_TICKET_TABLE}.redeemed_outcome for ticket ${ticketId}`);
             }
-            catch (err) {
-                throw new Error(`${PERMISSION_RULE_TICKET_TABLE}.redeemed_outcome for ticket ${ticketId} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+            catch (e) {
+                throw foldJsonColumn(e, (m) => new Error(`${m} — refusing rather than read a settled ticket as still open (which re-runs a redemption that already ran)`));
             }
             return { state: "settled", outcome };
         }
@@ -738,7 +747,7 @@ export class SqlRuleImportTicketStore {
         return affected === 1 ? { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId } : { ok: false };
     }
     async readRow(ticketId) {
-        const { rows } = await this.db.query(this.q(`SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, redeemed_outcome, ${SQL_DB_NOW_MS.tidb} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = ?`, `SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, redeemed_outcome, ${SQL_DB_NOW_MS.pg} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = $1`), [ticketId]);
+        const { rows } = await this.db.query(this.q(`SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, ${jsonColumnText("tidb", "redeemed_outcome")}, ${SQL_DB_NOW_MS.tidb} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = ?`, `SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, ${jsonColumnText("pg", "redeemed_outcome")}, ${SQL_DB_NOW_MS.pg} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = $1`), [ticketId]);
         const row = rows[0];
         if (row === undefined)
             return undefined;

package/dist/plugins/session-policy-store-sql.d.ts

@@ -1,6 +1,7 @@
 import { type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+import { type JsonColumnShape } from "./sql-json-column.js";
 import { type SqlDriver } from "./sql-driver.js";
 /** `session_policy.policy_key` 的**唯一铸造点**(core 复合键的 sha256)。
  *
@@ -8,6 +9,29 @@ import { type SqlDriver } from "./sql-driver.js";
  *  逐行重算这把键(身份在 hash 的**原像**里,等值 UPDATE 够不着)。两处各写一遍 sha256 表达式的下场是
  *  某天有人在这里改了 key 公式而收编腿还在按旧式算 —— 迁完的行从此谁也读不到,且**静默**。 */
 export declare const policyKeyFor: (sessionId: string, principal: string | undefined) => string;
+/**
+ * 一行的 **`rules` 体**(已按文本取出的那一串)→ 收窄好的 `SessionPermissionRules`(C1)。读不出形 ⇒
+ * `SessionPolicyError("corrupt")`,与 rev / gen 两道拒同口径、同一个码。
+ *
+ * 形判据复用**现成的那一只**读者 `readSessionPermissionRules`(五桶 `string[]` 的单一属主;未知键照旧忽略,
+ * 与 core 的 `normalizeRules` 同口径),不在这里铸第二份键集。
+ *
+ * 🔴 **恰好解一次码,而这是由读腿的投影保证的**(codex 对抗复审两轮,两条读法各自实测被推翻后的终形):
+ *  · 「体是什么就直接判形」——**错**:MariaDB(本仓 README 声明支持的 MySQL 协议后端之一)的 `JSON` 是
+ *    `LONGTEXT` 的**别名**,驱动只对真 JSON 传输类型自动解码 ⇒ 那台机器上每一条**合法**规则都以文本到达,
+ *    会被判成 `corrupt`(三个读点全挂,一台好机器变砖);
+ *  · 「体是串就再解一次」——**也错**:`JSON`/`JSONB` 列上驱动已经解过一次,于是一行体为 `"{}"`(一个把
+ *    `JSON.stringify` 多调了一次的迁移脚本的典型产物)会被解成 `{}` 并当作**空规则**端出去 —— 与本道拒
+ *    要关的 `null` 洞逐字同形,只是换了个入口。
+ * 两条读法错在**同一个地方**:从值本身分不出「驱动解过了」还是「没解过」。⇒ 让这个歧义在**构造上**不存在:
+ * 三个读点都把这一列**按文本**投影(`CAST(rules AS CHAR)` / `::text`),于是到这里恒是一只串、恰好解一次。
+ * JSON 列里的字符串标量按文本取出来**带着引号**(真库实测两方言同形:`"\"{}\""`)⇒ 解一次得到一只串 ⇒ 判坏;
+ * 文本承载的列取出来就是它自己 ⇒ 解一次得到对象 ⇒ 好体。**一条规则,两种承载,零方言分叉,不依赖驱动行为。**
+ *
+ * 🔴 S-550:上面这一整段现在是**整仓**的口径,实现搬进唯一属主 `sql-json-column.ts`(投影 `jsonColumnText`
+ * + 恰好解一次 `decodeJsonColumn` + 折码 `foldJsonColumn`);本店只留「形判据是哪一只」与「坏体折成哪个码」。
+ */
+export declare function readSessionRulesBody(body: unknown): JsonColumnShape<SessionPermissionRules>;
 /** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     private readonly db;

package/dist/plugins/session-policy-store-sql.js

@@ -1,25 +1,24 @@
 import { createHash } from "node:crypto";
 import { loosenReasons, SessionPolicyError, normalizeRules, stripRev } from "@sema-agent/core";
 import { readSessionPermissionRules, describeSessionPermissionRulesProblem } from "../session-policy-wire.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
 import { pgHasUnstorable } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDeadlockError, isDupKeyError } from "./sql-errors.js";
 export const policyKeyFor = (sessionId, principal) => createHash("sha256").update(JSON.stringify([sessionId, principal ?? null])).digest("hex");
 const policyKey = policyKeyFor;
 const RETRY_LIMIT = 8;
+export function readSessionRulesBody(body) {
+    const read = readSessionPermissionRules(body);
+    return read.problem !== undefined ? { problem: describeSessionPermissionRulesProblem(read.problem) } : { value: read.rules };
+}
 function readRulesBody(text, where) {
-    let body;
     try {
-        body = JSON.parse(text);
+        return decodeJsonColumn(text, readSessionRulesBody, where);
     }
-    catch {
-        throw new SessionPolicyError("corrupt", `session rules row ${where} carries a rules body that is not JSON (a torn or hand-edited write) — refusing rather than serve a row nobody can read as rules`);
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new SessionPolicyError("corrupt", `${m} — an unreadable rules body served as an EMPTY rule set would silently drop every tightening this session carries`));
     }
-    const read = readSessionPermissionRules(body);
-    if (read.problem !== undefined) {
-        throw new SessionPolicyError("corrupt", `session rules row ${where} carries a malformed rules body (${describeSessionPermissionRulesProblem(read.problem)}) — refusing rather than serve it as an EMPTY rule set, which would silently drop every tightening this session carries`);
-    }
-    return read.rules;
 }
 function rowToStored(r, where) {
     const rev = Number(r.rev);
@@ -30,11 +29,7 @@ function rowToStored(r, where) {
     if (!Number.isFinite(gen) || !Number.isInteger(gen) || gen < 0) {
         throw new SessionPolicyError("corrupt", `session rules row ${where} carries lineage gen ${String(r.gen)} — a generation is a whole number ≥ 0; refusing rather than let a reader judge lineage by a value nothing minted`);
     }
-    const raw = r.rules;
-    if (typeof raw !== "string") {
-        throw new Error(`session rules row ${where}: the read did not project the rules column as TEXT (got ${typeof raw}) — the SELECT and rowToStored have drifted apart`);
-    }
-    return { ...readRulesBody(raw, where), rev, gen };
+    return { ...readRulesBody(r.rules, `session_policy.rules ${where}`), rev, gen };
 }
 export class SqlSessionPolicyStore {
     db;
@@ -48,13 +43,13 @@ export class SqlSessionPolicyStore {
         return isDupKeyError(this.db.dialect, e);
     }
     async getRules(sessionId, principal) {
-        const { rows } = await this.db.query(this.q("SELECT CAST(rules AS CHAR) AS rules, rev, gen FROM session_policy WHERE policy_key = ?", "SELECT rules::text AS rules, rev, gen FROM session_policy WHERE policy_key = $1"), [policyKey(sessionId, principal)]);
+        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "rules")}, rev, gen FROM session_policy WHERE policy_key = ?`, `SELECT ${jsonColumnText("pg", "rules")}, rev, gen FROM session_policy WHERE policy_key = $1`), [policyKey(sessionId, principal)]);
         if (!rows[0])
             return null;
         return rowToStored(rows[0], `for session ${JSON.stringify(sessionId)}`);
     }
     async listBySession(sessionId) {
-        const { rows } = await this.db.query(this.q("SELECT principal, CAST(rules AS CHAR) AS rules, rev, gen FROM session_policy WHERE session_id = ?", "SELECT principal, rules::text AS rules, rev, gen FROM session_policy WHERE session_id = $1"), [sessionId]);
+        const { rows } = await this.db.query(this.q(`SELECT principal, ${jsonColumnText("tidb", "rules")}, rev, gen FROM session_policy WHERE session_id = ?`, `SELECT principal, ${jsonColumnText("pg", "rules")}, rev, gen FROM session_policy WHERE session_id = $1`), [sessionId]);
         return rows.map((r) => ({
             principal: r.principal == null ? undefined : String(r.principal),
             rules: rowToStored(r, `for session ${JSON.stringify(sessionId)} (enumeration)`),
@@ -63,7 +58,7 @@ export class SqlSessionPolicyStore {
     async putRules(sessionId, principal, rules, opts) {
         const key = policyKey(sessionId, principal);
         return this.retrying(() => this.tx(async (conn) => {
-            const { rows } = await conn.query(this.q("SELECT CAST(rules AS CHAR) AS rules, rev, gen FROM session_policy WHERE policy_key = ? FOR UPDATE", "SELECT rules::text AS rules, rev, gen FROM session_policy WHERE policy_key = $1 FOR UPDATE"), [key]);
+            const { rows } = await conn.query(this.q(`SELECT ${jsonColumnText("tidb", "rules")}, rev, gen FROM session_policy WHERE policy_key = ? FOR UPDATE`, `SELECT ${jsonColumnText("pg", "rules")}, rev, gen FROM session_policy WHERE policy_key = $1 FOR UPDATE`), [key]);
             const prior = rows[0] ? rowToStored(rows[0], `for session ${JSON.stringify(sessionId)} (pre-write snapshot)`) : undefined;
             const priorRev = prior?.rev ?? 0;
             if (opts?.expectedRev !== undefined && priorRev !== opts.expectedRev) {

package/dist/plugins/sql-json-column.d.ts

@@ -0,0 +1,128 @@
+/**
+ * **SQL JSON 列读腿的唯一属主**(S-550 设计稿 §2)—— 一列 JSON 怎么**投影**、怎么**恰好解一次码**、
+ * 读不出形怎么**拒**,整仓只有这一份定义。
+ *
+ * ── 病(KM / 7.92.2 C1 的真案,三库实测两次换形之后的终形)────────────────────────────────────
+ * 一条 JSON 列的值到 JS 手里时,**从值本身分不出「驱动解过了」还是「没解过」**:
+ *  · 「体是什么就直接判形」——**错**:MariaDB(README 声明支持的 MySQL 协议后端之一)的 `JSON` 是
+ *    `LONGTEXT` 的**别名**,驱动只对真 JSON 传输类型自动解码 ⇒ 那台机器上每一条**合法**行都以文本
+ *    到达,会被判成坏体(一台好机器变砖);
+ *  · 「体是串就再解一次」——**也错**:真 `JSON`/`JSONB` 列上驱动已经解过一次,于是一行体为 `"{}"`
+ *    (迁移脚本多调了一次 `JSON.stringify` 的典型产物)会被解成 `{}` 当成**空体**端出去 —— 在授权面上
+ *    那就是「运行中途放宽、零披露」。
+ * ⇒ 让歧义在**构造上**不存在:读腿把 JSON 列**按文本**投影({@link jsonColumnText}),到 JS 恒是一只串,
+ * {@link decodeJsonColumn} **恰好解一次**。JSON 列里的字符串标量按文本取出**带着引号** ⇒ 解一次仍是串
+ * ⇒ 形读者判坏;文本承载(LONGTEXT / TEXT)取出即自身 ⇒ 解一次得对象 ⇒ 好体。
+ * **一条规则,两种承载,零方言分叉,不依赖驱动行为。**
+ *
+ * ── 失败方向 = 拒(fail-closed),全店同向 ────────────────────────────────────────────────────
+ * `decodeJsonColumnLenient` **不存在**,而且不会有:容忍必须写在店的调用点上(显式 `try/catch` +
+ * `recordFailOpen`),让每一处容忍都留痕、都可数。本模块只有一个失败方向。
+ *
+ * ── 机器门 ──────────────────────────────────────────────────────────────────────────────────
+ * `test/sql-json-column-single-owner.test.ts` 三道:①`JSON.parse(` 在 `src/plugins/**` 只许出现在本文件
+ * (未改调的店走显式 `PENDING_STORES` 登记 + 反向门);②JSON 承载列(清单由 `schema-ensure-legs` 的录制
+ * 驱动**机器派生**,不手抄)在 SELECT 投影里必须经 {@link jsonColumnText};③{@link decodeJsonColumn} 的
+ * `read` 实参必须是具名读者,禁内联 `(b) => b as T`。
+ */
+import { z } from "zod";
+import type { SqlDialect } from "./sql-driver.js";
+/**
+ * 一个 JSON 承载列的 **SELECT 投影片段**(整仓唯一铸点)—— MySQL 协议 `CAST(col AS CHAR) AS col`,
+ * PostgreSQL `col::text AS col`。
+ *
+ * 🔴 **别名是产物的一部分,不是调用点的自由**:MySQL 协议下 `CAST(rules AS CHAR)` 的回报字段名是
+ * `CAST(rules AS CHAR)` 而不是 `rules` —— 把别名留给调用点写,就等于给每一处读腿留一个「忘了写别名,
+ * 行上于是没有这个键、读回恒 `undefined`」的静默洞。别名在这里一次钉死,行的键恒等于列名。
+ *
+ * 🔴 **`CAST` 不影响索引**:投影不在 `WHERE` 里;大体量列多一次文本拷贝,量级与现状同(驱动本来也解一次)。
+ */
+export declare function jsonColumnText(dialect: SqlDialect, column: string): string;
+/**
+ * 同一只投影的**裸表达式**(不带别名)—— 给 `WHERE` / `UPDATE … WHERE` 这种**没有别名位**的地方用。
+ *
+ * 🔴 存在的唯一理由是「别名位在那里不合法」,**不是**给读腿留第二条路:读腿一律用 {@link jsonColumnText}
+ * (别名是它的产物的一部分,理由见那只函数)。今天整仓只有一处消费方 —— `one-time-migrations.ts` 的
+ * M4(把 `device_audit.detail` 里 JSON 文本 `null` 的旧行改成列 NULL),它要在 `WHERE` 里判这一列的**文本**,
+ * 而「怎么把一列 JSON 取成文本」这件事整仓只能有一种写法:两种承载(真 JSON 列 / LONGTEXT 别名)在这条
+ * 表达式下合成同一只串,迁移的判等因此与读腿的判形**看同一份字节**。
+ */
+export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string): string;
+/**
+ * 一次读回失败的**种别**(店层码,闭集):
+ *  · `not-text` —— 拿到的不是串 = **读腿漏了投影**,那是**码的问题不是数据的问题** ⇒ 响亮的程序错,
+ *    绝不冒充「你的库坏了」({@link foldJsonColumn} 因此**不折**这一种);
+ *  · `not-json` —— 解不出 JSON(撕裂写 / 手改 / 非 JSON 字节);
+ *  · `malformed` —— 解出来了,但该店的形读者不认(`null` 字面 / 字符串标量 / 双重编码 / 缺键错型)。
+ */
+export type SqlJsonColumnProblem = "not-text" | "not-json" | "malformed";
+/**
+ * 店层码,**不上 wire**:各店在自己的错误映射里把它折成该店既有的 corrupt 类码(见 {@link foldJsonColumn})。
+ * 终局对外码经 7.92.2 的词法门,永不裸穿。
+ */
+export declare class SqlJsonColumnError extends Error {
+    readonly problem: SqlJsonColumnProblem;
+    /** 出事的坐标(`<table>.<column> for <identity>`)—— 进错误文案,让运维知道去看哪一行。 */
+    readonly where: string;
+    constructor(problem: SqlJsonColumnProblem, where: string, detail: string);
+}
+/** 形读者认了:带上收窄后的值。 */
+export interface JsonColumnShapeOk<T> {
+    readonly value: T;
+    readonly problem?: undefined;
+}
+/** 形读者不认:`problem` 是给人读的一句话(进 corrupt 文案)。 */
+export interface JsonColumnShapeBad {
+    readonly value?: undefined;
+    readonly problem: string;
+}
+/** {@link JsonColumnReader} 的答复。 */
+export type JsonColumnShape<T> = JsonColumnShapeOk<T> | JsonColumnShapeBad;
+/**
+ * 一只**形读者** = 「解出来的体 → 这个店认不认」。判据必须是该店**既有**的那一只(core 导出的验证器 /
+ * 本店的 zod schema / wire 面的单一属主读者),**不新造第二份键集** —— 两份键集迟早分叉,而分叉的那一天
+ * 是「写得进、读不出」。
+ */
+export type JsonColumnReader<T> = (body: unknown) => JsonColumnShape<T>;
+/**
+ * **按文本取出的一列 JSON → 该店认得的值**(整仓唯一解码点)。
+ *
+ * @param text  该列**按 {@link jsonColumnText} 投影**后的单元格。恒是串;不是串 ⇒ `not-text`(程序错)。
+ * @param read  该店**既有的**形读者(见 {@link JsonColumnReader})。
+ * @param where 坐标文案(`<table>.<column> for <identity>`)。
+ */
+export declare function decodeJsonColumn<T>(text: unknown, read: JsonColumnReader<T>, where: string): T;
+/**
+ * 店层折码的**唯一规则**(`catch (e) { throw foldJsonColumn(e, (m) => new XError("corrupt", m)); }`)。
+ *
+ * 🔴 `not-text` **不折**:它是读腿自己的缺陷(投影漏了),折成「这一行坏了」会把一次代码漂伪装成一次
+ * 数据事故 —— 这条判别只写在这里一处,五个店不各写一遍(各写一遍的下场是某天有一处把程序错也折了)。
+ * 非本模块的错误原样透出(连接 / 超时 / 权限本来就该照原样上抛)。
+ */
+export declare function foldJsonColumn(e: unknown, corrupt: (message: string) => Error): Error;
+/**
+ * 把一只**既有的 zod schema** 当形读者用(本仓多数店的形判据就是它自己那份 schema)。
+ * `create*` 而不是 `build*`:产物是一只函数([ref] N2 命名律)。
+ */
+export declare function createZodColumnReader<T>(schema: z.ZodType<T>): JsonColumnReader<T>;
+/**
+ * **自由载荷列**的最小形读者:只判「这是一只 JSON 对象」,不碰键集。
+ *
+ * 给那些**schema 属主不在本仓 / 不在本层**的列用(approval 的 `card_json`、device 的审计 `detail`):
+ * 持久层对它们保持透明字节存取语义,但「是不是一只对象」这一条仍然判 —— 那正是 `null` 字面 / 字符串
+ * 标量 / 双重编码三形的落点。**不是**不判形的借口:一列有结构属主的,必须用属主那只读者。
+ */
+export declare const readJsonObjectColumn: JsonColumnReader<Record<string, unknown>>;
+/** 「一只普通 JSON 对象」的收窄谓词(`null` / 数组 / 标量都不是)。谓词而非 `as`:边界铸形门 [ref] §2。 */
+export declare function isJsonObject(v: unknown): v is Record<string, unknown>;
+/**
+ * **任意 JSON 值**的形读者 —— 只把 `not-json` 挡下来,`null` / 标量 / 数组一律是**合法的值**。
+ *
+ * 🔴 用它的列必须满足一个硬条件:**它的 wire 契约本身就是「任意 JSON 值」,而且「值是 `null`」与
+ * 「这一格缺席」在该列上是两件不同的事、且由**列的 NULL** 区分。今天整仓只有一处符合:
+ * `approval_ask.updated_input`([ref] / [ref] 的三态读法 —— 列 NULL = 没带编辑,JSON 文本 `"null"` =
+ * **编辑成 null**;把 `"null"` 判成坏体会把一条合法的人类编辑抹掉)。
+ * 一列只要有结构,就**不许**用它 —— 那是把形判据静默关掉。
+ */
+export declare const readAnyJsonValueColumn: JsonColumnReader<unknown>;
+//# sourceMappingURL=sql-json-column.d.ts.map

package/dist/plugins/sql-json-column.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+const COLUMN_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function jsonColumnText(dialect, column) {
+    return `${jsonColumnTextExpr(dialect, column)} AS ${column}`;
+}
+export function jsonColumnTextExpr(dialect, column) {
+    if (!COLUMN_NAME_RE.test(column)) {
+        throw new Error(`jsonColumnTextExpr: ${JSON.stringify(column)} is not a bare column identifier — refusing to splice it into SQL text`);
+    }
+    return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
+}
+export class SqlJsonColumnError extends Error {
+    problem;
+    where;
+    constructor(problem, where, detail) {
+        super(`${where}: ${detail}`);
+        this.name = "SqlJsonColumnError";
+        this.problem = problem;
+        this.where = where;
+    }
+}
+function describeBody(body) {
+    if (body === null)
+        return "the JSON literal `null`";
+    if (Array.isArray(body))
+        return "a JSON array";
+    if (typeof body === "string")
+        return `a JSON string scalar (${JSON.stringify(body.slice(0, 64))}) — the column was written pre-encoded, or double-encoded`;
+    return `a JSON ${typeof body}`;
+}
+export function decodeJsonColumn(text, read, where) {
+    if (typeof text !== "string") {
+        throw new SqlJsonColumnError("not-text", where, `the SELECT did not project this column as TEXT (got ${text === null ? "null" : typeof text}) — the read leg and decodeJsonColumn have drifted apart`);
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch (err) {
+        throw new SqlJsonColumnError("not-json", where, `carries bytes that are not JSON (${err instanceof Error ? err.message : String(err)}) — refusing rather than serve a row nobody can read`);
+    }
+    const shape = read(body);
+    if (shape.problem !== undefined) {
+        throw new SqlJsonColumnError("malformed", where, `carries ${describeBody(body)} that this store cannot read (${shape.problem}) — refusing rather than serve it as an empty/partial value`);
+    }
+    return shape.value;
+}
+export function foldJsonColumn(e, corrupt) {
+    if (e instanceof SqlJsonColumnError && e.problem !== "not-text")
+        return corrupt(e.message);
+    return e instanceof Error ? e : new Error(String(e));
+}
+export function createZodColumnReader(schema) {
+    return (body) => {
+        const parsed = schema.safeParse(body);
+        return parsed.success ? { value: parsed.data } : { problem: parsed.error.message };
+    };
+}
+export const readJsonObjectColumn = (body) => isJsonObject(body) ? { value: body } : { problem: "expected a JSON object" };
+export function isJsonObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export const readAnyJsonValueColumn = (body) => ({ value: body });
+//# sourceMappingURL=sql-json-column.js.map

package/dist/plugins/task-list-store-sql.d.ts

@@ -1,6 +1,7 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type TaskListStore } from "@sema-agent/core";
+import { type TaskListItem, type TaskListStore } from "@sema-agent/core";
+import { type JsonColumnShape } from "./sql-json-column.js";
 export declare const TASK_LIST_META_TABLE = "task_list_meta";
 export declare const TASK_LIST_ITEM_TABLE = "task_list_item";
 /**
@@ -25,6 +26,17 @@ export declare const TASK_LIST_ITEM_TABLE = "task_list_item";
  * 批量删本表的行,两个消费点必须读同一个函数 —— 键派生有两份就是「在线删除删得掉、留存腿删不掉」。
  */
 export declare function taskListKeyFor(sessionId: string): string;
+/**
+ * `task_list_item.item_json` 的**形读者**(S-550)。
+ *
+ * 🔴 判据刻意只到「一只 JSON 对象 + 一把串 id」为止,**不复刻 core 的 `TaskListItem` 键表**:那张表的
+ * 属主在 core(`tools/task-list.d.ts`),而 core 今天没有导出验证器 —— 在这里手写一份等价 schema 就是
+ * 设计稿明令禁止的「第二份键集」,它迟早与 core 分叉,而分叉那天是「写得进、读不出」。
+ * 这一条最小判据已经把四形坏体全关在门外(`null` 字面 / JSON 字符串标量 / 双重编码 / 非 JSON),
+ * 而本店此前是**零判据**(裸 `JSON.parse` + `as TaskListItem`):一行 `"null"` 会被当成一条 item 端给模型。
+ * core 哪天导出了验证器,这里换成它、判据只增不减。
+ */
+export declare function readTaskListItemBody(body: unknown): JsonColumnShape<TaskListItem>;
 export declare function ensureTiDBTaskListSchema(pool: MySqlPool): Promise<void>;
 export declare function ensurePgTaskListSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
 /**

package/dist/plugins/task-list-store-sql.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { assertJsonMetadata } from "@sema-agent/core";
 import { pgHasUnstorable, pgSafeJsonStringify, PgUnstorableError } from "./pg-safe-json.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
 export const TASK_LIST_META_TABLE = "task_list_meta";
 export const TASK_LIST_ITEM_TABLE = "task_list_item";
 export function taskListKeyFor(sessionId) {
@@ -14,8 +15,20 @@ function arrayIndexOf(id) {
     const n = Number(id);
     return Number.isSafeInteger(n) && n < 2 ** 32 - 1 ? n : null;
 }
-function parseItem(v) {
-    return JSON.parse(String(v));
+export function readTaskListItemBody(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return { problem: "expected a JSON object" };
+    if (typeof body.id !== "string")
+        return { problem: "the item carries no string `id`" };
+    return { value: body };
+}
+function parseItem(v, where) {
+    try {
+        return decodeJsonColumn(v, readTaskListItemBody, `${TASK_LIST_ITEM_TABLE}.item_json ${where}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`TaskListStore: ${m} — refusing rather than hand the model a row nobody can read as a task`));
+    }
 }
 function assertListKeyBytes(listKey) {
     if (Buffer.byteLength(listKey, "utf8") > 190) {
@@ -147,8 +160,8 @@ export function createTiDBTaskListStore(pool, listKey) {
     };
     const build = (q, inTx) => ({
         get: async (id) => {
-            const [rows] = (await q.query(`SELECT item_json FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = ? AND id = ?${inTx ? " FOR UPDATE" : ""}`, [listKey, id]));
-            return rows.length > 0 ? parseItem(rows[0].item_json) : undefined;
+            const [rows] = (await q.query(`SELECT ${jsonColumnText("tidb", "item_json")} FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = ? AND id = ?${inTx ? " FOR UPDATE" : ""}`, [listKey, id]));
+            return rows.length > 0 ? parseItem(rows[0].item_json, `for list ${listKey} item ${JSON.stringify(id)}`) : undefined;
         },
         set: async (id, item) => {
             if (item.metadata)
@@ -161,8 +174,8 @@ export function createTiDBTaskListStore(pool, listKey) {
             return res.affectedRows === 1;
         },
         list: async () => {
-            const [rows] = (await q.query(`SELECT item_json FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = ? ORDER BY id_num IS NULL, id_num, sort_seq${inTx ? " FOR UPDATE" : ""}`, [listKey]));
-            return rows.map((r) => parseItem(r.item_json));
+            const [rows] = (await q.query(`SELECT ${jsonColumnText("tidb", "item_json")} FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = ? ORDER BY id_num IS NULL, id_num, sort_seq${inTx ? " FOR UPDATE" : ""}`, [listKey]));
+            return rows.map((r) => parseItem(r.item_json, `for list ${listKey} (enumeration)`));
         },
         allocateId: async () => (inTx ? allocateOn(execOn(q), "tidb", listKey) : tx((c) => allocateOn(execOn(c), "tidb", listKey))),
         ...(inTx
@@ -203,8 +216,8 @@ export function createPgTaskListStore(pool, listKey) {
     };
     const build = (q, inTx) => ({
         get: async (id) => {
-            const { rows } = await q.query(`SELECT item_json FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = $1 AND id = $2${inTx ? " FOR UPDATE" : ""}`, [listKey, id]);
-            return rows.length > 0 ? parseItem(rows[0].item_json) : undefined;
+            const { rows } = await q.query(`SELECT ${jsonColumnText("pg", "item_json")} FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = $1 AND id = $2${inTx ? " FOR UPDATE" : ""}`, [listKey, id]);
+            return rows.length > 0 ? parseItem(rows[0].item_json, `for list ${listKey} item ${JSON.stringify(id)}`) : undefined;
         },
         set: async (id, item) => {
             if (pgHasUnstorable(id) ||
@@ -224,8 +237,8 @@ export function createPgTaskListStore(pool, listKey) {
             return (res.rowCount ?? 0) === 1;
         },
         list: async () => {
-            const { rows } = await q.query(`SELECT item_json FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = $1 ORDER BY (id_num IS NULL), id_num, sort_seq${inTx ? " FOR UPDATE" : ""}`, [listKey]);
-            return rows.map((r) => parseItem(r.item_json));
+            const { rows } = await q.query(`SELECT ${jsonColumnText("pg", "item_json")} FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = $1 ORDER BY (id_num IS NULL), id_num, sort_seq${inTx ? " FOR UPDATE" : ""}`, [listKey]);
+            return rows.map((r) => parseItem(r.item_json, `for list ${listKey} (enumeration)`));
         },
         allocateId: async () => (inTx ? allocateOn(execOn(q), "pg", listKey) : tx((c) => allocateOn(execOn(c), "pg", listKey))),
         ...(inTx

package/dist/run-local.d.ts

@@ -136,4 +136,19 @@ export declare function promptYesNoOnTty(prompt: string, signal?: AbortSignal, s
  * `process.exit` so a test can assert the code; `main()` applies it.
  */
 export declare function runLocal(argv: string[], deps?: RunLocalDeps): Promise<number>;
+/** {@link installRunLocalExitBoundary} 的把手(同进程内反复装配的调用方=测试必须用它收尾)。 */
+export interface RunLocalExitBoundary {
+    /** 摘掉本次装配的两只信号处理器与退出边界钩。幂等。 */
+    dispose(): void;
+}
+/**
+ * 装上本进程的退出边界 + 两只信号处理器。理由与取舍逐字见上方注。
+ *
+ * `exit` 可注入**只**为让测试把「处理器真的走到了哪个码」量出来(生产恒 `process.exit`);它不是旋钮,
+ * 没有配置面。
+ */
+export declare function installRunLocalExitBoundary(deps: {
+    logger: Logger;
+    exit?: (code: number) => void;
+}): RunLocalExitBoundary;
 //# sourceMappingURL=run-local.d.ts.map

package/dist/run-local.js

@@ -44,6 +44,7 @@ import { createPermissionDeniedMeter } from "./observability/tool-trace.js";
 import { createKeyResolver } from "./key-resolver.js";
 import { createLogger } from "./observability/logger.js";
 import { fatalExit } from "./boot/fatal-exit.js";
+import { installProcessExitBoundary } from "./boot/exit-boundary.js";
 import { createMetrics } from "./observability/metrics.js";
 import { installSecretEnvScrubRecorder } from "./observability/secret-env-scrub.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
@@ -561,7 +562,38 @@ export async function runLocal(argv, deps = {}) {
     await fileBackend.dispose();
     return exitCode;
 }
+const RUN_LOCAL_SIGNAL_EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+export function installRunLocalExitBoundary(deps) {
+    const { logger } = deps;
+    const exit = deps.exit ?? ((code) => void process.exit(code));
+    const boundary = installProcessExitBoundary({ logger });
+    const onSignal = (signal) => {
+        const code = RUN_LOCAL_SIGNAL_EXIT_CODE[signal];
+        try {
+            logger.warn("run_local_signal_exit", { signal, code });
+        }
+        finally {
+            exit(code);
+        }
+    };
+    const onSigint = () => onSignal("SIGINT");
+    const onSigterm = () => onSignal("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    let disposed = false;
+    return {
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            process.removeListener("SIGINT", onSigint);
+            process.removeListener("SIGTERM", onSigterm);
+            boundary.dispose();
+        },
+    };
+}
 async function main() {
+    installRunLocalExitBoundary({ logger: createLogger(process.env.LOG_LEVEL) });
     const code = await runLocal(process.argv.slice(2));
     process.exit(code);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.93.4",
+  "version": "7.93.5",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",