@sema-agent/server 7.150.0 → 7.152.0

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

@@ -3,12 +3,14 @@ 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 { SqlWorkflowRunStore, type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
+import { type WorkflowParkDecisionStore, type WorkflowRecordFenceStore } from "../orchestration/workflow-park-decision.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 LocalWorkflowRunsReader } from "./local-session-live-reference.js";
 import { type LocalStoreDeclaration } from "../local-store-declaration.js";
 import type { LocalSessionRows } from "./local-session-window.js";
 import type { SessionHeadReader } from "./caching-session-store.js";
@@ -22,7 +24,10 @@ import { type MemoryOptOutGrantStore } from "./memory-optout-grant-store-sql.js"
 import { type SendFileLedger } from "./send-file-ledger.js";
 import type { UserInputLedgerStore } from "../user-input-ledger.js";
 import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-store-sql.js";
-import { type SessionPolicyStoreLogger } from "../stores-sql/session-policy-store-sql.js";
+import { SqlSessionPolicyStore } from "../stores-sql/session-policy-store-sql.js";
+import { SqlFileHistoryStore } from "../stores-sql/file-history-store-sql.js";
+import { type LandedAttendantSeat } from "./landed-attendants.js";
+import { type SessionBlobNamespace } from "./session-blob-namespace.js";
 import type { ServiceConfig } from "../config-types.js";
 import { TiDBRunStore, PgRunStore } from "./run-store-sql.js";
 import { TiDBCheckpointStore, PgCheckpointStore } from "../stores-sql/checkpoint-store-sql.js";
@@ -66,7 +71,9 @@ 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;
+/** 回退锚店的部署面:读(`resolve` / `listBySession`)与按会话删 —— **没有写**。锚的生产写口只有落定席位的 `putAnchors`
+ *  ({@link StoreBackend.landedAttendants}:段首锁会话根行判住客,迟到的写落不进别一代住客或空闲 id);店类上的 `put` 是夹具与契约面的同一句语句。 */
+export type ResumeAnchorStore = Pick<TiDBResumeAnchorStore | PgResumeAnchorStore | FileResumeAnchorStore, "resolve" | "listBySession" | "deleteBySession">;
 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";
@@ -106,9 +113,32 @@ export type SqlBlobPutResult = {
 export interface ServiceBlobExchange extends FileHistoryBlobExchange {
     put(hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
 }
+/**
+ * 一次会话同步推送 / 拉取**落在哪一格**(落点):会话 id + 落点属主格 + 门读时这只 id 有没有住客。路由在门判之后经 `landingOf`(`http/routes/session-sync.ts`)铸一次,
+ * 导入租约、blob 授予、blob 可见性三处读同一只;店不解释属主(只按字节存比,无主格记域键 `""`)。
+ *  · `occupied` = 门读时这只 id 被占着(活行 ∪ 在删行,「被占着」的唯一读法)。只有被占着的 id,它的历史图才是来历:空闲 id 上残留的图(删后残留 / 迟到的重放落下的)
+ *    不是任何一位调用方持有过字节的证明,所以空闲落点的可见集只读授予。
+ */
+export interface SyncLanding {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly occupied: boolean;
+}
+/**
+ * blob 的**按落点来历**面(SQL 两孪生有;与 {@link ServiceBlobExchange} 并列,不塞进 core 的交换组 —— core 判官只交回组的三员)。律:一枚 blob 对一个落点可见
+ * ⇔ (落点被占着 ∧ 这只会话的图引用它) ∨ 这个落点自己上传过它(授予),且字节在场;字节仍全局去重一份,可见性另表 —— 两个事实两张表。
+ *  · `putAt`:先核内容地址 → 再写字节(交换组同一写路径)→ **字节写成才**写授予(`granted_at = now`,单调)。答形 = {@link SqlBlobPutResult}(413 / 400 / 502 三臂不变);授予写失败 ⇒ 写失败臂。
+ *  · `visibleAt`:`hashes` 里对这个落点可见的那几枚。先算候选(图项 ∪ 授予项)、只对候选问字节在不在 —— 耗时只随这个落点自己的状态变,不随别人存过什么变。
+ */
+export interface ServiceBlobLanding {
+    putAt(landing: SyncLanding, hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
+    visibleAt(landing: SyncLanding, hashes: readonly string[]): Promise<ReadonlySet<string>>;
+}
 export type ServiceFileHistoryStore = FileHistoryStore & {
     /** The blob exchange (SQL twins only; core's local File store carries none). Narrowed per {@link ServiceBlobExchange}. */
     readonly blobExchange?: ServiceBlobExchange;
+    /** The per-landing provenance face over the same blob domain (SQL twins only) — see {@link ServiceBlobLanding}. The sync routes read blobs only through it. */
+    readonly blobLanding?: ServiceBlobLanding;
     /** E21 purge / overwrite-dst sync wipe: drop the WHOLE scope incl. v1 baselines + DV-14 markers
      *  (`reap(scope, [])` deliberately retains those while the scope lives — not a purge). SQL twins only. */
     deleteBySession?(scope: string): Promise<number>;
@@ -193,7 +223,7 @@ export interface StoreBackend {
     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. */
+     *  map, no cloud-only checkpoint), unlike the optional cloud-only stores below. **恒同一只**(附随店的律见 {@link landedAttendants})。 */
     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). */
@@ -219,8 +249,8 @@ export interface StoreBackend {
      *  (它承诺的是「稍后还能批、崩了行还在」)。机器钉 = `wiring-governance-operator.test.ts` 的
      *  「三腿 approvalAsk 全持久」格。
      *
-     *  无 backend 的 env-only worker 压根没有 `StoreBackend` ⇒ 协调器拿到 undefined askStore ⇒ 车2 的
-     *  D1 逐字现行为(store 缺席 = 现行 `tool_approval` 活卡腿一字不变)。 */
+     *  无 backend 的 env-only worker 压根没有 `StoreBackend` ⇒ 呈卡协议不上场 ⇒ 起服不构造审批协调器(没有「无账协调器」这一形,
+     *  `boot/coordinators.ts`)。 */
     approvalAsk(): ApprovalAskStoreType;
     /**
      * [ref] 车二(core 5.18.0 [ref] + 5.22.0 [ref]):**持久化权限规则店**(「不再询问」车道)
@@ -250,12 +280,20 @@ 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])的点名口(装配点缺省交日志出口接缝的 logger);local(core 的 File 店)不收。 */
-    sessionPolicy(logger?: SessionPolicyStoreLogger): ServiceSessionPolicyStore;
+     *  **恒同一只**(附随店的律见 {@link landedAttendants}):服务面的规则读口、引擎的规则席、E21 抹除与落定席位的规则写都是这一只。
+     *  SQL 孪生抹除封键那一臂([ref])的 warn 经开后端时交的 warn 座(`createStoreBackend` 第二参;缺席 ⇒ 日志出口接缝的缺省 logger)。 */
+    sessionPolicy(): 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
-     *  `FileFileHistoryStore` under the data root). Backs core's RunnerDeps.fileHistoryStore. */
+     *  `FileFileHistoryStore` under the data root). Backs core's RunnerDeps.fileHistoryStore. **恒同一只**(附随店的律见 {@link landedAttendants})。 */
     fileHistory(): ServiceFileHistoryStore;
+    /** 会话附随物(文件历史图 · 会话规则行 · 回退锚)的**唯一写口** —— 落定席位(`plugins/landed-attendants.ts`):每一笔写在一只先锁会话根行、判过住客的段里,
+     *  住客不是那一位 ⇒ 零写。会话同步的落定腿、`PUT /v1/sessions/:id/policy`、运行腿的每轮回退锚都经它。**必选**:SQL 两只后端交一只事务形(与会话店同一只池),
+     *  local 后端交会话写锁一节形;自建后端的嵌入方实现它(没有它,会话同步族答 501)。
+     *  🔴 **附随店的律**:一只后端对 {@link sessionPolicy} / {@link fileHistory} / {@link resumeAnchor} 与本席位各恒交同一只实例,席位写的就是那三只读口交出的店
+     *  (服务面 `ServiceDeps` 上附随店只有这一条读法 —— `deps.backend` —— 没有第二个注入位)。随包三只后端都如此;自建后端的嵌入方同守(写经一只、读经另一只 ⇒
+     *  `PUT …/policy` 答 200 而 `GET` 与引擎读不到这条收紧)。 */
+    landedAttendants(): LandedAttendantSeat;
     /** [ref] §3.1 / [ref] §一([ref] S-2):per-principal **memory-capture opt-out 授权表**
      *  (`memory_optout_grant`)—— `RuntimeCaps.allowMemoryOptOut` 的本地 verdict 源(三层折叠:per-principal
      *  行 → 部署缺省哨兵行 → 代码缺省 allow)+ `/v1/admin/memory-optout` 四端点的持久层。
@@ -289,6 +327,10 @@ export interface StoreBackend {
      *  epoch is gone (its manifest index table retired with it), so EVERY row in that domain is an orphan and its
      *  BYTES (incl. MinIO objects) would otherwise outlive the epoch forever. SQL backends only; reaper-driven. */
     legacySnapshotBlobSweep?(): Promise<number>;
+    /** The session blob namespace this backend's database holds (`session-blob-namespace.ts`): `ensureSchema()` proves it (another database's ⇒ refuse to open),
+     *  and every session blob port of this deployment is built from it (file history and the retired epoch here, attachments at boot). SQL backends with object
+     *  storage configured; absent otherwise (no object storage, or the local backend — its bytes are on its own disk). */
+    sessionBlobNamespace?(): SessionBlobNamespace | undefined;
     /** 🔴 **一次性迁移** —— 落在已写进库里的字节上的退役,升一次级改完、兼容臂当场删干净(硬 breaking 纪律:持久数据面 =
      *  响亮拒 + 一次性迁移,窗过即删,永不长期双读)。逐条语义、幂等与拒启臂见该模块头注。
      *
@@ -319,7 +361,7 @@ export interface StoreBackend {
     /** 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?(onWarn?: InboxWarn): import("@sema-agent/core").WorkflowRunStore;
+    workflowRun?(onWarn?: InboxWarn): SqlWorkflowRunStore;
     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). */
@@ -329,11 +371,12 @@ export interface StoreBackend {
      *  缺席**是一个真答案**:那里的索引家在 run 店同一间屋子里(`LocalWorkflowAgentSessionIndex`,文件账本
      *  或纯内存),不需要经过 backend。契约与单写者纪律的属主 = orchestration/workflow-agent-session-index.ts。 */
     workflowAgentSessionIndex?(): import("../orchestration/workflow-agent-session-index.js").WorkflowAgentSessionIndex;
-    /** workflow 子代停驻卡的耐久决定行(一张卡一行,键 = 子代 checkpoint 的 token),**绑在本后端的 {@link run} 那只 run 店上**(每一笔写都在它的会话认领栅栏里落)。
-     *  与 `run()` 同形:无参、恒交同一只(三孪生同),所以这只决定店绑的就是部署的 run 店。SQL 后端 = 跨副本表,读写走 run 店的池;`local` 后端 = 进程内,
-     *  账本位置由后端按自己的数据根与 `WORKFLOW_RUN_STORE` 定(`<数据根>/workflows/workflow-park-decisions/decisions.jsonl`;`memory` ⇒ 纯内存)。
+    /** workflow 子代停驻卡的耐久决定行(一张卡一行,键 = 子代 checkpoint 的 token),**绑两只栅栏**:本后端的 {@link run} 那只 run 店(认领栅栏)与 `records` ——
+     *  本服务全部 workflow 记录写者经它写的那只记录店(记录栅栏:SQL 后端 = 本后端 `workflowRun()` 交出的 SQL 记录店,同一只池;local 后端 = 基店外那只按 runId 互斥的装饰器)。
+     *  恒交同一只(三孪生同):记录栅栏在第一次交出时绑定,以另一只记录店再取 ⇒ 响亮抛(两只栅栏各管各的就不是同一个仲裁点)。SQL 后端 = 跨副本表,读写走 run 店的池;
+     *  `local` 后端 = 进程内,账本位置由后端按自己的数据根与 `WORKFLOW_RUN_STORE` 定(`<数据根>/workflows/workflow-park-decisions/decisions.jsonl`;`memory` ⇒ 纯内存)。
      *  契约与律的属主 = orchestration/workflow-park-decision.ts。 */
-    workflowParkDecisions?(): import("../orchestration/workflow-park-decision.js").WorkflowParkDecisionStore;
+    workflowParkDecisions?(records: WorkflowRecordFenceStore): WorkflowParkDecisionStore;
     /** 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. */
@@ -434,6 +477,23 @@ export interface StoreBackend {
     fileUsageWindowStore?(): UsageWindowStore;
     /** **local 后端专有**:构造时交给两半店(会话店顶层、检查点店)的那一份声明(唯一读者 `localStoreDeclarationOf`)—— 装配值从这里读回,不重算。SQL 后端省略。 */
     localStoreDeclaration?(): LocalStoreDeclaration;
+    /**
+     * **本进程此刻持锁独占的物理数据根**(正读数;本机控制 socket 开不开口只读它 —— `control-socket.ts` 的前提律):打开成功的 local 后端 ⇒ 引擎 File 后端取锁的那只根
+     * (绝对物理路径,`dataDirLayout.physicalRoot` 同一只),`close()` 之后 ⇒ `undefined`;打开那一刻被拒的 local 后端 ⇒ `undefined`(它的 `kind` 也是 `"local"`,所以判「独占」不读 `kind`)。
+     * SQL 后端省略(省略 = 不独占任何数据根,同 `undefined`)。
+     */
+    exclusiveDataRoot?(): string | undefined;
+    /**
+     * 会话店活引用判的 workflow 那一腿(会话种类的老化;`local-session-live-reference.ts`):本后端的会话店读不到 workflow run 店时(local:那只店在 boot 第 6 段才铸),
+     * 第 6 段把这台部署的 workflow run 店交过来(不起 workflow ⇒ `"none"`);绑一次。SQL 两孪生不实现(它们的判是一句 SQL,读 `workflow_run` 表)。
+     */
+    bindWorkflowRunReader?(reader: LocalWorkflowRunsReader | "none"): void;
+    /**
+     * 「不再询问」规则 project root 的铸卡快照读法(跑这条 run 的副本的会话 cwd 登记;与活卡铸点同一只函数)—— 第 6 段绑一次,本后端的 checkpoint 店写口 `put`
+     * 在停驻那一刻读它落快照(SQL 列 `card_scope_root` / local 快照索引)。未绑 / 不实现(嵌入方的替身后端)⇒ 不可知 ⇒ 不落快照(兑付答 `scope-unresolved`:只会拒)。
+     * 本仓三只后端都实现;形同 {@link bindWorkflowRunReader} 的晚绑。
+     */
+    bindCardScopeRoot?(read: (sessionId: string) => string | undefined): void;
 }
 /**
  * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十三张部署表,
@@ -467,8 +527,13 @@ export declare function createSqlSessionEraser(db: SqlDriver, opts: RetentionExe
  *  ({@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 的车道表 · M52 的判活窗(停-迁-起证据的心跳一半)= 收割器的同一个窗 · M48 的部署形读数(表里那一行)。 */
+/** SQL 一次性迁移段的输入(两只 SQL 后端同一份;各条目那一半的来源见 `SqlOneTimeMigrationInput`):M32 的车道表 · 停-迁-起证据读法的判活窗(守卫段与 M43 读,`stop-then-start.ts`)= 收割器的同一个窗 · M48 的部署形读数(表里那一行)。 */
 export declare function buildSqlOneTimeMigrationInput(config: ServiceConfig): SqlOneTimeMigrationInput;
+/**
+ * SQL 落定席位的组装(两只 SQL 后端同一只;进程内夹具也经它):席位跑在 `db`(这台后端的池)上,写经的就是交进来的这两只店 —— 后端交的是它自己的那一只
+ * (`fileHistory()` / `sessionPolicy()`,读者读的同一只实例);席位只调它们的**语句片**(出口表的 `in-store`)与两只不拨库的判官 / 披露口,锚的语句片住 `resume-anchor-store-sql.ts`。
+ */
+export declare function sqlLandedAttendantsOf(db: SqlDriver, history: SqlFileHistoryStore, policy: SqlSessionPolicyStore): LandedAttendantSeat;
 /**
  * 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;
@@ -527,6 +592,10 @@ export interface LocalStoreBackend extends StoreBackend {
     fileUsageWindowStore(): UsageWindowStore;
     /** local 后端恒有(构造时交给两半店的声明;接口上可选的那一口在这里必在)。 */
     localStoreDeclaration(): LocalStoreDeclaration;
+    /** local 后端恒有(会话店活引用判的 workflow 晚绑座;接口上可选的那一口在这里必在)。 */
+    bindWorkflowRunReader(reader: LocalWorkflowRunsReader | "none"): void;
+    /** local 后端恒有这一口(接口上可选的那一口在这里必在);答 `undefined` 的是拒启的那一只与关过的那一只(见 {@link StoreBackend.exclusiveDataRoot})。 */
+    exclusiveDataRoot(): string | undefined;
 }
 /** 引擎 File 后端上会话店之外、本仓没有自己一份口的店(run-local 的 Runner 接它们;工具结果 / 用量窗 / 会话规则走既有的 `toolResult()` / `fileUsageWindowStore()` / `sessionPolicy()` 口)。 */
 export type LocalEngineFileStores = Pick<FileStorageBackend, "checkpointStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore">;