approval-md 0.1.0 → 0.2.0

package/dist/src/cli/args.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hand-rolled argv parsing. Zero dependencies, by policy: an argument parser is
+ * a hundred lines of well-understood string handling, and a CLI that gates
+ * side effects should not widen its supply chain to save them.
+ *
+ * Accepted forms: `--flag value`, `--flag=value`, `-n value`, `-n=value`, and
+ * bare boolean flags. Anything else — an unknown flag, a flag missing its
+ * value, a non-integer count — is a usage error, never a guess. Fail closed
+ * applies to argument handling too: a CLI that quietly reinterprets a typo is a
+ * CLI that eventually reindexes the wrong file.
+ */
+/** A flag's expected shape. */
+export type FlagKind = "string" | "boolean";
+export type ParsedFlags = Record<string, string | boolean>;
+export type ParseResult = {
+    ok: true;
+    flags: ParsedFlags;
+    positionals: string[];
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Parse `argv` against a closed spec of flags. Unknown flags fail rather than
+ * landing in `positionals`, so a mistyped `--jsno` can never be silently
+ * swallowed as a path.
+ */
+export declare function parseFlags(argv: string[], spec: Record<string, FlagKind>): ParseResult;
+/** Read a string flag, or `null` when absent. */
+export declare function stringFlag(flags: ParsedFlags, name: string): string | null;
+/** Read a boolean flag. */
+export declare function boolFlag(flags: ParsedFlags, name: string): boolean;
+/**
+ * A non-negative integer flag value. `0` is legal and means "no records" —
+ * an explicit request for nothing is not an error.
+ */
+export declare function countFlag(flags: ParsedFlags, name: string): {
+    ok: true;
+    value: number | null;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/src/cli/attest.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `approval policy attest` (SPEC.md §5.2) — the human-only verb that makes the
+ * live policy file operative.
+ *
+ * As everywhere else in this CLI, the logic is not here: hashing, the actor
+ * rule, and the append live in `core/attest.ts`, and the append itself goes
+ * through `core/log.ts`. This file resolves paths and identity, decides an exit
+ * code, and formats output.
+ *
+ * Three choices are load-bearing enough to state plainly.
+ *
+ * **Bytes, not parse.** Attestation hashes the file and does not require the
+ * policy to load. A human may deliberately attest a file the engine rejects —
+ * and should be able to, because the alternative is a runtime that refuses to
+ * record what is actually on disk. A schema-invalid policy still fails closed
+ * everywhere it matters (`loadPolicy` answers manual-everything); attesting it
+ * changes nothing about that. What attestation records is "a human saw these
+ * bytes", not "these bytes are good".
+ *
+ * **Identity is declared, not proved.** `--as human:<id>`, else
+ * `APPROVAL_HUMAN`. The trust boundary is the local machine. This is stated in
+ * the help text rather than hidden, because a reader who believes attestation
+ * authenticates anyone would be wrong in a way that matters.
+ *
+ * **An agent actor is a usage error, not an I/O one.** `--as agent:x` is
+ * refused at exit 2 with the rule quoted. `core/attest.ts` refuses it again
+ * independently; the duplication is deliberate, since the core rule must hold
+ * for every caller and not only for this one.
+ *
+ * **`--organ <path>` attests a gate ORGAN instead (APRV-272)**, and appends a
+ * different event (`gate.organ.attested`, never `policy.updated`) for a
+ * different reason: the organs are `policy.core`, the gate mints nothing for a
+ * human-only class, so a hand edit to one can have no grant and the
+ * protected-path guard has no other evidence to accept. The three properties
+ * above hold there too — bytes not parse, declared identity, an agent actor
+ * refused at exit 2 — and two refusals are added, both usage errors, for a path
+ * that is the policy file and for a path that is not an organ at all.
+ */
+import type { Streams } from "./main.js";
+/** `approval policy attest …` — hash the live policy file and log the human's sign-off. */
+export declare function commandPolicyAttest(argv: string[], streams: Streams, cwd: string): number;

package/dist/src/cli/audit-card.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The retrospective review card, built from the log (SPEC.md §5.2, §9.1, §10.3;
+ * APRV-299).
+ *
+ * The daemon draws `audit.sampled` records and, until this task, the only place
+ * to answer one was `approval audit list` / `approval audit review` in a
+ * terminal. The supervised bargain is "execute now, a fraction is reviewed
+ * after", and a review nobody is shown is a review that does not happen: on
+ * 2026-09-07 sixty of them were sitting in `QUEUE.md` while the approver's
+ * phone showed nothing.
+ *
+ * This module turns each open sample into a {@link ReviewCard} the Telegram
+ * channel renders. Three properties are the whole of its contract:
+ *
+ * - **Everything is derived, nothing is self-reported.** The class comes from
+ *   the `task.registered` declaration the log already holds, the command
+ *   breakdown is recomputed by the classifier's own tokenizer over the bytes
+ *   the payload store holds under the hash the `execution.started` recorded,
+ *   the rate is the one the `audit.sampled` record states, and the claimed
+ *   summary carries the actor that registered the action. No payload key an
+ *   authoring party wrote chooses a row (SPEC.md §11.1 invariant 4).
+ * - **It reads only verified records** (invariant 1). A log that does not
+ *   verify produces a refusal and no cards: a card is a statement to a human
+ *   about what the log says, and one derived from a log the runtime disowns
+ *   would be worse than no card at all.
+ * - **It decides nothing and appends nothing.** No policy is resolved, no
+ *   reaction is read, and no enforcement path consults anything here
+ *   (invariant 10). The card is a rendering; the human's answer goes back
+ *   through the human-only `reviewSample`.
+ */
+import type { ReviewCard } from "../channels/telegram.js";
+/** Why a build of the review backlog produced nothing. */
+export type ReviewCardRefusalCode = "log-unreadable" | "log-torn-tail" | "log-corrupt";
+export type ReviewCardsResult = {
+    ok: true;
+    cards: ReviewCard[];
+} | {
+    ok: false;
+    code: ReviewCardRefusalCode;
+    message: string;
+};
+/** Where the payload bytes may be found, for the command breakdown. */
+export interface ReviewCardOptions {
+    /**
+     * A caller's override for the payload store, with `TagOptions.payload`'s
+     * semantics: action key and bound hash in, the value or `undefined` out.
+     * Consulted before the store, exactly as the pending queue consults it, so a
+     * test and an operator holding bytes elsewhere reach the same rendering.
+     */
+    payload?: (actionKey: string, payloadHash: string) => unknown;
+    /** The payload store, or `null` for none. Defaults to the one beside the log. */
+    payloadStoreDir?: string | null;
+}
+/**
+ * Every `audit.sampled` with no later `audit.reviewed`, as review cards, oldest
+ * first.
+ *
+ * The same projection `approval audit list` and `.approval/QUEUE.md` read
+ * (`openSamples`), so the phone, the file and the terminal cannot disagree
+ * about what is outstanding. Reads a verified log and writes nothing anywhere.
+ */
+export declare function openReviewCards(logPath: string, options?: ReviewCardOptions): ReviewCardsResult;

package/dist/src/cli/audit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `approval audit` — the retrospective-review verbs (SPEC.md §5.2, §9.1).
+ *
+ * Two subcommands, and neither of them samples:
+ *
+ * - `audit list` reads the open sampled-audit backlog and writes nothing;
+ * - `audit review <seq|action-key>` appends `audit.reviewed` and is HUMAN-ONLY.
+ *
+ * There is deliberately no `approval audit sample`. Sampling is the runtime's
+ * decision, made by the daemon from an operator-held secret, and a verb that let
+ * a caller sample (or decline to sample) an action of its choosing would hand
+ * the party under oversight the control that exists to oversee it. The daemon
+ * samples on its tick; that is the only path.
+ *
+ * The CLI holds no logic, as everywhere else here: eligibility, matching, and
+ * the human-only rule live in `core/audit.ts`, and this file is argument
+ * parsing, output formatting, and the mapping from a core result to an exit code.
+ */
+import type { Streams } from "./main.js";
+/**
+ * The open sampled-audit backlog: `audit.sampled` events with no later
+ * `audit.reviewed`, oldest first.
+ *
+ * The same set `.approval/QUEUE.md` renders and the same set the daemon counts,
+ * from the same projection, so the file, the daemon's `audit_backlog`, and this
+ * verb cannot disagree. Reads a verified log and writes nothing anywhere.
+ */
+export declare function commandAuditList(argv: string[], streams: Streams, cwd: string): number;
+/**
+ * `approval audit review <seq|action-key> [--note "<text>"]`
+ *
+ * HUMAN-ONLY, enforced in `core/audit.ts` and checked here first so a malformed
+ * invocation never reaches the log. `--note` is optional: the event's content is
+ * that a person looked, and a note is the reviewer's own record of what they
+ * concluded.
+ *
+ * No attestation is required, for the reason `execution resolve` states: review
+ * records an observation, exercises no policy authority, authorizes nothing, and
+ * spends no budget. A review blocked because a policy file was edited afterwards
+ * would be a supervision backlog held open by an unrelated fact.
+ */
+export declare function commandAuditReview(argv: string[], streams: Streams, cwd: string): number;
+/**
+ * The open reconciliation backlog: `reconciliation.required` records with no
+ * later `reconciliation.satisfied`.
+ *
+ * Reads a verified log and writes nothing. The same projection `status` and
+ * `doctor` read, so the three can never disagree about what is outstanding.
+ */
+export declare function commandAuditObligations(argv: string[], streams: Streams, cwd: string): number;
+/**
+ * `approval audit reconcile <obligation-seq> --note "<text>" [--revert <key>]`
+ *
+ * HUMAN-ONLY, enforced in `core/audit.ts` and again by the event schema, and
+ * checked here first so a malformed invocation never reaches the log.
+ */
+export declare function commandAuditReconcile(argv: string[], streams: Streams, cwd: string): number;
+/** `approval audit <subcommand>` — `list`, `review`, `obligations`, `reconcile`. */
+export declare function commandAudit(argv: string[], streams: Streams, cwd: string): number;