@sema-agent/settings-schema 14.4.0 → 14.6.0

package/dist/safety-merge-spec.js

@@ -4,8 +4,12 @@
  * law. This formalizes settings-core's v2-design §3 merge-spec into a published-data contract; the SEMANTIC
  * author is settings-core, web-admin maintains the formalized artifact here (this package), the axis VALUE domains
  * are core's (@sema-agent/core SAFETY_AXIS_VOCABULARY — validated by a dev-only conformance test, never a runtime
- * import). Each consumer keeps its OWN key→category map (client's SemaSettings KEY_CONTRACTS, web-admin's
- * config-field→category map); THIS file is only the shared category spec they all cite — no third copy of the law.
+ * import). The settings-document UNIT table — which keys of a settings file carry a merge contract, where each sits,
+ * which category below it maps into, and how its raw value reads — is published by this package too, as
+ * `SETTINGS_UNITS` (`./settings-units.ts`, 14.6.0): a consumer reads it instead of keeping a key→category map of its
+ * own for those ten units (the http-hook allowlist keys are the one exception: `./http-hook-allowlists` keys and reads them
+ * itself, with its own malformed-value reading — see the `./settings-units` header). THIS file is the category spec every unit
+ * cites — no second copy of the law.
  *
  * Per-category behavior is fully determined by `mergeShape` + `minTrust` + `tighten` + `enforcement` + `fail` — and,
  * for a MEMBERIZED category (one that declares `members`, 1.1.0), by its member rows: each member's own floor and
@@ -14,6 +18,16 @@
  * admitted or rejected as one value under its `minTrust`. A resolver reads this table and has NO per-key
  * special-casing.
  *
+ * COMPARISON (14.6.0) — "which of two values is stricter" has ONE implementation, {@link tightenVerdict}, and it reads
+ * ORDER only, never spelling (an empty-set sentinel, a "≤ 0 means off" cap, CC's `"disable"`, a mode alias are the value
+ * owner's reading — `readSettingsUnit` for a settings unit).
+ * A category's `tighten` answers ONLY the value of a `whole` unit mapped into it (today: `permissionMode`'s enumRank,
+ * `additionalDirectories`' setNarrower, `none` for the rest).
+ * A DECLARED member's comparator is derived from its row's value class ({@link memberTighten}: `boolPole` ⇒ boolStricter
+ * at that pole; `list` ⇒ setUnion for a tighten member, setNarrower for a loosen one). A memberized category's whole value
+ * and its UNDECLARED members have NO comparator — they only have the category floor's admission (the paragraph above);
+ * asking for one is a RangeError, never a fallback to the category rule.
+ *
  * MEMBER-LEVEL ADMISSION (1.1.0 — the WRITTEN layer of the permission-rule dual-channel ruling, [ref] ④;
  * the executing layer is core's `prepareCcImport` door + `RuleAddOrigin`, the resolver/shell halves are cli's):
  *   A category may declare `members`, each with its own admission floor and DIRECTION. Today only `permissions`
@@ -51,6 +65,9 @@
  *   ladder anyway; only {@link trustRank} is.
  */
 import { z } from "zod";
+import { MAX_HASH_DEPTH, stableStringify } from "./hash.js";
+import { captureStringArray, dataDescriptor } from "./definition-copy.js";
+import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js";
 /** How values from different layers/principals combine for a category. */
 export const MergeShape = z.enum(["denyFirst", "replace", "runAll", "overrideByName", "concat"]);
 /** The trust-tier VOCABULARY as a RUNTIME VALUE — the ONE source of the ladder's words, in the same form as
@@ -117,11 +134,19 @@ export const MemberDirection = z.enum(["loosen", "tighten"]);
  *  must be the LOOSEN floor (the category's), so a consumer that predates this field (its schema strips
  *  `boolPole`) reads the row as tighten@<loosen-floor> and withholds BOTH poles from low-trust layers —
  *  fail-closed (it loses only the convenience of low-trust tightening, it can never admit a loosening write).
- *  Resolution is value-aware: pass the candidate value to {@link memberAdmission} / {@link memberMinTrust}. */
+ *  Resolution is value-aware: pass the candidate value to {@link memberAdmission} / {@link memberMinTrust}.
+ *
+ *  `list` (14.6.0) — the VALUE-CLASS seat of a member whose value is a string list (`permissions.allow` / `deny` / `ask`,
+ *  `sandboxNetwork.filesystem.denyWrite` / `denyRead`). A row declares exactly ONE value class — `boolPole` (a boolean)
+ *  or `list` — and the member's comparator is derived from it ({@link resolveMemberTighten}); neither or both is a
+ *  RangeError there, never a guess (a future numeric member is neither, so it can never be silently read as a list —
+ *  its value class has to be designed first). The seat carries no floor, so admission reads exactly as before, and a
+ *  consumer whose schema predates it strips it. */
 export const MemberAdmission = z.object({
     direction: MemberDirection,
     minTrust: MinTrust.optional(),
     boolPole: z.object({ strict: z.boolean(), minTrust: MinTrust }).optional(),
+    list: z.literal(true).optional(),
 });
 /** WHERE the category is enforced (STRENGTH) — MUST stay in lockstep with `EffectiveKey.enforcement` (types.ts).
  *  gate=data-plane engine, server=control-plane/TOB boundary, resolver=merger correctness, client=UI only. */
@@ -133,14 +158,166 @@ export const FailMode = z.enum(["closed", "open"]);
  *  from LOOSEST→STRICTEST — the category's whole vocabulary: a word outside it is refused, and a ONE-word order (11.0.0:
  *  `shellGate`, whose engine vocabulary is the single floor word) is the degenerate rank where the only merge is identity;
  *  `boolStricter.strict` is the bool value that is the tighter one; `setNarrower` = a subset is tighter; `policyDenyWins` =
- *  deny beats allow; `none` = not rank-tightenable (replace / conflict-reject). */
+ *  deny beats allow (a fold law BETWEEN a category's members, not an order on one value); `none` = not rank-tightenable
+ *  (replace / conflict-reject); `setUnion` (14.6.0) = a superset is tighter; `numericLower` (14.6.0) = a smaller number is
+ *  tighter, `+Infinity` (no limit) the loosest. A parameter may only change the ORDER (`strict`, `order`), so the two
+ *  appended words take none: a literal that reads as "empty set" or "no limit" is a spelling, normalized by the value's
+ *  owner before it reaches the comparator. Executed by {@link tightenVerdict}. The two words are appended at the tail
+ *  (README 发版纪律: a consumer holding an exhaustive table over `rule` goes compile-red at pickup — the pickup cost). */
 export const TightenRule = z.discriminatedUnion("rule", [
     z.object({ rule: z.literal("none") }),
     z.object({ rule: z.literal("policyDenyWins") }),
     z.object({ rule: z.literal("setNarrower") }),
     z.object({ rule: z.literal("boolStricter"), strict: z.boolean() }),
     z.object({ rule: z.literal("enumRank"), order: z.array(z.string()).min(1) }),
+    z.object({ rule: z.literal("setUnion") }),
+    z.object({ rule: z.literal("numericLower") }),
 ]);
+/** Where `candidate` lands relative to `existing` under a {@link TightenRule} (14.6.0; closed, in this order):
+ *  `equal` · `stricter` · `looser` · `unordered` (comparable values, neither side contains the other — two different sets,
+ *  two different `none` values) · `unreadable` (a side is outside the rule's normalized domain — absent, misspelled,
+ *  the wrong type). */
+export const TIGHTEN_VERDICTS = ["equal", "stricter", "looser", "unordered", "unreadable"];
+/** `diff` > 0 ⇒ the candidate is higher on the strictness order. */
+function orderVerdict(diff) {
+    return diff > 0 ? "stricter" : diff < 0 ? "looser" : "equal";
+}
+/** A string list as a set (order and duplicates do not count); `undefined` when the value is not an array of strings
+ *  — a sparse array, an accessor that throws, a proxy that cannot be read (revoked, a trap that throws) is not one: all through the package's one string-array
+ *  reading ({@link captureStringArray}), so the comparator never throws on them and never splits a string. */
+function stringSetOf(v) {
+    const list = captureStringArray(v);
+    return list === undefined ? undefined : new Set(list);
+}
+/** `superset ⇒ stricter` for setUnion, the mirror for setNarrower. */
+function setVerdict(existing, candidate, supersetIsStricter) {
+    const a = stringSetOf(existing);
+    const b = stringSetOf(candidate);
+    if (a === undefined || b === undefined)
+        return "unreadable";
+    const candidateCoversExisting = [...a].every((x) => b.has(x));
+    const existingCoversCandidate = [...b].every((x) => a.has(x));
+    if (candidateCoversExisting && existingCoversCandidate)
+        return "equal";
+    if (candidateCoversExisting)
+        return supersetIsStricter ? "stricter" : "looser";
+    if (existingCoversCandidate)
+        return supersetIsStricter ? "looser" : "stricter";
+    return "unordered";
+}
+/** numericLower's domain: a finite number, or `+Infinity` (= no limit, the loosest). NaN / `-Infinity` / a non-number are not in it. */
+function isNumericLowerValue(v) {
+    return typeof v === "number" && (Number.isFinite(v) || v === Number.POSITIVE_INFINITY);
+}
+const NOT_STRICT_JSON = { ok: false };
+function strictJsonCopy(v, depth = 0) {
+    if (depth > MAX_HASH_DEPTH)
+        return NOT_STRICT_JSON;
+    if (v === null || typeof v === "string" || typeof v === "boolean")
+        return { ok: true, value: v };
+    if (typeof v === "number")
+        return Number.isFinite(v) ? { ok: true, value: v } : NOT_STRICT_JSON;
+    if (typeof v !== "object")
+        return NOT_STRICT_JSON; // undefined / function / symbol / bigint
+    if (isJsonArray(v)) {
+        const length = v.length;
+        if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0)
+            return NOT_STRICT_JSON;
+        const out = [];
+        for (let i = 0; i < length; i++) {
+            const member = strictJsonStored(Object.getOwnPropertyDescriptor(v, i), depth);
+            if (!member.ok)
+                return NOT_STRICT_JSON;
+            Object.defineProperty(out, i, dataDescriptor(member.value));
+        }
+        return { ok: true, value: out };
+    }
+    if (!isPlainJsonObject(v))
+        return NOT_STRICT_JSON; // Date / Map / class instance
+    const out = Object.create(null);
+    for (const key of Reflect.ownKeys(v)) {
+        if (typeof key === "symbol")
+            continue; // never serialized
+        const desc = Object.getOwnPropertyDescriptor(v, key);
+        if (desc !== undefined && desc.enumerable !== true)
+            continue; // never serialized (what `Object.keys` leaves out)
+        const member = strictJsonStored(desc, depth);
+        if (!member.ok)
+            return NOT_STRICT_JSON;
+        Object.defineProperty(out, key, dataDescriptor(member.value));
+    }
+    return { ok: true, value: out };
+}
+/** One member, judged by the descriptor read ONCE: a stored value (a hole has no descriptor; an accessor has no `value`) that is itself strict JSON. */
+function strictJsonStored(desc, depth) {
+    if (desc === undefined || !Object.hasOwn(desc, "value"))
+        return NOT_STRICT_JSON; // 描述符本身也只读自有键:`Object.prototype.value` 被污染时访问器描述符不会「有 value」
+    return strictJsonCopy(desc.value, depth + 1);
+}
+/** `none`: compares the DESCRIPTOR VIEW, read once ({@link strictJsonCopy}), and serializes only the copies — member values never go through `[[Get]]`. The ONE guard around the
+ *  whole comparison catches what the walk itself cannot read (a proxy that has been revoked, a trap that throws on `ownKeys` / a descriptor / an array's `length`): that is outside the
+ *  domain ⇒ `unreadable`, never a throw. */
+function noneVerdict(existing, candidate) {
+    try {
+        const a = strictJsonCopy(existing);
+        const b = strictJsonCopy(candidate);
+        if (!a.ok || !b.ok)
+            return "unreadable";
+        return stableStringify(a.value) === stableStringify(b.value) ? "equal" : "unordered"; // serializes the COPIES — the descriptor view the walk saw
+    }
+    catch {
+        return "unreadable";
+    }
+}
+/**
+ * THE comparator (14.6.0): where `candidate` lands relative to `existing` under `rule`. One implementation for every
+ * consumer — the shell's resolver, the server's catalog column, the profile loader — so "stricter" has one reading.
+ * It reads ORDER only: each rule has a normalized domain, and a side outside it is `unreadable` (spellings are normalized
+ * by the value's owner first — `readSettingsUnit` for a settings unit):
+ *  · `enumRank`     — a word of `order`; the higher rank is stricter, the same word `equal`;
+ *  · `boolStricter` — a boolean (strict equality, never truthiness: the string `"false"` is unreadable, not `true`);
+ *                     the `strict` pole is stricter;
+ *  · `setUnion`     — an array of strings, as a SET (order and duplicates do not count): a proper superset is stricter,
+ *                     a proper subset looser, the same set `equal`, neither containing the other `unordered`;
+ *  · `setNarrower`  — the same domain, the opposite direction;
+ *  · `numericLower` — a finite number or `+Infinity` (no limit, the loosest): the smaller is stricter;
+ *  · `none`         — a strict JSON value no deeper than {@link MAX_HASH_DEPTH}: `equal` when `stableStringify` agrees
+ *                     (key order does not count), else `unordered`;
+ *  · `policyDenyWins` — a RangeError: it is the fold law BETWEEN a category's members, not an order on one value —
+ *                     compare a member through {@link memberTighten}.
+ * Both sides must be present: absence is not a value (`undefined` ⇒ `unreadable`); "an absent landing spot takes the
+ * write" is the loading law's business, not the comparator's. A rule word outside the closed set (a JavaScript /
+ * deserialized caller) is a RangeError, never a silent verdict.
+ */
+export function tightenVerdict(rule, existing, candidate) {
+    switch (rule.rule) {
+        case "enumRank": {
+            const a = typeof existing === "string" ? rule.order.indexOf(existing) : -1;
+            const b = typeof candidate === "string" ? rule.order.indexOf(candidate) : -1;
+            return a < 0 || b < 0 ? "unreadable" : orderVerdict(b - a);
+        }
+        case "boolStricter":
+            if (typeof existing !== "boolean" || typeof candidate !== "boolean")
+                return "unreadable";
+            return existing === candidate ? "equal" : candidate === rule.strict ? "stricter" : "looser";
+        case "setUnion":
+            return setVerdict(existing, candidate, true);
+        case "setNarrower":
+            return setVerdict(existing, candidate, false);
+        case "numericLower":
+            if (!isNumericLowerValue(existing) || !isNumericLowerValue(candidate))
+                return "unreadable";
+            return existing === candidate ? "equal" : candidate < existing ? "stricter" : "looser";
+        case "none":
+            return noneVerdict(existing, candidate);
+        case "policyDenyWins":
+            throw new RangeError("tightenVerdict: policyDenyWins is the fold law between a category's members (deny beats allow), not an order on one value — compare a member through memberTighten(category, member)");
+        default: {
+            const unknown = rule;
+            throw new RangeError(`tightenVerdict: unknown rule '${String(unknown.rule)}' — not a TightenRule word`);
+        }
+    }
+}
 export const MergeCategorySpec = z.object({
     mergeShape: MergeShape,
     minTrust: MinTrust,
@@ -167,9 +344,9 @@ export const SAFETY_MERGE_SPEC = {
         mergeShape: "denyFirst", minTrust: "global", tighten: { rule: "policyDenyWins" }, enforcement: "gate", fail: "closed",
         seam: "toolPolicy + deny-narrowing (SessionPolicyStore)", coreAxis: "permissionDecision",
         members: {
-            allow: { direction: "loosen", minTrust: "global" },
-            deny: { direction: "tighten", minTrust: "local" },
-            ask: { direction: "tighten", minTrust: "local" },
+            allow: { direction: "loosen", minTrust: "global", list: true },
+            deny: { direction: "tighten", minTrust: "local", list: true },
+            ask: { direction: "tighten", minTrust: "local", list: true },
         },
     },
     // Order covers the FULL shell-addressable mode vocabulary — a word missing here is not "unknown", it makes every
@@ -203,7 +380,7 @@ export const SAFETY_MERGE_SPEC = {
     // row carries `boolPole {strict, minTrust:"local"}` and keeps its ROW floor at the loosen floor "global" —
     // value-aware consumers admit the strict pole at "local"; pole-blind consumers (whose schema strips boolPole)
     // read tighten@global and withhold BOTH poles from low-trust layers (fail-closed: convenience lost, never a
-    // loosening write admitted). The two deny arrays narrow in every write, so they are plain tighten@"local".
+    // loosening write admitted). The two deny arrays narrow in every write, so they are plain tighten@"local" (value class `list`).
     // DELIBERATELY NOT members (⇒ the 1.1.0 header law: an undeclared member stays under the category minTrust
     // "global" — exactly the consumer's fail-closed withhold arm, so FUTURE sub-keys are withheld by default):
     //   · the loosen face — network.allowedDomains / network.allowUnixSockets / filesystem.allowWrite /
@@ -230,8 +407,8 @@ export const SAFETY_MERGE_SPEC = {
             "network.allowAllUnixSockets": { direction: "tighten", minTrust: "global", boolPole: { strict: false, minTrust: "local" } },
             "network.allowLocalBinding": { direction: "tighten", minTrust: "global", boolPole: { strict: false, minTrust: "local" } },
             "filesystem.allowManagedReadPathsOnly": { direction: "tighten", minTrust: "global", boolPole: { strict: true, minTrust: "local" } },
-            "filesystem.denyWrite": { direction: "tighten", minTrust: "local" },
-            "filesystem.denyRead": { direction: "tighten", minTrust: "local" },
+            "filesystem.denyWrite": { direction: "tighten", minTrust: "local", list: true },
+            "filesystem.denyRead": { direction: "tighten", minTrust: "local", list: true },
         },
     },
     hooks: { mergeShape: "runAll", minTrust: "project", tighten: { rule: "none" }, enforcement: "gate", fail: "closed", seam: "hooks (single source or adapter-composed)" },
@@ -286,6 +463,16 @@ export function membersOf(category) {
     const spec = categorySpec(category);
     return (spec.members === undefined ? [] : Object.keys(spec.members));
 }
+/** A declared member's row — the two misuse arms (whole-key category, undeclared member) that admission and comparison share. */
+function memberRow(spec, member, categoryLabel) {
+    if (spec.members === undefined) {
+        throw new RangeError(`SAFETY_MERGE_SPEC: category '${categoryLabel}' has no member-level admission — its minTrust applies to the whole key`);
+    }
+    if (!Object.hasOwn(spec.members, member)) {
+        throw new RangeError(`SAFETY_MERGE_SPEC: unknown member '${member}' of category '${categoryLabel}' (members: ${Object.keys(spec.members).join(", ")})`);
+    }
+    return spec.members[member];
+}
 /**
  * Resolve one member's admission off a category spec VALUE (the single implementation; {@link memberAdmission}
  * binds it to {@link SAFETY_MERGE_SPEC}). Fallback law: a member row without `minTrust` inherits the category's.
@@ -298,13 +485,7 @@ export function membersOf(category) {
  * @param categoryLabel only decorates the error message (the spec value carries no name of its own).
  */
 export function resolveMemberAdmission(spec, member, categoryLabel = "(unnamed category)", value) {
-    if (spec.members === undefined) {
-        throw new RangeError(`SAFETY_MERGE_SPEC: category '${categoryLabel}' has no member-level admission — its minTrust applies to the whole key`);
-    }
-    if (!Object.hasOwn(spec.members, member)) {
-        throw new RangeError(`SAFETY_MERGE_SPEC: unknown member '${member}' of category '${categoryLabel}' (members: ${Object.keys(spec.members).join(", ")})`);
-    }
-    const row = spec.members[member];
+    const row = memberRow(spec, member, categoryLabel);
     const rowFloor = row.minTrust ?? spec.minTrust;
     if (row.boolPole !== undefined) {
         const floor = value === row.boolPole.strict ? row.boolPole.minTrust : rowFloor;
@@ -323,3 +504,38 @@ export function memberAdmission(category, member, value) {
 export function memberMinTrust(category, member, value) {
     return memberAdmission(category, member, value).minTrust;
 }
+/**
+ * Derive one member's comparator off a category spec VALUE (14.6.0; the single implementation — {@link memberTighten} binds
+ * it to {@link SAFETY_MERGE_SPEC}). The comparator follows from the row's VALUE CLASS and direction, never from the category's
+ * `tighten` (that answers only a `whole` unit's value — the file header):
+ *  · `boolPole` ⇒ `{ rule: "boolStricter", strict: boolPole.strict }`;
+ *  · `list` ⇒ `setUnion` for a `tighten` member (a superset narrows more), `setNarrower` for a `loosen` member (a subset grants less).
+ * A row declaring NEITHER value class or BOTH is a RangeError (nothing to derive / two readings) — never a default; so are the
+ * misuse arms {@link resolveMemberAdmission} has (a whole-key category, an undeclared member).
+ * @param categoryLabel only decorates the error message.
+ */
+export function resolveMemberTighten(spec, member, categoryLabel = "(unnamed category)") {
+    const row = memberRow(spec, member, categoryLabel);
+    const isList = row.list === true;
+    if ((row.boolPole !== undefined) === isList) {
+        const which = isList ? "both value classes (boolPole and list)" : "no value class (neither boolPole nor list)";
+        throw new RangeError(`SAFETY_MERGE_SPEC: member '${member}' of category '${categoryLabel}' declares ${which} — its comparator cannot be derived`);
+    }
+    if (row.boolPole !== undefined)
+        return { rule: "boolStricter", strict: row.boolPole.strict };
+    switch (row.direction) {
+        case "tighten":
+            return { rule: "setUnion" };
+        case "loosen":
+            return { rule: "setNarrower" };
+        default: {
+            const unknown = row.direction;
+            throw new RangeError(`SAFETY_MERGE_SPEC: member '${member}' of category '${categoryLabel}' has an unknown direction '${String(unknown)}'`);
+        }
+    }
+}
+/** A declared member's comparator from the published table (see {@link resolveMemberTighten}); compare two of its values with
+ *  {@link tightenVerdict}. Unknown category or member ⇒ RangeError (never the category rule as a fallback). */
+export function memberTighten(category, member) {
+    return resolveMemberTighten(categorySpec(category), member, category);
+}

package/dist/scheduler-store.js

@@ -1,14 +1,15 @@
+import { isPlainJsonObject } from './plain-json-object.js';
 import { isSessionLifetime } from './scheduler-lifetime.js';
 import { migrateSchedulerRecords } from './scheduler-store-migration.js';
 /** Structural validation of one record (required fields + a well-formed `when`). Unknown fields are allowed. */
 export function isSchedulerRecord(v) {
-    if (typeof v !== 'object' || v === null)
+    if (!isPlainJsonObject(v))
         return false;
     const r = v;
     if (typeof r.id !== 'string' || typeof r.scope !== 'string' || typeof r.prompt !== 'string' || typeof r.createdMs !== 'number')
         return false;
     const w = r.when;
-    if (typeof w !== 'object' || w === null)
+    if (!isPlainJsonObject(w))
         return false;
     if (w.kind === 'cron')
         return typeof w.expr === 'string';

package/dist/settings-units.d.ts

@@ -0,0 +1,85 @@
+import { type TightenRule } from "./safety-merge-spec.js";
+/** The settings-document units (see the file header). `path` is the unit's place in a settings document. */
+export declare const SETTINGS_UNITS: {
+    readonly permissions: {
+        readonly path: readonly ["permissions"];
+        readonly category: "permissions";
+        readonly reads: "members";
+    };
+    readonly permissionMode: {
+        readonly path: readonly ["permissions", "defaultMode"];
+        readonly category: "permissionMode";
+        readonly reads: "whole";
+        readonly reading: "permissionMode";
+    };
+    readonly additionalDirectories: {
+        readonly path: readonly ["permissions", "additionalDirectories"];
+        readonly category: "sandboxNetwork";
+        readonly reads: "whole";
+        readonly reading: "stringList";
+    };
+    readonly sandbox: {
+        readonly path: readonly ["sandbox"];
+        readonly category: "sandboxNetwork";
+        readonly reads: "members";
+    };
+    readonly disableBypassPermissionsMode: {
+        readonly path: readonly ["permissions", "disableBypassPermissionsMode"];
+        readonly category: "killSwitches";
+        readonly reads: "member";
+        readonly member: "disableBypassPermissionsMode";
+        readonly reading: "killSwitch";
+    };
+    readonly disableAutoMode: {
+        readonly path: readonly ["permissions", "disableAutoMode"];
+        readonly category: "killSwitches";
+        readonly reads: "member";
+        readonly member: "disableAutoMode";
+        readonly reading: "killSwitch";
+    };
+    readonly hooks: {
+        readonly path: readonly ["hooks"];
+        readonly category: "hooks";
+        readonly reads: "whole";
+        readonly reading: "hooks";
+    };
+    readonly env: {
+        readonly path: readonly ["env"];
+        readonly category: "env";
+        readonly reads: "whole";
+        readonly reading: "envMap";
+    };
+    readonly model: {
+        readonly path: readonly ["model"];
+        readonly category: "model";
+        readonly reads: "whole";
+        readonly reading: "nonEmptyString";
+    };
+    readonly outputStyle: {
+        readonly path: readonly ["outputStyle"];
+        readonly category: "ui";
+        readonly reads: "whole";
+        readonly reading: "nonEmptyString";
+    };
+};
+export type SettingsUnitName = keyof typeof SETTINGS_UNITS;
+/** The comparator of one unit — or, for a `members` unit, of one DECLARED member of it: `whole` ⇒ the category's `tighten`;
+ *  `member` ⇒ that member's comparator; `members` ⇒ the named member's comparator ({@link resolveMemberTighten}). Compare two values
+ *  with `tightenVerdict`. A `members` unit without a member (its whole value), an undeclared member (e.g. `sandbox`'s
+ *  `failIfUnavailable`), a `whole` unit given a member, a `member` unit given another one, an unknown unit ⇒ RangeError. */
+export declare function unitTighten(unit: SettingsUnitName, member?: string): TightenRule;
+/**
+ * Read one unit's raw value out of a settings document (14.6.0) — the settings half of "how an existing value is normalized
+ * before it is compared". The reading of every unit is the file header's table; anything outside it is `unreadable`, and
+ * `undefined` / `null` are `unreadable` for every unit. An accepted value is returned as is (same reference) — the only rewrites
+ * are `"manual"` ⇒ `"default"` (permissionMode) and `"disable"` ⇒ `true` (kill-switches); `"bypassPermissions"` is `launch_only`.
+ * The last step of every reading is the unit comparator's own domain: whatever reads, compares (file header).
+ * Addressing is {@link unitTighten}'s (same RangeErrors: a `members` unit needs a declared member, …).
+ */
+export declare function readSettingsUnit(unit: SettingsUnitName, raw: unknown, member?: string): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: "unreadable" | "launch_only";
+};

package/dist/settings-units.js

@@ -0,0 +1,175 @@
+/**
+ * SETTINGS UNITS (14.6.0) — the settings-document unit table: which keys of a settings file carry a merge contract, where each
+ * sits in the document, which {@link SAFETY_MERGE_SPEC} category it maps into, and how its raw value READS. Every resolver of a
+ * settings file (the shell reads it for each of its sources; a profile loader is a second projection) reads THIS table instead of
+ * keeping a key→category map of its own for these ten units. Unit names are the shell's established ten; the two permission-mode
+ * kill-switches map to their own `killSwitches` member rows (the table has no managed-only floor for them).
+ *
+ * NOT in this table: the two http-hook allowlist keys (`allowedHttpHookUrls` / `httpHookAllowedEnvVars`). They carry a merge contract
+ * too (the `httpHookAllowlists` category of {@link SAFETY_MERGE_SPEC}) but are keyed and read by `./http-hook-allowlists` on its own
+ * (`HTTP_HOOK_ALLOWLIST_KEYS`, `readHttpHookAllowlistLayer`), and read a malformed value differently: there it is `[]` plus a
+ * `malformed` mark (the failure direction is "no hook may run"), while a unit reading answers `unreadable`. Folding the two tables
+ * into one is a design question (which reading is right), not a drive-by — until it is settled a consumer that wants the allowlist
+ * layers reads that module, not this table.
+ *
+ * How a unit is addressed (`reads`):
+ *  · `whole`   — the unit's value is one value under its category: compared by the category's `tighten`
+ *                (the only thing a category's `tighten` answers — safety-merge-spec header);
+ *  · `member`  — the unit IS one declared member of its category (the two kill-switches): compared by that member's comparator;
+ *  · `members` — the unit is an object of declared members (`permissions`, `sandbox`): every question names ONE declared member,
+ *                compared and read by that member's row ({@link memberTighten}; its value class `boolPole` / `list`). The unit's whole
+ *                value and its undeclared members have no comparator and no reading here — asking is a RangeError.
+ *
+ * How a unit READS (`reading`, on every `whole` / `member` row; a `members` unit reads each member by the member row's value class):
+ *  · `stringList`     — an array whose every element is a non-empty string (`[]` reads); a bare string is NOT wrapped into an array;
+ *  · `permissionMode` — a word of the `permissionMode` category's order other than `bypassPermissions`; `"manual"` reads as
+ *                       `"default"` (the alias); `"bypassPermissions"` is `launch_only` — a launch flag, never a settings-file value;
+ *  · `killSwitch`     — a boolean; `"disable"` (CC's spelling of ON) reads as `true`; `false` is the loose pole — a value, not absence;
+ *  · `hooks`          — what the one hooks judge (`classifyHooksConfig`) classifies as `loaded`;
+ *  · `envMap`         — a plain object whose keys are non-empty and whose values are all strings;
+ *  · `nonEmptyString` — a non-empty string;
+ *  and a member's value class: `boolPole` ⇒ a boolean, `list` ⇒ the `stringList` reading.
+ * Everything else is `unreadable` — no default arm. Two laws for every unit: `undefined` and JSON `null` are `unreadable` (absence
+ * is not a value; "an absent landing spot takes the write" is the loader's business, before it calls the reader), and the reader
+ * only recognizes a shape, never rewrites it — an accepted value comes back as the same reference; the only rewrites are the two
+ * spellings above (`"manual"` ⇒ `"default"`, `"disable"` ⇒ `true`).
+ * WHATEVER READS, COMPARES: a reading has two halves — its shape / spelling half (the table above) and, as its last step, the
+ * unit comparator's OWN domain (`tightenVerdict(unitTighten(unit, member), value, value)` must be `equal`). The domain has one
+ * owner, the comparator; a reading only adds what it needs on top (non-empty list elements, the hooks judge, …). So a value the
+ * shape half accepts but the comparator cannot place — a hooks document the hooks judge loads while a key it strips hides data
+ * nested deeper than `MAX_HASH_DEPTH`, or an `undefined` — is `unreadable`, never "read but not comparable".
+ * The env DOCUMENT's literal grammar (boolean words, csv + empty-set sentinel, a "≤ 0 means off" cap) is not here: it belongs to
+ * the engine's env catalog, whose one implementation is the server's.
+ */
+import { classifyHooksConfig } from "./hooks-config.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
+import { SAFETY_MERGE_SPEC, resolveMemberTighten, tightenVerdict } from "./safety-merge-spec.js";
+/** The settings-document units (see the file header). `path` is the unit's place in a settings document. */
+export const SETTINGS_UNITS = {
+    permissions: { path: ["permissions"], category: "permissions", reads: "members" },
+    permissionMode: { path: ["permissions", "defaultMode"], category: "permissionMode", reads: "whole", reading: "permissionMode" },
+    additionalDirectories: { path: ["permissions", "additionalDirectories"], category: "sandboxNetwork", reads: "whole", reading: "stringList" },
+    sandbox: { path: ["sandbox"], category: "sandboxNetwork", reads: "members" },
+    disableBypassPermissionsMode: { path: ["permissions", "disableBypassPermissionsMode"], category: "killSwitches", reads: "member", member: "disableBypassPermissionsMode", reading: "killSwitch" },
+    disableAutoMode: { path: ["permissions", "disableAutoMode"], category: "killSwitches", reads: "member", member: "disableAutoMode", reading: "killSwitch" },
+    hooks: { path: ["hooks"], category: "hooks", reads: "whole", reading: "hooks" },
+    env: { path: ["env"], category: "env", reads: "whole", reading: "envMap" },
+    model: { path: ["model"], category: "model", reads: "whole", reading: "nonEmptyString" },
+    outputStyle: { path: ["outputStyle"], category: "ui", reads: "whole", reading: "nonEmptyString" },
+};
+/** The one place a unit + optional member resolves to what is being asked about — the row and its comparator. Fail-closed
+ *  and loud on every misaddressing: an unknown unit (own-property lookup — `"__proto__"` is unknown, not Object.prototype),
+ *  a `members` unit without a member, a `whole` unit with one, a `member` unit given another one, an undeclared member
+ *  (refused by the member row lookup in {@link resolveMemberTighten}). */
+function unitTarget(unit, member) {
+    if (!Object.hasOwn(SETTINGS_UNITS, unit)) {
+        throw new RangeError(`SETTINGS_UNITS: unknown unit '${unit}' (units: ${Object.keys(SETTINGS_UNITS).join(", ")})`);
+    }
+    const row = SETTINGS_UNITS[unit];
+    const spec = SAFETY_MERGE_SPEC[row.category];
+    switch (row.reads) {
+        case "whole":
+            if (member !== undefined)
+                throw new RangeError(`SETTINGS_UNITS: unit '${unit}' is read whole — it has no member '${member}'`);
+            return { row, rule: spec.tighten };
+        case "member":
+            if (member !== undefined)
+                throw new RangeError(`SETTINGS_UNITS: unit '${unit}' already names its member ('${row.member}' of '${row.category}') — pass no member`);
+            return { row, rule: resolveMemberTighten(spec, row.member, row.category) };
+        case "members":
+            if (member === undefined) {
+                throw new RangeError(`SETTINGS_UNITS: unit '${unit}' is read per declared member of '${row.category}' (members: ${Object.keys(spec.members ?? {}).join(", ")}) — its whole value and its undeclared members have no comparator`);
+            }
+            return { row, rule: resolveMemberTighten(spec, member, row.category) };
+        default: {
+            const unknown = row;
+            throw new RangeError(`SETTINGS_UNITS: unit '${unit}' has an unknown addressing '${String(unknown.reads)}'`);
+        }
+    }
+}
+/** The comparator of one unit — or, for a `members` unit, of one DECLARED member of it: `whole` ⇒ the category's `tighten`;
+ *  `member` ⇒ that member's comparator; `members` ⇒ the named member's comparator ({@link resolveMemberTighten}). Compare two values
+ *  with `tightenVerdict`. A `members` unit without a member (its whole value), an undeclared member (e.g. `sandbox`'s
+ *  `failIfUnavailable`), a `whole` unit given a member, a `member` unit given another one, an unknown unit ⇒ RangeError. */
+export function unitTighten(unit, member) {
+    return unitTarget(unit, member).rule;
+}
+const UNREADABLE = { ok: false, reason: "unreadable" };
+const LAUNCH_ONLY = { ok: false, reason: "launch_only" };
+/** `stringList`: an array whose every element is a non-empty string (a hole reads as `undefined`, so a sparse array is not one). */
+function isNonEmptyStringList(v) {
+    if (!Array.isArray(v))
+        return false;
+    for (let i = 0; i < v.length; i++) {
+        const x = v[i];
+        if (typeof x !== "string" || x.length === 0)
+            return false;
+    }
+    return true;
+}
+/** `envMap`: a plain object (prototype `Object.prototype` or `null`), non-empty keys, string values. */
+function isEnvMap(v) {
+    if (!isPlainJsonObject(v))
+        return false;
+    return Object.keys(v).every((k) => k.length > 0 && typeof v[k] === "string");
+}
+/** What a declared member's value class adds on top of its comparator's domain — read through the comparator
+ *  {@link resolveMemberTighten} derived from the row, so the seat is interpreted in one place: `list` ⇒ setUnion / setNarrower,
+ *  whose domain takes any strings, so the `stringList` reading adds "every element non-empty"; `boolPole` ⇒ boolStricter, whose
+ *  domain IS the boolean — nothing to add. A member comparator is only ever one of those three. */
+function memberShapeReads(unit, rule, value) {
+    switch (rule.rule) {
+        case "boolStricter":
+            return true;
+        case "setUnion":
+        case "setNarrower":
+            return isNonEmptyStringList(value);
+        default:
+            throw new RangeError(`SETTINGS_UNITS: unit '${unit}' resolved to the comparator '${rule.rule}', which no member value class derives`);
+    }
+}
+/** A reading's shape / spelling half (the file header's table): the value the raw input reads as, or a refusal. The domain half
+ *  is the unit comparator's, applied by {@link readSettingsUnit} after this. */
+function shapedReading(unit, row, rule, raw) {
+    if (row.reads === "members")
+        return memberShapeReads(unit, rule, raw) ? { ok: true, value: raw } : UNREADABLE;
+    switch (row.reading) {
+        case "stringList":
+            return isNonEmptyStringList(raw) ? { ok: true, value: raw } : UNREADABLE;
+        case "permissionMode":
+            // the words are the category's order (the comparator's enumRank domain); the reading owns the two spellings around it
+            if (raw === "bypassPermissions")
+                return LAUNCH_ONLY;
+            return { ok: true, value: raw === "manual" ? "default" : raw };
+        case "killSwitch":
+            // CC spells ON "disable"; the boolean itself is the member comparator's domain
+            return { ok: true, value: raw === "disable" ? true : raw };
+        case "hooks":
+            return classifyHooksConfig({ hooks: raw }).outcome === "loaded" ? { ok: true, value: raw } : UNREADABLE;
+        case "envMap":
+            return isEnvMap(raw) ? { ok: true, value: raw } : UNREADABLE;
+        case "nonEmptyString":
+            return typeof raw === "string" && raw.length > 0 ? { ok: true, value: raw } : UNREADABLE;
+        default: {
+            const unknown = row.reading;
+            throw new RangeError(`SETTINGS_UNITS: unit '${unit}' has an unknown reading '${String(unknown)}'`);
+        }
+    }
+}
+/**
+ * Read one unit's raw value out of a settings document (14.6.0) — the settings half of "how an existing value is normalized
+ * before it is compared". The reading of every unit is the file header's table; anything outside it is `unreadable`, and
+ * `undefined` / `null` are `unreadable` for every unit. An accepted value is returned as is (same reference) — the only rewrites
+ * are `"manual"` ⇒ `"default"` (permissionMode) and `"disable"` ⇒ `true` (kill-switches); `"bypassPermissions"` is `launch_only`.
+ * The last step of every reading is the unit comparator's own domain: whatever reads, compares (file header).
+ * Addressing is {@link unitTighten}'s (same RangeErrors: a `members` unit needs a declared member, …).
+ */
+export function readSettingsUnit(unit, raw, member) {
+    const t = unitTarget(unit, member);
+    if (raw === undefined || raw === null)
+        return UNREADABLE;
+    const shaped = shapedReading(unit, t.row, t.rule, raw);
+    if (!shaped.ok)
+        return shaped;
+    return tightenVerdict(t.rule, shaped.value, shaped.value) === "equal" ? shaped : UNREADABLE;
+}

package/dist/types.d.ts

@@ -57,6 +57,10 @@ export declare function urlQueryFragmentHasSecret(u: URL): boolean;
  *  echoed; a fragment's also names its migration, {@link nonSecretUrlIssue}); `params` carries the sentence (`template` / `operands`,
  *  no operands) and `flaw`, the rule word.
  *
+ *  Scope of the secret test: it judges the VALUE's shape (a value that looks like a secret, whatever the parameter is called) — the sibling
+ *  name-shaped judge `findUrlCredential` (`./url-credential`) asks the other question (a parameter whose NAME is on the credential-name table,
+ *  whatever the value looks like). Neither contains the other: `?key=abc` passes here and is a hit there; `?x=sk-live-…` is the reverse.
+ *
  *  This is the seat of every URL in a STORED document the one-time migration rewrites: the domain documents (models `baseUrl`, mcp `url`,
  *  `sessionMirror.engineUrl`, workers `gitApiBaseUrl`) and `config.d/remote-exec.json` (k8s `apiUrl`, `s3Snapshot.endpoint`). A URL
  *  that is not stored data — the web-admin credential envelope's `issuer`, a wire input — uses {@link NON_SECRET_URL_NO_MIGRATION}.