@sema-agent/server 7.148.0 → 7.149.0

package/dist/plugins/schema-consistency.js

@@ -1,7 +1,8 @@
 import { recordEnsureStatements } from "./schema-ensure-legs.js";
 import { readLiveColumns } from "./schema-live-columns.js";
 import { SCHEMA_MISMATCH_WAYS_OUT } from "./schema-drift-sentence.js";
-import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, SchemaMismatchRefusedError, StoreBootRefusalError } from "./store-contracts.js";
+import { stopThenStartAction } from "./stop-then-start-sentence.js";
 const QUOTES = new Set(["'", '"', "`"]);
 function stripComments(sql) {
     let out = "";
@@ -263,6 +264,117 @@ export function diffSchema(expected, live) {
     }
     return out;
 }
+function claimedColumnsOf(change) {
+    switch (change.kind) {
+        case "drop":
+            return change.columns;
+        case "rename":
+            return [...change.from, change.to];
+        case "add":
+            return [change.column];
+        case "rebuild":
+            return undefined;
+        default: {
+            const unhandled = change;
+            throw new Error(`unknown pending shape change ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+const WHOLE_TABLE = "*";
+function assertSingleOwnerPerShape(sources) {
+    const owners = new Map();
+    for (const s of sources) {
+        for (const change of s.shapeChanges ?? []) {
+            const table = owners.get(change.table) ?? new Map();
+            owners.set(change.table, table);
+            const columns = claimedColumnsOf(change);
+            const clashes = columns === undefined ? [...table.values()] : [table.get(WHOLE_TABLE), ...columns.map((c) => table.get(c))];
+            const clash = clashes.find((id) => id !== undefined && id !== s.id);
+            if (clash !== undefined)
+                throw new Error(`pending shape: table ${change.table} is changed by both ${clash} and ${s.id} on the same ${columns === undefined ? "table" : "column"} — one shape change has one migration`);
+            for (const c of columns ?? [WHOLE_TABLE])
+                table.set(c, s.id);
+        }
+    }
+}
+function renamedColumn(dialect, old, declared) {
+    switch (dialect) {
+        case "mysql":
+            return declared();
+        case "pg":
+            return old;
+        default: {
+            const unhandled = dialect;
+            throw new Error(`unknown SQL dialect ${String(unhandled)}`);
+        }
+    }
+}
+export function projectPendingShape(expected, live, sources, dialect) {
+    assertSingleOwnerPerShape(sources);
+    const out = new Map([...live].map(([t, cols]) => [t, new Map(cols)]));
+    const declaredNullable = (table, column) => {
+        const col = expected.get(table)?.columns.find((c) => c.name === column);
+        if (col === undefined)
+            throw new Error(`pending shape: ${table}.${column} is not declared by this build's schema — a migration can only bring a column the build declares`);
+        return { nullable: !declaresNotNull(col) };
+    };
+    const applied = new Set();
+    for (const s of sources) {
+        for (const change of s.shapeChanges ?? []) {
+            const before = live.get(change.table);
+            const after = out.get(change.table);
+            if (before === undefined || after === undefined)
+                continue;
+            switch (change.kind) {
+                case "drop": {
+                    const present = change.columns.filter((c) => before.has(c));
+                    for (const c of present)
+                        after.delete(c);
+                    if (present.length > 0)
+                        applied.add(s.id);
+                    break;
+                }
+                case "rename": {
+                    const present = change.from.filter((c) => before.has(c));
+                    if (before.has(change.to) || present.length !== 1)
+                        break;
+                    const [from] = present;
+                    after.set(change.to, renamedColumn(dialect, before.get(from), () => declaredNullable(change.table, change.to)));
+                    after.delete(from);
+                    applied.add(s.id);
+                    break;
+                }
+                case "add": {
+                    if (before.has(change.column))
+                        break;
+                    const gate = change.whilePresent;
+                    if (gate !== undefined && !gate.anyOf.some((c) => live.get(gate.table)?.has(c) === true))
+                        break;
+                    after.set(change.column, declaredNullable(change.table, change.column));
+                    applied.add(s.id);
+                    break;
+                }
+                case "rebuild": {
+                    if (!before.has(change.whilePresent))
+                        break;
+                    const shape = expected.get(change.table);
+                    if (shape === undefined)
+                        throw new Error(`pending shape: ${change.table} is rebuilt by ${s.id} but this build declares no such table`);
+                    if (shape.columns.some((c) => !change.supplies.includes(c.name) && !before.has(c.name)))
+                        break;
+                    out.set(change.table, new Map(shape.columns.map((c) => [c.name, { nullable: !declaresNotNull(c) }])));
+                    applied.add(s.id);
+                    break;
+                }
+                default: {
+                    const unhandled = change;
+                    throw new Error(`unknown pending shape change ${JSON.stringify(unhandled)}`);
+                }
+            }
+        }
+    }
+    return { projected: out, appliedBy: sources.filter((s) => applied.has(s.id)).map((s) => s.id) };
+}
 function tightenLines(dialect, table, c) {
     switch (dialect) {
         case "pg":
@@ -337,34 +449,91 @@ export function describeMismatchedTables(dialect, mismatches) {
     lines.push("", ...SCHEMA_MISMATCH_WAYS_OUT);
     return lines;
 }
-export function describeSchemaMismatch(dialect, mismatches) {
+function needsStatements(mismatches) {
+    return mismatches.some((m) => m.missing.length > 0 || m.tightened.length > 0);
+}
+export async function describeUpgradeChecklist(mismatches) {
+    if (!needsStatements(mismatches))
+        return [];
+    const { stopThenStartMigrations } = await import("./one-time-migrations.js");
+    const stops = stopThenStartMigrations();
+    const steps = [["Run every statement printed below, each recipe in the order it is printed (a printed comment line marks a value only you can choose) — all tables at once, before anything else (this build never alters a database for you)."]];
+    if (stops.length > 0) {
+        steps.push([
+            "Stop-then-start one-time migrations: this build runs them itself on its first boot (no statement from you), and each refuses to start — writing nothing — while any run on this database has",
+            "heartbeated within REAP_RUN_STALE_SEC. A database that has already been through one of them is not asked again.",
+            ...stops.map((m) => `  - ${m.id}: ${m.reason}`),
+            stopThenStartAction(),
+        ]);
+    }
+    steps.push(["Start this version; the one-time migrations above (if any are still owed) run on that boot."]);
+    return [
+        "Upgrade checklist — everything this build needs from you on this database, in this order (one start lists all of it; do not fix one table and retry):",
+        ...steps.flatMap((lines, i) => lines.map((l, k) => (k === 0 ? `  ${i + 1}. ${l}` : `     ${l}`))),
+    ];
+}
+export function describeSchemaMismatch(dialect, mismatches, checklist = []) {
     const lines = [
         `${SCHEMA_MISMATCH_ERROR_CODE}: the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database does not match this build's schema — refusing to start.`,
         "Schema policy: the code is the single source of truth, and the column check that produced this refusal never alters a database —",
         "so a drifted database is a deployment-order problem, not something the process may quietly work around.",
         "",
+        ...(checklist.length > 0 ? [...checklist, ""] : []),
         ...describeMismatchedTables(dialect, mismatches),
     ];
     return lines.join("\n");
 }
-export async function assertSchemaMatchesCode(read, dialect) {
+export async function statementBearing(expected, live, dialect) {
+    const { ONE_TIME_MIGRATIONS } = await import("./one-time-migrations.js");
+    return diffSchema(expected, projectPendingShape(expected, live, ONE_TIME_MIGRATIONS, dialect).projected)
+        .map((m) => ({ ...m, ghost: [] }))
+        .filter((m) => m.missing.length > 0 || m.tightened.length > 0);
+}
+export async function describeUpgradeBody(dialect, mismatches) {
+    const checklist = await describeUpgradeChecklist(mismatches);
+    return [...(checklist.length > 0 ? [...checklist, ""] : []), ...describeMismatchedTables(dialect, mismatches)];
+}
+export const DRIFT_TAIL_DEADLINE_MS = 10_000;
+export async function describeUpgradeDriftTail(read, dialect, deadlineMs = DRIFT_TAIL_DEADLINE_MS) {
+    let mismatches;
+    let timer;
+    try {
+        const work = (async () => statementBearing(await expectedTableShapes(dialect), await readLiveColumns(read, dialect), dialect))();
+        work.catch(() => undefined);
+        const expired = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`no answer within ${deadlineMs} ms`)), deadlineMs);
+            timer.unref?.();
+        });
+        mismatches = await Promise.race([work, expired]);
+    }
+    catch (err) {
+        return `\n\nThe column check could not be read here (${err instanceof Error ? err.message : String(err)}), so any ALTER this database still owes is not listed in this refusal — the column check at boot lists them.`;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (mismatches.length === 0)
+        return "";
+    return `\n\nThis database also does not match this build's schema — the statements below are the ones the column check prints at boot:\n${(await describeUpgradeBody(dialect, mismatches)).join("\n")}`;
+}
+export async function assertSchemaMatchesCode(read, dialect, pending) {
     const expected = await expectedTableShapes(dialect);
     let live;
     try {
         live = await readLiveColumns(read, dialect);
     }
     catch (err) {
-        throw new Error(`${SCHEMA_MISMATCH_ERROR_CODE}: could not read information_schema.columns to verify the ${dialect} schema — refusing to start ` +
+        throw new SchemaMismatchRefusedError(`${SCHEMA_MISMATCH_ERROR_CODE}: could not read information_schema.columns to verify the ${dialect} schema — refusing to start ` +
             `(an unverifiable schema is treated as a mismatch, not as a pass): ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
     if (live.size === 0) {
-        throw new Error(`${SCHEMA_MISMATCH_ERROR_CODE}: information_schema.columns returned no rows anywhere on this ${dialect} connection's schema path — refusing to start. ` +
+        throw new SchemaMismatchRefusedError(`${SCHEMA_MISMATCH_ERROR_CODE}: information_schema.columns returned no rows anywhere on this ${dialect} connection's schema path — refusing to start. ` +
             `Either the connection points at an empty/foreign schema, or the account cannot see its own catalog; both make the ` +
             `"database matches the code" check unprovable, and an unprovable protective check never passes.`);
     }
-    const mismatches = diffSchema(expected, live);
+    const mismatches = diffSchema(expected, projectPendingShape(expected, live, pending, dialect).projected);
     if (mismatches.length > 0)
-        throw new Error(describeSchemaMismatch(dialect, mismatches));
+        throw new SchemaMismatchRefusedError(describeSchemaMismatch(dialect, mismatches, await describeUpgradeChecklist(mismatches)));
 }
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT = { table: "checkpoint", column: "pending_steer" };

package/dist/plugins/schema-drift-sentence.d.ts

@@ -1,4 +1,5 @@
 import type { SqlDialect } from "./sql-driver.js";
+import { SchemaMismatchRefusedError } from "./store-contracts.js";
 /** 「库比构建旧」那一条出路的两个可变件:旧在哪(括注)、部署者要自己做的那件事。其余字一个不变。 */
 export interface OlderWayOut {
     /** 括注:库旧在哪(例:`missing columns`)。 */
@@ -20,11 +21,11 @@ export declare const SCHEMA_MISMATCH_WAYS_OUT: readonly string[];
 export type ProbeQuery = (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>;
+/** 单表探针的拒启(缺列、键宽不够)的出口:`body` 是码之后的整句,码在这里领头 —— 各探针不自己拼码。 */
+export declare function schemaMismatchRefusal(body: string): SchemaMismatchRefusedError;
 /**
- * 单表探针抓到可证缺列后,拒因里「哪几列缺、该跑哪几条 ALTER」+ 闭集出路这一整段(多行文本,不含探针自己的首句与底层错误)。
- *
- * 读不出库的列册(权限 / 超时)或对账看不到探针点名的表有缺列(探针与建表语句互相矛盾)⇒ **响亮**地说「ALTER 没能打印」及原因,
- * 出路仍是同一份闭集(旧一条改成「按建表语句自己加」)—— 绝不退回销毁性指路,也不悄悄吞掉这一段。
+ * 单表探针抓到可证缺列后的**整条拒启**(唯一铸点;`throw await probedMissingColumnRefusal(…)`):探针自己的首句 `lead`(这张表缺什么、缺了会在哪里坏;不带码、不带换行收尾)
+ * + 底层驱动错误 `underlying`(运维要看见是哪条探针读撞的)+ {@link describeProbedTableDrift} 的逐表段与闭集出路,码领头({@link schemaMismatchRefusal})。
  */
-export declare function describeProbedTableDrift(query: ProbeQuery, dialect: SqlDialect, tables: readonly string[]): Promise<string>;
+export declare function probedMissingColumnRefusal(query: ProbeQuery, dialect: SqlDialect, tables: readonly string[], lead: string, underlying: unknown): Promise<SchemaMismatchRefusedError>;
 //# sourceMappingURL=schema-drift-sentence.d.ts.map

package/dist/plugins/schema-drift-sentence.js

@@ -1,4 +1,5 @@
 import { readLiveColumns } from "./schema-live-columns.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, SchemaMismatchRefusedError } from "./store-contracts.js";
 export function schemaWaysOut(older) {
     return [
         "  Ways out (these three and no others):",
@@ -11,16 +12,23 @@ export const SCHEMA_MISMATCH_WAYS_OUT = schemaWaysOut({
     when: "missing columns, or columns that allow NULL where this build declares NOT NULL",
     action: "run the statements printed above yourself (where a column needs a value this build cannot choose for rows already in the table, the printed comment says so and that value is yours; this refusal stays until every printed statement has taken effect)",
 });
-export async function describeProbedTableDrift(query, dialect, tables) {
+export function schemaMismatchRefusal(body) {
+    return new SchemaMismatchRefusedError(`${SCHEMA_MISMATCH_ERROR_CODE}: ${body}`);
+}
+export async function probedMissingColumnRefusal(query, dialect, tables, lead, underlying) {
+    return schemaMismatchRefusal(`${lead}\n` +
+        `Underlying probe error: ${underlying instanceof Error ? underlying.message : String(underlying)}\n\n` +
+        (await describeProbedTableDrift(query, dialect, tables)));
+}
+async function describeProbedTableDrift(query, dialect, tables) {
     const d = dialect === "pg" ? "pg" : "mysql";
     const read = async (sql) => (await query(sql)).rows;
     let why;
     try {
         const sc = await import("./schema-consistency.js");
-        const diff = sc.diffSchema(await sc.expectedTableShapes(d), await readLiveColumns(read, d));
-        const missingOnly = diff.filter((m) => tables.includes(m.table) && m.missing.length > 0).map((m) => ({ ...m, ghost: [], tightened: [] }));
-        if (missingOnly.length > 0)
-            return sc.describeMismatchedTables(d, missingOnly).join("\n");
+        const diff = await sc.statementBearing(await sc.expectedTableShapes(d), await readLiveColumns(read, d), d);
+        if (diff.some((m) => tables.includes(m.table) && m.missing.length > 0))
+            return (await sc.describeUpgradeBody(d, diff)).join("\n");
         why = "this build's table definitions list no column that the database lacks on that table, so the probe and the definitions disagree";
     }
     catch (err) {

package/dist/plugins/session-placement.d.ts

@@ -37,8 +37,9 @@ import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementReco
 import type { ForkPlacement } from "./session-fork.js";
 /**
  * 三只持久会话店(SQL 两孪生 + local 后端)的**会话耐久声明**(core `SessionStore.durability`:未 placed 的会话活不活过进程重启)——
- * **单源**:三处声明(两孪生类上的顶层 `durability`、`LocalBackend` 交给店的顶层 `durability`)与委派分区的 {@link SESSION_PLACEMENTS}
- * 引用的都是这一只常量,源码里不再有第二份 `"durable"` 字面(`test/session-store-durability-declaration.test.ts` 的 AST 钉)。
+ * **单源**:两孪生类上的顶层 `durability` 与委派分区的 {@link SESSION_PLACEMENTS} 引用的都是这一只常量;local 后端交给两半店(会话店顶层、
+ * 检查点店)的声明由 `local-store-declaration.ts` 的读者定,它的「店型的设计声明」一臂就是这一只常量(运维声明易失 / 店落在调用方自己那块易失盘上 ⇒ `process-local`)。
+ * 源码里不再有第二份 `"durable"` 字面(`test/session-store-durability-declaration.test.ts` 的 AST 钉)。
  *
  * 为什么必须声明:core 的静态装配对**缺席**折 `"process-local"`(它不能替没表态的店猜),接线清单 `session.store` 与起服自检读的就是它 ——
  * 不声明 ⇒ 一个真持久的 SQL 部署读成「重启即丢」,没有任何一处报错。依据同下面分区声明那一段:两孪生的会话史落在 `session_meta` + `session_event` 两张真表,
@@ -47,8 +48,8 @@ import type { ForkPlacement } from "./session-fork.js";
  */
 export declare const SESSION_DURABILITY: "durable";
 /**
- * 三只持久会话店的 placement **声明**(core `SessionStore.placements`):两支 SQL 孪生(类上的字段)与 local 后端
- * (`LocalBackend` 装配 `LocalSessionStore` 时交进去 —— 值与 core `FileStorageBackend` 对同一种文件 repo 的声明同)。
+ * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`,类上的字段)。local 后端装配 `LocalSessionStore` 时交进去的分区声明与它同形,
+ * 耐久取 local 店的那一份声明(`local-store-declaration.ts`;设计声明一臂与这里同值,与 core `FileStorageBackend` 对同一种文件 repo 的声明同)。
  *
  * 🔴 声明制,不是鸭子类型:core 的铸造门判「row store ∧ session 店声明」,不声明的店**不收** placed
  * 语义(合法降级:placement 参数被忽略,会话就是普通会话)。所以这一格只有在上面六条义务**全部**在

package/dist/plugins/shell-sentinel-owner-m48.d.ts

@@ -1,3 +1,4 @@
+import type { SqlDialect } from "./sql-driver.js";
 /**
  * 一次性迁移 **M48** 的唯一属主(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表;随 M48 删整个文件)。
  *
@@ -13,8 +14,29 @@
  * 改写面 = 曾放那一格的读面读属主的那几处:SQL `session_meta` / `task_run` / `leader_run` 的 `owner` 列;local 会话元数据边档那一格的 `owner`、
  * `FileRunStore` 的 run 行 `owner`(local 没有 leader run 店)。不改的(如实):规则行(存在哨兵键下的规则此前也不对无主体任务生效,改键 = 放宽,不做)、
  * 收件箱条目 / 问账行 / 检查点 scope(这些读面从没放过那一格)。
+ *
+ * **有身份边界的部署不改写,但不零信号**:部署形读数取自**起服的那一个进程**的配置,而改写落在整只库 / 数据根上、不可逆 ⇒ 同一只库 / 根被身份配置不同的进程打开
+ * (`run-local` 不带服务凭据 / 桥、嵌入方先于验签器装配的起服序列、连着共享库的临时进程)时,一样身份键都不带的那个进程先起,会替有边界的服务进程把行改成无主(边界是任一身份来源在的并 —— 改写只在一样都没有时发生)。
+ * 有边界的进程自己只看见「零改写」,不数一数就不知道库里还留着多少行 ⇒ 那一臂对**同一批改写面**用**同一个比较**数一遍(不写,不改),读数 {@link ShellSentinelOwnerRowsRetained}
+ * 逐面列非零的计数,起服日志一行 warn(`shell_sentinel_rows_retained`)。比较只有一份:SQL 的 {@link shellSentinelOwnerWhereM48}(改写的 `UPDATE` 与计数的 `SELECT COUNT(*)` 共用),
+ * local 的 {@link isShellSentinelOwnerM48}(会话元数据格与 run 行的改写和计数共用)。
  */
 export declare const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
 /** SQL 腿改写 `owner` 列的表(曾放那一格的读面读属主的表;local 腿的对应面见文件头)。 */
 export declare const SHELL_SENTINEL_OWNER_TABLES_M48: readonly ["session_meta", "task_run", "leader_run"];
+/** 改写面的词(留存读数与日志的逐面计数键):SQL = 表名;local 腿借同一组词 —— `session_meta` = 会话元数据格、`task_run` = run 行(local 没有 leader run 店 ⇒ 不出 `leader_run`)。 */
+export type ShellSentinelOwnerSurfaceM48 = (typeof SHELL_SENTINEL_OWNER_TABLES_M48)[number];
+/** 留存读数的一只:有身份边界的部署上,这一面还留着多少行哨兵属主(只列非零的面)。 */
+export interface ShellSentinelOwnerRowsRetained {
+    readonly surface: ShellSentinelOwnerSurfaceM48;
+    readonly rows: number;
+}
+/**
+ * SQL 腿「这一行是哨兵属主」的比较(**唯一一份**;改写的 `UPDATE … SET owner = NULL WHERE <此>` 与留存计数的 `SELECT COUNT(*) … WHERE <此>` 共用,绑定参数同为 {@link SHELL_SENTINEL_OWNER_M48})。
+ * 值**逐字节**比:MySQL 协议的 `utf8mb4_bin` 是 PAD SPACE(`'a' = 'a '`),普通等值会把只差尾空格的另一位属主(合法主体名)也当哨兵 ——
+ * 与 M17 / M18 的 CAS 同一写法 `CAST(… AS BINARY)`;PG `text` 等值本就逐字节。
+ */
+export declare function shellSentinelOwnerWhereM48(dialect: SqlDialect): string;
+/** local 腿「这一行 / 格的属主是哨兵」的比较(**唯一一份**;会话元数据格与 run 行的改写、留存计数共用 —— 严格相等,与 SQL 腿的逐字节比同义)。 */
+export declare function isShellSentinelOwnerM48(owner: string | null | undefined): boolean;
 //# sourceMappingURL=shell-sentinel-owner-m48.d.ts.map

package/dist/plugins/shell-sentinel-owner-m48.js

@@ -1,3 +1,9 @@
 export const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
 export const SHELL_SENTINEL_OWNER_TABLES_M48 = ["session_meta", "task_run", "leader_run"];
+export function shellSentinelOwnerWhereM48(dialect) {
+    return dialect === "mysql" ? "CAST(owner AS BINARY) = CAST(? AS BINARY)" : "owner = $1";
+}
+export function isShellSentinelOwnerM48(owner) {
+    return owner === SHELL_SENTINEL_OWNER_M48;
+}
 //# sourceMappingURL=shell-sentinel-owner-m48.js.map

package/dist/plugins/stop-then-start-sentence.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 「停-迁-起」那一段的**唯一属主**。
+ *
+ * 一次性迁移里有几条(登记表 `stopThenStart` 一格点名的)改的是更早版本的副本还会继续写的形:改完之后它再写一笔,这一笔读不出 / 丢掉。它们没有运行期开关,
+ * 起服时由守卫判 —— 判活窗内(`REAP_RUN_STALE_SEC`,收割器判 run 持有者还活着的同一个窗)库里还有 `running` run 在心跳 ⇒ 拒启、一字节不写。
+ * 四只守卫(M40 · M41 · M42 · M51)的拒句和起服列册对账的升级清单**说同一件事**:先停光更早版本的副本、等满判活窗、再起本版。
+ * 这件事的句子只在这里写一遍;各守卫只讲「为什么这一条要停」,不各抄一份动作段。
+ *
+ * 叶子模块:零 import(守卫所在的一次性迁移文件、M42 的拒句文件与列册对账都静态 import 它,不成环)。
+ */
+/**
+ * 动作段:停光 → 等窗 → 再起。`after` = 全停之后可以再起的最早时刻(守卫读到的最新心跳 + 判活窗,人读形);
+ * 缺席 ⇒ 读不到具体心跳(列册对账的清单:此刻没有守卫在判),只说「等满判活窗」。
+ */
+export declare function stopThenStartAction(after?: string): string;
+//# sourceMappingURL=stop-then-start-sentence.d.ts.map

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

@@ -0,0 +1,7 @@
+export function stopThenStartAction(after) {
+    return ("Stop every replica of the earlier version, then start this version (stop, migrate, start — this release cannot be rolled across replicas of both versions). " +
+        (after === undefined
+            ? "Wait out the heartbeat window (REAP_RUN_STALE_SEC) after the last replica stops, then start this version."
+            : `If every replica is already stopped, those are the runs they left behind: start this version again after ${after}`));
+}
+//# sourceMappingURL=stop-then-start-sentence.js.map

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

@@ -9,6 +9,7 @@ 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 LocalStoreDeclaration } from "../local-store-declaration.js";
 import type { LocalSessionRows } from "./local-session-window.js";
 import type { SessionHeadReader } from "./caching-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
@@ -41,9 +42,10 @@ 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 LocalDataRootAdmission } from "./local-data-root-admission.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 import { type SqlDriver } from "./sql-driver.js";
-import { type StoreDegradedReason } from "../store-posture.js";
+import { type StoreDegradedReason, type StoreDurability as MediumDurability } from "../store-posture.js";
 /** boot 期的一条日志座(级别由**座位**决定,不由参数携带):`createStoreBackend` 的 `onWarn` / `onError`
  *  两参与 `LocalBackend` 的同名字段共用此形。装配层把它们分别接到 `logger.warn` / `logger.error` 上。 */
 export type BootLogSink = (msg: string, meta?: Record<string, unknown>) => void;
@@ -54,6 +56,10 @@ export type BootLogSink = (msg: string, meta?: Record<string, unknown>) => void;
 export interface StoreBackendObservers {
     readonly runStallVerdicts?: (landed: number) => void;
 }
+/** 开店时递进来的起服事实(只 local 腿读):数据根介质的判定(起服第 2 段的取证;缺席 = 这条入口没有起服证据 ⇒ 按 `unknown` 读 —— 判不出的介质不放宽 local 店的声明)。 */
+export interface StoreOpenFacts {
+    readonly dataRootMedium?: MediumDurability;
+}
 /** run 店落死亡判决的两样:窗 = 后端持有的配置对象的 `runStaleSec`(热发布原地改写 ⇒ getter 读到热值;判活窗只有这一个来源)+ 计数座。 */
 export declare function createRunStallWiring(config: Pick<ServiceConfig, "runStaleSec">, observers: StoreBackendObservers | undefined): RunStallWiring;
 export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
@@ -426,6 +432,8 @@ export interface StoreBackend {
      *  拒绝句不带盘上位置)的同时,路径进本 backend 的 `file_store_corrupt_read` 披露座(逐命中 warn)。修前 `boot/stores.ts` 在同一数据根上自己
      *  `new FileUsageWindowStore(root)` 第二只实例、不接座 ⇒ 坏值只拒不披露,运维找不到是哪只文件。SQL 后端省略(它们有自己的 usage-window 双方言店)。 */
     fileUsageWindowStore?(): UsageWindowStore;
+    /** **local 后端专有**:构造时交给两半店(会话店顶层、检查点店)的那一份声明(唯一读者 `localStoreDeclarationOf`)—— 装配值从这里读回,不重算。SQL 后端省略。 */
+    localStoreDeclaration?(): LocalStoreDeclaration;
 }
 /**
  * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十三张部署表,
@@ -517,25 +525,31 @@ export interface LocalStoreBackend extends StoreBackend {
     toolResult(): ToolResultStoreFull;
     /** local 后端恒有(引擎 File 后端的用量窗账本;接口上可选的那一口在这里必在)。 */
     fileUsageWindowStore(): UsageWindowStore;
+    /** local 后端恒有(构造时交给两半店的声明;接口上可选的那一口在这里必在)。 */
+    localStoreDeclaration(): LocalStoreDeclaration;
 }
 /** 引擎 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;
+    /** 这只根的数据根准入读数(必填;{@link admitLocalDataRoot} 铸,调用方在它对这只根的第一笔写之前取 —— 打开就是第一笔写的调用方当场取,见 {@link createStoreBackend})。 */
+    readonly admission: LocalDataRootAdmission;
     readonly onWarn?: BootLogSink;
     readonly onError?: BootLogSink;
     readonly observers?: StoreBackendObservers;
+    /** 起服事实(数据根介质的判定;HTTP 服务递第 2 段的取证,缺席 ⇒ `unknown`)。 */
+    readonly facts?: StoreOpenFacts;
 }
 /**
  * **local 后端打开数据根**(唯一的路 —— 本仓每一条打开 local 数据根的入口都经它:`createStoreBackend` 的 local 腿(HTTP 服务)与 run-local;一个数据根一只会话行店、一份装配):
- * 取锁(引擎 File 后端)→ **判与抬引擎版本高水位**({@link holdEngineHighWater},同步一段;判前钩 = 判或记收令牌欠账 {@link holdArchiveTokenAdoptionDuty},抬之前)→ 本仓的店。
+ * 数据根准入(调用方交来的读数 `opts.admission`,判已在本进程第一笔写之前做完)→ 取锁(引擎 File 后端:建根、锁文件、引擎自己的店目录与空账本)→
+ * **锁内一步**({@link holdLocalDataRootAdmission}:核物理数据根与准入那一次观察都没动 → 跳版臂记 / 销账 → 抬引擎版本高水位)→ 本仓的店。
  * 打开之后的公开序列两条入口相同:`ensureSchema()`(起服对账)→ `runOneTimeMigrations()` → 才读会话。
- * 判与抬住在这里而不是 `ensureSchema()` 里,因为围栏以**第一笔落盘**界定:本仓的店在构造里就会写(撕裂的问账日志留证 + 压实、撕裂的 run 认领挪开、会话收尾的活跃边档落盘),
- * 判必须先于它们(被拒 = 本仓的店一只都没开、不抬、不改既有文件的字节;判拒发生在钥匙对与空账本已落、店尚未开之后;下一版改为判拒先于任何写),抬必须先于它们(写到一半崩了,水位已是本构建)。所以这一段之后才有店,没有任何一只店先于它。
- * 拒(判拒 / 本构建版本读不出 / 抬写不进 / 本仓的店构造时抛)⇒ 交回一只 {@link RefusedLocalBackend}:只握着锁,`ensureSchema()` 交出那一只拒(公开序列在它该在的那一步拒,降级臂按拒的族判),
- * `close()` 只放锁 —— 没有店、没有收尾写。
- * 残余(如实):引擎 `FileStorageBackend` 的构造把取锁与它自己的店放在同一步(建子目录、店目录锁、撕裂账本尾的收拢)—— 那几笔在判之前,本仓在两者之间没有座(要 core 给)。
+ * 抬住在这里而不是 `ensureSchema()` 里,因为围栏以**第一笔落盘**界定:本仓的店在构造里就会写(撕裂的问账日志留证 + 压实、撕裂的 run 认领挪开、会话收尾的活跃边档落盘),
+ * 抬必须先于它们(写到一半崩了,水位已是本构建)。所以这一段之后才有店,没有任何一只店先于它。
+ * 锁内一步拒(准入判过的输入在准入之后被另一只引擎动过 / 记账或抬写不进)或本仓的店构造时抛 ⇒ 交回一只 {@link RefusedLocalBackend}:只握着锁,`ensureSchema()` 交出那一只拒
+ * (公开序列在它该在的那一步拒,降级臂按拒的族判),`close()` 只放锁 —— 没有店、没有收尾写。
  */
 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
@@ -573,7 +587,7 @@ export declare function localBackendRootOf(config: Pick<ServiceConfig, "localDat
 export declare function openStoreBackendWithFallback(config: ServiceConfig, logger: {
     warn: (msg: string, meta?: Record<string, unknown>) => void;
     error?: (msg: string, meta?: Record<string, unknown>) => void;
-}, observers?: StoreBackendObservers): Promise<{
+}, observers?: StoreBackendObservers, localAdmission?: LocalDataRootAdmission, facts?: StoreOpenFacts): Promise<{
     backend: StoreBackend | undefined;
     degradedReason: StoreDegradedReason | undefined;
 }>;