@sema-agent/server 7.93.3 → 7.93.5

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/dist/tool-approval.d.ts

@@ -1,9 +1,9 @@
-import type { HostDecidedBy } from "./host-decision.js";
+import type { HostDecidedBy, HostSettledBy } from "./host-decision.js";
 import type { IncomingMessage } from "node:http";
 import { type AskRequest, type AskOutcome, type ReadRootGrantCandidate, type RuleOffer } from "@sema-agent/core";
 import { type CardRulePersisted, type RuleConsentLane } from "./rules-consent.js";
 import { type DenialLimitFallback, type RuleOffersAbsence, type ApprovalRequestFrame, type ApprovalRevokeFrame, type RuleEvidenceProjection } from "./approval-card.js";
-import { type ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
+import { type ApprovalAskStore, type AskRow } from "./plugins/approval-ask-store-sql.js";
 import type { ApprovalAskAuditSink } from "./approval-ask-audit-store.js";
 import { type GovernanceAskMarks } from "./governance-ask-marks.js";
 /** [ref]:审批 gate kind 闭集(core gateMatch 的 `human`/`irreversible_ask` ↔ outcome.gate "policy_ask")。
@@ -613,27 +613,6 @@ export declare function parseToolApprovalResponse(body: unknown): {
     ok: false;
     error: string;
 };
-/**
- * core 5.23.0([ref]/[ref]②)—— **宿主自报**的结算来源,`AskOutcome` 对象臂新开的口。本仓在这一格上有
- * **两种身份**,合成一只座是刻意的(两只座 = 同一个 wire 位的两个写者):
- *  · **铸**(本仓自己观察到的事实):只有 `"timeout"` —— 同步 `onAsk` 腿的等待窗归**宿主**所有(引擎不为
- *    一个它没排程的回调起表),所以「本仓的 TTL 窗走完了、没人答」这件事引擎结构上观察不到,不自报就
- *    永远被记成「一个人拒绝了」;
- *  · **转**(调用方在回决体里自报的事实,core 7.26.2 / #1016 起):`settledBy:"policy"` = 答这张卡的是
- *    **这台部署自己的策略**,不是人。本仓**零判据、原样过境**:词的拒绝逻辑归引擎(`resolveAsk` 对
- *    自报词表外的值是响亮 fail-closed deny),本仓抄一份词表的那天 core 加词就会被静默 400 掉。
- * 逐词(词表属主恒是 core):
- *  · `"human"` —— 与「不铸这个键」逐字同义(core 缺席即按人处理);
- *  · `"aborted"` —— core **明令拒收**宿主自报(那是引擎自家 fail-closed 端的词,宿主自报等于把自己的
- *    拒绝改标成引擎故障),所以它**不在** `AskOutcome` 的这一格上,本型也就够不着它。
- * 类型从 core 的**同步 outcome 面**推导(不手抄):`AskOutcome` 的对象臂上 `settledBy` 是**宿主报的事实**,
- * core 7.6.0([ref] S6-A)删掉的是那张**结算词表**(`ApprovalSettledBy`),不是这一格 —— 词由 core 从
- * 这个事实铸(`human_refused` / `approval_window_expired` / `policy_refused`)。core 若改这一格的词表,
- * 这里编译期先红。
- */
-type HostSettledBy = NonNullable<Extract<AskOutcome, {
-    allow: boolean;
-}>["settledBy"]>;
 /**
  * #1016 —— wire 上**开给调用方**的那一个词,从 core 的两只闭集里取**交集**。
  *
@@ -802,6 +781,33 @@ export declare function resolveApprovalLeg(input: {
      *  「窗偏短」(安全侧,§7.3 的误差方向论证)。 */
     nowMonotonicMs: number;
 }): ApprovalLegAssembly;
+/** 一条 **DECIDED 行**能交还给引擎的全部形(`AskOutcome` 减掉 park 路由那一臂 —— 一条有决议的行
+ *  从定义上不是「投递面拿走了它」)。{@link ToolApprovalCoordinator.notifyExternalDecision} 收的就是它。 */
+export type DecidedAskOutcome = Exclude<AskOutcome, "unavailable">;
+/** 铸点的入参形 = 行上与**这条决议本身**有关的三格。整行(`AskRow`)与 claim 败方读数都满足。 */
+type DecidedRowFacts = Pick<AskRow, "decision" | "settledBy"> & {
+    updatedInput?: unknown;
+};
+/**
+ * 🔴 **一条 DECIDED 行 → 交还给引擎的那个 outcome:全仓唯一铸点**(S-558)。
+ *
+ * 存在理由 = 这条投影此前被**手抄**在每个消费点上(`row.decision === "approve"` + `row.updatedInput`,
+ * 六处),于是给行加一格新事实就得记得改六处 —— `settledBy` 正是那个没人改到的格:一次**策略拒**在
+ * 重放 / 兄弟广播 / 歧义提交恢复三条路上全都退化成裸 `false`,而裸 `false` 在 core 那边逐字是
+ * 「**一个人**拒绝了」。手抄投影全面下线([ref]):消费点交行,形由这里铸。
+ *
+ * 三条读法,每条的属主注在别处,这里只落笔:
+ *  · **方向** —— `decision !== "approve"` 即拒(列的二值由店的 CAS 保证);
+ *  · **编辑载荷**([ref])—— `updatedInput` 键缺席 = 没带编辑 ⇒ 裸 `true`;在场(**含 `null`**)= 编辑的
+ *    字面值 ⇒ 对象臂(语义三态的唯一属主 = `AskRow.updatedInput` 顶注);
+ *  · **结算来源**(S-558)—— 行上非 null 即宿主自报的那个词(`null` = 人决,与「不铸这个键」同义;
+ *    语义属主 = `AskRow.settledBy` 顶注)。
+ *
+ * 🔴 approve 臂**不读**来源位,而且那不是「静默丢」:store 的入店形门(`assertDecideSettledBy`)让
+ * 「approve 行带来源位」在**写面不可表示** —— core 对 `{allow:true, settledBy}` 是 fail-closed 拒,
+ * 一条那样的行没有任何读回路径能诚实地交还给引擎,所以它在落库那一刻就被拒掉了,而不是在这里被吞掉。
+ */
+export declare function outcomeOfDecidedRow(row: DecidedRowFacts): DecidedAskOutcome;
 /**
  * Coordinates the live tool-approval HITL for the singleton runner. Process-local + same-replica (the pending map is
  * in memory, like QuestionCoordinator): a respond that lands on another replica finds nothing → 404. Present (passed
@@ -1194,7 +1200,7 @@ export declare class ToolApprovalCoordinator {
      * 真决议」,重复注册必须拿到**同一个**决议(approve 就是 approve)——合并会把外部批准的重复条目错
      * 结算成拒绝。已被结算过的条目再调 settle 天然无操作(幂等),所以本口对「赢家自己已 settle」安全。
      */
-    notifyExternalDecision(askId: string, allowed: boolean, updatedInput?: unknown): {
+    notifyExternalDecision(askId: string, outcome: DecidedAskOutcome): {
         settled: number;
     };
     /**