@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/sql-driver.d.ts

@@ -1,7 +1,79 @@
+/**
+ * Backend-NEUTRAL SQL exec/transaction seam for the "single-file dual-dialect" store collapses
+ * (design/158 A12 定型半场). Sibling of `sql-escape.ts` / `sql-row-helpers.ts` / `store-contracts.ts`:
+ * a leaf module with ZERO store logic, so a collapsed pair never has to load the other dialect's
+ * adapter to reach a driver call.
+ *
+ * What it normalizes (and ONLY this):
+ *   - `query(sql, params)` → `{ rows, affected }` — the two drivers disagree on the RESULT shape
+ *     (mysql2 `[rowsOrHeader, fields]` + `ResultSetHeader.affectedRows`; node-pg `{rows, rowCount}`).
+ *   - transaction control verbs — mysql2 has NATIVE `beginTransaction/commit/rollback` methods while
+ *     node-pg issues them as statements. Call-shape matters (the fake-pool unit suites script the
+ *     `query` calls IN ORDER), so the seam keeps each engine on its historical verb form.
+ *
+ * What it deliberately does NOT normalize (the A12 判据 — 方言差异必须显式):
+ *   - SQL TEXT: placeholders (`?` vs `$n`), `ON DUPLICATE KEY UPDATE` vs `ON CONFLICT … DO UPDATE`,
+ *     `CAST(? AS JSON)` vs `$n::jsonb`, `INSERT IGNORE` vs `ON CONFLICT DO NOTHING`, `<=>` vs
+ *     `IS NOT DISTINCT FROM`, VARBINARY vs `COLLATE "C"` — every one of these stays written out at
+ *     the call site so a reader sees BOTH statements side by side (the real-DB suites are the oracle).
+ *   - error classification: `ER_DUP_ENTRY`/errno 1062 vs SQLSTATE `23505`, and WHICH unique key
+ *     collided (mysql2 `sqlMessage` text vs pg `err.constraint`) — those live with the store that
+ *     needs them, because the discrimination rule is store-specific, not driver-generic.
+ *   - per-query timeouts: mysql2 takes `{sql, timeout}` while node-pg takes a `QueryConfig` with
+ *     `query_timeout`. The counter family (write-behind-counter.ts) needs those and keeps its own
+ *     exec; this seam stays on the plain (sql, params) form.
+ *
+ * `beginPessimistic()` is TiDB's `BEGIN PESSIMISTIC` (a CURRENT read for the FOR UPDATE admission
+ * check — a snapshot read would double-admit) and a plain `BEGIN` on PG (READ COMMITTED already
+ * reads the latest committed row under the sentinel lock). It is a NAMED verb precisely so the
+ * divergence is visible rather than hidden inside `begin()`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * REPLICATION PLAYBOOK — collapsing the remaining tidb-/pg- twin pairs (design/158 A12)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * Reference collapses: image-bake-store-sql.ts (class + transactions) and checkpoint-store-sql.ts
+ * (class, no transactions). Function-style stores follow task-list-store-sql.ts instead (inline
+ * `dialect === "tidb" ? … : …` ternaries, no driver object) — pick the shape the pair already has.
+ *
+ * STEPS
+ *  1. Read BOTH twins end to end first. List every method and mark it identical / SQL-text-only /
+ *     genuinely-divergent-algorithm. Do not start editing before that list exists.
+ *  2. New file `<name>-store-sql.ts`. Move the WHOLE implementation into a `Sql<Name>` class (or
+ *     `createSql<Name>` fn) taking a `SqlDriver`. Keep every doc comment — merge the two headers,
+ *     never drop the longer twin's rationale.
+ *  3. Per statement, write BOTH texts at the call site via a 2-arg `q(tidbSql, pgSql)` helper.
+ *     Never build one text with a placeholder-numbering loop — the point is that a reviewer sees
+ *     the two statements adjacent.
+ *  4. Genuinely-divergent algorithms get an `if (dialect === "tidb") { … } else { … }` block with a
+ *     🔴 comment saying WHY both are correct. Never "unify" them by picking one engine's algorithm.
+ *  5. Old files become thin re-export shims. Class names, ctor arity, exported constants/types and
+ *     helper names stay EXACTLY as they were — consumers and tests must not move.
+ *  6. Subclass bindings at the bottom: `class TiDB<X> extends Sql<X> { ctor(pool: MySqlPool, …) }`
+ *     and `class Pg<X> extends Sql<X> { ctor(pool: PgPool, …) }`.
+ *  7. Verify: `npm run typecheck` → the pair's unit suites → a HEAD-vs-new SQL parity harness (drive
+ *     every method on a recording fake pool for both dialects and diff the (sql, params) sequence;
+ *     `git show HEAD:<file>` into a temp `__head_*.ts` sibling, delete it after) → the env-gated
+ *     real dual-DB suite before release. Never trust a comment-level review for SQL text.
+ *
+ * WHAT MUST STAY EXPLICIT (never parameterized away)
+ *   placeholders (?/$n) · upsert form (ON DUPLICATE vs ON CONFLICT) · JSON casts (CAST(? AS JSON) /
+ *   $n::jsonb) · null-safe compare (<=> vs IS NOT DISTINCT FROM) AND its placeholder-arity fallout ·
+ *   key-column byte semantics (VARBINARY vs COLLATE "C") · isolation/txn verbs · error classification
+ *   (ER_DUP_ENTRY/errno vs SQLSTATE, sqlMessage vs err.constraint) · PG-only protocol-byte handling
+ *   (pgSafeJsonStringify / pgProtocolJsonStringify / pgSanitizeText / pgHasUnstorable) · DDL.
+ *
+ * WHAT MAY BE PARAMETERIZED
+ *   result unwrapping (rows/affected) · transaction plumbing · numeric coercion of BIGINT-as-string
+ *   (`Number(...)` is already dialect-safe) · row→record mappers, column lists, pure predicates and
+ *   validation (those belong in store-contracts.ts / sql-row-helpers.ts / sql-escape.ts) · table
+ *   bindings (`{table, keyCol, valCol}`) when the generated text is byte-identical to the old literal
+ *   — prove that with the parity harness, don't assume it.
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 export type SqlDialect = "tidb" | "pg";
 export type SqlRow = Record<string, unknown>;
+/** Normalized statement result: `rows` for SELECTs, `affected` for INSERT/UPDATE/DELETE. */
 export interface SqlResult {
     rows: SqlRow[];
     affected: number;
@@ -9,8 +81,10 @@ export interface SqlResult {
 export interface SqlExec {
     query(sql: string, params?: unknown[]): Promise<SqlResult>;
 }
+/** A pooled connection with transaction control (released by the caller in a `finally`). */
 export interface SqlTxConn extends SqlExec {
     begin(): Promise<void>;
+    /** TiDB: `BEGIN PESSIMISTIC` (current-read txn). PG: plain `BEGIN`. */
     beginPessimistic(): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
@@ -20,6 +94,9 @@ export interface SqlDriver extends SqlExec {
     readonly dialect: SqlDialect;
     connect(): Promise<SqlTxConn>;
 }
+/** MySQL-protocol (TiDB) driver. Transaction control uses mysql2's NATIVE methods — the historical
+ *  call shape the fake-pool unit suites script around. */
 export declare function mysqlDriver(pool: MySqlPool): SqlDriver;
+/** PostgreSQL driver. Transaction control is issued as STATEMENTS (node-pg has no native verbs). */
 export declare function pgDriver(pool: PgPool): SqlDriver;
 //# sourceMappingURL=sql-driver.d.ts.map

package/dist/plugins/sql-driver.js

@@ -1,3 +1,4 @@
+/** mysql2 hands back `[rows]` for a SELECT and `[ResultSetHeader]` for a write. */
 function mysqlResult(r) {
     if (Array.isArray(r))
         return { rows: r, affected: 0 };
@@ -8,6 +9,8 @@ async function mysqlQuery(q, sql, params) {
     const [r] = (await q.query(sql, params ?? []));
     return mysqlResult(r);
 }
+/** MySQL-protocol (TiDB) driver. Transaction control uses mysql2's NATIVE methods — the historical
+ *  call shape the fake-pool unit suites script around. */
 export function mysqlDriver(pool) {
     return {
         dialect: "tidb",
@@ -31,6 +34,7 @@ async function pgQuery(q, sql, params) {
     const res = await q.query(sql, params ?? []);
     return { rows: (res.rows ?? []), affected: res.rowCount ?? 0 };
 }
+/** PostgreSQL driver. Transaction control is issued as STATEMENTS (node-pg has no native verbs). */
 export function pgDriver(pool) {
     return {
         dialect: "pg",

package/dist/plugins/sql-escape.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Backend-NEUTRAL SQL string escaping (design/158 A3 沉底).
+ *
+ * Lives in its own leaf so no adapter has to load another dialect's adapter module to get a pure
+ * string transform (the PG stores used to runtime-import the TiDB tool-result store for exactly
+ * this one function). Zero dialect deps by construction — keep it that way.
+ */
+/** Escape SQL LIKE metacharacters (`\`, `%`, `_`) so a value is matched literally (default `\` escape char). */
 export declare function escapeLike(s: string): string;
 //# sourceMappingURL=sql-escape.d.ts.map

package/dist/plugins/sql-escape.js

@@ -1,3 +1,11 @@
+/**
+ * Backend-NEUTRAL SQL string escaping (design/158 A3 沉底).
+ *
+ * Lives in its own leaf so no adapter has to load another dialect's adapter module to get a pure
+ * string transform (the PG stores used to runtime-import the TiDB tool-result store for exactly
+ * this one function). Zero dialect deps by construction — keep it that way.
+ */
+/** Escape SQL LIKE metacharacters (`\`, `%`, `_`) so a value is matched literally (default `\` escape char). */
 export function escapeLike(s) {
     return s.replace(/[\\%_]/g, (ch) => `\\${ch}`);
 }

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

@@ -1,7 +1,32 @@
+/**
+ * Shared pure row-mapping helpers for the SQL store twins (design/158 S8 纯 helper 归位).
+ *
+ * These were duplicated verbatim across the pg-/tidb- store twin pairs; each store imports the flavor
+ * it was written against (usually under its historical local alias, e.g. `parseJsonStrict as
+ * parseJson`) so call sites and semantics are byte-identical to before.
+ *
+ * THREE parseJson flavors exist ON PURPOSE — they differ in what a corrupted/legacy JSON column
+ * reads back as (lenient → null / strict → throw / fallback value), and the TWO nullable date→ISO
+ * helpers differ in how a non-Date cell is rendered (String() passthrough vs `new Date()` re-parse).
+ * Do NOT collapse them into one.
+ */
+/** JSON column → value; a corrupted/legacy JSON column reads back as `null` instead of failing the
+ *  read. Non-strings pass through (node-pg parses jsonb → object already). */
 export declare function parseJsonLenient<T>(v: unknown): T | null;
+/** JSON column → value; malformed JSON THROWS. For stores whose write arm keeps the column clean
+ *  (R7 终形:协议面拒绝式,库内恒干净,直读). Non-strings pass through (node-pg parses jsonb →
+ *  object already). */
 export declare function parseJsonStrict<T>(v: unknown): T | null;
+/** JSON column → value with a caller-supplied fallback for NULL/corrupted cells. Non-strings pass
+ *  through (node-pg parses jsonb → object already; tolerate a string just in case). */
 export declare function parseJsonOr<T>(v: unknown, fallback: T): T;
+/** NOT NULL datetime column → ISO string (drivers return Date; a string cell passes through via
+ *  String() — NOT re-parsed). */
 export declare function toIso(v: unknown): string;
+/** Nullable twin of {@link toIso} (string cells still pass through verbatim). */
 export declare function toIsoOrNull(v: unknown): string | null;
+/** Nullable datetime column → ISO string, RE-PARSING a string cell via `new Date()` (normalizes a
+ *  raw DB datetime string like "2026-01-01 00:00:00" to ISO — unlike {@link toIsoOrNull}, which
+ *  passes it through unchanged). */
 export declare function normalizeIsoOrNull(v: unknown): string | null;
 //# sourceMappingURL=sql-row-helpers.d.ts.map

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

@@ -1,3 +1,17 @@
+/**
+ * Shared pure row-mapping helpers for the SQL store twins (design/158 S8 纯 helper 归位).
+ *
+ * These were duplicated verbatim across the pg-/tidb- store twin pairs; each store imports the flavor
+ * it was written against (usually under its historical local alias, e.g. `parseJsonStrict as
+ * parseJson`) so call sites and semantics are byte-identical to before.
+ *
+ * THREE parseJson flavors exist ON PURPOSE — they differ in what a corrupted/legacy JSON column
+ * reads back as (lenient → null / strict → throw / fallback value), and the TWO nullable date→ISO
+ * helpers differ in how a non-Date cell is rendered (String() passthrough vs `new Date()` re-parse).
+ * Do NOT collapse them into one.
+ */
+/** JSON column → value; a corrupted/legacy JSON column reads back as `null` instead of failing the
+ *  read. Non-strings pass through (node-pg parses jsonb → object already). */
 export function parseJsonLenient(v) {
     if (v == null)
         return null;
@@ -10,11 +24,16 @@ export function parseJsonLenient(v) {
         return null;
     }
 }
+/** JSON column → value; malformed JSON THROWS. For stores whose write arm keeps the column clean
+ *  (R7 终形:协议面拒绝式,库内恒干净,直读). Non-strings pass through (node-pg parses jsonb →
+ *  object already). */
 export function parseJsonStrict(v) {
     if (v == null)
         return null;
     return (typeof v === "string" ? JSON.parse(v) : v);
 }
+/** JSON column → value with a caller-supplied fallback for NULL/corrupted cells. Non-strings pass
+ *  through (node-pg parses jsonb → object already; tolerate a string just in case). */
 export function parseJsonOr(v, fallback) {
     if (v == null)
         return fallback;
@@ -27,14 +46,20 @@ export function parseJsonOr(v, fallback) {
         return fallback;
     }
 }
+/** NOT NULL datetime column → ISO string (drivers return Date; a string cell passes through via
+ *  String() — NOT re-parsed). */
 export function toIso(v) {
     return v instanceof Date ? v.toISOString() : String(v);
 }
+/** Nullable twin of {@link toIso} (string cells still pass through verbatim). */
 export function toIsoOrNull(v) {
     if (v == null)
         return null;
     return v instanceof Date ? v.toISOString() : String(v);
 }
+/** Nullable datetime column → ISO string, RE-PARSING a string cell via `new Date()` (normalizes a
+ *  raw DB datetime string like "2026-01-01 00:00:00" to ISO — unlike {@link toIsoOrNull}, which
+ *  passes it through unchanged). */
 export function normalizeIsoOrNull(v) {
     if (v == null)
         return null;

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

@@ -30,16 +30,41 @@ import { TiDBRateLimiter } from "./tidb-rate-limiter.js";
 import type { CounterDegradeHook } from "./write-behind-counter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
 export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
+/** E18 resume-at eventId→entryId anchor map — tidb/pg/local 3-backend (works LOCAL; needs only the session tree +
+ *  this map, no cloud-only checkpoint). Union = the three nominal twins; consumers use put/resolve/deleteBySession.
+ *  FileResumeAnchorStore is the FILE-backed local twin (P0.5 variant-1; survives restart). */
 export type ResumeAnchorStore = TiDBResumeAnchorStore | PgResumeAnchorStore | FileResumeAnchorStore;
 export type { ApprovalExemptionStore } from "./approval-exemption-store.js";
+/** E6 SessionPolicyStore — core's interface PLUS the service `deleteBySession` (E21 purge; only the durable twins carry
+ *  it, core's InMemory omits it → optional). tidb/pg = durable twins; local = core's InMemorySessionPolicyStore (works
+ *  local — rules need no cloud-only infra). The shared env-gated equivalence suite keeps the twins byte-matched to InMemory. */
 export type ServiceSessionPolicyStore = SessionPolicyStore;
+/** E19 rewind-files FileSnapshotStore — core's interface PLUS the service `deleteBySession` (E21 purge; the durable
+ *  twins carry it, core's InMemory omits it → optional). tidb/pg = durable twins (manifest+blobs, reuse core
+ *  captureManifest/applyManifest); local = core's FileFileSnapshotStore(file-backed content-addressed,跨重启
+ *  存活——接入审计 L6 订正:旧注释写 InMemory 会误导 local 快照持久性判断). Also the 2c work-artifact transfer store. */
 export type ServiceFileSnapshotStore = FileSnapshotStore & {
+    /** [805]③a observability tail (SQL twins only — core's local stores drop the count internally, a core-side
+     *  gap): captureManifest's tolerated-vanished counter → metric sink, assigned by main.ts when present.
+     *  codex F8: async sinks admitted; the twins swallow a rejected promise (never-throw seam holds). */
     onSkippedVanished?: (count: number) => void | Promise<void>;
     deleteBySession?(scope: string): Promise<number>;
+    /** 2c session-sync DoS bound — GLOBALLY GC grace-window orphan blobs (standalone PUTs never imported, plus the
+     *  blobs reap()/deleteBySession() left orphaned — byte deletion is ASYNC, never on the sync purge path). The durable
+     *  twins carry it (scheduled by the main.ts reaper, error-tolerant → eventual consistency); core's InMemory omits it. */
     sweepOrphanBlobs?(): Promise<number>;
+    /** The subset of `hashes` already present — a cheap SQL INDEX probe (BOTH backends). Used by the §10 import
+     *  blob-presence pre-check (a HEAD/index check, NOT N full getBlob GETs). The durable twins carry it; optional. */
     hasBlobs?(hashes: string[]): Promise<Set<string>>;
 };
+/** SVC-2 (core CORE-7) WorkflowJournalStore — core's interface PLUS the service `deleteByRun` (GC extra). tidb/pg =
+ *  durable SQL twins (cross-replica resume journal); local = the service {@link FileWorkflowJournalStore}
+ *  (single-box but RESTART-durable crash-safe JSONL, replacing core's InMemory). The shared equivalence suite keeps
+ *  all three byte-matched (scope guard / idempotent-per-ordinal / oversize skip-journal). */
 export type ServiceWorkflowJournalStore = WorkflowJournalStore & {
+    /** codex R1-H2(journal 读面界):分页+单行字节门的投影读——SQL 端 LIMIT/OFFSET 定行数、LENGTH 门
+     *  定单行(超 maxResultBytes 的行 resultJson=null 只回 resultBytes,读面标 truncated)。HTTP 读面
+     *  优先走此面;缺席(旧实现/in-memory)回落全量 load(元素少的店可受)。 */
     loadPage?(runId: string, scope: string, opts: {
         offset: number;
         limit: number;
@@ -50,34 +75,82 @@ export type ServiceWorkflowJournalStore = WorkflowJournalStore & {
         resultBytes: number;
     }>>;
     deleteByRun?(runId: string): Promise<number>;
+    /** SVC-2 GC sweep (durable twins only): purge entries older than `maxAgeMs` — wired into the reaper to bound the
+     *  TaskResult-bearing table (the per-run deleteByRun has no run-store reap hook). Local InMemory omits it. */
     reapExpired?(now: number, maxAgeMs: number): Promise<number>;
 };
 export type ApprovalStore = TiDBApprovalStore | PgApprovalStore;
 export type ImageIndex = TiDBImageIndex | PgImageIndex;
 export type ImageBake = TiDBImageBake | PgImageBake;
+/** The FULL checkpoint store (core CheckpointStore + the service operator-queue/ctx methods listPending/
+ *  listByScope/findPendingTokenBySession/peekPendingScope/putCtx/getCtx/reapCtx) — the SQL twins carry them,
+ *  and the LOCAL lane now does too (core FileCheckpointStore + the service half — TOC plan-mode /
+ *  durable HITL work on one box). */
 export type CheckpointStoreFull = TiDBCheckpointStore | PgCheckpointStore | LocalCheckpointStore;
+/** The full tool-result store: core `ToolResultStore` + the service maintenance extras. The SQL twins carry
+ *  both extras; the LOCAL lane returns core's `FileToolResultStore` (core 1.219 — durable across a
+ *  process restart, the TOC "ReadToolResult(ref) 恒空" fix) which carries NEITHER — consumers must optional-call
+ *  (`store.reapOlderThan?.()`). Structural (not a nominal union) so all three backends flow through one seam. */
 export type ToolResultStoreFull = ToolResultStore & {
+    /** TTL sweep (SQL twins only): purge rows older than the cutoff. Local file store omits it (CC posture:
+     *  a single user's tool-result files persist like transcripts; bounded by being text previews). */
     reapOlderThan?(cutoffMs: number): Promise<number>;
+    /** E21 purge (SQL twins only): delete `tr_<sessionId>_%` refs when a session is purged. */
     deleteBySession?(sessionId: string): Promise<number>;
 };
+/** Cross-replica counter twins expose the write-behind lifecycle (startRefresh/stop) main.ts drives. */
 export type BreakerStateStore = TiDBBreakerState | PgBreakerState;
 export type CostQuotaStore = TiDBCostQuota | PgCostQuota;
 export type RateLimiterStore = TiDBRateLimiter | PgRateLimiter;
 export interface StoreBackend {
+    /** Protocol-truth kind (clay 2026-07-06 wording): "mysql" = any MySQL-protocol server (MySQL / TiDB /
+     *  MariaDB) behind the one mysql2 pool — the startup summary prints durable(mysql) for all of them. */
     readonly kind: "mysql" | "pg" | "local";
+    /** Connect + create schema (also the reachability probe). */
     ensureSchema(): Promise<void>;
     close(): Promise<void>;
     run(): RunStore;
+    /** E18 resume-at eventId→entryId map. REQUIRED on all backends (works local — needs only the session tree + this
+     *  map, no cloud-only checkpoint), unlike the optional cloud-only stores below. */
     resumeAnchor(): ResumeAnchorStore;
+    /** Per-session per-toolName approval exemption ("本会话不再询问") — an approval MEMORY the F4
+     *  ask-gate consults after deny/neverAuto. REQUIRED on all backends (works local, like resumeAnchor). */
     approvalExemption(): ApprovalExemptionStore;
+    /** SendUserFile scope↔object ledger (multi-tenant list/revoke handle; the hashed key segment hides the
+     *  mapping from URLs). REQUIRED on all backends (works local — one JSONL, like approvalExemption). */
     sendFileLedger(): SendFileLedger;
+    /** E6 durable SessionPolicyStore (operator-tightened per-session tool rules). REQUIRED on all backends — works local
+     *  (local = core's InMemorySessionPolicyStore), like resumeAnchor. Backs core's RunnerDeps.sessionPolicyStore. */
     sessionPolicy(): ServiceSessionPolicyStore;
+    /** E19 rewind-files FileSnapshotStore (working-tree snapshot/restore keyed by entryId; also the 2c artifact-transfer
+     *  store). REQUIRED on all backends (local = core's InMemoryFileSnapshotStore). Backs core's RunnerDeps.fileSnapshotStore. */
     fileSnapshot(): ServiceFileSnapshotStore;
+    /** SVC-2 (core CORE-7) durable WorkflowJournalStore — the cross-replica resume journal for an LLM-authored workflow
+     *  (RunWorkflowOptions.journalStore). REQUIRED on all backends (tidb/pg = durable twins; local = core's
+     *  InMemoryWorkflowJournalStore, single-replica/in-process).
+     *
+     *  ✅ WIRED (was "NOT YET WIRABLE, as of core 1.144.0" — that claim went STALE and sat here misleading readers
+     *  until a 2026-07-25 doc-rot sweep caught it). core 1.145.0 added the seam this comment was waiting for:
+     *  `RunnerDeps.workflowJournalStore` (now `@sema-agent/core` `dist/core/types.d.ts:708`) + `journalStore` on the
+     *  run_workflow tool deps (`dist/orchestration/run-workflow-tool.d.ts:65`), and main.ts consumes it end-to-end:
+     *  built at §run_workflow mount (`main.ts:1349`), threaded into RunnerDeps (`main.ts:1636`), reaped on the
+     *  maintenance tick (`main.ts:2399`), and read by `GET /v1/workflows/:id/journal` (`main.ts:3077`, [1402]). */
     workflowJournal(): ServiceWorkflowJournalStore;
+    /** design/73 §1 consumption sink for `RunnerDeps.onTaskOutcome` facts. REQUIRED on all backends:
+     *  tidb/pg = the outcome-ledger twins (SQL rows, mapped via coreOutcomeToLedgerRow + verbatim core_outcome
+     *  JSON); local = an owner-only JSONL File sink. Read-only v1 — records facts, drives no policy. */
     outcomeSink(): OutcomeSink;
+    /** P1 (fleet failover): durable cross-replica WorkflowRunStore + completion-inbox twins. OPTIONAL —
+     *  SQL backends only (local keeps the File pair: single box, no cross-replica surface). main.ts prefers
+     *  these under WORKFLOW_RUN_STORE=auto (the default). */
     workflowRun?(): import("@sema-agent/core").WorkflowRunStore;
     completionInbox?(onWarn?: InboxWarn): import("../orchestration/workflow-completion-inbox.js").WorkflowCompletionInbox;
+    /** 1.108 review fix (lens③ HIGH): the notify-JOURNAL twin — third leg of the same axis (a SQL run store +
+     *  inbox with a replica-LOCAL File journal stranded a dead replica's un-acked notify forever). */
     notifyJournal?(): import("../orchestration/workflow-notify-journal.js").WorkflowNotifyJournalStore;
+    /** Cloud-only stores below are OPTIONAL: the `local` (in-memory/file) backend omits them (it has no core
+     *  in-memory twin carrying the service extras, and these are fleet/multi-replica concepts), so a local HTTP
+     *  service degrades EXACTLY like today's no-DB env (the consumers gate on `backend?.X?.()`). TiDB/PG provide all. */
     checkpoint?(logger?: {
         info?(msg: string, meta?: unknown): void;
     }): CheckpointStoreFull;
@@ -88,14 +161,44 @@ export interface StoreBackend {
     breaker?(onWriteFail?: (streak: number) => void): BreakerStateStore;
     costQuota?(limitMicroUsd: number, windowMs: number, onDegraded?: CounterDegradeHook): CostQuotaStore;
     rateLimiter?(limit: number, onDegraded?: CounterDegradeHook): RateLimiterStore;
+    /** Session store (caller wraps caching). DB-backed on tidb/pg; the in-memory/file `LocalSessionStore` on local. */
     session(): SessionStore;
+    /** The raw mysql2 pool — ONLY on the TiDB backend (undefined on PG). For the few TiDB-specific raw-SQL
+     *  consumers outside the store abstraction (session audit, degenerate-output instrument); those features are
+     *  no-ops on PG until ported. */
     mysqlPool(): MysqlPool | undefined;
+    /** S3-TOB(设计 §1.4):the raw PG pool for the memory-engine DB backend's PgQueryFn binding (mirror of
+     *  mysqlPool). undefined on non-PG backends. */
     pgPool(): PgPool | undefined;
+    /** S10 (SILENT-FALLBACK P1): the DB server's wall clock in epoch ms — the reaper probes it against the local
+     *  clock to expose replica clock skew (the write-behind counters bucket on LOCAL floor(now/windowMs); skew
+     *  splits a fleet window into disjoint buckets = soft-limit leak). OPTIONAL: local backend omits (no fleet). */
     dbNowMs?(): Promise<number>;
 }
+/** (c)(clay 拍 a+c,2026-07-27)云形快照 blob 姿势门——boot 时调用(main.ts),纯函数可单测。
+ *  SQL 后端(mysql|pg)把 blob 字节落 `snapshot_blob` 单行的形已被两役实证撞 mysql-协议包墙
+ *  (D-1 附件 → 对象存储裁定;snapshot_blob >31MiB 同墙):大字节归对象存储。云形缺 MinIO ⇒
+ *  fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` = 显式接受 SQL 店 +
+ *  per-blob 帽(单机/测试台形)。local 后端不经此门(file/in-memory 快照店,无 SQL 包墙)。 */
 export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "local", config: Pick<ServiceConfig, "snapshotBlobStore" | "snapshotBlobAllowSql">): void;
+/** REWIND_SNAPSHOT_MAX_MB overrides ONLY the byte cap of core's DEFAULT_SNAPSHOT_BOUNDS (raise for
+ *  big monorepos, lower for tight DBs). File-count / ignoreDirs stay core defaults — the knob answers the one
+ *  field the 20G-workspace case needed; more knobs when a case shows up. Exported for tests
+ *  (fractional-MB rounding + partial-merge semantics need a regression lock). */
 export declare function snapshotBoundsFromConfig(config: ServiceConfig): FileSnapshotBounds;
+/** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
+ *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
 export declare function createStoreBackend(config: ServiceConfig): StoreBackend | undefined;
+/** boot 期打开 store 后端的**统一入口**:构造 + ensureSchema 同罩一层降级臂。
+ *
+ *  为什么必须把 `createStoreBackend()` 也罩进来(2026-07-28 修):clay 1.292 拍的口径是「裸 boot
+ *  **默认推导**的 local 在只读文件系统/mkdir 失败时不得拒启」,但原先 try 只罩 `ensureSchema()`——
+ *  而 LocalBackend 的 `ensureSchema` 是**空实现**,真正会抛的 mkdir + 数据根 BootLock 在构造函数里、
+ *  落在 try 之外。于是那条降级臂对 local 形从来没生效过,注释宣称的行为与代码真做的事撕裂。
+ *
+ *  降级条件不变(两形同一姿势):`sessionBackend=auto`(配置的 DB 不可达,S5 原形)或**默认推导**的
+ *  local(`dbBackend=local && !dbBackendExplicit`)。**显式** DB_BACKEND=local / tidb 仍 fail-loud——
+ *  operator 要了 durable,静默丢=丢数据。 */
 export declare function openStoreBackendWithFallback(config: ServiceConfig, logger: {
     warn: (msg: string, meta?: Record<string, unknown>) => void;
 }): Promise<{