@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/pg-outcome-ledger.js

@@ -1,2 +1,11 @@
+/**
+ * PostgreSQL outcome ledger — the implementation now lives in the single-file dual-dialect
+ * `outcome-ledger-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, JSON encode, the AVG boolean-coercion divergence) read side by side instead of
+ * drifting across two files.
+ *
+ * This file is the historical import path: class name, `PG_OUTCOME_LEDGER_SCHEMA` and `ensureSchema`
+ * are unchanged, so pg-pool.ts / store-backend.ts / the integration suite are untouched.
+ */
 export { PgOutcomeLedger, PG_OUTCOME_LEDGER_SCHEMA, ensurePgOutcomeLedgerSchema as ensureSchema, } from "./outcome-ledger-sql.js";
 //# sourceMappingURL=pg-outcome-ledger.js.map

package/dist/plugins/pg-pool.d.ts

@@ -1,7 +1,57 @@
+/**
+ * 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";
 import type { ServiceConfig } from "../config-types.js";
 export declare const PG_SCHEMA_STATEMENTS: readonly string[];
+/** 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 declare function pgPoolOptions(pgCfg: NonNullable<ServiceConfig["pg"]>, dbQueryTimeoutMs?: number): pg.PoolConfig;
+/** 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 declare function createPgPool(opts: string | pg.PoolConfig): pg.Pool;
+/** 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 declare function ensurePgSchema(pool: pg.Pool): Promise<void>;
 //# sourceMappingURL=pg-pool.d.ts.map

package/dist/plugins/pg-pool.js

@@ -1,4 +1,32 @@
+/**
+ * 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 "./pg-tool-result-store.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
@@ -46,6 +74,7 @@ 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) NOT NULL,
      scope        VARCHAR(190) NOT NULL,
@@ -77,6 +106,7 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at 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)    NOT NULL,
      event_id   VARCHAR(64)    NOT NULL,
@@ -86,6 +116,8 @@ 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 /
+    // docs/design/APPROVAL-SESSION-EXEMPTION.md).
     `CREATE TABLE IF NOT EXISTS approval_exemption (
      session_id VARCHAR(64)    NOT NULL,
      tool_name  VARCHAR(190)   NOT NULL,
@@ -93,6 +125,9 @@ 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)    NOT NULL,
      scope      VARCHAR(190)   NOT NULL,
@@ -108,6 +143,9 @@ 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 / tidb-session-policy-store.ts).
     `CREATE TABLE IF NOT EXISTS session_policy (
      policy_key CHAR(64)       NOT NULL,
      session_id VARCHAR(64)    NOT NULL,
@@ -122,6 +160,8 @@ 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)   NOT NULL,
      snap_key  VARCHAR(64)   NOT NULL,
@@ -143,6 +183,10 @@ 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 pg-workflow-journal-store.ts.
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id     VARCHAR(191) NOT NULL,
      ordinal    INT          NOT NULL,
@@ -157,6 +201,8 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at 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) NOT NULL,
      scope         VARCHAR(190) NOT NULL,
@@ -164,6 +210,8 @@ export const PG_SCHEMA_STATEMENTS = [
      claimed_at    BIGINT       NOT NULL,
      PRIMARY KEY (source_run_id, scope)
    )`,
+    // P1 (fleet failover): WorkflowRunStore + completion-inbox PG twins (design doc in tidb-workflow-run-store.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) NOT NULL,
      scope      VARCHAR(190) NOT NULL,
@@ -209,6 +257,7 @@ 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) NOT NULL,
      scope          VARCHAR(190) NOT NULL,
@@ -221,6 +270,17 @@ export const PG_SCHEMA_STATEMENTS = [
    )`,
     `CREATE INDEX IF NOT EXISTS idx_wfnotify_acked ON workflow_notify_journal (acked)`,
 ];
+/** 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,
@@ -232,14 +292,32 @@ 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;

package/dist/plugins/pg-query.d.ts

@@ -1,7 +1,18 @@
+/**
+ * `PgQueryFn` — the minimal pg query seam the server's PG-dialect stores are written against
+ * (`(text, params) => Promise<{ rows }>`; deliberately NO rowCount — callers assert post-state, not counts).
+ *
+ * HISTORY: this type used to be re-exported by `@sema-agent/core` from its pg REFERENCE adapter. core 1.424.0
+ * removed the whole example-adapter export surface from the npm package (clay's package-hygiene ruling,
+ * board [1803] — examples are in-repo samples, not user API). The type itself is server-owned wiring, so it
+ * moved here VERBATIM (same shape as core 1.423's `examples/adapters/pg-adapter.d.ts`); six plugins consume it.
+ */
 export interface PgQueryResult {
     rows: Array<Record<string, unknown>>;
 }
 export type PgQueryFn = (text: string, params?: unknown[]) => Promise<PgQueryResult>;
+/** Same relocation as PgQueryFn (core 1.424 example-adapter export removal): the embedding seam the
+ *  pg memory engine takes — verbatim shape from core 1.423's `examples/adapters/pg-adapter.d.ts`. */
 export interface PgEmbedder {
     embed(text: string): Promise<number[]>;
     dimensions: number;

package/dist/plugins/pg-rate-limiter.d.ts

@@ -1,3 +1,19 @@
+/**
+ * PostgreSQL cross-replica per-key request rate limiter — the PG twin of {@link TiDBRateLimiter}
+ * (src/plugins/tidb-rate-limiter.ts). Behaviourally identical: a thin {@link RateGate} over a shared
+ * write-behind aggregating counter; `check` both COUNTS the request and decides, with the count summed
+ * fleet-wide via atomic write-behind aggregation. SAME class surface + SAME SOFT-limiting semantics
+ * (eventually consistent: a replica may briefly admit a few requests over the ceiling at a window
+ * boundary before peers' counts propagate).
+ *
+ * design/158 A12 C1b: the `PgWriteBehindCounter` this file used to define inline now lives in
+ * write-behind-counter.ts as the PG binding of ONE dialect-parameterized counter (the mysql2 twin is
+ * `WriteBehindCounter`); the SQL-dialect deltas are documented and branched there. It is re-exported here
+ * so the historical import path keeps working.
+ *
+ * Schema: this store's `rate_limit` table is DISJOINT from the other PG stores' tables, so a
+ * self-contained {@link PG_RATE_LIMITER_SCHEMA} + {@link ensureSchema} is safe (no shadowing).
+ */
 import type { Pool, PoolClient } from "pg";
 import type { RateDecision, RateGate } from "../observability/rate-limit.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
@@ -8,12 +24,19 @@ export declare class PgRateLimiter implements RateGate {
     private readonly counter;
     constructor(pool: Pool, limit: number, windowMs?: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
     check(key: string): RateDecision;
+    /** The flush loop self-reaps old windows; the periodic sweeper has nothing to do for this backend. */
     sweep(): void;
     flush(): Promise<void>;
     refresh(): Promise<void>;
     startRefresh(intervalMs?: number): this;
     stop(): void;
 }
+/**
+ * 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 declare const PG_RATE_LIMITER_SCHEMA: string[];
+/** Self-contained schema bootstrap for tests (the rate_limit table is disjoint from other stores). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
 //# sourceMappingURL=pg-rate-limiter.d.ts.map

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

@@ -1,5 +1,6 @@
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
 export { 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: "n" };
 export class PgRateLimiter {
     limit;
@@ -11,14 +12,17 @@ export class PgRateLimiter {
     check(key) {
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
-        const usedBefore = this.counter.used(key);
-        this.counter.addLocal(key, 1);
+        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
         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();
     }
@@ -33,6 +37,11 @@ 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)   NOT NULL,
@@ -43,6 +52,7 @@ 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-resume-anchor-store.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation moved to the single-file
+ * dual-dialect `resume-anchor-store-sql.ts` (shared with the TiDB twin via `SqlDriver`). Kept so
+ * consumers importing this path (store-backend.ts, the resume-anchor integration suite) don't move.
+ */
 export { PgResumeAnchorStore } from "./resume-anchor-store-sql.js";
 //# sourceMappingURL=pg-resume-anchor-store.d.ts.map

package/dist/plugins/pg-resume-anchor-store.js

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation moved to the single-file
+ * dual-dialect `resume-anchor-store-sql.ts` (shared with the TiDB twin via `SqlDriver`). Kept so
+ * consumers importing this path (store-backend.ts, the resume-anchor integration suite) don't move.
+ */
 export { PgResumeAnchorStore } from "./resume-anchor-store-sql.js";
 //# sourceMappingURL=pg-resume-anchor-store.js.map

package/dist/plugins/pg-run-store.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场 collapse): the real implementation now lives in
+ * `run-store-sql.ts` (single-file dual-dialect — TiDB + PG share one `SqlRunStore` body, dialect deltas
+ * kept EXPLICIT per statement). `PgRunStore`'s class name/ctor arity is unchanged so every existing
+ * consumer (store-backend.ts, the reaper/session integration suites) needs ZERO changes. New code
+ * should import from `run-store-sql.ts` directly.
+ */
 export { PgRunStore } from "./run-store-sql.js";
 //# sourceMappingURL=pg-run-store.d.ts.map

package/dist/plugins/pg-run-store.js

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场 collapse): the real implementation now lives in
+ * `run-store-sql.ts` (single-file dual-dialect — TiDB + PG share one `SqlRunStore` body, dialect deltas
+ * kept EXPLICIT per statement). `PgRunStore`'s class name/ctor arity is unchanged so every existing
+ * consumer (store-backend.ts, the reaper/session integration suites) needs ZERO changes. New code
+ * should import from `run-store-sql.ts` directly.
+ */
 export { PgRunStore } from "./run-store-sql.js";
 //# sourceMappingURL=pg-run-store.js.map

package/dist/plugins/pg-safe-json.d.ts

@@ -1,9 +1,22 @@
 export declare function pgSanitizeText(s: string): string;
+/** 有损深度安全 stringify(键+值)。 */
 export declare function pgSafeJsonStringify(value: unknown): string;
+/** 无损:干净值原样;脏值折版本化信封(读侧 {@link pgLosslessJsonParse} 逐位还原)。干净值若**恰为
+ *  保留形**(用户数据撞信封/转义形)→ 套 {__pgSafe:"esc.v1", d:<原文>} 转义一层,读侧解一层——
+ *  保留形永不与用户数据歧义。 */
 export declare function pgLosslessJsonStringify(value: unknown): string;
+/** detect-only:值树里是否含不可存码点(字符串值+属性名都查,零形变零拷贝)。干净输入(绝大多数)
+ *  让调用方走**引用原样**快路——canonical 化的 JSON round-trip 对干净输入也可能形变(undefined 值键
+ *  剥离等),CAS/rev 语义的臂必须先 detect 再变换。 */
 export declare function pgHasUnstorable(v: unknown): boolean;
+/** codex R4→R7 终形:协议数据(approval args/checkpoint/ctx/outcome/rules/memory)一律**拒绝式**。
+ *  信封方案历经 R4-R7 四轮对抗全灭:行内判别子恒可被 ≤1.240 老行/用户数据撞形(静默解错=approval
+ *  信任边界破),进程旗恒有混旗副本窗(写读不同解)。唯一无歧义解=**脏值不进库**:PG 存不了
+ *  NUL 是后端能力边界,fail-loud 暴露(清晰文案)严格优于修前的 22P05 神秘崩——两者都存不进,
+ *  但拒绝式下 review==execute 恒成立(库里只有干净值,展示面=执行面永逐位一致)。 */
 export declare class PgUnstorableError extends Error {
     constructor(what: string);
 }
+/** 协议数据写面:干净=原样 stringify;脏={@link PgUnstorableError} fail-loud。 */
 export declare function pgProtocolJsonStringify(value: unknown, what: string): string;
 //# sourceMappingURL=pg-safe-json.d.ts.map

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

@@ -1,7 +1,26 @@
+/**
+ * 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);
@@ -12,13 +31,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);
+        const out = Object.create(null); // codex R2-M:{} 会把 own "__proto__" 键吞进原型 setter
         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);
@@ -27,20 +46,27 @@ function sanitizeDeep(v, state) {
     }
     return v;
 }
+/** 有损深度安全 stringify(键+值)。 */
 export function pgSafeJsonStringify(value) {
     const raw = JSON.stringify(value);
     if (raw === undefined)
-        return raw;
-    const plain = JSON.parse(raw);
+        return raw; // undefined 输入随 stringify 语义
+    const plain = JSON.parse(raw); // 先走一遍 stringify 语义(toJSON/undefined 剥离),再深扫
     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)
@@ -57,8 +83,12 @@ 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;
@@ -72,6 +102,11 @@ 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). ` +
@@ -79,6 +114,7 @@ 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)

package/dist/plugins/pg-session-policy-store.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation lives in the single-file
+ * dual-dialect `session-policy-store-sql.ts` (`SqlSessionPolicyStore` + this file's historical
+ * `PgSessionPolicyStore` ctor subclass). Kept so every consumer's import path is untouched.
+ */
 export { PgSessionPolicyStore } from "./session-policy-store-sql.js";
 //# sourceMappingURL=pg-session-policy-store.d.ts.map

package/dist/plugins/pg-session-policy-store.js

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation lives in the single-file
+ * dual-dialect `session-policy-store-sql.ts` (`SqlSessionPolicyStore` + this file's historical
+ * `PgSessionPolicyStore` ctor subclass). Kept so every consumer's import path is untouched.
+ */
 export { PgSessionPolicyStore } from "./session-policy-store-sql.js";
 //# sourceMappingURL=pg-session-policy-store.js.map