@sema-agent/settings-schema 14.4.0 → 14.6.0

package/dist/file-store.js

@@ -29,25 +29,13 @@ import path from "node:path";
 import { buildEffective, DOMAIN_READ_FALLBACK, parseDomainLoud } from "./config-fns.js";
 import { configDPath, readConfigDFile, refuseRetiredDomainFiles } from "./config-d-file.js";
 import { stableHash } from "./hash.js";
+import { PORTABLE_DOMAINS } from "./portable-domains.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
 /** The retired domain names (`RETIRED_DOMAINS` keys) — read from `config.d/` for their tombstone only. */
 const RETIRED_DOMAIN_NAMES = Object.keys(RETIRED_DOMAINS);
-/** The domains a single-machine TOC carries: what `FileConfigStore` reads out of `config.d/`, and the
- *  **default**域集 of the bundle helpers (`exportBundle`/`readBundle`). 每个被排除的域必须在
- *  {@link NON_PORTABLE_DOMAIN_REASONS} 里有一条成文理由(禁裸排除,#282 件5 附带裁定)。
- *
- *  ⚠️ 口径诚实(对抗复审 复审 round1 F4):这是**默认集与本地读取集,不是 API 级硬边界** —— `exportBundle`
- *  / `readBundle` 的 `domains` 参数可显式传任意 `DomainName`(bundle.ts 不拒非便携域)。把非便携域搬进
- *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
- *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
- *
- *  🔴 **开新顶层域时必须同步登记本表**(成案 = 消费方 #322 真事故):域表是**闭集**,不在这里的
- *  域名,`config.d/<域>.json` 不会被读进 effective —— 消费方拿到的是「该域缺席」,和文件不存在**逐字
- *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
- *  今日的兜底:漏登记的文件会被 {@link FileConfigStore} 的 `"unread-config-file"` 警告点名(fail-loud,
- *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
-export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits"];
+// 便携域表的定义住在纯叶 ./portable-domains.ts(14.6.0;零 node 依赖,主桶模块可 import);这里原名转出口,`./node` 子路径逐名不变。
+export { NON_PORTABLE_DOMAIN_REASONS, PORTABLE_DOMAINS } from "./portable-domains.js";
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
  *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
@@ -55,21 +43,6 @@ export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins"
  *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
  *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
 export const NON_DOMAIN_CONFIG_FILES = new Set([`${REMOTE_EXEC_DOCUMENT}.json`]);
-/**
- * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
- *
- * `satisfies Record<Exclude<DomainName, PortableDomain>, string>` 让键集在**编译期**双向咬死:新开一个
- * 域却不放进 PORTABLE_DOMAINS ⇒ 这里缺行 ⇒ 编译错;把某域改成便携却忘了删行 ⇒ 多余键 ⇒ 编译错。
- * (此前是「理由写在注释里」,机器只能做子串匹配——域名出现在文件任何角落都算数,等于没门;对抗复审
- * 复审 round1 F3。)理由要写**为什么它不该被单机/跨部署搬运**,带出处。
- */
-export const NON_PORTABLE_DOMAIN_REASONS = {
-    workers: "FLEET-only:单机没有 reconciler,`{workers:[]}` 的 schema 默认就是正确语义(缺席不需要 stub)。",
-    hosts: "FLEET-only:同 workers —— 单机无机器注册表/自动排布,空注册表即正确语义。",
-    systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 web-admin 侧生命周期,单机 lane 无对应执法点。",
-    projects: "TENANT IDENTITY DATA,不是可搬运的配置:登记簿随包复制进另一个部署 = 凭空多出的身份登记(design/142 §1.4 威胁模型①「carried-in foreign projectId」换了身 import 的衣服)。要带走走 142 §5 的导出面(service 半场)。",
-    entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service / web-admin 边界)。缺席语义如实:本地 buildEffective 给它 schema 默认值(空表),这**不等于**把远端 kill-switch/预算上限搬到了本地 —— 单机 lane 本就没有那个执法点。",
-};
 export class FileConfigStore {
     root;
     opts;

package/dist/fleet.js

@@ -20,6 +20,7 @@
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
 import { fnv1a64 } from "./hash.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { buildQuotedIssue } from "./quoted-issue.js";
 // ── Web-admin's fleet endpoints (paths, one spelling) ─────────────────────────────────────────────────────
 /**
@@ -173,7 +174,7 @@ export const RestartSignal = z.object({
  */
 function judgeSignalBody(body, pick, schema) {
     try {
-        if (body === null || typeof body !== "object" || Array.isArray(body))
+        if (!isPlainJsonObject(body))
             return { kind: "not-an-object" };
         const parsed = schema.safeParse(pick(body));
         return parsed.success ? { kind: "read", value: parsed.data } : { kind: "invalid" };

package/dist/fs-failure.d.ts

@@ -5,6 +5,8 @@
  *
  * 落点({@link FsFailureSite}.`landing`,闭集)按失败发生在哪一步分句 —— 同一个 errno 在不同落点指向不同的东西:
  *  · `dir-create-temp` —— 原子写器在目标所在目录里建临时文件。目录不让建 ⇒ 点名**目录**(文件本身没错);
+ *  · `chmod`           —— 原子写器给临时文件设模式(已有的文件沿用它原来的模式,临时文件建成后、`rename` 之前设)。这一步失败 ⇒ 点名**设模式**这件事(文件系统不让改文件模式;目录没有问题),
+ *                          不提目录、不提不可变标志;`path` 是被保留模式的**真文件**(chmod 作用在替换它的临时副本上,用户认得的是真文件名);
  *  · `rename`          —— 原子写器 `rename` 盖过目标。目录收了新文件、却换不掉这一份 ⇒ 点名**真文件**;
  *  · `remove`          —— 删一个文件。删的是目录项:目录不让删 ⇒ 点名文件所在的**目录**(与建临时文件同一个因);
  *  · `read`            —— 读一个目录或文件;
@@ -12,22 +14,35 @@
  * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
  *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
  *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
- * 目录落点(`dir-create-temp` / `remove`)的 `EPERM` / `EROFS` 出路句尾加「目录可能是只读 / 不可变(chflags / chattr)」—— 改权限位修不好的那两种。
+ * 三个落点(`dir-create-temp` / `remove` / `rename`)的权限类出路走**同一张表**、一只函数({@link permissionWayOut}):落点表 {@link WAY_OUT_LANDING}(这个落点认哪些 errno、清标志点名谁、动已有目录项的落点才有粘滞目录一句)×
+ * errno 表 {@link WAY_OUT_BY_ERRNO}(穷举;每个 errno 两格 —— 目录权限位对本进程「可写」/「不可写或没读过」)。同一个 `EPERM` 既可能是目录模式不让写,也可能是不可变标志(macOS `chflags uchg` / Linux `chattr +i`),
+ * 同一个 `EACCES` 在模式位已经放行时只能是 ACL 条目或安全模块策略 —— 铸点是纯函数,分不清,但调用方在 Node 一侧能读目录模式,把「模式对本进程可写」这个事实经落点的 `directoryWritable` 递进来:
+ * 「可写」⇒ chmod 已经没用,`EPERM` 的首选出路 = 清标志(`chflags nouchg` / `chattr -i`),动已有目录项的落点(remove / rename)再接粘滞目录一句(那条属主规则给的就是 `EPERM`),`EACCES` 的出路 = 查 ACL / 安全模块(不接粘滞句);
+ * 否则(模式不可写,或调用方没读过模式 —— 注入的替身 I/O 抛的错,包看不到它背后)⇒ 先让目录可写,`EPERM` / `EROFS` 句尾提示「只读 / 不可变」的可能。`EROFS` 的出路不变(只读文件系统清不掉)。
+ * `rename` 落点的「可写」不是读出来的而是已证明的({@link RENAME_DIRECTORY_WRITABLE}:走到 rename 时临时文件刚在同一目录建成)—— 一个来源,`EPERM` 与 `EACCES` 同走「可写」那一列,所以 rename 句从不说「make the directory writable」。
  *
  * 原子写器抛 {@link FsFailure}(句子在 `message`,`code` 照抄底层 errno,原错误在 `cause`);它在写器内部已经按更细的落点铸过句子,
  * 命令行 / 迁移用 {@link fsFailureMessage} 取句 —— 已经是 {@link FsFailure} 的原样用,否则按它所在的口铸。
  */
 /** 一次失败发生的地方(闭集):落点加那一步交给操作系统的真实路径(`dir-create-temp` 是要建的临时文件,点名的目录是它的父目录;`rename` 是被盖过的真文件;
- *  `remove` / `write` 是那份文件;`read` 是读的目录或文件)。 */
+ *  `remove` / `write` 是那份文件;`read` 是读的目录或文件;`chmod` 是被保留模式的真文件〔这一格不是「交给操作系统的路径」口径:chmod 的对象是替换它的临时副本〕)。
+ *  `directoryWritable`(只有 `dir-create-temp` / `remove` 两个落点有)—— 失败那一刻,目录的权限位对本进程是否可写(Node 一侧读的事实,见 `./atomic-write` 的 `directoryAdmitsWrite`);
+ *  缺席 = 没读过(注入的替身 I/O),出路顺序按「不可写」走。`rename` 落点没有这一格:走到 rename 时临时文件刚在同一目录建成,目录可写是已证明的事实,由铸点按 {@link RENAME_DIRECTORY_WRITABLE} 给出。
+ */
 export type FsFailureSite = {
     readonly landing: "dir-create-temp";
     readonly path: string;
+    readonly directoryWritable?: boolean;
+} | {
+    readonly landing: "chmod";
+    readonly path: string;
 } | {
     readonly landing: "rename";
     readonly path: string;
 } | {
     readonly landing: "remove";
     readonly path: string;
+    readonly directoryWritable?: boolean;
 } | {
     readonly landing: "read";
     readonly path: string;

package/dist/fs-failure.js

@@ -5,6 +5,8 @@
  *
  * 落点({@link FsFailureSite}.`landing`,闭集)按失败发生在哪一步分句 —— 同一个 errno 在不同落点指向不同的东西:
  *  · `dir-create-temp` —— 原子写器在目标所在目录里建临时文件。目录不让建 ⇒ 点名**目录**(文件本身没错);
+ *  · `chmod`           —— 原子写器给临时文件设模式(已有的文件沿用它原来的模式,临时文件建成后、`rename` 之前设)。这一步失败 ⇒ 点名**设模式**这件事(文件系统不让改文件模式;目录没有问题),
+ *                          不提目录、不提不可变标志;`path` 是被保留模式的**真文件**(chmod 作用在替换它的临时副本上,用户认得的是真文件名);
  *  · `rename`          —— 原子写器 `rename` 盖过目标。目录收了新文件、却换不掉这一份 ⇒ 点名**真文件**;
  *  · `remove`          —— 删一个文件。删的是目录项:目录不让删 ⇒ 点名文件所在的**目录**(与建临时文件同一个因);
  *  · `read`            —— 读一个目录或文件;
@@ -12,20 +14,58 @@
  * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
  *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
  *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
- * 目录落点(`dir-create-temp` / `remove`)的 `EPERM` / `EROFS` 出路句尾加「目录可能是只读 / 不可变(chflags / chattr)」—— 改权限位修不好的那两种。
+ * 三个落点(`dir-create-temp` / `remove` / `rename`)的权限类出路走**同一张表**、一只函数({@link permissionWayOut}):落点表 {@link WAY_OUT_LANDING}(这个落点认哪些 errno、清标志点名谁、动已有目录项的落点才有粘滞目录一句)×
+ * errno 表 {@link WAY_OUT_BY_ERRNO}(穷举;每个 errno 两格 —— 目录权限位对本进程「可写」/「不可写或没读过」)。同一个 `EPERM` 既可能是目录模式不让写,也可能是不可变标志(macOS `chflags uchg` / Linux `chattr +i`),
+ * 同一个 `EACCES` 在模式位已经放行时只能是 ACL 条目或安全模块策略 —— 铸点是纯函数,分不清,但调用方在 Node 一侧能读目录模式,把「模式对本进程可写」这个事实经落点的 `directoryWritable` 递进来:
+ * 「可写」⇒ chmod 已经没用,`EPERM` 的首选出路 = 清标志(`chflags nouchg` / `chattr -i`),动已有目录项的落点(remove / rename)再接粘滞目录一句(那条属主规则给的就是 `EPERM`),`EACCES` 的出路 = 查 ACL / 安全模块(不接粘滞句);
+ * 否则(模式不可写,或调用方没读过模式 —— 注入的替身 I/O 抛的错,包看不到它背后)⇒ 先让目录可写,`EPERM` / `EROFS` 句尾提示「只读 / 不可变」的可能。`EROFS` 的出路不变(只读文件系统清不掉)。
+ * `rename` 落点的「可写」不是读出来的而是已证明的({@link RENAME_DIRECTORY_WRITABLE}:走到 rename 时临时文件刚在同一目录建成)—— 一个来源,`EPERM` 与 `EACCES` 同走「可写」那一列,所以 rename 句从不说「make the directory writable」。
  *
  * 原子写器抛 {@link FsFailure}(句子在 `message`,`code` 照抄底层 errno,原错误在 `cause`);它在写器内部已经按更细的落点铸过句子,
  * 命令行 / 迁移用 {@link fsFailureMessage} 取句 —— 已经是 {@link FsFailure} 的原样用,否则按它所在的口铸。
  */
-/** `dir-create-temp` 里「目录本身不让建文件」的 errno:权限不够、只读文件系统、目录不在。出路 = 让目录可写。 */
-const DIRECTORY_NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT"]);
-/** `remove` 里「目录不让删目录项」的 errno(同一个因:目录不可写)。目录不在 / 文件已不在(ENOENT)不是这个因,给 Node 自己的句子。 */
-const DIRECTORY_ENTRY_NOT_REMOVABLE = new Set(["EACCES", "EPERM", "EROFS"]);
-/** `rename` 里「目录收新文件、却换不掉这一份」的 errno:不可变标志、粘滞目录里别人的文件。出路 = 让文件可被替换。 */
-const FILE_NOT_REPLACEABLE = new Set(["EACCES", "EPERM"]);
-/** 目录落点(`dir-create-temp` / `remove`)的出路。`EPERM`(目录带不可变标志:macOS `chflags uchg`、Linux `chattr +i`)与 `EROFS`(只读文件系统)靠改权限位修不好,
- *  出路句尾提示这一种可能;`EACCES` / `ENOENT` 是纯权限位 / 目录不在,出路就是让目录可写。 */
-const directoryWayOut = (code) => (code === "EPERM" || code === "EROFS" ? "make the directory writable; directory may be read-only or immutable (chflags / chattr)" : "make the directory writable");
+/** `rename` 落点上「目录对本进程可写」的事实:走到 rename 时临时文件刚在**同一目录**建成,这是已证明的,不是读出来的 —— 写器不对 rename 落点读模式位(一个来源)。 */
+const RENAME_DIRECTORY_WRITABLE = true;
+const MODE_BITS_ADMIT = "the directory's permission bits already admit this process, so chmod will not help";
+const MAKE_DIRECTORY_WRITABLE = "make the directory writable";
+const READ_ONLY_OR_IMMUTABLE = `${MAKE_DIRECTORY_WRITABLE}; directory may be read-only or immutable (chflags / chattr)`;
+/** errno 表:每个权限类 errno 在目录权限位「可写」(`admits`:chmod 已无用,说还剩什么真因)与「不可写或没读过」(`otherwise`)两格的出路,以及「可写」时是否接粘滞目录一句(`stickyWhenAdmitted`)。
+ *  `EROFS` / `ENOENT` 的两格同一句 —— 模式位可不可写不改变它们的出路(只读文件系统清不掉;目录不在,先让它在)。 */
+const WAY_OUT_BY_ERRNO = {
+    EPERM: {
+        admits: (flagSubject) => `clear the immutable flag on ${flagSubject} (macOS: chflags nouchg; Linux: chattr -i) — ${MODE_BITS_ADMIT}`,
+        otherwise: READ_ONLY_OR_IMMUTABLE,
+        stickyWhenAdmitted: true,
+    },
+    EACCES: {
+        admits: () => `${MODE_BITS_ADMIT}; an ACL entry may still deny this process (macOS: ls -le; Linux: getfacl); so may a security-module policy (SELinux / AppArmor: the audit log names the rule)`,
+        otherwise: MAKE_DIRECTORY_WRITABLE,
+        stickyWhenAdmitted: false, // 粘滞目录的属主规则返回的是 EPERM(macOS `man 2 unlink` / `rename`;Linux 同,推断),EACCES 的句尾不指向一个产生不了它的因
+    },
+    EROFS: { admits: () => READ_ONLY_OR_IMMUTABLE, otherwise: READ_ONLY_OR_IMMUTABLE, stickyWhenAdmitted: false },
+    ENOENT: { admits: () => MAKE_DIRECTORY_WRITABLE, otherwise: MAKE_DIRECTORY_WRITABLE, stickyWhenAdmitted: false },
+};
+const WAY_OUT_LANDING = {
+    "dir-create-temp": { errnos: ["EACCES", "EPERM", "EROFS", "ENOENT"], flagSubject: "the directory" },
+    remove: { errnos: ["EACCES", "EPERM", "EROFS"], flagSubject: "the file or its directory", stickyVerb: "remove" },
+    rename: { errnos: ["EACCES", "EPERM"], flagSubject: "the file or its directory", stickyVerb: "replace" },
+};
+/** 权限类出路的**唯一一只函数**(三个落点共用,表驱动):`code` 不是这个落点认的权限类 errno ⇒ `undefined`(调用方给 Node 自己的句子)。
+ *  组合律一条:errno 表的格(按 `directoryWritable === true` 选「可写」列或「不可写或没读过」列);「可写」∧ 该 errno 带粘滞 ∧ 这个落点有 `stickyVerb` ⇒ 句尾接 `in a sticky directory only the file's owner may <verb> it`。 */
+const permissionWayOut = (landing, code, directoryWritable) => {
+    const spec = WAY_OUT_LANDING[landing];
+    const errno = spec.errnos.find((e) => e === code);
+    if (errno === undefined)
+        return undefined;
+    const row = WAY_OUT_BY_ERRNO[errno];
+    if (directoryWritable !== true)
+        return row.otherwise;
+    const way = row.admits(spec.flagSubject);
+    return row.stickyWhenAdmitted && spec.stickyVerb !== undefined ? `${way}; in a sticky directory only the file's owner may ${spec.stickyVerb} it` : way;
+};
+/** `chmod` 落点认的 errno:`EPERM` —— 创建者对自己刚建的临时文件 chmod 被拒,只能是文件系统 / 挂载不支持改模式。别的 errno 给 Node 自己的句子。 */
+const CHMOD_REFUSED = new Set(["EPERM"]);
+const CHMOD_WAY_OUT = "the filesystem does not allow changing file modes — keep this file on a filesystem that supports POSIX permissions";
 const errnoOf = (e) => {
     const code = e?.code;
     return typeof code === "string" ? code : undefined;
@@ -49,13 +89,13 @@ export function fsFailureSentence(site, cause) {
     const tag = code === undefined ? "" : ` (${code})`;
     switch (site.landing) {
         case "dir-create-temp":
-            return `cannot write into directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_NOT_WRITABLE.has(code) ? directoryWayOut(code) : nodeSentenceOf(cause, code)}`;
+            return `cannot write into directory ${parentDirectory(site.path)}${tag}: ${permissionWayOut("dir-create-temp", code, site.directoryWritable) ?? nodeSentenceOf(cause, code)}`;
+        case "chmod":
+            return `cannot set the mode of ${site.path}${tag}: ${code !== undefined && CHMOD_REFUSED.has(code) ? CHMOD_WAY_OUT : nodeSentenceOf(cause, code)}`;
         case "rename":
-            return code !== undefined && FILE_NOT_REPLACEABLE.has(code)
-                ? `cannot replace ${site.path}${tag}: make the file replaceable — clear an immutable flag; in a sticky directory only the file's owner may replace it`
-                : `cannot replace ${site.path}${tag}: ${nodeSentenceOf(cause, code)}`;
+            return `cannot replace ${site.path}${tag}: ${permissionWayOut("rename", code, RENAME_DIRECTORY_WRITABLE) ?? nodeSentenceOf(cause, code)}`;
         case "remove":
-            return `cannot remove ${site.path} from directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_ENTRY_NOT_REMOVABLE.has(code) ? directoryWayOut(code) : nodeSentenceOf(cause, code)}`;
+            return `cannot remove ${site.path} from directory ${parentDirectory(site.path)}${tag}: ${permissionWayOut("remove", code, site.directoryWritable) ?? nodeSentenceOf(cause, code)}`;
         case "read":
             return `cannot read ${site.of === "directory" ? "directory " : ""}${site.path}${tag}: ${nodeSentenceOf(cause, code)}`;
         case "write":

package/dist/hooks-config.d.ts

@@ -167,8 +167,8 @@ export declare const HOOKS_DROPPED_PIECE_CODES: readonly ["hooks-not-object", "u
 export type HooksDroppedPieceCode = (typeof HOOKS_DROPPED_PIECE_CODES)[number];
 /**
  * Why the document was REJECTED (closed; each is "a guard may be in this piece"):
- *  · `guard-outside-hooks`       — a guard sign outside `hooks` (top level, under another key, or the document itself matcher-shaped);
- *  · `hooks-is-matcher`          — `hooks` is an array holding objects / arrays, a single matcher, or a single entry;
+ *  · `guard-outside-hooks`       — a guard sign outside `hooks` (top level, under another key, or the document itself matcher-shaped), or the document could not be read at all (path `[]`);
+ *  · `hooks-is-matcher`          — `hooks` is an array holding objects / arrays, a single matcher, or a single entry, or an object that is not a readable block (a class instance, a value that cannot be inspected) holding — or possibly holding — a guard sign;
  *  · `guard-under-unknown-event` — an unknown event name holding a guard sign;
  *  · `guard-event-not-array`     — a guard event whose value is not an array (and not null), or a known event whose non-array value holds a sign;
  *  · `guard-matcher-invalid`     — a bad matcher in a guard event, or a matcher holding a sign (in any event);

package/dist/hooks-config.js

@@ -46,6 +46,7 @@
  * contract; cycles are tolerated, a throwing accessor propagates.
  */
 import { z } from "zod";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { buildQuotedIssue, fixed } from "./quoted-issue.js";
 // ── event vocabulary ───────────────────────────────────────────────────────────────────────────────────────
 // The two halves below are where each word came from (CC 2.1.198's own table, then the later additions) — provenance for the
@@ -141,8 +142,8 @@ export const HOOKS_CLASSIFICATION_OUTCOMES = ["loaded", "loaded-partial", "rejec
 export const HOOKS_DROPPED_PIECE_CODES = ["hooks-not-object", "unknown-event", "event-not-array", "matcher-invalid", "entry-invalid"];
 /**
  * Why the document was REJECTED (closed; each is "a guard may be in this piece"):
- *  · `guard-outside-hooks`       — a guard sign outside `hooks` (top level, under another key, or the document itself matcher-shaped);
- *  · `hooks-is-matcher`          — `hooks` is an array holding objects / arrays, a single matcher, or a single entry;
+ *  · `guard-outside-hooks`       — a guard sign outside `hooks` (top level, under another key, or the document itself matcher-shaped), or the document could not be read at all (path `[]`);
+ *  · `hooks-is-matcher`          — `hooks` is an array holding objects / arrays, a single matcher, or a single entry, or an object that is not a readable block (a class instance, a value that cannot be inspected) holding — or possibly holding — a guard sign;
  *  · `guard-under-unknown-event` — an unknown event name holding a guard sign;
  *  · `guard-event-not-array`     — a guard event whose value is not an array (and not null), or a known event whose non-array value holds a sign;
  *  · `guard-matcher-invalid`     — a bad matcher in a guard event, or a matcher holding a sign (in any event);
@@ -156,12 +157,57 @@ export const HOOKS_REJECTION_CODES = [
     "guard-matcher-invalid",
     "guard-entry-invalid",
 ];
-/** A JSON object: not null, not an array, prototype `Object.prototype` or null. */
-function hookIsRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const proto = Object.getPrototypeOf(value);
-    return proto === Object.prototype || proto === null;
+/** The value's shape — six words: `plain` is a JSON object (not null, not an array, prototype null or a prototype whose own prototype is null: any realm's `Object.prototype`),
+ *  `uninspectable` is a value whose shape cannot be read at all (a proxy that has been revoked, a throwing `getPrototypeOf` trap). This function IS `./plain-json-object`'s `jsonShapeOf`, character for
+ *  character: the classifier is copied as source by consumers' generators, so its closure cannot import — the package has this one second copy, and the test is what keeps it from drifting. */
+function hookShapeOf(v) {
+    try {
+        if (v === null)
+            return "null";
+        if (Array.isArray(v))
+            return "array";
+        if (typeof v === "function")
+            return "non_plain_object";
+        if (typeof v !== "object")
+            return "primitive";
+        const proto = Object.getPrototypeOf(v);
+        return proto === null || Object.getPrototypeOf(proto) === null ? "plain" : "non_plain_object";
+    }
+    catch {
+        return "uninspectable"; // 读形状就抛(已撤销的 Proxy 连 `Array.isArray` 都抛、`getPrototypeOf` 陷阱抛):不是「不朴素」,是读不出 —— 读者按最严处置
+    }
+}
+/** `./plain-json-object` 的 `isPlainJsonObject`,调各自的形状分类核后逐字同文(闭包里不能 import)。 */
+function hookIsRecord(v) {
+    const shape = hookShapeOf(v);
+    return shape === "plain";
+}
+/** Is the value object-like — anything but null / a primitive (arrays, functions and values whose shape cannot be read count). The shape is asked first, never a `typeof` split. */
+function hookIsObjectLike(v) {
+    const shape = hookShapeOf(v);
+    switch (shape) {
+        case "null":
+        case "primitive":
+            return false;
+        case "plain":
+        case "non_plain_object":
+        case "array":
+        case "uninspectable":
+            return true;
+        default: {
+            const unhandled = shape;
+            throw new Error(`hookIsObjectLike: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
+/** `./plain-json-object` 的 `isJsonArray`,逐字同文(闭包里不能 import):`Array.isArray` 的总版 —— 已撤销的 Proxy 读不出 ⇒ 不是数组,不抛。 */
+function hookIsArray(v) {
+    try {
+        return Array.isArray(v);
+    }
+    catch {
+        return false; // 已撤销的 Proxy:读不出 ⇒ 不是数组
+    }
 }
 /** The first own key of `node` (in key order) that names a guard event with a value other than null / undefined / `[]` (CC `ei`). */
 function hookGuardKeyOf(node) {
@@ -169,7 +215,7 @@ function hookGuardKeyOf(node) {
         if (!HOOK_GUARD_EVENTS.includes(key))
             continue;
         const value = node[key];
-        if (value !== null && value !== undefined && !(Array.isArray(value) && value.length === 0))
+        if (value !== null && value !== undefined && !(hookIsArray(value) && value.length === 0))
             return key;
     }
     return undefined;
@@ -179,7 +225,7 @@ function hookLooksLikeMatcher(value) {
     if (!hookIsRecord(value))
         return false;
     const inner = Object.hasOwn(value, "hooks") ? value.hooks : undefined;
-    if (Array.isArray(inner))
+    if (hookIsArray(inner))
         return inner.length > 0;
     return hookIsRecord(inner) && (Object.hasOwn(value, "matcher") || typeof inner.type === "string");
 }
@@ -203,25 +249,48 @@ function hookGuardSignIn(root, rootPath, place) {
     };
     while (pending.length > 0) {
         const [node, frame, at] = pending.pop();
-        if (node === null || typeof node !== "object" || seen[at].has(node))
+        // the shape is asked BEFORE any `typeof` split: a node whose shape cannot be read — a proxy that has been revoked, of a function target included — cannot be shown free of guard signs
+        // ⇒ reported as a sign at its own coordinate (fail-closed: the document is rejected); no `typeof` gate of the classifier's own stands in front of the seat
+        const shape = hookShapeOf(node);
+        let isList = false;
+        switch (shape) {
+            case "null":
+            case "primitive":
+                continue; // not an object: nothing to search
+            case "uninspectable":
+                return pathTo(frame, []);
+            case "array":
+                isList = true;
+                break;
+            case "plain":
+            case "non_plain_object":
+                break; // searched as an object below
+            default: {
+                const unhandled = shape;
+                throw new Error(`hookGuardSignIn: unhandled shape ${String(unhandled)}`);
+            }
+        }
+        const visited = node;
+        if (seen[at].has(visited))
             continue;
-        seen[at].add(node);
-        if (Array.isArray(node)) {
-            for (let i = node.length - 1; i >= 0; i--) {
+        seen[at].add(visited);
+        if (isList) {
+            const list = node;
+            for (let i = list.length - 1; i >= 0; i--) {
                 frames.push({ key: i, parent: frame });
-                pending.push([node[i], frames.length - 1, at === "matcherList" ? "matcher" : "other"]);
+                pending.push([list[i], frames.length - 1, at === "matcherList" ? "matcher" : "other"]);
             }
             continue;
         }
-        const guardKey = hookGuardKeyOf(node);
+        const guardKey = hookGuardKeyOf(visited);
         if (guardKey !== undefined)
             return pathTo(frame, [guardKey]);
-        if (at !== "matcher" && hookLooksLikeMatcher(node))
+        if (at !== "matcher" && hookLooksLikeMatcher(visited))
             return pathTo(frame, []);
-        const keys = Object.keys(node);
+        const keys = Object.keys(visited);
         for (let i = keys.length - 1; i >= 0; i--) {
             frames.push({ key: keys[i], parent: frame });
-            pending.push([node[keys[i]], frames.length - 1, "other"]);
+            pending.push([visited[keys[i]], frames.length - 1, "other"]);
         }
     }
     return undefined;
@@ -248,7 +317,7 @@ function hookFieldFits(base, value) {
         case "stringRecord":
             return hookIsRecord(value) && Object.values(value).every((v) => typeof v === "string");
         case "stringList":
-            if (!Array.isArray(value))
+            if (!hookIsArray(value))
                 return false;
             for (let i = 0; i < value.length; i++)
                 if (typeof value[i] !== "string")
@@ -283,7 +352,7 @@ function hookEntryRead(entry) {
         const base = (optional ? kind.slice(0, -1) : kind);
         if (!hookFieldFits(base, value))
             return { field };
-        out[field] = Array.isArray(value) ? value.slice() : hookIsRecord(value) ? Object.fromEntries(Object.entries(value)) : value;
+        out[field] = hookIsArray(value) ? value.slice() : hookIsRecord(value) ? Object.fromEntries(Object.entries(value)) : value;
     }
     return { entry: out };
 }
@@ -301,18 +370,18 @@ function hookMatcherRead(matcher, at, guardEvent, reject, drop) {
     // the rejection's `field` is the matcher's own guard-event key if it has one, else the first member (document order) whose subtree holds a sign —
     // the order hookGuardSignIn reports
     const signField = hookGuardKeyOf(matcher) ??
-        Object.keys(matcher).find((key) => !(key === "hooks" && Array.isArray(entries)) && hookGuardSignIn(matcher[key], [...at, key], "other") !== undefined);
+        Object.keys(matcher).find((key) => !(key === "hooks" && hookIsArray(entries)) && hookGuardSignIn(matcher[key], [...at, key], "other") !== undefined);
     if (signField !== undefined) {
         reject("guard-matcher-invalid", at, signField);
         return undefined;
     }
     const entrySigns = [];
-    if (Array.isArray(entries))
+    if (hookIsArray(entries))
         for (let j = 0; j < entries.length; j++)
             entrySigns.push(hookGuardSignIn(entries[j], [...at, "hooks", j], "other"));
     const name = Object.hasOwn(matcher, "matcher") ? matcher.matcher : undefined;
-    const badField = name !== undefined && typeof name !== "string" ? "matcher" : !Array.isArray(entries) ? "hooks" : undefined;
-    if (badField !== undefined || !Array.isArray(entries)) {
+    const badField = name !== undefined && typeof name !== "string" ? "matcher" : !hookIsArray(entries) ? "hooks" : undefined;
+    if (badField !== undefined || !hookIsArray(entries)) {
         if (guardEvent || entrySigns.some((sign) => sign !== undefined))
             reject("guard-matcher-invalid", at, badField);
         else
@@ -340,7 +409,10 @@ function hookMatcherRead(matcher, at, guardEvent, reject, drop) {
 /** The `hooks` value → what loads of it (undefined when nothing does), reporting its bad pieces / signs into the two sinks. */
 function hookBlockRead(hooks, reject, drop) {
     if (!hookIsRecord(hooks)) {
-        if (Array.isArray(hooks) && hooks.some((x) => x !== null && typeof x === "object"))
+        if (hookIsArray(hooks) && hooks.some(hookIsObjectLike))
+            reject("hooks-is-matcher", ["hooks"]);
+        // an object that is not a readable block (a class instance, a proxy that cannot be inspected) holding — or possibly holding — a guard sign: reject, never drop it (a dropped guard silently disappears)
+        else if (hookGuardSignIn(hooks, ["hooks"], "other") !== undefined)
             reject("hooks-is-matcher", ["hooks"]);
         else
             drop("hooks-not-object", ["hooks"]);
@@ -355,14 +427,14 @@ function hookBlockRead(hooks, reject, drop) {
         const value = hooks[event];
         const at = ["hooks", event];
         if (!HOOK_EVENTS.includes(event)) {
-            if (hookGuardSignIn(value, at, Array.isArray(value) ? "matcherList" : "other") !== undefined)
+            if (hookGuardSignIn(value, at, hookIsArray(value) ? "matcherList" : "other") !== undefined)
                 reject("guard-under-unknown-event", at);
             else
                 drop("unknown-event", at);
             continue;
         }
         const guardEvent = HOOK_GUARD_EVENTS.includes(event);
-        if (!Array.isArray(value)) {
+        if (!hookIsArray(value)) {
             if ((guardEvent && value !== null) || hookGuardSignIn(value, at, "other") !== undefined)
                 reject("guard-event-not-array", at);
             else
@@ -392,6 +464,15 @@ function hookBlockRead(hooks, reject, drop) {
  * the hooks-classify test file (group ⑤) pins that the free names are exactly these.
  */
 export function classifyHooksConfig(settingsDoc) {
+    try {
+        return hookClassify(settingsDoc);
+    }
+    catch {
+        // reading the document threw (a trap, an accessor that throws): nothing in it can be shown free of guard signs ⇒ rejected at the root — ONE `try` for the whole classifier, none per node
+        return { outcome: "rejected", hooks: undefined, dropped: [], rejections: [{ code: "guard-outside-hooks", path: [] }] };
+    }
+}
+function hookClassify(settingsDoc) {
     const rejections = [];
     const dropped = [];
     const reject = (code, path, field) => {
@@ -401,7 +482,7 @@ export function classifyHooksConfig(settingsDoc) {
         dropped.push(field === undefined ? { code, path } : { code, path, field });
     };
     let hooks;
-    if (settingsDoc !== null && typeof settingsDoc === "object" && !Array.isArray(settingsDoc)) {
+    if (hookIsRecord(settingsDoc)) {
         const doc = settingsDoc;
         for (const key of Object.keys(doc)) {
             const value = doc[key];
@@ -412,7 +493,7 @@ export function classifyHooksConfig(settingsDoc) {
             // the document itself written as a matcher: its top-level `matcher` key is the evidence, reported at that key's place
             const sign = key === "matcher" && hookLooksLikeMatcher(doc)
                 ? [key]
-                : HOOK_GUARD_EVENTS.includes(key) && value !== null && value !== undefined && !(Array.isArray(value) && value.length === 0)
+                : HOOK_GUARD_EVENTS.includes(key) && value !== null && value !== undefined && !(hookIsArray(value) && value.length === 0)
                     ? [key]
                     : hookGuardSignIn(value, [key], "other");
             if (sign !== undefined)
@@ -450,7 +531,7 @@ function hooksFace(carry, strip, take) {
 }
 /** The carrier for one entry of type `type`: the value itself when it says that type, else an untyped object (⇒ the issue names `type`). */
 function entryOfType(value, type) {
-    return value !== null && typeof value === "object" && value.type === type ? value : {};
+    return isPlainJsonObject(value) && value.type === type ? value : {}; // 读不出 / 不是纯数据的值不当「自己说了这个 type」的载体:⇒ `{}`(issue 点名 `type`)
 }
 const entryFace = (type) => hooksFace((v) => ({ hooks: { Stop: [{ hooks: [entryOfType(v, type)] }] } }), 5, (h) => h.Stop[0].hooks[0]);
 export const CommandHookEntry = entryFace("command");

package/dist/http-hook-allowlists.d.ts

@@ -43,11 +43,15 @@ export interface HttpHookAllowlistLayerRead {
     readonly malformed: readonly HttpHookAllowlistKey[];
 }
 /**
- * 从一层的原始设置对象读出两键(唯一读法)。键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样;其余一切(非数组、含非串条目、`null`)
- * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象 ⇒ 两键都缺。
+ * 从一层的原始设置对象读出两键(唯一读法)。键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样(过 `captureAllowlist`〔包内私有〕,与判官同一只读法);其余一切(非数组、含非串条目或洞、取值或读元素时抛、`null`)
+ * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象(`null` / 原始值 / 数组)⇒ 两键都缺。
+ * **是对象但不朴素**(类实例 / `Map` / 建在别的对象原型上的记录 / 函数 —— JSON 解析不出来,只能是嵌入方程序拼的)⇒ 同样 fail-closed:两键都读成 `[]` 并点名 `malformed`。
+ * 把它当「没有设置」读,等于把一层带名单的托管设置静默丢掉、方向放行(与本模块「坏形 = 一个都不许」的失败方向相反)。
+ * 名单键**只靠继承可见**(不是自有键)⇒ 同样 fail-closed:该键读成 `[]` 并点名 `malformed`(自有键盖过继承键;自有键值为 `undefined` 仍是「不设」)。
+ * 原型是带成员的 null 原型对象的对象(`Object.create(<null 原型的名单袋>)`)是一例:它按座位的判据读成朴素、按**自有**键读,名单键只在原型上 ⇒ 坏形。它只能由程序造出,JSON 解析不出来(座位头注 `./plain-json-object` 同写)。
  */
 export declare function readHttpHookAllowlistLayer(source: SettingsSource, settings: unknown): HttpHookAllowlistLayerRead;
-/** 拦下一只 http hook 的原因。`rule`:`empty` = 有一张准入名单是空的(那一层改对之前一只都不许);`url` = 没命中那几张名单里的任何模式。
+/** 拦下一只 http hook 的原因。`rule`:`empty` = 有一张准入名单是空的(那一层改对之前一只都不许;**名单形坏 —— 非串数组、含非串条目或洞、读它或读它的元素时 getter 抛 —— 也读成空**,所以 `empty` 不一定是写成了 `[]`);`url` = 没命中那几张名单里的任何模式。
  *  `sources` = 不放行它的那几张名单所在的层(入参序)。零 URL 回显 —— URL 调用方自己有,按受众给显示形。 */
 export interface HttpHookUrlBlock {
     readonly list: "allowedHttpHookUrls";