@sema-agent/server 7.93.7 → 7.95.0

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

@@ -20,10 +20,23 @@
  * `recordFailOpen`),让每一处容忍都留痕、都可数。本模块只有一个失败方向。
  *
  * ── 机器门 ──────────────────────────────────────────────────────────────────────────────────
- * `test/sql-json-column-single-owner.test.ts` 三道:①`JSON.parse(` 在 `src/plugins/**` 只许出现在本文件
+ * `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`。
+ * `read` 实参必须是具名读者,禁内联 `(b) => b as T`;④(S-577)**读者 × 列可空性**求交,**双向**:每一只
+ * 形读者对承载列的可空性要求写在门的那张闭集表里,与 DDL 机器派生的读数不符即红(两个方向各一格)。
+ * 那条要求此前是注释里的一句散文,而整仓第二个用它的地方把它违了一整版。
+ *
+ * ── 「任意 JSON 值」那一族的三只铸点(S-577;区别在**名字**里,不在散文里)─────────────────────
+ * 一列的载荷没有声明形时,`null` 字面算不算合法值,**只由这一列有没有「缺席」这个状态**决定 —— 而那是
+ * 列可空性的另一种说法。所以这一族按可空性拆成三只,各自的前置条件由门双向咬:
+ *  | 铸点 | 承载列必须 | JSON 字面 `null` |
+ *  |---|---|---|
+ *  | {@link readTriStateJsonValueColumn} | **可空** | 合法值(缺席由列 NULL 单独表达) |
+ *  | {@link readNonNullJsonValueColumn} | **可空** | 判坏(缺席就落 SQL NULL,写不进 `null` 字面) |
+ *  | {@link readOpaqueJsonValueColumn} | **NOT NULL** | 合法值(该列**没有**缺席态 ⇒ 不与任何东西同形) |
+ * 🔴 三条前置条件都是**机器判**的,没有第四种「看情况」——一列要是三只都不满足,它要的是自己的结构化
+ * 读者({@link createZodColumnReader} / {@link createObjectColumnReader}),不是这一族里的第四只。
  */
 import { z } from "zod";
 import type { SqlDialect } from "./sql-driver.js";
@@ -42,20 +55,35 @@ export declare function jsonColumnText(dialect: SqlDialect, column: string): str
  * 同一只投影的**裸表达式**(不带别名)—— 给 `WHERE` / `UPDATE … WHERE` 这种**没有别名位**的地方用。
  *
  * 🔴 存在的唯一理由是「别名位在那里不合法」,**不是**给读腿留第二条路:读腿一律用 {@link jsonColumnText}
- * (别名是它的产物的一部分,理由见那只函数)。今天整仓只有一处消费方 —— `one-time-migrations.ts` 的
- * M4(把 `device_audit.detail` 里 JSON 文本 `null` 的旧行改成列 NULL),它要在 `WHERE` 里判这一列的**文本**,
+ * (别名是它的产物的一部分,理由见那只函数)。今天整仓**两处**消费方,各自的「别名位不合法」都是真的:
+ *  · `one-time-migrations.ts` 的 M4(把 `device_audit.detail` 里 JSON 文本 `null` 的旧行改成列 NULL)——
+ *    它要在 `WHERE` 里判这一列的**文本**,而 `WHERE` 没有别名位;
+ *  · `workflow-journal-store-sql.ts` 的 `loadPage`(S-550 车③a)—— 那一列的投影裹在一条
+ *    `CASE WHEN LENGTH(result) > ? THEN NULL ELSE <expr> END AS result_json` 里:**别名属于整条 CASE**
+ *    (`result_json`,因为超字节门的那一支要给 `NULL`),CASE 里面的表达式位上写别名是语法错。
  * 而「怎么把一列 JSON 取成文本」这件事整仓只能有一种写法:两种承载(真 JSON 列 / LONGTEXT 别名)在这条
- * 表达式下合成同一只串,迁移的判等因此与读腿的判形**看同一份字节**。
+ * 表达式下合成同一只串,迁移的判等、分页腿的取文本因此与读腿的判形**看同一份字节**。
+ *
+ * 🚧 **门② 看不见本函数的产物**(如实声明,车① §8.4 登记过的射程边界):它只跳过 `jsonColumnText(…)` 的
+ * 子树,本函数的插值对它是一个不透明表达式。所以「误用进 SELECT 投影且没给别名」这一形没有机器门 ——
+ * 误用的落点是真库上当场的 `SqlJsonColumnError("not-text")` 响亮抛(行上没有那个键 ⇒ `undefined`),不是静默。
  */
 export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string): string;
 /**
- * 一次读回失败的**种别**(店层码,闭集):
+ * 一次读回失败的**种别**(店层码,**闭集**;运行期词表在这里,类型从它推导 —— 一张词表只有一个写者):
  *  · `not-text` —— 拿到的不是串 = **读腿漏了投影**,那是**码的问题不是数据的问题** ⇒ 响亮的程序错,
  *    绝不冒充「你的库坏了」({@link foldJsonColumn} 因此**不折**这一种);
  *  · `not-json` —— 解不出 JSON(撕裂写 / 手改 / 非 JSON 字节);
  *  · `malformed` —— 解出来了,但该店的形读者不认(`null` 字面 / 字符串标量 / 双重编码 / 缺键错型)。
+ *
+ * 🔴 与 core `CORRUPT_BODY_FORMS`(`@contract store.read_back_shape_judged`)的**逐形对拍**写在
+ * `test/store-contract-kit.test.ts` 的契约句里,并由那里两格机器钉住(任一侧改词 ⇒ 红,回来重对)。
+ * 一句话版:core 那四形数的是**体的形**,本表数的是**承载**这一维 —— 两张表不是同一个坐标系,
+ * 所以不合并;本表的 `malformed` 是 core 三只体形词的共同落点,而 core 没有 `not-text` 的对应词
+ * (它没有 SELECT 投影这一维)。
  */
-export type SqlJsonColumnProblem = "not-text" | "not-json" | "malformed";
+export declare const SQL_JSON_COLUMN_PROBLEMS: readonly ["not-text", "not-json", "malformed"];
+export type SqlJsonColumnProblem = (typeof SQL_JSON_COLUMN_PROBLEMS)[number];
 /**
  * 店层码,**不上 wire**:各店在自己的错误映射里把它折成该店既有的 corrupt 类码(见 {@link foldJsonColumn})。
  * 终局对外码经 7.92.2 的词法门,永不裸穿。
@@ -122,6 +150,21 @@ export declare function foldJsonColumn(e: unknown, corrupt: (message: string) =>
  * 那会让一次代码漂 / 一次故障伪装成「几行数据坏了」,而两者的处置完全不同。
  */
 export declare function isJsonColumnBodyProblem(e: unknown): e is SqlJsonColumnError;
+/**
+ * **写腿的形闸** —— 一个值**序列化之后**还是不是这一列读得回来的形。判据与读腿**共用同一只形读者**,
+ * 所以「写得进」与「读得出」在构造上是同一句话。
+ *
+ * 🔴 为什么类型面不够(codex 对抗复审 [medium],验真后按类修):TS 的 `object` 说不出「序列化之后是一只
+ * JSON 对象」—— 数组 / `Date` / `toJSON()` 返回标量或 `null` 的对象**全部**通得过 `ctx: object`,却各自
+ * 写出一行读腿当场判坏的字节(`[1,2]` / `"1970-01-01T…"` / `null` / `7`;实测四形)。后果不是「这次写失败」
+ * 而是**这次写成功**:一行原本读得回来的耐久行被换成读不回来的字节,而调用方拿到的是 2xx。
+ * ⇒ 闸在**写点**,在落盘**之前**,方向 fail-closed:响亮拒,盘上那一行原样不动。
+ *
+ * @param text  该值按本列的编码器序列化后的文本(`toJSON` 已生效 —— 这正是类型面看不见的那一层)。
+ * @param read  这一列的形读者(**与读腿同一只**;两只不同就又是两份判据了)。
+ * @param where 坐标文案,同 {@link decodeJsonColumn}。
+ */
+export declare function assertJsonColumnWritable<T>(text: unknown, read: JsonColumnReader<T>, where: string): void;
 /**
  * 把一只**既有的 zod schema** 当形读者用(本仓多数店的形判据就是它自己那份 schema)。
  * `create*` 而不是 `build*`:产物是一只函数([ref] N2 命名律)。
@@ -131,10 +174,18 @@ export declare function createZodColumnReader<T>(schema: z.ZodType<T>): JsonColu
  * **载荷形属主不在本仓 / 本层**的那一族列的形读者 —— 判「这一格是不是一只 JSON 对象」,然后把它当成
  * 该店的域型交出去。整仓**只有这一处**做这一跳断言。
  *
- * 🔴 什么时候用它(硬条件,别扩大):这一列的键表属主在 **core**(`Checkpoint` / `ResumeOutcome` /
- * `GateOutcome` / `WorkflowRun` / `BackgroundAgentRecord` …),而 core **没有导出验证器**。在 server 手写
- * 一份等价 zod 就是设计稿明令禁止的**第二份键集**,它迟早与 core 分叉,而分叉那天是「写得进、读不出」。
- * 一列只要有本仓自己的 schema 属主,就必须用 {@link createZodColumnReader} —— 用本函数等于把形判据关小。
+ * 🔴 什么时候用它(硬条件,别扩大):这一列的键表属主**不在本层**,而那一层**没有导出验证器**。
+ * 两族,判据同一条(S-577 把这段与本函数第一句对齐 —— 它此前只写了 core 那一族,于是第二族要么被迫
+ * 违注、要么被迫另造一只读者,而「加一只特例读者」在本仓是红旗):
+ *  · 属主在 **core**:`Checkpoint` / `ResumeOutcome` / `GateOutcome` / `WorkflowRun` /
+ *    `BackgroundAgentRecord` …;
+ *  · 属主在**本仓的别一层**:`checkpoint_ctx.ctx` 的 `CheckpointCtx`(`http/route-ctx.ts`)—— 键表住在
+ *    HTTP 层,`src/plugins/**` 按分层不值 import 它,而那一层今天也没有运行期验证器。
+ * 在店里手写一份等价 zod 就是设计稿明令禁止的**第二份键集**,它迟早与属主分叉,而分叉那天是「写得进、
+ * 读不出」。⚠️ 现成的键闭集门(`request-key-closure.ts` 的 `taskBodyKeyIssue`)**不能**拿来当这里的读判据:
+ * 它自己的纪律逐字写着「拒只在 FRESH 提交面,RESUME 重放走宽容层」—— 把它打在读腿上会把存量 parked 行
+ * 整族砖死,方向正好相反。
+ * 一列只要有**本层自己的** schema 属主,就必须用 {@link createZodColumnReader} —— 用本函数等于把形判据关小。
  *
  * 🔴 为什么是一只工厂而不是让每个店各写一遍 `typeof body !== "object"`:那是同一条判据的 N 份拷贝
  * (S-550 车② 初版真的写了六份),而且每一份都要自己那一跳 `as`。收成一处之后,判据只有一个写者,
@@ -152,15 +203,43 @@ export declare const readJsonObjectColumn: JsonColumnReader<Record<string, unkno
 /** 「一只普通 JSON 对象」的收窄谓词(`null` / 数组 / 标量都不是)。谓词而非 `as`:边界铸形门 [ref] §2。 */
 export declare function isJsonObject(v: unknown): v is Record<string, unknown>;
 /**
- * **任意 JSON 值**的形读者 —— 只把 `not-json` 挡下来,`null` / 标量 / 数组一律是**合法的值**。
+ * **任意 JSON 值**的形读者,**用在可空列上** —— 只把 `not-json` 挡下来,`null` / 标量 / 数组一律是值。
+ *
+ * 🔴 前置条件(**门④ 机器执法,不是散文**):承载列**可空**,而「缺席」在它上面由**列的 NULL** 单独表达
+ * (三态列);于是 JSON 字面 `null` 是一个与缺席**不同形**的合法值。用在 `NOT NULL` 列上当场红 —— 那种列
+ * 根本没有缺席态,`null` 字面与「没有这一行」在点读的消费点上逐字同答,而那正是 S-577 的病灶
+ * (`checkpoint_ctx.ctx`:`JSON NOT NULL` + 有结构的载荷,一整版都读回一个没人分得出来的 `null`)。
+ * NOT NULL 且契约不透明的列用 {@link readOpaqueJsonValueColumn};缺席落 SQL NULL 的用
+ * {@link readNonNullJsonValueColumn}(那一族把 `null` 字面判坏)。
+ *
+ * 之所以叫得出「三态」:范本是 `approval_ask.updated_input`([ref] / [ref])—— 列 NULL = 没带编辑,
+ * JSON 文本 `"null"` = **编辑成 null**,对象 = 编辑成那只对象;把 `"null"` 判成坏体会把一条合法的人类
+ * 编辑抹掉。这一句是**理由**,不是名单:哪几处在用它由门数,别在这里写计数(S-577 之前这里写着
+ * 「今天整仓只有一处符合」—— 那句话当时就是假的,而没有门看着的计数,下一个人加第二处时不会来改它)。
  *
- * 🔴 用它的列必须满足一个硬条件:**它的 wire 契约本身就是「任意 JSON 值」,而且「值是 `null`」与
- * 「这一格缺席」在该列上是两件不同的事、且由**列的 NULL** 区分。今天整仓只有一处符合:
- * `approval_ask.updated_input`([ref] / [ref] 的三态读法 —— 列 NULL = 没带编辑,JSON 文本 `"null"` =
- * **编辑成 null**;把 `"null"` 判成坏体会把一条合法的人类编辑抹掉)。
- * 一列只要有结构,就**不许**用它 —— 那是把形判据静默关掉。
+ * 一列只要有结构,就**不许**用它 —— 那是把形判据静默关掉(这条是 S-577 的病灶判据,三只铸点同守)。
  */
-export declare const readAnyJsonValueColumn: JsonColumnReader<unknown>;
+export declare const readTriStateJsonValueColumn: JsonColumnReader<unknown>;
+/**
+ * **任意 JSON 值**的形读者,**用在 `NOT NULL` 列上** —— 同样只把 `not-json` 挡下来。
+ *
+ * 🔴 前置条件(门④ 机器执法,**反向**那一格):承载列 **NOT NULL**,所以这一列**根本没有缺席状态** ——
+ * 缺席 = 根本没有这一行 / 这一条。于是 JSON 字面 `null` 不与任何东西同形,它只是一个值。用在**可空**列上
+ * 当场红:那种列上「值是 `null`」与「这一格空着」立刻二义,要的是上面那两只之一。
+ *
+ * 🔴 还有一条前置条件门判不出来,必须亲读契约:这一列的载荷**契约上不透明、没有声明形**(本店不解释它,
+ * 只做传输中立的字节存取)。一列只要有声明形 / 有 schema 属主,就必须用 {@link createZodColumnReader}
+ * 或 {@link createObjectColumnReader} —— 用本函数等于把形判据关小,而「NOT NULL」这一条它自己是拦不住的。
+ * 范本:`agent_memory_engine_push_queue.payload`(`JSON`/`jsonb` NOT NULL,契约逐字是「传输中立包,本店
+ * 不解释」;读腿是 `rows.map` 的行字段,缺一条 = 数组里没这一行,`null` 与缺席**不同形**)。
+ *
+ * 🔴 **它与 {@link readTriStateJsonValueColumn} 的实现逐字相同,而且必须各自独立写出来** —— 不许收成
+ * `export const readOpaqueJsonValueColumn = readTriStateJsonValueColumn`(门④c2 会红)。两只的区别整个
+ * 落在**前置条件**上(一只要可空列、一只要 NOT NULL 列),而前置条件的载体就是**名字**:合成一个名字就等于
+ * 把两条互斥的前置条件重新揉回一起 —— 那正是 S-577 立案时那条散文析取的形。「去重」在这里去掉的不是重复,
+ * 是判据。
+ */
+export declare const readOpaqueJsonValueColumn: JsonColumnReader<unknown>;
 /**
  * **任意 JSON 值,但缺席由「列 NULL」表达**的列的形读者 —— `null` 字面判坏,其余一律是值。
  *
@@ -168,10 +247,33 @@ export declare const readAnyJsonValueColumn: JsonColumnReader<unknown>;
  * 写腿接的是 `unknown`(`PendingAction.args` / 账本行载荷 / leader 结果……),于是**数组 / 串 / 数 /
  * 布尔实参都写得进去** —— 拿 {@link readJsonObjectColumn} 判它们就是「写腿收得下、读腿读不出」,而且
  * 后果往往不是一行坏:`rows.map` 里一条这样的合法行会让整只读面抛。
- * 与 {@link readAnyJsonValueColumn} 的**唯一**区别是这一形:这族列的写腿把缺席(`undefined` / `null`)
- * 统一落成 **SQL NULL**,所以列里的 `null` 字面按构造写不进来 —— 它只可能来自手改 / 迁移脚本,判坏。
- * 用它之前先亲读写腿:缺席若**不是**落 SQL NULL(`approval_ask.updated_input` 的三态),用
- * {@link readAnyJsonValueColumn}。
+ * 与 {@link readTriStateJsonValueColumn} 的**唯一**区别是这一形(两只的承载列都必须**可空**):这族列的
+ * 写腿把缺席(`undefined` / `null`)统一落成 **SQL NULL**,所以列里的 `null` 字面按构造写不进来 —— 它只
+ * 可能来自手改 / 迁移脚本,判坏。用它之前先亲读写腿:缺席若**不是**落 SQL NULL
+ * (`approval_ask.updated_input` 的三态),用 {@link readTriStateJsonValueColumn};列若是 `NOT NULL`
+ * (根本没有缺席态),用 {@link readOpaqueJsonValueColumn}。
+ *
+ * 🔴 与 {@link readTriStateJsonValueColumn} 同属「承载列必须**可空**」这一族,所以同受门④ 约束
+ * (S-577):这族读者用在 `NOT NULL` 列上一律红 —— 列上没有 NULL 这个状态,「缺席」就无处安放,而写腿把
+ * 缺席落成 SQL NULL 这句话在那种列上根本执行不了。
  */
 export declare const readNonNullJsonValueColumn: JsonColumnReader<unknown>;
+/**
+ * **一只 JSON 数组**的承载形读者(内容判据归各列自己的既有属主,这里只判承载形)。
+ *
+ * 🔴 为什么在属主里而不是各店各写一遍(S-550 车③a 把车② 的店内私有形上收):今天有三个消费方
+ * (checkpoint 的 `rule_suggestions` / `pending_steer_queue`、memory-engine 的 `embedding`),判据逐字
+ * 相同,而「这一格是不是一只数组」恰好是坏体四形的落点 —— 三份拷贝迟早有一份忘了判 `null` 字面。
+ */
+export declare const readJsonArrayColumn: JsonColumnReader<unknown[]>;
+/**
+ * **一只字符串数组**的形读者(`image_bake.argv` / `bands`、`sandbox_image_index.bands`、
+ * `mailbox_message.hop_chain`)。
+ *
+ * 🔴 判到元素形是**必须**的,不是洁癖:mailbox 的 hop 链元素参与 core 的 `hop_loop` **等值比对**,
+ * 一条混进数字/对象的链会让准入判决改错;`argv` 是要交给构建器的命令行。四形坏体全落在这条判据外面。
+ */
+export declare const readStringArrayColumn: JsonColumnReader<string[]>;
+/** **串→串的映射**(`sandbox_image_index.toolchain_versions`、`agent_memory_engine_sync_cursor.base_revs`)。 */
+export declare const readStringRecordColumn: JsonColumnReader<Record<string, string>>;
 //# sourceMappingURL=sql-json-column.d.ts.map

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

@@ -9,6 +9,7 @@ export function jsonColumnTextExpr(dialect, column) {
     }
     return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
 }
+export const SQL_JSON_COLUMN_PROBLEMS = ["not-text", "not-json", "malformed"];
 export class SqlJsonColumnError extends Error {
     problem;
     where;
@@ -56,6 +57,9 @@ export function foldJsonColumn(e, corrupt) {
 export function isJsonColumnBodyProblem(e) {
     return e instanceof SqlJsonColumnError && e.problem !== "not-text";
 }
+export function assertJsonColumnWritable(text, read, where) {
+    decodeJsonColumn(text, read, where);
+}
 export function createZodColumnReader(schema) {
     return (body) => {
         const parsed = schema.safeParse(body);
@@ -69,6 +73,23 @@ export const readJsonObjectColumn = (body) => isJsonObject(body) ? { value: body
 export function isJsonObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-export const readAnyJsonValueColumn = (body) => ({ value: body });
+export const readTriStateJsonValueColumn = (body) => ({ value: body });
+export const readOpaqueJsonValueColumn = (body) => ({ value: body });
 export const readNonNullJsonValueColumn = (body) => body === null ? { problem: "the JSON literal `null` — absence is SQL NULL on this column, so a written `null` can only be a hand edit" } : { value: body };
+export const readJsonArrayColumn = (body) => Array.isArray(body) ? { value: body } : { problem: "expected a JSON array" };
+export const readStringArrayColumn = (body) => {
+    if (!Array.isArray(body))
+        return { problem: "expected a JSON array of strings" };
+    const bad = body.findIndex((x) => typeof x !== "string");
+    return bad === -1 ? { value: body } : { problem: `element ${bad} of the array is not a string` };
+};
+export const readStringRecordColumn = (body) => {
+    if (!isJsonObject(body))
+        return { problem: "expected a JSON object of string values" };
+    for (const [k, v] of Object.entries(body)) {
+        if (typeof v !== "string")
+            return { problem: `key ${JSON.stringify(k)} does not carry a string value` };
+    }
+    return { value: body };
+};
 //# sourceMappingURL=sql-json-column.js.map

package/dist/plugins/sql-row-helpers.d.ts

@@ -2,24 +2,18 @@
  * Shared pure row-mapping helpers for the SQL store twins ([ref] S8 纯 helper 归位).
  *
  * These were duplicated verbatim across the pg-/tidb- store twin pairs; each store imports the flavor
- * it was written against (usually under its historical local alias, e.g. `parseJsonStrict as
- * parseJson`) so call sites and semantics are byte-identical to before.
+ * it was written against so call sites and semantics are byte-identical to before.
  *
- * THREE parseJson flavors exist ON PURPOSE — they differ in what a corrupted/legacy JSON column
- * reads back as (lenient → null / strict → throw / fallback value), and the TWO nullable date→ISO
- * helpers differ in how a non-Date cell is rendered (String() passthrough vs `new Date()` re-parse).
- * Do NOT collapse them into one.
+ * 🔴 **JSON 列的解析不在这里,也永远不会回来**(S-550):本文件曾住着三只 `parseJson*`
+ * (lenient → `null` / strict → 抛 / fallback → 兜底),三种失败方向由**调用点自选** —— 那正是 S-550
+ * 要消灭的现状:同一格读不出的 JSON,在一个店里是「空体」、在另一个店里是「这一行不存在」、在第三个
+ * 店里是异常。三只在车③b **删除**(零别名、零转出),整仓唯一属主 = `sql-json-column.ts`
+ * (按文本投影 · 恰好解一次码 · 坏体一律拒),容忍写在店的调用点上(显式 `try/catch` + `recordFailOpen`)。
+ * 机器执法:`test/sql-json-column-single-owner.test.ts` 门① 对这三个**标识符**全仓零容忍。
+ *
+ * 剩下的两只 nullable date→ISO helper 仍然是两只:它们对一格非 Date 的渲染**刻意不同**
+ * (`String()` 原样透出 vs `new Date()` 重解析),不许合并。
  */
-/** JSON column → value; a corrupted/legacy JSON column reads back as `null` instead of failing the
- *  read. Non-strings pass through (node-pg parses jsonb → object already). */
-export declare function parseJsonLenient<T>(v: unknown): T | null;
-/** JSON column → value; malformed JSON THROWS. For stores whose write arm keeps the column clean
- *  (R7 终形:协议面拒绝式,库内恒干净,直读). Non-strings pass through (node-pg parses jsonb →
- *  object already). */
-export declare function parseJsonStrict<T>(v: unknown): T | null;
-/** JSON column → value with a caller-supplied fallback for NULL/corrupted cells. Non-strings pass
- *  through (node-pg parses jsonb → object already; tolerate a string just in case). */
-export declare function parseJsonOr<T>(v: unknown, fallback: T): T;
 /** NOT NULL datetime column → ISO string (drivers return Date; a string cell passes through via
  *  String() — NOT re-parsed). */
 export declare function toIso(v: unknown): string;

package/dist/plugins/sql-row-helpers.js

@@ -1,32 +1,3 @@
-export function parseJsonLenient(v) {
-    if (v == null)
-        return null;
-    if (typeof v !== "string")
-        return v;
-    try {
-        return JSON.parse(v);
-    }
-    catch {
-        return null;
-    }
-}
-export function parseJsonStrict(v) {
-    if (v == null)
-        return null;
-    return (typeof v === "string" ? JSON.parse(v) : v);
-}
-export function parseJsonOr(v, fallback) {
-    if (v == null)
-        return fallback;
-    if (typeof v !== "string")
-        return v;
-    try {
-        return JSON.parse(v);
-    }
-    catch {
-        return fallback;
-    }
-}
 export function toIso(v) {
     return v instanceof Date ? v.toISOString() : String(v);
 }

package/dist/plugins/store-backend.js

@@ -1,4 +1,5 @@
 import { homedir } from "node:os";
+import { buildDurableAbsenceNote, createCorruptReadSeat } from "../observability/corrupt-read-seat.js";
 import { join } from "node:path";
 import { AdoptionError, FileStorageBackend, FileSessionRepo } from "@sema-agent/core";
 import { FileWorkflowJournalStore } from "@sema-agent/core";
@@ -213,23 +214,16 @@ class LocalBackend {
     outcomeSinkInst;
     onWarn;
     onError;
+    discloseWarn;
     constructor(root, config, onWarn, onError) {
         this.onWarn = onWarn;
+        this.discloseWarn = onWarn ?? ((msg, meta) => console.warn(msg, meta));
         this.onError = onError;
         try {
             this.fileBackend = acquireLocalBackendWithWait(() => new FileStorageBackend({
                 root,
                 ...(config.fileHistory !== undefined ? { fileHistory: config.fileHistory } : {}),
-                onCorruptRead: (info) => this.onWarn?.("file_store_corrupt_read", {
-                    path: info.path,
-                    reason: info.reason,
-                    ...(info.sessionId !== undefined ? { sessionId: info.sessionId } : {}),
-                    ...(info.principal !== undefined ? { principal: info.principal } : {}),
-                    note: "a durable read was treated as ABSENT because the bytes were unreadable (never a plain ENOENT). " +
-                        "Consequence depends on which store read it: session-policy = that run lost its SUBTRACTIVE session-rule " +
-                        "layer (deployment policy / hooks / shell gate still applied); session repo = a listing silently omitted " +
-                        "rows; file-history = a rewind boundary or scope read as missing. Inspect the named path before deciding.",
-                }),
+                onCorruptRead: createCorruptReadSeat((msg, fields) => this.discloseWarn(msg, fields), "file_store_corrupt_read", buildDurableAbsenceNote("file-history = a rewind boundary or scope read as missing")),
             }), config.storeLockWaitMs, (fields) => this.onWarn?.("store_dir_lock_wait", { ...fields }));
         }
         catch (e) {
@@ -239,7 +233,9 @@ class LocalBackend {
             throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)}` +
                 (tail === undefined ? "" : ` ${tail}`));
         }
-        this.sessionStore = new LocalSessionStore(new FileSessionRepo(this.fileBackend.root), this.fileBackend.root);
+        this.sessionStore = new LocalSessionStore(new FileSessionRepo(this.fileBackend.root, {
+            onCorruptRead: createCorruptReadSeat((msg, fields) => this.discloseWarn(msg, fields), "session_repo_corrupt_read"),
+        }), this.fileBackend.root);
         this.runStore = new FileRunStore(this.fileBackend.root, {
             error: (msg, fields) => void (this.onError ?? this.onWarn)?.(msg, fields),
             strictHydrate: config.runStoreStrictHydrate,
@@ -249,7 +245,9 @@ class LocalBackend {
         this.approvalNonceStore = new FileApprovalNonceStore(this.fileBackend.root);
         this.approvalAskStore = new FileApprovalAskStore(this.fileBackend.root);
         this.sendFileLedgerStore = new FileSendFileLedger(this.fileBackend.root);
-        this.workflowJournalStore = new FileWorkflowJournalStore(this.fileBackend.root);
+        this.workflowJournalStore = new FileWorkflowJournalStore(this.fileBackend.root, undefined, {
+            onCorruptRead: createCorruptReadSeat((msg, fields) => this.discloseWarn(msg, fields), "workflow_journal_corrupt_read"),
+        });
         this.outcomeSinkInst = new FileOutcomeSink(this.fileBackend.root);
         const ownControlDir = fileMemoryControlDirFor(config);
         this.captureRecordsSource = ownControlDir === undefined

package/dist/plugins/store-contracts.d.ts

@@ -9,6 +9,10 @@
  * Rules for this file:
  *  - ZERO dialect dependencies (no mysql2, no pg) — types + pure functions only. The only imports
  *    allowed are core contract types and the neutral sql-row-helpers leaf.
+ *    (S-550 车③a:`mapBakeRow`/`mapImageRow`/`BAKE_SELECT_COLS` 搬回了它们**唯一**的消费者
+ *    `image-bake-store-sql.ts` / `image-index-sql.ts` —— 「两个 SQL 孪生共用」那条理由在孪生合成
+ *    单文件双方言之后就不存在了,而一条 SELECT 的**列清单**必须和它的**投影铸点**、**解码点**长在
+ *    同一个文件里:否则 JSON 承载列的投影门(它按「这个文件查了哪张表」定列集)对那份清单是瞎的。)
  *  - Adapters import their contracts from HERE; no adapter imports its twin (store-backend.ts, the
  *    composition root, is the one place that names every concrete adapter).
  *  - The TiDB adapters re-export these names for back-compat (the historical import surface), but new
@@ -447,10 +451,6 @@ export interface BakeRow {
     created_at: Date | string;
     updated_at: Date | string;
 }
-/** SELECT row → {@link BakeRecord} — shared by BOTH SQL twins ([ref] S8 归位, A3 沉底). */
-export declare function mapBakeRow(r: BakeRow): BakeRecord;
-/** Column list mapBakeRow expects — shared by BOTH SQL twins ([ref] S8 归位, A3 沉底). */
-export declare const BAKE_SELECT_COLS: string;
 /** Nested-build security posture (the operator console shows rootless vs privileged-dind). */
 export type ImageNestedBuildMode = "none" | "docker-cli-only" | "rootless-buildkit" | "privileged-dind";
 export interface ImageCapabilities {
@@ -540,6 +540,4 @@ export interface ImageRow {
     created_at: Date | string;
     updated_at: Date | string;
 }
-/** SELECT row → {@link ImageIndexEntry} — shared by BOTH SQL twins ([ref] S8 归位, A3 沉底). */
-export declare function mapImageRow(r: ImageRow): ImageIndexEntry;
 //# sourceMappingURL=store-contracts.d.ts.map

package/dist/plugins/store-contracts.js

@@ -1,4 +1,3 @@
-import { parseJsonOr, toIso as iso, normalizeIsoOrNull as isoOrNull } from "./sql-row-helpers.js";
 export class StoreBootRefusalError extends Error {
 }
 export const RUN_STATUS_CLASS = {
@@ -36,63 +35,4 @@ export function sessionTempoOfRunStatus(lastStatus) {
 export function runProvenElsewhere(run, thisInstanceId) {
     return typeof run.instanceId === "string" && run.instanceId.length > 0 && thisInstanceId !== undefined && run.instanceId !== thisInstanceId;
 }
-export function mapBakeRow(r) {
-    return {
-        bakeId: r.bake_id,
-        profile: r.profile,
-        bands: r.bands == null ? null : parseJsonOr(r.bands, []),
-        baseRef: r.base_ref,
-        push: !!r.push,
-        dryRun: !!r.dry_run,
-        logs: !!r.logs,
-        argv: parseJsonOr(r.argv, []),
-        status: r.status,
-        state: r.state ?? null,
-        digest: r.digest,
-        repo: r.repo,
-        ref: r.ref,
-        indexId: r.index_id,
-        exitCode: r.exit_code === null ? null : Number(r.exit_code),
-        error: r.error,
-        errorCode: r.error_code ?? null,
-        manifestSha: r.manifest_sha,
-        tag: r.tag,
-        idemKey: r.idem_key,
-        ingestSecret: r.ingest_secret,
-        runnerId: r.runner_id,
-        leaseUntil: isoOrNull(r.lease_until),
-        cancelRequested: !!r.cancel_requested,
-        requestedBy: r.requested_by,
-        createdAt: iso(r.created_at),
-        updatedAt: iso(r.updated_at),
-    };
-}
-export const BAKE_SELECT_COLS = "bake_id, profile, bands, base_ref, push, dry_run, logs, argv, status, state, digest, repo, ref, index_id, " +
-    "exit_code, error, error_code, manifest_sha, tag, idem_key, ingest_secret, runner_id, lease_until, " +
-    "cancel_requested, requested_by, created_at, updated_at";
-export function mapImageRow(r) {
-    return {
-        id: r.id,
-        profile: r.profile,
-        bands: parseJsonOr(r.bands, []),
-        repo: r.repo,
-        tag: r.tag,
-        digest: r.digest,
-        toolchainVersions: parseJsonOr(r.toolchain_versions, {}),
-        capabilities: parseJsonOr(r.capabilities, {}),
-        podContract: parseJsonOr(r.pod_contract, {}),
-        sizeBytes: r.size_bytes === null ? null : Number(r.size_bytes),
-        status: r.status,
-        visibility: r.visibility,
-        tenantId: r.tenant_id,
-        manifestSha: r.manifest_sha,
-        recipeGitSha: r.recipe_git_sha,
-        generatorVersion: r.generator_version,
-        buildDate: isoOrNull(r.build_date),
-        supersedes: r.supersedes,
-        signed: !!r.signed,
-        createdAt: isoOrNull(r.created_at) ?? new Date(0).toISOString(),
-        updatedAt: isoOrNull(r.updated_at) ?? new Date(0).toISOString(),
-    };
-}
 //# sourceMappingURL=store-contracts.js.map

package/dist/plugins/task-attachment-store.d.ts

@@ -24,21 +24,30 @@
  *  - 绑定:`bind` 把行钉到 sessionId(重复绑定=改绑,同 owner 内 last-wins;同 session 多 task 共享
  *    自然成立——listBySession 是物化输入)。未绑定行 = 上传后从未被任何 task 引用 ⇒ reapUnbound(TTL)。
  */
+import { z } from "zod";
 import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
 import { type IndexSpec } from "./ensure-index.js";
-export interface TaskAttachmentRecord {
-    id: string;
-    owner: string;
-    /** 消毒后的 basename(http 面用 core sanitizePathComponent 处理;store 只存不再消毒)。 */
-    name: string;
-    mime: string;
-    sha256: string;
-    sizeBytes: number;
-    createdAtMs: number;
-    sessionId?: string;
-    boundAtMs?: number;
-}
+/**
+ * 一条附件 meta 的**形属主**(整仓唯一那份键集)。
+ *
+ * 🔴 为什么是一只 schema 而不只是一个 interface(S-550 车③b):SQL 车道把这些字段拆成**标量列**,
+ * 形由 DDL 管;local 车道把整条记录**序列化成一个 JSON 档**(`attachments/<id>.json`),于是它需要一个
+ * 运行期的形判据 —— 而那个判据必须与这里的键集是**同一份**(第二份键集分叉的那天 = 「写得进、读不出」)。
+ * 所以类型从 schema 推导({@link TaskAttachmentRecord}),两者按构造不可能漂。
+ */
+export declare const TaskAttachmentRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    owner: z.ZodString;
+    name: z.ZodString;
+    mime: z.ZodString;
+    sha256: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    createdAtMs: z.ZodNumber;
+    sessionId: z.ZodOptional<z.ZodString>;
+    boundAtMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type TaskAttachmentRecord = z.infer<typeof TaskAttachmentRecordSchema>;
 export interface TaskAttachmentStore {
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;

package/dist/plugins/task-attachment-store.js

@@ -1,4 +1,16 @@
+import { z } from "zod";
 import { ensureIndexes } from "./ensure-index.js";
+export const TaskAttachmentRecordSchema = z.object({
+    id: z.string(),
+    owner: z.string(),
+    name: z.string(),
+    mime: z.string(),
+    sha256: z.string(),
+    sizeBytes: z.number(),
+    createdAtMs: z.number(),
+    sessionId: z.string().optional(),
+    boundAtMs: z.number().optional(),
+});
 export const TASK_ATTACHMENT_TABLE = "task_attachment";
 export function materializedRelPaths(atts) {
     const used = new Set();

package/dist/plugins/tidb-session-storage.d.ts

@@ -1,8 +1,8 @@
 import { BaseSessionStorage, type PromptEpochDescriptor, type SessionMetadata, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 export declare const SESSION_EVENT_LATEST_BY_TYPE_SQL: {
-    readonly floor: "SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ payload FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1";
-    readonly epochAnchor: "SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ seq, payload FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100";
+    readonly floor: `SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ ${string} FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1`;
+    readonly epochAnchor: `SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ seq, ${string} FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`;
 };
 /**
  * TiDB-backed {@link BaseSessionStorage} — the durable L1 event log for one session.

package/dist/plugins/tidb-session-storage.js

@@ -3,10 +3,12 @@ import { BaseSessionStorage, SessionError, leafIdAfterEntry, normalizePromptEpoc
 import { toIso } from "./sql-row-helpers.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { PLACEMENT_SELECT_COLUMNS, placementFromRow } from "./session-placement.js";
+import { decodeSessionEventPayload } from "./session-event-payload.js";
+import { jsonColumnText } from "./sql-json-column.js";
 const SESSION_EVENT_BY_TYPE_HINT = "/*+ USE_INDEX(session_event, idx_session_event_type) */";
 export const SESSION_EVENT_LATEST_BY_TYPE_SQL = {
-    floor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} payload FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1`,
-    epochAnchor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} seq, payload FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`,
+    floor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1`,
+    epochAnchor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} seq, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`,
 };
 const isDupKey = isMysqlDupKeyError;
 export class TiDBSessionStorage extends BaseSessionStorage {
@@ -28,7 +30,7 @@ export class TiDBSessionStorage extends BaseSessionStorage {
             if (rows.length === 0)
                 return undefined;
             for (const r of rows) {
-                const e = (typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload);
+                const e = decodeSessionEventPayload(r.payload, this.sessionId, r.seq);
                 const d = e.type === "prompt_epoch" ? normalizePromptEpoch(e) : normalizePromptEpoch(e.details?.promptEpoch);
                 if (d)
                     return d;
@@ -42,8 +44,8 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         if (!meta)
             return null;
         const { floorEntryId, floorSeq } = await TiDBSessionStorage.computeFloor(pool, sessionId);
-        const [eventRows] = await pool.query("SELECT payload FROM session_event WHERE session_id = ? AND seq >= ? ORDER BY seq ASC", [sessionId, floorSeq]);
-        const entries = eventRows.map((r) => typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload);
+        const [eventRows] = await pool.query(`SELECT seq, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? AND seq >= ? ORDER BY seq ASC`, [sessionId, floorSeq]);
+        const entries = eventRows.map((r) => decodeSessionEventPayload(r.payload, sessionId, r.seq));
         const placement = placementFromRow(meta);
         const metadata = { id: sessionId, createdAt: toIso(meta.created_at), ...(placement !== undefined ? { placement } : {}) };
         return new TiDBSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, floorEntryId, floorSeq);
@@ -52,8 +54,8 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         const [compRows] = await pool.query(SESSION_EVENT_LATEST_BY_TYPE_SQL.floor, [sessionId]);
         if (!compRows[0])
             return { floorEntryId: null, floorSeq: 0 };
-        const comp = (typeof compRows[0].payload === "string" ? JSON.parse(compRows[0].payload) : compRows[0].payload);
-        const fk = comp.firstKeptEntryId;
+        const comp = decodeSessionEventPayload(compRows[0].payload, sessionId, "latest compaction");
+        const fk = comp.type === "compaction" ? comp.firstKeptEntryId : undefined;
         if (!fk)
             return { floorEntryId: null, floorSeq: 0 };
         const [seqRows] = await pool.query("SELECT seq FROM session_event WHERE session_id = ? AND entry_id = ?", [sessionId, fk]);
@@ -65,11 +67,10 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         const inMem = await super.getEntry(id);
         if (inMem)
             return inMem;
-        const [rows] = await this.pool.query("SELECT payload FROM session_event WHERE session_id = ? AND entry_id = ?", [this.sessionId, id]);
-        const p = rows[0]?.payload;
-        if (p == null)
+        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? AND entry_id = ?`, [this.sessionId, id]);
+        if (rows[0] === undefined)
             return undefined;
-        return (typeof p === "string" ? JSON.parse(p) : p);
+        return decodeSessionEventPayload(rows[0].payload, this.sessionId, id);
     }
     async appendEntry(entry, opts) {
         await this.persist(entry, opts);

package/dist/plugins/tidb-session-store.d.ts

@@ -155,8 +155,8 @@ export declare class TiDBSessionStore implements SessionStore {
      *
      * Resolves to `null` (NOT an empty async-iterable) when the session does not exist — checked via `session_meta`
      * EAGERLY here (before returning the iterable), exactly like {@link exportEntries}, so a missing session is distinct
-     * from a real-but-empty one (an empty stream). payload is parsed like {@link exportEntries} (string → JSON.parse,
-     * object passthrough). The check is eager (the method is async) because a generator body is lazy — it can't decide
+     * from a real-but-empty one (an empty stream). payload is decoded like {@link exportEntries}
+     * (按文本投影 + `decodeSessionEventPayload` 恰好解一次码,坏体当场拒). The check is eager (the method is async) because a generator body is lazy — it can't decide
      * `null` vs. iterable on its own first pull.
      */
     exportEntriesStream(sessionId: string, opts?: {