approval-md 0.0.1 → 0.1.0

package/dist/src/cli/audit-card.js

@@ -0,0 +1,201 @@
+/**
+ * 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 { claimed, computed } from "../channels/contract.js";
+import { openSamples } from "../core/audit.js";
+import { indexDeclarations } from "../core/execute.js";
+import { loadPayload, payloadStoreDirFor } from "../core/payload-store.js";
+import { payloadOf, readVerifiedRecords } from "../core/state.js";
+import { commandBreakdown, commandPayloadView } from "../core/wysiwys.js";
+function stringOrNull(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * The actor that declared an action, per key: the `task.registered` record's
+ * own, and failing that the `execution.started` that ran it.
+ *
+ * The author of a card's CLAIMED region, and it is read off who APPENDED a
+ * record rather than out of a payload field, for the reason `humanFeedback`
+ * gives about the same question: an actor is a property of the writer, and a
+ * self-reported one would let the party under oversight choose whose claim the
+ * approver is reading (SPEC.md §11.1 invariant 4).
+ */
+function authorsByKey(records) {
+    const registered = new Map();
+    const executed = new Map();
+    for (const record of records) {
+        const actor = typeof record.actor === "string" && record.actor.length > 0 ? record.actor : null;
+        if (actor === null)
+            continue;
+        if (record.event === "task.registered") {
+            const actions = payloadOf(record)["actions"];
+            if (!Array.isArray(actions))
+                continue;
+            for (const entry of actions) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const key = entry["idempotency_key"];
+                if (typeof key === "string" && key.length > 0)
+                    registered.set(key, actor);
+            }
+            continue;
+        }
+        if (record.event !== "execution.started")
+            continue;
+        const key = record.action_key;
+        if (typeof key === "string" && key.length > 0 && !executed.has(key))
+            executed.set(key, actor);
+    }
+    for (const [key, actor] of executed) {
+        if (!registered.has(key))
+            registered.set(key, actor);
+    }
+    return registered;
+}
+/**
+ * The bytes the sampled execution bound to, when anybody holds them.
+ *
+ * `null` whenever they cannot be produced honestly: no recorded hash, no
+ * override and no store, a store with no file, or a stored file that does not
+ * hash to what the log recorded. The last case is the one worth naming — a
+ * tampered `<hash>.json` yields NO breakdown rather than a breakdown of bytes
+ * that are not the ones that ran, because a line describing the wrong command
+ * is worse on a review card than an absent line.
+ */
+function materialFor(options, logPath, actionKey, boundHash) {
+    if (boundHash === null)
+        return null;
+    const supplied = options.payload?.(actionKey, boundHash);
+    if (supplied !== undefined)
+        return supplied;
+    const storeDir = options.payloadStoreDir === undefined ? payloadStoreDirFor(logPath) : options.payloadStoreDir;
+    if (storeDir === null)
+        return null;
+    const loaded = loadPayload(storeDir, boundHash);
+    return loaded.ok ? loaded.value : null;
+}
+/**
+ * What the runtime did at the time, in one computed line.
+ *
+ * The three facts a reviewer needs before they can say whether it should have
+ * happened: that NOBODY was asked, which autonomy said so, and the rate the
+ * draw was made at — all three read off the `audit.sampled` record the daemon
+ * wrote, which states the number the verdict was compared against (APRV-183).
+ * The outcome is appended when the log carries one; "not recorded" is the
+ * honest answer for an execution whose end nothing wrote, and it is never
+ * guessed at from the absence.
+ */
+function verdictLine(sample, outcome) {
+    const autonomy = stringOrNull(sample["autonomy"]) ?? "supervised";
+    const rate = sample["rate"];
+    const drawn = typeof rate === "number" ? `, drawn for review at rate ${String(rate)}` : ", drawn for review";
+    return `allowed without asking (autonomy ${autonomy})${drawn} · outcome ${outcome}`;
+}
+/** How the log says the sampled execution ended, or that it does not say. */
+function outcomeOf(records, actionKey, startSeq) {
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const record = records[index];
+        if (record.seq <= startSeq || record.action_key !== actionKey)
+            continue;
+        if (record.event === "execution.completed")
+            return "completed";
+        if (record.event === "execution.failed")
+            return "failed";
+    }
+    return "not recorded";
+}
+/**
+ * One card for one open sample, or `null` when the log cannot describe it.
+ *
+ * A sample naming no action key, or an action key no `task.registered` record
+ * declares, produces no card. That is the same refusal to guess `core/audit.ts`
+ * makes when it selects candidates: a class nobody declared is a class the card
+ * would have to invent, and a review card asserting an invented class is a
+ * statement to a human that nothing in the log supports. Such a sample stays in
+ * the backlog and is still answerable with `approval audit review`.
+ */
+function cardFor(records, subject, authors, declarations, logPath, options) {
+    const actionKey = subject.actionKey;
+    if (actionKey === null)
+        return null;
+    const declared = declarations.get(actionKey);
+    if (declared === undefined)
+        return null;
+    const sampleRecord = records.find((record) => record.seq === subject.seq);
+    const sample = sampleRecord === undefined ? {} : payloadOf(sampleRecord);
+    const start = subject.subjectSeq === null
+        ? undefined
+        : records.find((record) => record.seq === subject.subjectSeq && record.event === "execution.started");
+    const startPayload = start === undefined ? {} : payloadOf(start);
+    const ranAt = start?.ts ?? stringOrNull(sample["subject_ts"]) ?? subject.ts;
+    const material = materialFor(options, logPath, actionKey, stringOrNull(startPayload["payload_hash"]) ?? declared.payload_hash);
+    const command = material === null ? null : commandPayloadView(material);
+    const breakdown = command === null ? null : commandBreakdown(command.command);
+    const author = authors.get(actionKey) ?? "the requesting party";
+    const fields = {
+        action_key: computed(actionKey, "log"),
+        class: computed(declared.class, "log"),
+        task: computed(subject.task ?? declared.task, "log"),
+        summary: claimed(declared.summary, author),
+        ...(breakdown === null ? {} : { command_breakdown: computed(breakdown, "classifier") }),
+    };
+    return {
+        sampleSeq: subject.seq,
+        fields,
+        ranAtTs: ranAt,
+        ranAt: computed(start === undefined
+            ? `${ranAt} (the sample's record of when it started)`
+            : `${ranAt} (execution.started at seq ${String(start.seq)})`, "log"),
+        verdict: computed(verdictLine(sample, start === undefined ? "not recorded" : outcomeOf(records, actionKey, start.seq)), "log"),
+    };
+}
+/**
+ * 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 function openReviewCards(logPath, options = {}) {
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok)
+        return { ok: false, code: read.code, message: read.message };
+    const index = indexDeclarations(read.records);
+    const authors = authorsByKey(read.records);
+    const cards = [];
+    for (const subject of openSamples(read.records)) {
+        const card = cardFor(read.records, subject, authors, index.declarations, logPath, options);
+        if (card !== null)
+            cards.push(card);
+    }
+    return { ok: true, cards };
+}
+//# sourceMappingURL=audit-card.js.map

package/dist/src/cli/audit-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-card.js","sourceRoot":"","sources":["../../../src/cli/audit-card.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/audit.js

@@ -0,0 +1,460 @@
+/**
+ * `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 { isAbsolute, resolve as resolvePathSegments } from "node:path";
+import { openObligations, openSamples, parseSubjectRef, reconciliationObligations, isReaction, REACTIONS, reviewSample, sampledSubjects, satisfyObligation, } from "../core/audit.js";
+import { resolveHumanActor, HUMAN_ACTOR_ENV } from "../core/attest.js";
+import { loadPolicy } from "../core/policy-load.js";
+import { classSampling, resolveSampler } from "../core/sampler.js";
+import { readVerifiedRecords } from "../core/state.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_TORN_TAIL, EXIT_USAGE, } from "./exit-codes.js";
+import { AUDIT_HELP, AUDIT_LIST_HELP, AUDIT_OBLIGATIONS_HELP, AUDIT_RECONCILE_HELP, AUDIT_REVIEW_HELP, } from "./help.js";
+import { DEFAULT_LOG_PATH, preflightLog, resolvePath } from "./paths.js";
+import { refusal as renderRefusal, style } from "./style.js";
+import { usageErrorText } from "./usage.js";
+const COMMON_FLAGS = {
+    "--log": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+function absolute(value, cwd) {
+    return isAbsolute(value) ? value : resolvePathSegments(cwd, value);
+}
+function usageError(streams, json, message, helpText) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "usage", message } })}\n`);
+    else
+        streams.err(usageErrorText(message, helpText));
+    return EXIT_USAGE;
+}
+function ioError(streams, json, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "io", message } })}\n`);
+    else
+        streams.err(`approval: ${message}\n`);
+    return EXIT_IO;
+}
+function emitJson(streams, value) {
+    streams.out(`${JSON.stringify(value)}\n`);
+}
+/**
+ * Map an audit refusal onto the frozen exit table, by the same split every
+ * other verb draws: filesystem facts are 4, a crashed write is 3, and every
+ * decision the runtime itself made is 1.
+ */
+function refusalExitCode(refusal) {
+    switch (refusal.code) {
+        case "log-unreadable":
+            return EXIT_IO;
+        case "log-torn-tail":
+            return EXIT_TORN_TAIL;
+        case "append-failed":
+            switch (refusal.append?.code) {
+                case "corrupt-tail":
+                    return EXIT_TORN_TAIL;
+                case "io":
+                case "lock-timeout":
+                    return EXIT_IO;
+                default:
+                    return EXIT_INTEGRITY;
+            }
+        default:
+            return EXIT_INTEGRITY;
+    }
+}
+function emitRefusal(streams, json, refusal) {
+    if (json) {
+        const error = { code: refusal.code, message: refusal.message };
+        if (refusal.seq !== undefined)
+            error["seq"] = refusal.seq;
+        streams.err(`${JSON.stringify({ ok: false, error })}\n`);
+    }
+    else {
+        // APRV-102: the one refusal shape, and no `fix:` — an audit refusal names a
+        // state of the log or of the backlog, not a command that repairs it.
+        streams.err(`${renderRefusal(style({ json }), refusal.code, refusal.message)}\n`);
+    }
+    return refusalExitCode(refusal);
+}
+function front(argv, spec, helpText, streams, cwd) {
+    const json = argv.includes("--json");
+    const parsed = parseFlags(argv, spec);
+    if (!parsed.ok) {
+        return { kind: "handled", code: usageError(streams, json, parsed.message, helpText) };
+    }
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${helpText}\n`);
+        return { kind: "handled", code: EXIT_OK };
+    }
+    return {
+        kind: "run",
+        flags: parsed.flags,
+        positionals: parsed.positionals,
+        json,
+        logPath: resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, cwd),
+    };
+}
+// ===========================================================================
+// approval audit list
+// ===========================================================================
+/**
+ * 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 function commandAuditList(argv, streams, cwd) {
+    const outcome = front(argv, { ...COMMON_FLAGS, "--all": "boolean", "--policy": "string", "--dir": "string" }, AUDIT_LIST_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, logPath } = outcome;
+    const extra = positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, AUDIT_LIST_HELP);
+    }
+    const check = preflightLog(logPath);
+    if (!check.ok)
+        return ioError(streams, json, check.message);
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok) {
+        return emitRefusal(streams, json, { ok: false, code: read.code, message: read.message });
+    }
+    const all = boolFlag(flags, "--all");
+    const samples = all ? sampledSubjects(read.records) : openSamples(read.records);
+    const rows = samples.map((subject) => ({
+        seq: subject.seq,
+        ts: subject.ts,
+        action_key: subject.actionKey,
+        task: subject.task,
+        subject_seq: subject.subjectSeq,
+        reviewed_seq: subject.reviewedSeq,
+    }));
+    // The sampler's state is reported beside the backlog it explains: an empty
+    // backlog means one thing when sampling is running and quite another when no
+    // secret is configured, and an operator reading "empty" deserves to know
+    // which. See core/sampler.ts on why a missing secret disables sampling.
+    const policyFlag = stringFlag(flags, "--policy");
+    const dirFlag = stringFlag(flags, "--dir");
+    const samplingLoad = loadPolicy(policyFlag !== null
+        ? { file: absolute(policyFlag, cwd) }
+        : { dir: dirFlag === null ? cwd : absolute(dirFlag, cwd) });
+    const sampler = resolveSampler(samplingLoad);
+    // APRV-183. `rate` is the GLOBAL fallback and `classes` is the coverage: with
+    // a per-class `retro_rate` in the grammar, one number can no longer describe
+    // what is sampled, and a backlog explained by one number would be explained
+    // wrongly. Additive to the existing object, so every reader of `enabled`,
+    // `rate`, `secret_env` and `reason` keeps reading what it read.
+    const classes = classSampling(samplingLoad, sampler).map((entry) => ({
+        pattern: entry.pattern,
+        autonomy: entry.autonomy,
+        rate: entry.rate,
+        source: entry.source,
+        enabled: entry.enabled,
+        reason: entry.reason,
+    }));
+    const sampling = sampler.enabled
+        ? {
+            enabled: true,
+            rate: sampler.rate,
+            secret_env: sampler.secretEnv,
+            reason: null,
+            classes,
+        }
+        : {
+            enabled: false,
+            rate: sampler.rate,
+            secret_env: sampler.secretEnv,
+            reason: sampler.reason,
+            classes,
+        };
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            sampling,
+            open: rows.filter((row) => row.reviewed_seq === null).length,
+            samples: rows,
+        });
+    }
+    else {
+        streams.out(sampler.enabled
+            ? `sampling: on, rate ${String(sampler.rate)}, secret from ${sampler.secretEnv}\n`
+            : `sampling: OFF (${sampler.reason}) — ${sampler.message}\n`);
+        for (const entry of classes) {
+            streams.out(entry.enabled
+                ? `  ${entry.pattern}: rate ${String(entry.rate)} (${entry.source})\n`
+                : `  ${entry.pattern}: not sampled (${entry.reason ?? "rate-absent"})\n`);
+        }
+        if (rows.length === 0) {
+            streams.out(all
+                ? "no audit.sampled records in this log\n"
+                : "sampled-audit backlog: empty (no audit.sampled event is waiting for a review)\n");
+        }
+        for (const row of rows) {
+            streams.out(`${String(row.seq)}\t${row.ts}\t${row.action_key ?? "-"}\t${row.reviewed_seq === null ? "open" : `reviewed at seq ${String(row.reviewed_seq)}`}\n`);
+        }
+    }
+    return EXIT_OK;
+}
+// ===========================================================================
+// approval audit review
+// ===========================================================================
+/**
+ * `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 function commandAuditReview(argv, streams, cwd) {
+    const outcome = front(argv, {
+        ...COMMON_FLAGS,
+        "--note": "string",
+        "--deny": "boolean",
+        "--reaction": "string",
+        "--as": "string",
+        "--policy": "string",
+        "--dir": "string",
+    }, AUDIT_REVIEW_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, logPath } = outcome;
+    const subject = positionals[0];
+    if (subject === undefined) {
+        return usageError(streams, json, "missing <seq|action-key> argument", AUDIT_REVIEW_HELP);
+    }
+    const extra = positionals[1];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, AUDIT_REVIEW_HELP);
+    }
+    const asFlag = stringFlag(flags, "--as");
+    const actor = resolveHumanActor(asFlag === null ? {} : { actor: asFlag });
+    if (actor === null) {
+        return usageError(streams, json, asFlag === null
+            ? `no human identity: set ${HUMAN_ACTOR_ENV}=human:<id> or pass --as human:<id>`
+            : `--as expects a human identity matching human:<id>, got ${JSON.stringify(asFlag)}; a review records that a PERSON looked, and an agent: or system: actor cannot perform it`, AUDIT_REVIEW_HELP);
+    }
+    // Closed vocabulary, refused at exit 2 rather than defaulted or passed
+    // through, exactly as `withdraw --reason` is. A misspelling that silently
+    // became `indifferent` would put a word in the reviewer's mouth in an
+    // append-only log; one that reached the core would be answered as a refusal
+    // when what happened is that a person typed "love" for "loved".
+    const reactionFlag = stringFlag(flags, "--reaction");
+    if (reactionFlag !== null && !isReaction(reactionFlag)) {
+        return usageError(streams, json, `--reaction expects one of ${REACTIONS.join(" | ")}, got ${JSON.stringify(reactionFlag)}`, AUDIT_REVIEW_HELP);
+    }
+    const check = preflightLog(logPath);
+    if (!check.ok)
+        return ioError(streams, json, check.message);
+    const policyFlag = stringFlag(flags, "--policy");
+    const dirFlag = stringFlag(flags, "--dir");
+    const deny = boolFlag(flags, "--deny");
+    const result = reviewSample(logPath, parseSubjectRef(subject), actor, stringFlag(flags, "--note"), {
+        policy: policyFlag !== null
+            ? { file: absolute(policyFlag, cwd) }
+            : { dir: dirFlag === null ? cwd : absolute(dirFlag, cwd) },
+        // Explicit rather than defaulted through: the ABSENCE of --deny is "ok",
+        // and it must be this file that says so, once, where a reader can see it.
+        verdict: deny ? "denied" : "ok",
+        // Absent means absent (APRV-239). No default is substituted here or
+        // downstream: `indifferent` is a thing a person had to actually say.
+        ...(reactionFlag === null ? {} : { reaction: reactionFlag }),
+    });
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    const obligation = result.obligation;
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            seq: result.record.seq,
+            sample_seq: result.subject.seq,
+            action_key: result.subject.actionKey,
+            task: result.subject.task,
+            verdict: deny ? "denied" : "ok",
+            // Always present, `null` when the reviewer gave none: a consumer reading
+            // this shape must be able to tell "no reaction" from "the key is missing
+            // because this build predates the field".
+            reaction: reactionFlag,
+            obligation_seq: obligation === null ? null : obligation.seq,
+            actor,
+        });
+    }
+    else {
+        streams.out(`reviewed sample at seq ${String(result.subject.seq)} (action ${result.subject.actionKey ?? "-"}) at seq ${String(result.record.seq)} by ${actor}${deny ? " — DENIED" : ""}${reactionFlag === null ? "" : ` — reaction: ${reactionFlag} (guidance, not policy)`}\n`);
+        if (obligation !== null) {
+            const shape = String(obligation.payload?.["obligation"] ?? "");
+            streams.out(shape === "gated-revert"
+                ? `reconciliation obligation at seq ${String(obligation.seq)}: GATED REVERT. The action was declared reversible, so undo it through the gate and close this with \`approval audit reconcile ${String(obligation.seq)} --revert <action-key> --note "…"\`.\n`
+                : `reconciliation obligation at seq ${String(obligation.seq)}: POLICY FINDING. Nothing can be reverted, so what is owed is a review of the class that permitted this. Close it with \`approval audit reconcile ${String(obligation.seq)} --note "…"\` once that review has happened.\n`);
+        }
+    }
+    return EXIT_OK;
+}
+// ===========================================================================
+// approval audit obligations
+// ===========================================================================
+/**
+ * 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 function commandAuditObligations(argv, streams, cwd) {
+    const outcome = front(argv, { ...COMMON_FLAGS, "--all": "boolean" }, AUDIT_OBLIGATIONS_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, logPath } = outcome;
+    const extra = positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, AUDIT_OBLIGATIONS_HELP);
+    }
+    const check = preflightLog(logPath);
+    if (!check.ok)
+        return ioError(streams, json, check.message);
+    const read = readVerifiedRecords(logPath);
+    if (!read.ok) {
+        return emitRefusal(streams, json, { ok: false, code: read.code, message: read.message });
+    }
+    const all = boolFlag(flags, "--all");
+    const items = all ? reconciliationObligations(read.records) : openObligations(read.records);
+    const rows = items.map((item) => ({
+        seq: item.seq,
+        ts: item.ts,
+        action_key: item.actionKey,
+        task: item.task,
+        class: item.class,
+        review_seq: item.reviewSeq,
+        obligation: item.obligation,
+        reversible: item.reversible,
+        satisfied_seq: item.satisfiedSeq,
+    }));
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            open: rows.filter((row) => row.satisfied_seq === null).length,
+            obligations: rows,
+        });
+        return EXIT_OK;
+    }
+    if (rows.length === 0) {
+        streams.out(all
+            ? "no reconciliation.required records in this log\n"
+            : "reconciliation backlog: empty (no retrospective denial is waiting to be reconciled)\n");
+        return EXIT_OK;
+    }
+    for (const row of rows) {
+        streams.out(`${String(row.seq)}\t${row.ts}\t${row.action_key}\t${row.class}\t${row.obligation}\t${row.satisfied_seq === null ? "OPEN" : `satisfied at seq ${String(row.satisfied_seq)}`}\n`);
+    }
+    return EXIT_OK;
+}
+// ===========================================================================
+// approval audit reconcile
+// ===========================================================================
+/**
+ * `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 function commandAuditReconcile(argv, streams, cwd) {
+    const outcome = front(argv, { ...COMMON_FLAGS, "--note": "string", "--revert": "string", "--as": "string" }, AUDIT_RECONCILE_HELP, streams, cwd);
+    if (outcome.kind === "handled")
+        return outcome.code;
+    const { flags, positionals, json, logPath } = outcome;
+    const subject = positionals[0];
+    if (subject === undefined) {
+        return usageError(streams, json, "missing <obligation-seq> argument", AUDIT_RECONCILE_HELP);
+    }
+    const extra = positionals[1];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, AUDIT_RECONCILE_HELP);
+    }
+    if (!/^[1-9][0-9]*$/u.test(subject)) {
+        return usageError(streams, json, `<obligation-seq> is the SEQ of the reconciliation.required record, a positive integer, got ${JSON.stringify(subject)}; run \`approval audit obligations\` for the open ones`, AUDIT_RECONCILE_HELP);
+    }
+    const asFlag = stringFlag(flags, "--as");
+    const actor = resolveHumanActor(asFlag === null ? {} : { actor: asFlag });
+    if (actor === null) {
+        return usageError(streams, json, asFlag === null
+            ? `no human identity: set ${HUMAN_ACTOR_ENV}=human:<id> or pass --as human:<id>`
+            : `--as expects a human identity matching human:<id>, got ${JSON.stringify(asFlag)}; satisfying an obligation records that a PERSON discharged it, and an agent: or system: actor cannot perform it`, AUDIT_RECONCILE_HELP);
+    }
+    const note = stringFlag(flags, "--note");
+    if (note === null || note.trim().length === 0) {
+        return usageError(streams, json, `--note is required: this record asserts that an obligation was discharged, and a discharge nobody described is one no auditor can check`, AUDIT_RECONCILE_HELP);
+    }
+    const check = preflightLog(logPath);
+    if (!check.ok)
+        return ioError(streams, json, check.message);
+    const revert = stringFlag(flags, "--revert");
+    const result = satisfyObligation(logPath, Number(subject), actor, {
+        note,
+        ...(revert === null ? {} : { revertActionKey: revert }),
+    });
+    if (!result.ok)
+        return emitRefusal(streams, json, result);
+    if (json) {
+        emitJson(streams, {
+            ok: true,
+            seq: result.record.seq,
+            obligation_seq: result.obligation.seq,
+            action_key: result.obligation.actionKey,
+            task: result.obligation.task,
+            class: result.obligation.class,
+            obligation: result.obligation.obligation,
+            actor,
+        });
+    }
+    else {
+        streams.out(`reconciled the obligation at seq ${String(result.obligation.seq)} (${result.obligation.obligation} for ${result.obligation.actionKey}) at seq ${String(result.record.seq)} by ${actor}\n`);
+    }
+    return EXIT_OK;
+}
+/** `approval audit <subcommand>` — `list`, `review`, `obligations`, `reconcile`. */
+export function commandAudit(argv, streams, cwd) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    const json = argv.includes("--json");
+    if (sub === undefined) {
+        return usageError(streams, json, "missing subcommand for `approval audit`", AUDIT_HELP);
+    }
+    if (sub === "--help" || sub === "-h" || sub === "help") {
+        streams.out(`${AUDIT_HELP}\n`);
+        return EXIT_OK;
+    }
+    if (sub === "list")
+        return commandAuditList(rest, streams, cwd);
+    if (sub === "review")
+        return commandAuditReview(rest, streams, cwd);
+    if (sub === "obligations")
+        return commandAuditObligations(rest, streams, cwd);
+    if (sub === "reconcile")
+        return commandAuditReconcile(rest, streams, cwd);
+    return usageError(streams, json, `unknown subcommand ${JSON.stringify(sub)} for \`approval audit\``, AUDIT_HELP);
+}
+//# sourceMappingURL=audit.js.map