approval-md 0.0.1 → 0.2.0

package/dist/src/core/policy-match.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Class matching and autonomy resolution (SPEC.md §5.2, §7).
+ *
+ * Given a loaded policy and an action class, decide the autonomy level that
+ * governs the action, and say *why* — which rule matched, which rules were
+ * considered, and whether the irreversibility floor overrode the match.
+ *
+ * This module is pure and deterministic: no I/O, no clock, no randomness, no
+ * caching. The same `(load, actionClass, options)` always yields a deeply equal
+ * `Resolution`. Every ordering decision below is total, so candidate order and
+ * winner selection never depend on object key insertion order beyond what is
+ * explicitly documented.
+ *
+ * ## Matching grammar (SPEC.md §5.2, `schema/policy.schema.json` `classPattern`)
+ *
+ * Patterns and classes are dot-separated segments. Within a pattern:
+ *
+ * - a literal segment matches exactly that segment;
+ * - `*` in a non-final position matches exactly one segment;
+ * - a **trailing** `.*` matches **one or more** remaining segments of any depth.
+ *
+ * The "one or more" is a deliberate choice: `read.*` matches `read.web` and
+ * `read.web.page` but **not** the bare class `read`. The schema's
+ * `classPattern` admits `read` and `read.*` as two distinct keys a policy may
+ * list separately with different autonomy, so they must not be aliases of one
+ * another; and §7 introduces `read.*` as a *namespace*, i.e. the things under
+ * `read`, not `read` itself. A policy that wants the bare class covered writes
+ * it as its own rule (or relies on `defaults.autonomy`).
+ *
+ * A bare `*` pattern is a single-segment pattern whose only segment is a
+ * wildcard, and it is not "trailing `.*`" — it matches any single-segment class
+ * (`read`, `deploy`) and nothing deeper. `*.*` is a wildcard followed by a
+ * trailing wildcard, so it matches any class of TWO OR MORE segments. (APRV-137
+ * corrects this line, which read "exactly two". The trailing `.*` consumes one
+ * or more, so `*.*` matches `a.b` and `a.b.c` alike. `matchesPattern` always
+ * behaved this way; only the comment was wrong.)
+ *
+ * ## Specificity (SPEC.md §5.2, Specificity bullet)
+ *
+ * Candidates are ordered by the two-part key
+ * `(literalSegments DESC, wildcardSegments ASC)`. A trailing `.*` counts as one
+ * wildcard segment and contributes no literals. Patterns still tied are equally
+ * specific, and then "deny beats allow" decides: the strictest autonomy among
+ * the tied rules wins.
+ *
+ * ## Fail-closed
+ *
+ * ## The autonomy split (amended SPEC.md §5.2, APRV-127)
+ *
+ * A rule may declare `supervised-live` (with a `live_rate`) or `supervised-retro`
+ * as well as the pre-split `supervised`. Both collapse onto the one enforced
+ * `supervised` autonomy, and the difference travels beside it as
+ * `Resolution.supervision`: `"live"` means a `live_rate` fraction of the class's
+ * actions stop at the human gate BEFORE executing, `"retro"` means every action
+ * proceeds and a fraction is reviewed AFTERWARDS. Bare `supervised` is `"retro"`,
+ * with a load-time note from `policy-load.ts` naming the alias.
+ *
+ * Nothing about the SELECTION lives here: this module is pure, and selection
+ * needs an operator-held secret. `core/sampler.ts` derives it, and `core/gate.ts`
+ * applies it at intake.
+ *
+ * A not-ok {@link PolicyLoadResult} resolves **every** class to `manual` with
+ * provenance `"fail-closed"` — see `policy-load.ts`. An absent
+ * `defaults.autonomy` is likewise `manual` (provenance `"default"`): the schema
+ * permits omitting `defaults`, and the absence of a grant is not a grant.
+ *
+ * ## `human-only` (amended SPEC.md §5.2, APRV-185)
+ *
+ * A fourth level, and the strictest: an action reserved to human hands, taken
+ * outside agent execution entirely. It resolves like any other level and
+ * nothing here refuses anything — this module is pure — but every enforcement
+ * path downstream refuses it with the code `class-human-only`, so a resolution
+ * carrying it authorizes no request, no decision, no token and no run.
+ *
+ * The fail-closed target stays `manual` and deliberately does not follow the
+ * new head of the strictness table. A policy that cannot be parsed must remain
+ * recoverable through its own gate, and a broken file whose every class became
+ * `human-only` would put the repair behind a level that admits no gated repair.
+ * Failing closed raises the scrutiny an action gets; it does not remove the
+ * path by which a human fixes the file.
+ */
+import type { Autonomy, DeclaredAutonomy, PolicyClassRule, PolicyLoadResult, SupervisionMode } from "./policy-load.js";
+/** Where a {@link Resolution}'s autonomy came from. */
+export type Provenance = 
+/** A `classes` rule matched. */
+"rule"
+/** No rule matched; `defaults.autonomy` (or its absent-means-manual form). */
+ | "default"
+/**
+ * Amended SPEC.md §5.2 (APRV-266): no rule matched a `policy.edit` sub-class,
+ * so the `policy.edit` line itself decided it. Distinct from `"rule"` because
+ * the pattern that decided does not MATCH this class — a reader of the trace
+ * has to be able to see that the class inherited rather than matched — and
+ * distinct from `"default"` because `defaults.autonomy` did not decide it.
+ */
+ | "inherited"
+/** The policy failed to load; everything is `manual`. */
+ | "fail-closed"
+/** The §7 irreversibility floor overrode the resolved autonomy. */
+ | "floor";
+/**
+ * Specificity key: `[literalSegments, wildcardSegments, totalSegments]`.
+ * Ordered on the first two elements only, as literals DESC then wildcards ASC.
+ * `totalSegments` is the sum of the other two, so it can never break a tie they
+ * did not already break; it is carried for the explain trace, which reports it.
+ */
+export type Specificity = [number, number, number];
+/** A rule whose pattern matched the action class, with its specificity key. */
+export interface Candidate {
+    pattern: string;
+    rule: PolicyClassRule;
+    specificity: Specificity;
+}
+/**
+ * Outcome of {@link resolve}.
+ *
+ * `candidates` is every matching rule in descending specificity order, so a
+ * decision trace (APRV-12 `explain`) can be rendered without re-deriving the
+ * match.
+ */
+export interface Resolution {
+    autonomy: Autonomy;
+    /**
+     * Amended SPEC.md §5.2 (APRV-127): what the winning rule (or the default)
+     * actually WROTE, before the split was collapsed onto {@link Autonomy}. A
+     * reader that wants to echo the policy's own word — `explain`, the amendment
+     * differ, a channel's provenance line — uses this; a reader that wants to
+     * know what is enforced uses `autonomy`.
+     */
+    declaredAutonomy: DeclaredAutonomy;
+    /**
+     * `"live"` or `"retro"` when `autonomy` is `supervised`, `null` otherwise.
+     * Bare `supervised` is `"retro"` — see `policy-load.ts`'s alias note.
+     */
+    supervision: SupervisionMode | null;
+    /**
+     * The declared `live_rate` for a `supervised-live` class, else `null`.
+     *
+     * Never `null` for a live class that reached here through the schema, which
+     * requires the key. A live class that somehow carries no usable rate resolves
+     * to `1` rather than to `null`: see {@link supervisionOf} for why the missing
+     * rate is read as "gate all of them".
+     */
+    liveRate: number | null;
+    /**
+     * The declared `retro_rate` for a supervised class, else `null` (amended
+     * SPEC.md §5.2, APRV-183).
+     *
+     * `null` is not "do not sample": it is "this class declared no rate of its
+     * own", and the retrospective sampler reads it as the instruction to fall back
+     * to `audit.supervised_sample_rate`. A rate the schema would have rejected
+     * cannot arrive here, and one that somehow does is read as absent, which puts
+     * the class back on the global rate rather than on a number nobody wrote.
+     */
+    retroRate: number | null;
+    provenance: Provenance;
+    matched: {
+        pattern: string;
+        rule: PolicyClassRule;
+    } | null;
+    approvers: string[] | null;
+    limits: Record<string, number> | null;
+    floorApplied: boolean;
+    /** Whether every equally most-specific rule explicitly permits irreversibility. */
+    allowIrreversible: boolean;
+    /** The maximum-specificity rule group governing that permission. */
+    irreversiblePatterns: string[];
+    candidates: Candidate[];
+}
+/** Options for {@link resolve}. */
+export interface ResolveOptions {
+    /**
+     * Whether the action can be undone. `false` engages the SPEC.md §7
+     * irreversibility floor; `true` and `undefined` do not.
+     */
+    reversible?: boolean;
+}
+/**
+ * Strictness order, strictest first (SPEC.md §5.2 "deny beats allow"), over the
+ * DECLARED vocabulary.
+ *
+ * `supervised-live` sits between `manual` and the retrospective modes because it
+ * is the only supervised mode that can stop an action before it happens: at rate
+ * 1 it is `manual`, at any lower rate it is strictly more scrutiny than review
+ * after the fact. `supervised` and `supervised-retro` share a rank because they
+ * are the same level under two spellings; the lexicographic tie-break in
+ * {@link compareCandidates} then decides between two equally specific rules that
+ * spell it differently, deterministically and without preferring either word.
+ *
+ * Exported because `core/policy-explain.ts` needs the same order to name the
+ * tie-break in its trace, and a private mirror of this table there is exactly
+ * the drift a decision trace must never have from the decision.
+ *
+ * The RATE is not part of the order. A tie between `supervised-live 0.5` and
+ * `supervised-live 0.01` is a tie between two equally specific rules that
+ * disagree about a fraction, and ordering by rate would let a policy author move
+ * a rule's precedence by editing a number they were only tuning. The
+ * lexicographic tie-break settles it, exactly as it settles every other tie.
+ *
+ * APRV-185 puts `human-only` above `manual` at the head of the table, and this
+ * table is the one place the ordering exists: the tie-break below,
+ * `core/policy-explain.ts`'s trace, and `core/agents-md.ts`'s draft merge all
+ * read it and hold no copy. It sits above `manual` because it is strictly more
+ * scrutiny — `manual` says a human decides and an agent then acts, `human-only`
+ * says the human acts — so a tie between the two must resolve to the level that
+ * lets no agent execute.
+ */
+export declare const STRICTNESS: Readonly<Record<DeclaredAutonomy, number>>;
+/**
+ * Collapse a declared level onto the enforced {@link Autonomy} plus its
+ * supervision mode and live rate.
+ *
+ * Pure and total. A `supervised-live` rule whose `live_rate` is absent, or is
+ * not a usable proportion, resolves to **1** — every action in the class is
+ * gated. `policy.schema.json` requires the key, so this branch is unreachable
+ * for a policy that loaded; it is here as the fail-closed backstop, and the
+ * direction is the one the rest of this runtime takes everywhere else. The
+ * alternative reading, "a rate we could not understand means gate none of them",
+ * would turn a typo into a silently disabled control, which is the failure this
+ * project exists to prevent.
+ *
+ * `human-only` (APRV-185) collapses onto itself carrying nothing, exactly as
+ * `manual` and `autonomous` do. It names no supervision because it describes no
+ * agent execution to supervise, and the schema forbids both rates on it, so
+ * there is no fraction here for a reader to misread as live.
+ */
+export declare function supervisionOf(declared: DeclaredAutonomy, rule: PolicyClassRule | null): {
+    autonomy: Autonomy;
+    supervision: SupervisionMode | null;
+    liveRate: number | null;
+    retroRate: number | null;
+};
+/**
+ * The refusal every enforcement path prints for a `human-only` class (APRV-185).
+ *
+ * One text, in one place, for the same reason `STRICTNESS` is one table: the
+ * code `class-human-only` is frozen in four separate unions (`core/gate.ts`,
+ * `core/token.ts`, `core/execute.ts`, and the hook's own), and four hand-written
+ * explanations of one condition would disagree about what a caller should do the
+ * first time one of them was edited.
+ *
+ * `whatWasRefused` is the verb's own half of the sentence, so the message names
+ * the thing that did not happen as well as the reason it cannot.
+ */
+export declare function humanOnlyRefusal(actionClass: string, whatWasRefused: string): string;
+/**
+ * Does `pattern` match `actionClass`?
+ *
+ * See the module header for the grammar. Both are split on `.`; the pattern's
+ * final segment is the only one that may span more than one class segment, and
+ * only when the pattern has more than one segment (a bare `*` is single-span).
+ */
+export declare function matchesPattern(pattern: string, actionClass: string): boolean;
+/**
+ * Specificity key of a pattern (SPEC.md §5.2). A trailing `.*` is one wildcard
+ * segment contributing no literals — which is exactly how it is already counted
+ * by segment splitting, so no special case is needed here.
+ */
+export declare function specificityOf(pattern: string): Specificity;
+/**
+ * Resolve the autonomy governing `actionClass` under `load`.
+ *
+ * 1. A not-ok load resolves `manual` / `"fail-closed"` for every class.
+ * 2. Otherwise collect matching `classes` rules, order them by specificity, and
+ *    take the most specific; among a full specificity tie the strictest
+ *    autonomy wins, and among equally strict tied rules the lexicographically
+ *    smallest pattern is chosen so the outcome is deterministic.
+ * 3. With no matching rule, a class in the `policy.edit.*` namespace (APRV-266)
+ *    inherits the `policy.edit` line when that line is a rule, with provenance
+ *    `"inherited"`; otherwise the result is `defaults.autonomy` — or `manual`
+ *    when `defaults` or `defaults.autonomy` is absent — with provenance
+ *    `"default"`.
+ * 4. Finally, `options.reversible === false` engages the §7 floor: a resolved
+ *    `autonomous` or `supervised` becomes `manual` with `floorApplied: true`
+ *    and provenance `"floor"`. An already-`manual` outcome is untouched, and
+ *    keeps its original provenance, because the floor did not decide it.
+ *
+ * `approvers` and `limits` are carried from the matched rule only; they are
+ * `null` when the rule omits them or when no rule matched.
+ */
+export declare function resolve(load: PolicyLoadResult, actionClass: string, options?: ResolveOptions): Resolution;