@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/oracle-isolation.d.ts

@@ -1,15 +1,84 @@
+/**
+ * Gate-1 — oracleIsolation (design/77 §1): the CORE SEAM + assertion for the out-of-process grader boundary,
+ * the 4th auto-promote gate. The whole auto-promote tier is **mandate-OFF** (design/77 §5/§7); this file only
+ * makes the seam EXIST so that auto-accept (`fixed`) becomes implementable once the SERVICE supplies the real
+ * isolated grader environment (an E2B/Kata container). SAFE-tier stays `candidate_only` regardless.
+ *
+ * **What core owns vs what the service owns** (mirrors {@link import("./remote-env.js").RemoteExecutionEnv} —
+ * core owns the seam shape; service owns the backend):
+ * - CORE: the {@link GraderEnv} provenance contract, the {@link assertOracleIsolation} assertion (3 fail-closed
+ *   checks), and the {@link OracleIsolationVerdict}.isolationClass tiering that CAPS a non-isolated grader at
+ *   `candidate_only` (never auto-accept).
+ * - SERVICE: the actually-isolated grader env (E2B microVM with `capabilities.isolation === true`), minted by
+ *   the trusted control plane through {@link import("./types.js").RunnerDeps.graderEnvFactory}.
+ *
+ * 🔴 **Honest residual (design/77 §1 Residual + §9):** the bash write-probe is point-in-time and
+ * necessary-not-sufficient — core, running *inside the worker*, cannot prove a mount is truly immutable (it
+ * only observes that one write failed once; a candidate can `mount -o remount,rw` after the probe). And
+ * `capabilities.isolation` is self-declared by the adapter (a lying adapter can claim `true`). The REAL
+ * protection is the OUT-OF-PROCESS structural boundary (check B) on a control-plane-provisioned adapter — which
+ * is exactly why auto-promote stays mandate-OFF until the deployment contract is verified end-to-end (Slice-3).
+ */
 import type { ExecutionEnv } from "../internal/harness-types.js";
+/**
+ * The verdict of {@link assertOracleIsolation}. `protected` is the fail-closed AND of all three checks
+ * (identity ∧ structural-class-acceptable ∧ write-probe). `isolationClass` is the load-bearing tiering that the
+ * (OFF) auto-accept path consults:
+ * - `"out_of_process"` — the grader is a real isolated sandbox (a remote env with `capabilities.isolation ===
+ *   true`). ONLY this class is eligible for auto-accept (still mandate-OFF).
+ * - `"in_process_probe_only"` — the grader is non-remote or non-isolated; the bash write-probe is the only
+ *   signal and it is necessary-not-sufficient → this CAPS the run at `candidate_only`, NEVER auto-accept (the
+ *   2-of-3 asymmetry, design/77 §1/§6: the oracle axis's real protection is the out-of-process boundary).
+ */
 export interface OracleIsolationVerdict {
     protected: boolean;
     isolationClass: "out_of_process" | "in_process_probe_only";
+    /** Set when `protected:false` (or when the class is downgraded) — the fail-closed reason, for observability. */
     reason?: string;
 }
+/**
+ * The isolated grader environment, provisioned by the trusted control plane. `provenance` is settable ONLY at
+ * the {@link import("./types.js").RunnerDeps.graderEnvFactory} call site — it is NEVER reconstructed from
+ * worker-visible state (a worker that could mint a `{provenance:'control_plane'}` object would defeat the whole
+ * gate). `immutableOraclePaths` are the paths the oracle/spec is supposed to live behind (e.g. a hidden held-out
+ * test dir) that the worker must not be able to corrupt; the bash write-probe (check C) targets them.
+ */
 export interface GraderEnv {
+    /** The isolated env the oracle grades in (service-provisioned; a {@link import("./remote-env.js").RemoteExecutionEnv} in production). */
     env: ExecutionEnv;
+    /** Paths the oracle must be protected behind — probed for writability through the WORKER's bash bypass surface. */
     immutableOraclePaths: string[];
+    /** Provenance brand — ONLY the control-plane factory sets this. Never derived from worker state. */
     provenance: "control_plane";
 }
+/** Options for {@link assertOracleIsolation}. */
 export interface AssertOracleIsolationOptions {
+    /** Abort the write-probe(s); an abort/timeout during the probe is fail-closed (protected:false). */
     signal?: AbortSignal;
 }
+/**
+ * Assert that the grader env is isolated from the worker env so a positive oracle verdict is trustworthy
+ * (design/77 §1, the 4th auto-promote gate). THREE fail-closed checks — ANY failure ⇒ `protected:false`:
+ *
+ * **(A) IDENTITY** — `grader.env !== workerEnv` (reference inequality); when BOTH are remote envs, also require
+ * distinct `workspaceHandle().sandboxId`. A grader that IS the worker env (or the same sandbox) is grading in
+ * the very env the worker can corrupt.
+ *
+ * **(B) STRUCTURAL CLASS (the real protection)** — when `grader.env` is a {@link import("./remote-env.js").RemoteExecutionEnv}
+ * with `capabilities.isolation === true` ({@link isIsolated}, fail-closed default false) → `isolationClass =
+ * "out_of_process"` (the only class the OFF auto-accept path may consider). A non-remote / non-isolated grader →
+ * `"in_process_probe_only"`, which CAPS the run at `candidate_only` — never auto-accept. Note: a non-isolated
+ * grader is NOT itself a `protected:false` (the probe can still pass and the run can still be a legitimate
+ * `candidate_only`); the class is what gates auto-accept (the 2-of-3 asymmetry).
+ *
+ * **(C) BASH WRITE-PROBE (necessary-not-sufficient, cheap early signal)** — for each `immutableOraclePath`, run
+ * a write probe through the WORKER env's `exec` (the bash bypass surface — see {@link probeCommand}), against
+ * the path canonicalized via {@link canonicalizeTarget}. The probe PASSES only if the write returns a non-zero
+ * exit code or an exec error (read-only mount / permission denied / not supported). Any SUCCESS (RC 0) ⇒ the
+ * oracle dir is writable from the worker ⇒ `protected:false`. A probe THROW / abort / timeout ⇒ fail-closed
+ * (`protected:false`).
+ *
+ * The verdict is fail-closed: the function itself never throws — a thrown probe is caught and mapped to
+ * `protected:false` (so a flaky env can't turn into a silent pass).
+ */
 export declare function assertOracleIsolation(workerEnv: ExecutionEnv, grader: GraderEnv, opts?: AssertOracleIsolationOptions): Promise<OracleIsolationVerdict>;

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

@@ -1,10 +1,42 @@
+/**
+ * design/179 §4/§7/§13 — the ONE consent protocol every rule takes to enter the store through the engine.
+ *
+ * Single card, settings import and starter batch all reduce to the same three steps:
+ *
+ *   durable approval record (pending)  →  authenticated confirmation transfer (approved)  →  principal-bound redemption (redeemed)
+ *
+ * and only the third step reaches the core-private writer. A host holding a record id cannot redeem it
+ * while it is pending, cannot redeem another principal's record, and cannot redeem free text — the
+ * redemption face takes a ticket and nothing else, so there is no field to write a rule of one's own into.
+ *
+ * The record is DURABLE, not an in-memory ticket: a safety ask can park, and the approval that redeems it
+ * may arrive in another process at another time. An in-memory ticket loses exactly that case.
+ *
+ * ## Crash order, and why replay is safe
+ *
+ * The record moves to `redeemed` — carrying the dot it minted — BEFORE the writer applies. A crash in
+ * between leaves a redeemed record whose rule is not in the store; replaying the redemption re-applies the
+ * SAME delta with the SAME dot, which the store folds idempotently. One redemption mints exactly one dot,
+ * for as many replays as it takes. Deliberately re-adding a deleted rule is a different act: a new ask, a
+ * new record, a new dot.
+ *
+ * ## The boundary this does NOT claim
+ *
+ * The confirmation transfer is an in-process call. A deployment must reach it only from its authenticated
+ * approval channel, and a deployment that shares filesystem credentials with the user can bypass all of
+ * this by editing a file backend's file. That is the settings-file trust model, stated rather than
+ * defended against: for a file backend, host = user, no more and no less.
+ */
 import { type RuleScope, type RuleDot } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider } from "./permission-rule-store.js";
+/** One candidate rule inside an approval record: the exact text and where it would apply. */
 export interface RuleCandidate {
     rule: string;
     scope: RuleScope;
 }
+/** What the approval record is for — it decides the provenance the minted adds carry. */
 export type RuleApprovalKind = "card" | "import" | "starter";
+/** A durable record of one pending/settled human decision about minting rules. */
 export interface RuleApprovalRecord {
     id: string;
     principal: string;
@@ -12,38 +44,89 @@ export interface RuleApprovalRecord {
     state: "pending" | "approved" | "redeemed";
     candidates: RuleCandidate[];
     createdAt: string;
+    /** The ask this record was drawn from, for reconciliation. Advisory metadata; never adjudication input. */
     toolCallId?: string;
     boundInputHash?: string;
+    /** Monotonic revision of THIS record, bumped by every accepted transition. The compare-and-set key:
+     *  comparing state alone cannot separate two different writes that both leave the state unchanged. */
     rev: number;
+    /**
+     * Which candidate the person actually chose, recorded by the confirmation transfer.
+     *
+     * A card offers alternatives — the exact command and, sometimes, a broader prefix — and a human picks
+     * ONE. Without this, confirming the card would authorize every option on it: a host could redeem the
+     * exact ticket, then later redeem the wider prefix ticket, and the second rule would exist without
+     * anyone ever having agreed to it. Absent on batch records, where the confirmation is over the whole
+     * previewed list by construction.
+     */
     selectedCandidate?: number;
+    /** Dots already minted for this record, keyed by candidate index — the replay anchor. */
     redeemedDots?: Record<number, RuleDot>;
 }
+/**
+ * The durable home of approval records. A separate record type on purpose: it is not a checkpoint row and
+ * must not evolve with one.
+ */
 export interface RuleApprovalRecordStore {
     get(id: string): Promise<RuleApprovalRecord | undefined>;
+    /**
+     * Compare-and-set on the record's REVISION, not on its state.
+     *
+     * State alone is not a compare-and-set key: a batch's second candidate transitions redeemed → redeemed,
+     * so two concurrent retries would both find the state they expected, both mint a dot, and both write —
+     * one silently overwriting the other's `redeemedDots`, which is how one approval becomes two adds and a
+     * deleted rule comes back to life. `next.rev` must be `expectRev + 1`.
+     */
     cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
     create(record: RuleApprovalRecord): Promise<void>;
 }
+/** Everything the consent lane needs wired. */
 export interface RuleConsentDeps {
     provider: PermissionRuleStoreProvider;
     approvals: RuleApprovalRecordStore;
+    /** Injectable clock/id for deterministic tests; defaults are the real ones. */
     now?: () => Date;
     newId?: () => string;
 }
+/** In-memory approval records — the test backend and the reference CAS semantics. */
 export declare class InMemoryRuleApprovalRecordStore implements RuleApprovalRecordStore {
     private readonly rows;
     get(id: string): Promise<RuleApprovalRecord | undefined>;
     create(record: RuleApprovalRecord): Promise<void>;
     cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
+    /** Test/inspection helper — how many records exist. The principal negative pins read this. */
     size(): number;
 }
+/** An opaque, single-purpose redemption ticket. Its only content is which record and which candidate. */
 export type RuleTicket = string;
 export declare function mintRuleTicket(recordId: string, candidateIndex: number): RuleTicket;
+/**
+ * Create the pending record behind ONE approval card, and the tickets its options would redeem.
+ *
+ * The candidates are DERIVED here, from the call, by the same function that produced the options shown on
+ * the card — they are not an argument. That is the difference between the stated invariant and a wish:
+ * while this took a candidate list, a surface could display an approval for `git status` and build a
+ * record containing `Bash(rm:*)`, and every later step would faithfully honor the record. There is now no
+ * field in which to write a rule of one's own, on this entry as on the redemption entry.
+ *
+ * `toolCallId` and `boundInputHash` are recorded so an auditor can tie the record back to the exact ask,
+ * and a command the lane cannot speak for yields no record and no tickets at all.
+ *
+ * What this does NOT claim: that the command named here is the command that was displayed. A surface that
+ * shows one thing and says another is the same-layer trust §5 already states plainly — in an in-process
+ * deployment the host IS the user. What it closes is the gap where the rule TEXT never came from the
+ * engine at all.
+ */
 export declare function prepareCardApproval(opts: {
     principal: string;
+    /** The tool whose ask this card belongs to. Only the shell tool the rule lane speaks for is accepted. */
     toolName: string;
+    /** The command as adjudicated — the same bytes the ask carried. */
     command: string;
+    /** The ask's call id and argument digest, recorded for reconciliation. */
     toolCallId?: string;
     boundInputHash?: string;
+    /** Where a redeemed rule would apply. Defaults to global. */
     scope?: RuleScope;
     deps: RuleConsentDeps;
 }): Promise<{
@@ -51,19 +134,34 @@ export declare function prepareCardApproval(opts: {
     tickets: RuleTicket[];
     candidates: RuleCandidate[];
 } | undefined>;
+/**
+ * The authenticated confirmation transfer: pending → approved.
+ *
+ * A deployment must reach this ONLY from the channel that actually carries a human decision — the same
+ * channel an approval card's yes travels. Nothing below this line can tell an authentic confirmation from
+ * a fabricated one, which is why the boundary is stated here rather than checked here.
+ */
 export declare function confirmRuleApproval(opts: {
     approvalId: string;
     principal: string;
+    /**
+     * REQUIRED for a card record: the index of the option the person chose. A card presents alternatives of
+     * different breadth, so "they said yes" is not an answer on its own — "they said yes to THIS one" is.
+     * Rejected on a batch record, whose confirmation covers the previewed list by construction.
+     */
     selectedCandidate?: number;
     deps: RuleConsentDeps;
 }): Promise<ConfirmResult>;
+/** Why a confirmation did not land. A closed set so a host can branch (re-present, re-fetch, give up). */
 export type ConfirmRefusalReason = "record_not_found" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "batch_takes_no_selection" | "not_pending" | "conflict";
+/** The confirmation outcome: landed, or refused with a named reason. */
 export type ConfirmResult = {
     ok: true;
 } | {
     ok: false;
     reason: ConfirmRefusalReason;
 };
+/** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule. */
 export type RedeemResult = {
     status: "redeemed";
     rule: string;
@@ -75,18 +173,35 @@ export type RedeemResult = {
     status: "refused";
     reason: string;
 };
+/**
+ * Redeem one ticket into one persisted rule.
+ *
+ * Takes a ticket and a verified principal, and nothing else. There is deliberately no field carrying rule
+ * text: what gets persisted is what the engine put in the record when it drew the card, so a host cannot
+ * turn a click on `git status` into a rule for something else.
+ */
 export declare function redeemRuleTicket(opts: {
     ticket: RuleTicket;
     principal: string;
     deps: RuleConsentDeps;
 }): Promise<RedeemResult>;
+/** The three user-editable settings layers this version reads. */
 export type ImportedSettingsLayer = "userSettings" | "projectSettings" | "localSettings";
+/** One layer to read. `root` is the canonical directory a project-layer rule is scoped to — taken from
+ *  where the FILE actually lives, since the local layer is not always at a repository root. */
 export interface CcImportLayer {
     layer: ImportedSettingsLayer;
     path: string;
     root: string;
     readFile: (path: string) => Promise<string | undefined>;
 }
+/**
+ * What the import WOULD do, shown before anyone confirms.
+ *
+ * `uncovered` is a two-key record, not a list: the two layers this version does not read are named in the
+ * TYPE, so an empty list, a missing member or a duplicate is not expressible. A preview that reported only
+ * the layers it read would be claiming completeness it does not have.
+ */
 export interface ImportPreview {
     candidates: RuleCandidate[];
     skipped: Array<{
@@ -103,6 +218,8 @@ export interface ImportPreview {
         policySettings: "not-imported-v1";
     };
 }
+/** What the import ACTUALLY did — a different moment and a different contract from the preview, because
+ *  dedup, concurrency and redemption-time validation can all move an entry between the two. */
 export interface ImportResult {
     persisted: RuleCandidate[];
     deduped: RuleCandidate[];
@@ -112,6 +229,13 @@ export interface ImportResult {
     }>;
     rev: number;
 }
+/**
+ * Read the allow buckets of the user-editable settings layers and produce a preview plus a PENDING
+ * approval record. Nothing is stored until someone confirms that record and the batch is redeemed.
+ *
+ * Only the allow bucket is read. The deny/ask buckets are the tightening direction and have their own
+ * channel; importing them through a loosening lane would be the wrong door.
+ */
 export declare function prepareCcImport(opts: {
     layers: CcImportLayer[];
     principal: string;
@@ -120,7 +244,17 @@ export declare function prepareCcImport(opts: {
     preview: ImportPreview;
     approvalId: string;
 }>;
+/**
+ * The factory-reviewed starter set, offered when there is nothing to import.
+ *
+ * Every entry is an EXACT read-only command whose behavior does not depend on repository or environment
+ * configuration. The version-control family is deliberately absent: repository configuration can make a
+ * subcommand invoke an external helper, which is the same reason this repository already declined a
+ * subcommand allowlist for it. Nothing here takes effect until someone confirms the batch.
+ */
 export declare const STARTER_RULES: readonly string[];
+/** Prepare the starter batch as a pending approval record. Nothing takes effect without confirmation;
+ *  an unconfirmed deployment simply starts with an empty rule set. */
 export declare function prepareStarterBatch(opts: {
     principal: string;
     deps: RuleConsentDeps;
@@ -128,6 +262,10 @@ export declare function prepareStarterBatch(opts: {
     preview: RuleCandidate[];
     approvalId: string;
 }>;
+/**
+ * Redeem an approved BATCH record (import or starter) — every candidate, one dot each, reporting what
+ * actually landed rather than what was previewed.
+ */
 export declare function redeemRuleBatch(opts: {
     approvalId: string;
     principal: string;

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

@@ -1,66 +1,188 @@
+/**
+ * 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: only a single simple command can ever be matched
+ *
+ * Everything a shell can use to run a SECOND program behind an admitted first one — operators,
+ * substitution, subshells, backgrounding, and **redirection** — puts the command outside this lane
+ * entirely: it falls back to the pre-existing chain and asks. That includes redirection specifically,
+ * which is a deliberate registered divergence from upstream (upstream strips redirections before
+ * matching; with this repo's write gate not covering the shell tool, stripping would turn a rule as
+ * innocuous as `Bash(ls)` into a licence for `ls > ~/.ssh/authorized_keys`).
+ *
+ * The floor is `parseLeadingCommandName` — the one simple-command parser already shared by 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 bypass rather
+ * than as a test failure.
+ *
+ * ## Normalization order is load-bearing
+ *
+ * Whitespace folding runs AFTER the shell-construct rejection, never before: folding first would
+ * swallow a newline and glue two commands into one string that then reads as a single simple command.
+ * Only space/tab runs fold; there is no case folding, no alias expansion (no shell alias view exists
+ * 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.
+ */
+/** The one tool the v1 rule lane speaks for. The field exists on the rule so v2 can widen without a shape change. */
 export type PersistedRuleTool = "Bash";
+/** v1 match forms. `"wildcard"` is reserved for v2 and is not a value this version ever produces. */
 export type PersistedRuleMatch = "exact" | "prefix";
+/**
+ * Where a rule applies. A rule read out of a project-local settings layer applies ONLY inside that
+ * project's canonical root — project A's approval is not project B's. User-layer, starter and
+ * user-minted rules are global.
+ *
+ * `root` is expected to be already canonicalized (realpath) by whoever constructs the scope; the
+ * matcher compares with word-boundary containment, never a bare `startsWith` (`/a` must not reach `/ab`).
+ */
 export type RuleScope = {
     kind: "global";
 } | {
     kind: "project";
     root: string;
 };
+/** The immutable causal identity of one add: a replica identity plus a monotonic counter. */
 export interface RuleDot {
     actor: string;
     counter: number;
 }
+/** Where one add came from. Stored PER ADD — never folded across dots (a folded provenance cannot
+ *  follow a dot that is later deleted on its own). */
 export type RuleAddOrigin = "user" | "imported-cc" | "starter";
+/** One add of one logical rule, carrying its own dot and its own provenance. */
 export interface RuleAdd {
     dot: RuleDot;
     origin: RuleAddOrigin;
     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.
+ */
 export interface PersistedAllowRule {
+    /** Canonical rule text: `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). */
     rule: string;
     tool: PersistedRuleTool;
     match: PersistedRuleMatch;
+    /** What the matcher compares against — parsed out of `rule`, stored so no consumer re-parses. */
     command: string;
     scope: RuleScope;
     adds: RuleAdd[];
 }
+/**
+ * A delete intent, in observed-remove form: it carries EVERY add dot for its (rule, scope) that was
+ * visible to the deleting replica at delete time. A single-dot tombstone cannot delete cleanly —
+ * concurrent replicas add the same rule text under different dots, and a tombstone that names only one
+ * of them lets the deleted rule come back. The merge criterion is dot IDENTITY, not a causal-order
+ * comparison (single dots across replicas have no order to compare): an add is live iff its dot appears
+ * in no tombstone for the same (rule, scope).
+ */
 export interface RuleTombstone {
     rule: string;
     scope: RuleScope;
     removedDots: RuleDot[];
+    /** The delete operation's own dot — the operation's persistent identity. */
     deletedBy: RuleDot;
 }
+/** Why a rule text was refused. Codes are stable so an import report can group by them. */
 export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "invalid.not_simple_command" | "invalid.bare_interpreter_prefix" | "invalid.unbalanced_quotes" | "invalid.too_long" | "unsupported.tool" | "unsupported.wildcard";
 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 {
     rule: string;
     tool: PersistedRuleTool;
     match: PersistedRuleMatch;
     command: string;
 }
+/** Upper bound on a rule text. Rules are human-authored one-liners; anything longer is a mistake or an
+ *  attempt to make the store unreadable. */
 export declare const MAX_RULE_TEXT_CHARS = 512;
+/**
+ * Interpreter names whose PREFIX form is refused everywhere a rule can enter the store (minting,
+ * import, file reload, every backend). `Bash(node:*)` reads as one narrow-looking rule and means "run
+ * any program you like" — that is not a shape a single click can be understood to have authorized.
+ *
+ * The check is on argv[0] of the prefix, not on the prefix being exactly one word: `node -e:*` is the
+ * same licence spelled longer. Deliberately strict-side — it costs the ability to persist a rule like
+ * `python manage.py migrate:*` (which an import reports as skipped rather than dropping silently), and
+ * an EXACT rule naming a whole interpreter command line stays legal, since it authorizes one command.
+ */
 export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
+/**
+ * Parse one rule text into its canonical shape, or refuse it with a reason.
+ *
+ * This is the ONE validator every entry point shares — minting a suggestion, importing another
+ * product's settings, reloading a store file, and any future backend. A shape refused here cannot enter
+ * the store through any door.
+ */
 export declare function parseAllowRuleText(text: string): {
     rule: ParsedAllowRule;
 } | {
     reject: RuleReject;
 };
+/** The canonical spelling of a rule for a (already folded) command and match form. */
 export declare function formatAllowRuleText(command: string, match: PersistedRuleMatch): string;
+/**
+ * Does this rule's command pattern admit `command`?
+ *
+ * `command` is the raw tool argument: the floor and the folding happen HERE, in that order, so no
+ * caller can accidentally match a folded compound. Returns false for anything that is not a single
+ * simple command — including every redirection form.
+ */
 export declare function ruleAdmitsCommand(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
+/**
+ * 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.
+ */
 export declare function pathWithinRoot(path: string, root: string): boolean;
+/** Does a rule's scope cover a task running in `cwd`? A project rule needs a cwd to compare against;
+ *  without one it covers nothing (fail-closed). */
 export declare function scopeCoversCwd(scope: RuleScope, cwd: string | undefined): 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;
+/**
+ * Find the rule that admits this command for a task in `cwd`, or `undefined`.
+ *
+ * Order is defined only for reporting (the first match wins and its text is what the decision names);
+ * no rule is stronger than another — they are all the same one answer, "the person already said yes to
+ * this".
+ */
 export declare function findAdmittingRule(rules: readonly PersistedAllowRule[], call: {
     tool: string;
     command: string;
     cwd: string | undefined;
 }): PersistedAllowRule | undefined;
+/** A rule the engine offers to mint, as carried on an approval card. */
 export interface RuleSuggestion {
+    /** The canonical rule text the host would redeem. */
     rule: string;
     match: PersistedRuleMatch;
+    /** The command pattern in the rule, for a host that wants to render it without re-parsing. */
     command: string;
 }
+/**
+ * The 1-2 candidates offered on an approval card for `command`.
+ *
+ * The exact form (this whole command line) is always offered when the command is matchable at all. A
+ * prefix form is offered only when it is a shape a person can read as narrow: the upstream multi-word
+ * convention (`git status`, `npm run`) is preferred over a bare program name, and no prefix at all is
+ * offered for an interpreter head — that candidate would be refused by the validator anyway, and
+ * offering a candidate the store will not accept is worse than offering one fewer.
+ *
+ * Returns an empty array for anything the rule lane cannot speak for (compounds, redirections,
+ * substitutions) — the card then simply carries no "don't ask again" option, which is the honest answer.
+ */
 export declare function suggestRulesForCommand(command: string): RuleSuggestion[];