@sema-agent/core 7.8.0 → 7.9.1

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

@@ -1,13 +1,25 @@
 /**
- * design/179 §2 — the persisted ALLOW rule model and its matcher.
- *
- * A persisted allow rule is the standing form of ONE recorded human approval: the person confirmed a
- * command once on an approval card and asked not to be asked again, and the rule is what that answer
- * becomes. This module owns the rule's SHAPE (text grammar, canonical spelling, scope) and its MATCH
- * semantics; who may mint one, where it is stored, and where in the gate it is consumed live in
- * `permission-rule-store.ts`, `permission-rule-consent.ts` and `hooks.ts` respectively.
- *
- * ## The floor: what a rule may name, and what a rule may match
+ * design/179 §2 — the persisted permission-rule model and its matchers.
+ *
+ * A persisted rule is one person's standing instruction about a tool call, in one of THREE behaviors
+ * ({@link RULE_BEHAVIORS}): an `allow` is the standing form of ONE recorded human approval (the person
+ * confirmed a command once on an approval card and asked not to be asked again); a `deny` and an `ask`
+ * are the standing forms of "never run this" and "ask me every time" — the same content-form rules
+ * upstream reads out of its settings' deny/ask lists. ONE grammar, ONE canonical spelling and ONE
+ * matcher family serve all three; the behavior is a FIELD beside the text, never part of it, so
+ * `Bash(rm -r:*)` is one spelling whether it allows, denies or asks. This module owns the rule's SHAPE
+ * (text grammar, canonical spelling, scope, behavior) and its MATCH semantics; who may mint one, where
+ * it is stored, and where in the gate it is consumed live in `permission-rule-store.ts`,
+ * `permission-rule-consent.ts` and `gate-lanes.ts` respectively.
+ *
+ * The two DIRECTIONS read a command differently, on purpose: an allow must cover the WHOLE call
+ * ({@link ruleAdmitsCommand} — one recorded yes clears exactly what it spells), while a deny/ask
+ * speaks about any PROGRAM RUN the call may perform ({@link programRunReachOf} — whole command or
+ * any segment of a chain, read with a real shell lexer, `shell-lexer.ts`, and answering `unreadable`
+ * for what it cannot read rather than silence). Precedence across behaviors is the upstream one,
+ * deny > ask > allow ({@link RULE_BEHAVIOR_PRECEDENCE}, the one table every adjudication reads).
+ *
+ * ## The floor: what a rule may name, and what a rule may match (the ALLOW direction)
  *
  * Everything a shell can use to run a program the text does not NAME — substitution, subshells,
  * backgrounding, escapes, line breaks, and **redirection** — puts the command outside this lane
@@ -41,7 +53,9 @@
  * The floor is `parseLeadingCommandName` + `splitShellCompoundSegments` — the one simple-command parser
  * and the one segmentation, both already shared with the read-only classifier, the reversibility probe,
  * the coarse command-name policy and the skill tool specifier. A second tokenizer would drift, and drift
- * on a loosening face shows up as a circumvention rather than as a test failure.
+ * on a LOOSENING face shows up as a circumvention rather than as a test failure. The tightening
+ * direction's lexer is not that second tokenizer: it reads MORE than the floor (never less), and a
+ * drift there costs an approval prompt, never a standing approval.
  *
  * argv[0] may carry a PATH prefix here (`./gradlew`, `/usr/bin/git`) — opt-in at the shared parser and
  * used by this lane alone. The bare-name requirement belongs to the argv[0]-NAME filters, which compare
@@ -58,6 +72,48 @@
  * here) and no leading-env-assignment stripping (`FOO=1 git status` simply does not match
  * `Bash(git status:*)`) — the last two are strict-side divergences from upstream, registered as such.
  */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/**
+ * The closed set of rule BEHAVIORS — what a matching rule says about the call. The upstream vocabulary
+ * verbatim (`allow` / `deny` / `ask`, the three settings lists), in PRECEDENCE order: when rules of more
+ * than one behavior speak for one call, the earliest member here decides ({@link RULE_BEHAVIOR_PRECEDENCE}
+ * is that order as a table, and {@link adjudicatePersistedRules} is the one place that walks it).
+ *
+ * The type is derived FROM the array so a member added to either side is a compile error; a value read
+ * off a wire or a file goes through {@link isRuleBehavior} (present but outside the set = refused, never
+ * defaulted) or {@link readRowBehavior} (the ONE reading of a row that predates the field).
+ */
+export declare const RULE_BEHAVIORS: readonly ["deny", "ask", "allow"];
+export type RuleBehavior = (typeof RULE_BEHAVIORS)[number];
+/** Membership test for {@link RuleBehavior}. Exported because the word crosses process boundaries (a
+ *  store row, a sync payload, a settings entry) and a host validating one must not hand-roll the set. */
+export declare function isRuleBehavior(v: unknown): v is RuleBehavior;
+/**
+ * The precedence table: the rank at which each behavior decides a call when several rules speak (lower
+ * decides first). Upstream's arbiter walks deny, then ask, then allow — an explicit deny is never
+ * outvoted by an allow, and a standing "ask me each time" is never silenced by a remembered yes. Every
+ * adjudication over a mixed rule table orders its walk by THIS table (never by a hand-written if-chain),
+ * so the rank of a behavior is stated once.
+ */
+export declare const RULE_BEHAVIOR_PRECEDENCE: {
+    readonly deny: 0;
+    readonly ask: 1;
+    readonly allow: 2;
+};
+/** Compile-time fence over the precedence table: `never` while every behavior has a rank. */
+export type PrecedenceTableCoversEveryBehavior = AssertAllKeysHandled<Exclude<RuleBehavior, keyof typeof RULE_BEHAVIOR_PRECEDENCE>>;
+/** The behaviors in precedence order — the walk every mixed-table adjudication takes. */
+export declare const RULE_BEHAVIORS_BY_PRECEDENCE: readonly RuleBehavior[];
+/**
+ * The ONE reading of a persisted row's behavior at every seam that may meet a row written before the
+ * field existed — the file store's schema migration, the sync wire's inbound picker, a checkpoint's
+ * rehydrated session rows. An ABSENT behavior reads `"allow"`: every row an engine without the field
+ * ever wrote was an allow, so that reading is the row's own meaning, not a default. A PRESENT value
+ * outside the closed set is refused (`undefined`) — a word this engine cannot read must not become an
+ * allow by falling through (the loud-bad-value doctrine), and must not become a deny either (a
+ * fabricated tightening is still a fabrication).
+ */
+export declare function readRowBehavior(v: unknown): RuleBehavior | undefined;
 /** The tools the rule lane speaks for. `"Bash"` is the historical member; `"Read"` (design/382 §2.2)
  *  speaks EXACTLY ONE grammar — the double-slash directory form `Read(//abs/**)`, the directory
  *  read-authorization a compound card's cd segment mints — and its admission is the CLOSED two-point
@@ -70,7 +126,19 @@
  *  silence the classifier's questions, never a mandated one), so a recorded human yes is exactly what
  *  clears it. The org/hook/matchedAskRule immunities stay: those conjuncts live in the gate's
  *  persisted-rule lane and do not loosen with this set. */
-export type PersistedRuleTool = "Bash" | "Read";
+export type PersistedRuleTool = string;
+/** The one shell tool the command grammar speaks for. */
+export declare const COMMAND_RULE_TOOL = "Bash";
+/** The one tool whose path family has an ALLOW form (the `Read(//abs-dir/**)` directory grant). */
+export declare const READ_RULE_TOOL = "Read";
+/**
+ * Which tools a rule may name — the model's tool set is DERIVED, never a hand-kept list: the shell tool
+ * takes the COMMAND grammar; every tool the catalog declares a path target for (Read / Edit / Write /
+ * Glob / NotebookEdit / …, `pathTargetOf`) takes the PATH grammar. A rule on any other tool has no
+ * content this model can judge and is refused (`unsupported.tool`). The tool set therefore moves with the
+ * catalog's declarations, exactly as the protective fences' covered set does.
+ */
+export declare function ruleToolGrammarOf(toolName: string): "command" | "path" | undefined;
 /**
  * Match forms. Four members, two of them one predicate:
  *  · `exact` — admits the one string the rule spells.
@@ -82,13 +150,19 @@ export type PersistedRuleTool = "Bash" | "Read";
  *    on the single-command body. Kept as a fully supported COMPATIBILITY READ — stored rules are never
  *    migrated or rewritten — and it remains the ONLY spelling of the compound-prefix form
  *    (`Bash(cd /tmp && adb pull:*)`): the trailing-star form deliberately has no compound reading
- *    (see {@link parseAllowRuleText}), because upstream's own trailing-star pattern is inert on a
+ *    (see {@link parseRuleText}), because upstream's own trailing-star pattern is inert on a
  *    compound and importing/minting one as a chain licence would grant what nobody approved.
- *  · `subpath` — the Read directory form (design/382 §2.2): `Read(//abs/**)`, admitting reads under
- *    one absolute directory. Never admits any command; its one predicate is
- *    {@link directoryRuleAdmits}.
+ *  · `subpath` — the directory form (design/382 §2.2): `Tool(//abs-dir/**)`, reaching every path under
+ *    one absolute directory. Never admits any command; its one predicate is {@link directoryRuleAdmits}.
+ *    As an ALLOW it exists for the Read tool only (a standing yes to reads under a directory); as a
+ *    deny/ask it is legal on every path-targeting tool.
+ *  · `path` — the PATH PATTERN form, deny/ask only: upstream's file-rule spelling over a tool's path
+ *    target (`Edit(~/.sema/settings.json)`, `Write(src/**)`, `Read(//etc/*)`), stored AS SPELLED and
+ *    resolved at match time against the call's bases (`//` absolute, `~/` home, `/` project root,
+ *    otherwise the working directory). Its predicate is {@link pathRuleReaches}. Not an allow form: a
+ *    standing approval by path pattern would be a wider grant than any card ever shows a person.
  */
-export type PersistedRuleMatch = "exact" | "prefix" | "wildcard" | "subpath";
+export type PersistedRuleMatch = "exact" | "prefix" | "wildcard" | "subpath" | "path";
 /**
  * Where a rule applies — design/382 §4.1, the THREE consent dimensions.
  *
@@ -143,13 +217,24 @@ export interface RuleAdd {
     createdAt: string;
 }
 /**
- * A persisted ALLOW rule for one tool.
- *
- * `adds` is a real set, not a scalar: two concurrently approved records for the same (rule, scope)
- * each redeem their own dot, and a rule is live iff at least one of its adds survives the tombstones.
- * Organization rules have the opposite polarity (deny/ask only) and never enter this type.
+ * A persisted rule for one tool, in one of the three behaviors.
+ *
+ * The logical identity of a rule is the TRIPLE (behavior, rule text, scope): the same text may stand as
+ * an allow and as a deny in one bucket (upstream keeps the three lists side by side and lets precedence
+ * decide), so a tombstone, a quarantine row and a join group all key on the triple — a key on (text,
+ * scope) alone would let a delete aimed at the allow take the deny with it.
+ *
+ * `adds` is a real set, not a scalar: two concurrently approved records for the same identity each
+ * redeem their own dot, and a rule is live iff at least one of its adds survives the tombstones.
+ * Organization rules are a separate partition (a server-published snapshot, no CRDT) and never enter
+ * this type; the personal deny/ask rows here are the PERSON's own standing instructions (their settings'
+ * deny/ask lists, imported through the same consent door the allow list takes).
  */
-export interface PersistedAllowRule {
+export interface PersistedRule {
+    /** What a match of this rule says about the call — REQUIRED on every row this engine writes. A row
+     *  read without one is a pre-field row and reads `allow` through {@link readRowBehavior}, at the
+     *  reading seams only (the store's schema migration, the sync picker, a checkpoint's session rows). */
+    behavior: RuleBehavior;
     /** Canonical rule text: `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). A prefix body
      *  may itself be a connector chain (`Bash(cd /tmp && adb pull:*)`) — see the module note on
      *  connectors for what such a rule reaches. */
@@ -170,6 +255,8 @@ export interface PersistedAllowRule {
  * in no tombstone for the same (rule, scope).
  */
 export interface RuleTombstone {
+    /** The identity's behavior member — a tombstone deletes adds of ONE (behavior, text, scope). */
+    behavior: RuleBehavior;
     rule: string;
     scope: RuleScope;
     removedDots: RuleDot[];
@@ -185,8 +272,11 @@ export interface RuleReject {
     code: RuleRejectCode;
     message: string;
 }
-/** The parsed, canonical shape of one rule text — everything but the scope and the provenance. */
-export interface ParsedAllowRule {
+/** The parsed, canonical shape of one rule text under one behavior — everything but the scope and the
+ *  provenance. The behavior is the parser's INPUT (it decides which validator floor applies), carried
+ *  out so a consumer holding the parse never re-derives which list the text came from. */
+export interface ParsedRule {
+    behavior: RuleBehavior;
     rule: string;
     tool: PersistedRuleTool;
     match: PersistedRuleMatch;
@@ -209,7 +299,7 @@ export declare const MAX_RULE_TEXT_CHARS = 512;
  * an EXACT rule naming a whole interpreter command line stays legal, since it authorizes one command.
  *
  * TWO READERS, and they consult this table with DIFFERENT questions — do not read either as the other.
- * {@link parseAllowRuleText} asks "is this rule TEXT's own head a row?" and compares the basename as
+ * {@link parseRuleText} asks "is this rule TEXT's own head a row?" and compares the basename as
  * SPELLED, so an alias spelling (`SSH host:*`, `ssh.exe host:*`) is a different name to it and enters
  * the store like any other rule. {@link genericPrefixBody} asks "should the engine PROPOSE a body with
  * this head?" and normalizes first ({@link screenedHeadName}: case, trailing periods, executable
@@ -250,18 +340,16 @@ export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
  * Shell KEYWORDS, refused as a segment's `argv[0]` everywhere this lane reads a command.
  *
  * The floor this lane stands on extracts the first TOKEN of a segment and calls it the command name.
- * That identification is what every comparison here rests on — the interpreter refusal, the deny/ask
- * layer's per-segment judgement, and a person's reading of the rule text. For a control structure it is
- * simply false. `for x in once; do curl evil.example; done` splits into three segments whose first
- * tokens are `for`, `do` and `done`; all three are ordinary bare words, so the floor accepts each,
- * `curl` is named by nothing, and a published `deny Bash(curl:*)` matches none of them while bash runs
- * curl. A whole loop body — any number of programs — hides behind three tokens that name no program.
- *
- * Refusing the keyword puts the whole command outside the lane, which is the honest answer: no rule can
- * be minted for it and no rule matches it, so it asks. Recovering these shapes properly needs a real
- * shell grammar (upstream has one — it parses to a syntax tree and reads the commands out of the
- * structure, so a keyword is never mistaken for a program); a token-level lane cannot, and pretending
- * otherwise is the loosening direction.
+ * That identification is what every comparison here rests on — the interpreter refusal and a person's
+ * reading of the rule text. For a control structure it is simply false: `for x in once; do curl
+ * evil.example; done` splits into three segments whose first tokens are `for`, `do` and `done`; all
+ * three are ordinary bare words, so the floor accepts each, and a rule text could name a keyword as
+ * though it were a program.
+ *
+ * Refusing the keyword puts the whole command outside the ALLOW lane, which is the honest answer: no rule
+ * can be minted for it and no allow matches it, so it asks. The DENY/ASK direction reads these shapes
+ * with its own lexer (`shell-lexer.ts`: a prefixing keyword is stripped so `do curl evil.example` runs
+ * `curl`; a `for`/`case` header, whose commands need a syntax tree, is `unreadable` and asks).
  *
  * `!` is here for the same reason with a sharper edge: it is a keyword that PREFIXES a real command, so
  * `! node -e …` is the `node` licence the interpreter table exists to refuse, wearing one extra token.
@@ -391,23 +479,46 @@ export declare function hasUnrenderableCharacters(text: string): boolean;
  * product's settings, reloading a store file, and any future backend. A shape refused here cannot enter
  * the store through any door.
  *
- * `direction` (design/182 §7, additive): the bare-interpreter-prefix refusal is an ALLOW-side argument
- * — one approval click cannot be read as authorizing arbitrary programs. An org deny/ask rule has the
- * opposite polarity: `Bash(node:*)` as a DENY is a legitimately wide tightening, and refusing it would
- * silently disarm exactly the policy an administrator most wants. `"tighten"` therefore admits the
- * interpreter-headed prefix form and changes nothing else; the default stays the allow-side floor.
+ * `behavior` is REQUIRED — there is no default, because the two directions have different floors and
+ * a defaulted allow is exactly the silent-widening shape a validator must not have: the
+ * bare-interpreter-prefix refusal is an ALLOW-side argument (one approval click cannot be read as
+ * authorizing arbitrary programs), while a deny/ask has the opposite polarity — `Bash(node:*)` as a DENY
+ * is a legitimately wide tightening, and refusing it would silently disarm exactly the rule a person
+ * most wants. The tightening behaviors therefore admit the interpreter-headed prefix form and change
+ * nothing else; the allow floor is unchanged.
  */
-export declare function parseAllowRuleText(text: string, opts?: {
-    direction?: "allow" | "tighten";
-}): {
-    rule: ParsedAllowRule;
+export declare function parseRuleText(text: string, behavior: RuleBehavior): {
+    rule: ParsedRule;
 } | {
     reject: RuleReject;
 };
-/** The canonical spelling of a rule for a (already folded) command and match form. For `subpath` the
- *  command is the lexical-normal absolute directory (one leading slash), re-spelled in the
- *  double-slash directory form. */
-export declare function formatAllowRuleText(command: string, match: PersistedRuleMatch): string;
+/** The canonical spelling of a rule for a (already folded) command and match form on `tool`. For
+ *  `subpath` the command is the lexical-normal absolute directory (one leading slash), re-spelled in the
+ *  double-slash directory form; for `path` it is the pattern as spelled. */
+export declare function formatRuleText(command: string, match: PersistedRuleMatch, tool: PersistedRuleTool): string;
+/**
+ * The bases a path pattern resolves against at match time — facts of the CALL, never of the rule:
+ * `home` for `~/…` (absent ⇒ `os.homedir()`), `root` for `/…` (the task's project root), `cwd` for a
+ * relative pattern (the live working directory; absent ⇒ `root`). A pattern whose base is absent
+ * resolves to nothing and reaches nothing.
+ */
+export interface PathRuleBases {
+    readonly root?: string;
+    readonly cwd?: string;
+    readonly home?: string;
+}
+/** Is this base usable by {@link resolvePathPattern} — an absolute path with a lexical normal form? A rule
+ *  compiler asks this at compile time so a pattern is refused rather than compiled inert. */
+export declare function isUsablePathBase(base: string | undefined): boolean;
+/**
+ * The PATH family's tightening predicate: does this deny/ask rule reach the call's target path? The
+ * target is the caller's ALREADY-RESOLVED lexical-normal absolute path (the same identity the read/write
+ * fences judge with). A `subpath` rule reaches the directory and everything under it
+ * ({@link directoryRuleAdmits}); a `path` rule resolves its spelling against the call's bases and
+ * matches segment-wise (`*` within a segment, `**` across segments), reaching the path it names and
+ * everything under a directory it names. A command-family rule reaches no path.
+ */
+export declare function pathRuleReaches(rule: Pick<PersistedRule, "match" | "command">, target: string, bases: PathRuleBases): boolean;
 /**
  * Does this rule's command pattern admit `command`?
  *
@@ -425,22 +536,74 @@ export declare function formatAllowRuleText(command: string, match: PersistedRul
  * same count equality is the containment: `Bash(a && b:*)` admits `a && b x`, never `a && b x && c`.
  * An EXACT rule has no such reach by construction: it admits one string, the one it spells.
  */
-export declare function ruleAdmitsCommand(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
+export declare function ruleAdmitsCommand(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
 /**
- * The same match, asked the DENY/ASK layer's question — "does this rule speak about this program run?".
- *
- * Split from {@link ruleAdmitsCommand} because the two differ on one axis that decides real cases: a
- * quoted operator. `curl "https://x/?a=1&b=2"` is ONE command bash runs, and the `&` in a query string
- * is not a connector; the matching side refuses it anyway (a rule text is a spelling with no operator
- * characters in it at all — the historical rule-face contract), and the deny side inheriting that
- * refusal made `deny Bash(curl:*)` silent on the commonest spelling of the very program it names
- * (adversarial round 3).
- *
- * The asymmetry only ever runs one way: this predicate reads MORE commands than the matching one, never
- * fewer. A shape only the ALLOW side could read would be a standing approval no published policy could
- * see — the inversion this whole ticket exists to prevent.
+ * What one TIGHTENING (deny/ask) rule can say about a call — the closed three-word answer of
+ * {@link programRunReachOf}:
+ *  - `reached` — the text PROVABLY performs a run the rule names (the whole chain, or any one segment);
+ *  - `not_reached` — the text provably does not (every compared word is literal and differs, or the
+ *    command is shorter than the rule's body);
+ *  - `unreadable` — the text MAY perform it but cannot be read: an expansion sits where the rule reads a
+ *    word, a quote or substitution never closes, a syntax error, a control structure whose commands need
+ *    a syntax tree, a wrapper handed its command as one string.
+ * The three lanes that consume it (the org partition, the personal deny/ask rows, the rule DSL's
+ * content-form rules) dispose of the words identically: `reached` speaks with the rule's behavior,
+ * `not_reached` is silence, and `unreadable` is a FAIL-CLOSED ask — never silence, which is what once let
+ * `rm -r x; echo "$HOME"` walk past a deny on `rm -r` because one expansion took the whole line out of
+ * the reader. Registered in docs/CLOSED-SETS.md.
+ */
+export declare const PROGRAM_RUN_REACHES: readonly ["reached", "not_reached", "unreadable"];
+export type ProgramRunReach = (typeof PROGRAM_RUN_REACHES)[number];
+/** The answer of {@link programRunReachOf}: the word, and for `unreadable` the reason a surface can show. */
+export type ProgramRunReachOutcome = {
+    readonly reach: "reached" | "not_reached";
+} | {
+    readonly reach: "unreadable";
+    readonly reason: string;
+};
+/**
+ * Does one TIGHTENING (deny/ask) rule speak about this call — as a whole, or about any single program
+ * run in it — or can the call not be read against it at all? The ONE reach predicate of the tightening
+ * direction, shared by the org partition, the personal deny/ask rows and the rule DSL's content-form
+ * deny/ask rules, so no two of them can disagree about what a deny reaches.
+ *
+ * The allow lane asks a different question and gets a different answer, deliberately. An allow rule is
+ * one recorded human yes and must cover the WHOLE call to clear it ({@link ruleAdmitsCommand}:
+ * `Bash(npm test)` does not clear `npm test && curl evil.example`, because nobody said yes to the second
+ * half), and it refuses every shell construct outright. A deny/ask rule is a standing statement about a
+ * program run, and a call that MAY perform that run is a call the rule speaks about — so this direction
+ * reads the command with a real lexer ({@link readShellCommand}): redirections are stripped at the
+ * token level, quotes are removed on BOTH sides before words are compared (`rm "-r" x` runs `rm -r x`),
+ * wrappers are peeled (`sudo env X=1 nohup rm -r x` runs `rm -r x`), every connector — `&` and a newline
+ * included — bounds a segment, and a comment is not a run. Deliberately an OVER-approximation, in the
+ * tightening direction: the segments are the runs the text can reach, not the runs that will happen, so
+ * a short-circuited branch (`true || curl evil.example`) is judged as though it ran. Answering "does this
+ * definitely execute" needs evaluation, not parsing; over-firing costs an approval prompt, and the
+ * opposite error costs the rule.
+ *
+ * Words are compared ARGV-wise, position by position, against the rule body read by the same lexer —
+ * over every run CANDIDATE a segment carries: as spelled, then each peeled layer (`sudo rm -r x` is a run
+ * of `sudo …` AND of `rm -r x`; a deny on either reaches; a rule body is never peeled, so
+ * `Bash(sudo rm -r x)` denies exactly that). A literal word that differs settles `not_reached`; a word
+ * carrying an expansion at a position the rule reads settles `unreadable` (the text could spell the
+ * rule's word there — unless it is the SAME glob/brace spelling the body wrote); a prefix body whose
+ * every word is matched is `reached` whatever follows; an exact body needs equal length — a longer
+ * command is `not_reached` unless an extra word is an UNQUOTED expansion (or `"$@"` / an array
+ * expansion), which may expand to nothing. The commands inside a substitution and an unquoted heredoc
+ * body are segments of their own (`echo "$(rm -r x)"` runs `rm`). A compound
+ * body (`Bash(echo ok && rm -r:*)`) reaches only a chain of the same shape — same segment count, same
+ * connectors, every leading segment equal, the final one by the body's match kind; a single-segment
+ * body reaches any segment. A segment the lexer could not read makes the answer `unreadable` when no
+ * other segment already reached.
+ *
+ * A rule body the lexer cannot read (foreign store bytes; every entrance validates against exactly
+ * this) reaches nothing. A path-family rule (`subpath` / `path`) reaches no command: its predicates are
+ * {@link directoryRuleAdmits} and {@link pathRuleReaches}.
  */
-export declare function ruleAdmitsProgramRun(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
+export declare function programRunReachOf(rule: Pick<PersistedRule, "match" | "command">, command: string): ProgramRunReachOutcome;
+/** The boolean face of {@link programRunReachOf}: `reached` only. The shadow view and the pins that
+ *  assert a reach read this; a lane that must fail closed on `unreadable` reads the outcome. */
+export declare function ruleReachesProgramRun(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
 /** design/382 §3.3-5 — one BREADTH note about a rule a person is about to persist: which wide shape
  *  it has, said in words a surface can show beside the input line. A warning is never a refusal —
  *  the closed refusal set is untouched — and never adjudication input. */
@@ -478,21 +641,7 @@ export interface EditedRuleBreadthWarning {
  * The upstream editor validates edited text but shows no breadth evidence at all; this seat is a
  * superset disclosure (registered divergence, design/382 §6-4).
  */
-export declare function ruleBreadthWarningsOf(rule: Pick<PersistedAllowRule, "match" | "command">): readonly EditedRuleBreadthWarning[];
-/**
- * The segments of `command` as the deny/ask layer must judge them, or `undefined` for a command this
- * lane cannot read.
- *
- * A tightening rule speaks about a PROGRAM RUN, and a compound runs several. `Bash(curl:*)` published
- * as a deny means "this machine does not make that call", and reading `npm test && curl evil.example`
- * as one unmatched blob answered that with silence — the shape the widening above would otherwise make
- * permanently approvable. Exported (rather than folded into a matcher here) because the layer that
- * needs it holds the rules: this module owns what a command IS, `permission-rule-org.ts` owns what the
- * organization says about each part of it.
- *
- * A single simple command yields a one-element list, so a deny that matched before matches identically.
- */
-export declare function ruleLaneSegmentsOf(command: string): readonly string[] | undefined;
+export declare function ruleBreadthWarningsOf(rule: Pick<PersistedRule, "match" | "command">): readonly EditedRuleBreadthWarning[];
 /**
  * Is `path` inside (or equal to) `root`? Word-boundary containment on the path separator, so `/a` does
  * not contain `/ab`. Both sides are expected to be canonical already.
@@ -501,8 +650,8 @@ export declare function pathWithinRoot(path: string, root: string): boolean;
 /**
  * The LEXICAL NORMALIZER for a CALL's target path (design/382 §2.2 — the rule family's one path
  * identity is the lexical normal form, zero IO): collapse slash runs and `.` segments, resolve `..`
- * segments textually, and answer the one-leading-slash absolute spelling — or `undefined` when no
- * such spelling exists (a relative path, a `..` climbing past the root, an empty result). RULE
+ * segments textually (a `..` at the root stays at the root, as POSIX resolves it), and answer the
+ * one-leading-slash absolute spelling — or `undefined` for a relative path. RULE
  * bodies never come through here (their canonical spelling is unique and non-normal spellings are
  * refused at the validator); this is for the comparison INPUT a caller derives from a live call.
  */
@@ -520,13 +669,16 @@ export declare function lexicalNormalAbsolutePathOf(path: string): string | unde
  * caller cannot smuggle a second path identity through the comparison. Containment is the
  * word-boundary one ({@link pathWithinRoot}: `/a` never reaches `/ab`).
  *
- * What it never does, stated as loudly as what it does (§2.5): admits READS ONLY — a rule of this
- * family never admits a write, never a whole Bash command, never a non-cd segment — and it clears
- * ASKS only, never a filesystem fence: workspace containment, the sensitive-read deny face and every
- * violation refusal judge exactly as they would without the rule (a fence refusal is structural, not
- * an ask, so there is nothing here for it to clear).
+ * What it never does, stated as loudly as what it does (§2.5): as an ALLOW it admits READS ONLY — the
+ * TOOL conjunct is the caller's (every consumer judges eligibility with the call's tool, and
+ * {@link adjudicatePersistedPathRules} takes the allow arm for the Read tool alone), so a directory allow
+ * never admits a write, never a whole Bash command, never a non-cd segment — and it clears ASKS only,
+ * never a filesystem fence: workspace containment, the sensitive-read deny face and every violation
+ * refusal judge exactly as they would without the rule (a fence refusal is structural, not an ask, so
+ * there is nothing here for it to clear). As a DENY/ASK the same containment refuses or questions every
+ * path under the directory, on whichever path tool the rule names.
  */
-export declare function directoryRuleAdmits(rule: Pick<PersistedAllowRule, "tool" | "match" | "command">, path: string): boolean;
+export declare function directoryRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, path: string): boolean;
 /** Does a rule's scope cover a task running in `cwd` (and, for the session dimension, in the session
  *  named by `sessionId`)? A project rule needs a cwd to compare against; without one it covers nothing
  *  (fail-closed). A session rule (design/382 §4.3) covers a call iff the call's `sessionId` equals the
@@ -539,7 +691,7 @@ export declare function directoryRuleAdmits(rule: Pick<PersistedAllowRule, "tool
 export declare function scopeCoversCwd(scope: RuleScope, cwd: string | undefined, sessionId?: string): boolean;
 /** Is this rule live — i.e. does it still carry at least one add? Deleted adds are removed by the store
  *  when tombstones are applied, so a rule with an empty `adds` is a rule that no longer exists. */
-export declare function isRuleLive(rule: PersistedAllowRule): boolean;
+export declare function isRuleLive(rule: PersistedRule): boolean;
 /**
  * design/375 §5.1 — MAY this rule speak about this call's CONTEXT? Tool identity plus scope coverage,
  * and nothing about the rule's liveness: the CONTEXT question is the half a not-yet-persisted rule (a
@@ -551,7 +703,7 @@ export declare function isRuleLive(rule: PersistedAllowRule): boolean;
  * cwd to compare against covers nothing (fail-closed, {@link scopeCoversCwd}).
  *
  * `scope` rides beside the rule rather than inside it for the PROPOSED half's sake: a
- * {@link ParsedAllowRule} carries no scope, so a proposal is judged against the scope it would LAND in.
+ * {@link ParsedRule} carries no scope, so a proposal is judged against the scope it would LAND in.
  *
  * design/382 §4.3 — the call context carries a THIRD axis, `sessionId` (optional: an existing caller
  * that threads only `{tool, cwd}` still compiles and still means what it meant — no session rule can
@@ -576,13 +728,16 @@ export declare function eligibleContext(rule: {
  * conjunction arm and its coverage-set selection here, the suggestion face's coverage judgement and the
  * consent prepare's ({@link segmentCoverageOf} is the shared instrument). One predicate, so a rule that
  * one consumer refuses cannot be a rule another counts: the historically inlined trio of checks
- * (live / tool / scope) is this function, verbatim.
+ * (live / tool / scope) is this function, verbatim — plus the BEHAVIOR conjunct: a mixed table holds
+ * allow, deny and ask rows, and a consumer asking "which allow rules cover this" must not be answered
+ * by a deny row that happens to spell the same text. The behavior is a REQUIRED argument for the same
+ * reason the parser's is: a defaulted allow here is a silent widening.
  */
-export declare function eligiblePersisted(rule: PersistedAllowRule, call: {
+export declare function eligiblePersisted(rule: PersistedRule, call: {
     tool: string;
     cwd: string | undefined;
     sessionId?: string;
-}): boolean;
+}, behavior: RuleBehavior): boolean;
 /**
  * Find the rules that admit this command for a task in `cwd`, or `undefined`.
  *
@@ -611,8 +766,12 @@ export declare function eligiblePersisted(rule: PersistedAllowRule, call: {
  *
  * Order is defined only for reporting (what the decision names); no rule is stronger than another —
  * they are all the same one answer, "the person already said yes to this".
+ *
+ * ALLOW rows only: this is the allow direction's question, and a deny/ask row in the same table is not
+ * coverage (the eligibility predicate's behavior conjunct). The mixed-table walk that orders the three
+ * behaviors is {@link adjudicatePersistedRules}.
  */
-export declare function findAdmittingRule(rules: readonly PersistedAllowRule[], call: {
+export declare function findAdmittingRule(rules: readonly PersistedRule[], call: {
     tool: string;
     command: string;
     cwd: string | undefined;
@@ -622,7 +781,63 @@ export declare function findAdmittingRule(rules: readonly PersistedAllowRule[],
      *  `./x` against the moved cursor, not the task root). Defaults to `cwd`; the scope/eligibility
      *  axis stays `cwd` either way. */
     execCwd?: string;
-}): readonly PersistedAllowRule[] | undefined;
+}): readonly PersistedRule[] | undefined;
+/** The answer of {@link adjudicatePersistedRules}: which behavior decided, and the rule(s) it stands
+ *  on — a one-element set for a deny/ask (the first table-order rule of the deciding behavior that
+ *  reaches the call) and the allow direction's coverage SET ({@link findAdmittingRule}). */
+export interface PersistedRuleVerdict {
+    readonly behavior: RuleBehavior;
+    readonly rules: readonly PersistedRule[];
+    /** The call could not be READ against the person's deny/ask rows (see {@link programRunReachOf}):
+     *  `behavior` is `ask`, `rules` names the first tightening row that could not be judged, and this is
+     *  the lexer's reason. The lane projects it as an UNREADABLE answer — the same fail-closed shape an
+     *  unreadable store takes — never as a matched ask rule. */
+    readonly unreadable?: string;
+}
+/**
+ * The ONE adjudication over a MIXED persisted-rule table for a shell call: walk the behaviors in
+ * {@link RULE_BEHAVIOR_PRECEDENCE} order and answer with the first behavior whose eligible rules speak
+ * for the call — deny before ask before allow, the upstream arbiter's order across its three lists.
+ *
+ * Each behavior is judged with ITS direction's instrument: a deny/ask row through
+ * {@link programRunReachOf} (the wide tightening reading: whole command or any program run in it,
+ * three-valued), an allow through {@link findAdmittingRule} (the narrow reading: the whole call, or
+ * every segment of it, covered by recorded yeses). The asymmetry is the point and runs one way only: a
+ * deny reads MORE of a command than an allow does, so an exact allow naming a whole chain can never
+ * outrun a deny on one of its parts. A call the lexer cannot read against a standing deny/ask row is an
+ * UNREADABLE verdict (`behavior: "ask"` + `unreadable`), returned before any allow is consulted: the
+ * question "does one of my rules forbid this?" is unanswered, and a recorded yes must not answer it.
+ * Eligibility (live, this tool, scope covers the call, THIS behavior) is the one predicate every
+ * consumer shares. `undefined` ⇒ no rule of any behavior speaks.
+ */
+export declare function adjudicatePersistedRules(rules: readonly PersistedRule[], call: {
+    tool: string;
+    command: string;
+    cwd: string | undefined;
+    sessionId?: string;
+    execCwd?: string;
+}): PersistedRuleVerdict | undefined;
+/**
+ * The path-family sibling of {@link adjudicatePersistedRules}: the same precedence walk over the rules
+ * of one path-targeting tool, judged on the call's resolved target path.
+ *
+ * TWO targets, because the two directions read the call's path slot differently (design/388 B6/B17): the
+ * tightening arms judge the PROTECTIVE target (`protectivePathTargetOf` — the object face's declaration,
+ * the catalog's for the name as the floor: reading the catalog for an undeclared same-name tool can only
+ * tighten a deny) with {@link pathRuleReaches}; the allow arm judges the DECLARED target
+ * (`declaredPathTargetOf` — the face's OWN declaration only: a same-name tool that declares no path
+ * target is unconfirmable, and no grant admits it) with {@link directoryRuleAdmits}, and for the Read tool
+ * ONLY — a directory allow is a standing yes to reads, never to a write. Either target may be absent
+ * (no resolvable path in that reading); the arm that needs it then speaks for nothing.
+ */
+export declare function adjudicatePersistedPathRules(rules: readonly PersistedRule[], call: {
+    tool: string;
+    cwd: string | undefined;
+    sessionId?: string;
+}, targets: {
+    readonly tighten?: string;
+    readonly allow?: string;
+}, bases: PathRuleBases): PersistedRuleVerdict | undefined;
 /**
  * design/375 §5.2 — the per-segment coverage table for `command`: which segments an eligible rule
  * already admits, judged with the SAME split and the same eligibility predicates as the gate's
@@ -654,9 +869,9 @@ export declare function findAdmittingRule(rules: readonly PersistedAllowRule[],
  * adjudication inputs.
  */
 export declare function segmentCoverageOf(command: string, rules: {
-    persisted: readonly PersistedAllowRule[];
+    persisted: readonly PersistedRule[];
     proposed?: readonly {
-        rule: ParsedAllowRule;
+        rule: ParsedRule;
         scope: RuleScope;
     }[];
 }, call: {