approval-md 0.1.0 → 0.3.0

package/dist/src/cli/policy-apply.d.ts

@@ -0,0 +1,195 @@
+/**
+ * `approval policy apply <proposal.md>` (APRV-343) — apply a proposal
+ * document's quoted replacements to `APPROVAL.md`, then run the amendment.
+ *
+ * ## The hand-ritual this replaces
+ *
+ * Agents may not write `APPROVAL.md`: it is `policy.core`, and this repository's
+ * policy holds that class human-only. So a policy change an agent proposes
+ * travels as a document under `docs/proposals/` that quotes each current line
+ * byte for byte beside its replacement, and the human pastes. On 2026-09-16 the
+ * paste was done by copying a prepared file over `APPROVAL.md` and running
+ * `approval policy amend`. Two things go wrong with that, and both have:
+ *
+ * - **a whole-file copy reverts what it did not know about.** The prepared file
+ *   was written against the policy as it stood when the proposal was drafted,
+ *   so anything landed in between is silently undone. This is the failure
+ *   `base-policy-diverged` catches for the COMMIT, one step too late to help;
+ * - **a paste carries its wrapper.** One paste of a proposal page took the
+ *   page's own fence with it, which hid a block from the loader (APRV-273).
+ *
+ * This verb answers both by construction. It never writes bytes that are not
+ * anchored to bytes already in the live file, and it reads fences by their
+ * backtick run, so a four-backtick wrapper around a three-backtick block is the
+ * wrapper it is rather than part of the content.
+ *
+ * ## The contract, and the three questions APRV-343 left open
+ *
+ * A proposal is markdown. Anywhere in it, a fenced block whose immediately
+ * preceding non-blank line is a LABEL is a member of a pair:
+ *
+ * - `Current:` — the bytes as they stand in the live policy;
+ * - `Replace with:` — what they become;
+ * - `Supersedes:` — optional, and the answer to the first open question.
+ *
+ * **How supersession is declared.** Explicitly, by a third block, and never by
+ * position. A later section that rewrites a line an earlier section already
+ * rewrote quotes the earlier section's RESULT under a `Supersedes:` label, and
+ * the applier looks for that text when the section's own `Current` block is no
+ * longer in the file — which is exactly the state the earlier section left
+ * behind. Position could not carry this: two sections that touch one line are
+ * not in general in the order the file needs, and a rule inferred from order is
+ * a rule nobody can read off the page. A pair whose `Current` AND `Supersedes`
+ * blocks both occur is ambiguous and refuses, because it means the file
+ * contains both spellings and no verb here will pick.
+ *
+ * **Whether a whole-file replacement is accepted.** No, and that is the
+ * decision rather than an omission. The verb's whole value is that every byte it
+ * writes is anchored to a byte it proved present, which is what makes a stale
+ * proposal a refusal instead of a silent revert. A whole-file blob has no
+ * anchor: applying one is a paste with extra steps, and `approval policy amend`
+ * over a hand-edited file is already the supported way to do that deliberately.
+ *
+ * **How the values block is treated.** Identically, and by knowing nothing
+ * about it. The applier is a byte-level replacement over the whole file; it
+ * does not parse the policy, does not locate blocks, and does not care which
+ * fence a pair lands in. The values block is inert (SPEC §11.1 invariant 10),
+ * so applying one changes no verdict, and the attestation the amend appends
+ * covers the whole file's bytes either way (SPEC §5.2, §5.3). A verb that
+ * treated the two blocks differently would be asserting a distinction the file
+ * does not make.
+ *
+ * ## Refuse before writing, always
+ *
+ * Every pair is resolved against an IN-MEMORY copy, in document order, before a
+ * byte reaches the disk. A proposal whose third pair is stale writes nothing at
+ * all, so "a stale proposal cannot half-apply" is a property of the code rather
+ * than of the order somebody wrote the sections in.
+ *
+ * ## It publishes, because one command means one command (APRV-360)
+ *
+ * The amendment runs with `--pr` unless `--no-publish` says otherwise. Before
+ * this, `apply` ran the amend with no flag: the policy was written and
+ * attested, and the operator was handed a printed procedure for getting it onto
+ * main. On 2026-09-18 that procedure opened with `git checkout -b
+ * policy-amend-<seq> origin/main`, the primary's main was fourteen commits
+ * behind, and the switch refused rather than overwrite `QUEUE.md`, the working
+ * log and six payloads. The ceremony stalled with an edited, attested,
+ * unpublished policy, which is the one state in which every gated operation on
+ * the box refuses.
+ *
+ * A verb whose whole value is that the edit and its attestation are ONE act has
+ * no business stopping one step short of the act being visible. `--no-publish`
+ * is the operator who wants it to stop at the commit; `--pr` is accepted and
+ * does nothing, because runbooks already say it.
+ *
+ * ## Human-only
+ *
+ * `approval policy apply` classifies `policy.core` (`core/command-class.ts`),
+ * which this repository's policy holds human-only, so the hook denies an agent
+ * that runs it. The verb ALSO refuses an agent identity itself, with
+ * `apply-agent-actor`: a lock that exists only in the classifier is a lock that
+ * a harness without a hook does not have. It mints no class — `policy.core`
+ * already exists and already covers the policy's own machinery (SPEC §11.1
+ * invariant 9).
+ */
+import type { Streams } from "./main.js";
+/**
+ * Machine-readable refusal codes. Frozen public API, printed in the help.
+ *
+ * Distinct by repair, which is the whole test: `proposal-stale` means the live
+ * file moved and the proposal has to be rewritten against it; `proposal-
+ * ambiguous` means the quoted text is not specific enough and the proposal has
+ * to quote more; `proposal-malformed` means the page is not a proposal yet.
+ *
+ * Two outcomes are deliberately NOT in this union, because neither is this
+ * verb's refusal to make:
+ *
+ * - an operator who answers no at the confirmation gets exit 0 and `aborted:`
+ *   on stdout, exactly as `policy amend` does. Nothing failed, and an error
+ *   object at exit 0 would be a contradiction a caller has to resolve;
+ * - an amendment that refuses has already printed its OWN code, from its own
+ *   frozen union. Wrapping it in a second one would put two error objects on
+ *   one stream and make a caller guess which is the answer. What this verb adds
+ *   is the sentence naming the state that refusal leaves behind.
+ */
+export declare const POLICY_APPLY_REFUSAL_CODES: readonly ["usage", "io", "apply-agent-actor", "proposal-empty", "proposal-malformed", "proposal-stale", "proposal-ambiguous"];
+export type PolicyApplyRefusalCode = (typeof POLICY_APPLY_REFUSAL_CODES)[number];
+/** One fenced block, with the label line that introduced it. */
+interface Fence {
+    /** The non-blank line immediately above the opening fence, trimmed. */
+    label: string;
+    /** The block's content, without either fence line and without a trailing newline. */
+    body: string;
+    /** 1-based line number of the opening fence, for a refusal that has to point. */
+    line: number;
+}
+/**
+ * Every fenced block in `text` that declares a language.
+ *
+ * Two rules, and both are APRV-273:
+ *
+ * 1. **A fence is closed by a run of AT LEAST as many backticks as opened it.**
+ *    That is CommonMark's rule and it is the one that makes a four-backtick
+ *    wrapper work: the inner ```` ```yaml approval-values ```` lines are content,
+ *    not fences, so the block quoted is the block including its own fences.
+ * 2. **An opener with no info string is not a block this verb reads.** The
+ *    incident was a bare fence swallowing a block whose language nobody
+ *    declared; a proposal that wants a block applied says what it is.
+ */
+export declare function fencesOf(text: string): Fence[];
+/** One current/replacement pair, in the order the document states them. */
+export interface ProposalPair {
+    /** The `###` (or `##`) heading this pair sits under, for the diff. */
+    heading: string;
+    current: string;
+    replacement: string;
+    /** The earlier section's result this pair replaces instead, when declared. */
+    supersedes: string | null;
+    /** Line of the `Replace with:` fence, so a refusal can point at the page. */
+    line: number;
+}
+export type ParseResult = {
+    ok: true;
+    pairs: ProposalPair[];
+} | {
+    ok: false;
+    code: PolicyApplyRefusalCode;
+    message: string;
+};
+/**
+ * Read a proposal document into ordered pairs.
+ *
+ * A block whose label names no role is skipped in silence, which is what lets a
+ * proposal page carry a `bash` block of commands to run afterwards without the
+ * applier mistaking it for policy text.
+ */
+export declare function parseProposal(text: string): ParseResult;
+/** What one pair did, once the whole proposal was known to apply. */
+export interface AppliedPair {
+    heading: string;
+    /** The text that was found in the file: the `Current` block, or the superseded one. */
+    matched: string;
+    replacement: string;
+    /** True when the match was the superseded text rather than the pair's own Current. */
+    superseded: boolean;
+}
+export type PlanResult = {
+    ok: true;
+    text: string;
+    applied: AppliedPair[];
+} | {
+    ok: false;
+    code: PolicyApplyRefusalCode;
+    message: string;
+};
+/**
+ * Resolve every pair against an in-memory copy of the policy, in order.
+ *
+ * Nothing here touches the disk, which is what makes the refusals honest: a
+ * proposal is applied whole or not at all, and the caller writes only the text
+ * this function returned.
+ */
+export declare function planApply(live: string, pairs: readonly ProposalPair[]): PlanResult;
+export declare function commandPolicyApply(argv: string[], streams: Streams, cwd: string): number;
+export {};