@sema-agent/core 7.7.0 → 7.9.0

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

@@ -1,11 +1,22 @@
 /**
- * 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.
+ * 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 ruleReachesProgramRun} — whole command or
+ * any segment of a chain, the wider tightening reading). 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
  *
@@ -58,6 +69,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 +123,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 +147,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 +214,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 +252,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 +269,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 +296,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
@@ -391,23 +478,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,7 +535,7 @@ 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?".
  *
@@ -440,7 +550,38 @@ export declare function ruleAdmitsCommand(rule: Pick<PersistedAllowRule, "match"
  * 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.
  */
-export declare function ruleAdmitsProgramRun(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
+export declare function ruleAdmitsProgramRun(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
+/**
+ * Does one TIGHTENING (deny/ask) rule speak about this call — as a whole, or about any single program
+ * run in it? 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: `Bash(npm test)` does not clear
+ * `npm test && curl evil.example`, because nobody said yes to the second half. 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 a segment hit is a hit. 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`) and a commented-out tail
+ * (`echo ok # ; curl evil.example`) are judged as though they ran. Answering "does this definitely
+ * execute" needs evaluation, not parsing; over-firing costs an approval prompt, and the opposite error
+ * costs the rule. Reading the compound as one unmatched blob is what once made `deny Bash(curl:*)`
+ * silent on `npm test && curl evil.example`: a rule standing on paper and matching nothing in fact.
+ *
+ * `ruleAdmitsProgramRun`, not `ruleAdmitsCommand`, on BOTH arms — this direction asks which programs
+ * the call runs, and the matching predicate refuses a quoted operator that is ordinary argument text
+ * (a `&` inside a URL); inheriting that refusal here silenced a deny on the commonest curl spelling.
+ * EVERY segment is judged, including the sole segment of a one-element list: the two readings differ
+ * on terminator handling, so `curl evil.example;` has a single segment `curl evil.example` that the
+ * whole-command arm refuses and this arm must still see (a trailing `;` once carried a chain past the
+ * fence). A command the lane cannot read at all (a redirection, a substitution) has no segments; the
+ * whole-command arm still runs and answers false, as it always did — those shapes are refused upstream.
+ *
+ * A path-family rule (`subpath` / `path`) reaches no command: its predicates are {@link directoryRuleAdmits}
+ * and {@link pathRuleReaches}.
+ */
+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,7 +619,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[];
+export declare function ruleBreadthWarningsOf(rule: Pick<PersistedRule, "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.
@@ -501,8 +642,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 +661,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 +683,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 +695,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 +720,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 +758,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 +773,55 @@ 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 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 ruleReachesProgramRun} (the wide tightening reading: whole command or any program run in
+ * it), 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. 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 +853,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: {