@sema-agent/settings-schema 14.5.0 → 14.7.0

package/dist/fleet.js

@@ -20,6 +20,9 @@
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
 import { fnv1a64 } from "./hash.js";
+import { parseDeclared } from "./declared-capture.js";
+import { readDeclaredKey, ownValueOf } from "./own-key-read.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { buildQuotedIssue } from "./quoted-issue.js";
 // ── Web-admin's fleet endpoints (paths, one spelling) ─────────────────────────────────────────────────────
 /**
@@ -163,24 +166,41 @@ export const RestartSignal = z.object({
     since: EpochMs,
     withheld: z.boolean().optional(),
 });
-/**
- * The ONE guarded body judgement behind every wire-shape read in this file: `pick(body)` — one key of the body, or the body itself —
- * is judged against that shape's one schema, and the verdict says WHY when it is not a read: `not-an-object` (the body is null, an
- * array or a scalar) or `invalid` (the shape rejected it, or an accessor threw). It never throws (a probe must not die on one odd
- * body). Almost every reader wants only "a read or nothing" and goes through {@link readSignalBody}; the one reader whose
- * failure direction matters ({@link readCapabilityReading}) takes the reason. A second hand-written guard anywhere else in this
- * package is the defect, not a convenience.
- */
+const WHOLE_BODY = Symbol("whole body");
 function judgeSignalBody(body, pick, schema) {
-    try {
-        if (body === null || typeof body !== "object" || Array.isArray(body))
-            return { kind: "not-an-object" };
-        const parsed = schema.safeParse(pick(body));
-        return parsed.success ? { kind: "read", value: parsed.data } : { kind: "invalid" };
+    if (!isPlainJsonObject(body))
+        return { kind: "not-an-object" };
+    // the carrier key is read from the body's OWN keys (a polluted `Object.prototype.engineSignal` is not a signal the body carries) with the SAME descriptor check as a declared key:
+    // an own key that cannot be read as plain data (hidden — non-enumerable —, or an accessor that throws) is no readable signal, never "absent"
+    let target = body;
+    if (pick !== WHOLE_BODY) {
+        const carried = readDeclaredKey(body, pick);
+        switch (carried.presence) {
+            case "own":
+                target = carried.value;
+                break;
+            case "inherited":
+            case "absent":
+                target = undefined;
+                break;
+            case "hidden":
+            case "unreadable":
+                return { kind: "invalid" };
+            default: {
+                const unhandled = carried;
+                throw new Error(`judgeSignalBody: unhandled presence ${String(unhandled.presence)}`);
+            }
+        }
     }
-    catch {
+    // the validator reads members with `[[Get]]`, required keys included: a key the body does not carry would be filled from a polluted `Object.prototype` (a granted lease from an empty reply, a
+    // ready signal from `{}`, a "declared" capability from nothing) — so it never sees the caller's object: it reads an own-key snapshot of exactly the keys it declares (for a union: of
+    // the arm it will try), on the kernel's isolated prototype `COPY_PROTOTYPE` (no inherited members; it still answers `toString` / `valueOf`), and a value that cannot be captured
+    // (an accessor — throwing or not —, a hidden own key, a trap that throws, a cycle, not plain data) is `invalid`. `parseDeclared` admits only a closed allow-list of schema shapes, each
+    // reasoned and pinned against zod's own verdict and data; any other shape is a loud throw — the package chose the wrong reader, not a caller value that cannot be read
+    const parsed = parseDeclared(schema, target);
+    if (!parsed.ok)
         return { kind: "invalid" };
-    }
+    return { kind: "read", value: parsed.data };
 }
 /**
  * The reader behind every wire-shape read in this file that has no use for a reason: the engine-owned signals on /health
@@ -192,8 +212,6 @@ function readSignalBody(body, pick, schema) {
     const judged = judgeSignalBody(body, pick, schema);
     return judged.kind === "read" ? judged.value : undefined;
 }
-/** `pick` for a shape whose keys sit flat on the body itself (as opposed to under one key of it). */
-const wholeBody = (body) => body;
 /**
  * The model-refusal cause codes (S-768) — CLOSED sets, owned HERE, never a hand-copied second list. Adding a code is
  * one edit in this file; who goes red at compile time: a reader that switches on the code exhaustively (a web-admin), and
@@ -284,11 +302,14 @@ const isModelPlaneRefusalCode = (c) => MODEL_PLANE_REFUSAL_CODES.includes(c);
  * at all — it answers the key only and never judges the engine's version (see {@link InstanceAnnouncement}`.modelRefusals`).
  */
 export function readModelRefusals(body) {
-    const wire = readSignalBody(body, (b) => b.modelRefusals, ModelRefusalsWire);
+    const wire = readSignalBody(body, "modelRefusals", ModelRefusalsWire);
     if (wire === undefined)
         return undefined;
     const entries = Object.fromEntries(Object.entries(wire.entries).filter((e) => isModelEntryRefusalCode(e[1])));
-    const plane = wire.plane !== undefined && isModelPlaneRefusalCode(wire.plane) ? wire.plane : undefined;
+    // the validated output is an ordinary object: an absent optional `plane` stays absent (own key only), never read off a polluted `Object.prototype`
+    const planeRead = ownValueOf(wire, "plane");
+    const planeWord = planeRead.ok ? planeRead.value : undefined;
+    const plane = typeof planeWord === "string" && isModelPlaneRefusalCode(planeWord) ? planeWord : undefined;
     if (Object.keys(entries).length === 0 && plane === undefined)
         return undefined;
     return plane === undefined ? { entries } : { entries, plane };
@@ -362,7 +383,7 @@ export const ENGINE_SIGNAL_KEY = "engineSignal";
  * dialect; the carrier is the one key).
  */
 export function readEngineSignal(body) {
-    return readSignalBody(body, (b) => b[ENGINE_SIGNAL_KEY], EngineSignal);
+    return readSignalBody(body, ENGINE_SIGNAL_KEY, EngineSignal);
 }
 /** The `/health` self-description every orchestrator reads. Liveness and readiness are deliberately SPLIT: `status` stays ok while
  *  draining (the process is alive); readiness is {@link judgeReadiness} over the engine signal the body carries under
@@ -555,6 +576,17 @@ export const FLEET_GENERATION_ENV = "FLEET_GENERATION";
  * {@link FLEET_GENERATION_ENV} it is a reserved worker env name (`WorkerSpec.env` / `secretEnv` cannot set it).
  */
 export const FLEET_SCOPE_ENV = "FLEET_SCOPE";
+/**
+ * The env name a fleet member's advertise address travels under — the base URL this instance tells the control plane it can be
+ * reached at; the control plane appends request paths to it. The operator or the config renderer sets it (on Kubernetes the renderer
+ * writes a `$(POD_IP)` placeholder in the value and the kubelet expands it), and the engine reads it back. Both sides import THIS
+ * constant; neither spells the name. The address is a base that request paths are appended to, so a reader judges a present, non-empty
+ * value with `pathBaseUrlFlaws` (main barrel) — the one judge of every such seat, which forbids a credential, a
+ * query and a fragment there and allows a path prefix; judge the value AFTER the deployment has expanded its placeholders. Absent or
+ * the empty string means "no address declared" (the `${NAME:-}` idiom of a compose file), and that reading is the caller's, not the
+ * judge's.
+ */
+export const FLEET_ADVERTISE_ADDRESS_ENV = "FLEET_ADVERTISE_ADDRESS";
 /**
  * The serving lease — the ONE fence between a superseded generation and the traffic it must stop taking. A fleet-member
  * engine renews it with web-admin; web-admin answers per the lifecycle object it holds for that instance. Three constants
@@ -646,14 +678,14 @@ export const SERVING_LEASE_VERDICTS = ["granted", "denied", "unknown"];
 /** Web-admin side: the request body of a serving-lease renewal. Shape mismatch / non-object / throwing accessor ⇒ `undefined`,
  *  never throws (same guarded reader as every other read in this file). */
 export function readServingLeaseRequest(body) {
-    return readSignalBody(body, wholeBody, ServingLeaseRequest);
+    return readSignalBody(body, WHOLE_BODY, ServingLeaseRequest);
 }
 /** Engine side: the reply to a renewal, judged by its `verdict` key: `granted` needs a valid `ttlMs`, `denied` is `denied`
  *  whatever its `reason` (see {@link ServingLeaseReading}), `unknown` is `unknown`. A non-object, a throwing accessor, a
  *  `verdict` outside the three words or a `granted` without a valid `ttlMs` ⇒ `undefined`, never throws — and `undefined`
  *  is read like an unreachable web-admin, never like `denied` and never like `granted`. */
 export function readServingLeaseResponse(body) {
-    return readSignalBody(body, wholeBody, ServingLeaseReadFace);
+    return readSignalBody(body, WHOLE_BODY, ServingLeaseReadFace);
 }
 /**
  * What web-admin says it can do: capability bits an engine reads before it starts using a web-admin-side endpoint.
@@ -703,14 +735,16 @@ const CapabilitiesCarrier = z.object({ [HEARTBEAT_REPLY_CAPABILITIES_KEY]: WebAd
  * other reader here.
  */
 export function readCapabilityReading(reply) {
-    const judged = judgeSignalBody(reply, wholeBody, CapabilitiesCarrier);
+    const judged = judgeSignalBody(reply, WHOLE_BODY, CapabilitiesCarrier);
     switch (judged.kind) {
         case "not-an-object":
             return { kind: "unreadable", why: "not-an-object" };
         case "invalid":
             return { kind: "unreadable", why: "invalid-capabilities" };
         case "read": {
-            const capabilities = judged.value[HEARTBEAT_REPLY_CAPABILITIES_KEY];
+            // the validated output is an ordinary object: an absent optional key must stay absent, not be read off a polluted `Object.prototype` — own key only (it was parsed from a snapshot, so it cannot be unreadable)
+            const carried = ownValueOf(judged.value, HEARTBEAT_REPLY_CAPABILITIES_KEY);
+            const capabilities = carried.ok ? carried.value : undefined;
             return capabilities === undefined ? { kind: "undeclared" } : { kind: "declared", capabilities };
         }
         default: {
@@ -754,11 +788,11 @@ export const DrainReceiptState = z.enum(DRAIN_RECEIPT_STATES);
 export const DrainReceipt = EngineDraining.extend({ state: DrainReceiptState });
 /** Engine side: the request body of the drain endpoint. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
 export function readDrainRequest(body) {
-    return readSignalBody(body, wholeBody, DrainRequest);
+    return readSignalBody(body, WHOLE_BODY, DrainRequest);
 }
 /** Caller side: the drain endpoint's answer. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
 export function readDrainReceipt(body) {
-    return readSignalBody(body, wholeBody, DrainReceipt);
+    return readSignalBody(body, WHOLE_BODY, DrainReceipt);
 }
 // ── Domain 3: dispatch policy (traffic + failover + LB — three domains, one gateway) ──────────────────────
 export const DISPATCH_STRATEGIES = ["round-robin", "least-inflight", "consistent-hash"];

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,18 +14,18 @@
  * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
  *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
  *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
- * 三个落点(`dir-create-temp` / `remove` / `rename`)的权限类出路走**同一条顺序**(`rename` 的「可写」是已证明的事实,见下)({@link permissionWayOut}):同一个 `EPERM` 既可能是目录模式不让写,也可能是不可变标志
- * (macOS `chflags uchg` / Linux `chattr +i`)—— 铸点是纯函数,分不清,但调用方在 Node 一侧能读目录模式,把「模式对本进程可写」这个事实经落点的 `directoryWritable` 递进来:
- * `EPERM` ∧ 可写 ⇒ chmod 已经没用,首选出路 = 清标志(`chflags nouchg` / `chattr -i`);否则(模式不可写,或调用方没读过模式 —— 注入的替身 I/O 抛的错,包看不到它背后)⇒ 先 chmod,
- * 句尾提示「只读 / 不可变」的可能。`EROFS` 的出路不变(只读文件系统清不掉),`EACCES` 是纯权限位,不吃这条规则。
- * `rename` 落点的「可写」不是读出来的而是已证明的(走到 rename 时临时文件刚在同一目录建成):`EPERM` 恒为清标志先行,`EACCES` 保留 14.4.0 的文件向原句("make the file replaceable — clear an immutable flag"),
- * 两者句尾都是粘滞目录一句,都不说「make the directory writable」。
+ * 三个落点(`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} 给出。
  */
@@ -31,6 +33,9 @@ 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;

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,36 +14,58 @@
  * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
  *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
  *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
- * 三个落点(`dir-create-temp` / `remove` / `rename`)的权限类出路走**同一条顺序**(`rename` 的「可写」是已证明的事实,见下)({@link permissionWayOut}):同一个 `EPERM` 既可能是目录模式不让写,也可能是不可变标志
- * (macOS `chflags uchg` / Linux `chattr +i`)—— 铸点是纯函数,分不清,但调用方在 Node 一侧能读目录模式,把「模式对本进程可写」这个事实经落点的 `directoryWritable` 递进来:
- * `EPERM` ∧ 可写 ⇒ chmod 已经没用,首选出路 = 清标志(`chflags nouchg` / `chattr -i`);否则(模式不可写,或调用方没读过模式 —— 注入的替身 I/O 抛的错,包看不到它背后)⇒ 先 chmod,
- * 句尾提示「只读 / 不可变」的可能。`EROFS` 的出路不变(只读文件系统清不掉),`EACCES` 是纯权限位,不吃这条规则。
- * `rename` 落点的「可写」不是读出来的而是已证明的(走到 rename 时临时文件刚在同一目录建成):`EPERM` 恒为清标志先行,`EACCES` 保留 14.4.0 的文件向原句("make the file replaceable — clear an immutable flag"),
- * 两者句尾都是粘滞目录一句,都不说「make the directory writable」。
+ * 三个落点(`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:不可变标志、粘滞目录里别人的文件。出路 = 文件向(见 {@link renameWayOut}),句尾加粘滞目录一句。 */
-const FILE_NOT_REPLACEABLE = new Set(["EACCES", "EPERM"]);
 /** `rename` 落点上「目录对本进程可写」的事实:走到 rename 时临时文件刚在**同一目录**建成,这是已证明的,不是读出来的 —— 写器不对 rename 落点读模式位(一个来源)。 */
 const RENAME_DIRECTORY_WRITABLE = true;
-/** 权限类出路的**唯一一条顺序**(三个落点共用;`rename` 以「可写」为已证明的事实代入):`EPERM` ∧ 目录模式对本进程可写 ⇒ 真因只能是不可变标志(或粘滞位),chmod 无效 ⇒ 首选出路 = 清标志,点名清谁(`flagSubject`)与两个平台的命令;
- *  其余 ⇒ 先让目录可写,`EPERM` / `EROFS`(靠改权限位修不好的两种)的句尾提示「只读 / 不可变」;`EACCES` / `ENOENT` 是纯权限位 / 目录不在,出路就是让目录可写。 */
-const permissionWayOut = (code, directoryWritable, flagSubject) => code === "EPERM" && directoryWritable === true
-    ? `clear the immutable flag on ${flagSubject} (macOS: chflags nouchg; Linux: chattr -i) — the directory's permission bits already admit this process, so chmod will not help`
-    : code === "EPERM" || code === "EROFS"
-        ? "make the directory writable; directory may be read-only or immutable (chflags / chattr)"
-        : "make the directory writable";
-/** `rename` 落点的出路(文件向):`EPERM` 走 {@link permissionWayOut} 的顺序(目录可写已证明 ⇒ 清标志先行);`EACCES` 是 14.4.0 的原句逐字 ——
- *  无论哪个 errno,都不说「make the directory writable」(与已证明的事实自相矛盾)。 */
-const renameWayOut = (code) => code === "EPERM" ? permissionWayOut(code, RENAME_DIRECTORY_WRITABLE, "the file or its directory") : "make the file replaceable — clear an immutable flag";
-/** `rename` 句尾的粘滞目录一句(与权限类出路并列的另一个因:粘滞目录里别人的文件只有属主能换)。 */
-const STICKY_DIRECTORY_NOTE = "in a sticky directory only the file's owner may replace it";
+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;
@@ -65,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) ? permissionWayOut(code, site.directoryWritable, "the directory") : 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}: ${renameWayOut(code)}; ${STICKY_DIRECTORY_NOTE}`
-                : `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) ? permissionWayOut(code, site.directoryWritable, "the file or its directory") : 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/hash.d.ts

@@ -1,12 +1,3 @@
-/**
- * Tiny stable content hash — shared by `workerSpecHash` (reconciler drift detection) and the per-worker
- * `/effective` ETag (so an unrelated roster change doesn't churn a worker's cache). Zero-dep, deterministic.
- *
- * FNV-1a **64-bit** (BigInt) → 16 hex. NOT cryptographic; it's a change-detector. 64-bit pushes the
- * birthday-collision boundary to ~5B distinct inputs — a collision would silently SUPPRESS a needed
- * container restart (drift) or serve a stale 304 (ETag), so we don't want the 32-bit ~77k boundary here
- * (council finding). Output length isn't a contract (values are only compared for equality before/after).
- */
 /** Max nesting stableStringify will hash. A real EffectiveConfig nests ~10-15 deep; this generous cap turns a
  *  pathologically deep OR cyclic value (e.g. a poisoned `model.extraBody` = z.unknown()) into a DETERMINISTIC
  *  throw instead of a `RangeError: Maximum call stack` that would crash every scoped-worker `/effective` poll

package/dist/hash.js

@@ -7,6 +7,8 @@
  * container restart (drift) or serve a stale 304 (ETag), so we don't want the 32-bit ~77k boundary here
  * (council finding). Output length isn't a contract (values are only compared for equality before/after).
  */
+import { UNINSPECTABLE, containerView, inspect, valueOfDescriptor } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
 /** Max nesting stableStringify will hash. A real EffectiveConfig nests ~10-15 deep; this generous cap turns a
  *  pathologically deep OR cyclic value (e.g. a poisoned `model.extraBody` = z.unknown()) into a DETERMINISTIC
  *  throw instead of a `RangeError: Maximum call stack` that would crash every scoped-worker `/effective` poll
@@ -37,13 +39,68 @@ export function stableStringify(v, depth = 0) {
     // crash every scoped-worker poll. Treat undefined like null for hashing.
     if (v === undefined)
         return "null";
-    if (v === null || typeof v !== "object")
-        return JSON.stringify(v);
-    if (Array.isArray(v))
-        return `[${v.map((x) => stableStringify(x, depth + 1)).join(",")}]`;
-    const obj = v;
-    const keys = Object.keys(obj).sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k], depth + 1)}`).join(",")}}`;
+    // the shape is asked of the seat (total); a node whose members cannot be read is REFUSED loudly with the package's one sentence — a hash of "what could be read" would be a hash of something else.
+    // Every container is read through the package's ONE whole-container read (`containerView`, wide): its members and ONE descriptor each are fixed when they are listed (objects: own
+    // enumerable string keys; arrays: own indexes + `length`); a value only ever comes from such a descriptor — not from `[[Get]]` (a proxy's `get` / `has` traps are not asked), not
+    // through the prototype chain (a hole stays a hole), not from a method of the array (an own `map` is not called).
+    // VALUE ORDER = the hash's own order: object keys sorted, array indexes ascending; each member's value is taken from its listed descriptor right before its subtree is hashed,
+    // so getters run in the order the hash emits them (a value-first read would run them in insertion order and change the hash of a successful read).
+    // Every raw read happens inside `inspect`, the recursion outside it: a refusal raised by a child (depth, unreadable) is never re-labelled by its parent.
+    const shape = jsonShapeOf(v);
+    switch (shape) {
+        case "null":
+        case "primitive":
+            return JSON.stringify(v);
+        case "uninspectable":
+            throw new TypeError(`stableStringify: ${UNINSPECTABLE} — refusing to hash`);
+        case "array": {
+            // the length is the listed `length` value through `ToLength(ToNumber(·))`; an index that is not an own member is a hole (it hashes as nothing between two commas)
+            const view = readOrRefuse(() => containerView(v, true, "wide"));
+            const length = readOrRefuse(() => lengthOf(view.length));
+            const byIndex = new Map(view.members);
+            let out = "";
+            for (let i = 0; i < length; i++) {
+                const d = byIndex.get(String(i));
+                out += `${i === 0 ? "" : ","}${d === undefined ? "" : stableStringify(readOrRefuse(() => valueOfDescriptor(v, d)), depth + 1)}`;
+            }
+            return `[${out}]`;
+        }
+        case "plain":
+        case "non_plain_object": {
+            if (typeof v === "function")
+                return JSON.stringify(v); // not data (and never was hashed as an object)
+            // the package's one whole-container read (wide): the members — own ENUMERABLE string keys, `Object.keys`' set — and ONE descriptor each are fixed when the keys are listed
+            // (a later change to the object by a getter does not change what is hashed); keys sorted; each member's value comes from ITS listed descriptor right before its subtree is hashed
+            const members = readOrRefuse(() => containerView(v, false, "wide")).members.slice().sort(([a], [b]) => (a < b ? -1 : 1));
+            let out = "";
+            for (const [key, d] of members) {
+                const value = readOrRefuse(() => valueOfDescriptor(v, d));
+                out += `${out === "" ? "" : ","}${JSON.stringify(key)}:${stableStringify(value, depth + 1)}`;
+            }
+            return `{${out}}`;
+        }
+        default: {
+            const unhandled = shape;
+            throw new Error(`stableStringify: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
+/** One raw read of a node's member (inside `inspect`); unreadable ⇒ the package's one refusal sentence. */
+function readOrRefuse(read) {
+    const r = inspect(read);
+    if (!r.ok)
+        throw new TypeError(`stableStringify: ${r.sentence} — refusing to hash`);
+    return r.value;
+}
+/** An array's length from its listed `length` value: `ToLength(ToNumber(value))` — the unary plus is `ToNumber` (a BigInt / Symbol throws, an object is converted through
+ *  `valueOf` / `toString`), not a number ⇒ 0, truncated — with the allocation limit of an array: a length beyond the largest array length (2^32 − 1 — only a proxy's descriptor
+ *  trap can report one) throws before a single index is hashed (the caller refuses with the one sentence). */
+function lengthOf(value) {
+    const n = +value;
+    const length = Number.isNaN(n) || n <= 0 ? 0 : Math.floor(n);
+    if (length > 2 ** 32 - 1)
+        throw new RangeError("Invalid array length");
+    return length;
 }
 const FNV64_OFFSET = 0xcbf29ce484222325n;
 const FNV64_PRIME = 0x100000001b3n;

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);