@sema-agent/server 7.93.3 → 7.93.5

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)) {
@@ -12,6 +13,18 @@ export function assertIdempotencyKeyShape(key) {
         throw new Error(`invalid idempotency key: must be 1-255 chars with no leading/trailing whitespace (got ${JSON.stringify(key.slice(0, 32))}${key.length > 32 ? "…" : ""}, length ${key.length})`);
     }
 }
+export const MAX_SETTLED_BY_CHARS = 16;
+export function assertDecideSettledBy(decision) {
+    const v = decision.settledBy;
+    if (v === undefined)
+        return;
+    if (v.length === 0 || v.length > MAX_SETTLED_BY_CHARS) {
+        throw new Error(`invalid settledBy: the settlement source is one word from the engine's closed set and lands in a VARCHAR(${MAX_SETTLED_BY_CHARS}) column — must be 1-${MAX_SETTLED_BY_CHARS} chars (got ${JSON.stringify(v.slice(0, 32))}${v.length > 32 ? "…" : ""}, length ${v.length})`);
+    }
+    if (decision.decision !== "deny") {
+        throw new Error(`invalid settledBy: a settlement source is only representable on a deny row (got decision="${decision.decision}") — only a person approves an action that EXECUTES, so an approve row carrying a non-human settlement source is a row no replay could honestly hand back to the engine`);
+    }
+}
 export class ApprovalAskReadAbortedError extends Error {
     constructor(where) {
         super(`approval-ask read ${where} aborted by caller`);
@@ -47,6 +60,7 @@ export function projectAskTerminalClaimTruth(row) {
         rev: row.rev,
         decision: row.decision,
         ...(row.updatedInput !== undefined ? { updatedInput: row.updatedInput } : {}),
+        settledBy: row.settledBy,
     };
 }
 export const APPROVAL_ASK_TABLE = "approval_ask";
@@ -87,6 +101,12 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     decision VARCHAR(16) NULL,
     decision_actor TEXT NULL,
     decision_note TEXT NULL,
+    -- settled_by(S-558 / #1016 持久半场):这条决议的结算来源词(NULL = 人答的)。语义、两态读法与
+    -- 「为什么是自己一列而不是塞进 decision_actor」的全文见 AskRow.settledBy 顶注。
+    -- VARCHAR(16):词表属主是 core(AskOutcome.settledBy,今天最长 7 字符 "timeout"),宽度与同表
+    -- decision 同尺同理由 —— 闭集词列,不是自由文本。截断面由入店形门堵死(assertDecideSettledBy),
+    -- 不靠「列够宽就不会截」这种运气(MySQL 非严格模式静默截、PG 直接报错 = 两方言不同答)。
+    settled_by VARCHAR(16) NULL,
     -- updated_input(S-26 / #304,A-054.15 收口):人批准时带的 ctrl+g 编辑实参,JSON 文本,与决议同一条
     -- UPDATE 原子落列;NULL = 没带编辑(与 JSON "null" = 编辑成 null 分家)。LONGTEXT 照 card_json 先例:
     -- 编辑实参是整只工具入参,VARCHAR/TEXT 会造静默截断面。语义三态与读法见 AskRow.updatedInput 顶注。
@@ -166,6 +186,8 @@ export async function ensurePgApprovalAskSchema(q) {
     decision VARCHAR(16) COLLATE "C",
     decision_actor TEXT COLLATE "C",
     decision_note TEXT COLLATE "C",
+    -- settled_by(S-558)—— MySQL 孪生逐字同形(宽度/语义/形门的理由写在那侧的行内注)。
+    settled_by VARCHAR(16) COLLATE "C",
     -- updated_input(S-26 / #304)—— MySQL 孪生逐字同形(语义/类型理由见那侧行内注;PG TEXT 无长度上限)。
     updated_input TEXT COLLATE "C",
     decided_at_ms BIGINT,
@@ -190,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))
@@ -210,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, 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));
 }
@@ -228,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),
@@ -243,16 +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),
-        ...(r.updated_input == null ? {} : { updatedInput: parseJsonColumn(r.updated_input) }),
+        settledBy: strOrNull(r.settled_by),
+        ...(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),
@@ -315,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) {
@@ -331,9 +370,9 @@ export class SqlApprovalAskStore {
         try {
             await conn.begin();
             await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES (?, ?, 'OPEN', 0, ?, ?)`, `INSERT INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES ($1, $2, 'OPEN', 0, $3, $4) ON CONFLICT (batch_id) DO NOTHING`), [row.batchId, row.taskId, now, now]);
-            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (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, 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) ` +
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (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, 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) ` +
-                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $11, $12, $13, $14, $15, $16, $17) ON CONFLICT (ask_id) DO NOTHING"), [
+            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (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, 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) ` +
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (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, 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) ` +
+                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $11, $12, $13, $14, $15, $16, $17) ON CONFLICT (ask_id) DO NOTHING"), [
                 row.askId,
                 row.taskId,
                 row.sourceTaskId,
@@ -389,6 +428,7 @@ export class SqlApprovalAskStore {
     async decideAsk(askId, batchId, decision) {
         if (decision.idempotencyKey != null)
             assertIdempotencyKeyShape(decision.idempotencyKey);
+        assertDecideSettledBy(decision);
         const now = Date.now();
         const dialect = this.db.dialect;
         const conn = await this.db.connect();
@@ -401,10 +441,11 @@ export class SqlApprovalAskStore {
             }
             let askRes;
             try {
-                askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=${ph(dialect, 1)}, decision_actor=${ph(dialect, 2)}, decision_note=${ph(dialect, 3)}, updated_input=${ph(dialect, 4)}, decided_at_ms=${ph(dialect, 5)}, idempotency_key=${ph(dialect, 6)}, rev=rev+1, updated_at_ms=${ph(dialect, 7)} WHERE ${pendingClaimWhere(dialect, 8)}`, [
+                askRes = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=${ph(dialect, 1)}, decision_actor=${ph(dialect, 2)}, decision_note=${ph(dialect, 3)}, settled_by=${ph(dialect, 4)}, updated_input=${ph(dialect, 5)}, decided_at_ms=${ph(dialect, 6)}, idempotency_key=${ph(dialect, 7)}, rev=rev+1, updated_at_ms=${ph(dialect, 8)} WHERE ${pendingClaimWhere(dialect, 9)}`, [
                     decision.decision,
                     decision.decisionActor == null ? null : this.json(decision.decisionActor),
                     decision.decisionNote ?? null,
+                    decision.settledBy ?? null,
                     decision.updatedInput === undefined ? null : this.json(decision.updatedInput),
                     now,
                     decision.idempotencyKey ?? null,
@@ -461,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) };
             }
@@ -590,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;