@sema-agent/server 7.149.0 → 7.150.0

package/dist/plugins/remote-env-host.js

@@ -2,6 +2,7 @@ import { writeLogText } from "../observability/logger.js";
 import { spawn } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync, accessSync, constants as FS_CONST } from "node:fs";
@@ -12,7 +13,7 @@ import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
-import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, physicalPathOf as kernelRealPathOf, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { LaneHomeSeat, laneHomeRefusal } from "../lane-home-probe.js";
@@ -1004,7 +1005,7 @@ export class RemoteHostExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.join(...parts));
+        return ok(joinedPath(path, parts));
     }
     async readTextFile(p, abortSignal) {
         const ready = await this.fsReady(p);
@@ -1106,7 +1107,7 @@ export class RemoteHostExecutionEnv {
             const entries = await fs.readdir(abs, { withFileTypes: true });
             const out = [];
             for (const e of entries) {
-                const child = path.join(abs, e.name);
+                const child = anchorUnder(path, abs, e.name);
                 let size = 0;
                 let mtimeMs = 0;
                 try {
@@ -1247,7 +1248,7 @@ export class RemoteHostExecutionEnv {
         });
     }
     resolve(p) {
-        return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
+        return anchoredPath(path, this.cwd, p);
     }
     assertWorkspaceParentWritable() {
         const uid = process.getuid?.();
@@ -1324,14 +1325,22 @@ export class RemoteHostExecutionEnv {
         const abs = this.resolve(p);
         if (!existsSync(abs))
             return false;
-        const real = (x) => { try {
-            return realpathSync(x);
-        }
-        catch {
-            return path.resolve(x);
-        } };
+        const real = (x) => {
+            try {
+                return kernelRealPathOf(x);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const target = real(abs);
+        if (target === undefined)
+            return false;
         const inside = (root) => {
-            const rel = path.relative(real(root), real(abs));
+            const r = real(root);
+            if (r === undefined)
+                return false;
+            const rel = path.relative(r, target);
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
         return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.tenure.kind === "borrowed" && inside(this.workspaceDir));

package/dist/plugins/remote-env-k8s.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 import { readFileSync } from "node:fs";
 import https from "node:https";
 import http from "node:http";
@@ -300,7 +301,7 @@ export class RemoteK8sExecutionEnv {
         return this.cfg.timeoutMs;
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return { sandboxId: this.podName ?? "(unconnected)", provider: PROVIDER, mountPath: this.cwd, ...(this.handleSnapshotId ? { snapshotId: this.handleSnapshotId } : {}) };
@@ -2196,7 +2197,7 @@ export class RemoteK8sExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readBinaryFile(p, abortSignal) {
         const abs = this.resolve(p);

package/dist/plugins/remote-env-local-docker.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
@@ -89,7 +90,7 @@ export class RemoteLocalDockerExecutionEnv {
         return this.teardownSettled && this.leftover === undefined;
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cfg.mountPath };
@@ -618,7 +619,7 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readBinaryFile(p, abortSignal) {
         const ready = await this.fsReady(p, abortSignal);

package/dist/plugins/remote-env-ssh.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import { Client } from "ssh2";
 import { createSshHostKeyVerifier } from "../ssh-host-key.js";
 import { appendFileStaged, buildCwdEnvCommand, createCwdGuardedCall, kindFromMode, writeFileStaged } from "./remote-shell.js";
@@ -57,7 +58,7 @@ export class RemoteSshExecutionEnv {
         this.homeSeat = new LaneHomeSeat(PROVIDER, config);
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return { sandboxId: `${this.cfg.host}:${this.cfg.port}`, provider: PROVIDER, mountPath: this.cwd };
@@ -595,7 +596,7 @@ export class RemoteSshExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readTextFile(p, abortSignal) {
         const r = await this.readBinaryFile(p, abortSignal);
@@ -674,7 +675,7 @@ export class RemoteSshExecutionEnv {
             const entries = await new Promise((resolve, reject) => sftp.readdir(abs, (err, list) => (err ? reject(err) : resolve(list))));
             return ok(entries.map((e) => {
                 const a = e.attrs;
-                return { name: e.filename, path: path.posix.join(abs, e.filename), kind: kindFromMode(a.mode), size: a.size ?? 0, mtimeMs: (a.mtime ?? 0) * 1000 };
+                return { name: e.filename, path: anchorUnder(path.posix, abs, e.filename), kind: kindFromMode(a.mode), size: a.size ?? 0, mtimeMs: (a.mtime ?? 0) * 1000 };
             }));
         }
         catch (e) {

package/dist/plugins/remote-shell.d.ts

@@ -60,7 +60,9 @@ export type CwdGuardFace = "settled" | "raw";
  * 🔴 [ref](7.103.1)—— 三条远端 shell 腿(ssh / k8s / adb)交给远端 `sh -c` 的那一串**唯一**的组装:进工作目录 →(settled 面)打 started 行 →
  * 导出任务 env → 跑命令。各腿只决定 `dir`(自己的缺省 cwd 规则 + 路径绝对化),串的形状只在这里。
  *
- * 形:`cd '<dir>' || { echo '<marker>: <dir> (cd failed; command not run)' >&2; exit 125; }; echo '<started>' >&2; export K='v'; … <command>`
+ * 形:`cd -P '<dir>' || { echo '<marker>: <dir> (cd failed; command not run)' >&2; exit 125; }; echo '<started>' >&2; export K='v'; … <command>`
+ *  · `-P`(物理):工作目录按内核解 —— 执行缝路径律下 `<dir>` 是未折的拼法(`<base>/bridge/../next`),文件面由内核解 `..`;缺省的逻辑 `cd` 会先词法折成 `<base>/next`,
+ *    命令与文件动作就各在一只目录。`-P` 是 POSIX `cd` 的选项(dash / bash / busybox ash / mksh 都认)。
  * (raw 面没有 `echo '<started>' >&2;` 那一段)
  *  · cd 失败(目录不存在 / 无权限 / 不是目录)⇒ 命令**不跑**,整条退 {@link CWD_UNAVAILABLE_EXIT};stderr 先是 shell 自己的 cd 报错,再是守卫行。
  *    修前形 `cd '<dir>' && export K='v'; <command>`:`&&` 只绑到第一只 `export`,`;` 之后的命令照样在**登录目录**里跑,还少了那只 env ——

package/dist/plugins/remote-shell.js

@@ -30,7 +30,7 @@ export function buildCwdEnvCommand(command, dir, env, face) {
         const nonce = randomBytes(8).toString("hex");
         cwdGuard = { dir, marker: `${CWD_UNAVAILABLE_LINE} [${nonce}]`, started: startedLineFor(face, nonce) };
         const line = `${cwdGuard.marker}: ${dir} (cd failed; command not run)`;
-        parts.push(`cd ${shellQuote(dir)} || { echo ${shellQuote(line)} >&2; exit ${CWD_UNAVAILABLE_EXIT}; };`);
+        parts.push(`cd -P ${shellQuote(dir)} || { echo ${shellQuote(line)} >&2; exit ${CWD_UNAVAILABLE_EXIT}; };`);
         if (cwdGuard.started !== undefined)
             parts.push(`echo ${shellQuote(cwdGuard.started)} >&2;`);
     }
@@ -184,11 +184,11 @@ function hardenPrivate(dir) {
     return `( chmod -- 700 ${dir} 2>/dev/null && ${readModeOwner(dir)} && case "$1" in drw[xs]--[-S]--[-T]*) [ "$3" = "$(id -u)" ];; *) false;; esac && ${aclCleared(dir)} )`;
 }
 function aclCleared(dir) {
-    const marker = `ls_out=$(cd ${dir} && ls -ld . 2>&1) && [ -z "$(printf '%s\\n' "$ls_out" | sed -n 2p)" ] && mode_word=\${ls_out%% *} && ` +
+    const marker = `ls_out=$(cd -P ${dir} && ls -ld . 2>&1) && [ -z "$(printf '%s\\n' "$ls_out" | sed -n 2p)" ] && mode_word=\${ls_out%% *} && ` +
         `case "$mode_word" in d?????????*+*) echo +;; d?????????*) ;; *) false;; esac`;
     return (`plat=$(uname -s 2>/dev/null) && case "$plat" in ` +
         `Linux) acl_read() { :; }; acl_strip() { false; };; ` +
-        `Darwin) acl_read() { ls_out=$(cd ${dir} && ls -led . 2>&1) && case "$ls_out" in d?????????*) ;; *) false;; esac && printf '%s\\n' "$ls_out" | sed 1d; }; acl_strip() { chmod -N ${dir}; };; ` +
+        `Darwin) acl_read() { ls_out=$(cd -P ${dir} && ls -led . 2>&1) && case "$ls_out" in d?????????*) ;; *) false;; esac && printf '%s\\n' "$ls_out" | sed 1d; }; acl_strip() { chmod -N ${dir}; };; ` +
         `FreeBSD) acl_read() { ${marker}; }; acl_strip() { setfacl -b ${dir}; };; ` +
         `SunOS) acl_read() { ${marker}; }; acl_strip() { chmod A- ${dir}; };; ` +
         `*) false;; esac && acl=$(acl_read 2>/dev/null) && { [ -z "$acl" ] || { acl_strip 2>/dev/null && acl=$(acl_read 2>/dev/null) && [ -z "$acl" ]; }; }`);

package/dist/plugins/replica-registration.d.ts

@@ -0,0 +1,35 @@
+import type { SqlDialect, SqlExec } from "./sql-driver.js";
+/** 表名。 */
+export declare const REPLICA_REGISTRATION_TABLE = "replica_registration";
+/**
+ * 本构建的能力名单(常设、只增):每一条读停-迁-起证据的一次性迁移一个名。删码之后名字留着 —— 名单只增不减(钉:`test/replica-registration.test.ts`)。
+ * 守卫读证据时传的名在型上就要在这里(`ReplicaCapability`):不在名单里的迁移读不了证据,编译期红。
+ */
+export declare const REPLICA_CAPABILITIES: readonly ["M40", "M41", "M42", "M43", "M51"];
+export type ReplicaCapability = (typeof REPLICA_CAPABILITIES)[number];
+/** 留存视界(写者钟):登记早于此的别人的行在下一次登记时删。量级取远大于任一副本的寿命与副本间钟差。 */
+export declare const REPLICA_REGISTRATION_HORIZON_MS: number;
+/** 登记行(纯数据)。 */
+export interface ReplicaRegistration {
+    readonly instanceId: string;
+    /** 发布线(`package.json` 的版本串;只作归因,不进任何判据)。 */
+    readonly releaseLine: string;
+    readonly capabilities: readonly string[];
+    readonly hostName: string;
+    readonly pid: number;
+}
+/** 本进程的登记行:身份 · 本构建的发布线 · 能力名单 · 主机 · pid。 */
+export declare function buildThisReplicaRegistration(): ReplicaRegistration;
+/** 能力格的存形:逗号连接。 */
+export declare function capabilitiesCell(capabilities: readonly string[]): string;
+/** `knows(r, M)`:能力名单里有 M(整词相等;读不出的格 ⇒ 不知道,保守)。观察与准入共用这一只判据。 */
+export declare function knowsCapability(capabilities: readonly string[], migrationId: string): boolean;
+/** 能力格的读形(存形的逆;空串 ⇒ 空名单)。 */
+export declare function capabilitiesOfCell(cell: unknown): readonly string[];
+/** 建表句(两方言;幂等)。中央建表语句读它(`tidb-pool.ts` / `pg-pool.ts`),与 `one-time-migration-marker.ts` 同形:键列钉二进制排序。 */
+export declare function replicaRegistrationDdl(dialect: SqlDialect): string;
+/** 登记:先删视界外的别人的行,再缺席才落本行(两句,各自自动提交)。 */
+export declare function registerReplica(db: SqlExec, dialect: SqlDialect, me: ReplicaRegistration, nowMs: number): Promise<void>;
+/** 读这几只身份的登记行(不在的身份不出现在结果里;空入参 ⇒ 不读库)。 */
+export declare function readReplicaRegistrations(db: SqlExec, dialect: SqlDialect, instanceIds: readonly string[]): Promise<Map<string, ReplicaRegistration>>;
+//# sourceMappingURL=replica-registration.d.ts.map

package/dist/plugins/replica-registration.js

@@ -0,0 +1,48 @@
+import { hostname } from "node:os";
+import { processInstanceId } from "../process-instance.js";
+import { serviceVersion } from "../service-version.js";
+export const REPLICA_REGISTRATION_TABLE = "replica_registration";
+export const REPLICA_CAPABILITIES = ["M40", "M41", "M42", "M43", "M51"];
+export const REPLICA_REGISTRATION_HORIZON_MS = 90 * 24 * 60 * 60 * 1000;
+export function buildThisReplicaRegistration() {
+    return { instanceId: processInstanceId(), releaseLine: serviceVersion(), capabilities: REPLICA_CAPABILITIES, hostName: hostname(), pid: process.pid };
+}
+export function capabilitiesCell(capabilities) {
+    return capabilities.join(",");
+}
+export function knowsCapability(capabilities, migrationId) {
+    return capabilities.includes(migrationId);
+}
+export function capabilitiesOfCell(cell) {
+    return typeof cell === "string" && cell !== "" ? cell.split(",") : [];
+}
+export function replicaRegistrationDdl(dialect) {
+    return dialect === "mysql"
+        ? `CREATE TABLE IF NOT EXISTS ${REPLICA_REGISTRATION_TABLE} (instance_id VARCHAR(64) NOT NULL PRIMARY KEY, release_line VARCHAR(64) NOT NULL, capabilities VARCHAR(1024) NOT NULL, host_name VARCHAR(255) NOT NULL, pid BIGINT NOT NULL, registered_at_ms BIGINT NOT NULL) COLLATE utf8mb4_bin`
+        : `CREATE TABLE IF NOT EXISTS ${REPLICA_REGISTRATION_TABLE} (instance_id VARCHAR(64) COLLATE "C" NOT NULL PRIMARY KEY, release_line VARCHAR(64) COLLATE "C" NOT NULL, capabilities VARCHAR(1024) COLLATE "C" NOT NULL, host_name VARCHAR(255) COLLATE "C" NOT NULL, pid BIGINT NOT NULL, registered_at_ms BIGINT NOT NULL)`;
+}
+const ph = (dialect, i) => (dialect === "mysql" ? "?" : `$${i}`);
+export async function registerReplica(db, dialect, me, nowMs) {
+    await db.query(`DELETE FROM ${REPLICA_REGISTRATION_TABLE} WHERE registered_at_ms < ${ph(dialect, 1)} AND instance_id <> ${ph(dialect, 2)}`, [nowMs - REPLICA_REGISTRATION_HORIZON_MS, me.instanceId]);
+    const insert = `INSERT INTO ${REPLICA_REGISTRATION_TABLE} (instance_id, release_line, capabilities, host_name, pid, registered_at_ms) VALUES (${[1, 2, 3, 4, 5, 6].map((i) => ph(dialect, i)).join(", ")})`;
+    await db.query(dialect === "mysql" ? `${insert} ON DUPLICATE KEY UPDATE instance_id = instance_id` : `${insert} ON CONFLICT (instance_id) DO NOTHING`, [
+        me.instanceId,
+        me.releaseLine,
+        capabilitiesCell(me.capabilities),
+        me.hostName,
+        me.pid,
+        nowMs,
+    ]);
+}
+export async function readReplicaRegistrations(db, dialect, instanceIds) {
+    const out = new Map();
+    if (instanceIds.length === 0)
+        return out;
+    const { rows } = await db.query(`SELECT instance_id, release_line, capabilities, host_name, pid FROM ${REPLICA_REGISTRATION_TABLE} WHERE instance_id IN (${instanceIds.map((_, i) => ph(dialect, i + 1)).join(", ")})`, [...instanceIds]);
+    for (const r of rows) {
+        const instanceId = String(r["instance_id"]);
+        out.set(instanceId, { instanceId, releaseLine: String(r["release_line"]), capabilities: capabilitiesOfCell(r["capabilities"]), hostName: String(r["host_name"]), pid: Number(r["pid"]) });
+    }
+    return out;
+}
+//# sourceMappingURL=replica-registration.js.map

package/dist/plugins/retention-lane-store-sql.d.ts

@@ -1,6 +1,6 @@
 /**
  * 托管留存执行面的**非破坏性 SQL 半场** —— SINGLE-FILE DUAL-DIALECT([ref] A12;先例 =
- * `retention-store-sql.ts` 本身)。[ref] 车2,设计稿 `docs/DESIGN-270-retention-lane.md` v1.3。
+ * `retention-store-sql.ts` 本身)。[ref] 车2,设计稿 `docs/[ref]-retention-lane.md` v1.3。
  *
  * ── 为什么与车1 的 `retention-store-sql.ts` 分家(而不是往那只店上再挂三组方法)────────────────────
  * 车1 那只店是 core `ManagedRetentionCapability` 的**实现体**:它的每一个公开方法都是一次**破坏性**

package/dist/plugins/run-store-sql.d.ts

@@ -216,7 +216,7 @@ export declare class SqlRunStore {
     markResuming(taskId: string, instanceId: string): Promise<string | undefined>;
     /**
      * 认领当写栅栏用(进程内两孪生的契约 = `store-contracts.ts` 的 `InProcessClaimFence`;本孪生是它的事务形):一个事务 ——
-     *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
+     *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`;副本与持有腿两列随行交给 `write`,见 `FencedRun`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
      *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑(另收锁住那一行的 {@link FencedRun});提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
      * 🔴 **取锁序 = task_run → task_active**,与 `setTerminal` / `reapStale` / `reapSuspended` 同序(它们先改 run 行、再删认领行):两行用两条语句按序锁,
      *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 先锁根会话行再插认领行(本序从不碰 `session_meta`)、

package/dist/plugins/run-store-sql.js

@@ -383,7 +383,7 @@ export class SqlRunStore {
     async whileHoldingClaim(sessionId, taskId, write) {
         let fenced = { held: false };
         await this.tx(async (conn) => {
-            const run = await conn.query(this.q("SELECT task_id, instance_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id, instance_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
+            const run = await conn.query(this.q("SELECT task_id, instance_id, leg_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id, instance_id, leg_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
             const row = run.rows[0];
             if (row === undefined)
                 return;
@@ -392,7 +392,7 @@ export class SqlRunStore {
             if (holder === undefined || String(holder.task_id) !== taskId)
                 return;
             await conn.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ?", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2"), [new Date(), taskId]);
-            fenced = { held: true, value: await write(conn, { instanceId: row.instance_id ?? null }) };
+            fenced = { held: true, value: await write(conn, { instanceId: row.instance_id ?? null, legId: row.leg_id ?? null }) };
         });
         return fenced;
     }

package/dist/plugins/scenario-prefix-switch-m42.d.ts

@@ -1,4 +1,5 @@
 import { StoreBootRefusalError } from "./store-contracts.js";
+import { type OlderReplicaEvidence } from "./stop-then-start-sentence.js";
 /** 本条的拒启码(机读)。 */
 export declare const SCENARIO_PREFIX_SWITCH_REFUSED_CODE = "config.scenario_prefix_switch_refused";
 /** 本条在标记表(`one-time-migration-marker.ts`)里的那一行的键。 */
@@ -18,26 +19,19 @@ export interface ScenarioPrefixHit {
 export interface ScenarioPrefixReceipt {
     scenarioPrefixSourcesScanned: number;
 }
-/** 拒因闭集:存量命中 / 零命中而更早版本的副本可能仍在服务(SQL 的停-迁-起)。 */
-export type ScenarioPrefixRefusalReason = "stored_prefix" | "live_runs";
-/** 判活读数(`live_runs` 那一拒带):判活窗内心跳过的 run 数与可以再起的最早时刻。 */
-export interface ScenarioPrefixLiveRuns {
-    readonly liveRuns: number;
-    readonly windowSec: number;
-    readonly restartAfter: string;
-    readonly after: string;
-}
+/** 拒因闭集:存量命中 / 零命中而有停-迁-起证据(更早版本的副本可能仍在服务;SQL 的停-迁-起)。 */
+export type ScenarioPrefixRefusalReason = "stored_prefix" | "older_replica";
 /**
  * M42 的起服拒。具名类型 + 机读码 + 拒因;继承 {@link StoreBootRefusalError}(SQL 开库的等待窗不重试它;隐式 local 的降级臂不吞)。一个字节没改(扫描只读,标记没写)。
  *  · `stored_prefix` —— 存量里有以保留前缀开头的身份(`hits` 逐来源点名);
- *  · `live_runs` —— 零命中,但判活窗内仍有 run 在心跳:更早版本的副本可能还在服务,扫描之后它还会收下这类身份 ⇒ 全停之后再起(`live` 带时刻)。
+ *  · `older_replica` —— 零命中,但有停-迁-起证据:更早版本的副本可能还在服务,扫描之后它还会收下这类身份 ⇒ 全停之后再起(`live` = 证据,带时刻)。
  */
 export declare class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
     readonly reason: ScenarioPrefixRefusalReason;
     readonly hits: readonly ScenarioPrefixHit[];
-    readonly live?: ScenarioPrefixLiveRuns | undefined;
+    readonly live?: OlderReplicaEvidence | undefined;
     readonly code = "config.scenario_prefix_switch_refused";
-    constructor(reason: ScenarioPrefixRefusalReason, hits: readonly ScenarioPrefixHit[], live?: ScenarioPrefixLiveRuns | undefined, 
+    constructor(reason: ScenarioPrefixRefusalReason, hits: readonly ScenarioPrefixHit[], live?: OlderReplicaEvidence | undefined, 
     /** 库此刻还差的列(SQL 腿经 `describeUpgradeDriftTail` 读到的;列齐 / local 腿 ⇒ 空串):一次起服读全。 */
     tail?: string);
     private static sentence;

package/dist/plugins/scenario-prefix-switch-m42.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { SCENARIO_SUBJECT_PREFIX } from "../owner-brands.js";
 import { atomicWriteFileSync } from "./owner-only-file-mode.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
-import { stopThenStartAction } from "./stop-then-start-sentence.js";
+import { olderReplicaEvidenceSentence, stopThenStartAction } from "./stop-then-start-sentence.js";
 export const SCENARIO_PREFIX_SWITCH_REFUSED_CODE = "config.scenario_prefix_switch_refused";
 export const SCENARIO_PREFIX_MARKER_ID = "M42";
 export const LOCAL_MARKER_FILE = "one-time-migration-M42.json";
@@ -28,10 +28,12 @@ export class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
                     `). This version reads that prefix as a scenario of a person, so these rows would be attributed to another person; it refuses to start rather than misread them. ` +
                     `Nothing was changed. Rename or delete those identities (the identity boundary now rejects principals with this prefix), then restart — ` +
                     `the check runs until it finds none, then records a marker in the store and does not run again.`);
-            case "live_runs":
-                return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: no stored identity starts with the reserved prefix "${SCENARIO_SUBJECT_PREFIX}", but ${live?.liveRuns ?? 0} run(s) heartbeated on this database ` +
-                    `within the last ${live?.windowSec ?? 0}s — a replica of an earlier version may still be serving, and it accepts principals with that prefix, so a clean check now would not stay clean. ` +
-                    `Nothing was changed and no marker was written. ${stopThenStartAction(live?.after)}`);
+            case "older_replica":
+                if (live === undefined)
+                    throw new Error("scenario-prefix-switch: an older_replica refusal carries its evidence");
+                return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: no stored identity starts with the reserved prefix "${SCENARIO_SUBJECT_PREFIX}", but ${olderReplicaEvidenceSentence(live)} ` +
+                    `— a replica of an earlier version may still be serving, and it accepts principals with that prefix, so a clean check now would not stay clean. ` +
+                    `Nothing was changed and no marker was written. ${stopThenStartAction(live.after)}`);
             default: {
                 const unhandled = reason;
                 throw new Error(`scenario-prefix-switch: unknown refusal reason ${String(unhandled)}`);

package/dist/plugins/schema-consistency.d.ts

@@ -185,11 +185,13 @@ export declare function describeMismatchedTables(dialect: SqlDialect, mismatches
 /**
  * **升级清单**(多行;`[]` = 没有语句要部署者执行,清单不出):一次起服的拒句里「这只库此刻对本构建还差什么、先后顺序」一段。
  * 缺列拒、判活拒、一次性迁移的拒本来各报各的一段 —— 运维补一句再起、才撞上下一族(列册对账在迁移段之后时,第四次起服才拒出其余全部 ALTER)。
- * 清单把本构建对存量库的全部动作写成一张:① 逐表的 ALTER(其下 {@link describeMismatchedTables} 的逐表段,全库一次列全)② 本构建带的停-迁-起迁移(登记表 `stopThenStart` 一格,
- * 行在 ⇒ 码在;一次性迁移文件静态依赖本文件,所以惰性载入)③ 起服。第 ② 步对「已经走过这些迁移」的库是空操作(迁移在自己的守卫处判),清单不替守卫判「这一只库欠不欠」。
+ * 清单把本构建对这一只库的全部动作写成一张:① 逐表的 ALTER(其下 {@link describeMismatchedTables} 的逐表段,全库一次列全)② 这只库**还欠**的停-迁-起迁移
+ * ③ 起服。第 ② 步逐行问登记行的 `stopThenStart.owedOn`(一次性迁移文件静态依赖本文件,所以惰性载入)—— 那条迁移的守卫自己问的同一只判据,清单不另判:
+ * 已经走过它们的库(标记落了 / 部署格已搬 / 零行旧词)一条不欠 ⇒ 第 ② 步与它的「不可滚动」动作段都不出,起服是第 ② 步。某一条读不出欠不欠(探针读抛)⇒ 照列并如实说
+ * 没读到(多停一次,不漏停)。`read` = 列册对账读列册的同一只无参读口。
  */
-export declare function describeUpgradeChecklist(mismatches: readonly TableMismatch[]): Promise<string[]>;
-/** 拒启文案(表头 + {@link describeUpgradeChecklist}〔有语句要执行时〕+ 逐表段与闭集三条出路 {@link describeMismatchedTables})。`checklist` 由调用方 `await describeUpgradeChecklist(…)` 交来(本函数保持同步纯函数)。 */
+export declare function describeUpgradeChecklist(read: SchemaProbeRead, dialect: SqlDialect, mismatches: readonly TableMismatch[]): Promise<string[]>;
+/** 拒启文案(表头 + {@link describeUpgradeChecklist}〔有语句要执行时〕+ 逐表段与闭集三条出路 {@link describeMismatchedTables})。`checklist` 由调用方 `await describeUpgradeChecklist(…)` 交来(本函数保持同步纯函数,不读库)。 */
 export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[], checklist?: readonly string[]): string;
 /**
  * 迁移段**之前 / 之中**读列册的拒句(单表探针的拒因、判活守卫的句尾)要的那一份:库经本构建**全部待跑迁移**之后({@link projectPendingShape},登记表各行的 `shapeChanges`,
@@ -201,7 +203,7 @@ export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches:
  */
 export declare function statementBearing(expected: Map<string, ParsedTable>, live: LiveColumns, dialect: SqlDialect): Promise<TableMismatch[]>;
 /** 清单 + 逐表段 + 闭集三条出路(多行):单表探针的拒因与判活守卫的句尾共用的正文(列册对账的拒句是 {@link describeSchemaMismatch},同一份清单与逐表段)。 */
-export declare function describeUpgradeBody(dialect: SqlDialect, mismatches: readonly TableMismatch[]): Promise<string[]>;
+export declare function describeUpgradeBody(read: SchemaProbeRead, dialect: SqlDialect, mismatches: readonly TableMismatch[]): Promise<string[]>;
 /** 句尾读列册的期限(ms):这一段是拒句上的附加,不许把已经成立的拒拖住 —— 读不回来就如实说没读到,拒照出。 */
 export declare const DRIFT_TAIL_DEADLINE_MS = 10000;
 /**

package/dist/plugins/schema-consistency.js

@@ -452,21 +452,33 @@ export function describeMismatchedTables(dialect, mismatches) {
 function needsStatements(mismatches) {
     return mismatches.some((m) => m.missing.length > 0 || m.tightened.length > 0);
 }
-export async function describeUpgradeChecklist(mismatches) {
+export async function describeUpgradeChecklist(read, dialect, mismatches) {
     if (!needsStatements(mismatches))
         return [];
     const { stopThenStartMigrations } = await import("./one-time-migrations.js");
-    const stops = stopThenStartMigrations();
+    const owed = [];
+    for (const m of stopThenStartMigrations()) {
+        let owes;
+        try {
+            owes = await m.owedOn(read, dialect);
+        }
+        catch (err) {
+            owed.push(`  - ${m.id}: ${m.reason} (whether this database still owes it could not be read — ${err instanceof Error ? err.message : String(err)} — so it is listed)`);
+            continue;
+        }
+        if (owes)
+            owed.push(`  - ${m.id}: ${m.reason}`);
+    }
     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) {
+    if (owed.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}`),
+            "Stop-then-start one-time migrations this database still owes: this build runs them itself on its first boot (no statement from you), and each refuses to start — writing nothing — while a run on this database has",
+            "heartbeated within REAP_RUN_STALE_SEC held by a replica not registered as knowing that migration (a replica of a release that predates replica registration never is).",
+            ...owed,
             stopThenStartAction(),
         ]);
     }
-    steps.push(["Start this version; the one-time migrations above (if any are still owed) run on that boot."]);
+    steps.push([owed.length > 0 ? "Start this version; the stop-then-start migrations above run on that boot." : "Start this version."]);
     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}`))),
@@ -489,22 +501,26 @@ export async function statementBearing(expected, live, dialect) {
         .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);
+export async function describeUpgradeBody(read, dialect, mismatches) {
+    const checklist = await describeUpgradeChecklist(read, dialect, 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))();
+        const work = (async () => {
+            const mismatches = await statementBearing(await expectedTableShapes(dialect), await readLiveColumns(read, dialect), dialect);
+            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(read, dialect, mismatches)).join("\n")}`;
+        })();
         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]);
+        return 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.`;
@@ -512,9 +528,6 @@ export async function describeUpgradeDriftTail(read, dialect, deadlineMs = DRIFT
     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);
@@ -533,7 +546,7 @@ export async function assertSchemaMatchesCode(read, dialect, pending) {
     }
     const mismatches = diffSchema(expected, projectPendingShape(expected, live, pending, dialect).projected);
     if (mismatches.length > 0)
-        throw new SchemaMismatchRefusedError(describeSchemaMismatch(dialect, mismatches, await describeUpgradeChecklist(mismatches)));
+        throw new SchemaMismatchRefusedError(describeSchemaMismatch(dialect, mismatches, await describeUpgradeChecklist(read, dialect, mismatches)));
 }
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT = { table: "checkpoint", column: "pending_steer" };

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

@@ -28,7 +28,7 @@ async function describeProbedTableDrift(query, dialect, tables) {
         const sc = await import("./schema-consistency.js");
         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");
+            return (await sc.describeUpgradeBody(read, 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/serving-requirement.d.ts

@@ -0,0 +1,49 @@
+/**
+ * **起服准入**(SQL 两方言;常设)—— 「这只库要求每一只服务者有哪些能力」一张表,与本构建的能力名单比:库上记着本构建没有的能力 ⇒ 拒启,本构建不迁移、不服务。
+ *
+ * ## 律
+ *  · 一行一能力:`migration_id` = 能力名(= 一次性迁移名,`replica-registration.ts` 的 {@link REPLICA_CAPABILITIES} 同一词表),`state` 两词闭集
+ *    {@link SERVING_REQUIREMENT_STATES}:`pending`(要求方已认领、还没做任何不兼容写)/ `in_force`(不兼容写已开始或已完成)。两态都要求;读出词表外的词 ⇒ 当作 `in_force`,拒句点名那一行。
+ *  · 判据 = `knows(本构建, M)`(`knowsCapability`,与停-迁-起证据读法同一只谓词);发布线不进判据(同版本串的构建可以能力不同)。
+ *  · 两次读,同一判据:SQL 一次性迁移段头、取迁移锁之前读一次(锁外预读);取到迁移锁之后、第一步迁移之前在锁连接上再读一次(锁内复核)——
+ *    在本进程等锁时握着锁的那一只若写下了要求,锁内复核读得到。拒 ⇒ 本构建不迁移;库上只留本进程的登记行(段头第一步)。
+ *  · 表不在(跳过了 `ensureSchema()` 的嵌入方)⇒ 拒:证不出「没有要求」不是「没有要求」。
+ *  · 本构建不写本表(没有写者;写者随之后的停-迁-起迁移来)—— 表空 ⇒ 准入恒过。装早一版:从本版起的每一只构建都读它,之后写下的要求挡得住它们重启开服。
+ *
+ * ## 射程(如实)
+ * 挡的是**起服者**:已在服务的副本不再读本表;准入与开服之间的停顿也不在它的射程里。早于本表那一版的构建不读本表。
+ */
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { type ReplicaRegistration } from "./replica-registration.js";
+import { type UnmetServingRequirement } from "./stop-then-start-sentence.js";
+import type { SqlDialect, SqlExec } from "./sql-driver.js";
+/** 表名。 */
+export declare const SERVING_REQUIREMENT_TABLE = "serving_requirement";
+/** 要求行的状态词(闭集)。 */
+export declare const SERVING_REQUIREMENT_STATES: readonly ["pending", "in_force"];
+export type ServingRequirementState = (typeof SERVING_REQUIREMENT_STATES)[number];
+/** 拒启码(确定的拒启表态;继承 {@link StoreBootRefusalError}:开库等待窗不重试、降级臂不吞)。 */
+export declare const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
+/** 拒因闭集:库要求的能力本构建没有 / 准入读的表不在库里(证不出)。 */
+export type ServingRequirementRefusalReason = "capability_missing" | "table_absent";
+/** 建表句(两方言;幂等)。中央建表语句读它(`tidb-pool.ts` / `pg-pool.ts`)。 */
+export declare function servingRequirementDdl(dialect: SqlDialect): string;
+/** 起服准入拒。 */
+export declare class ServingRequirementUnmetError extends StoreBootRefusalError {
+    readonly reason: ServingRequirementRefusalReason;
+    /** `capability_missing`:本构建没有的那几行(按能力名排序);`table_absent`:空。 */
+    readonly unmet: readonly UnmetServingRequirement[];
+    /** `table_absent`:不在库里的那几张表;`capability_missing`:空。 */
+    readonly absentTables: readonly string[];
+    readonly code = "config.serving_requirement_unmet";
+    constructor(reason: ServingRequirementRefusalReason, 
+    /** `capability_missing`:本构建没有的那几行(按能力名排序);`table_absent`:空。 */
+    unmet: readonly UnmetServingRequirement[], 
+    /** `table_absent`:不在库里的那几张表;`capability_missing`:空。 */
+    absentTables: readonly string[], releaseLine: string);
+}
+/** 准入读的两张表(本表与段头写的登记表)都在库里;不在 ⇒ 拒(`table_absent`),点名公开序列。 */
+export declare function assertReplicaTablesPresent(db: SqlExec, dialect: SqlDialect, me: ReplicaRegistration): Promise<void>;
+/** 准入:库上每一行要求的能力本构建都有 ⇒ 过;否则拒(`capability_missing`,点名每一行)。纯读;两方言同一句(无占位符)。 */
+export declare function assertServingRequirementsMet(db: SqlExec, me: ReplicaRegistration): Promise<void>;
+//# sourceMappingURL=serving-requirement.d.ts.map

package/dist/plugins/serving-requirement.js

@@ -0,0 +1,53 @@
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { REPLICA_REGISTRATION_TABLE, knowsCapability } from "./replica-registration.js";
+import { servingRequirementUnmetSentence } from "./stop-then-start-sentence.js";
+export const SERVING_REQUIREMENT_TABLE = "serving_requirement";
+export const SERVING_REQUIREMENT_STATES = ["pending", "in_force"];
+export const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
+export function servingRequirementDdl(dialect) {
+    return dialect === "mysql"
+        ? `CREATE TABLE IF NOT EXISTS ${SERVING_REQUIREMENT_TABLE} (migration_id VARCHAR(16) NOT NULL PRIMARY KEY, state VARCHAR(16) NOT NULL, required_at_ms BIGINT NOT NULL) COLLATE utf8mb4_bin`
+        : `CREATE TABLE IF NOT EXISTS ${SERVING_REQUIREMENT_TABLE} (migration_id VARCHAR(16) COLLATE "C" NOT NULL PRIMARY KEY, state VARCHAR(16) COLLATE "C" NOT NULL, required_at_ms BIGINT NOT NULL)`;
+}
+export class ServingRequirementUnmetError extends StoreBootRefusalError {
+    reason;
+    unmet;
+    absentTables;
+    code = SERVING_REQUIREMENT_UNMET_CODE;
+    constructor(reason, unmet, absentTables, releaseLine) {
+        super(servingRequirementUnmetSentence(SERVING_REQUIREMENT_UNMET_CODE, reason, unmet, absentTables, releaseLine));
+        this.reason = reason;
+        this.unmet = unmet;
+        this.absentTables = absentTables;
+        this.name = "ServingRequirementUnmetError";
+    }
+}
+export async function assertReplicaTablesPresent(db, dialect, me) {
+    const scope = dialect === "mysql" ? "DATABASE()" : "current_schema()";
+    const absent = [];
+    for (const table of [REPLICA_REGISTRATION_TABLE, SERVING_REQUIREMENT_TABLE]) {
+        const { rows } = await db.query(`SELECT 1 AS present FROM information_schema.tables WHERE table_schema = ${scope} AND table_name = '${table}'`);
+        if (rows.length === 0)
+            absent.push(table);
+    }
+    if (absent.length > 0)
+        throw new ServingRequirementUnmetError("table_absent", [], absent, me.releaseLine);
+}
+function stateOf(cell) {
+    const word = String(cell);
+    return SERVING_REQUIREMENT_STATES.includes(word) ? { state: word, word } : { state: "in_force", word };
+}
+export async function assertServingRequirementsMet(db, me) {
+    const { rows } = await db.query(`SELECT migration_id, state FROM ${SERVING_REQUIREMENT_TABLE} ORDER BY migration_id`);
+    const unmet = [];
+    for (const r of rows) {
+        const migration = String(r["migration_id"]);
+        if (knowsCapability(me.capabilities, migration))
+            continue;
+        const { state, word } = stateOf(r["state"]);
+        unmet.push({ migration, state, word });
+    }
+    if (unmet.length > 0)
+        throw new ServingRequirementUnmetError("capability_missing", unmet, [], me.releaseLine);
+}
+//# sourceMappingURL=serving-requirement.js.map