@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/sql-json-column.d.ts

@@ -53,15 +53,16 @@ import type { SqlDialect } from "./sql-driver.js";
  */
 export declare function jsonColumnText(dialect: SqlDialect, column: string, member?: JsonColumnMember): string;
 /**
- * 一列 JSON 的**一个顶层成员**(NP-3,7.100.0)—— 读腿只要文档里的一棵子树时用它,整只文档不出引擎。
- *  · `key` = 成员名(裸标识符;进 MySQL 路径 `'$.<key>'` 与 PG 字面 `'<key>'`,所以只认裸标识符,不转义不猜);
+ * 一列 JSON 的**一个成员**(NP-3,7.100.0)—— 读腿只要文档里的一棵子树 / 一格时用它,整只文档不出引擎。
+ *  · `path` = 自顶层往下的成员名(一段或多段,每段裸标识符;进 MySQL 路径 `'$.<a>.<b>'` 与 PG 链 `-> '<a>' -> '<b>'`,所以只认裸标识符,不转义不猜)。
+ *    一段 = 顶层成员(`["pendingAction"]`),多段 = 成员里的成员(`["state", "rowTaskId"]`);一段的产物与多段形之前的写法逐字节同;
  *  · `as` = 行上的键(**小写**裸标识符:PG 把不带引号的别名折成小写,别的拼法会让两方言的行键不同)。
- * 产物仍是**文本**(同一条「按文本投影、恰好解一次」),成员缺席 / 文档不是对象 ⇒ SQL NULL(两引擎同答),
- * 所以读腿用 {@link decodeNullableJsonColumn}:NULL = 「这份文档没有这棵子树」,JSON `null` 字面 = 一个值(交形读者判)。
- * 首个读者:`checkpoint-store-sql.ts` 的 `listPending`(运维队列 / `/v1/approvals/stream` 热读)只取 `pendingAction`。
+ * 产物仍是**文本**(同一条「按文本投影、恰好解一次」),路径上任一段缺席 / 不是对象 ⇒ SQL NULL(两引擎同答),
+ * 所以读腿用 {@link decodeNullableJsonColumn}:NULL = 「这份文档没有这一格」,JSON `null` 字面 = 一个值(交形读者判)。
+ * 读者:`checkpoint-store-sql.ts` 的 `listPending`(运维队列 / `/v1/approvals/stream` 热读)与 `one-time-migrations.ts` 的 M21。
  */
 export interface JsonColumnMember {
-    readonly key: string;
+    readonly path: readonly [string, ...string[]];
     readonly as: string;
 }
 /**
@@ -82,7 +83,7 @@ export interface JsonColumnMember {
  * 子树,本函数的插值对它是一个不透明表达式。所以「误用进 SELECT 投影且没给别名」这一形没有机器门 ——
  * 误用的落点是真库上当场的 `SqlJsonColumnError("not-text")` 响亮抛(行上没有那个键 ⇒ `undefined`),不是静默。
  */
-export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string, memberKey?: string): string;
+export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string, memberPath?: JsonColumnMember["path"]): string;
 /**
  * 一列 JSON 的**投影文本的 sha256**(十六进制小写,引擎内算 —— 整只文档不出库),带别名。输入恰是 {@link jsonColumnTextExpr} 那一只投影:
  * 同一行、同一次读里,本表达式的摘要就是 {@link jsonColumnText} 交给读腿的那串字节的摘要,于是「字节没变 ⇒ 摘要没变」只有一种读法。

package/dist/plugins/sql-json-column.js

@@ -6,19 +6,23 @@ export function jsonColumnText(dialect, column, member) {
     if (!MEMBER_ALIAS_RE.test(member.as)) {
         throw new Error(`jsonColumnText: member alias ${JSON.stringify(member.as)} must be a lower-case bare identifier — PostgreSQL folds unquoted aliases to lower case, so any other spelling would give the two dialects different row keys`);
     }
-    return `${jsonColumnTextExpr(dialect, column, member.key)} AS ${member.as}`;
+    return `${jsonColumnTextExpr(dialect, column, member.path)} AS ${member.as}`;
 }
 const MEMBER_ALIAS_RE = /^[a-z_][a-z0-9_]*$/;
-export function jsonColumnTextExpr(dialect, column, memberKey) {
+export function jsonColumnTextExpr(dialect, column, memberPath) {
     if (!COLUMN_NAME_RE.test(column)) {
         throw new Error(`jsonColumnTextExpr: ${JSON.stringify(column)} is not a bare column identifier — refusing to splice it into SQL text`);
     }
-    if (memberKey === undefined)
+    if (memberPath === undefined)
         return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
-    if (!COLUMN_NAME_RE.test(memberKey)) {
-        throw new Error(`jsonColumnTextExpr: member ${JSON.stringify(memberKey)} is not a bare identifier — refusing to splice it into a JSON path`);
+    for (const segment of memberPath) {
+        if (!COLUMN_NAME_RE.test(segment)) {
+            throw new Error(`jsonColumnTextExpr: member ${JSON.stringify(segment)} is not a bare identifier — refusing to splice it into a JSON path`);
+        }
     }
-    return dialect === "pg" ? `(${column}::jsonb -> '${memberKey}')::text` : `CAST(JSON_EXTRACT(${column}, '$.${memberKey}') AS CHAR)`;
+    return dialect === "pg"
+        ? `(${column}::jsonb ${memberPath.map((segment) => `-> '${segment}'`).join(" ")})::text`
+        : `CAST(JSON_EXTRACT(${column}, '$.${memberPath.join(".")}') AS CHAR)`;
 }
 export function jsonColumnTextSha256(dialect, column, as) {
     if (!MEMBER_ALIAS_RE.test(as)) {

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

@@ -1,10 +1,14 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { SessionStore, SessionPolicyStore, FileHistoryStore, FileHistoryBlobExchange, FileHistoryError, WorkflowJournalStore, ToolResultStore, SessionCaptureRecordStore, UsageWindowStore } from "@sema-agent/core";
+import { FileStorageBackend } from "@sema-agent/core";
 import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
-import { type OneTimeMigrationReport } from "./one-time-migrations.js";
+import { type RunStallWiring } from "./store-contracts.js";
+import { type StoreOpenLane } from "./store-open-refusal.js";
+import { type OneTimeMigrationReport, type SqlOneTimeMigrationInput } from "./one-time-migrations.js";
+import { LocalSessionStore } from "./local-session-store.js";
 import type { LocalSessionRows } from "./local-session-window.js";
 import type { SessionHeadReader } from "./caching-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
@@ -33,19 +37,33 @@ import type { CounterDegradeHook } from "./write-behind-counter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
 import { type SqlSharedMemoryStore, type SharedMemoryScopeAuthorizer } from "./shared-memory-store-sql.js";
 import { type AdoptionLogStore } from "./adoption-log-sql.js";
-import { type SqlRetentionStore, type SqlRetentionStoreOptions } from "./retention-store-sql.js";
+import { type SqlTransactionHooks } from "../stores-sql/retention-store-sql.js";
+import type { SessionEraser } from "../session-erase.js";
+import { type RetentionDestructiveInput, type RetentionExecutor, type RetentionExecutorOptions } from "./retention-deployment.js";
 import { type RetentionLaneStore } from "./retention-lane-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
+import { type SqlDriver } from "./sql-driver.js";
 import { type StoreDegradedReason } from "../store-posture.js";
 /** boot 期的一条日志座(级别由**座位**决定,不由参数携带):`createStoreBackend` 的 `onWarn` / `onError`
  *  两参与 `LocalBackend` 的同名字段共用此形。装配层把它们分别接到 `logger.warn` / `logger.error` 上。 */
 export type BootLogSink = (msg: string, meta?: Record<string, unknown>) => void;
+/**
+ * 后端交给店的**观测座**(加项、可缺席:嵌入方 / 测试不给 ⇒ 不计数)。今天一格:run 店每落下 n 条死亡判决(收割器 / 观察口 / 认领冲突同一只)
+ * ⇒ `runStallVerdicts(n)`(生产装配 = `runs_reaped_total{kind:"stale"}`,`boot/stores.ts`)。
+ */
+export interface StoreBackendObservers {
+    readonly runStallVerdicts?: (landed: number) => void;
+}
+/** run 店落死亡判决的两样:窗 = 后端持有的配置对象的 `runStaleSec`(热发布原地改写 ⇒ getter 读到热值;判活窗只有这一个来源)+ 计数座。 */
+export declare function createRunStallWiring(config: Pick<ServiceConfig, "runStaleSec">, observers: StoreBackendObservers | undefined): RunStallWiring;
 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";
+/** 会话树根的写(事务内钩的写闭集,`stores-sql/session-write-hooks.ts`):本组合座转口给目录外的判官(`execution-placement.ts` 的 `judgeSessionWrite`;local 店的写锁内同一组词)。 */
+export type { SessionWrite } from "../stores-sql/session-write-hooks.js";
 export type { ApprovalNonceStore } from "./approval-nonce-store.js";
 /** [ref]([ref] v3.1 §3.0-§3.2 流内审批协议持久层):`ApprovalAskStore` 接口 + 行/补丁类型。
  *  车3 刀 3a 起 `StoreBackend.approvalAsk()` 已在(见接口体的那条注)。 */
@@ -65,7 +83,7 @@ export type ServiceSessionPolicyStore = SessionPolicyStore;
  * The SQL twins' blob exchange — core's {@link FileHistoryBlobExchange} group (`put` / `get` / `has`, all three or none, read only
  * through `blobExchangeOf` in `session-sync.ts`, which defers to core's judge) with ONE narrowing: a `put` refusal may carry
  * `blobCap`, the SQL blob judge's refusal on the connection that would have written the blob
- * ({@link import("./blob-backend.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
+ * ({@link import("../stores-sql/blob-index-sql.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
  * `blob_too_large_for_sql` (the judge's sentence, plus the machine-readable `wallSource` = where the cap came from). The content-address
  * refusal is core's own (`adopt_failed`, `permanence: "terminal"`, nothing stored); every other failure is a write fault the route answers 502.
  */
@@ -75,7 +93,7 @@ export type SqlBlobPutResult = {
     readonly ok: false;
     readonly error: FileHistoryError & {
         readonly blobCap?: {
-            readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+            readonly wallSource: import("../stores-sql/blob-index-sql.js").SqlBlobCapReading["source"];
         };
     };
 };
@@ -157,13 +175,14 @@ export type SessionCaptureRecordSource = (plane?: {
 }) => SessionCaptureRecordStore;
 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. */
+     *  MariaDB) behind the one mysql2 pool — the startup summary prints `mysql` for all of them. */
     readonly kind: "mysql" | "pg" | "local";
     /** Connect + create schema (also the reachability probe). On the SQL backends it first checks the database for the
      *  schema that the one-time migrations of server 7.74.0–7.125.x retired and **refuses** with `RetiredSchemaPresentError`
      *  (code `config.schema_mismatch`, exported from the package root) before it issues the first CREATE; only then does it create.
      *  The check lives in this method itself, so the public sequence `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
-     *  needs no step of its own. The LOCAL backend has no SQL pool and nothing to probe. */
+     *  needs no step of its own. The LOCAL backend has no SQL pool: its data root's engine high-water is judged when the backend is opened (before any store is built),
+     *  and a data root refused there surfaces here, as that refusal; otherwise this runs the local reconciliation (strict sidecars, archive snapshots). */
     ensureSchema(): Promise<void>;
     close(): Promise<void>;
     run(): RunStore;
@@ -225,7 +244,7 @@ export interface StoreBackend {
     userInputLedger(): UserInputLedgerStore;
     /** E6 durable SessionPolicyStore (operator-tightened per-session tool rules). REQUIRED on all backends — works local
      *  (local = core's FileSessionPolicyStore), like resumeAnchor. Backs core's RunnerDeps.sessionPolicyStore.
-     *  `logger`:SQL 孪生抹除封键那一臂([ref])的点名口(缺席 ⇒ 店退回 `console.warn`);local(core 的 File 店)不收。 */
+     *  `logger`:SQL 孪生抹除封键那一臂([ref])的点名口(装配点缺省交日志出口接缝的 logger);local(core 的 File 店)不收。 */
     sessionPolicy(logger?: SessionPolicyStoreLogger): ServiceSessionPolicyStore;
     /** [ref] per-edited-file rewind FileHistoryStore (trackEdit/annulTrack/snapshot/restore over the tracked set;
      *  also the 2c history-transfer store). REQUIRED on all backends (local = core's file-backed
@@ -354,7 +373,7 @@ export interface StoreBackend {
      * `local` 刻意省略 —— 与 {@link leaderRun} 逐字同一条理由:config 层已经把「`REMOTE_EXEC=device` 且
      * 无外部 SQL 店」整个组合拒启了(`device-durable-store` 不变量),所以 local 车道上根本不存在一个需要
      * 这四张表的 device worker。消费点按 `backend?.device?.()` 取,缺席 ⇒ `boot/device-lane.ts` 的
-     * `assertDeviceLaneWired` 响亮拒启(**不是**静默落进程内 stub)。
+     * `assertDeviceLaneWired` 响亮拒启(**不是**静默跑成无手)。
      */
     device?(): DeviceStore;
     /**
@@ -364,9 +383,14 @@ export interface StoreBackend {
      *
      * `taskAttachmentTable` 必填、无默认值 —— boot 只在配了对象存储时才 ensure 那张表,一条盲发的
      * DELETE 在无 MinIO 的部署上会以 unknown-table 打红整轮 sweep(理由逐字见
-     * `retention-store-sql.ts` 的 `SqlRetentionStoreOptions`)。
+     * `retention-deployment.ts` 的 `RetentionExecutorOptions`)。组合形见 {@link createSqlRetentionExecutor}。
+     */
+    retention?(opts: RetentionExecutorOptions): RetentionExecutor;
+    /**
+     * 删净一只会话的**执行体**(`session-erase.ts` 的 `SessionEraser`;在线删除协调器调它)—— 与 {@link retention} 的会话树清扫同一段事务体(组合 `createSqlSessionEraser`)。
+     * **SQL 后端专有**:local 的执行体是会话店写锁一节(`session-erase.ts` 的 `createLocalSessionEraser`),各店在 boot 里才齐,由删除协调器自己组。
      */
-    retention?(opts: SqlRetentionStoreOptions): SqlRetentionStore;
+    sessionEraser?(opts: RetentionExecutorOptions): SessionEraser;
     /**
      * [ref] 车2 —— 留存执行面的**非破坏性**半场:sweep 租约、legal-hold 的放置/解除、审计表的读与
      * 非破坏行的写。同样 SQL 专有(它写的三张表只在 SQL schema 里)。
@@ -403,13 +427,40 @@ export interface StoreBackend {
      *  `new FileUsageWindowStore(root)` 第二只实例、不接座 ⇒ 坏值只拒不披露,运维找不到是哪只文件。SQL 后端省略(它们有自己的 usage-window 双方言店)。 */
     fileUsageWindowStore?(): UsageWindowStore;
 }
+/**
+ * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十三张部署表,
+ * `plugins/retention-deployment.ts`,经 K4 事务内钩参与同一事务)。
+ *
+ * 破坏性三方法**每次调用**铸一只执行器、钩表绑这一次调用(`createRetentionDeploymentHooks` 的头注:审计行的判定时点三格与
+ * `checkpoint_ctx` 属主门的域是这一次调用的事实)。会话树删除的 `erased`(交收尾的那一份)由执行器的行面回执 + 部署收集的附件哈希拼成,
+ * 只在执行器**提交成功返回之后**挂上回执(回滚 ⇒ 执行器抛,不挂)。非破坏两口(域枚举 / 预览)不经钩。
+ */
+/**
+ * 一次破坏性调用的整张事务内钩表:部署的 `retention` 组(按这一次调用铸,`createRetentionDeploymentHooks`)+ 会话座的钩
+ * (`createSqlSessionWriteHooks`,会话店用的同一只工厂;留存删除走它的 `retention-delete` 臂)。`attachmentShas` 读部署那一半收到的行。
+ */
+export declare function createSqlRetentionCallHooks(db: SqlDriver, opts: RetentionExecutorOptions, input: RetentionDestructiveInput): {
+    readonly hooks: SqlTransactionHooks;
+    attachmentShas(): readonly string[];
+};
+export declare function createSqlRetentionExecutor(db: SqlDriver, opts: RetentionExecutorOptions): RetentionExecutor;
+/**
+ * **删净一只在删会话的 SQL 执行体**(`session-erase.ts` 的 `SessionEraser`):执行器的 `eraseSession` —— 与留存清扫同一段会话树事务体,前面是锁行 + 属主 +
+ * 会话座事务内钩的 `erase` 判(这一行处于这只令牌的在删态)。行不在 / 属主不是那一位 / 令牌不是它(`SessionDeletionSupersededError`)⇒ `superseded`,别的拒原样抛。
+ * 部署行那一半用与留存同一只钩(`createSessionRowsHook`,域 = 围栏判过的属主),附件哈希随回执交收尾。
+ * `opts` 与留存执行器同一份(附件 / 任务清单两张表在不在是 boot 的事实)。
+ */
+export declare function createSqlSessionEraser(db: SqlDriver, opts: RetentionExecutorOptions): SessionEraser;
 /** (c)(clay 拍 a+c,2026-07-27;[ref] 换店后域=file_history_blob,门与旋钮名不变)云形 blob 姿势门——
- *  boot 时调用(boot/stores.ts),纯函数可单测。SQL 后端(mysql|pg)把 blob 字节落单行的形已被两役
+ *  boot 时调用(boot/stores.ts),纯函数可单测。SQL 后端(mysql|pg)把 blob 字节落单行的形,mysql 腿已被两役
  *  实证撞 mysql-协议包墙(D-1 附件 → 对象存储裁定):大字节归对象存储。per-file 历史的 blob=单文件
  *  字节,同一堵墙(>6MiB 的被 track 文件在 TiDB 上落不进 SQL 行 ⇒ trackEdit 拒 ⇒ 默认 DV-14 下该次
- *  编辑被拒)。云形缺 MinIO ⇒ fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` =
- *  显式接受 SQL 店 + per-blob 帽(单机/测试台形)。local 后端不经此门(file 店,无 SQL 包墙)。 */
+ *  编辑被拒);pg 腿本服务不建模这两堵墙(只有一个 bytea 值的 1 GB 硬上限、没有推出来的缺省帽),同一条裁定、拒句只说各自方言的事实
+ *  ({@link SQL_BLOB_POSTURE_FACTS})。云形缺 MinIO ⇒ fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` =
+ *  显式接受 SQL 店 + per-blob 帽(单机/测试台形;pg 上帽只来自 `SNAPSHOT_BLOB_SQL_MAX_BYTES`)。local 后端不经此门(file 店,无 SQL 包墙)。 */
 export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "local", config: Pick<ServiceConfig, "snapshotBlobStore" | "snapshotBlobAllowSql">): void;
+/** SQL 一次性迁移段的输入(两只 SQL 后端同一份;各条目那一半的来源见 `SqlOneTimeMigrationInput`):M32 的车道表 · M40 的判活窗 = 收割器的同一个窗 · M48 的部署形读数(表里那一行)。 */
+export declare function buildSqlOneTimeMigrationInput(config: ServiceConfig): SqlOneTimeMigrationInput;
 /**
  * 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;
@@ -440,6 +491,8 @@ export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "l
  * projection and its log export — and `undefined` on any other backend. The one place that answers "is there a local store to read rows from".
  */
 export declare function localSessionRowsOf(backend: StoreBackend | undefined): LocalSessionRows | undefined;
+/** local 车道的客户端写计数口(附件店绑定时计数,`session-birth.ts`):本地后端那一只会话店;别的后端 ⇒ `undefined`(SQL 附件店在自己的认领事务里计数)。 */
+export declare function localClientWritesOf(backend: StoreBackend | undefined): Pick<LocalSessionStore, "withClientWrite"> | undefined;
 /**
  * 启动日志里「跨副本 or 进程内」那一格的标签。
  *
@@ -453,6 +506,38 @@ export declare function localSessionRowsOf(backend: StoreBackend | undefined): L
  * 而兄弟行都写 `shared(${kind})`。)
  */
 export declare function counterStoreLabel(store: unknown, kind: string | undefined): string;
+/**
+ * 打开 local 数据根的那一只后端(打开成功的 {@link LocalBackend} 或打开那一刻被拒的 {@link RefusedLocalBackend}):`StoreBackend` 之外多一只口 ——
+ * 引擎 File 后端上**会话店之外**本仓没有自己一份的那几只店({@link LocalEngineFileStores};run-local 的 Runner 接它们)。会话行店不在其中:行只经本仓的会话店读(`session()`)。
+ */
+export interface LocalStoreBackend extends StoreBackend {
+    readonly kind: "local";
+    engineFileStores(): LocalEngineFileStores;
+    /** local 后端恒有(引擎 File 后端的工具结果店;接口上可选的那一口在这里必在)。 */
+    toolResult(): ToolResultStoreFull;
+    /** local 后端恒有(引擎 File 后端的用量窗账本;接口上可选的那一口在这里必在)。 */
+    fileUsageWindowStore(): UsageWindowStore;
+}
+/** 引擎 File 后端上会话店之外、本仓没有自己一份口的店(run-local 的 Runner 接它们;工具结果 / 用量窗 / 会话规则走既有的 `toolResult()` / `fileUsageWindowStore()` / `sessionPolicy()` 口)。 */
+export type LocalEngineFileStores = Pick<FileStorageBackend, "checkpointStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore">;
+/** 打开 local 数据根的入口参数:哪条路在开(只决定拒句的措辞 —— 表头与「换根」半句)与三只 boot 期日志座(见 {@link createStoreBackend})。 */
+export interface LocalBackendOpenOptions {
+    readonly lane: StoreOpenLane;
+    readonly onWarn?: BootLogSink;
+    readonly onError?: BootLogSink;
+    readonly observers?: StoreBackendObservers;
+}
+/**
+ * **local 后端打开数据根**(唯一的路 —— 本仓每一条打开 local 数据根的入口都经它:`createStoreBackend` 的 local 腿(HTTP 服务)与 run-local;一个数据根一只会话行店、一份装配):
+ * 取锁(引擎 File 后端)→ **判与抬引擎版本高水位**({@link holdEngineHighWater},同步一段;判前钩 = 判或记收令牌欠账 {@link holdArchiveTokenAdoptionDuty},抬之前)→ 本仓的店。
+ * 打开之后的公开序列两条入口相同:`ensureSchema()`(起服对账)→ `runOneTimeMigrations()` → 才读会话。
+ * 判与抬住在这里而不是 `ensureSchema()` 里,因为围栏以**第一笔落盘**界定:本仓的店在构造里就会写(撕裂的问账日志留证 + 压实、撕裂的 run 认领挪开、会话收尾的活跃边档落盘),
+ * 判必须先于它们(被拒 = 本仓的店一只都没开、不抬、不改既有文件的字节;判拒发生在钥匙对与空账本已落、店尚未开之后;下一版改为判拒先于任何写),抬必须先于它们(写到一半崩了,水位已是本构建)。所以这一段之后才有店,没有任何一只店先于它。
+ * 拒(判拒 / 本构建版本读不出 / 抬写不进 / 本仓的店构造时抛)⇒ 交回一只 {@link RefusedLocalBackend}:只握着锁,`ensureSchema()` 交出那一只拒(公开序列在它该在的那一步拒,降级臂按拒的族判),
+ * `close()` 只放锁 —— 没有店、没有收尾写。
+ * 残余(如实):引擎 `FileStorageBackend` 的构造把取锁与它自己的店放在同一步(建子目录、店目录锁、撕裂账本尾的收拢)—— 那几笔在判之前,本仓在两者之间没有座(要 core 给)。
+ */
+export declare function openLocalBackend(config: ServiceConfig, opts: LocalBackendOpenOptions): LocalStoreBackend;
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily); the next
  *  step is `ensureSchema()` (retired-schema check, then the CREATEs; it is also the reachability probe), then
  *  `runOneTimeMigrations()`. Returns undefined when no DB is configured.
@@ -463,7 +548,9 @@ export declare function counterStoreLabel(store: unknown, kind: string | undefin
  *  `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 declare function createStoreBackend(config: ServiceConfig, onWarn?: BootLogSink, onError?: BootLogSink): StoreBackend | undefined;
+export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootLogSink, onError?: BootLogSink, observers?: StoreBackendObservers): StoreBackend | undefined;
+/** local 后端的数据根(`createStoreBackend` 交给 `LocalBackend` 的那一只,与 {@link openStoreBackendWithFallback} 的降级判据、起服第 2 段的持久性取证读同一只)。 */
+export declare function localBackendRootOf(config: Pick<ServiceConfig, "localDataRoot">): string;
 /** boot 期打开 store 后端的**统一入口**:构造 + ensureSchema 同罩一层降级臂。
  *
  *  为什么必须把 `createStoreBackend()` 也罩进来(2026-07-28 修):clay 1.292 拍的口径是「裸 boot
@@ -471,7 +558,13 @@ export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootL
  *  而 LocalBackend 的 `ensureSchema` 是**空实现**,真正会抛的 mkdir + 数据根 BootLock 在构造函数里、
  *  落在 try 之外。于是那条降级臂对 local 形从来没生效过,注释宣称的行为与代码真做的事撕裂。
  *
- *  **降级臂只有一条:缺省推导的 local**(`dbBackend=local && !dbBackendExplicit`)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
+ *  **降级臂只有一条:缺省推导的 local 且数据根上什么都没有**(`dbBackend=local && !dbBackendExplicit`,数据根不存在或是空目录 —— 开店之前判)。
+ *  判据看的是**数据根的状态**,不是错误的种类:数据根上已有东西 ⇒ 这台部署有过持久面,开它时的**任何**失败(权限 / 只读挂载 / 子目录建不出 /
+ *  另一实例持锁 / adoption 在飞 / 账本重放不了 …)都按显式 `DB_BACKEND=local` 同待遇 —— 原样抛、拒启,不退内存(退了 = 已有的会话 / run 账本 /
+ *  问账整片看不见、新写只进内存,而 `/health` 照样 200)。只有「数据根不存在 / 空」那一形是「这台机器存不了盘」的诚实等价物,才许退内存 + 一行 warn。
+ *  修前按错误种类逐个豁免(adoption 一条、File 店族拒启一条、再往各店构造器里逐处包),漏一处就是一条 fail-open;按状态判之后,新店的新失败默认落在拒启一侧。
+ *  1.292 的口径据此收窄:只读挂载 / 建不出的根**在空 / 不存在时**仍退内存;已有数据的根拒启(出路:修好权限 / 挂载 / 停掉持锁的另一实例;要内存就显式写
+ *  `DB_BACKEND=memory`;要另起一个空根就把 `LOCAL_DATA_ROOT` 指过去)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
  *  `SESSION_BACKEND=auto` 与显式 `DB_BACKEND=mysql|pg` 同一待遇,库当下打不开 ⇒ 在 `STORE_LOCK_WAIT_MS` 的窗内重试
  *  ({@link openWithinWait}),到窗仍打不开 ⇒ 拒启(拒句 {@link buildSqlStoreOpenRefusal} 点名后端与库的显示安全形)。修前 `auto` 在这里
  *  静默落内存(只留一行 warn):会话 / 停驻 / run 账本进进程内存、重启即丢,而 `/health` 照样 200 —— [ref] P 类 fail-open。
@@ -480,7 +573,7 @@ export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootL
 export declare function openStoreBackendWithFallback(config: ServiceConfig, logger: {
     warn: (msg: string, meta?: Record<string, unknown>) => void;
     error?: (msg: string, meta?: Record<string, unknown>) => void;
-}): Promise<{
+}, observers?: StoreBackendObservers): Promise<{
     backend: StoreBackend | undefined;
     degradedReason: StoreDegradedReason | undefined;
 }>;
@@ -494,8 +587,11 @@ export declare function openStoreBackendWithFallback(config: ServiceConfig, logg
 export declare function sqlStoreCoordinatesAsUrl(config: Pick<ServiceConfig, "dbBackend" | "tidb" | "pg">): string;
 /**
  * SQL 族「配了 DSN 而店打不开(窗内重试过了)」的拒启句(唯一铸点)。点名 `DB_BACKEND=<引擎>`、库的显示安全形(`postgres://host:port` / `mysql://host:port`,经 {@link sqlStoreCoordinatesAsUrl} 拼出、再过 {@link buildDisplaySafeUrl},
- * 不带口令)、等了多久,出路两条:修坐标 / 连通性(窗是 `STORE_LOCK_WAIT_MS`);或**显式**内存部署(`DB_BACKEND=memory`)。🔴 没有第三条
- * 「`SESSION_BACKEND=auto` 内存起服」—— 那一条就是被删掉的静默降级。驱动原文只取 message(与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令)。
+ * 不带口令)、等了多久,出路按**失败类**走(判官 = 整仓一只的 {@link isDeploymentFaultError}),都含**显式**内存部署(`DB_BACKEND=memory`):
+ *  · 库**确定拒**了一条语句(部署错配类:缺表 / 权限拒 / 建外键被拒 …)⇒ 等与改坐标都改变不了答案,出路是库里被点名的那一件(表引擎 / 主键 / 外键相容 / 授权);拒句带库答的 errno / SQLSTATE 原码
+ *    ({@link databaseAnswerCodesOf});
+ *  · 其余(连不上 / 超时 / 认不出)⇒ 修坐标 / 连通性(窗是 `STORE_LOCK_WAIT_MS`)。
+ * 🔴 没有第三条「`SESSION_BACKEND=auto` 内存起服」—— 那一条就是被删掉的静默降级。驱动原文只取 message(与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令);原码段只经闭字符形读取。
  */
 export declare function buildSqlStoreOpenRefusal(engine: "mysql" | "pg", endpoint: string, waitedMs: number, err: unknown): string;
 //# sourceMappingURL=store-backend.d.ts.map