@sema-agent/settings-schema 14.5.0 → 14.6.0

package/dist/safety-merge-spec.d.ts

@@ -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`
@@ -53,8 +67,8 @@
 import { z } from "zod";
 /** How values from different layers/principals combine for a category. */
 export declare const MergeShape: z.ZodEnum<{
-    concat: "concat";
     replace: "replace";
+    concat: "concat";
     denyFirst: "denyFirst";
     runAll: "runAll";
     overrideByName: "overrideByName";
@@ -121,7 +135,14 @@ export type MemberDirection = z.infer<typeof MemberDirection>;
  *  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 declare const MemberAdmission: z.ZodObject<{
     direction: z.ZodEnum<{
         loosen: "loosen";
@@ -146,6 +167,7 @@ export declare const MemberAdmission: z.ZodObject<{
             task: "task";
         }>;
     }, z.core.$strip>>;
+    list: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 export type MemberAdmission = z.infer<typeof MemberAdmission>;
 /** The RESOLVED admission a consumer branches on — the category fallback already applied, so `minTrust` is never
@@ -180,7 +202,12 @@ export type FailMode = z.infer<typeof FailMode>;
  *  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 declare const TightenRule: z.ZodDiscriminatedUnion<[z.ZodObject<{
     rule: z.ZodLiteral<"none">;
 }, z.core.$strip>, z.ZodObject<{
@@ -193,12 +220,43 @@ export declare const TightenRule: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     rule: z.ZodLiteral<"enumRank">;
     order: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    rule: z.ZodLiteral<"setUnion">;
+}, z.core.$strip>, z.ZodObject<{
+    rule: z.ZodLiteral<"numericLower">;
 }, z.core.$strip>], "rule">;
 export type TightenRule = z.infer<typeof TightenRule>;
+/** 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 declare const TIGHTEN_VERDICTS: readonly ["equal", "stricter", "looser", "unordered", "unreadable"];
+export type TightenVerdict = (typeof TIGHTEN_VERDICTS)[number];
+/**
+ * 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 declare function tightenVerdict(rule: TightenRule, existing: unknown, candidate: unknown): TightenVerdict;
 export declare const MergeCategorySpec: z.ZodObject<{
     mergeShape: z.ZodEnum<{
-        concat: "concat";
         replace: "replace";
+        concat: "concat";
         denyFirst: "denyFirst";
         runAll: "runAll";
         overrideByName: "overrideByName";
@@ -223,6 +281,10 @@ export declare const MergeCategorySpec: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         rule: z.ZodLiteral<"enumRank">;
         order: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        rule: z.ZodLiteral<"setUnion">;
+    }, z.core.$strip>, z.ZodObject<{
+        rule: z.ZodLiteral<"numericLower">;
     }, z.core.$strip>], "rule">;
     enforcement: z.ZodEnum<{
         gate: "gate";
@@ -268,6 +330,7 @@ export declare const MergeCategorySpec: z.ZodObject<{
                 task: "task";
             }>;
         }, z.core.$strip>>;
+        list: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type MergeCategorySpec = z.infer<typeof MergeCategorySpec>;
@@ -288,14 +351,17 @@ export declare const SAFETY_MERGE_SPEC: {
             readonly allow: {
                 readonly direction: "loosen";
                 readonly minTrust: "global";
+                readonly list: true;
             };
             readonly deny: {
                 readonly direction: "tighten";
                 readonly minTrust: "local";
+                readonly list: true;
             };
             readonly ask: {
                 readonly direction: "tighten";
                 readonly minTrust: "local";
+                readonly list: true;
             };
         };
     };
@@ -429,10 +495,12 @@ export declare const SAFETY_MERGE_SPEC: {
             readonly "filesystem.denyWrite": {
                 readonly direction: "tighten";
                 readonly minTrust: "local";
+                readonly list: true;
             };
             readonly "filesystem.denyRead": {
                 readonly direction: "tighten";
                 readonly minTrust: "local";
+                readonly list: true;
             };
         };
     };
@@ -608,3 +676,17 @@ export declare function memberAdmission<C extends SafetyMergeCategory>(category:
 /** A member's admission FLOOR from the published table — the word a resolver compares the layer's trust against
  *  (`isAtLeast(layer, floor)` ⇒ admitted; the ladder is {@link trustRank}). Convenience over {@link memberAdmission}. */
 export declare function memberMinTrust<C extends SafetyMergeCategory>(category: C, member: SafetyMergeMember<C>, value?: unknown): 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 declare function resolveMemberTighten(spec: MergeCategorySpec, member: string, categoryLabel?: string): TightenRule;
+/** 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 declare function memberTighten<C extends SafetyMergeCategory>(category: C, member: SafetyMergeMember<C>): TightenRule;

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";
+};