@sema-agent/server 7.93.7 → 7.94.0

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

@@ -2,6 +2,7 @@ import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE, Mail
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { escapeLike } from "./sql-escape.js";
+import { decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, readStringArrayColumn } from "./sql-json-column.js";
 export const MAILBOX_TABLE = "mailbox";
 export const MAILBOX_MSG_TABLE = "mailbox_message";
 export const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";
@@ -46,19 +47,13 @@ function encodeHopChain(hopChain) {
     }
     return text;
 }
-function decodeHopChain(raw) {
-    if (raw === null || raw === undefined)
-        return undefined;
-    let parsed;
+function decodeHopChain(raw, seq) {
     try {
-        parsed = JSON.parse(bufToStr(raw));
+        return decodeNullableJsonColumn(raw, readStringArrayColumn, `${MAILBOX_MSG_TABLE}.hop_chain for seq ${String(seq)}`);
     }
-    catch {
-        return undefined;
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`MailboxStore: ${m} — refusing the lease rather than let a message skip peer admission (an absent chain makes core's judgePeerAdmission not run at all)`));
     }
-    if (!Array.isArray(parsed) || parsed.some((x) => typeof x !== "string"))
-        return undefined;
-    return parsed;
 }
 const PEER_META_MAX_BYTES = 60_000;
 function encodePeerMeta(raw) {
@@ -71,52 +66,59 @@ function encodePeerMeta(raw) {
     }
     return text;
 }
-function decodePeerMeta(raw) {
-    if (raw === null || raw === undefined)
-        return undefined;
-    const text = bufToStr(raw);
-    let parsed;
+function decodePeerMeta(raw, seq) {
     try {
-        parsed = JSON.parse(text);
+        return decodeNullableJsonColumn(raw, readPeerMetaColumn, `${MAILBOX_MSG_TABLE}.peer_meta for seq ${String(seq)}`);
     }
-    catch (err) {
-        throw new MailboxStoreError(MAILBOX_INVALID_PEER_META_CODE, `MailboxStore: stored peer_meta is not JSON (refusing the lease — a corrupt typed record must not be read as "no metadata"): ${err instanceof Error ? err.message : String(err)}`);
+    catch (e) {
+        if (e instanceof MailboxStoreError)
+            throw e;
+        throw foldJsonColumn(e, (m) => new MailboxStoreError(MAILBOX_INVALID_PEER_META_CODE, `MailboxStore: ${m} — refusing the lease rather than read a corrupt typed record as "no metadata"`));
     }
+}
+const readPeerMetaColumn = (body) => {
     try {
-        return readMailboxPeerMeta(parsed);
+        const meta = readMailboxPeerMeta(body);
+        return meta === undefined ? { problem: "the JSON literal `null` — absence is SQL NULL on this column, so a written `null` can only be a hand edit" } : { value: meta };
     }
     catch (err) {
         if (err instanceof MailboxStoreError)
             throw err;
-        throw new MailboxStoreError(MAILBOX_INVALID_PEER_META_CODE, `MailboxStore: stored peer_meta failed validation (refusing the lease): ${err instanceof Error ? err.message : String(err)}`);
+        return { problem: err instanceof Error ? err.message : String(err) };
     }
-}
+};
 function rowsToMessages(rows, scope, handle, logger) {
     const out = [];
     for (const r of rows) {
-        try {
-            out.push(rowToMessage(r));
-        }
-        catch (err) {
-            if (err instanceof MailboxStoreError)
-                logger?.warn("mailbox_peer_meta_corrupt", { scope, handle, seq: Number(r.seq), code: err.code, note: "claimLease refused for the whole box (fail-closed); repair or NULL the peer_meta column of this row" });
-            throw err;
-        }
+        const read = (column, decode) => {
+            try {
+                return decode();
+            }
+            catch (err) {
+                logger?.warn("mailbox_message_column_corrupt", {
+                    scope,
+                    handle,
+                    seq: Number(r.seq),
+                    column,
+                    ...(err instanceof MailboxStoreError ? { code: err.code } : {}),
+                    note: "claimLease refused for the whole box (fail-closed); repair or NULL that column of this row",
+                });
+                throw err;
+            }
+        };
+        const hopChain = read("hop_chain", () => decodeHopChain(r.hop_chain, r.seq));
+        const peerMeta = read("peer_meta", () => decodePeerMeta(r.peer_meta, r.seq));
+        out.push({
+            seq: Number(r.seq),
+            ...(r.from_id !== null && r.from_id !== undefined ? { from: bufToStr(r.from_id) } : {}),
+            content: String(r.content),
+            sentAt: Number(r.sent_at_ms),
+            ...(hopChain !== undefined ? { hopChain } : {}),
+            ...(peerMeta !== undefined ? { peerMeta } : {}),
+        });
     }
     return out;
 }
-function rowToMessage(r) {
-    const hopChain = decodeHopChain(r.hop_chain);
-    const peerMeta = decodePeerMeta(r.peer_meta);
-    return {
-        seq: Number(r.seq),
-        ...(r.from_id !== null && r.from_id !== undefined ? { from: bufToStr(r.from_id) } : {}),
-        content: String(r.content),
-        sentAt: Number(r.sent_at_ms),
-        ...(hopChain !== undefined ? { hopChain } : {}),
-        ...(peerMeta !== undefined ? { peerMeta } : {}),
-    };
-}
 export async function ensureTiDBMailboxSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
     scope_key VARBINARY(190) NOT NULL,
@@ -250,7 +252,7 @@ export class TiDBMailboxStore {
                 bufToStr(box.lease_owner) !== owner) {
                 return null;
             }
-            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain, peer_meta FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
+            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("tidb", "hop_chain")}, ${jsonColumnText("tidb", "peer_meta")} FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);
@@ -397,7 +399,7 @@ export class PgMailboxStore {
             const box = boxes[0];
             if (box.lease_owner !== null && Number(box.lease_expires_at_ms) > now && String(box.lease_owner) !== owner)
                 return null;
-            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain, peer_meta FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
+            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("pg", "hop_chain")}, ${jsonColumnText("pg", "peer_meta")} FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);

package/dist/plugins/memory-embedder-fingerprint.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { PG_MEMORY_ENGINE_TABLES } from "./memory-engine-pg.js";
+import { createZodColumnReader, decodeJsonColumn, jsonColumnText, SqlJsonColumnError } from "./sql-json-column.js";
 export const PG_MEMORY_ENGINE_META_TABLE = "agent_memory_engine_meta";
 export const EMBEDDER_IDENTITY_META_KEY = "embedder_identity";
 export const CAS_MAX_ROUNDS = 3;
@@ -13,28 +14,23 @@ export async function ensurePgMemoryEmbedderMetaSchema(query) {
     meta_value jsonb NOT NULL
   )`);
 }
+const readEmbedderIdentityColumn = createZodColumnReader(EmbedderIdentitySchema);
 function parseStoredText(text) {
-    let candidate;
     try {
-        candidate = JSON.parse(text);
+        return { kind: "ok", value: decodeJsonColumn(text, readEmbedderIdentityColumn, `${PG_MEMORY_ENGINE_META_TABLE}.meta_value for key ${EMBEDDER_IDENTITY_META_KEY}`) };
     }
     catch (err) {
-        return { kind: "unreadable", raw: `${text.slice(0, 160)} [JSON.parse: ${String(err).slice(0, 80)}]` };
+        if (!(err instanceof SqlJsonColumnError))
+            throw err;
+        return { kind: "unreadable", raw: `${text.slice(0, 160)} [${err.problem}: ${err.message.slice(0, 120)}]` };
     }
-    if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) {
-        return { kind: "unreadable", raw: `${text.slice(0, 160)} [not a JSON object]` };
-    }
-    const parsed = EmbedderIdentitySchema.safeParse(candidate);
-    if (!parsed.success)
-        return { kind: "unreadable", raw: text.slice(0, 200) };
-    return { kind: "ok", value: parsed.data };
 }
 async function readStored(query) {
-    const r = await query(`SELECT meta_value::text AS meta_value_text FROM ${PG_MEMORY_ENGINE_META_TABLE} WHERE meta_key = $1`, [EMBEDDER_IDENTITY_META_KEY]);
+    const r = await query(`SELECT ${jsonColumnText("pg", "meta_value")} FROM ${PG_MEMORY_ENGINE_META_TABLE} WHERE meta_key = $1`, [EMBEDDER_IDENTITY_META_KEY]);
     const row = r.rows[0];
     if (row === undefined)
         return { kind: "absent" };
-    const text = row.meta_value_text;
+    const text = row.meta_value;
     if (typeof text !== "string")
         return { kind: "unreadable", raw: `[meta_value::text did not return text: ${typeof text}]` };
     return parseStoredText(text);

package/dist/plugins/memory-engine-pg.js

@@ -1,5 +1,7 @@
 import { cosineDistance, jaccardDistance, termSet } from "@sema-agent/core";
-import { isUniqueViolation } from "./memory-engine-vector-util.js";
+import { isUniqueViolation, readEmbeddingColumn, readFrontmatterColumn } from "./memory-engine-vector-util.js";
+import { decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText } from "./sql-json-column.js";
+import { recordFailOpen } from "../observability/fail-open.js";
 import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgSafeJsonStringify, pgHasUnstorable } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
@@ -44,8 +46,24 @@ function vectorLiteral(v) {
 function inPlaceholders(first, count) {
     return Array.from({ length: count }, (_, i) => `$${first + i}`).join(", ");
 }
-function fromJson(v) {
-    return (typeof v === "string" ? JSON.parse(v) : v);
+function readFrontmatter(cell, id) {
+    try {
+        return decodeJsonColumn(cell, readFrontmatterColumn, `${PG_MEMORY_ENGINE_TABLES.entry}.frontmatter for entry ${String(id)}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`memory-engine: ${m} — refusing rather than serve a note whose frontmatter (the origin/exposure law carrier) nobody can read`));
+    }
+}
+function readEmbedding(cell, id) {
+    try {
+        return decodeNullableJsonColumn(cell, readEmbeddingColumn, `${PG_MEMORY_ENGINE_TABLES.entry}.embedding for entry ${String(id)}`);
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        recordFailOpen("server.sql-json.memory-engine.embedding");
+        return undefined;
+    }
 }
 export class PgMemoryEngineBackend {
     query;
@@ -78,7 +96,7 @@ export class PgMemoryEngineBackend {
         return this.pgvectorSql ? vectorLiteral(v) : pgSafeJsonStringify(v);
     }
     headerFromRow(r) {
-        const fm = fromJson(r.frontmatter);
+        const fm = readFrontmatter(r.frontmatter, r.id);
         return {
             id: r.id,
             slug: r.slug,
@@ -98,7 +116,7 @@ export class PgMemoryEngineBackend {
             id: r.id,
             slug: r.slug,
             scope: r.scope,
-            frontmatter: fromJson(r.frontmatter),
+            frontmatter: readFrontmatter(r.frontmatter, r.id),
             body: r.body,
             rev: r.rev,
         };
@@ -107,14 +125,14 @@ export class PgMemoryEngineBackend {
         const uniq = [...new Set(scopes)];
         if (uniq.length === 0)
             return [];
-        const res = await this.query(`SELECT id, scope, slug, frontmatter, rev, mtime_ms, size_bytes FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(1, uniq.length)}) ORDER BY id`, uniq);
+        const res = await this.query(`SELECT id, scope, slug, ${jsonColumnText("pg", "frontmatter")}, rev, mtime_ms, size_bytes FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(1, uniq.length)}) ORDER BY id`, uniq);
         return res.rows.map((r) => this.headerFromRow(r));
     }
     async getByIds(ids) {
         const uniq = [...new Set(ids)];
         if (uniq.length === 0)
             return [];
-        const res = await this.query(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id IN (${inPlaceholders(1, uniq.length)}) ORDER BY id`, uniq);
+        const res = await this.query(`SELECT id, scope, slug, ${jsonColumnText("pg", "frontmatter")}, body, rev, mtime_ms, size_bytes FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id IN (${inPlaceholders(1, uniq.length)}) ORDER BY id`, uniq);
         return res.rows.map((r) => this.entryFromRow(r));
     }
     async search(query, scopes, opts) {
@@ -132,7 +150,7 @@ export class PgMemoryEngineBackend {
             if (Array.isArray(qv) && qv.length === this.embedder.dimensions) {
                 const vecParam = scopes.length + 1;
                 const bandExpr = bands ? `(CASE WHEN ${originMarkedSqlPredicate("frontmatter")} THEN 1 ELSE 0 END) ASC, ` : "";
-                const res = await this.query(`SELECT id, scope, slug, frontmatter, rev, mtime_ms, size_bytes, embedding <=> $${vecParam}::vector AS dist
+                const res = await this.query(`SELECT id, scope, slug, ${jsonColumnText("pg", "frontmatter")}, rev, mtime_ms, size_bytes, embedding <=> $${vecParam}::vector AS dist
              FROM ${PG_MEMORY_ENGINE_TABLES.entry}
             WHERE scope IN (${inPlaceholders(1, scopes.length)}) AND embedding IS NOT NULL
             ORDER BY ${bandExpr}embedding <=> $${vecParam}::vector ASC, id ASC
@@ -141,16 +159,16 @@ export class PgMemoryEngineBackend {
                 return hits.sort(contractOrder);
             }
         }
-        const res = await this.query(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes, embedding FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(1, scopes.length)})`, [...scopes]);
+        const res = await this.query(`SELECT id, scope, slug, ${jsonColumnText("pg", "frontmatter")}, body, rev, mtime_ms, size_bytes, ${jsonColumnText("pg", "embedding")} FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(1, scopes.length)})`, [...scopes]);
         const queryVec = this.embedder ? await this.embedder.embed(query).catch(() => null) : null;
         const dims = this.embedder?.dimensions;
         const scored = [];
         for (const raw of res.rows) {
             const r = raw;
-            const fm = fromJson(r.frontmatter);
+            const fm = readFrontmatter(r.frontmatter, r.id);
             if (queryVec && Array.isArray(queryVec) && queryVec.length === dims && r.embedding != null) {
-                const stored = fromJson(r.embedding);
-                if (Array.isArray(stored) && stored.length === dims) {
+                const stored = readEmbedding(r.embedding, r.id);
+                if (stored !== undefined && stored.length === dims) {
                     scored.push({ ...this.headerFromRow(r), score: cosineDistance(queryVec, stored) });
                     continue;
                 }
@@ -233,10 +251,10 @@ export class PgMemoryEngineBackend {
                 return;
             }
             const entry = rawEntry;
-            const prior = await this.query(`SELECT scope, slug, rev, frontmatter FROM ${T} WHERE id = $1`, [entry.id]);
+            const prior = await this.query(`SELECT scope, slug, rev, ${jsonColumnText("pg", "frontmatter")} FROM ${T} WHERE id = $1`, [entry.id]);
             const priorRow = prior.rows.length > 0 ? prior.rows[0] : undefined;
             {
-                const committedBaseFm = rememberBatchCommitted(originBaseline, entry.id, priorRow !== undefined ? fromJson(priorRow.frontmatter) : undefined);
+                const committedBaseFm = rememberBatchCommitted(originBaseline, entry.id, priorRow !== undefined ? readFrontmatter(priorRow.frontmatter, entry.id) : undefined);
                 const refusal = originWhitewashRefusal("add", committedBaseFm, entry.frontmatter);
                 if (refusal !== undefined) {
                     report.conflicts.push({ op: "add", id: entry.id, reason: refusal });
@@ -304,7 +322,7 @@ export class PgMemoryEngineBackend {
                 slug = `${entry.slug}-${n}`;
             }
         }
-        const cur = await this.query(`SELECT slug, rev, scope, frontmatter FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1`, [patch.id]);
+        const cur = await this.query(`SELECT slug, rev, scope, ${jsonColumnText("pg", "frontmatter")} FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1`, [patch.id]);
         if (cur.rows.length === 0) {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
             return;
@@ -312,7 +330,7 @@ export class PgMemoryEngineBackend {
         const currentRev = String(cur.rows[0].rev);
         const currentSlug = String(cur.rows[0].slug);
         const currentScope = String(cur.rows[0].scope);
-        const committedFm = fromJson(cur.rows[0].frontmatter);
+        const committedFm = readFrontmatter(cur.rows[0].frontmatter, patch.id);
         const committedBaseFm = rememberBatchCommitted(originBaseline, patch.id, committedFm);
         if (patch.op === "update" && patch.entry !== undefined) {
             if (committedFm.provenance?.kind === "repo_file") {

package/dist/plugins/memory-engine-tidb.js

@@ -1,4 +1,6 @@
 import { jaccardDistance, termSet } from "@sema-agent/core";
+import { readFrontmatterColumn } from "./memory-engine-vector-util.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
 import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgHasUnstorable } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
@@ -41,8 +43,13 @@ function isPrimaryKeyDup(err) {
 function inPlaceholders(count) {
     return Array.from({ length: count }, () => "?").join(", ");
 }
-function fromJson(v) {
-    return (typeof v === "string" ? JSON.parse(v) : v);
+function readFrontmatter(cell, id) {
+    try {
+        return decodeJsonColumn(cell, readFrontmatterColumn, `${TIDB_MEMORY_ENGINE_TABLES.entry}.frontmatter for entry ${String(id)}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`memory-engine: ${m} — refusing rather than serve a note whose frontmatter (the origin/exposure law carrier) nobody can read`));
+    }
 }
 export class TiDBMemoryEngineBackend {
     pool;
@@ -72,7 +79,7 @@ export class TiDBMemoryEngineBackend {
         return `${fm.name ?? slug} ${fm.description ?? ""} ${body}`;
     }
     headerFromRow(r) {
-        const fm = fromJson(r.frontmatter);
+        const fm = readFrontmatter(r.frontmatter, r.id);
         return {
             id: r.id,
             slug: r.slug,
@@ -92,7 +99,7 @@ export class TiDBMemoryEngineBackend {
             id: r.id,
             slug: r.slug,
             scope: r.scope,
-            frontmatter: fromJson(r.frontmatter),
+            frontmatter: readFrontmatter(r.frontmatter, r.id),
             body: r.body,
             rev: r.rev,
         };
@@ -101,14 +108,14 @@ export class TiDBMemoryEngineBackend {
         const uniq = [...new Set(scopes)];
         if (uniq.length === 0)
             return [];
-        const rows = await this.selectRows(`SELECT id, scope, slug, frontmatter, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
+        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("tidb", "frontmatter")}, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
         return rows.map((r) => this.headerFromRow(r));
     }
     async getByIds(ids) {
         const uniq = [...new Set(ids)];
         if (uniq.length === 0)
             return [];
-        const rows = await this.selectRows(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
+        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("tidb", "frontmatter")}, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
         return rows.map((r) => this.entryFromRow(r));
     }
     async search(query, scopes, opts) {
@@ -121,11 +128,11 @@ export class TiDBMemoryEngineBackend {
         if (q.size === 0)
             return [];
         const uniq = [...new Set(scopes)];
-        const rows = await this.selectRows(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)})`, uniq);
+        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("tidb", "frontmatter")}, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)})`, uniq);
         const scored = [];
         for (const raw of rows) {
             const r = raw;
-            const fm = fromJson(r.frontmatter);
+            const fm = readFrontmatter(r.frontmatter, r.id);
             const d = jaccardDistance(q, this.haystackOf(r.slug, fm, r.body));
             if (d === null)
                 continue;
@@ -203,11 +210,11 @@ export class TiDBMemoryEngineBackend {
                 report.conflicts.push({ op: "add", id: entry.id, reason: "unstorable_bytes (utf8mb4 cannot store NUL/lone surrogates without mangling; strip them at the source — the store never rewrites content)" });
                 return;
             }
-            const prior = await this.selectRows(`SELECT scope, slug, rev, frontmatter FROM ${T} WHERE id = ?`, [entry.id]);
+            const prior = await this.selectRows(`SELECT scope, slug, rev, ${jsonColumnText("tidb", "frontmatter")} FROM ${T} WHERE id = ?`, [entry.id]);
             const priorRow = prior.length > 0 ? prior[0] : undefined;
             let existsById = priorRow !== undefined;
             {
-                const committedBaseFm = rememberBatchCommitted(originBaseline, entry.id, priorRow !== undefined ? fromJson(priorRow.frontmatter) : undefined);
+                const committedBaseFm = rememberBatchCommitted(originBaseline, entry.id, priorRow !== undefined ? readFrontmatter(priorRow.frontmatter, entry.id) : undefined);
                 const refusal = originWhitewashRefusal("add", committedBaseFm, entry.frontmatter);
                 if (refusal !== undefined) {
                     report.conflicts.push({ op: "add", id: entry.id, reason: refusal });
@@ -288,7 +295,7 @@ export class TiDBMemoryEngineBackend {
                 slug = `${entry.slug}-${n}`;
             }
         }
-        const cur = await this.selectRows(`SELECT slug, rev, scope, frontmatter FROM ${T} WHERE id = ?`, [patch.id]);
+        const cur = await this.selectRows(`SELECT slug, rev, scope, ${jsonColumnText("tidb", "frontmatter")} FROM ${T} WHERE id = ?`, [patch.id]);
         if (cur.length === 0) {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
             return;
@@ -296,7 +303,7 @@ export class TiDBMemoryEngineBackend {
         const currentRev = String(cur[0].rev);
         const currentSlug = String(cur[0].slug);
         const currentScope = String(cur[0].scope);
-        const committedFm = fromJson(cur[0].frontmatter);
+        const committedFm = readFrontmatter(cur[0].frontmatter, patch.id);
         const committedBaseFm = rememberBatchCommitted(originBaseline, patch.id, committedFm);
         if (patch.op === "update" && patch.entry !== undefined) {
             if (committedFm.provenance?.kind === "repo_file") {

package/dist/plugins/memory-engine-vector-util.d.ts

@@ -1,2 +1,28 @@
+/** memory-engine 方言实现共用的纯工具函数。三个距离/词集函数(termSet/jaccardDistance/cosineDistance)
+ *  在 core(1.268.0 起公开导出,单一语义源)——消费者直引 core([ref] 兼容面全清:此处转口已删)。
+ *  `isUniqueViolation` 重新内联:它当年随 core 的 pg **示例适配器**导出面走,core 1.424 按 clay 包卫生令
+ *  把整个 examples 面退出 npm 包([ref] BREAKING)⇒ re-export 断源。原为逐字抄自 core 1.423
+ *  `examples/adapters/pg-adapter.js`(纯谓词,无 byte-equal 契约约束);[ref] P1-① 后**码面判据**
+ *  改走属主 `sql-errors.ts`,只留 message 补充臂(理由在函数体内)。 */
+import type { MemoryEntryFrontmatter } from "@sema-agent/core";
+import { type JsonColumnReader } from "./sql-json-column.js";
 export declare function isUniqueViolation(err: unknown): boolean;
+/**
+ * `agent_memory_engine_entry.frontmatter` 的**形读者**。
+ *
+ * 🔴 判据只到「一只 JSON 对象」为止:键表属主在 core(`MemoryEntryFrontmatter`),而 core 没有导出
+ * 验证器 —— 在这里手写一份等价 zod 就是设计稿明令禁止的第二份键集。这一条最小判据已经把坏体四形全关在
+ * 门外,而此前这里是**零判据**(裸 `JSON.parse` + `as MemoryEntryFrontmatter`)。
+ *
+ * 🔴 失败方向 = **拒**,而且这一列不是普通载荷:`frontmatter` 是 **origin/exposure 不可变律**的载体
+ * (`committedOriginOf` / `exposureBandOf` / `distilledCarriage` 全读它)。一行读不出形的 frontmatter 被
+ * 当成 `{}` 端出去 = 那条笔记的 external-origin 标记与曝光带**静默消失** —— 洗白检查(`originWhitewashRefusal`)
+ * 拿到的「已提交基线」于是是空的,一次真的洗白会被放过。
+ */
+export declare const readFrontmatterColumn: JsonColumnReader<MemoryEntryFrontmatter>;
+/**
+ * `agent_memory_engine_entry.embedding` 的**形读者** = 本店既有的那一条判据(`Array.isArray`)。
+ * 维数判据仍在调用点(它要跟 embedder 的 `dimensions` 比,那是运行期事实,不是列的形)。
+ */
+export declare const readEmbeddingColumn: JsonColumnReader<unknown[]>;
 //# sourceMappingURL=memory-engine-vector-util.d.ts.map

package/dist/plugins/memory-engine-vector-util.js

@@ -1,4 +1,5 @@
 import { isPgUniqueViolation } from "./sql-errors.js";
+import { createObjectColumnReader, readJsonArrayColumn } from "./sql-json-column.js";
 export function isUniqueViolation(err) {
     if (isPgUniqueViolation(err))
         return true;
@@ -6,4 +7,6 @@ export function isUniqueViolation(err) {
         return false;
     return /duplicate key|unique constraint|already exists/i.test(String(err.message ?? ""));
 }
+export const readFrontmatterColumn = createObjectColumnReader();
+export const readEmbeddingColumn = readJsonArrayColumn;
 //# sourceMappingURL=memory-engine-vector-util.js.map

package/dist/plugins/memory-sync-store-pg.d.ts

@@ -50,6 +50,12 @@ export interface MemorySyncStore {
 export declare const MEMORY_SYNC_INDEXES: readonly IndexSpec[];
 /** Idempotent DDL for the sync plane (PG dialect). Call once at startup. */
 export declare function ensurePgMemorySyncSchema(query: PgQueryFn): Promise<void>;
+/**
+ * 本店三只 JSON 承载列的**折码点**(唯一)—— 本店没有枚举式 corrupt 码,既有的「读不出来」口径就是
+ * 响亮抛(`claimLeaseMs` 守卫 / dup id 一律 fail-loud)⇒ 折成响亮裸 `Error`,点名 `<表>.<列>` + 行标识
+ * (S-550 车①② 裁定,沿用;不新铸码)。两个孪生共用本函数(MySQL 腿 import 它 —— 一条折码规则一个写者)。
+ */
+export declare function refusingMemorySyncRow<T>(read: () => T): T;
 /** Options for {@link PgMemorySyncStore}. */
 export interface PgMemorySyncStoreOptions {
     /** How long a `claimDue` lease holds a row invisible before a crashed worker's claim self-heals.

package/dist/plugins/memory-sync-store-pg.js

@@ -1,6 +1,7 @@
 import { ensureIndexes } from "./ensure-index.js";
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth } from "./memory-key-guards.js";
+import { decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, readNonNullJsonValueColumn, readOpaqueJsonValueColumn, readStringRecordColumn, } from "./sql-json-column.js";
 export const PG_MEMORY_SYNC_TABLES = {
     syncCursor: "agent_memory_engine_sync_cursor",
     pushQueue: "agent_memory_engine_push_queue",
@@ -28,10 +29,13 @@ export async function ensurePgMemorySyncSchema(query) {
   )`);
     await ensureIndexes(query, "pg", MEMORY_SYNC_INDEXES);
 }
-function fromJsonb(v) {
-    if (typeof v === "string")
-        return JSON.parse(v);
-    return v;
+export function refusingMemorySyncRow(read) {
+    try {
+        return read();
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => new Error(`memory-sync store: ${m} — refusing rather than serve a sync row nobody can read`));
+    }
 }
 function toMs(v) {
     return typeof v === "number" ? v : Number(v);
@@ -48,14 +52,14 @@ export class PgMemorySyncStore {
         this.claimLeaseMs = lease;
     }
     async getCursor(scope, peer) {
-        const res = await this.query(`SELECT base_revs, updated_at_ms FROM ${PG_MEMORY_SYNC_TABLES.syncCursor} WHERE scope = $1 AND peer = $2`, [scope, peer]);
+        const res = await this.query(`SELECT ${jsonColumnText("pg", "base_revs")}, updated_at_ms FROM ${PG_MEMORY_SYNC_TABLES.syncCursor} WHERE scope = $1 AND peer = $2`, [scope, peer]);
         const row = res.rows[0];
         if (!row)
             return undefined;
         return {
             scope,
             peer,
-            baseRevs: fromJsonb(row.base_revs),
+            baseRevs: refusingMemorySyncRow(() => decodeJsonColumn(row.base_revs, readStringRecordColumn, `${PG_MEMORY_SYNC_TABLES.syncCursor}.base_revs for scope ${scope} peer ${peer}`)),
             updatedAtMs: toMs(row.updated_at_ms),
         };
     }
@@ -83,12 +87,12 @@ export class PgMemorySyncStore {
        )
        UPDATE ${PG_MEMORY_SYNC_TABLES.pushQueue} q SET next_attempt_at_ms = $3
        FROM due WHERE q.id = due.id
-       RETURNING q.id, q.scope, q.entry_id, q.payload, q.attempts, q.last_error`, [nowMs, limit, leasedUntilMs]);
+       RETURNING q.id, q.scope, q.entry_id, ${jsonColumnText("pg", "payload")}, q.attempts, q.last_error`, [nowMs, limit, leasedUntilMs]);
         return res.rows.map((r) => ({
             id: String(r.id),
             scope: String(r.scope),
             entryId: String(r.entry_id),
-            payload: fromJsonb(r.payload),
+            payload: refusingMemorySyncRow(() => decodeJsonColumn(r.payload, readOpaqueJsonValueColumn, `${PG_MEMORY_SYNC_TABLES.pushQueue}.payload for item ${String(r.id)}`)),
             attempts: toMs(r.attempts),
             lastError: r.last_error == null ? null : String(r.last_error),
             leasedUntilMs,
@@ -138,7 +142,7 @@ export class PgMemoryHistoryStore {
        ON CONFLICT (id, rev) DO NOTHING`, params);
     }
     async historyOf(id) {
-        const res = await this.query(`SELECT id, rev, prev_rev, op, scope, snapshot, written_at_ms
+        const res = await this.query(`SELECT id, rev, prev_rev, op, scope, ${jsonColumnText("pg", "snapshot")}, written_at_ms
        FROM ${PG_MEMORY_SYNC_TABLES.history}
        WHERE id = $1
        ORDER BY written_at_ms ASC, rev ASC`, [id]);
@@ -156,7 +160,7 @@ export function historyRowFrom(r) {
         prevRev: r.prev_rev == null ? null : String(r.prev_rev),
         op: String(r.op),
         scope: String(r.scope),
-        snapshot: r.snapshot == null ? null : fromJsonb(r.snapshot),
+        snapshot: refusingMemorySyncRow(() => decodeNullableJsonColumn(r.snapshot, readNonNullJsonValueColumn, `${PG_MEMORY_SYNC_TABLES.history}.snapshot for entry ${String(r.id)} rev ${String(r.rev)}`)) ?? null,
         writtenAtMs: toMs(r.written_at_ms),
     };
 }

package/dist/plugins/memory-sync-store-tidb.js

@@ -1,4 +1,5 @@
-import { historyRowFrom } from "./memory-sync-store-pg.js";
+import { historyRowFrom, refusingMemorySyncRow } from "./memory-sync-store-pg.js";
+import { decodeJsonColumn, jsonColumnText, readOpaqueJsonValueColumn, readStringRecordColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { MEMORY_SYNC_INDEXES, MEMORY_HISTORY_INDEXES, PG_MEMORY_SYNC_TABLES } from "./memory-sync-store-pg.js";
 import { assertMemoryScopeWidth } from "./memory-key-guards.js";
@@ -30,11 +31,6 @@ export async function ensureTiDBMemorySyncSchema(pool) {
   ) COLLATE utf8mb4_bin`);
     await ensureIndexes((text, params) => pool.query(text, params), "mysql", MEMORY_SYNC_INDEXES);
 }
-function fromJson(v) {
-    if (typeof v === "string")
-        return JSON.parse(v);
-    return v;
-}
 function toMs(v) {
     return typeof v === "number" ? v : Number(v);
 }
@@ -50,14 +46,14 @@ export class TiDBMemorySyncStore {
         this.claimLeaseMs = lease;
     }
     async getCursor(scope, peer) {
-        const [rows] = await this.pool.query(`SELECT base_revs, updated_at_ms FROM ${TIDB_MEMORY_SYNC_TABLES.syncCursor} WHERE scope = ? AND peer = ?`, [scope, peer]);
+        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("tidb", "base_revs")}, updated_at_ms FROM ${TIDB_MEMORY_SYNC_TABLES.syncCursor} WHERE scope = ? AND peer = ?`, [scope, peer]);
         const row = rows[0];
         if (!row)
             return undefined;
         return {
             scope,
             peer,
-            baseRevs: fromJson(row.base_revs),
+            baseRevs: refusingMemorySyncRow(() => decodeJsonColumn(row.base_revs, readStringRecordColumn, `${TIDB_MEMORY_SYNC_TABLES.syncCursor}.base_revs for scope ${scope} peer ${peer}`)),
             updatedAtMs: toMs(row.updated_at_ms),
         };
     }
@@ -76,7 +72,7 @@ export class TiDBMemorySyncStore {
         if (limit <= 0)
             return [];
         const leasedUntilMs = nowMs + this.claimLeaseMs;
-        const [candidates] = await this.pool.query(`SELECT id, scope, entry_id, payload, attempts, next_attempt_at_ms, last_error
+        const [candidates] = await this.pool.query(`SELECT id, scope, entry_id, ${jsonColumnText("tidb", "payload")}, attempts, next_attempt_at_ms, last_error
        FROM ${TIDB_MEMORY_SYNC_TABLES.pushQueue}
        WHERE next_attempt_at_ms <= ?
        ORDER BY next_attempt_at_ms, id
@@ -92,7 +88,7 @@ export class TiDBMemorySyncStore {
                 id: row.id,
                 scope: row.scope,
                 entryId: row.entry_id,
-                payload: fromJson(row.payload),
+                payload: refusingMemorySyncRow(() => decodeJsonColumn(row.payload, readOpaqueJsonValueColumn, `${TIDB_MEMORY_SYNC_TABLES.pushQueue}.payload for item ${row.id}`)),
                 attempts: toMs(row.attempts),
                 lastError: row.last_error == null ? null : String(row.last_error),
                 leasedUntilMs,
@@ -141,7 +137,7 @@ export class TiDBMemoryHistoryStore {
        ON DUPLICATE KEY UPDATE id = id`, params);
     }
     async historyOf(id) {
-        const [rows] = await this.pool.query(`SELECT id, rev, prev_rev, op, scope, snapshot, written_at_ms
+        const [rows] = await this.pool.query(`SELECT id, rev, prev_rev, op, scope, ${jsonColumnText("tidb", "snapshot")}, written_at_ms
        FROM ${TIDB_MEMORY_SYNC_TABLES.history}
        WHERE id = ?
        ORDER BY written_at_ms ASC, rev ASC`, [id]);