@sema-agent/server 7.113.0 → 7.115.0

package/scripts/{retired-mode-seed-drain-local.mjs → drain-check-local.mjs}

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 /**
- * 换钉 7.113.0(core 7.39.0 删掉退役 mode-seed 的一次性迁移)前的**排空检查 —— `DB_BACKEND=local`(File 店)车道**,只读。
- * 随 npm 包出(`scripts/retired-mode-seed-drain-local.mjs`;SQL 车道的同一判据是 `docs/DEPLOY-PREREQS.md` 同名节的两条只读 SQL)。
+ * 换钉前的**排空检查 —— `DB_BACKEND=local`(File 店)车道**,只读。随 npm 包出(`scripts/drain-check-local.mjs`)。
+ * 一次跑**两条判据**(判据表 {@link DRAIN_CRITERIA},每条一行末行、各自的命中行;SQL 车道的同一判据是 `docs/DEPLOY-PREREQS.md` 各节的只读 SQL):
+ *  · `retired-mode-seed`(换钉 7.113.0 前,core 7.39.0 删掉退役 mode-seed 的一次性迁移):pending 行的 `state.inheritedGate` 仍带退役成员;
+ *  · `permissions-allow-list`(换钉 7.115.0 前,本服务把 `settings.permissions.allow` 从名单改成 allow 规则):pending 行所在会话的续跑上下文
+ *    (`checkpoint-ctx/*.json` 的信封 `{ sessionId, updatedAt, ctx }`)里,`ctx.body.settings.permissions.allow` 是非空数组,且 `ctx.permissionsAllowReading` 不是 `"statement"`
+ *    —— 这样的行在 7.115.0 上续跑会被拒(行字节不动;出路按停驻种类分,见随包 `MIGRATION.md` 7.115.0 节)。判据**就是**服务续跑腿拒臂的那一只函数(`src/http/checkpoint-ctx.ts` 的 `allowListReadingUnstated`),
+ *    经包里脚本隔壁的编译产物 `dist/http/checkpoint-ctx.js` 取(与缺省数据根经 `dist/local-data-root.js` 取同一姿势;该模块只有类型 import,编出来零运行期依赖)—— 本脚本不写第二份。
+ * 扫描骨架(快照 + 账本折成当前行、一致性重读、数据根判定)两条判据共用;判据只回答「这一条 pending 行算不算命中」。
  *
  * ## 为什么是一只脚本,不是一行 grep
  *  ① 判据有三条成员(core `refuseRetiredModeSeed`):`autoModeRequested` / `approverPosture` **任何值**(含 JSON null)、
@@ -27,7 +33,7 @@
  * 仍不稳 ⇒ rc 2 + 一句话(服务在写:停写或重跑),不给结论。
  *
  * ## 数据根
- *  · 带参:`node scripts/retired-mode-seed-drain-local.mjs <数据根>` —— 读那个目录;
+ *  · 带参:`node scripts/drain-check-local.mjs <数据根>` —— 读那个目录;
  *  · 不带参:数据根 = **服务自己的那只解析**(`dist/local-data-root.js` 的 `resolveLocalDataRoot`,`loadConfig` 调的同一只函数,脚本不自抄那条链),
  *    所以要在**与服务同一份 env**(同样的数据根相关 env、同一个 home)下跑,读到的才是服务用的那个目录;末行 `root=` 回显实际读了哪个目录。
  *    随包形里 `dist/` 在脚本隔壁;源码树没 build 过又没给根 ⇒ rc 2 说明(见下)。
@@ -35,19 +41,21 @@
  *    根 `LOCK` 是 pidfile、干净退出即删,不能当标记)⇒ rc 2,不给结论 —— 路径打错、env 没对上服务,都会读到一个什么都没有的目录。
  *
  * ## 读数(机读末行 + 退出码)
- *  · 每条命中一行:`RETIRED-ROW token=<token> sessionId=<id> createdAt=<ms> member=<成员>`;
- *  · 末行恒有:`RETIRED-MODE-SEED rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`;
+ *  · 每条命中一行:`ALLOW-LIST-ROW token=<token> sessionId=<id> createdAt=<ms>` / `RETIRED-ROW token=<token> sessionId=<id> createdAt=<ms> member=<成员>`;
+ *  · 每条判据一行末行(表序;`RETIRED-MODE-SEED` 那一行恒在最后,7.113.0 起读「最后一行」的下游不受影响):
+ *    `PERMISSIONS-ALLOW-LIST rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`,
+ *    `RETIRED-MODE-SEED rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`;
+ *    `corrupt` = 共用扫描的坏记录 + 这条判据自己读不懂的旁路输入(`permissions-allow-list`:读不懂的 ctx 档,文件名进 stderr —— 一份读不懂的 ctx 可能正是某条 pending 行带 `allow` 的那一份);
  *    没读成 / 不能下结论(rc 2 的几种缺席与不稳形)时前五个计数是 `-`、多一个 `reason=<词>`,**不会出现 `rows=0`**(下游读 `rows=0` 即「干净」);
- *  · rc 0 = 零命中(可换钉)· rc 1 = 有命中(逐行列出;答完或取消再跑)· rc 2 = 读不懂 / 没读成 / 不能下结论(账本里有本脚本不认的事件词 / 不合形的记录 /
- *    数据根缺席 / 缺省根解析不可用 / 读期间文件一直在变 / 读文件出错 / 用法错)—— 不给结论(缺席 ≠ 干净:一条读不懂的记录可能正是让某行回到 pending 的那一条)。
+ *  · rc 0 = 两条判据都零命中(可换钉)· rc 1 = 有命中(逐行列出;答完或取消再跑)· rc 2 = 读不懂 / 没读成 / 不能下结论(账本里有本脚本不认的事件词 / 不合形的记录 / 读不懂的 ctx 档 /
+ *    数据根缺席 / 缺省根解析不可用 / 判据模块不可用(脚本隔壁没有 `dist/`:源码树没 build)/ 读期间文件一直在变 / 读文件出错 / 用法错)—— 不给结论(缺席 ≠ 干净:一条读不懂的记录可能正是让某行回到 pending 的那一条)。
  *    rc 2 与 rc 1 同时成立时(有命中、也有读不懂的记录)报 rc 2,命中行照列。
  */
-import { readFileSync, realpathSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const TAIL_PREFIX = "RETIRED-MODE-SEED";
 /** 读期间文件在变时的有界重读次数(含第一次)。 */
 const STABLE_READ_ATTEMPTS = 3;
 /** core 账本事件注册表(`stores/file/checkpoint-store.js:7-14`)。 */
@@ -204,12 +212,89 @@ function retiredMember(gate) {
   return undefined;
 }
 
-/** 没读成 / 不能下结论的报告:一句人话进 stderr、机读末行进 stdout(计数全 `-`,不出现 `rows=0`),rc 2。
+/** @param {unknown} v */
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * `<数据根>/checkpoint-ctx/*.json` —— 本服务 local 店的续跑上下文,一档一会话,信封 `{ sessionId, updatedAt, ctx }`(`ctx` 是对象;形判据同本服务 `LocalCheckpointStore` 的
+ * `CtxRecordSchema` + 对象读者)。目录不存在 = 没有 ctx(没写过);读不懂的档计入 `corrupt`(不猜它属于哪个会话)、文件名回给调用方;读期间被收割删掉的档跳过。
+ * @param {string} root
+ * @returns {{ bySession: Map<string, Record<string, unknown>>, corrupt: number, unreadable: string[] }} */
+function readCtxIndex(root) {
+  const dir = join(root, "checkpoint-ctx");
+  /** @type {Map<string, Record<string, unknown>>} */
+  const bySession = new Map();
+  /** @type {string[]} */
+  const unreadable = [];
+  /** @type {string[]} */
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === "ENOENT") return { bySession, corrupt: 0, unreadable };
+    throw e;
+  }
+  for (const name of names.sort()) {
+    if (!name.endsWith(".json")) continue;
+    let text;
+    try {
+      text = readFileSync(join(dir, name), "utf8");
+    } catch (e) {
+      if (/** @type {NodeJS.ErrnoException} */ (e).code === "ENOENT") continue; // 读期间被收割删掉
+      throw e;
+    }
+    const rec = parse(text);
+    if (rec === undefined || typeof rec.sessionId !== "string" || typeof rec.updatedAt !== "number" || !isObject(rec.ctx)) {
+      unreadable.push(name);
+      continue;
+    }
+    bySession.set(rec.sessionId, /** @type {Record<string, unknown>} */ (rec.ctx));
+  }
+  return { bySession, corrupt: unreadable.length, unreadable };
+}
+
+/**
+ * 判据表 —— 「哪些 pending 行算命中」。扫描骨架(快照 + 账本折成当前行、一致性重读、数据根判定)两条共用,判据只管这一问:
+ *  · `tail` / `hit`:末行前缀 / 命中行前缀;
+ *  · `load(root, service)`:这条判据要的旁路输入(读不懂的记录计入 `corrupt`,`unreadable` 回显进 stderr);`service` = 从编译产物取来的服务判据({@link drainReport} 取一次);
+ *  · `judge(row, input)`:命中 ⇒ 命中行的尾巴(可为空串),不命中 ⇒ `undefined`。
+ * 表序 = 输出序;`retired-mode-seed` 排最后 ⇒ 最后一行仍是 `RETIRED-MODE-SEED …`(7.113.0 起读最后一行的下游)。
+ * @type {ReadonlyArray<{ name: string, tail: string, hit: string, load: (root: string, service: { allowListReadingUnstated: (ctx: Record<string, unknown>) => boolean }) => { input: unknown, corrupt: number, unreadable: string[] }, judge: (row: Record<string, unknown>, input: unknown) => string | undefined }>}
+ */
+export const DRAIN_CRITERIA = [
+  {
+    name: "permissions-allow-list",
+    tail: "PERMISSIONS-ALLOW-LIST",
+    hit: "ALLOW-LIST-ROW",
+    load: (root, service) => {
+      const idx = readCtxIndex(root);
+      return { input: { bySession: idx.bySession, unstated: service.allowListReadingUnstated }, corrupt: idx.corrupt, unreadable: idx.unreadable };
+    },
+    judge: (row, input) => {
+      const { bySession, unstated } = /** @type {{ bySession: Map<string, Record<string, unknown>>, unstated: (ctx: Record<string, unknown>) => boolean }} */ (input);
+      const ctx = typeof row.sessionId === "string" ? bySession.get(row.sessionId) : undefined;
+      return ctx !== undefined && unstated(ctx) ? "" : undefined;
+    },
+  },
+  {
+    name: "retired-mode-seed",
+    tail: "RETIRED-MODE-SEED",
+    hit: "RETIRED-ROW",
+    load: () => ({ input: undefined, corrupt: 0, unreadable: [] }),
+    judge: (row) => {
+      const state = isObject(row.state) ? /** @type {Record<string, unknown>} */ (row.state) : {};
+      const member = retiredMember(state.inheritedGate);
+      return member === undefined ? undefined : ` member=${member}`;
+    },
+  },
+];
+
+/** 没读成 / 不能下结论的报告:一句人话进 stderr、每条判据一行机读末行进 stdout(计数全 `-`,不出现 `rows=0`),rc 2。
  * @param {string} reason 机读词
  * @param {string} sentence
  * @param {string} rootEcho */
 function unreadableReport(reason, sentence, rootEcho) {
-  return { rc: /** @type {const} */ (2), stdout: [`${TAIL_PREFIX} rows=- pending=- total=- unknownEvents=- corrupt=- reason=${reason} root=${rootEcho}`], stderr: [sentence] };
+  return { rc: /** @type {const} */ (2), stdout: DRAIN_CRITERIA.map((c) => `${c.tail} rows=- pending=- total=- unknownEvents=- corrupt=- reason=${reason} root=${rootEcho}`), stderr: [sentence] };
 }
 
 /**
@@ -235,12 +320,36 @@ export async function drainReport(root, opts = {}) {
       root,
     );
   }
+  // 判据的唯一实现在服务里;随包形里编译产物在脚本隔壁。取不到(源码树没 build)⇒ 不给结论 —— 绝不退回一份手写的判据。
+  /** @type {{ allowListReadingUnstated: (ctx: Record<string, unknown>) => boolean }} */
+  let service;
+  try {
+    service = await import("../dist/http/checkpoint-ctx.js");
+  } catch (e) {
+    return unreadableReport(
+      "criterion-unavailable",
+      `cannot load the service's own criterion (dist/http/checkpoint-ctx.js next to scripts/ is not loadable: ${e instanceof Error ? e.message : String(e)}) — no verdict: run the copy inside an installed @sema-agent/server package (or after \`npm run build\`)`,
+      root,
+    );
+  }
+  // 模块能加载不等于判据在:产物被截断 / 损坏时 import 照样成功、导出缺席。判据给不出来 ⇒ 同一条「不给结论」,
+  // 不许在没有行可判时读成 rows=0,也不许等到调用处抛出(未捕获异常的退出码是 1 = 「有命中」)。
+  if (typeof service?.allowListReadingUnstated !== "function") {
+    return unreadableReport(
+      "criterion-unavailable",
+      "cannot use the service's own criterion (dist/http/checkpoint-ctx.js next to scripts/ loaded but does not provide it — the compiled output is incomplete or damaged) — no verdict: reinstall @sema-agent/server and run the copy inside the installed package",
+      root,
+    );
+  }
   let scan;
+  /** @type {Array<{ input: unknown, corrupt: number, unreadable: string[] }>} */
+  let inputs;
   try {
     scan = await scanCheckpointDir(dir, opts);
+    inputs = DRAIN_CRITERIA.map((c) => c.load(root, service));
   } catch (e) {
     // 读文件出错(权限 / 路径是目录 / …)⇒ 不给结论。未捕获异常的退出码是 1 = 「有命中」,会被下游读成有停放行。
-    return unreadableReport("read-error", `cannot read the checkpoint files under ${dir}: ${e instanceof Error ? e.message : String(e)} — no verdict`, root);
+    return unreadableReport("read-error", `cannot read the checkpoint files under ${root}: ${e instanceof Error ? e.message : String(e)} — no verdict`, root);
   }
   if (!scan.stable) {
     return unreadableReport(
@@ -250,25 +359,37 @@ export async function drainReport(root, opts = {}) {
     );
   }
   const { rows, corrupt, unknownEvents } = scan;
+  /** @type {string[]} */
   const stdout = [];
-  let hits = 0;
-  let pending = 0;
-  for (const [token, row] of rows) {
-    if (row.status !== "pending") continue;
-    pending++;
-    const state = row.state !== null && typeof row.state === "object" ? /** @type {Record<string, unknown>} */ (row.state) : {};
-    const member = retiredMember(state.inheritedGate);
-    if (member === undefined) continue;
-    hits++;
-    stdout.push(`RETIRED-ROW token=${token} sessionId=${String(row.sessionId)} createdAt=${String(row.createdAt)} member=${member}`);
-  }
-  stdout.push(`${TAIL_PREFIX} rows=${hits} pending=${pending} total=${rows.size} unknownEvents=${unknownEvents} corrupt=${corrupt} root=${root}`);
-  return { rc: unknownEvents > 0 || corrupt > 0 ? 2 : hits > 0 ? 1 : 0, stdout, stderr: [] };
+  /** @type {string[]} */
+  const stderr = [];
+  /** @type {string[]} */
+  const tails = [];
+  let anyHit = false;
+  let anyUnreadable = unknownEvents > 0 || corrupt > 0;
+  DRAIN_CRITERIA.forEach((criterion, i) => {
+    const { input, corrupt: ownCorrupt, unreadable } = inputs[i];
+    let hits = 0;
+    let pending = 0;
+    for (const [token, row] of rows) {
+      if (row.status !== "pending") continue;
+      pending++;
+      const tailOfHit = criterion.judge(row, input);
+      if (tailOfHit === undefined) continue;
+      hits++;
+      stdout.push(`${criterion.hit} token=${token} sessionId=${String(row.sessionId)} createdAt=${String(row.createdAt)}${tailOfHit}`);
+    }
+    if (unreadable.length > 0) stderr.push(`${criterion.name}: unreadable input files (no verdict — one of them may be what makes a pending row count): ${unreadable.join(", ")}`);
+    if (ownCorrupt > 0) anyUnreadable = true;
+    if (hits > 0) anyHit = true;
+    tails.push(`${criterion.tail} rows=${hits} pending=${pending} total=${rows.size} unknownEvents=${unknownEvents} corrupt=${corrupt + ownCorrupt} root=${root}`);
+  });
+  return { rc: anyUnreadable ? 2 : anyHit ? 1 : 0, stdout: [...stdout, ...tails], stderr };
 }
 
 /** CLI 入口:解析实参与缺省根,打印报告,按报告的 rc 退出。 */
 async function main() {
-  const usage = "usage: retired-mode-seed-drain-local.mjs [<data root>]";
+  const usage = "usage: drain-check-local.mjs [<data root>]";
   const args = process.argv.slice(2);
   /** @param {{ rc: number, stdout: string[], stderr: string[] }} r */
   const finish = (r) => {