@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/permission-rule-org.d.ts

@@ -34,8 +34,30 @@
  * refused and disclosed — identity comparison alone cannot catch it, and an in-memory-only mark would
  * accept revision N−1 after a restart. Signature / predecessor chaining belongs to the privilege-
  * separation ticket; the high-water mark is the floor that needs no key distribution.
+ *
+ * ## One reading of a row
+ *
+ * A snapshot is installed and served on its ENVELOPE ({@link validateOrgSnapshot}: revision, observation
+ * time, a rules list) and the anti-rollback fence; what its rows say never decides which snapshot is in
+ * force. Whether the rules are a list is judged in ONE place ({@link listRefusalOf}) for the partition and for
+ * every store that hands a resolution over — rules that are not a list, or that carry more places than a rule set may
+ * (the same cap the rule compiler holds a set to), are governance nobody can read (the
+ * partition refuses the snapshot; the org lane answers unavailable), never a policy of zero rows — and ONE reader
+ * ({@link orgRuleListOf}) copies the whole list in one receipt: a member of a row that cannot be read is left out of
+ * that row's copy alone, and every row is judged on its copy. A snapshot the partition holds — fetched or read back
+ * from its persistence — is that same copy ({@link orgSnapshotCopyOf}). Every row is then read by ONE reader
+ * ({@link readOrgRules}), the same for every store that hands a resolution over, on its policy members
+ * ({@link ORG_ROW_POLICY_MEMBERS}): a row is READ when its behavior is `deny` or `ask` and its text is a shell command
+ * rule under that behavior. Any other row — another grammar's rule, a shell rule the validator refuses, a row
+ * with no text, a behavior this layer has no bucket for — is UNREADABLE, and stands at its strictest
+ * reading over the calls it may reach ({@link OrgRowReach}): an `ask` row asks a person, every other row
+ * refuses. Readable deny and ask rows hold as published beside it. One unreadable row therefore never
+ * takes the rest of the policy down with it, and never turns a published deny into a question; the
+ * snapshot is served DEGRADED, and every resolution and every adjudication over it names the unreadable
+ * rows ({@link describeUnreadableOrgRows}).
  */
-import { type PersistedRule, type RuleRejectCode } from "./permission-rule-model.js";
+import { type ParsedRule, type PersistedRule, type RuleRejectCode } from "./permission-rule-model.js";
+import type { DenyFace } from "../tools/fs/read-deny.js";
 import type { PermissionRuleStore } from "./permission-rule-provider.js";
 /** One org rule. There is structurally no allow bucket (design/179 §9: the org layer only tightens). */
 export interface OrgPermissionRule {
@@ -171,42 +193,146 @@ export declare const UNGOVERNED_ORG_RESOLUTION: Readonly<OrgRuleResolution>;
  *    bound is refused loudly, never coerced.
  */
 export declare function createOrgRulePartition(cfg: OrgRulePartitionConfig): OrgRulePartition;
+/** Whether two snapshots carry the same POLICY: row for row, the same policy members ({@link ORG_ROW_POLICY_MEMBERS}) — never
+ *  observation metadata, never a member no judgment reads (which a copy may carry or leave out). The ONE test of "the same
+ *  revision, the same content": the partition's equal-revision guard asks it of two snapshots it holds in one form
+ *  ({@link orgSnapshotCopyOf}), and a persistence backend asks it of what it stores. */
+export declare function sameOrgPolicyContent(a: OrgRuleSnapshot, b: OrgRuleSnapshot): boolean;
 /**
- * Which entries of an org snapshot the CURRENT rule validator refuses — the published deny/ask rules
- * that can match nothing on this build. Empty ⟺ every rule is enforceable.
+ * Which calls an UNREADABLE row may reach — the calls its strictest reading stands over.
  *
- * Separate from {@link validateOrgSnapshot} because BOTH gates need it: the install gate (a fetched
- * snapshot) and the serving gate (backlog #177 — a snapshot persisted by an earlier build is read back
- * and served without ever having met this validator). It reports every offender rather than the first,
- * since a refusal an administrator cannot act on names no line to fix.
+ * `"every"` when the row names no tool this layer can place: no rule text, a head the rule syntax cannot read, the lone
+ * `*`, or a tool with no rule grammar (a misspelled tool name and a tool this build does not know look the same, and
+ * both may be the shell). Otherwise the rule WORD it names — a shell tool's head is the command word, as a call's is —
+ * and, for a tool whose path rules speak for a face ({@link PATH_RULE_FACES}), the faces of the column its strictest
+ * behavior reads: such a row reaches what a readable rule of its tool could reach, and nothing else.
+ */
+export type OrgRowReach = "every" | {
+    readonly words: readonly string[];
+    readonly faces: readonly DenyFace[];
+};
+/**
+ * A row the layer cannot read: its text (as published; the rendering of the scalar its `rule` holds when that is not a string;
+ * `<unreadable>` when it holds none — a structure is no value, {@link orgRowPolicyOf}), its 1-based place in the
+ * snapshot, why (`code`, and `detail` for a row whose shape — not its text — is at fault), the behavior it stands at, and
+ * the calls it reaches. `behavior` is the row's STRICTEST reading: `ask` only when the row says `ask`, `deny` for a row
+ * that says `deny` and for one whose behavior cannot be read.
+ */
+export interface UnreadableOrgRow {
+    readonly kind: "unreadable";
+    readonly index: number;
+    readonly rule: string;
+    readonly code: RuleRejectCode;
+    readonly detail?: string;
+    readonly behavior: "deny" | "ask";
+    readonly reach: OrgRowReach;
+}
+/** A row the layer reads: a shell command rule under the behavior it publishes. */
+export interface ReadOrgRow {
+    readonly kind: "read";
+    readonly index: number;
+    readonly rule: string;
+    readonly behavior: "deny" | "ask";
+    readonly parsed: ParsedRule;
+}
+/** One call as the org layer judges it: the rule words it answers to (`laneToolNamesOf`; one word is enough), its shell
+ *  command when it is the shell tool's, and the face of its path target when it has one (`callPathFaceOf`). */
+export interface OrgRuleCall {
+    readonly tool: string | readonly string[];
+    readonly command?: string;
+    readonly face?: DenyFace;
+}
+/** Every row of a snapshot read once, and the one judgment of a call against them. */
+export interface OrgRulesReading {
+    readonly rows: readonly (ReadOrgRow | UnreadableOrgRow)[];
+    readonly unreadable: readonly UnreadableOrgRow[];
+    verdictFor(call: OrgRuleCall): OrgRuleVerdict | undefined;
+}
+/**
+ * The members of an org row the layer reads to judge a call — the row's POLICY. A row IS these members: every reader holds and
+ * judges a row as its policy ({@link orgRowPolicyOf}), and two rows with the same policy members are the same policy
+ * ({@link sameOrgPolicyContent}). Any other member a row carries is never judged, held, served or persisted (the receipt reads
+ * each of a row's own members once — a getter on one runs once — and copies none of what it holds beyond a scalar).
+ */
+export declare const ORG_ROW_POLICY_MEMBERS: readonly ["rule", "behavior"];
+/** A JSON scalar — the only value a member the partition keeps holds as data. */
+type Scalar = string | number | boolean | null;
+type ScalarMembers<K extends string> = {
+    [P in K]?: Scalar;
+};
+type OrgRowPolicy = Readonly<ScalarMembers<(typeof ORG_ROW_POLICY_MEMBERS)[number]>>;
+/**
+ * The envelope's rules LIST, read once: `refused` when it is not a list of at most the cap's places ({@link listRefusalOf} —
+ * judged before the list is received, so an oversized or sparse list builds no row) or cannot be received at all;
+ * otherwise its rows, each as its policy ({@link orgRowPolicyOf}) — the list received whole in one receipt
+ * ({@link ORG_RULES_RECEIPT}), so a row's member that cannot be read is that row's alone, a row that cannot be read at all (and
+ * a hole) is a row with nothing in it (`{}`: no rule text, read at its strictest reading) and the rows beside it are untouched.
+ * The ONE reader of the list — the partition holds a snapshot's rows as these, fetched and read back alike
+ * ({@link orgSnapshotCopyOf}), and every reading of rows ({@link readOrgRules}) reads them through it — so no store's rows can be
+ * read two ways, and no row can take the reading of another down with it.
+ */
+export declare function orgRuleListOf(rules: unknown): {
+    readonly rows: readonly OrgRowPolicy[];
+} | {
+    readonly refused: string;
+};
+/**
+ * The ONE reading of an org snapshot's rows: each row read once ({@link readOrgRow}), and the one judgment of a call
+ * against them. Every reader of org rows goes through it — the partition's degraded line, the lane's adjudication,
+ * {@link orgRuleVerdictFor}, {@link unenforceableOrgRules} and the shadow view — so no two of them can read one row two ways.
+ *
+ * A call meets the rows in three answers. DENY: a readable deny reaches one of its program runs, or an unreadable row
+ * standing at deny reaches the call — the first such row in snapshot order speaks. ASK: a readable rule the call cannot be
+ * READ against (the lexer's reason — a rule that cannot be judged may be a deny, so it outranks a reached ask), else a
+ * readable ask reaching it or an unreadable row standing at ask reaching it, the first in snapshot order. Otherwise none.
+ * An unreadable row's verdict carries its reason ({@link unreadableOrgRowReason}) beside its text.
+ *
+ * The rows are read off the one list reader's copy ({@link orgRuleListOf}): rules that are not a list come back `refused` —
+ * the org's rules cannot be read, which is never a policy of zero rows — and a row is judged on what its copy holds: a policy
+ * member that could not be read is one the row does not have (no `rule` ⇒ no rule text, every call; no `behavior` ⇒ its
+ * strictest reading over the calls of the tool it names), read like any other unreadable row while the rows beside it keep
+ * their effect.
+ */
+export declare function readOrgRules(rules: unknown): OrgRulesReading | {
+    readonly refused: string;
+};
+/**
+ * Which rows of an org snapshot this layer cannot read, each with its code — the rows that stand at their strictest
+ * reading instead of as published. Empty ⟺ every row is read. Every unreadable row is reported, a row with no rule text
+ * or a behavior other than deny / ask included (its text rendered when it is not a string). Rules that are not a list, or a
+ * list past the cap, throw the one list judgment's sentence ({@link readListedOrgRules}) — never a reading of fewer rows.
  */
 export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[]): Array<{
     rule: string;
     code: RuleRejectCode;
 }>;
+/** The reason an unreadable row's verdict carries — its place in the snapshot, its code, and the repair. */
+export declare function unreadableOrgRowReason(row: Pick<UnreadableOrgRow, "index" | "code" | "detail">): string;
+/** The ONE clause for an org verdict that carries an `unreadable` reason — a rule the call could not be read against, or
+ *  a row this layer cannot read — on a refusal and on a question alike. */
+export declare function orgUnreadableClause(reason: string): string;
 /**
- * design/182 §7.2 — which org rule speaks for this command, if any. Deny outranks ask; within a
- * behavior the first textual match wins (reporting order only — all denies are the same one answer).
- * Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use
- * ({@link programRunReachOf}: an interpreter-headed prefix deny like `Bash(node:*)` is a
- * legitimately wide tightening and matches; a segment hit is a hit; a call the lexer cannot read
- * against a rule is an ASK with the reason — fail closed, never silence).
- *
- * The skip below is a defensive floor, and what stands behind it is worth stating precisely: rules that
- * arrive from the org partition's `resolve` ({@link createOrgRulePartition}) have passed {@link validateOrgSnapshot} on BOTH the install
- * and the serving path (backlog #177), so an unenforceable entry cannot reach here through the overlay
- * — the whole snapshot is refused, or the resolution reports `unavailable`, and either way it is
- * disclosed. A caller that hands this function a snapshot it obtained ELSEWHERE gets no such guarantee:
- * the skip is silent, and naming the dead entries is that caller's job — {@link unenforceableOrgRules}
- * is the shared way to do it.
+ * The ONE line naming a snapshot's unreadable rows (count, the first {@link DISCLOSED_UNREADABLE_ROWS} by place, text and
+ * code, the rest summarized), or `undefined` when every row is read. The partition puts it on every resolution that
+ * serves such a snapshot, and the org lane hands it to its operator sink on every adjudication over one, so the two seats
+ * describe one snapshot in one sentence. Each text is escaped — the characters that most often make a row unreadable are
+ * exactly the ones that do not render.
  */
-export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: {
-    tool: string;
-    command: string;
-}): OrgRuleVerdict | undefined;
-/** The org layer's answer for one call: which rule spoke, with what behavior — and, when the call could
- *  not be READ against the org's rules, the lexer's reason beside the first rule it could not judge
- *  (`behavior` is then `ask`: the org published a rule that may reach this call, and nobody can say). */
+export declare function describeUnreadableOrgRows(unreadable: readonly UnreadableOrgRow[], revision?: unknown): string | undefined;
+/**
+ * design/182 §7.2 — which org rule speaks for this call, if any: {@link readOrgRules}'s judgment, over a snapshot read for
+ * this call alone. Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use
+ * ({@link programRunReachOf}: an interpreter-headed prefix deny like `Bash(node:*)` is a legitimately wide tightening and
+ * matches; a segment hit is a hit; a call the lexer cannot read against a rule is an ASK with the reason — fail closed,
+ * never silence), and a row this layer cannot read stands at its strictest reading over the calls it may reach. A caller
+ * judging many calls against one snapshot reads it once with {@link readOrgRules} instead. Rules that are not a list, or a
+ * list past the cap, throw the one list judgment's sentence ({@link readListedOrgRules}) — never a verdict over fewer rows.
+ */
+export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: OrgRuleCall): OrgRuleVerdict | undefined;
+/** The org layer's answer for one call: which rule spoke, with what behavior — and, when the rule could not be judged
+ *  against the call, why (`unreadable`): either the call could not be READ against it (the lexer's reason; `behavior` is
+ *  then `ask` — the org published a rule that may reach this call, and nobody can say), or the row is not one this layer
+ *  reads ({@link unreadableOrgRowReason}; `behavior` is the row's strictest reading). */
 export interface OrgRuleVerdict {
     readonly behavior: "deny" | "ask";
     readonly rule: string;
@@ -234,14 +360,18 @@ export interface OrgRuleVerdict {
  * either way. org ASK rules do not shadow: the personal lane never consumes a `requiresRealApproval`
  * ask, so the two never actually meet on one call.
  *
- * design/382 §2.6 — a Read directory rule is never org-shadowed in this version: the org layer has no
- * Read grammar (a snapshot carrying one refuses whole at the validator), so there is no deny that could
- * reach it, and its `command` is a PATH that must not be fed to the shell lane's segment reader as
- * though it were a command line.
+ * An UNREADABLE row standing at deny refuses every call it reaches ({@link readOrgRules}), so it shadows every personal
+ * rule of a tool it reaches — by the rule word, or by the face that tool's calls are on — exactly as the gate refuses
+ * those calls; one standing at ask does not shadow, as a readable ask does not.
+ *
+ * design/382 §2.6 — no READABLE org row reaches a Read directory rule in this version: the org layer has no Read
+ * grammar, and the rule's `command` is a PATH that must not be fed to the shell lane's segment reader as though it
+ * were a command line.
  */
 export declare function orgRuleShadows(orgRules: readonly OrgPermissionRule[], rule: Pick<PersistedRule, "tool" | "command">): boolean;
-/** The shadow predicate with the org denies parsed ONCE — what a read over many rows uses. */
+/** The shadow predicate with the org rows read ONCE — what a read over many rows uses. */
 export declare function compileOrgShadowPredicate(orgRules: readonly OrgPermissionRule[]): (rule: Pick<PersistedRule, "tool" | "command">) => boolean;
 /** Does this store carry a write face? Re-exported convenience for org-ticket integrations that need to
  *  distinguish a read-only projection from a writable personal bucket without importing the writer seam. */
 export declare function isWritablePermissionRuleStore(store: PermissionRuleStore): boolean;
+export {};

package/dist/core/permission-rule-org.js

@@ -1,5 +1,11 @@
-import { escapeForDisclosure, parseRuleText, programRunReachOf, ruleReachesProgramRun } from "./permission-rule-model.js";
+import { COMMAND_RULE_TOOL, PATH_RULE_FACES, escapeForDisclosure, parseRuleText, programRunReachOf, ruleReachesProgramRun, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { isNameableToolName, ruleSpellingOf } from "./permission-rule-syntax.js";
+import { isShellFaceToolName, pathTargetOf } from "./tool-registry.js";
 import { writerOf } from "./permission-rule-store.js";
+import { canonicalize } from "./canonical-json.js";
+import { types } from "node:util";
+import { describeFault, receive } from "./mods/kernel/receive.js";
+import { DEFAULT_CAPS } from "./permission-rules.js";
 export const ORG_UNAVAILABLE_DECISION_REASON = "org_unavailable";
 export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
 export function settleOrgVerdictWithin(p, fallback, opts) {
@@ -48,7 +54,7 @@ export function createOrgRulePartition(cfg) {
     let memoryState;
     const readState = async () => {
         const state = cfg.persistence !== undefined ? await cfg.persistence.readOrgState() : memoryState;
-        return state === undefined ? undefined : structuredClone(state);
+        return state === undefined ? undefined : orgStateCopyOf(state);
     };
     const writeState = async (state) => {
         if (cfg.persistence !== undefined)
@@ -75,7 +81,7 @@ export function createOrgRulePartition(cfg) {
                 throw new Error(`the org snapshot source did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms`);
             if ("e" in settled)
                 throw settled.e;
-            fetched = structuredClone(settled.v);
+            fetched = orgSnapshotCopyOf(settled.v);
         }
         catch (err) {
             fetchFailed = true;
@@ -152,6 +158,9 @@ export function createOrgRulePartition(cfg) {
                     if (!freshlyInstalled && !fetchFailed && fetched === undefined) {
                         disclosures.push("org snapshot source returned no snapshot — continuing on the last-known-good");
                     }
+                    const degraded = describeUnreadableOrgRows(readListedOrgRules(installed.snapshot.rules).unreadable, installed.snapshot.revision);
+                    if (degraded !== undefined)
+                        disclosures.push(degraded);
                     return {
                         source: "org",
                         status: freshlyInstalled ? "fresh" : "last-known-good",
@@ -188,34 +197,187 @@ function persistedMarkIsCoherent(state) {
         Number.isFinite(state.snapshot.revision) &&
         state.revisionHighWater >= state.snapshot.revision);
 }
-function sameOrgPolicyContent(a, b) {
+export function sameOrgPolicyContent(a, b) {
     if (a.rules.length !== b.rules.length)
         return false;
-    return a.rules.every((r, i) => b.rules[i]?.rule === r.rule && b.rules[i]?.behavior === r.behavior);
+    const policy = (r) => canonicalize(orgRowPolicyOf(r));
+    return a.rules.every((r, i) => policy(b.rules[i]) === policy(r));
 }
-const DISCLOSED_UNENFORCEABLE_RULES = 20;
-export function unenforceableOrgRules(rules) {
-    const out = [];
-    for (const r of rules) {
-        if (typeof r?.rule !== "string" || r.rule === "")
-            continue;
-        const parsed = parseRuleText(r.rule, r.behavior);
-        if ("reject" in parsed) {
-            out.push({ rule: r.rule, code: parsed.reject.code });
-            continue;
-        }
-        if (parsed.rule.tool !== "Bash")
-            out.push({ rule: r.rule, code: "unsupported.tool" });
+const DISCLOSED_UNREADABLE_ROWS = 20;
+function reachOfRowHead(text, behavior) {
+    const head = typeof text === "string" ? ruleSpellingOf(text)?.toolName : undefined;
+    if (head === undefined || !isNameableToolName(head))
+        return "every";
+    if (head === COMMAND_RULE_TOOL || isShellFaceToolName(head))
+        return { words: [COMMAND_RULE_TOOL], faces: [] };
+    if (ruleToolGrammarOf(head) === undefined)
+        return "every";
+    const column = Object.hasOwn(PATH_RULE_FACES, head) ? PATH_RULE_FACES[head]?.[behavior] : undefined;
+    return { words: [head], faces: column ?? [] };
+}
+function rowReaches(reach, words, face) {
+    if (reach === "every")
+        return true;
+    return reach.words.some((w) => words.includes(w)) || (face !== undefined && reach.faces.includes(face));
+}
+function listRefusalOf(rules) {
+    if (typeof rules === "object" && rules !== null) {
+        if (types.isProxy(rules))
+            return "rules is a Proxy, not an array";
+        const held = HELD_LIST_REFUSALS.get(rules);
+        if (held !== undefined)
+            return held;
     }
-    return out;
+    if (!Array.isArray(rules))
+        return "rules is not an array";
+    const cap = DEFAULT_CAPS.maxRules;
+    return rules.length > cap ? `rules list has ${rules.length} entries; the cap is ${cap} — refused whole (not truncated)` : undefined;
+}
+export const ORG_ROW_POLICY_MEMBERS = Object.freeze(["rule", "behavior"]);
+const ORG_SNAPSHOT_ENVELOPE_MEMBERS = Object.freeze(["revision", "fetchedAtMs", "signature"]);
+const ORG_STATE_MEMBERS = Object.freeze(["revisionHighWater", "installedAtMs"]);
+function scalarMembersOf(value, members) {
+    const held = {};
+    if (typeof value !== "object" || value === null)
+        return held;
+    for (const k of members) {
+        const v = Object.hasOwn(value, k) ? value[k] : undefined;
+        if (typeof v === "string" || typeof v === "boolean" || v === null || (typeof v === "number" && Number.isFinite(v)))
+            held[k] = v;
+    }
+    return held;
+}
+function orgRowPolicyOf(row) {
+    return scalarMembersOf(row, ORG_ROW_POLICY_MEMBERS);
+}
+const ORG_RULES_DEPTH = 2;
+const ORG_RULES_RECEIPT = Object.freeze({ accessors: "call-once", depth: ORG_RULES_DEPTH, others: "copy", contain: true, isProxy: (v) => types.isProxy(v) });
+export function orgRuleListOf(rules) {
+    const refused = listRefusalOf(rules);
+    if (refused !== undefined)
+        return { refused };
+    const received = receive(rules, ORG_RULES_RECEIPT);
+    if (!received.ok)
+        return { refused: `rules could not be received (${describeFault(received.fault)})` };
+    const copy = received.value;
+    return { rows: Array.from({ length: copy.length }, (_, i) => orgRowPolicyOf(Object.hasOwn(copy, i) ? copy[i] : undefined)) };
+}
+const HELD_LIST_REFUSALS = new WeakMap();
+function heldRefusalOf(words) {
+    const held = Object.freeze({});
+    HELD_LIST_REFUSALS.set(held, words);
+    return held;
+}
+function orgSnapshotCopyOf(v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v === "object" && v !== null && types.isProxy(v))
+        throw new Error("the snapshot is a Proxy, not data");
+    const envelope = scalarMembersOf(v, ORG_SNAPSHOT_ENVELOPE_MEMBERS);
+    const rules = typeof v === "object" && v !== null ? v.rules : undefined;
+    const refusal = listRefusalOf(rules);
+    if (refusal !== undefined)
+        return { ...envelope, rules: heldRefusalOf(refusal) };
+    const list = orgRuleListOf(rules);
+    if ("refused" in list)
+        throw new Error(`the snapshot's ${list.refused}`);
+    return { ...envelope, rules: list.rows };
+}
+function orgStateCopyOf(state) {
+    if (typeof state === "object" && state !== null && types.isProxy(state))
+        throw new Error("the persisted org state is a Proxy, not data");
+    const snapshot = typeof state === "object" && state !== null ? state.snapshot : undefined;
+    return { ...scalarMembersOf(state, ORG_STATE_MEMBERS), snapshot: orgSnapshotCopyOf(snapshot ?? null) };
+}
+function readOrgRow(row, index) {
+    const { rule: text, behavior: said } = orgRowPolicyOf(row);
+    const behavior = said === "ask" ? "ask" : "deny";
+    const unreadable = (code, detail) => ({
+        kind: "unreadable",
+        index,
+        rule: typeof text === "string" ? text : text === undefined ? "<unreadable>" : escapeForDisclosure(text),
+        code,
+        ...(detail !== undefined ? { detail } : {}),
+        behavior,
+        reach: reachOfRowHead(text, behavior),
+    });
+    if (typeof text !== "string" || text === "")
+        return unreadable("invalid.grammar", "no rule text");
+    if (said !== "deny" && said !== "ask")
+        return unreadable("invalid.grammar", said === undefined ? "no behavior" : `behavior "${escapeForDisclosure(said)}" is not deny or ask`);
+    const parsed = parseRuleText(text, said);
+    if ("reject" in parsed)
+        return unreadable(parsed.reject.code);
+    if (parsed.rule.tool !== COMMAND_RULE_TOOL)
+        return unreadable("unsupported.tool");
+    return { kind: "read", index, rule: text, behavior: said, parsed: parsed.rule };
+}
+export function readOrgRules(rules) {
+    const list = orgRuleListOf(rules);
+    if ("refused" in list)
+        return list;
+    const rows = list.rows.map((row, i) => readOrgRow(row, i + 1));
+    const unreadable = rows.filter((r) => r.kind === "unreadable");
+    return {
+        rows,
+        unreadable,
+        verdictFor(call) {
+            const words = typeof call.tool === "string" ? [call.tool] : call.tool;
+            const command = words.includes(COMMAND_RULE_TOOL) && typeof call.command === "string" ? call.command : undefined;
+            let ask;
+            let unjudged;
+            for (const row of rows) {
+                if (row.kind === "unreadable") {
+                    if (!rowReaches(row.reach, words, call.face))
+                        continue;
+                    const verdict = { behavior: row.behavior, rule: row.rule, unreadable: unreadableOrgRowReason(row) };
+                    if (row.behavior === "deny")
+                        return verdict;
+                    ask ??= verdict;
+                    continue;
+                }
+                if (command === undefined)
+                    continue;
+                const outcome = programRunReachOf(row.parsed, command);
+                if (outcome.reach === "not_reached")
+                    continue;
+                if (outcome.reach === "unreadable") {
+                    unjudged ??= { behavior: "ask", rule: row.rule, unreadable: outcome.reason };
+                    continue;
+                }
+                if (row.behavior === "deny")
+                    return { behavior: "deny", rule: row.rule };
+                ask ??= { behavior: "ask", rule: row.rule };
+            }
+            return unjudged ?? ask;
+        },
+    };
+}
+export function unenforceableOrgRules(rules) {
+    return readListedOrgRules(rules).unreadable.map((u) => ({ rule: u.rule, code: u.code }));
+}
+function readListedOrgRules(rules) {
+    const reading = readOrgRules(rules);
+    if ("refused" in reading)
+        throw new TypeError(`the org rules cannot be read: ${reading.refused}`);
+    return reading;
+}
+export function unreadableOrgRowReason(row) {
+    return `row ${row.index} of the organization snapshot is not a rule this layer reads (${row.code}${row.detail !== undefined ? `: ${row.detail}` : ""}); republish it in the shell tool's command grammar`;
+}
+export function orgUnreadableClause(reason) {
+    return `which could not be read against it (${reason})`;
 }
-function describeUnenforceable(unenforceable) {
-    const named = unenforceable
-        .slice(0, DISCLOSED_UNENFORCEABLE_RULES)
-        .map((u) => `"${escapeForDisclosure(u.rule)}" (${u.code})`)
+export function describeUnreadableOrgRows(unreadable, revision) {
+    if (unreadable.length === 0)
+        return undefined;
+    const named = unreadable
+        .slice(0, DISCLOSED_UNREADABLE_ROWS)
+        .map((u) => `row ${u.index} "${escapeForDisclosure(u.rule)}" (${u.code}${u.detail !== undefined ? `: ${u.detail}` : ""})`)
         .join(", ");
-    const more = unenforceable.length - DISCLOSED_UNENFORCEABLE_RULES;
-    return more > 0 ? `${named} and ${more} more` : named;
+    const more = unreadable.length - DISCLOSED_UNREADABLE_ROWS;
+    return (`the org snapshot${revision !== undefined ? ` (revision ${escapeForDisclosure(revision)})` : ""} is served DEGRADED: ${unreadable.length} row(s) this layer cannot read — ${named}${more > 0 ? ` and ${more} more` : ""}; ` +
+        `each stands at its strictest reading over the calls it may reach (a deny row, or one whose behavior cannot be read, refuses them; an ask row asks a person), and every readable row stands as published — republish the named rows in the shell tool's command grammar`);
 }
 function validateOrgSnapshot(s, nowMs) {
     if (typeof s.revision !== "number" || !Number.isFinite(s.revision))
@@ -225,61 +387,33 @@ function validateOrgSnapshot(s, nowMs) {
     if (s.fetchedAtMs > nowMs + ORG_FETCHED_AT_SKEW_ALLOWANCE_MS) {
         return `fetchedAtMs is ${s.fetchedAtMs - nowMs}ms in the future (allowance ${ORG_FETCHED_AT_SKEW_ALLOWANCE_MS}ms) — a future-dated observation would satisfy the staleness bound indefinitely`;
     }
-    if (!Array.isArray(s.rules))
-        return "rules is not an array";
-    for (const r of s.rules) {
-        if (typeof r?.rule !== "string" || r.rule === "")
-            return "a rule entry carries no rule text";
-        if (r.behavior !== "deny" && r.behavior !== "ask") {
-            return `rule "${escapeForDisclosure(r.rule)}" carries behavior "${escapeForDisclosure(r.behavior)}" — the org layer has no allow bucket`;
-        }
-    }
-    const unenforceable = unenforceableOrgRules(s.rules);
-    const first = unenforceable[0];
-    if (first !== undefined) {
-        const rest = unenforceable.length > 1 ? ` (${unenforceable.length} in all — ${describeUnenforceable(unenforceable)})` : "";
-        return `rule "${escapeForDisclosure(first.rule)}" does not parse (${first.code}) — an unenforceable deny/ask must not stand as policy${rest}`;
-    }
-    return undefined;
+    return listRefusalOf(s.rules);
 }
 export function orgRuleVerdictFor(rules, call) {
-    let ask;
-    let unreadable;
-    for (const r of rules) {
-        const parsed = parseRuleText(r.rule, r.behavior);
-        if ("reject" in parsed)
-            continue;
-        if (parsed.rule.tool !== call.tool)
-            continue;
-        const outcome = programRunReachOf(parsed.rule, call.command);
-        if (outcome.reach === "not_reached")
-            continue;
-        if (outcome.reach === "unreadable") {
-            unreadable ??= { behavior: "ask", rule: r.rule, unreadable: outcome.reason };
-            continue;
-        }
-        if (r.behavior === "deny")
-            return { behavior: "deny", rule: r.rule };
-        ask ??= { behavior: "ask", rule: r.rule };
-    }
-    return unreadable ?? ask;
+    return readListedOrgRules(rules).verdictFor(call);
 }
 export function orgRuleShadows(orgRules, rule) {
     return compileOrgShadowPredicate(orgRules)(rule);
 }
 export function compileOrgShadowPredicate(orgRules) {
-    const denies = [];
-    for (const d of orgRules) {
-        if (d.behavior !== "deny")
-            continue;
-        const parsed = parseRuleText(d.rule, "deny");
-        if (!("reject" in parsed))
-            denies.push(parsed.rule);
-    }
+    const { rows } = readListedOrgRules(orgRules);
+    const denies = rows.flatMap((r) => (r.kind === "read" && r.behavior === "deny" ? [r.parsed] : []));
+    const standing = rows.flatMap((r) => (r.kind === "unreadable" && r.behavior === "deny" ? [r.reach] : []));
     return (rule) => {
-        if (rule.tool !== "Bash" || denies.length === 0)
+        if (standing.length > 0) {
+            const word = isShellFaceToolName(rule.tool) ? COMMAND_RULE_TOOL : rule.tool;
+            const target = pathTargetOf(rule.tool);
+            const faces = Object.hasOwn(PATH_RULE_FACES, rule.tool)
+                ? (PATH_RULE_FACES[rule.tool]?.allow ?? [])
+                : target !== undefined
+                    ? [target.access === "read" ? "read" : "write"]
+                    : [undefined];
+            if (standing.some((reach) => faces.some((face) => rowReaches(reach, [word], face))))
+                return true;
+        }
+        if (rule.tool !== COMMAND_RULE_TOOL || denies.length === 0)
             return false;
-        return denies.some((d) => d.tool === rule.tool && ruleReachesProgramRun(d, rule.command));
+        return denies.some((d) => ruleReachesProgramRun(d, rule.command));
     };
 }
 export function isWritablePermissionRuleStore(store) {

package/dist/core/permission-rule-syntax.d.ts

@@ -28,3 +28,18 @@ export declare function lastIndexOfUnescaped(s: string, ch: string): number;
  * factory) to refuse the downgrades.
  */
 export declare function parsePermissionRule(rule: string): ParsedPermissionRule;
+/**
+ * Can a rule name this tool name — is it the rule syntax's name head ({@link RULE_TOOL_NAME}) and not the lone `*`? The
+ * lone `*` is the wildcard (every tool), not a name: a tool called `*` could never be granted or refused on its own. The
+ * mount contract for every name a caller tool answers to (its name and each alias), so each one is a name every list can
+ * write; a protocol-minted name (`<ns>__<peer>__<tool>`, segments in `[A-Za-z0-9_-]`) is always one.
+ */
+export declare function isNameableToolName(name: string): boolean;
+/**
+ * One rule entry read by the rule syntax, or `undefined` when the syntax cannot read it: blanks around it, a tool name (the
+ * text before the first unescaped `(`, as written) outside {@link RULE_TOOL_NAME}, or a `(` the parse cannot close at the
+ * entry's end (the lenient parser's downgrade: the whole string read as a name); otherwise {@link parsePermissionRule}'s
+ * reading. THE test of "this is a rule spelling" — every entry list's reader asks it before any rule grammar reads the
+ * content (what the parentheses hold, a parenthesis or a control character included, is that grammar's to judge).
+ */
+export declare function ruleSpellingOf(rule: string): ParsedPermissionRule | undefined;

package/dist/core/permission-rule-syntax.js

@@ -1,25 +1,19 @@
+function escapedAt(s, i) {
+    let backslashes = 0;
+    for (let j = i - 1; j >= 0 && s[j] === "\\"; j--)
+        backslashes++;
+    return backslashes % 2 === 1;
+}
 export function indexOfUnescaped(s, ch) {
-    for (let i = 0; i < s.length; i++) {
-        if (s[i] !== ch)
-            continue;
-        let backslashes = 0;
-        for (let j = i - 1; j >= 0 && s[j] === "\\"; j--)
-            backslashes++;
-        if (backslashes % 2 === 0)
+    for (let i = 0; i < s.length; i++)
+        if (s[i] === ch && !escapedAt(s, i))
             return i;
-    }
     return -1;
 }
 export function lastIndexOfUnescaped(s, ch) {
-    for (let i = s.length - 1; i >= 0; i--) {
-        if (s[i] !== ch)
-            continue;
-        let backslashes = 0;
-        for (let j = i - 1; j >= 0 && s[j] === "\\"; j--)
-            backslashes++;
-        if (backslashes % 2 === 0)
+    for (let i = s.length - 1; i >= 0; i--)
+        if (s[i] === ch && !escapedAt(s, i))
             return i;
-    }
     return -1;
 }
 function unescapeRuleContent(s) {
@@ -42,3 +36,17 @@ export function parsePermissionRule(rule) {
         return { toolName: name.trim() };
     return { toolName: name.trim(), ruleContent: unescapeRuleContent(content) };
 }
+const RULE_TOOL_NAME = /^(?:\*|[A-Za-z0-9_](?:[A-Za-z0-9_.:*-]*[A-Za-z0-9_*-])?)$/;
+export function isNameableToolName(name) {
+    return typeof name === "string" && name !== "*" && RULE_TOOL_NAME.test(name);
+}
+export function ruleSpellingOf(rule) {
+    if (rule !== rule.trim())
+        return undefined;
+    const open = indexOfUnescaped(rule, "(");
+    const name = open < 0 ? rule : rule.slice(0, open);
+    if (!RULE_TOOL_NAME.test(name))
+        return undefined;
+    const parsed = parsePermissionRule(rule);
+    return parsed.toolName === name ? parsed : undefined;
+}