@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/pg-cost-quota.js

@@ -1,9 +1,7 @@
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
-/** The counter's table binding for the cumulative cost quota (mirror of the TiDB twin's binding). */
 const COST_QUOTA_TABLE = { table: "cost_quota", keyCol: "scope_key", valCol: "micro_usd" };
 export class PgCostQuota {
     counter;
-    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
     limitMicroUsd;
     refreshRequested = false;
     refreshIntervalMs;
@@ -36,7 +34,6 @@ export class PgCostQuota {
             return;
         this.counter.addLocal(scopeKey, micro);
     }
-    // write-behind lifecycle (delegated; exposed for the reaper/tests)
     flush() {
         return this.counter.flush();
     }
@@ -57,9 +54,6 @@ export class PgCostQuota {
         this.counter.stop();
     }
 }
-/** PG DDL for the `cost_quota` table (translated from tidb-pool.ts SCHEMA_STATEMENTS: BIGINT same,
- *  DATETIME(3)→TIMESTAMPTZ(3), inline `KEY idx_window`→separate CREATE INDEX). DISJOINT from other stores'
- *  tables, so a self-contained ensureSchema is safe (the central pg-pool aggregation is done separately). */
 export const PG_COST_QUOTA_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS cost_quota (
      scope_key     VARCHAR(190) COLLATE "C" NOT NULL,
@@ -70,7 +64,6 @@ export const PG_COST_QUOTA_SCHEMA = [
    )`,
     `CREATE INDEX IF NOT EXISTS idx_cost_quota_window ON cost_quota (window_bucket)`,
 ];
-/** Idempotent schema apply for the cost_quota table (the PG twin of tidb-pool.ts ensureSchema). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_COST_QUOTA_SCHEMA)
         await pool.query(stmt);

package/dist/plugins/pg-pool.js

@@ -1,32 +1,4 @@
-/**
- * PostgreSQL pool + central schema — the PG sibling of tidb-pool.ts, for the second run-store backend
- * (clay 2026-06-21). Schema ownership is CENTRAL (one ensurePgSchema, like tidb-pool's SCHEMA_STATEMENTS) — PG
- * stores assume the tables exist and NEVER create their own (a per-store `CREATE TABLE IF NOT EXISTS` is
- * first-writer-wins, so a trimmed table would shadow the full one and drop columns).
- *
- * Dialect deltas vs the MySQL DDL in tidb-pool.ts: JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), TINYINT(1)→SMALLINT,
- * inline `KEY …`→separate `CREATE INDEX`. checkpoint timestamps stay epoch-ms BIGINT (core's Checkpoint uses ms),
- * matching the TiDB schema byte-for-byte semantically. Only the tables PG backends implement so far are listed
- * (run-store + checkpoint); the remaining tidb-* tables are added as their PG stores land (tracked).
- *
- * ─────────────────────────────── SCHEMA POLICY (clay 裁 2026-07-26) ───────────────────────────────
- * THIS CODE IS THE SINGLE SOURCE OF TRUTH for the PG schema. The stack is not yet in production and runs
- * against a single local operator's database, so a schema change is DROP-AND-RECREATE (drop the database,
- * boot, `ensurePgSchema` rebuilds it) — NOT an in-place migration.
- *
- * Consequence, and it is a hard rule: **do NOT add new `ALTER TABLE` seams here.** Every column / default /
- * constraint change is folded into its own `CREATE TABLE`, and this array stays pure `CREATE TABLE` +
- * `CREATE INDEX`. The historical additive-ALTER seams were folded in on 2026-07-26 (they had all decayed
- * into permanent no-ops — the CREATEs already carried the columns).
- *
- * Because the seams are gone, the semantics they used to document now live as inline `--` comments ON THE
- * COLUMN inside the CREATE, not as TypeScript comments outside the template literal: the full-set SQL
- * baseline `docs/schema/baseline-pg.sql` is GENERATED from these statement strings, so only what is inside
- * the SQL survives the export. The baseline is a derived artifact — regenerate it, never hand-edit it.
- */
 import pg from "pg";
-// Each PG store owns its own (disjoint) tables' DDL via a standalone idempotent ensureSchema; the central apply
-// composes them so production wires ONE ensurePgSchema (the PG twin of tidb-pool's single ensureSchema).
 import { ensureSchema as ensureSessionSchema } from "./pg-session-storage.js";
 import { ensureSchema as ensureToolResultSchema } from "./tool-result-store-sql.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
@@ -87,7 +59,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_task_active_task ON task_active (task_id)`,
-    // Durable-checkpoint (core 1.67 / design/45) — the FULL table (matches tidb-pool.ts checkpoint + its migrations).
     `CREATE TABLE IF NOT EXISTS checkpoint (
      token        VARCHAR(120) COLLATE "C" NOT NULL,
      scope        VARCHAR(190) COLLATE "C" NOT NULL,
@@ -128,7 +99,6 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (session_id)
    )`,
-    // E18 resume-at anchor map (the PG twin of the TiDB resume_anchor table — eventId→entryId; see tidb-pool.ts).
     `CREATE TABLE IF NOT EXISTS resume_anchor (
      session_id VARCHAR(64) COLLATE "C"    NOT NULL,
      event_id   VARCHAR(64) COLLATE "C"    NOT NULL,
@@ -138,8 +108,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, event_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_resume_anchor_session ON resume_anchor (session_id)`,
-    // Per-session per-toolName approval exemption (the PG twin — see tidb-pool.ts /
-    // sema-internal server/docs/design/APPROVAL-SESSION-EXEMPTION.md).
     `CREATE TABLE IF NOT EXISTS approval_exemption (
      session_id VARCHAR(64) COLLATE "C"    NOT NULL,
      tool_name  VARCHAR(190) COLLATE "C"   NOT NULL,
@@ -147,9 +115,6 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (session_id, tool_name)
    )`,
-    // SendUserFile server-side ledger (the PG twin — scope↔object mapping for per-tenant list/revoke; the hashed
-    // key segment hides this from URLs. id = uuidv7 time-ordered PK = keyset cursor; see tidb-pool.ts /
-    // send-file-ledger.ts).
     `CREATE TABLE IF NOT EXISTS sendfile_link (
      id         VARCHAR(64) COLLATE "C"    NOT NULL,
      scope      VARCHAR(190) COLLATE "C"   NOT NULL,
@@ -165,9 +130,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_sendfile_link_scope ON sendfile_link (scope, id)`,
-    // E6 durable SessionPolicyStore (the PG twin of the TiDB session_policy table; policy_key = sha256(JSON.stringify(
-    // [sessionId, principal ?? null])) = a fixed 64-char hash PK; rules JSONB; CAS-versioned tighten-only — see
-    // tidb-pool.ts / session-policy-store-sql.ts).
     `CREATE TABLE IF NOT EXISTS session_policy (
      policy_key CHAR(64) COLLATE "C"       NOT NULL,
      session_id VARCHAR(64) COLLATE "C"    NOT NULL,
@@ -182,8 +144,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (policy_key)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_session_policy_session ON session_policy (session_id)`,
-    // E19 rewind-files (the PG twin of the TiDB snapshot_manifest/snapshot_blob; relPath→blob_hash manifest +
-    // content-addressed BYTEA blobs; core captureManifest/applyManifest do the walk/restore — see tidb-pool.ts).
     `CREATE TABLE IF NOT EXISTS snapshot_manifest (
      scope     VARCHAR(64) COLLATE "C"   NOT NULL,
      snap_key  VARCHAR(64) COLLATE "C"   NOT NULL,
@@ -205,10 +165,6 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at TIMESTAMPTZ(3) NOT NULL
    )`,
     `CREATE INDEX IF NOT EXISTS idx_snapshot_blob_created ON snapshot_blob (created_at)`,
-    // SVC-2 (core CORE-7) durable WorkflowJournalStore — the PG twin of the TiDB workflow_journal table (cross-replica
-    // resume journal; (run_id, ordinal) PK = idempotent OVERWRITE upsert; `result` = JSON.stringify(TaskResult)). `result`
-    // is TEXT, NOT JSONB — the byte-match contract is "string in, string out" (the store JSON.parses on load); JSONB would
-    // make `pg` auto-parse the row back to an object and break the twin's String()→JSON.parse path. See workflow-journal-store-sql.ts.
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id        VARCHAR(191) COLLATE "C" NOT NULL,
      ordinal       INT          NOT NULL,
@@ -223,8 +179,6 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (run_id, ordinal)
    )`,
-    // RB-242 / WF2 ([1981] core 拍板 a 形):cross-replica workflow resume admission lease — the PG twin of
-    // workflow_resume_claim in tidb-pool.ts (rationale there; TTL = crash backstop only).
     `CREATE TABLE IF NOT EXISTS workflow_resume_claim (
      source_run_id VARCHAR(191) COLLATE "C" NOT NULL,
      scope         VARCHAR(190) COLLATE "C" NOT NULL,
@@ -232,8 +186,6 @@ export const PG_SCHEMA_STATEMENTS = [
      claimed_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (source_run_id, scope)
    )`,
-    // P1 (fleet failover): WorkflowRunStore + completion-inbox PG twins (design doc in workflow-run-store-sql.ts).
-    // `run` is TEXT not jsonb (node-pg auto-parse would break the shared String()→JSON.parse path).
     `CREATE TABLE IF NOT EXISTS workflow_run (
      id            VARCHAR(191) COLLATE "C" NOT NULL,
      scope         VARCHAR(190) COLLATE "C" NOT NULL,
@@ -279,7 +231,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, kind, run_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_wffence_until ON workflow_inbox_fence (until_ms)`,
-    // 1.108 review fix (lens③ HIGH): notify-journal PG twin (design note in tidb-pool.ts).
     `CREATE TABLE IF NOT EXISTS workflow_notify_journal (
      run_id         VARCHAR(191) COLLATE "C" NOT NULL,
      scope          VARCHAR(190) COLLATE "C" NOT NULL,
@@ -291,10 +242,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (run_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_wfnotify_acked ON workflow_notify_journal (acked)`,
-    // design/177 shared-memory store —— org 盘三张表的 PG twin(MySQL 侧的逐列注释见 tidb-pool.ts;方言差
-    // 只在 TINYINT(1)→SMALLINT 与 inline KEY→独立 CREATE INDEX)。🔴 与 `agent_memory_engine_*` 零关系。
-    // 每个字符串列都带 COLLATE "C":core 的 cursor 词表是「UTF-16 code-unit 序」,而它的翻页只在
-    // `nextCursor > windowCursor`(JS 比较)成立时才继续 —— 数据库若按 locale 排序,一次列举会静默截断。
     `CREATE TABLE IF NOT EXISTS shared_memory_scope (
      scope_key     VARCHAR(190) COLLATE "C" NOT NULL,
      state         VARCHAR(16) COLLATE "C"  NOT NULL,
@@ -321,17 +268,6 @@ export const PG_SCHEMA_STATEMENTS = [
      PRIMARY KEY (store_id, path)
    )`,
 ];
-/** Build the pg PoolConfig from PG config (pure → unit-testable apart from the live connection) — the PG twin of
- *  tidbPoolOptions. `dbQueryTimeoutMs` (DB_QUERY_TIMEOUT_MS, S9 deeper fix) arms a POOL-WIDE per-query ceiling on
- *  every client the pool hands out, BOTH sides:
- *    - `statement_timeout` = T: SERVER-side cancel (sent as a startup parameter) — frees the server's resources
- *      and surfaces the canonical 57014 error on any statement that runs past T;
- *    - `query_timeout` = T + 5s: CLIENT-side read-timeout backstop for the cases the server can't answer at all
- *      (dead network / hung server — the S9 hang class). Slightly ABOVE statement_timeout on purpose, so the
- *      server's clean cancel normally wins and the client timer only fires when no response ever arrives (a
- *      query_timeout rejection makes pg-pool DESTROY that client, discarding the poisoned connection).
- *  Unset = both off (byte-compat: legit heavyweight statements — boot DDL, ≤64 MiB snapshot-blob rows — make a
- *  universal default unsafe; the S9 write-behind counter face carries its own always-on per-query timeout). */
 export function pgPoolOptions(pgCfg, dbQueryTimeoutMs) {
     return {
         host: pgCfg.host,
@@ -343,32 +279,14 @@ export function pgPoolOptions(pgCfg, dbQueryTimeoutMs) {
         ...(dbQueryTimeoutMs ? { statement_timeout: dbQueryTimeoutMs, query_timeout: dbQueryTimeoutMs + 5_000 } : {}),
     };
 }
-/** Create the PG pool from a connection string (or pg.PoolConfig). Thin — production backend-selection wiring
- *  (a ServiceConfig.pg sibling of .tidb) is a tracked follow-on. */
 export function createPgPool(opts) {
     return typeof opts === "string" ? new pg.Pool({ connectionString: opts }) : new pg.Pool(opts);
 }
-/** A fixed bigint key for the `pg_advisory_lock` that serializes the whole `ensurePgSchema` DDL run (see below).
- *  Arbitrary constant; only its uniqueness within this app matters (advisory-lock keys are app-private). */
 const ENSURE_SCHEMA_LOCK_KEY = 4906;
-/** Idempotent central schema apply (the PG twin of tidb-pool.ts ensureSchema): the run/checkpoint tables here +
- *  every PG store's own (disjoint) tables. Order is irrelevant (CREATE IF NOT EXISTS, no cross-table FKs).
- *
- *  Concurrency: callers run this concurrently — tests fan ALL integration suites out in parallel (each beforeAll
- *  calls ensurePgSchema), and in production every replica calls it at boot. Concurrent DDL on the SAME table makes
- *  PG raise `tuple concurrently updated` in its catalog. We serialize the entire run behind a session-level
- *  `pg_advisory_lock`: the first caller does the real CREATE/ALTER, the rest block until it unlocks then find every
- *  statement already satisfied (IF NOT EXISTS ⇒ no-op), so there is no catalog race. The DDL semantics are
- *  unchanged — only its timing is serialized. The advisory lock is SESSION (connection)-level, so the lock and
- *  ALL the DDL MUST run on the one client we hold; routing DDL through `pool.query` could land on a different
- *  pooled connection and silently void the lock. */
 export async function ensurePgSchema(pool) {
     const client = await pool.connect();
     let locked = false;
     try {
-        // pg_advisory_lock blocks until the lock is granted (the DDL run is short, so blocking is acceptable). If the
-        // lock op itself errors we DEGRADE to running the DDL unserialized rather than failing boot — the CREATE IF NOT
-        // EXISTS statements are still individually idempotent (they just lose the cross-caller serialization).
         try {
             await client.query("SELECT pg_advisory_lock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
             locked = true;
@@ -386,20 +304,10 @@ export async function ensurePgSchema(pool) {
         await ensureOutcomeLedgerSchema(client);
         await ensureImageIndexSchema(client);
         await ensureImageBakeSchema(client);
-        // #151 流内审批协议持久层(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。该 ensure 收的是裸
-        // `PgQueryFn`(而非兄弟们收的 client 形),故在这里绑一层 —— DDL 仍然跑在**同一条** client 上,
-        // advisory lock 的 session 语义不受影响(见本函数头注:路由到别的池连接会静默作废那把锁)。
         await ensurePgApprovalAskSchema((text, params) => client.query(text, params));
-        // design/183 form b 的 SQL 收编日志(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。
-        // 同 approval-ask:收裸 query 形,故在这里绑一层——DDL 仍跑在**同一条** client 上,advisory lock 不失效。
         await ensurePgAdoptionLogSchema((text, params) => client.query(text, params));
-        // #154 车二:持久化权限规则店三张表(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。
-        // 同上一行的绑法 —— DDL 跑在**同一条** client 上,advisory lock 的 session 语义不受影响。
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
-        // #193 车4 件1:durable leader-run 登记表(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。同上绑法。
         await ensurePgLeaderRunSchema((text, params) => client.query(text, params));
-        // #270 车1:托管留存执行面四表(审计/hold/sweep 租约/墓碑;MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS
-        // 展开)。同上绑法 —— DDL 跑在**同一条** client 上,advisory lock 的 session 语义不受影响。
         await ensurePgRetentionSchema((text, params) => client.query(text, params));
     }
     finally {

package/dist/plugins/pg-rate-limiter.js

@@ -1,9 +1,7 @@
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
-/** The counter's table binding for the per-key request rate limit (mirror of the TiDB twin's binding). */
 const RATE_LIMIT_TABLE = { table: "rate_limit", keyCol: "limit_key", valCol: "hits" };
 export class PgRateLimiter {
     counter;
-    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
     limit;
     refreshRequested = false;
     refreshIntervalMs;
@@ -26,17 +24,14 @@ export class PgRateLimiter {
     check(key) {
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
-        const usedBefore = this.counter.used(key); // fleet (last refresh) + local pending — soft/eventually consistent
-        this.counter.addLocal(key, 1); // count every request, like the in-memory limiter
+        const usedBefore = this.counter.used(key);
+        this.counter.addLocal(key, 1);
         return usedBefore < this.limit
             ? { allowed: true, retryAfterSec: 0, remaining: this.limit - usedBefore - 1 }
             : { allowed: false, retryAfterSec: Math.max(1, this.counter.retryAfterSec()), remaining: 0 };
     }
-    /** The flush loop self-reaps old windows; the periodic sweeper has nothing to do for this backend. */
     sweep() {
-        /* no-op */
     }
-    // write-behind lifecycle (delegated; exposed for tests/parity)
     flush() {
         return this.counter.flush();
     }
@@ -54,11 +49,6 @@ export class PgRateLimiter {
         this.counter.stop();
     }
 }
-/**
- * PG translation of tidb-pool's `rate_limit` DDL (SCHEMA_STATEMENTS): INT→INTEGER, DATETIME(3)→TIMESTAMPTZ(3),
- * inline `KEY idx_window`→separate `CREATE INDEX`. The composite PK (limit_key, window_bucket) backs the
- * atomic ON CONFLICT increment.
- */
 export const PG_RATE_LIMITER_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS rate_limit (
      limit_key     VARCHAR(190) COLLATE "C"   NOT NULL,
@@ -69,7 +59,6 @@ export const PG_RATE_LIMITER_SCHEMA = [
    )`,
     `CREATE INDEX IF NOT EXISTS idx_rate_limit_window ON rate_limit (window_bucket)`,
 ];
-/** Self-contained schema bootstrap for tests (the rate_limit table is disjoint from other stores). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_RATE_LIMITER_SCHEMA)
         await pool.query(stmt);

package/dist/plugins/pg-safe-json.js

@@ -1,26 +1,7 @@
-/**
- * PG 写入臂族的统一序列化([1439]/[1442]test CF-UNICODE + codex 四 high 复审)。
- *
- * 病:PG 的 text/jsonb 域**不可存 NUL**(ERRCODE 22P05/22021),unpaired surrogate 同族——tool_result
- * 夹带真 0x00(agent raw `cat` 二进制/含 NUL 文件)→ 写入即炸 → session append 崩、run 中途死
- * (云独有指纹:file store 无此约束,[1438]②/[1439] 定谳归 server)。
- *
- * 三层工具,按臂的保真需求选用:
- *  - {@link pgSanitizeText}:裸 text 列(memory body / tool_result content)。
- *  - {@link pgSafeJsonStringify}:**深度** sanitize(键+值都扫——codex H2:replacer 换不了键名,
- *    含 NUL 的属性名照样炸;撞键以 U+FFFD 追加消歧,诚实不静默覆盖)后 stringify。有损(U+FFFD),
- *    用于观测/记账类 blob(session event、run 行、outcome、journal——内容语义容忍替换标记)。
- *  - {@link pgLosslessJsonStringify}/{@link pgLosslessJsonParse}:**无损信封**(codex H1:checkpoint 的
- *    pendingAction args 过 approval 信任边界,hash 绑定原文,有损替换=执行内容偏离已批内容)。
- *    干净值原样直存(既有行形不变);含不可存码点才折 `{__pgSafeB64}` 信封(base64 承载 stringify
- *    原文——stringify 输出恒 well-formed 转义形,base64 逐位保真),读侧解封逐位还原。
- */
 const NUL_OR_LONE_SURROGATE = /\u0000|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
 export function pgSanitizeText(s) {
     return s.replace(NUL_OR_LONE_SURROGATE, "�");
 }
-/** 深度 sanitize:字符串值+**属性名**都扫(数组递归;非 plain 值原样)。输入应为 JSON-plain 树
- *  (调用方先过 `JSON.parse(JSON.stringify(v))` 保 toJSON/undefined 语义——见 pgSafeJsonStringify)。 */
 function sanitizeDeep(v, state) {
     if (typeof v === "string") {
         const s = pgSanitizeText(v);
@@ -31,13 +12,13 @@ function sanitizeDeep(v, state) {
     if (Array.isArray(v))
         return v.map((x) => sanitizeDeep(x, state));
     if (v !== null && typeof v === "object") {
-        const out = Object.create(null); // codex R2-M:{} 会把 own "__proto__" 键吞进原型 setter
+        const out = Object.create(null);
         for (const [k, val] of Object.entries(v)) {
             let key = pgSanitizeText(k);
             if (key !== k)
                 state.changed = true;
             while (Object.prototype.hasOwnProperty.call(out, key)) {
-                key += "�"; // 撞键消歧(两键仅差不可存字节的病态形)——追加标记,绝不静默覆盖
+                key += "�";
                 state.changed = true;
             }
             out[key] = sanitizeDeep(val, state);
@@ -46,27 +27,20 @@ function sanitizeDeep(v, state) {
     }
     return v;
 }
-/** 有损深度安全 stringify(键+值)。 */
 export function pgSafeJsonStringify(value) {
     const raw = JSON.stringify(value);
     if (raw === undefined)
-        return raw; // undefined 输入随 stringify 语义
-    const plain = JSON.parse(raw); // 先走一遍 stringify 语义(toJSON/undefined 剥离),再深扫
+        return raw;
+    const plain = JSON.parse(raw);
     const state = { changed: false };
     const clean = sanitizeDeep(plain, state);
     return state.changed ? JSON.stringify(clean) : raw;
 }
 const ENVELOPE_KEY = "__pgSafe";
 const ENVELOPE_VERSION = "b64.v1";
-/** 信封判别:**精确形**(恰两键 {__pgSafe:"b64.v1", d:string})——codex R2-H2:单键存在性判别会把
- *  「恰好带同名键的普通用户 JSON/老行」误当信封(合法 base64 静默解出别的对象、非 base64 读侧炸)。
- *  精确形+版本号把碰撞面收到「用户恰好存逐位同形信封」,由 stringify 侧转义规避(见下)。 */
 function isEnvelope(o) {
     return Object.keys(o).length === 2 && o[ENVELOPE_KEY] === ENVELOPE_VERSION && typeof o.d === "string";
 }
-/** 无损:干净值原样;脏值折版本化信封(读侧 {@link pgLosslessJsonParse} 逐位还原)。干净值若**恰为
- *  保留形**(用户数据撞信封/转义形)→ 套 {__pgSafe:"esc.v1", d:<原文>} 转义一层,读侧解一层——
- *  保留形永不与用户数据歧义。 */
 export function pgLosslessJsonStringify(value) {
     const raw = JSON.stringify(value);
     if (raw === undefined)
@@ -83,12 +57,8 @@ export function pgLosslessJsonStringify(value) {
         }
         return raw;
     }
-    // stringify 输出恒 well-formed(NUL/lone surrogate 均已是六字符转义),utf8→base64 逐位保真。
     return JSON.stringify({ [ENVELOPE_KEY]: ENVELOPE_VERSION, d: Buffer.from(raw, "utf8").toString("base64") });
 }
-/** detect-only:值树里是否含不可存码点(字符串值+属性名都查,零形变零拷贝)。干净输入(绝大多数)
- *  让调用方走**引用原样**快路——canonical 化的 JSON round-trip 对干净输入也可能形变(undefined 值键
- *  剥离等),CAS/rev 语义的臂必须先 detect 再变换。 */
 export function pgHasUnstorable(v) {
     if (typeof v === "string")
         return NUL_OR_LONE_SURROGATE.test(v) ? (NUL_OR_LONE_SURROGATE.lastIndex = 0, true) : false;
@@ -102,11 +72,6 @@ export function pgHasUnstorable(v) {
     }
     return false;
 }
-/** codex R4→R7 终形:协议数据(approval args/checkpoint/ctx/outcome/rules/memory)一律**拒绝式**。
- *  信封方案历经 R4-R7 四轮对抗全灭:行内判别子恒可被 ≤1.240 老行/用户数据撞形(静默解错=approval
- *  信任边界破),进程旗恒有混旗副本窗(写读不同解)。唯一无歧义解=**脏值不进库**:PG 存不了
- *  NUL 是后端能力边界,fail-loud 暴露(清晰文案)严格优于修前的 22P05 神秘崩——两者都存不进,
- *  但拒绝式下 review==execute 恒成立(库里只有干净值,展示面=执行面永逐位一致)。 */
 export class PgUnstorableError extends Error {
     constructor(what) {
         super(`${what} contains bytes PostgreSQL cannot store (NUL / lone surrogate). ` +
@@ -114,7 +79,6 @@ export class PgUnstorableError extends Error {
         this.name = "PgUnstorableError";
     }
 }
-/** 协议数据写面:干净=原样 stringify;脏={@link PgUnstorableError} fail-loud。 */
 export function pgProtocolJsonStringify(value, what) {
     const raw = JSON.stringify(value);
     if (raw === undefined)