@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/store-backend.js

@@ -1,11 +1,3 @@
-/**
- * Durable-store BACKEND seam (clay 2026-06-21 PG migration). One place that, given `config.dbBackend`, builds the
- * SQL pool (TiDB/MySQL via mysql2 OR PostgreSQL via pg) and constructs the right store TWIN for every durable
- * subsystem. main.ts wires through this instead of `new TiDB*(pool)` so `DB_BACKEND=pg` boots the whole service on
- * PG with zero call-site churn. The twins are interchangeable behaviourally (one shared real-DB integration suite
- * keeps them in lock-step); the unions below exist only because TS private fields make the concrete classes
- * nominally distinct (run/imageIndex/imageBake have no core interface — the rest implement one).
- */
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { AdoptionError, FileStorageBackend, FileSessionRepo, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
@@ -43,23 +35,13 @@ import { TiDBSessionStore } from "./tidb-session-store.js";
 import { PgSessionStore } from "./pg-session-storage.js";
 import { TiDBSharedMemoryStore, PgSharedMemoryStore } from "./shared-memory-store-sql.js";
 import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js";
-// #270:托管留存的两半场(破坏性三方法 = 车1;租约/hold/审计 = 车2)。SQL 后端专有,local 诚实缺席。
 import { TiDBRetentionStore, PgRetentionStore } from "./retention-store-sql.js";
 import { TiDBRetentionLaneStore, PgRetentionLaneStore } from "./retention-lane-store-sql.js";
-// #154 车二:持久化权限规则店(三面一束)。`mysqlDriver`/`pgDriver` 是既有的方言中立 seam。
-// #203 §1:local 车道的 File 三面束(core 现成 provider + 本仓 File 形审批记录/导入票)。
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
 import { createFilePermissionRuleStores } from "./permission-rule-store-file.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-/** Build the snapshot-BLOB object-store backend from config, or undefined to fall back to the SqlBlobBackend default.
- *  When `config.snapshotBlobStore` (MINIO_* env) is set, the E19/2c file-snapshot stores route ONLY the blob BYTES to
- *  MinIO; the MANIFEST stays in SQL (the transcript hot read never touches MinIO). The MinioBlobBackend is given the
- *  SAME pool+dialect so it keeps the bytes-NULL `snapshot_blob` INDEX in SQL (the orphan/grace reference-tracking +
- *  presence checks read it — see blob-backend.ts). Shared by the tidb + pg backends. */
 function snapshotBlobBackend(config, dialect, pool) {
     const s = config.snapshotBlobStore;
-    // (a): no MinIO ⇒ construct the SQL default EXPLICITLY so the per-blob cap (env override or the tidb
-    // packet-wall default) rides along — the stores' internal `?? new SqlBlobBackend(...)` fallback would lose it.
     if (!s)
         return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes);
     return new MinioBlobBackend({
@@ -72,11 +54,6 @@ function snapshotBlobBackend(config, dialect, pool) {
         ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
     }, { dialect, pool });
 }
-/** (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 function assertCloudSnapshotBlobPosture(kind, config) {
     if (kind === "local" || config.snapshotBlobStore || config.snapshotBlobAllowSql)
         return;
@@ -86,10 +63,6 @@ export function assertCloudSnapshotBlobPosture(kind, config) {
         "same ruling as the D-1 attachment store). Single-box/test rigs may explicitly opt out with " +
         "SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true (a per-blob cap then applies; oversized blobs are rejected 413).");
 }
-/** 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 function snapshotBoundsFromConfig(config) {
     const mb = config.rewindSnapshotMaxMb;
     return mb !== undefined ? { ...DEFAULT_SNAPSHOT_BOUNDS, maxBytes: Math.round(mb * 1024 * 1024) } : DEFAULT_SNAPSHOT_BOUNDS;
@@ -107,32 +80,32 @@ class TiDBBackend {
     run() { return new TiDBRunStore(this.pool); }
     resumeAnchor() { return new TiDBResumeAnchorStore(this.pool); }
     approvalExemption() { return new TiDBApprovalExemptionStore(this.pool); }
-    approvalAsk() { return new TiDBApprovalAskStore(this.pool); } // #151 流内审批协议持久层(无状态 store,每次新建同兄弟)
-    permissionRule() { return createSqlPermissionRuleStores(mysqlDriver(this.pool)); } // #154 车二 持久化权限规则店
+    approvalAsk() { return new TiDBApprovalAskStore(this.pool); }
+    permissionRule() { return createSqlPermissionRuleStores(mysqlDriver(this.pool)); }
     sendFileLedger() { return new TiDBSendFileLedger(this.pool); }
     sessionPolicy() { return new TiDBSessionPolicyStore(this.pool); }
     fileSnapshot() { return new TiDBFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "tidb", this.pool), snapshotBoundsFromConfig(this.config)); }
     workflowJournal() { return new TiDBWorkflowJournalStore(this.pool); }
-    outcomeSink() { return new TiDBOutcomeLedger(this.pool); } // design/73 §1→§7 bridge (recordCore)
-    workflowRun(onWarn) { return new TiDBWorkflowRunStore(this.pool, onWarn); } // P1: cross-replica workflow record(onWarn = C5 oversize-slim 留痕,completionInbox 同款先例)
-    completionInbox(onWarn) { return new TiDBWorkflowCompletionInbox(this.pool, onWarn); } // P1: cross-replica push half
-    notifyJournal() { return new TiDBWorkflowNotifyJournalStore(this.pool); } // 1.108: cross-replica at-least-once notify
-    sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); } // design/177 org 共享记忆库
+    outcomeSink() { return new TiDBOutcomeLedger(this.pool); }
+    workflowRun(onWarn) { return new TiDBWorkflowRunStore(this.pool, onWarn); }
+    completionInbox(onWarn) { return new TiDBWorkflowCompletionInbox(this.pool, onWarn); }
+    notifyJournal() { return new TiDBWorkflowNotifyJournalStore(this.pool); }
+    sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); }
     checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger); }
     toolResult() { return new TiDBToolResultStore(this.pool); }
     imageIndex() { return new TiDBImageIndex(this.pool); }
     imageBake() { return new TiDBImageBake(this.pool); }
-    leaderRun() { return new TiDBLeaderRunStore(this.pool); } // #193 车4 件1(无状态 store,每次新建同兄弟)
-    retention(opts) { return new TiDBRetentionStore(this.pool, opts); } // #270 车1(破坏性三方法)
-    retentionLane() { return new TiDBRetentionLaneStore(this.pool); } // #270 车2(租约/hold/审计,删不了业务数据)
+    leaderRun() { return new TiDBLeaderRunStore(this.pool); }
+    retention(opts) { return new TiDBRetentionStore(this.pool, opts); }
+    retentionLane() { return new TiDBRetentionLaneStore(this.pool); }
     breaker(onWriteFail) { return new TiDBBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new TiDBCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new TiDBRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     session() { return new TiDBSessionStore(this.pool); }
-    adoptionLog() { return new TiDBAdoptionLogStore(this.pool); } // design/183 form b 收编日志(无状态 store,每次新建同兄弟)
+    adoptionLog() { return new TiDBAdoptionLogStore(this.pool); }
     mysqlPool() { return this.pool; }
     pgPool() { return undefined; }
-    async dbNowMs() { const [rows] = await this.pool.query("SELECT ROUND(UNIX_TIMESTAMP(NOW(3))*1000) AS ms"); return Number(rows[0]?.ms); } // S10
+    async dbNowMs() { const [rows] = await this.pool.query("SELECT ROUND(UNIX_TIMESTAMP(NOW(3))*1000) AS ms"); return Number(rows[0]?.ms); }
 }
 class PgBackend {
     pool;
@@ -147,57 +120,33 @@ class PgBackend {
     run() { return new PgRunStore(this.pool); }
     resumeAnchor() { return new PgResumeAnchorStore(this.pool); }
     approvalExemption() { return new PgApprovalExemptionStore(this.pool); }
-    approvalAsk() { return new PgApprovalAskStore(this.pool); } // #151 流内审批协议持久层(SQL twin)
-    permissionRule() { return createSqlPermissionRuleStores(pgDriver(this.pool)); } // #154 车二 持久化权限规则店(SQL twin)
+    approvalAsk() { return new PgApprovalAskStore(this.pool); }
+    permissionRule() { return createSqlPermissionRuleStores(pgDriver(this.pool)); }
     sendFileLedger() { return new PgSendFileLedger(this.pool); }
     sessionPolicy() { return new PgSessionPolicyStore(this.pool); }
     fileSnapshot() { return new PgFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "pg", this.pool), snapshotBoundsFromConfig(this.config)); }
     workflowJournal() { return new PgWorkflowJournalStore(this.pool); }
-    outcomeSink() { return new PgOutcomeLedger(this.pool); } // design/73 §1→§7 bridge (recordCore)
-    workflowRun(onWarn) { return new PgWorkflowRunStore(this.pool, onWarn); } // P1: cross-replica workflow record(onWarn = C5 oversize-slim 留痕,completionInbox 同款先例)
-    completionInbox(onWarn) { return new PgWorkflowCompletionInbox(this.pool, onWarn); } // P1: cross-replica push half
-    notifyJournal() { return new PgWorkflowNotifyJournalStore(this.pool); } // 1.108: cross-replica at-least-once notify
-    sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); } // design/177 org 共享记忆库
+    outcomeSink() { return new PgOutcomeLedger(this.pool); }
+    workflowRun(onWarn) { return new PgWorkflowRunStore(this.pool, onWarn); }
+    completionInbox(onWarn) { return new PgWorkflowCompletionInbox(this.pool, onWarn); }
+    notifyJournal() { return new PgWorkflowNotifyJournalStore(this.pool); }
+    sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); }
     checkpoint(logger) { return new PgCheckpointStore(this.pool, logger); }
     toolResult() { return new PgToolResultStore(this.pool); }
     imageIndex() { return new PgImageIndex(this.pool); }
     imageBake() { return new PgImageBake(this.pool); }
-    leaderRun() { return new PgLeaderRunStore(this.pool); } // #193 车4 件1(SQL twin)
-    retention(opts) { return new PgRetentionStore(this.pool, opts); } // #270 车1(SQL twin)
-    retentionLane() { return new PgRetentionLaneStore(this.pool); } // #270 车2(SQL twin)
+    leaderRun() { return new PgLeaderRunStore(this.pool); }
+    retention(opts) { return new PgRetentionStore(this.pool, opts); }
+    retentionLane() { return new PgRetentionLaneStore(this.pool); }
     breaker(onWriteFail) { return new PgBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new PgCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new PgRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     session() { return new PgSessionStore(this.pool); }
-    adoptionLog() { return new PgAdoptionLogStore(this.pool); } // design/183 form b 收编日志(SQL twin)
+    adoptionLog() { return new PgAdoptionLogStore(this.pool); }
     mysqlPool() { return undefined; }
     pgPool() { return this.pool; }
-    async dbNowMs() { const res = await this.pool.query("SELECT ROUND(EXTRACT(EPOCH FROM now())*1000) AS ms"); return Number(res.rows[0]?.ms); } // S10
+    async dbNowMs() { const res = await this.pool.query("SELECT ROUND(EXTRACT(EPOCH FROM now())*1000) AS ms"); return Number(res.rows[0]?.ms); }
 }
-/**
- * LOCAL backend (clay 2026-06-25 seamless local↔cloud; P0.5 variant-2 + variant-1 file-backed 2026-06-26): a DB-less StoreBackend
- * so a locally-run HTTP service serves the SAME contract a cloud worker does (runs + trace + sessions + resume;
- * long-term memory rides the design/138 memory ENGINE, not this backend). Sessions / per-session policy / file snapshots are
- * FILE-BACKED via core's `FileStorageBackend` over `root`, so a session SURVIVES a process restart and the resume
- * picker (GET /v1/sessions → LocalSessionStore.listSessions) is restart-visible — the 2c "first local, then sync"
- * hard prerequisite.
- *
- * The session store stays the §0.5 owner-aware {@link LocalSessionStore} wrapper, but over a fresh `FileSessionRepo`
- * (NOT `fileBackend.sessionStore`, which is core's bare `TtlSessionStore` lacking the §0.5 owner/list/fork/delete
- * ops); policy/snapshot delegate to the fileBackend's own file stores. The fileBackend takes a coarse boot
- * single-instance lock on `root/LOCK` (an `O_EXCL`+`linkSync` PIDFILE, not flock — [2557] F4; same-host only:
- * liveness = `process.kill(pid,0)`, so a foreign PID namespace or NFS defeats it, see DEPLOY-PREREQS) —
- * `close()` MUST `dispose()` it so a graceful restart can
- * re-acquire (a stale lock from a dead PID is pruned by core, but graceful restart relies on the release).
- *
- * P0.5 variant-1 (clay 2026-06-26): `run()`/`resumeAnchor()` are now FILE-backed too (FileRunStore /
- * FileResumeAnchorStore over core 1.138.0's crash-safe fs primitives — atomicWriteFile/writeThenLink/AppendLog), so the
- * runs ledger + trace event log + E18 anchors SURVIVE a process restart, completing variant-2's promised follow-on. The
- * picker still lists from the session abstraction (variant-2), but a restart now also re-reads run history + resume
- * anchors. Owner identity is still process-local (single-user acceptable; durable owners = P1). The cloud-only stores
- * (checkpoint/approval/toolResult/imageIndex/imageBake/breaker/costQuota/rateLimiter) are OMITTED → the consumers'
- * `backend?.X?.()` gates degrade them exactly like a no-DB env.
- */
 class LocalBackend {
     kind = "local";
     fileBackend;
@@ -205,51 +154,19 @@ class LocalBackend {
     sessionStore;
     resumeAnchorStore;
     approvalExemptionStore;
-    /** #151 —— 进程内易失(见 approvalAsk() 的注);File 形落地前它就是 local 车道的占位。 */
     approvalAskStore = new InMemoryApprovalAskStore();
     sendFileLedgerStore;
-    // SVC-2: FILE-backed durable journal (was core's InMemory — a TOC restart silently resolved
-    // resumeFromRunId to an empty journal → full live re-run). Now restart-durable on one box; crash-safe JSONL,
-    // scope-guarded, oversize skip-journal — byte-matched degrade with the SQL twins. Singleton: fds live here.
     workflowJournalStore;
-    /** design/73 §1 — owner-only JSONL outcome-fact sink (stateless append; no fd held). */
     outcomeSinkInst;
-    /** boot 期的告警口(`openStoreBackendWithFallback` 把它接到 logger.warn 上)。可选:直接 `new` 一只
-     *  LocalBackend 的测试/工具不必装配日志面 —— 缺席时 core 的披露仍留在 core 那侧,只是本仓不复述。 */
     onWarn;
-    /** boot 期的 **error 级**口(F-D):`FileRunStore.hydrate` 的 readdir 失败按三处成文(本文件下方接线处 /
-     *  `fail-open.ts` 的 tag note / 普查表第 29 行)承诺的是 **error 级**披露,而 warn 座满足不了那句话 ——
-     *  按 `level >= error` 配告警的运维会一条都收不到。可选:缺席时退回 {@link onWarn}(降一级好过无声)。 */
     onError;
     constructor(root, config, onWarn, onError) {
         this.onWarn = onWarn;
         this.onError = onError;
-        // The fileBackend ctor mkdirs `root` + takes the boot pidfile lock — a same-host SECOND instance FAILS FAST.
-        // Re-throw with a clear operator message (the raw core error is "another instance owns this data dir").
-        //
-        // 🔴 core 5.23.0([3372] 提货批件④):这个构造器现在有**第二个**拒绝面 —— design/183 的 I6 adoption
-        // boot 门(`dist/stores/file/index.js:45` 的 `assertAdoptionBootGate`):数据根下 `adoption.json` 是
-        // 在飞标记 ⇒ `AdoptionError("adoption_in_flight")`,标记读不出 ⇒ `"adoption_marker_corrupt"`。
-        // 原来的 catch 是 **catch-all**,会把它一并改写成下面那句 boot-lock 文案 —— 那是**误诊**:它给的两条
-        // 出路对 adoption 在飞都不对,而「把 LOCAL_DATA_ROOT 指到一个空目录」更是直接劝运维**丢下一个迁移
-        // 到一半的数据根**;`AdoptionError` 的类型身份与 typed `code` 也在改写中被抹掉。
-        // ⇒ `AdoptionError` **原样穿过**:core 的拒绝句本就是写给人读的(点名在飞的那条弧,并给出「resume
-        // adoptLocalDataRoot 到完成,或修 adoption.json」的出路),我们没有更好的话可说,包一层只会更差。
-        // 包装只留给真正的 boot-lock 类失败(那句文案的适用条件)。
         try {
             this.fileBackend = new FileStorageBackend({
                 root,
-                ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}), // REWIND_SNAPSHOT_MAX_MB
-                // 🔴 腐读披露座(交接件④,与 `run-local.ts` 的同座同形、同 warn 名 `file_store_corrupt_read`)。
-                // core 对**读不出来的**持久文件是 documented fail-open —— 当作「缺席」继续跑(抛会让整条任务死,
-                // 也会自锁修复写)。这条 fail-open 是 core 的裁定,本仓不改它;但它**不许无声**(#157 安全轴纪律)。
-                // 此前 HTTP 服务的 local 车道**根本没接这个座**:同一份坏字节,run-local 上打一行、服务上一个字
-                // 都没有 —— 而服务形恰恰是没人盯着终端的那一个。
-                //
-                // ⚠️ 文案按脸分列后果、**不下统一结论**(run-local 那次 codex R2-medium 的教训一并吸收):一个座
-                // 覆盖 core 转发的三张脸,后果各不相同 —— 把「少了会话规则这一层」写成「整个任务无约束」会误导
-                // 事故定级,而且对另外两张脸根本不成立。共同事实只有一句:一次持久读被当成了缺席。
-                // ENOENT 不触发(那是真缺席,不是腐读)。
+                ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}),
                 onCorruptRead: (info) => this.onWarn?.("file_store_corrupt_read", {
                     path: info.path,
                     reason: info.reason,
@@ -268,21 +185,7 @@ class LocalBackend {
             throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)} ` +
                 "(another HTTP service / run-local instance may own it; stop it first or set LOCAL_DATA_ROOT to a free dir)");
         }
-        // §0.5 owner-aware wrapper over a fresh FileSessionRepo on the SAME root (NOT fileBackend.sessionStore — that's
-        // the bare TtlSessionStore without the §0.5 owner/list/fork/delete ops). Both touch root/sessions/*.jsonl.
-        // Pass `root` as the lastActivity sidecar dir so the /resume picker's newest-first order survives a restart (TOC #10):
-        // without it the in-memory recency map starts empty on boot and every session degrades to createdAt ordering.
         this.sessionStore = new LocalSessionStore(new FileSessionRepo(this.fileBackend.root), this.fileBackend.root);
-        // P0.5 variant-1: file-backed runs ledger + E18 anchors over the SAME canonical root (under root/runs + root/
-        // resume-anchors). Hydrate the in-memory index from disk on construction → restart-visible.
-        // 件6(#43 案 [4281]):hydrate 的 readdir 失败要**响亮**——把 boot 告警口接过去(缺席则只走 fail-open
-        // 遥测那一半)。包一层箭头而不是直接传方法引用:后者会把方法从接收者上摘下来,带 `this` 的实现会在
-        // 第一次真披露时炸,而那一刻正是最不该炸的时候(本文件 :658 同族先例)。
-        // 🔴 F-D(2026-08-17 合并码扫描):这一座必须接 **error** 口。件6 三处成文(FileRunStore 那条 catch 注 /
-        // `fail-open.ts` 的 tag note / 普查表第 29 行)承诺的都是「一行 **error 级**启动日志」,而修前它被绑到
-        // `onWarn` 上、且 `openStoreBackendWithFallback` 的 logger 参数类型里压根没有 error 通道 ⇒ 生产恒 warn,
-        // 按 `level >= error` 配告警的运维一条都收不到,而这条债的全部价值就是「恒 miss 不再被当成本来就没有」。
-        // `onError` 缺席(只装配了 warn 座的调用方)⇒ 退回 warn 座:降一级好过无声。
         this.runStore = new FileRunStore(this.fileBackend.root, {
             error: (msg, fields) => void (this.onError ?? this.onWarn)?.(msg, fields),
         });
@@ -292,47 +195,32 @@ class LocalBackend {
         this.workflowJournalStore = new FileWorkflowJournalStore(this.fileBackend.root);
         this.outcomeSinkInst = new FileOutcomeSink(this.fileBackend.root);
     }
-    async ensureSchema() { } // FileStorageBackend ctor already created root + the boot lock → always "reachable"
+    async ensureSchema() { }
     async close() {
-        await this.sessionStore.dispose(); // AWAIT the final lastActivity flush (bug C) BEFORE releasing the dir lock below
-        this.runStore.dispose(); // release the per-run event-log fds so a graceful restart can re-open the data dir
-        this.resumeAnchorStore.dispose(); // release the per-session anchor-log fds
-        this.approvalExemptionStore.dispose(); // release the per-session exemption-log fds
-        this.sendFileLedgerStore.dispose(); // release the sendfile-ledger append fd (lazy — may never have opened)
-        this.workflowJournalStore.dispose(); // release the per-run journal-ledger fds
-        this.checkpointStoreInst?.close(); // release the checkpoint ledger fd (lazy, may never have been built)
-        // #203 §1: release core's permission-rule DIRECTORY write lock (lazy — may never have been built).
-        // Same discipline as root/LOCK below: an un-released writer lock tells the next boot that a live process
-        // owns the rule directory, and core refuses the second holder LOUDLY rather than queueing.
+        await this.sessionStore.dispose();
+        this.runStore.dispose();
+        this.resumeAnchorStore.dispose();
+        this.approvalExemptionStore.dispose();
+        this.sendFileLedgerStore.dispose();
+        this.workflowJournalStore.dispose();
+        this.checkpointStoreInst?.close();
         this.permissionRuleStoresInst?.dispose();
-        await this.fileBackend.dispose(); // MUST release root/LOCK so a graceful restart can re-acquire the data dir
+        await this.fileBackend.dispose();
     }
     run() { return this.runStore; }
-    resumeAnchor() { return this.resumeAnchorStore; } // singleton — state lives in the instance (mirrors run()/session())
-    approvalExemption() { return this.approvalExemptionStore; } // singleton — same posture
-    /** #151 流内审批协议持久层的 local 形。**必须**是 singleton:状态全在实例的两个 Map 里,每次
-     *  new 一个就等于每个消费者各拿一份互不可见的账(而 SQL twin 天然共享一张表)。易失代价 +
-     *  「local 车道默认不上协议」的裁定见 StoreBackend.approvalAsk() 的接口注。 */
+    resumeAnchor() { return this.resumeAnchorStore; }
+    approvalExemption() { return this.approvalExemptionStore; }
     approvalAsk() { return this.approvalAskStore; }
-    /** #203 §1:local 车道的 File 三面束。**必须**是 singleton —— core 的 File provider 在第一次取写面时
-     *  对规则目录取一把进程级写锁,第二个持有者被**响亮拒绝**(不是排队),所以每次 `new` 一个就等于给
-     *  自己造一次「另一个进程占着这个目录」的假象。`close()` 里 `dispose()` 释放它(与数据根 `root/LOCK`
-     *  同一条纪律:不释放 ⇒ 优雅重启被自己上一条命留下的锁挡在门外)。惰性建:没开旋钮的部署不该因为
-     *  一个从不使用的面而在数据根里长出目录、更不该白占一把写锁。 */
     permissionRule() {
         if (!this.permissionRuleStoresInst) {
             this.permissionRuleStoresInst = createFilePermissionRuleStores(this.fileBackend.root, {
-                // core 规则文件的披露面(读不出 / 校验和不符 / 撞上符号链接 ⇒ 答零规则**并说出来**)。
-                // 不接住它就是一次静默的 fail-closed:用户突然被反复询问,而日志里一个字都没有。
                 onError: (message) => this.onWarn?.("permission_rule_store_disclosure", { message }),
             });
         }
         return this.permissionRuleStoresInst;
     }
     permissionRuleStoresInst;
-    sendFileLedger() { return this.sendFileLedgerStore; } // singleton — append fd lives in the instance
-    /** Durable HITL / plan-review parking on the LOCAL lane. Lazy singleton (the inner core store holds
-     *  an append fd). taskId join ← FileRunStore; E21 owner guard ← LocalSessionStore.ownerOf (same root). */
+    sendFileLedger() { return this.sendFileLedgerStore; }
     checkpoint() {
         if (!this.checkpointStoreInst) {
             const cs = new LocalCheckpointStore(this.fileBackend.root, {
@@ -340,14 +228,6 @@ class LocalBackend {
                 ownerOf: (sessionId) => this.sessionStore.ownerOf(sessionId),
             });
             this.checkpointStoreInst = cs;
-            // [868] the reverse join: FileRunStore's suspended-run reapers cannot JOIN the checkpoint plane (separate
-            // store), so they take the two EXISTS predicates as an injected probe — wired HERE because this is the one
-            // place both stores exist over the same root. Without it the reapers stay honest NO-OPs, and an abandoned
-            // durable HITL park (approval never answered) held its task_active claim forever (session locked; the
-            // [868] incident). NB the probe only tells the reaper what the SQL twins read via JOIN — the reaper's
-            // D-D NOT-pending guard still decides; and the APPROVAL_TIMEOUT_SEC=0 default still keeps the time-based
-            // leg OFF (durable HITL waits for a human indefinitely BY DESIGN; the checkpoint-expiry leg + the cancel
-            // verb are the recovery handles).
             this.runStore.setCheckpointProbe({
                 hasPending: async (sessionId) => (await cs.findPendingTokenBySession(sessionId)) !== null,
                 hasExpired: (sessionId) => cs.hasExpiredBySession(sessionId),
@@ -356,53 +236,24 @@ class LocalBackend {
         return this.checkpointStoreInst;
     }
     checkpointStoreInst;
-    sessionPolicy() { return this.fileBackend.sessionPolicyStore; } // E6 — file-backed (survives restart)
-    fileSnapshot() { return this.fileBackend.fileSnapshotStore; } // E19 — file-backed content-addressed blobs (survive restart)
-    workflowJournal() { return this.workflowJournalStore; } // SVC-2 — FILE-backed (restart-durable on one box, see field doc)
-    outcomeSink() { return this.outcomeSinkInst; } // design/73 §1 — owner-only JSONL fact ledger
+    sessionPolicy() { return this.fileBackend.sessionPolicyStore; }
+    fileSnapshot() { return this.fileBackend.fileSnapshotStore; }
+    workflowJournal() { return this.workflowJournalStore; }
+    outcomeSink() { return this.outcomeSinkInst; }
     session() { return this.sessionStore; }
-    // core 1.219 (dogfood finding "ReadToolResult(ref) 恒空"): the TOC lane now has a DURABLE tool-result
-    // store — core's FileToolResultStore under the same data root (one file per ref, write-once, restart-durable).
-    // In-process cross-task deref was already fixed core-side (1.219 Runner-shared fallback); this adds the
-    // cross-RESTART half. deleteBySession:core 5.28 起 FileToolResultStore **有**(R3 复扫更正过一次、
-    // R4 复扫再纠:上一版注写成「两者都有」过头了——`reapOlderThan` 在 core 5.28.0 dist 全文零命中,
-    // TTL 腿仍是 SQL twins only,reapers.ts 的 `?.` 可选链在 local 上永久 no-op,别拆)。deleteBySession
-    // 按 .owner.json 边车判属主,无边车的存量计 unattributable 不删,与 SQL 孪生同口径。
     toolResult() { return this.fileBackend.toolResultStore; }
     mysqlPool() { return undefined; }
     pgPool() { return undefined; }
 }
-/**
- * 启动日志里「跨副本 or 进程内」那一格的标签。
- *
- * 🔴 判据必须是**那个 store 本身在不在**,不是「有没有 backend」(2026-07-31 缝合审)。
- * `LocalBackend` 明确省略 `costQuota`/`rateLimiter`(见它类尾那行 "intentionally absent"),
- * 而 `DB_BACKEND=local` 是**裸 boot 的默认值** —— 原来 main.ts 那两行用 `backend ? "shared()" : …` 判,
- * 于是单机默认形配了 `RATE_LIMIT_PER_MIN` 会打出 `shared()`,实际跑的是每副本一份的进程内限流器。
- * 运维扩到 N 副本时读这行判定"限流是跨副本的",真实额度是 N 倍。
- * (同一个说谎病族在紧邻的 `breakerState` 上修过一次——"was hard-coded 'shared(tidb)' — lied under
- * DB_BACKEND=pg"——`session:` 也跟着修了,这两行没跟上。顺带:原来的 `shared()` 括号是空的,
- * 而兄弟行都写 `shared(${kind})`。)
- */
 export function counterStoreLabel(store, kind) {
     return store ? `shared(${kind ?? "unknown"})` : "in-process";
 }
-/** 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.
- *
- *  `onWarn` (additive, optional) is the boot-time warning sink the LOCAL backend needs for core's
- *  permission-rule DISCLOSURE face (#203 §1): an unreadable / checksum-mismatched / symlinked rule file
- *  answers ZERO rules and says so — swallowing that turns a fail-closed degrade into a silent one.
- *  `onError` (additive, optional; F-D) is the **error-level** twin of that seat — 件6 的
- *  `file_run_store_hydrate_unreadable` 按成文承诺是 error 级,warn 座满足不了那句话。两座都是**加项**:
- *  既有一/二参调用方逐字不变(缺席 ⇒ 该披露退回 warn 座 / 只剩 fail-open 遥测那一半)。 */
 export function createStoreBackend(config, onWarn, onError) {
     if (config.dbBackend === "local")
         return new LocalBackend(config.localDataRoot ?? join(homedir(), ".ai-agent"), config, onWarn, onError);
     if (config.dbBackend === "pg") {
         if (!config.pg)
             return undefined;
-        // pgPoolOptions also arms the DB_QUERY_TIMEOUT_MS pool-wide per-query ceiling (S9 deeper fix) when set.
         const pool = createPgPool(pgPoolOptions(config.pg, config.dbQueryTimeoutMs));
         return new PgBackend(pool, config);
     }
@@ -410,50 +261,19 @@ export function createStoreBackend(config, onWarn, onError) {
         return undefined;
     return new TiDBBackend(createTidbPool(config), config);
 }
-/** 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 async function openStoreBackendWithFallback(config, 
-// 🔴 `error` 是**可选加项**(F-D):件6 的 hydrate 披露按成文承诺是 error 级,而本参数此前只有 warn 通道
-//    ⇒ 那句承诺在生产链上结构性地兑不了(注释说 error、代码只出 warn,正是本文件下方 :659 自陈的病族)。
-//    仍可选:只装配 warn 座的调用方(测试/工具)逐字不变,它们的 hydrate 披露退回 warn 座。
-logger) {
-    // 判据按后端分岔(2026-07-28 同批修):原先写的是 `sessionBackend === "auto" || (local && !explicit)`,
-    // 而 `auto` 是 SESSION_BACKEND 的**默认值** ⇒ 显式 `DB_BACKEND=local` 的部署照样落进第一条臂被静默降级,
-    // 「显式仍 fail-loud」这句话同样从未生效。local 形只看 DB_BACKEND 是不是显式;SQL 形维持 S5 原义
-    // (auto=尽力而为可降级,显式 tidb/pg=fail-loud,静默丢持久化会丢 run)。
+export async function openStoreBackendWithFallback(config, logger) {
     const mayFallback = config.dbBackend === "local" ? !config.dbBackendExplicit : config.sessionBackend === "auto";
     let backend;
     try {
-        // 包一层箭头而不是直接传 `logger.warn`:后者会把方法从它的接收者上摘下来,一个带 `this` 的
-        // logger 实现会在第一次真披露时炸——而那一刻正是最不该炸的时候(本仓 fail-loud 病族先例)。
-        // error 座同款包法;调用方没有 error 通道时**不传**(LocalBackend 那侧据此退回 warn 座)。
         backend = createStoreBackend(config, (msg, meta) => logger.warn(msg, meta), logger.error === undefined ? undefined : (msg, meta) => logger.error(msg, meta));
-        // connects + creates schema (also the reachability probe).
         if (backend)
             await backend.ensureSchema();
     }
     catch (err) {
-        // 🔴 core 5.23.0([3372] 提货批,codex 复审 high 抓获、验真后修):**I6 adoption 门不许被降级臂吃掉**。
-        // 1.292 拍的降级裁定说的是「只读 FS / mkdir 失败」那一类——它们的意思是「这台机器存不了盘」,降级到
-        // 内存是诚实的等价物。`AdoptionError` 说的是完全不同的一句话:「这份数据**有主、正在搬**」(design/183
-        // I6:数据根的 `adoption.json` 在飞,或标记读不出)。对后者降级 = **在搬家途中另开一个写者**,而那正是
-        // I6 门存在的全部理由;更坏的是它还会留下一行「DB 不可达」的 warn,把运维支去查连通性。
-        // ⇒ 与显式 DB_BACKEND 同待遇:无条件 fail-loud,穿过 `mayFallback`。
         if (err instanceof AdoptionError)
             throw err;
         if (!mayFallback)
             throw err;
-        // S5 (SILENT-FALLBACK P0-b): one boot warn was the ONLY trace of "this replica is not persisting".
-        // The caller renders the gauge + /health twin flag so a degraded replica is distinguishable from
-        // an in-memory-by-choice one.
         logger.warn("store_db_unreachable_fallback_memory", {
             backend: backend?.kind ?? config.dbBackend,
             error: err instanceof Error ? err.message : String(err),

package/dist/plugins/store-contracts.js

@@ -1,22 +1,4 @@
 import { parseJsonOr, toIso as iso, normalizeIsoOrNull as isoOrNull } from "./sql-row-helpers.js";
-/**
- * 「这一行已经走到**终局**了吗」——`RunRecord["status"]`(= `"running" | TaskStatus`)的**穷举**判据,
- * 与类型定义同住一个文件(词表的属主 = 判据的属主)。
- *
- * 🔴 为什么是 `switch` 而不是一张 `ReadonlySet<string>`(2026-08-08,#176 二轮扫描 finding):终局词表
- * **真变过**(core 5.8.0 把 `"timeout"` 从 `TaskStatus` 里删了)。而集合形的门对象是 `string`,对词表
- * 两个方向都无钉:
- *   · **增词**(core 新加一个终局态)⇒ 集合不含它 ⇒ 该行被静默判成「非终局」,收敛器会一直等一个
- *     永远不会再动的行;
- *   · **删词** ⇒ 集合里留一个死字面量,没有任何东西会说话。
- * 穷举 `switch` 把两个方向都变成**编译期**问题:core 加成员 ⇒ `default` 臂收不敛到 `never` ⇒ tsc 红,
- * 加成员的人被迫当场回答「这个新态算不算终局」;删成员 ⇒ 对应 `case` 变成不可达字面量、同样红。
- * 这条判据不许再被手抄成第二份 —— 两个消费点(`approval-reconciler.ts` 判据 2、`http/routes/runs.ts`
- * 的取消后复读)都从这里取。
- *
- * 词表现状:终局 = completed / failed / blocked;非终局 = running / suspended / needs_review
- * (suspended 与 needs_review 都还能再动,`running` 更不必说)。
- */
 export function isTerminalRunStatus(status) {
     switch (status) {
         case "completed":
@@ -28,35 +10,12 @@ export function isTerminalRunStatus(status) {
         case "needs_review":
             return false;
         default: {
-            // core 的 `TaskStatus` 出了新成员 ⇒ 这里收不敛到 never ⇒ tsc 红(整条判据的**编译期**执行点)。
             const unhandled = status;
-            // 🔴 运行时**必须**照旧返回 false(#176 codex R1 真缺陷,红先复现):`never` 只活在编译期,
-            // `return unhandled` 在运行时返回的是那个字符串本身 = **truthy**。而 `plugins/run-store-sql.ts` 的
-            // rowToRun 把无约束的 SQL 文本列**裸 cast** 成本联合 ⇒ 滚动升级里一个更新的副本写入的新状态词
-            // 会被这里读到。判成「终局」的代价不可逆:approval-reconciler 判据 2 会把一张还活着的 ask 永久
-            // 打成 DENIED/routing_failure,取消路由也会把这一行当终局上报。未知 ⇒ 保守判**非终局**(落 hold,
-            // 下一轮重试),与本函数取代的那份 `ReadonlySet<string>.has()` 逐字节同行为。
             void unhandled;
             return false;
         }
     }
 }
-/**
- * 「这一行**停在门上**(park)了吗」——`RunRecord["status"]` 的第二张穷举判据,与 {@link isTerminalRunStatus}
- * 同住词表属主处(扫描P2,2026-08-12)。
- *
- * 🔴 为什么必须有名字:park 是**两个词**,不是一个 —— `suspended`(tool_approval / policy_ask / human /
- * resource_limit 门)与 `needs_review`(`plan_review` / dry-run 拦截门,写点 = 各 store 的
- * `setNeedsReview`)。两者的行为面**完全一致**:行还活着、`task_active` claim 还占着、checkpoint 还能被
- * 决议。凡是「行是不是还停着」的判断只手抄 `=== "suspended"` 的地方,对 plan_review 腿一律给出**相反**
- * 结论 —— 它会被当成终局:取消谎报 "already terminal — no-op"(claim 从此无人释放,正是 [868] 那个把会话
- * 锁死的指纹)、trace 面无帧、leader 面不触发 park 反应。这条判据的存在就是为了不再有第三次手抄。
- *
- * 未知词的方向与 {@link isTerminalRunStatus} 同向保守:判**不是** park。理由是消费点会据此做**不可逆**
- * 动作(cancel 的恢复把手会 CAS-expire 一张 checkpoint);对一个本进程读不懂的状态,少动一次远好过错杀。
- * 真正的执法点是下面那条 `never`:core 的 `TaskStatus` 一加成员就 tsc 红,加成员的人必须当场回答
- * 「这个新态算不算 park」。
- */
 export function isParkedRunStatus(status) {
     switch (status) {
         case "suspended":
@@ -68,13 +27,12 @@ export function isParkedRunStatus(status) {
         case "blocked":
             return false;
         default: {
-            const unhandled = status; // 词表增删两向的**编译期**执行点(同 isTerminalRunStatus 顶注)
+            const unhandled = status;
             void unhandled;
-            return false; // 运行时保守:未知 ⇒ 不当 park(不可逆动作宁可不做)
+            return false;
         }
     }
 }
-/** SELECT row → {@link BakeRecord} — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export function mapBakeRow(r) {
     return {
         bakeId: r.bake_id,
@@ -106,11 +64,9 @@ export function mapBakeRow(r) {
         updatedAt: iso(r.updated_at),
     };
 }
-/** Column list mapBakeRow expects — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export const BAKE_SELECT_COLS = "bake_id, profile, bands, base_ref, push, dry_run, logs, argv, status, state, digest, repo, ref, index_id, " +
     "exit_code, error, error_code, manifest_sha, tag, idem_key, ingest_secret, runner_id, lease_until, " +
     "cancel_requested, requested_by, created_at, updated_at";
-/** SELECT row → {@link ImageIndexEntry} — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export function mapImageRow(r) {
     return {
         id: r.id,