@sema-agent/server 7.92.0 → 7.92.2

package/dist/plugins/remote-env-host.d.ts

@@ -103,6 +103,55 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core [ref] 同形:写已释放的 inode。)
      *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     private readonly liveFgSpools;
+    /** 🔴 S-539 在飞的 fs **写**登记表(`liveFgSpools` 同律:「还有人在动这棵树,就别删它」)。
+     *  为什么按 promise 存而不是计数:只有 promise 才能被 `destroy()` **await**;计数只能轮询。 */
+    private readonly inflightFs;
+    /** 一次性:慢 drain 只抱怨一次(一条按次数刷屏的 teardown 读数没人会看)。 */
+    private inflightFsDrainWarned;
+    /**
+     * 🔴 S-539 —— 把一只**会在 workspace / spool 根里建路径或改路径**的 fs 动作登记为「在飞」,直到它 settle。
+     *
+     * ── 病(旧 `destroy()` 的自称与实情)──────────────────────────────────────────────────────────
+     * `destroy()` 只 await 了 `ensurePrepared()` 那只 memo(`preparing`),于是它顶注里的
+     * 「eliminating the prepared-flag race entirely」只对 **prepare 那一段**成立。写面在
+     * `await this.fsReady(p)` 放行**之后**还会自己碰一次磁盘(`writeFile`/`appendFile` 的
+     * `mkdir(dirname)`、`createDir` 的 `mkdir`、`createTempDir`/`createTempFile` 在 spool 根下建),
+     * 那一次调用与 destroy 的 `fs.rm` 是**两条独立 fs 调用在 libuv 线程池里赛跑**:rm 先 ⇒ `mkdir -p` 把已拆除
+     * 的工作区重建成**孤儿**(而 rm 成功后 `untrackEphemeralHostWorkspace()` 已注销 ⇒ 兜底腿也捞不回);
+     * mkdir 先 ⇒ 随后 rm 删掉,调用方拿到 `EINVAL`/`ENOENT` 而不是 "already destroyed"。
+     *
+     * ── 治(一处定义,十几个面共用)────────────────────────────────────────────────────────────────
+     * 调用点必须在方法体的**第一个同步段**里调它(第一个 `await` 之前),登记才与 `destroy()` 置 `destroyed`
+     * 的同步段互斥。于是二者只有两种相对次序,**两种都安全**:
+     *  · 先登记 ⇒ destroy 的快照看得到它,`rm` 等它 settle 之后才发;
+     *  · 后登记 ⇒ 这一面自己的 `fsReady` 看得到 `destroyed`,一个字节都不碰磁盘。
+     * 登记放在 `await this.fsReady(...)` **之后**就没有这个性质:那一刻已经跨过一个 microtask,destroy 可能刚好
+     * 在这中间把快照取完了。所以形状是 `return this.withInflightFs(async () => { …原方法体… })`,
+     * 而不是在方法体里补一句 `if (this.destroyed)` —— 后者仍然不原子(查完到动手之间还有让出点)。
+     *
+     * ── 读面刻意不进来 ─────────────────────────────────────────────────────────────────────────────
+     * ① 读不建路径:拆除之后一次在飞的读拿到 ENOENT 是**诚实**的,复活目录这条病与它无关;
+     * ② 把读拉进来会让 teardown 去等一次可能**永不 settle** 的读(workspace 里的 FIFO / 特殊文件),
+     *    把 destroy 挂死 —— 拿一条新的可用性病换一条不存在的正确性收益。
+     * 判据因此是一句话:**「可能建路径或改路径的那些面」进在飞集合**,不是「过了 fsReady 的都进」。
+     */
+    private withInflightFs;
+    /**
+     * 等 `destroy()` 取到的那批在飞写全部 settle。**永不抛**;答「在时限内清空了吗」。
+     *
+     * 🔴 两条都不能要,所以有第三条(合并复审 [high] 打出来的):
+     *  ① 无界等 —— workspace 里的 FIFO / 特殊文件会让一次 `writeFile` **永不 settle**,而拆除在 run 收尾路径上
+     *     ⇒ 整条收尾停摆。用一条新的可用性病换一条正确性收益,不划算。
+     *  ② 到点就照删 —— 把 S-539 的竞态**原样**搬回来(rm 与在飞 mkdir 再次在线程池里赛跑),只是把窗口从
+     *     「总是」改成「慢的时候」;一条确定的病换一条间歇的病,更糟。
+     *  ③ **到点就不再占着调用方,但 rm 依旧排在那批写之后**(`destroy()` 里的 `void …then(removeOwnedTrees)`)。
+     *     次序保证一个字节不松,teardown 变成「有界返回」。teardown 契约(core 1.258.2)禁的是**抛**,不是**慢**;
+     *     这一条连慢都不欠。
+     *
+     * 快照是 `destroy()` 在同步段取的,所以 destroy **之后**才登记的那些面(唯一一族:`appendFile` 的
+     * `lingeringBgWrite` 残余镜像写)不在这一批里 —— 它们按设计就是跨 destroy 存活的,等它们等于等后台 shell。
+     */
+    private drainInflightFs;
     private ensureSpoolRoot;
     /** True when `workspaceDir` was given (user-owned persistent dir) → destroy() must NOT delete it. */
     private readonly persistent;
@@ -155,6 +204,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  core 留活过的驻留 watcher 又杀了一遍(run 尾 dispose→destroy 顺序,destroy 是第二刀)。隔离 env(容器/VM)
      *  整体拆机自然带走进程,与本契约不冲突(k8s/e2b 各自 destroy 不走这条路径)。 */
     destroy(): Promise<void>;
+    /** `destroy()` 真正动手删的那一段(本 env **自有**的两棵树:spool 根 + ephemeral workspace)。
+     *  抽成一只是因为它有两个调用时机 —— 在飞写按时清空时由 `destroy()` 直接 await,超时时挂在那批写后面异步跑
+     *  (见 {@link drainInflightFs} 头注③)。永不抛(teardown 契约)。 */
+    private removeOwnedTrees;
     cleanup(): Promise<void>;
     get backgroundCapabilities(): BackgroundShellCapability["backgroundCapabilities"];
     private _bgManager?;
@@ -210,7 +263,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** S-539:整只方法体(**含** `fsReady` 那道门)走 `withInflightFs` —— 登记必须与调用方同一同步段,
+     *  否则 destroy 的快照可能刚好在 `await this.fsReady(...)` 的让出点上取完。见那处头注。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面是唯一能在 `destroyed` **之后**过门的写面
+     *  (`lingeringBgWrite`):那一族登记在 destroy 的快照**之后**,所以 destroy 不会去等它们 —— 正确,
+     *  它们按设计跨 destroy 存活(等它们等于等后台 shell)。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
@@ -231,10 +289,14 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。 */
     createDir(p: string, options?: {
         recursive?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Result<void, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面**不会**复活目录(`fs.rm` 只删),进在飞集合的理由是
+     *  同一条:destroy 的 rm 把树从它脚下抽走 ⇒ 一次本该 ok 的删返回 `not_found`。判据是「可能建或改路径」,
+     *  不是「可能复活目录」—— 少一条例外就少一处以后要重新想清楚的地方。 */
     remove(p: string, options?: {
         recursive?: boolean;
         force?: boolean;
@@ -252,7 +314,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);
      *   · ephemeral 形反而更好:`destroy()` 在**有后台 shell 在册**时不删这个根,而 workspace 是会被 rm 的。
      *  ⚠️ 这是 **host-only**:k8s/local-docker 的临时文件必须落在**容器内**可见的 cwd,ssh/e2b 本来就用远端系统 tmp。 */
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。这一面建在 **spool 根**下,而 destroy 也会整树删那个根 ——
+     *  `fs.mkdtemp` 不建父目录,所以它不会复活什么,坏处是一次本该成功的调用返回 `not_found`。 */
     createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注;spool 根同 `createTempDir`)。 */
     createTempFile(options?: {
         prefix?: string;
         suffix?: string;

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

@@ -14,6 +14,7 @@ import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
+const inflightFsDrainWaitMs = () => numEnvOr("HOST_FS_DRAIN_WAIT_MS", 10_000, 1);
 const HOST_BG_MAX_CONCURRENT = numEnvOr("HOST_BG_MAX_CONCURRENT", 8, 1);
 const HOST_BG_DEFAULT_TIMEOUT_SEC = numEnvOr("HOST_BG_DEFAULT_TIMEOUT_SEC", 300, 1);
 const HOST_BG_MAX_TIMEOUT_SEC = numEnvOr("HOST_BG_MAX_TIMEOUT_SEC", 1800, HOST_BG_DEFAULT_TIMEOUT_SEC);
@@ -62,6 +63,41 @@ export class RemoteHostExecutionEnv {
     destroyed = false;
     spoolRootDir;
     liveFgSpools = new Set();
+    inflightFs = new Set();
+    inflightFsDrainWarned = false;
+    withInflightFs(fn) {
+        const p = fn();
+        this.inflightFs.add(p);
+        const forget = () => void this.inflightFs.delete(p);
+        void p.then(forget, forget);
+        return p;
+    }
+    async drainInflightFs(inflight) {
+        if (inflight.length === 0)
+            return true;
+        const settled = Promise.allSettled(inflight);
+        const waitMs = inflightFsDrainWaitMs();
+        const timedOut = Symbol("inflight-fs-drain-timeout");
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(timedOut), waitMs);
+            timer.unref?.();
+        });
+        try {
+            const drained = (await Promise.race([settled, deadline])) !== timedOut;
+            if (!drained && !this.inflightFsDrainWarned) {
+                this.inflightFsDrainWarned = true;
+                console.warn(`RemoteHostExecutionEnv.destroy: ${this.inflightFs.size} in-flight filesystem write(s) did not settle within ` +
+                    `${waitMs}ms — returning from teardown now; removal of ${this.workspaceDir} stays ordered AFTER those writes ` +
+                    `and will land when they finish (a write that never settles, e.g. a FIFO target inside the workspace, defers it)`);
+            }
+            return drained;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     ensureSpoolRoot() {
         if (!this.spoolRootDir)
             this.spoolRootDir = mkdtempSync(path.join(os.tmpdir(), "sema-host-spool-"));
@@ -130,25 +166,32 @@ export class RemoteHostExecutionEnv {
         this.destroyed = true;
         const p = this.preparing;
         this.preparing = undefined;
+        const inflight = [...this.inflightFs];
         try {
             await p?.catch(() => { });
         }
         finally {
-            if (this.spoolRootDir && !this.bgManager.hasShells() && this.liveFgSpools.size === 0) {
-                try {
-                    await fs.rm(this.spoolRootDir, { recursive: true, force: true });
-                }
-                catch { }
-                this.spoolRootDir = undefined;
-            }
-            if (this.persistent)
-                return;
+            if (await this.drainInflightFs(inflight))
+                await this.removeOwnedTrees();
+            else
+                void Promise.allSettled(inflight).then(() => this.removeOwnedTrees());
+        }
+    }
+    async removeOwnedTrees() {
+        if (this.spoolRootDir && !this.bgManager.hasShells() && this.liveFgSpools.size === 0) {
             try {
-                await fs.rm(this.workspaceDir, { recursive: true, force: true });
-                untrackEphemeralHostWorkspace(this.workspaceDir);
-            }
-            catch {
+                await fs.rm(this.spoolRootDir, { recursive: true, force: true });
             }
+            catch { }
+            this.spoolRootDir = undefined;
+        }
+        if (this.persistent)
+            return;
+        try {
+            await fs.rm(this.workspaceDir, { recursive: true, force: true });
+            untrackEphemeralHostWorkspace(this.workspaceDir);
+        }
+        catch {
         }
     }
     async cleanup() {
@@ -905,37 +948,41 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: this.fileError(e, abs, abortSignal) };
         }
     }
-    async writeFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(path.dirname(abs), { recursive: true });
-            const data = typeof content === "string" ? content : Buffer.from(content);
-            await fs.writeFile(abs, data, { signal: abortSignal });
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, abortSignal) };
-        }
+    writeFile(p, content, abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                const data = typeof content === "string" ? content : Buffer.from(content);
+                await fs.writeFile(abs, data, { signal: abortSignal });
+                return ok(undefined);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, abortSignal) };
+            }
+        });
     }
-    async appendFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p, { lingeringBgWrite: true });
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(path.dirname(abs), { recursive: true });
-            if (abortSignal?.aborted)
-                throw Object.assign(new Error("aborted"), { name: "AbortError" });
-            const data = typeof content === "string" ? content : Buffer.from(content);
-            await fs.appendFile(abs, data);
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, abortSignal) };
-        }
+    appendFile(p, content, abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p, { lingeringBgWrite: true });
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                if (abortSignal?.aborted)
+                    throw Object.assign(new Error("aborted"), { name: "AbortError" });
+                const data = typeof content === "string" ? content : Buffer.from(content);
+                await fs.appendFile(abs, data);
+                return ok(undefined);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, abortSignal) };
+            }
+        });
     }
     async fileInfo(p, abortSignal) {
         const ready = await this.fsReady(p);
@@ -1058,66 +1105,74 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: fe };
         }
     }
-    async createDir(p, options) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(abs, { recursive: options?.recursive ?? true });
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, options?.abortSignal) };
-        }
-    }
-    async remove(p, options) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            if (!options?.force) {
-                await fs.lstat(abs);
+    createDir(p, options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(abs, { recursive: options?.recursive ?? true });
+                return ok(undefined);
             }
-            await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
-            return ok(undefined);
-        }
-        catch (e) {
-            const fe = this.fileError(e, abs, options?.abortSignal);
-            if (options?.force && fe.code === "not_found")
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, options?.abortSignal) };
+            }
+        });
+    }
+    remove(p, options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                if (!options?.force) {
+                    await fs.lstat(abs);
+                }
+                await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
                 return ok(undefined);
-            return { ok: false, error: fe };
-        }
+            }
+            catch (e) {
+                const fe = this.fileError(e, abs, options?.abortSignal);
+                if (options?.force && fe.code === "not_found")
+                    return ok(undefined);
+                return { ok: false, error: fe };
+            }
+        });
     }
-    async createTempDir(prefix = "tmp-", abortSignal) {
-        const ready = await this.fsReady(".");
-        if (!ready.ok)
-            return ready;
-        try {
-            return ok(await fs.mkdtemp(path.join(this.ensureSpoolRoot(), prefix)));
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, this.workspaceDir, abortSignal) };
-        }
+    createTempDir(prefix = "tmp-", abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(".");
+            if (!ready.ok)
+                return ready;
+            try {
+                return ok(await fs.mkdtemp(path.join(this.ensureSpoolRoot(), prefix)));
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, this.workspaceDir, abortSignal) };
+            }
+        });
     }
-    async createTempFile(options) {
-        const ready = await this.fsReady(".");
-        if (!ready.ok)
-            return ready;
-        const prefix = options?.prefix ?? "";
-        const suffix = options?.suffix ?? "";
-        try {
-            const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
-            const abs = path.join(this.ensureSpoolRoot(), name);
-            if (options?.abortSignal?.aborted)
-                throw Object.assign(new Error("aborted"), { name: "AbortError" });
-            await fs.writeFile(abs, "", { flag: "wx" });
-            return ok(abs);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
-        }
+    createTempFile(options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(".");
+            if (!ready.ok)
+                return ready;
+            const prefix = options?.prefix ?? "";
+            const suffix = options?.suffix ?? "";
+            try {
+                const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
+                const abs = path.join(this.ensureSpoolRoot(), name);
+                if (options?.abortSignal?.aborted)
+                    throw Object.assign(new Error("aborted"), { name: "AbortError" });
+                await fs.writeFile(abs, "", { flag: "wx" });
+                return ok(abs);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
+            }
+        });
     }
     resolve(p) {
         return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
@@ -1207,7 +1262,7 @@ export class RemoteHostExecutionEnv {
             const rel = path.relative(real(root), real(abs));
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
-        return inside(this.workspaceDir) || (this.spoolRootDir !== undefined && inside(this.spoolRootDir));
+        return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.persistent && inside(this.workspaceDir));
     }
     async fsReady(p, opts) {
         if (this.destroyed) {

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

@@ -1,5 +1,5 @@
 import { redactErrorMessage, redactLedgerEventData, redactTerminalResult } from "../observability/run-terminal.js";
-import { terminalProjection } from "@sema-agent/core";
+import { outwardPlane } from "../terminal.js";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
@@ -120,7 +120,7 @@ export class SqlRunStore {
     async setTerminal(taskId, status, result, error) {
         result = redactTerminalResult(result);
         error = error === null ? null : (redactErrorMessage(error) ?? null);
-        const errorCode = result === null ? null : (terminalProjection(result.terminal).errorCode ?? null);
+        const errorCode = result === null ? null : (outwardPlane(result.terminal).errorCode ?? null);
         let won = false;
         let observed;
         await this.tx(async (conn) => {
@@ -153,7 +153,7 @@ export class SqlRunStore {
                 resultTaskId: result?.taskId,
                 model: result?.model,
                 errorCode: errorCode ?? undefined,
-                errorMessage: (result === null ? undefined : terminalProjection(result.terminal).errorMessage) ?? error ?? undefined,
+                errorMessage: (result === null ? undefined : outwardPlane(result.terminal).errorMessage) ?? error ?? undefined,
                 elapsedMs: observed?.createdAt === undefined ? undefined : Math.max(0, Date.now() - observed.createdAt),
             });
         }

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

@@ -0,0 +1,88 @@
+/**
+ * **启动期「库 ≟ 代码」列集对账探针**(S-547)—— 存量库缺列/多列一律**响亮拒启**。
+ *
+ * ── 病(test T-47 三库一致的真读数)───────────────────────────────────────────────────────────────
+ * 7.91.2 建的 `session_policy`(那时还没有 `gen` 列)+ 一行数据,7.92.0 的二进制接上去:`CREATE TABLE
+ * IF NOT EXISTS` 对存量表是**空操作** ⇒ 启动全绿、日志零提 `gen`、健康检查 healthy,直到**用户路径上**
+ * 第一次读写策略行才炸 —— `PUT/GET /v1/sessions/:id/policy` 500,`POST /v1/tasks` 的 run 终局对外
+ * `errorCode` 直接是裸 `42703` / `ER_BAD_FIELD_ERROR`。
+ *
+ * ── 与 SCHEMA POLICY(`tidb-pool.ts` 顶注,clay 裁 2026-07-26)不冲突 ─────────────────────────────
+ * 那条口径禁的是 **ALTER seam**:「代码是 schema 的唯一真源、存量库删库重建、`ensure*` 里不许再出现
+ * `ALTER TABLE`」。本探针**一条 DDL 都不发**,它是只读的 information_schema 对账 —— 恰恰是那条口径的
+ * **执行面**:口径说「库必须等于代码」,在此之前没有任何东西检查过这句话是不是真的。两者一个是禁令
+ * (不许代码偷改库)、一个是对账(库偏离了就别起),同向不同面。
+ *
+ * ── 为什么两个方向都拒(缺列 **和** 多列)──────────────────────────────────────────────────────
+ * 缺列 = 库比代码旧(升级没重建库):读写会在用户路径上炸。多列 = 库比代码**新** —— 滚动升级窗里一个
+ * **旧副本**连上了已被新副本重建过的库;它按旧列集读写,新列上的不变量(本例:`gen` 血统)在它眼里
+ * 根本不存在,于是它会悄悄写出违反新契约的行。后者比前者更隐蔽,所以不做「幽灵列只警告」。
+ * ⇒ 运维顺序因此是**先升库再升副本**(见 `docs/DEPLOY-PREREQS.md` 滚动升级窗那一节)。
+ *
+ * ── 期望列集从哪来:**机器派生,不许手抄**([ref])────────────────────────────────────────────
+ * 期望值 = `schema-ensure-legs.ts` 的录制驱动跑一遍**真的** `ensure*Schema`,把录到的 `CREATE TABLE`
+ * 语句文本解析出列集。于是「代码里的 schema」与「探针拿来对账的 schema」是**同一份字节**,不存在第二
+ * 处清单会腐掉。(更好的形是把语句数组本身改成结构化再生成 SQL —— 那要改 70 张表的 DDL 写法,爆炸
+ * 半径远大于本批;先解析文本,理由写在这里。)拒启文案里的那句 `ALTER TABLE … ADD COLUMN …` 也由
+ * **同一份解析结果**生成,不是手写的。
+ *
+ * ── 失败方向:读不到就拒,不跳过 ─────────────────────────────────────────────────────────────
+ * information_schema 查询抛错、或整库一行都读不出来 ⇒ **拒启**。探针的语义是「我证明了库等于代码」,
+ * 证不出来时放行等于把一条保护性断言静默降级成祝福([ref]:保护型缺席必须 fail-closed)。
+ * `recordFailOpen` 在这条腿上**不适用** —— 它是 F 类(装饰/缓存)的登记口,不是 P 类保护臂的逃生门。
+ */
+import { type SchemaDialect } from "./schema-ensure-legs.js";
+/** 一列:名字 + 它在 `CREATE TABLE` 里的**原样定义文本**(生成 ADD COLUMN 指路用,不另手写)。 */
+export interface ParsedColumn {
+    readonly name: string;
+    readonly ddl: string;
+}
+/** 一张表的列形。 */
+export interface ParsedTable {
+    readonly table: string;
+    readonly columns: readonly ParsedColumn[];
+}
+/**
+ * 解析一条 `CREATE TABLE`。不是建表语句(CREATE INDEX / INSERT / SELECT / CREATE EXTENSION)⇒ `undefined`。
+ *
+ * 认识面窄得刻意:只取**表名 + 顶层列名 + 该列的定义文本**。类型、默认值、可空性一律**不比对** ——
+ * 本探针守的是「列在不在」这一类(T-47 的真病),把类型也拉进来会让方言差异(`DATETIME(3)` ⇄
+ * `TIMESTAMPTZ(3)`、`vector(d)` ⇄ `jsonb` 的运行期参数化)变成一堆假红,而那是另一条判据另一台车。
+ */
+export declare function parseCreateTable(stmt: string): ParsedTable | undefined;
+/** 启动时真会建出来的**全部**表形(录制 → 解析)。同名表二次出现以**先到**为准(`IF NOT EXISTS` 的真语义)。 */
+export declare function expectedTableShapes(dialect: SchemaDialect): Promise<Map<string, ParsedTable>>;
+/** 拒启码(机读)。附录 A / 拒启码表的登记名。 */
+export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
+/** 一张表的对账结论。 */
+export interface TableMismatch {
+    readonly table: string;
+    /** 代码有、库没有(库比代码**旧**)。 */
+    readonly missing: readonly ParsedColumn[];
+    /** 库有、代码没有(库比代码**新** —— 滚动窗里的旧副本)。 */
+    readonly ghost: readonly string[];
+}
+/** 探针读口:一条 SQL → 行数组(两方言由调用方各自绑)。 */
+export type SchemaProbeRead = (sql: string) => Promise<Array<Record<string, unknown>>>;
+/**
+ * 库里实际的列集(表名 → 列名集合)。
+ *
+ * 🔴 **PG 侧读的是「查询真正会解析到的那个关系」,不是 `current_schema()`**(codex 对抗复审本轮 [medium]
+ * 采纳):店里的 SQL 全是**不限定 schema** 的裸表名,它按 `search_path` **逐个** schema 解析,命中第一个;
+ * 而 `current_schema()` 只是路径的第一段。两者不等的部署是真的存在(角色的 `search_path` 配了多段),那时
+ * 只读第一段会让探针对「表其实住在路径后段、而且缺列」这一形**完全沉默**。⇒ 按 `current_schemas(false)`
+ * 的**顺序**取每张表的第一次命中 —— 探针于是与执行器看同一张表。MySQL 协议没有这个概念(库 = 连接上的
+ * `DATABASE()`),那条臂一个字不变。
+ */
+export declare function readLiveColumns(read: SchemaProbeRead, dialect: SchemaDialect): Promise<Map<string, Set<string>>>;
+/** 对账(纯函数:期望 × 实况 → 不符表清单)。 */
+export declare function diffSchema(expected: Map<string, ParsedTable>, live: Map<string, Set<string>>): TableMismatch[];
+/** 拒启文案(表名 + 缺/多列 + 两条路;ADD COLUMN 句由解析结果**生成**)。 */
+export declare function describeSchemaMismatch(dialect: SchemaDialect, mismatches: readonly TableMismatch[]): string;
+/**
+ * 启动期对账:**建表之后**跑,不符即抛(= 拒启)。两方言 + InnoDB 同腿(MySQL 协议共用 `mysql` 臂)。
+ *
+ * 失败方向见文件头注:读抛 / 整库零行 ⇒ 拒。
+ */
+export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SchemaDialect): Promise<void>;
+//# sourceMappingURL=schema-consistency.d.ts.map