@sema-agent/server 7.150.0 → 7.151.0

package/dist/plugins/stop-then-start.js

@@ -0,0 +1,104 @@
+import { REPLICA_CAPABILITIES, knowsCapability, readReplicaRegistrations } from "./replica-registration.js";
+import { compareReleaseTriples, releaseTriple } from "./release-version.js";
+import { runningHeartbeatPredicate } from "./run-store-sql.js";
+const isCapability = (id) => REPLICA_CAPABILITIES.includes(id);
+const sameChange = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export function judgeStopThenStart(entry) {
+    const faults = [];
+    if (!isCapability(entry.id))
+        faults.push(`${entry.id} is not in REPLICA_CAPABILITIES (a stop-then-start migration reads evidence only under a capability name)`);
+    if (entry.reason.trim() === "")
+        faults.push(`${entry.id}: reason is empty`);
+    const fence = entry.fence;
+    switch (fence.kind) {
+        case "structural":
+            if (!(entry.shapeChanges ?? []).some((c) => sameChange(c, fence.fencedBy)))
+                faults.push(`${entry.id}: structural fencedBy is not one of the row's shapeChanges`);
+            if (fence.fencedBy.kind === "add")
+                faults.push(`${entry.id}: structural fencedBy is an "add" (adding a column fences no earlier writer)`);
+            break;
+        case "per-write": {
+            const since = releaseTriple(fence.fencedSince);
+            const introduced = releaseTriple(entry.introducedIn);
+            if (since === undefined)
+                faults.push(`${entry.id}: per-write fencedSince "${fence.fencedSince}" is not x.y.z`);
+            if (introduced === undefined)
+                faults.push(`${entry.id}: introducedIn "${entry.introducedIn}" is not x.y.z`);
+            if (since !== undefined && introduced !== undefined && compareReleaseTriples(since, introduced) >= 0) {
+                faults.push(`${entry.id}: per-write fencedSince ${fence.fencedSince} is not earlier than introducedIn ${entry.introducedIn} (the fencing writes must ship at least one release before the migration)`);
+            }
+            if (fence.statements.trim() === "")
+                faults.push(`${entry.id}: per-write statements is empty`);
+            break;
+        }
+        case "accepted":
+            if (fence.residual.trim() === "")
+                faults.push(`${entry.id}: accepted residual is empty`);
+            break;
+        default: {
+            const unhandled = fence;
+            faults.push(`${entry.id}: unknown fence kind ${String(unhandled.kind)}`);
+        }
+    }
+    return faults;
+}
+export async function readOlderReplicaEvidence(db, dialect, input, migrationId) {
+    const scope = dialect === "mysql" ? "DATABASE()" : "current_schema()";
+    if ((await db.rows(`SELECT 1 AS present FROM information_schema.tables WHERE table_schema = ${scope} AND table_name = 'task_run'`)).length === 0)
+        return undefined;
+    const live = runningHeartbeatPredicate(dialect, "live", { nowMs: Date.now(), windowMs: input.liveRunWindowMs }, 1);
+    const groups = (await db.rows(`SELECT instance_id, COUNT(*) AS n, MAX(updated_at) AS newest FROM task_run WHERE ${live.sql} GROUP BY instance_id`, [live.param]))
+        .map((r) => ({ holder: typeof r["instance_id"] === "string" ? r["instance_id"] : undefined, runs: Number(r["n"] ?? 0), newest: r["newest"] }))
+        .filter((g) => g.runs > 0);
+    if (groups.length === 0)
+        return undefined;
+    const registered = await readReplicaRegistrations({ query: async (sql, params) => ({ rows: await db.rows(sql, params), affected: 0 }) }, dialect, groups.flatMap((g) => (g.holder === undefined ? [] : [g.holder])));
+    let unregisteredRuns = 0;
+    let newestMs = Number.NaN;
+    const registeredWithout = [];
+    for (const g of groups) {
+        const r = g.holder === undefined ? undefined : registered.get(g.holder);
+        if (r !== undefined && knowsCapability(r.capabilities, migrationId))
+            continue;
+        if (r === undefined)
+            unregisteredRuns += g.runs;
+        else
+            registeredWithout.push({ instanceId: r.instanceId, releaseLine: r.releaseLine, hostName: r.hostName, pid: r.pid, runs: g.runs });
+        const cell = g.newest instanceof Date ? g.newest : new Date(String(g.newest));
+        if (!Number.isNaN(cell.getTime()) && !(cell.getTime() <= newestMs))
+            newestMs = cell.getTime();
+    }
+    const liveRuns = unregisteredRuns + registeredWithout.reduce((n, h) => n + h.runs, 0);
+    if (liveRuns === 0)
+        return undefined;
+    const now = Date.now();
+    const restartAtMs = (Number.isNaN(newestMs) ? now : newestMs) + input.liveRunWindowMs;
+    return {
+        migration: migrationId,
+        liveRuns,
+        windowSec: Math.round(input.liveRunWindowMs / 1000),
+        restartAfter: new Date(restartAtMs).toISOString(),
+        after: `${new Date(restartAtMs).toISOString()} (${Math.max(0, Math.ceil((restartAtMs - now) / 1000))}s from now)`,
+        unregisteredRuns,
+        registeredWithout: registeredWithout.sort((a, b) => a.instanceId.localeCompare(b.instanceId)),
+    };
+}
+export function assertStopThenStartDeclarations(entries) {
+    const faults = entries.flatMap((e) => judgeStopThenStart(e));
+    if (faults.length > 0) {
+        throw new Error(`stop-then-start: this build declares a stop-then-start migration that contradicts its fence class (a build defect; refused before any statement reached the database): ${faults.join("; ")}`);
+    }
+}
+export async function guardOwedStopThenStart(db, dialect, input, entries) {
+    const read = (sql) => db.rows(sql);
+    for (const entry of entries) {
+        if (!(await entry.owedOn(read, dialect)))
+            continue;
+        if (!isCapability(entry.id))
+            throw new Error(`stop-then-start: ${entry.id} is not in REPLICA_CAPABILITIES`);
+        const evidence = await readOlderReplicaEvidence(db, dialect, input, entry.id);
+        if (evidence !== undefined)
+            throw await entry.refuse(evidence, read, dialect);
+    }
+}
+//# sourceMappingURL=stop-then-start.js.map

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,9 @@ 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 { 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 +70,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";
@@ -193,7 +199,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). */
@@ -250,12 +256,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` 四端点的持久层。
@@ -319,7 +333,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 +343,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 +449,11 @@ export interface StoreBackend {
     fileUsageWindowStore?(): UsageWindowStore;
     /** **local 后端专有**:构造时交给两半店(会话店顶层、检查点店)的那一份声明(唯一读者 `localStoreDeclarationOf`)—— 装配值从这里读回,不重算。SQL 后端省略。 */
     localStoreDeclaration?(): LocalStoreDeclaration;
+    /**
+     * 会话店活引用判的 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;
 }
 /**
  * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十三张部署表,
@@ -467,8 +487,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 +552,8 @@ export interface LocalStoreBackend extends StoreBackend {
     fileUsageWindowStore(): UsageWindowStore;
     /** local 后端恒有(构造时交给两半店的声明;接口上可选的那一口在这里必在)。 */
     localStoreDeclaration(): LocalStoreDeclaration;
+    /** local 后端恒有(会话店活引用判的 workflow 晚绑座;接口上可选的那一口在这里必在)。 */
+    bindWorkflowRunReader(reader: LocalWorkflowRunsReader | "none"): void;
 }
 /** 引擎 File 后端上会话店之外、本仓没有自己一份口的店(run-local 的 Runner 接它们;工具结果 / 用量窗 / 会话规则走既有的 `toolResult()` / `fileUsageWindowStore()` / `sessionPolicy()` 口)。 */
 export type LocalEngineFileStores = Pick<FileStorageBackend, "checkpointStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore">;