@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,9 +1,13 @@
 import { historyRowFrom } from "./memory-sync-store-pg.js";
+/** Table names (single source) — SAME names as PG_MEMORY_SYNC_TABLES (the two dialects never share
+ *  one database). */
 export const TIDB_MEMORY_SYNC_TABLES = {
     syncCursors: "agent_memory_engine_sync_cursors",
     pushQueue: "agent_memory_engine_push_queue",
     history: "agent_memory_engine_history",
 };
+/** Idempotent DDL for the sync plane (TiDB dialect). Call once at startup.
+ *  Key budget: utf8mb4 = 4 bytes/char, index cap 3072 bytes ⇒ PK(scope,peer) = 380 chars = 1520 B ✓. */
 export async function ensureTiDBMemorySyncSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_SYNC_TABLES.syncCursors} (
     scope         VARCHAR(190) NOT NULL,
@@ -24,11 +28,14 @@ export async function ensureTiDBMemorySyncSchema(pool) {
     KEY idx_next_attempt (next_attempt_at)
   )`);
 }
+/** JSON-column defense: mysql2 normally hands back parsed objects for JSON columns, but string
+ *  shapes leak through (connection flags/proxies) — same posture as memory-engine-tidb.ts. */
 function fromJson(v) {
     if (typeof v === "string")
         return JSON.parse(v);
     return v;
 }
+/** BIGINT columns may arrive as string depending on driver flags — normalize defensively. */
 function toMs(v) {
     return typeof v === "number" ? v : Number(v);
 }
@@ -43,6 +50,7 @@ export class TiDBMemorySyncStore {
         }
         this.claimLeaseMs = lease;
     }
+    // ── cursors ────────────────────────────────────────────────────────────────
     async getCursor(scope, peer) {
         const [rows] = await this.pool.query(`SELECT base_revs, updated_at_ms FROM ${TIDB_MEMORY_SYNC_TABLES.syncCursors} WHERE scope = ? AND peer = ?`, [scope, peer]);
         const row = rows[0];
@@ -56,11 +64,16 @@ export class TiDBMemorySyncStore {
         };
     }
     async putCursor(cursor) {
+        // The table's ONLY unique key is PK(scope,peer) ⇒ ON DUPLICATE KEY UPDATE has exactly one
+        // possible trigger — no hijack face (the entries-table ban does NOT apply; see header).
         await this.pool.query(`INSERT INTO ${TIDB_MEMORY_SYNC_TABLES.syncCursors} (scope, peer, base_revs, updated_at_ms)
        VALUES (?, ?, ?, ?)
        ON DUPLICATE KEY UPDATE base_revs = VALUES(base_revs), updated_at_ms = VALUES(updated_at_ms)`, [cursor.scope, cursor.peer, JSON.stringify(cursor.baseRevs), cursor.updatedAtMs]);
     }
+    // ── push queue ─────────────────────────────────────────────────────────────
     async enqueue(item) {
+        // Plain INSERT, fail-loud on a duplicate id (ER_DUP_ENTRY 1062) — caller mints uuidv7 per
+        // enqueue, a dup is a caller bug, never silently absorbed. Same posture as the PG twin.
         await this.pool.query(`INSERT INTO ${TIDB_MEMORY_SYNC_TABLES.pushQueue} (id, scope, entry_id, payload, attempts, next_attempt_at, last_error)
        VALUES (?, ?, ?, ?, 0, ?, NULL)`, [item.id, item.scope, item.entryId, JSON.stringify(item.payload), item.nextAttemptAtMs]);
     }
@@ -68,6 +81,10 @@ export class TiDBMemorySyncStore {
         if (limit <= 0)
             return [];
         const leasedUntilMs = nowMs + this.claimLeaseMs;
+        // Optimistic CAS claim (header rationale): read the due candidates, then win each row with a
+        // conditional UPDATE on the exact next_attempt_at we read. Losers (another worker claimed, or
+        // fail()/a re-schedule moved the row) see affectedRows=0 and are skipped — the SKIP LOCKED
+        // equivalent, without pessimistic locks or a held connection.
         const [candidates] = await this.pool.query(`SELECT id, scope, entry_id, payload, attempts, next_attempt_at, last_error
        FROM ${TIDB_MEMORY_SYNC_TABLES.pushQueue}
        WHERE next_attempt_at <= ?
@@ -75,11 +92,13 @@ export class TiDBMemorySyncStore {
        LIMIT ?`, [nowMs, limit]);
         const claimed = [];
         for (const row of candidates) {
+            // affectedRows=CHANGED 语义坑防御:lease = nowMs + claimLeaseMs > nowMs ≥ 读到的 next_attempt_at
+            // (WHERE 已保证),新值严格大于旧值 ⇒ 匹配必 change ⇒ affectedRows=1 恒等于「真的赢了」。
             const [res] = await this.pool.query(`UPDATE ${TIDB_MEMORY_SYNC_TABLES.pushQueue}
          SET next_attempt_at = ?
          WHERE id = ? AND next_attempt_at = ?`, [leasedUntilMs, row.id, toMs(row.next_attempt_at)]);
             if (res.affectedRows !== 1)
-                continue;
+                continue; // lost the race — skip, never block
             claimed.push({
                 id: row.id,
                 scope: row.scope,
@@ -96,12 +115,20 @@ export class TiDBMemorySyncStore {
         await this.pool.query(`DELETE FROM ${TIDB_MEMORY_SYNC_TABLES.pushQueue} WHERE id = ?`, [id]);
     }
     async fail(id, error, nextAttemptAtMs) {
+        // attempts = attempts + 1 is SQL-atomic (never read-modify-write in JS); the increment also
+        // guarantees the row CHANGES — the claim verdict is honest under BOTH affectedRows semantics
+        // (mysql2 default = FOUND_ROWS/matched; changed-only would also work here).
         await this.pool.query(`UPDATE ${TIDB_MEMORY_SYNC_TABLES.pushQueue}
        SET attempts = attempts + 1, last_error = ?, next_attempt_at = ?
        WHERE id = ?`, [error, nextAttemptAtMs, id]);
     }
 }
+// ── 142-S5 §1.3 — history table (tombstone + rev chain), TiDB dialect ───────────────────────────
+/** Idempotent DDL for the history table (TiDB dialect). Key budget: PK(id,rev) = CHAR(36)+
+ *  VARCHAR(128) = 164 chars ≤ 3072-byte utf8mb4 index cap ✓; KEY(scope) = 190 chars ✓. */
 export async function ensureTiDBMemoryHistorySchema(pool) {
+    // scope column + written_at_ms BIGINT = the same design-doc amendments as the Pg twin (see
+    // MemoryHistoryAppendRow.scope / ensurePgMemoryHistorySchema).
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_SYNC_TABLES.history} (
     id            CHAR(36)     NOT NULL,
     rev           VARCHAR(128) NOT NULL,
@@ -122,6 +149,9 @@ export class TiDBMemoryHistoryStore {
     async appendHistory(rows) {
         if (rows.length === 0)
             return;
+        // ONE multi-row INSERT; dup (id,rev) replay = no-op via `ON DUPLICATE KEY UPDATE id = id`
+        // (header rationale: NOT INSERT IGNORE — IGNORE swallows non-dup errors too). PK(id,rev) is the
+        // only unique key ⇒ the ODKU trigger is unambiguous, and the "update" writes nothing.
         const params = [];
         for (const r of rows) {
             params.push(r.id, r.rev, r.prevRev ?? null, r.op, r.scope, r.snapshot === undefined || r.snapshot === null ? null : JSON.stringify(r.snapshot), r.writtenAtMs);

package/dist/plugins/outcome-ledger-sql.d.ts

@@ -2,6 +2,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient } from "pg";
 import type { TaskOutcome as CoreTaskOutcome } from "@sema-agent/core";
 import { type SqlDriver } from "./sql-driver.js";
+/** Mechanical signals — the ONLY tier a future self-scheduler may read (council blocker 1). */
 export interface MechanicalOutcome {
     route?: "single" | "fanout";
     workerCount?: number;
@@ -14,6 +15,7 @@ export interface MechanicalOutcome {
     costMicroUsd?: number;
     turns?: number;
 }
+/** LLM-assisted signals — dashboard-only, NEVER drives automatic change, NEVER co-weighted. */
 export interface LlmAssistedOutcome {
     stuckEvents?: number;
     verifier?: {
@@ -21,35 +23,94 @@ export interface LlmAssistedOutcome {
         confidence: number;
     };
 }
+/** Raw inputs to the v1 task-signature (council Q11 candidate (a): structural/keyword hash). */
 export interface SignatureInputs {
     taskType?: string;
     toolset?: string[];
     targetLang?: string;
     moduleCount?: number;
+    /** Optional explicit tag override (council Q11 candidate (c)). When set, it IS the signature. */
     tag?: string;
 }
+/**
+ * Run-status classification (council blocker 3 — attribution noise). Gates whether the
+ * mechanical signal reflects TASK quality at all: an `infra-aborted` run died in the basework (sandbox
+ * OOM / git-ownership / timeout / harvest fail) BEFORE reaching the grader, so its 0/total oracle is an
+ * infra-health signal, NOT a task-difficulty signal. Route/budget learning must read `completed-graded`
+ * rows ONLY; `infra-aborted` rows are kept for the infra-health dashboard but excluded from training.
+ * (Found live: the task#2b backfill showed 9% pass-rate that was really 10/11 infra deaths since fixed.)
+ */
 export type RunStatus = "completed-graded" | "infra-aborted";
 export interface TaskOutcome {
     taskId?: string;
     model: string;
+    /** Default "completed-graded" if omitted. Set "infra-aborted" for runs that never reached the grader. */
     runStatus?: RunStatus;
     signatureInputs: SignatureInputs;
     mechanical: MechanicalOutcome;
     llmAssisted?: LlmAssistedOutcome;
+    /** design/73 §1 consumption: the VERBATIM core `TaskOutcome` fact this row was derived from (status/
+     *  errorCode/oracleHadRedRun/oracle blob — fields the v1 columns predate). Stored as-is in `core_outcome`
+     *  so red-line ② (`oracleHadRedRun`) and the free-form oracle survive lossless; the mapped mechanical
+     *  columns stay the aggregate/query surface. */
     core?: unknown;
 }
+/**
+ * v1 task-signature (council Q11, recommended candidate (a)): a deterministic structural hash — zero
+ * embedder, coarse on purpose (routing is a coarse decision). An explicit `tag` short-circuits to the
+ * tag itself (candidate (c)).
+ */
 export declare function taskSignature(s: SignatureInputs): string;
+/**
+ * Derive the coarse outcome from MECHANICAL fields only (council blocker 1: llmAssisted never participates).
+ * pass = all hidden tests green AND both build exits 0 AND merge ok; fail = nothing graded green; else partial.
+ */
 export declare function deriveOutcome(m: MechanicalOutcome, runStatus?: RunStatus): "pass" | "partial" | "fail" | "aborted";
+/**
+ * design/73 §1 → §7 bridge: project one CORE `TaskOutcome` fact (the `RunnerDeps.onTaskOutcome` seam,
+ * core 1.226) onto a v1 ledger row. Lossless: the verbatim fact rides `core` → the `core_outcome` JSON
+ * column (red-line ② `oracleHadRedRun` + the free-form oracle blob have no v1 columns); the mapped
+ * mechanical fields keep the existing aggregate surface working. Mapping rules:
+ *  - `signatureInputs.tag = o.taskSignature` — core already emits THE aggregation key, so the ledger's
+ *    tag short-circuit adopts it verbatim (no re-derivation drift);
+ *  - oracle counts: `oracle.oraclePassed/oracleTotal` when the harness supplied numeric counts, else the
+ *    required `green` bit as 1/0 over 1 (an honest degenerate count, not a fabrication);
+ *  - `runStatus` stays "completed-graded": core's red line ③ means emission only happens at a REAL
+ *    mechanical-oracle terminal (an infra-aborted run never reaches the emit point).
+ */
 export declare function coreOutcomeToLedgerRow(o: CoreTaskOutcome): TaskOutcome;
+/**
+ * PG translation of the `outcome_ledger` DDL in tidb-pool.ts SCHEMA_STATEMENTS:
+ * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), TINYINT(1)→SMALLINT, INT→INTEGER, inline KEY→separate CREATE INDEX.
+ * The table is DISJOINT from every other store's tables, so this self-contained set is safe (no shadowing).
+ *
+ * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
+ * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
+ */
 export declare const PG_OUTCOME_LEDGER_SCHEMA: string[];
+/** Idempotent self-contained PG schema apply (for the integration test; central aggregation via pg-pool.ts). */
 export declare function ensurePgOutcomeLedgerSchema(pool: PgPool | PoolClient): Promise<void>;
+/** Dual-dialect outcome ledger. See the file header for the dialect-delta ledger. */
 export declare class SqlOutcomeLedger {
     private readonly db;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** JSON column encode: TiDB stores `JSON.stringify` verbatim; PG runs the deep NUL/lone-surrogate
+     *  sanitize (a raw tool_result/core blob can carry bytes PG's jsonb column rejects, ERRCODE 22P05) — this
+     *  store's blobs are observability/dashboard data, so the lossy (U+FFFD) sanitize is the right tier
+     *  (not the lossless envelope checkpoint-store-sql.ts uses for the approval trust boundary). */
     private json;
+    /** Record one graded task run. Idempotent only by row id; callers pass distinct runs. */
     record(o: TaskOutcome): Promise<string>;
+    /** design/73 §1 seam consumption: record one CORE outcome fact (see {@link coreOutcomeToLedgerRow}). */
     recordCore(o: CoreTaskOutcome): Promise<void>;
+    /**
+     * Read-only aggregate for the dashboard / offline backtest: pass-rate + mean cost per (signature, model).
+     * 🔴 Defaults to `completed-graded` rows ONLY — the route/budget-learning signal must exclude infra-aborted
+     * runs (council blocker 3: a basework death is not a task-difficulty signal). Pass
+     * `includeAborted: true` only for the infra-health view, never for training.
+     */
     summary(opts?: {
         taskSignature?: string;
         includeAborted?: boolean;
@@ -61,9 +122,11 @@ export declare class SqlOutcomeLedger {
         meanCostMicroUsd: number;
     }>>;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBOutcomeLedger extends SqlOutcomeLedger {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgOutcomeLedger extends SqlOutcomeLedger {
     constructor(pool: PgPool);
 }

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

@@ -1,6 +1,42 @@
+/**
+ * Outcome ledger (design/73 §7) — the read-only first step of grounded self-evolution. SINGLE-FILE
+ * DUAL-DIALECT (design/158 A12 定型半场): ONE implementation, TWO dialects; the historical
+ * `TiDBOutcomeLedger` / `PgOutcomeLedger` class names survive as thin ctor subclasses so every consumer
+ * (store-backend.ts, pg-pool.ts, the unit + real-DB suites) is untouched.
+ *
+ * One row per graded task run, keyed by (taskSignature, model). v1 is STRICTLY READ-ONLY: it records
+ * outcomes for a dashboard + as the dataset for an offline backtest (bandit vs fixed routing). It drives
+ * NO automatic policy change — that is flag-gated and must first pass the offline-backtest gate
+ * (council blocker 3 / major 7).
+ *
+ * 🔴 Signal-hardness split is the load-bearing invariant (council blocker 1): only `mechanical` fields
+ * (oracle pass/total, build exits, mergeOk, cost, turns, route, replan) may ever drive an automatic
+ * policy change. `llmAssisted` (stuck counts, verifier verdict+confidence) is dashboard-only, carried in
+ * its own blob, never co-weighted with mechanical. `outcome` is DERIVED from mechanical fields ONLY.
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`                          - JSON columns bound `CAST(? AS JSON)`-free (TiDB
+ *     stores the string verbatim) vs `$n::jsonb`
+ *   - JSON encode: TiDB `JSON.stringify` verbatim vs PG `pgSafeJsonStringify` (deep NUL/lone-surrogate
+ *     sanitize — a raw tool_result/core blob can carry bytes PG's text/jsonb columns reject, ERRCODE 22P05)
+ *   - affected/SELECT rows via `result.rowCount` / `result.rows` (not RowDataPacket/ResultSetHeader) — via SqlDriver
+ *   - BIGINT (cost_micro_usd) read back as a STRING by node-pg → wrapped in `Number(...)`
+ *   - `AVG(outcome = 'pass')` (MySQL boolean→1/0) vs `AVG((outcome = 'pass')::int)` (PG has no boolean→int coercion)
+ *   - merge_ok TINYINT(1) vs SMALLINT (0/1 in/out)       - DATETIME(3) vs TIMESTAMPTZ(3) (Date in/out)
+ *   - schema ownership: TiDB DDL lives in tidb-pool.ts SCHEMA_STATEMENTS; the PG DDL is exported from HERE
+ *     (`PG_OUTCOME_LEDGER_SCHEMA` + `ensurePgOutcomeLedgerSchema`) for pg-pool.ts + the integration test.
+ *
+ * Kept in lock-step across dialects by the shared real-DB integration suite
+ * (test/pg-outcome-ledger-integration.test.ts, both engines run the SAME scenarios in parallel).
+ */
 import { randomUUID, createHash } from "node:crypto";
 import { pgSafeJsonStringify } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/**
+ * v1 task-signature (council Q11, recommended candidate (a)): a deterministic structural hash — zero
+ * embedder, coarse on purpose (routing is a coarse decision). An explicit `tag` short-circuits to the
+ * tag itself (candidate (c)).
+ */
 export function taskSignature(s) {
     if (s.tag)
         return `tag:${s.tag}`;
@@ -12,7 +48,14 @@ export function taskSignature(s) {
     });
     return `h:${createHash("sha256").update(canon).digest("hex").slice(0, 16)}`;
 }
+/**
+ * Derive the coarse outcome from MECHANICAL fields only (council blocker 1: llmAssisted never participates).
+ * pass = all hidden tests green AND both build exits 0 AND merge ok; fail = nothing graded green; else partial.
+ */
 export function deriveOutcome(m, runStatus = "completed-graded") {
+    // An infra-aborted run never reached the grader — its 0/total is infra, not task quality. Don't let it
+    // read as "fail" (which a self-scheduler would mistake for task difficulty); mark it "aborted" so the
+    // backtest can exclude it (council blocker 3).
     if (runStatus === "infra-aborted")
         return "aborted";
     const oracleGreen = m.oracleTotal != null && m.oracleTotal > 0 && m.oraclePassed === m.oracleTotal;
@@ -20,9 +63,24 @@ export function deriveOutcome(m, runStatus = "completed-graded") {
     const mergeGreen = m.mergeOk !== false;
     if (oracleGreen && buildGreen && mergeGreen)
         return "pass";
+    // "partial" needs POSITIVE green evidence. An OMITTED mergeOk is non-evidence — counting it green (the
+    // pre-2026-07 behavior) made "fail" unreachable for any row without an explicit mergeOk:false, so a
+    // fully-red oracle read as "partial" (caught wiring the design/73 §1 bridge, whose rows carry no mergeOk).
     const anyGreen = oracleGreen || (m.oraclePassed != null && m.oraclePassed > 0) || m.mergeOk === true;
     return anyGreen ? "partial" : "fail";
 }
+/**
+ * design/73 §1 → §7 bridge: project one CORE `TaskOutcome` fact (the `RunnerDeps.onTaskOutcome` seam,
+ * core 1.226) onto a v1 ledger row. Lossless: the verbatim fact rides `core` → the `core_outcome` JSON
+ * column (red-line ② `oracleHadRedRun` + the free-form oracle blob have no v1 columns); the mapped
+ * mechanical fields keep the existing aggregate surface working. Mapping rules:
+ *  - `signatureInputs.tag = o.taskSignature` — core already emits THE aggregation key, so the ledger's
+ *    tag short-circuit adopts it verbatim (no re-derivation drift);
+ *  - oracle counts: `oracle.oraclePassed/oracleTotal` when the harness supplied numeric counts, else the
+ *    required `green` bit as 1/0 over 1 (an honest degenerate count, not a fabrication);
+ *  - `runStatus` stays "completed-graded": core's red line ③ means emission only happens at a REAL
+ *    mechanical-oracle terminal (an infra-aborted run never reaches the emit point).
+ */
 export function coreOutcomeToLedgerRow(o) {
     const passed = typeof o.oracle?.oraclePassed === "number" ? o.oracle.oraclePassed : o.oracle?.green ? 1 : 0;
     const total = typeof o.oracle?.oracleTotal === "number" ? o.oracle.oracleTotal : 1;
@@ -30,6 +88,8 @@ export function coreOutcomeToLedgerRow(o) {
         taskId: o.runId.slice(0, 64),
         model: (o.model ?? "unknown").slice(0, 190),
         signatureInputs: {
+            // 🔴 `taskSignature()` prepends "tag:" → the final task_signature must fit VARCHAR(190).
+            // Cap the raw tag at 190 − len("tag:") = 186 so the prefixed key never overflows/truncates the column.
             tag: o.taskSignature.slice(0, 186),
             ...(o.signatureInputs?.toolset ? { toolset: o.signatureInputs.toolset } : {}),
             ...(o.signatureInputs?.targetLang ? { targetLang: o.signatureInputs.targetLang } : {}),
@@ -44,6 +104,14 @@ export function coreOutcomeToLedgerRow(o) {
         core: o,
     };
 }
+/**
+ * PG translation of the `outcome_ledger` DDL in tidb-pool.ts SCHEMA_STATEMENTS:
+ * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), TINYINT(1)→SMALLINT, INT→INTEGER, inline KEY→separate CREATE INDEX.
+ * The table is DISJOINT from every other store's tables, so this self-contained set is safe (no shadowing).
+ *
+ * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
+ * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
+ */
 export const PG_OUTCOME_LEDGER_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS outcome_ledger (
      id             VARCHAR(64)  NOT NULL,
@@ -75,31 +143,44 @@ export const PG_OUTCOME_LEDGER_SCHEMA = [
     `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_outcome ON outcome_ledger (outcome)`,
     `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_created ON outcome_ledger (created_at)`,
 ];
+/** Idempotent self-contained PG schema apply (for the integration test; central aggregation via pg-pool.ts). */
 export async function ensurePgOutcomeLedgerSchema(pool) {
     for (const stmt of PG_OUTCOME_LEDGER_SCHEMA)
         await pool.query(stmt);
 }
+/** Dual-dialect outcome ledger. See the file header for the dialect-delta ledger. */
 export class SqlOutcomeLedger {
     db;
     constructor(db) {
         this.db = db;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** JSON column encode: TiDB stores `JSON.stringify` verbatim; PG runs the deep NUL/lone-surrogate
+     *  sanitize (a raw tool_result/core blob can carry bytes PG's jsonb column rejects, ERRCODE 22P05) — this
+     *  store's blobs are observability/dashboard data, so the lossy (U+FFFD) sanitize is the right tier
+     *  (not the lossless envelope checkpoint-store-sql.ts uses for the approval trust boundary). */
     json(value) {
         return this.db.dialect === "tidb" ? JSON.stringify(value) : pgSafeJsonStringify(value);
     }
+    /** Record one graded task run. Idempotent only by row id; callers pass distinct runs. */
     async record(o) {
         const id = randomUUID().replace(/-/g, "").slice(0, 32);
         const sig = taskSignature(o.signatureInputs);
         const m = o.mechanical;
         const runStatus = o.runStatus ?? "completed-graded";
-        await this.db.query(this.q(`INSERT INTO outcome_ledger
+        await this.db.query(this.q(
+        // 🔴 byte-for-byte preserved from tidb-outcome-ledger.ts (pre-collapse) — the parity harness
+        // diffs this literally, so its indentation is NOT reflowed to the new call-site nesting.
+        `INSERT INTO outcome_ledger
         (id, task_signature, model, task_id, run_status, route, worker_count, oracle_passed, oracle_total,
          assemble_exit, lint_exit, merge_ok, replan_triggers, cost_micro_usd, turns, outcome,
          llm_assisted, signature_inputs, core_outcome, created_at)
-       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, `INSERT INTO outcome_ledger
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, 
+        // 🔴 byte-for-byte preserved from pg-outcome-ledger.ts (pre-collapse).
+        `INSERT INTO outcome_ledger
         (id, task_signature, model, task_id, run_status, route, worker_count, oracle_passed, oracle_total,
          assemble_exit, lint_exit, merge_ok, replan_triggers, cost_micro_usd, turns, outcome,
          llm_assisted, signature_inputs, core_outcome, created_at)
@@ -114,9 +195,16 @@ export class SqlOutcomeLedger {
         ]);
         return id;
     }
+    /** design/73 §1 seam consumption: record one CORE outcome fact (see {@link coreOutcomeToLedgerRow}). */
     async recordCore(o) {
         await this.record(coreOutcomeToLedgerRow(o));
     }
+    /**
+     * Read-only aggregate for the dashboard / offline backtest: pass-rate + mean cost per (signature, model).
+     * 🔴 Defaults to `completed-graded` rows ONLY — the route/budget-learning signal must exclude infra-aborted
+     * runs (council blocker 3: a basework death is not a task-difficulty signal). Pass
+     * `includeAborted: true` only for the infra-health view, never for training.
+     */
     async summary(opts = {}) {
         const clauses = [];
         const params = [];
@@ -124,10 +212,14 @@ export class SqlOutcomeLedger {
             clauses.push("run_status = 'completed-graded'");
         if (opts.taskSignature) {
             params.push(opts.taskSignature);
+            // 🔴 placeholder ARITY differs, not just the token: TiDB's `?` is positional-anonymous (always just
+            // "?"), while PG's `$n` must name the actual ordinal — `params.length` after the push IS that ordinal.
             clauses.push(this.q("task_signature = ?", `task_signature = $${params.length}`));
         }
         const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
-        const { rows } = await this.db.query(this.q(`SELECT task_signature, model, COUNT(*) n,
+        const { rows } = await this.db.query(this.q(
+        // 🔴 byte-for-byte preserved (both statements) — not reflowed to the new call-site nesting.
+        `SELECT task_signature, model, COUNT(*) n,
               AVG(outcome = 'pass') pass_rate, AVG(cost_micro_usd) mean_cost
          FROM outcome_ledger ${where}
         GROUP BY task_signature, model
@@ -145,11 +237,13 @@ export class SqlOutcomeLedger {
         }));
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBOutcomeLedger extends SqlOutcomeLedger {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgOutcomeLedger extends SqlOutcomeLedger {
     constructor(pool) {
         super(pgDriver(pool));

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

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT alongside the TiDB twin). Class name, ctor arity,
+ * and every exported type/const/helper stay EXACTLY as they were so no consumer (pg-pool.ts's
+ * central schema composition, store-backend.ts, test/pg-approval-store-integration.test.ts) has
+ * to move.
+ */
 export { PgApprovalStore, PG_APPROVAL_SCHEMA, ensureSchema, type ApprovalRow, type ApprovalStatus, } from "./approval-store-sql.js";
 //# sourceMappingURL=pg-approval-store.d.ts.map

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

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT alongside the TiDB twin). Class name, ctor arity,
+ * and every exported type/const/helper stay EXACTLY as they were so no consumer (pg-pool.ts's
+ * central schema composition, store-backend.ts, test/pg-approval-store-integration.test.ts) has
+ * to move.
+ */
 export { PgApprovalStore, PG_APPROVAL_SCHEMA, ensureSchema, } from "./approval-store-sql.js";
 //# sourceMappingURL=pg-approval-store.js.map

package/dist/plugins/pg-breaker-state.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./pg-breaker-state.js"` import (incl. pg-pool.ts's central ensureSchema
+ * composition and the real dual-DB integration suite) keeps working unchanged.
+ */
 export { PgBreakerState, PG_BREAKER_STATE_SCHEMA, ensureSchema } from "./breaker-state-sql.js";
 //# sourceMappingURL=pg-breaker-state.d.ts.map

package/dist/plugins/pg-breaker-state.js

@@ -1,2 +1,8 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./pg-breaker-state.js"` import (incl. pg-pool.ts's central ensureSchema
+ * composition and the real dual-DB integration suite) keeps working unchanged.
+ */
 export { PgBreakerState, PG_BREAKER_STATE_SCHEMA, ensureSchema } from "./breaker-state-sql.js";
 //# sourceMappingURL=pg-breaker-state.js.map

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

@@ -1,2 +1,10 @@
+/**
+ * PostgreSQL `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, `IS NOT DISTINCT FROM` + its placeholder-arity consequence, the lossless
+ * JSON envelope) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name and ctor shape unchanged.
+ */
 export { PgCheckpointStore } from "./checkpoint-store-sql.js";
 //# sourceMappingURL=pg-checkpoint-store.d.ts.map

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

@@ -1,2 +1,10 @@
+/**
+ * PostgreSQL `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, `IS NOT DISTINCT FROM` + its placeholder-arity consequence, the lossless
+ * JSON envelope) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name and ctor shape unchanged.
+ */
 export { PgCheckpointStore } from "./checkpoint-store-sql.js";
 //# sourceMappingURL=pg-checkpoint-store.js.map

package/dist/plugins/pg-cost-quota.d.ts

@@ -1,3 +1,16 @@
+/**
+ * PostgreSQL-backed cross-replica per-key CUMULATIVE cost quota — the PG twin of {@link TiDBCostQuota}
+ * (src/plugins/tidb-cost-quota.ts). Behaviourally identical (same {@link QuotaTracker} surface, same
+ * SOFT/eventual-consistency write-behind semantics: atomic `micro = micro + delta` per aligned window
+ * bucket), PostgreSQL dialect instead of MySQL/TiDB. The two are kept in lock-step by ONE shared real-DB
+ * integration suite (test/pg-cost-quota-integration.test.ts) running the SAME scenarios on BOTH engines.
+ *
+ * design/158 A12 C1b: this file used to carry a PRIVATE inline copy of the write-behind counter, hardwired
+ * to the `cost_quota` columns — the third copy of the same 150 lines. It is gone; both dialects now share
+ * ONE dialect-parameterized implementation (write-behind-counter.ts), and the dialect deltas this header
+ * used to enumerate ($n placeholders / ON CONFLICT increment / rowCount / BIGINT-as-string) are documented
+ * and branched THERE. Only the table binding lives here.
+ */
 import type { Pool, PoolClient } from "pg";
 import type { QuotaDecision, QuotaTracker } from "../observability/cost-quota.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
@@ -13,6 +26,10 @@ export declare class PgCostQuota implements QuotaTracker {
     startRefresh(intervalMs?: number): this;
     stop(): void;
 }
+/** 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 declare const PG_COST_QUOTA_SCHEMA: string[];
+/** Idempotent schema apply for the cost_quota table (the PG twin of tidb-pool.ts ensureSchema). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
 //# sourceMappingURL=pg-cost-quota.d.ts.map

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

@@ -1,4 +1,5 @@
 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" };
 export class PgCostQuota {
     limitMicroUsd;
@@ -15,6 +16,7 @@ export class PgCostQuota {
     add(scopeKey, micro) {
         this.counter.addLocal(scopeKey, micro);
     }
+    // write-behind lifecycle (delegated; exposed for the reaper/tests)
     flush() {
         return this.counter.flush();
     }
@@ -32,6 +34,9 @@ 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) NOT NULL,
@@ -42,6 +47,7 @@ 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-file-snapshot-store.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场) — the real implementation collapsed into
+ * `file-snapshot-store-sql.ts` (single file, dual dialect). Kept so every existing import path
+ * (store-backend.ts, the migration script, the contract/integration/minio-equivalence suites) is
+ * untouched: same class name, same ctor arity, same exported surface.
+ */
 export { PgFileSnapshotStore } from "./file-snapshot-store-sql.js";
 //# sourceMappingURL=pg-file-snapshot-store.d.ts.map

package/dist/plugins/pg-file-snapshot-store.js

@@ -1,2 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场) — the real implementation collapsed into
+ * `file-snapshot-store-sql.ts` (single file, dual dialect). Kept so every existing import path
+ * (store-backend.ts, the migration script, the contract/integration/minio-equivalence suites) is
+ * untouched: same class name, same ctor arity, same exported surface.
+ */
 export { PgFileSnapshotStore } from "./file-snapshot-store-sql.js";
 //# sourceMappingURL=pg-file-snapshot-store.js.map

package/dist/plugins/pg-image-bake.d.ts

@@ -1,3 +1,12 @@
+/**
+ * PostgreSQL BAKE store — the implementation now lives in the single-file dual-dialect
+ * `image-bake-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, jsonb casts, the admission-statement divergence, the PG-only
+ * protocol-byte defenses) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name, ctor shape, `PG_IMAGE_BAKE_SCHEMA` and
+ * `ensureSchema` are unchanged, so pg-pool.ts / store-backend.ts / the integration suite are untouched.
+ */
 export { PgImageBake, PG_IMAGE_BAKE_SCHEMA, ensurePgImageBakeSchema as ensureSchema } from "./image-bake-store-sql.js";
 export type { BakeStatus, BakeState, BakeErrorCode, BakeRecord, BakeEvent, CreateBakeInput, BakeTerminal, } from "./store-contracts.js";
 //# sourceMappingURL=pg-image-bake.d.ts.map

package/dist/plugins/pg-image-bake.js

@@ -1,2 +1,11 @@
+/**
+ * PostgreSQL BAKE store — the implementation now lives in the single-file dual-dialect
+ * `image-bake-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, jsonb casts, the admission-statement divergence, the PG-only
+ * protocol-byte defenses) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name, ctor shape, `PG_IMAGE_BAKE_SCHEMA` and
+ * `ensureSchema` are unchanged, so pg-pool.ts / store-backend.ts / the integration suite are untouched.
+ */
 export { PgImageBake, PG_IMAGE_BAKE_SCHEMA, ensurePgImageBakeSchema as ensureSchema } from "./image-bake-store-sql.js";
 //# sourceMappingURL=pg-image-bake.js.map

package/dist/plugins/pg-image-index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * PostgreSQL-backed sandbox-image-pool INDEX store — the PG twin of {@link TiDBImageIndex}
+ * (src/plugins/tidb-image-index.ts).
+ *
+ * Thin re-export shim (design/158 A12 定型半场): the real implementation is the single-file dual-dialect
+ * `image-index-sql.ts` (`SqlImageIndex` + this file's `PgImageIndex` ctor subclass). Class name, ctor
+ * arity, and the exported type/schema surface are UNCHANGED — every consumer (store-backend.ts, pg-pool.ts,
+ * the real-DB integration suite) imports from here exactly as before.
+ */
 export { PgImageIndex, PG_IMAGE_INDEX_SCHEMA, ensureSchema } from "./image-index-sql.js";
 export type { ImageNestedBuildMode, ImageCapabilities, ImagePodContract, ImageStatus, ImageVisibility, ImageIndexEntry, ImageIndexUpsert, ImageViewer, ImageListFilter, } from "./store-contracts.js";
 //# sourceMappingURL=pg-image-index.d.ts.map

package/dist/plugins/pg-image-index.js

@@ -1,2 +1,11 @@
+/**
+ * PostgreSQL-backed sandbox-image-pool INDEX store — the PG twin of {@link TiDBImageIndex}
+ * (src/plugins/tidb-image-index.ts).
+ *
+ * Thin re-export shim (design/158 A12 定型半场): the real implementation is the single-file dual-dialect
+ * `image-index-sql.ts` (`SqlImageIndex` + this file's `PgImageIndex` ctor subclass). Class name, ctor
+ * arity, and the exported type/schema surface are UNCHANGED — every consumer (store-backend.ts, pg-pool.ts,
+ * the real-DB integration suite) imports from here exactly as before.
+ */
 export { PgImageIndex, PG_IMAGE_INDEX_SCHEMA, ensureSchema } from "./image-index-sql.js";
 //# sourceMappingURL=pg-image-index.js.map

package/dist/plugins/pg-outcome-ledger.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 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";
 export type { TaskOutcome, RunStatus } from "./outcome-ledger-sql.js";
 //# sourceMappingURL=pg-outcome-ledger.d.ts.map