approval-md 0.0.1 → 0.2.0

package/dist/src/core/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../../src/core/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAEtD,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAuB,EAAE,GAAW;IACjE,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;AAC/C,CAAC"}

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

@@ -0,0 +1,292 @@
+/**
+ * Semantic policy diff (APRV-30) — what an edit to `APPROVAL.md` actually
+ * *changes about the runtime's answers*, computed by the real engine on both
+ * versions of the file.
+ *
+ * ## Why this module exists: two live incidents
+ *
+ * **seq 2 of this repository's own log.** An amendment was attested and then
+ * superseded eleven minutes later, because the operator attested a policy edit
+ * that broke a pinned dogfood assertion — a fact nobody learned until the test
+ * suite ran, well after the bytes had been signed for. Nothing in the ceremony
+ * had asked "what does this edit change?" before recording "a human saw these
+ * bytes".
+ *
+ * **The unsigned interregnum.** Commit `f829e6c` edited the policy file; its
+ * attestation landed in a later commit. In between, the repository was carrying
+ * an *inoperative* policy: `checkAttestation` reported `hash-mismatch`, and
+ * every gate operation refused. The edit and the attestation were two acts when
+ * they should have been one.
+ *
+ * Both incidents share a shape: the policy edit was treated as a text change
+ * rather than as an amendment with consequences. This module supplies the
+ * missing half of the ceremony — the consequences — and `cli/amend.ts` supplies
+ * the ceremony itself.
+ *
+ * ## What is compared, and how
+ *
+ * Nothing here re-implements matching, specificity, the irreversibility floor,
+ * or defaulting. {@link diffPolicies} calls `resolve()` from
+ * `core/policy-match.ts` on **both** loads for the same probe class, and reports
+ * the pairs that differ. A diff that computed the answer a second way could
+ * disagree with the engine, and the diff would be the more convincing lie.
+ *
+ * Five sections:
+ *
+ * - **classes** — resolution changes (autonomy, provenance, matched pattern)
+ *   over a probe set: every key of either version's `classes` map, plus the
+ *   caller's `sampleClasses` (the CLI passes SPEC.md §7's top-level namespaces).
+ * - **approvers** — approvers added, removed, or whose channel reachability
+ *   changed, plus the class rules left naming an approver the policy no longer
+ *   defines. Losing the only human who can be reached for a class is an
+ *   availability change disguised as a config tweak.
+ * - **defaults** — `autonomy`, `channel`, `approval_ttl`, `on_expiry`.
+ * - **budgets** — every `(scope, limit)` pair, old -> new. Scopes are the
+ *   `budgets` map's keys plus `classes.<pattern>` for a rule's `limits`.
+ * - **vocabulary** — every other key of the policy document, by dotted path,
+ *   before -> after. See below.
+ *
+ * ## The vocabulary section, and the incident that added it (APRV-111)
+ *
+ * On 2026-08-20 a real amendment added `protected_paths: [SPEC.md]` — a key
+ * that decides which file edits are `policy.edit`, which is to say which edits
+ * a human has to approve — and this module reported **"no semantic change"**.
+ * The four sections above were the whole diff, and none of them can see a
+ * top-level key outside `classes` / `approvers` / `defaults` / `budgets`. A
+ * human was shown "nothing changed" while signing bytes that moved the gate.
+ *
+ * The fix is not a fifth hand-written list, because a hand-written list is
+ * exactly what went stale: `protected_paths` was added to the vocabulary by
+ * APRV-107 and nothing here changed. {@link diffPolicies} now walks **both
+ * documents' actual keys**, flattens them to dotted paths, and reports every
+ * pair that differs. New spec keys are covered the day they parse, with no edit
+ * to this file. Paths the dedicated sections already report are dropped, so
+ * nothing is said twice.
+ *
+ * Two consequences worth stating:
+ *
+ * - **Unknown top-level keys are named, never dropped.** `policy.schema.json`
+ *   is closed, so an unrecognised key means the load FAILED and the policy is
+ *   all-manual. That key is reported (marked `recognised: false`) whether or
+ *   not its value changed: the display side fails closed too, and an edit this
+ *   module cannot describe must be called out rather than summarised as no
+ *   change. Which keys are known is READ FROM THAT SCHEMA since APRV-296 (see
+ *   {@link policyTopLevelKeys}), because the hand-written copy that stood here
+ *   fell behind it and warned an operator about three `daemon.*` keys the
+ *   schema had admitted for a month.
+ * - **A side whose YAML never parsed has no vocabulary to read.** Then
+ *   {@link PolicyDiff.vocabularyComparable} is `false` and the renderer says the
+ *   rest of the document was not compared, instead of printing "no semantic
+ *   change" over an unexamined document.
+ *
+ * ## Probes are a report, not a proof
+ *
+ * The class space is infinite; a diff over it cannot be exhaustive. The probe
+ * set is stated in the output ({@link PolicyDiff.probes}) precisely so a reader
+ * knows what was *not* examined. Wildcard keys (`read.*`) are probed as the
+ * literal strings they are, which is the honest thing to do without inventing
+ * action classes that nobody declared: both versions are asked the same
+ * question, so a difference in the answers is a real difference, and a class
+ * outside the probe set may still have changed.
+ *
+ * ## Fail-closed sides are rendered honestly
+ *
+ * A side that fails to load is not "an empty policy". It resolves **every**
+ * class to `manual` with provenance `fail-closed`, and `resolve()` already says
+ * so, so the class section stays truthful with no special case. The structural
+ * sections are different: a failed load has no `approvers`, `defaults` or
+ * `budgets` to read, and reporting them as removed would assert a change the
+ * file never made. So when either side failed, those three sections are empty
+ * and {@link PolicyDiff.structuralComparable} is `false`, with
+ * {@link PolicyDiff.beforeFailure} / {@link PolicyDiff.afterFailure} carrying
+ * the codes a renderer prints as "everything manual (fail-closed: <code>)".
+ *
+ * Deterministic: no clock, no randomness, and probe order is sorted, so the
+ * same two loads always produce a byte-identical diff. The one read of the
+ * filesystem is the policy SCHEMA, once per process, for the key vocabulary
+ * described above; nothing here reads a policy file, and no answer depends on
+ * anything but the two loads it was handed.
+ */
+import type { Autonomy, PolicyLoadErrorCode, PolicyLoadResult } from "./policy-load.js";
+import { type Provenance } from "./policy-match.js";
+/**
+ * SPEC.md §7's reserved top-level namespaces, in table order.
+ *
+ * Exported here rather than in the CLI because they are a fact about the spec's
+ * taxonomy, not about a command's flags, and because a diff that only probed
+ * the classes a policy happens to name would go quiet on exactly the edit that
+ * matters most: one that *stops* naming a dangerous namespace and lets it fall
+ * through to `defaults.autonomy`.
+ */
+export declare const SPEC_NAMESPACES: readonly string[];
+/** One version's answer for one probe class. */
+export interface ResolutionSnapshot {
+    autonomy: Autonomy;
+    provenance: Provenance;
+    /** The pattern that matched, or `null` for a default / fail-closed answer. */
+    pattern: string | null;
+}
+/** A probe class whose resolution differs between the two versions. */
+export interface ClassResolutionChange {
+    /** The probe string that was resolved under both versions. */
+    class: string;
+    before: ResolutionSnapshot;
+    after: ResolutionSnapshot;
+    /** Present whenever the truthful irreversible outcome changed. */
+    irreversible?: {
+        before: ResolutionSnapshot;
+        after: ResolutionSnapshot;
+    };
+}
+/** How an approver entry changed. */
+export type ApproverChangeKind = "added" | "removed" | "channels-changed";
+/** An approver added, removed, or re-channelled. */
+export interface ApproverChange {
+    approver: string;
+    change: ApproverChangeKind;
+    /** Channels before; `null` when the approver did not exist. */
+    beforeChannels: string[] | null;
+    /** Channels after; `null` when the approver no longer exists. */
+    afterChannels: string[] | null;
+    /**
+     * Class patterns in the AFTER policy that still name this approver although
+     * the AFTER `approvers` map no longer defines them — a rule whose decider is
+     * reachable on nothing.
+     *
+     * `policy.schema.json` already forbids an approver with an empty `channels`
+     * list ("an approver reachable nowhere can never grant"), so the only
+     * reachability hole a *loadable* policy can have is this dangling reference:
+     * the schema says explicitly that the rule-to-approver cross-reference is a
+     * runtime check, not a schema constraint. Empty for every other change.
+     */
+    danglingRules: string[];
+}
+/** A `defaults` field whose value changed. `null` means "absent". */
+export interface DefaultsChange {
+    field: "autonomy" | "channel" | "approval_ttl" | "on_expiry";
+    before: string | null;
+    after: string | null;
+}
+/**
+ * A policy key outside the four dedicated sections, before -> after (APRV-111).
+ *
+ * `key` is a dotted path into the policy document (`protected_paths`,
+ * `audit.skew_tolerance`, `channels.telegram.token_env`). Values are rendered
+ * for reading, not for parsing: scalars as themselves, sequences and anything
+ * else as JSON. `null` means the key was absent on that side.
+ */
+export interface VocabularyChange {
+    key: string;
+    /**
+     * Is this path's TOP-LEVEL key part of SPEC.md §5.2's policy vocabulary?
+     *
+     * `false` means the schema does not know the key, which means the policy does
+     * not load, which means every class is `manual`. Reported even when the value
+     * did not change — see the module header.
+     */
+    recognised: boolean;
+    before: string | null;
+    after: string | null;
+}
+/** A budget or class limit whose value changed. `null` means "absent". */
+export interface BudgetChange {
+    /** `budgets` key (e.g. `global`) or `classes.<pattern>` for a rule limit. */
+    scope: string;
+    /** The limit's name, e.g. `daily_usd`, `daily_actions`, `max_usd`. */
+    limit: string;
+    before: number | null;
+    after: number | null;
+}
+/** The result of {@link diffPolicies}. Frozen shape: the CLI prints it as JSON. */
+export interface PolicyDiff {
+    /** Non-null when the BEFORE side failed to load: everything was manual. */
+    beforeFailure: {
+        code: PolicyLoadErrorCode;
+        message: string;
+    } | null;
+    /** Non-null when the AFTER side failed to load: everything becomes manual. */
+    afterFailure: {
+        code: PolicyLoadErrorCode;
+        message: string;
+    } | null;
+    /**
+     * False when either side failed to load, in which case `approvers`,
+     * `defaults` and `budgets` are empty because a failed load has no structure
+     * to compare — not because nothing changed.
+     */
+    structuralComparable: boolean;
+    /** Every probe class that was resolved, sorted; the stated scope of the diff. */
+    probes: string[];
+    classes: ClassResolutionChange[];
+    approvers: ApproverChange[];
+    defaults: DefaultsChange[];
+    budgets: BudgetChange[];
+    /**
+     * Every other key of the document, changed or unrecognised (APRV-111).
+     * Sorted by `key`, so the same two policies always diff byte-identically.
+     */
+    vocabulary: VocabularyChange[];
+    /**
+     * False when a side's document could not be read as a mapping at all (its
+     * YAML did not parse, or the file was missing), in which case `vocabulary` is
+     * empty because there were no keys to walk — not because none changed.
+     */
+    vocabularyComparable: boolean;
+    /** True when no section reported a change. */
+    unchanged: boolean;
+}
+/**
+ * The policy schema on disk, the file `core/validate.ts` validates against.
+ *
+ * Derived here rather than imported from `DEFAULT_SCHEMA_DIR` so this module
+ * keeps its empty runtime dependency graph: importing `validate.ts` would pull
+ * Ajv into every process that renders a diff, the Telegram channel included.
+ * The two derivations are the same walk from the same directory, and
+ * `tests/policy-vocabulary.test.ts` asserts they name one file, so a schema
+ * directory that ever moves fails there rather than drifting quietly.
+ */
+export declare const POLICY_SCHEMA_PATH: string;
+/**
+ * SPEC.md §5.2's top-level policy keys, READ FROM `policy.schema.json`
+ * (APRV-296).
+ *
+ * Used for ONE decision: whether a key the document carries is part of the
+ * vocabulary at all. It is not used to decide what to walk — the documents' own
+ * keys decide that — so this list only ever changes what a key is CALLED in the
+ * report.
+ *
+ * It used to be a second, hand-written copy of the schema's top-level
+ * `properties`, and the 2026-09-07 ceremony is what a hand-written copy costs:
+ * the amend diff printed `daemon.full_reproof_after: 60s -> 60s (UNKNOWN KEY:
+ * … the policy FAILS CLOSED to all-manual until it is removed)` for three
+ * `daemon.*` keys the schema had admitted since APRV-217, which the same
+ * ceremony then loaded cleanly and resolved every pin against. A false
+ * fail-closed warning in a ceremony's output is worse than no warning: it
+ * teaches the operator reading it that the warnings are noise.
+ *
+ * Reading the schema is the fix that cannot go stale, because the schema is
+ * what actually decides whether the key loads. The read is memoised for the
+ * life of the process, which `core/validate.ts` deliberately does not do for
+ * validation: this is DISPLAY vocabulary over a file shipped with the package,
+ * not a verdict, and a schema edited under a running process changes what the
+ * next diff CALLS a key rather than whether that key was validated.
+ */
+export declare function policyTopLevelKeys(): readonly string[];
+/**
+ * Diff two loaded policies by what the engine answers under each.
+ *
+ * `before` and `after` are whole {@link PolicyLoadResult}s, failures included —
+ * see the module header for why a failed side is reported rather than treated
+ * as empty. `sampleClasses` widens the probe set beyond the two policies' own
+ * class keys; the CLI supplies {@link SPEC_NAMESPACES}.
+ */
+export declare function diffPolicies(before: PolicyLoadResult, after: PolicyLoadResult, sampleClasses?: readonly string[]): PolicyDiff;
+/**
+ * Render a {@link PolicyDiff} as the lines the CLI prints.
+ *
+ * Lives beside the diff rather than in the CLI for the same reason
+ * `decisionPath` lives in `policy-explain.ts`: the human rendering and the
+ * machine shape must be derived from one value, or they will eventually
+ * disagree about what changed.
+ */
+export declare function renderDiff(diff: PolicyDiff): string[];