approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,492 @@
+/**
+ * The audit lifecycle (SPEC.md §5.2, §9.1, §12): `audit.sampled` →
+ * `audit.reviewed` → (on a denial) `reconciliation.required` →
+ * `reconciliation.satisfied`.
+ *
+ * ## What a retrospective denial can and cannot do (amended SPEC.md §5.2, APRV-127)
+ *
+ * The action already happened. The runtime cannot undo it, and any design that
+ * pretended otherwise would be lying to the person who denied it. What it can do
+ * is **oblige and record**: a denial appends an obligation naming the action, its
+ * class, and the review that denied, and the obligation stays open, and loud,
+ * until a HUMAN says it is discharged. Which obligation depends on whether the
+ * action was declared reversible — see {@link obligationFor}, including why a
+ * self-reported `reversible` may choose the shape and can never remove one.
+ *
+ * This is also why the autonomy split has a floor. `supervised-retro` refuses an
+ * action declaring `reversible: false` (`core/policy-match.ts`'s irreversibility
+ * floor pushes it to `manual`), because retrospective review of something that
+ * cannot be undone is regret with a paper trail. The floor is a floor and not a
+ * proof: it acts on a claim the acting party makes about itself, so it catches
+ * the honest declaration and never the lie. The obligation machinery here is what
+ * remains when the floor did not apply and the review said no anyway.
+ *
+ * Two halves, deliberately asymmetric:
+ *
+ * - **Sampling is the runtime's.** It is mechanical, it is retrospective, and it
+ *   escalates a supervised action that already executed into a human's review
+ *   queue. {@link sampleSupervised} appends `audit.sampled` with a `system:`
+ *   actor. Selection is `core/sampler.ts`'s keyed HMAC, so no agent can predict
+ *   or steer it.
+ * - **Review is a human's.** {@link reviewSample} appends `audit.reviewed` and
+ *   refuses any actor that is not `human:<id>`, by the same rule that governs
+ *   `grant`, `reject`, `revoke`, `policy attest`, and `execution resolve`. A
+ *   runtime that could mark its own samples reviewed would be a supervision
+ *   backlog that empties itself, which is precisely the failure the sampled
+ *   backlog exists to make visible.
+ *
+ * ## Eligibility is derived, never self-reported (global invariant 4)
+ *
+ * A candidate is an `execution.started` record whose action's class, as recorded
+ * in the `task.registered` declaration the log already holds, resolves to
+ * `supervised` under the live policy. Two things follow, both load-bearing:
+ *
+ * - the class comes from the registration record rather than from the
+ *   `execution.started` payload, and the autonomy comes from re-running
+ *   `core/policy-match.ts` rather than from any field claiming an autonomy. No
+ *   payload key an authoring party writes can move an action out of the
+ *   candidate set;
+ * - eligibility is recomputed from the log every sweep, so it does not depend on
+ *   any remembered flag, and a candidate cannot exclude itself by writing
+ *   anything into its own event.
+ *
+ * The manual path is excluded because it never resolves `supervised`: a manual
+ * action's start is authorized by a token and its class resolves `manual`, so it
+ * is not a candidate and is not double-counted.
+ *
+ * ## Exactly once, without remembering anything
+ *
+ * Every sweep re-derives the whole candidate set and subtracts the subjects the
+ * log already carries an `audit.sampled` for, keyed on the subject record's
+ * `hash` (unique per record by construction, and stable across re-reads). A
+ * daemon restart, a second daemon, and a manual sweep all converge on the same
+ * set, and none of them can double-sample. Every append passes `expectedHead`,
+ * so a check made against one log cannot land on another (SPEC.md §11.1
+ * invariant 5).
+ *
+ * ## Time
+ *
+ * `audit.*` is gate-typed (SPEC.md §8), so no public function here takes a `ts`:
+ * the timestamp is read from the injected clock at the write boundary, and the
+ * party being audited does not author the clock it is judged by.
+ */
+import { type ClockOptions } from "./clock.js";
+import { type AppendError, type EventRecord } from "./log.js";
+import { type PolicyLoadResult } from "./policy-load.js";
+import { type Sampler } from "./sampler.js";
+import type { ValidateOptions } from "./validate.js";
+/**
+ * SPEC.md §8: the sampler is the runtime, so its actor is `system:`. Distinct
+ * from `system:gate` (expiries) and `system:daemon` (envelope drift) so a reader
+ * can tell which part of the runtime spoke without reading the payload.
+ */
+export declare const AUDIT_ACTOR = "system:audit";
+/**
+ * The closed set of audit refusal codes. Frozen public API in the same sense the
+ * gate's and the executor's are: a supervisor branches on these strings, so
+ * adding one is a spec change and renaming one is a breaking change.
+ */
+export declare const AUDIT_REFUSAL_CODES: readonly [
+/** Review was attempted by an actor that is not `human:<id>`. */
+"actor-not-human", 
+/** No `audit.sampled` record matches the subject named. */
+"not-sampled", 
+/** That sample already has a later `audit.reviewed`. */
+"already-reviewed", 
+/** An action key with more than one unreviewed sample; name the seq instead. */
+"ambiguous-subject", 
+/** No `reconciliation.required` record at the seq named (APRV-127). */
+"not-obliged", 
+/** That obligation already has a `reconciliation.satisfied` (APRV-127). */
+"already-satisfied", 
+/**
+ * A verb that requires a reason was given none. Two shapes, one code: a
+ * reconciliation satisfied with a blank note (APRV-127), and a review whose
+ * `reaction` is `loved` or `disliked` with a blank note (APRV-239). Both are
+ * an assertion nobody can check, and both are evaluated after the actor check
+ * and before the log is read.
+ */
+"note-required", 
+/**
+ * A review that says the action should not have happened and that the human
+ * liked or loved it (APRV-239). Evaluated beside `note-required`, before the
+ * log is read; nothing is appended.
+ *
+ * The two fields point opposite ways and only one of them is enforcement, so
+ * the safe reading is not "believe the verdict and drop the grade": a record
+ * carrying both would be read by a person later as evidence of whichever half
+ * suited them, and by an agent as a signal that a denial is survivable if the
+ * operator is pleased. The reviewer is asked to say which they meant.
+ */
+"reaction-conflicts-verdict", 
+/**
+ * A `gated-revert` obligation whose satisfaction names no completed revert
+ * (APRV-127). The obligation is to undo the action THROUGH THE GATE, and the
+ * evidence of that is an `execution.completed` in this same log.
+ */
+"revert-required", 
+/**
+ * The denial was recorded and its obligation was not (APRV-127). The log is
+ * NOT inconsistent — `audit.reviewed` stands and says `denied` — but the
+ * obligation it should have created is missing and must be created by
+ * reviewing again once the head settles.
+ */
+"obligation-not-appended", 
+/** The log could not be read, or holds a line that is not a record. */
+"log-unreadable", 
+/** The log's final line is unterminated (a crashed write). */
+"log-torn-tail", 
+/** The chain does not verify; nothing is derived from an untrustworthy log. */
+"log-corrupt", 
+/** The append itself failed; `append` carries the underlying error. */
+"append-failed"];
+export type AuditRefusalCode = (typeof AUDIT_REFUSAL_CODES)[number];
+export interface AuditRefusal {
+    ok: false;
+    code: AuditRefusalCode;
+    message: string;
+    /** The seq of the record that produced the refusal, when there is one. */
+    seq?: number;
+    /** The underlying append error, when `code` is `append-failed`. */
+    append?: AppendError;
+}
+/** Options shared by the audit verbs. No `ts`: `audit.*` is gate-typed. */
+export interface AuditOptions extends ClockOptions, ValidateOptions {
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy?: {
+        dir?: string;
+        file?: string;
+    };
+    /** Environment the sampling secret is read from. Injected by tests. */
+    env?: NodeJS.ProcessEnv;
+}
+/** One supervised execution eligible for retrospective review. */
+export interface AuditCandidate {
+    /** `seq` of the `execution.started` record. */
+    seq: number;
+    /** `hash` of that record: the HMAC input and the dedupe key. */
+    hash: string;
+    ts: string;
+    actionKey: string;
+    task: string | null;
+    /** The class the registration declared, re-resolved to `supervised`. */
+    class: string;
+}
+/**
+ * Every `execution.started` whose action resolves `supervised` under `load`, in
+ * log order.
+ *
+ * Pure: no I/O, no clock, no environment. Records with no action key, and keys
+ * no `task.registered` record declares, are skipped rather than guessed at — an
+ * undeclared key has no class, and inventing one would put a fact in the sample
+ * that nobody wrote.
+ */
+export declare function supervisedExecutions(records: readonly EventRecord[], load: PolicyLoadResult): AuditCandidate[];
+/** One `audit.sampled` record, with the review that closes it (or none). */
+export interface SampledSubject {
+    /** `seq` of the `audit.sampled` record itself. */
+    seq: number;
+    ts: string;
+    actionKey: string | null;
+    task: string | null;
+    /** `hash` of the subject record the sample named, when it named one. */
+    subjectHash: string | null;
+    /** `seq` of the subject record the sample named, when it named one. */
+    subjectSeq: number | null;
+    /** `seq` of the later `audit.reviewed`, or `null` when still open. */
+    reviewedSeq: number | null;
+}
+/**
+ * Every `audit.sampled` in the log, each tagged with the `audit.reviewed` that
+ * closes it.
+ *
+ * A review closes a sample only when it comes **after** it in the chain and
+ * names the same action key. An earlier review is a review of an earlier sample;
+ * treating it as covering this one would silently empty the backlog, which is
+ * exactly the failure a sampled-audit backlog exists to prevent. This mirrors
+ * `channels/render-queue.ts`'s matching rule, so the CLI and the queue
+ * projection never disagree about what is outstanding.
+ */
+export declare function sampledSubjects(records: readonly EventRecord[]): SampledSubject[];
+/** Samples with no later review, oldest first. The human's audit backlog. */
+export declare function openSamples(records: readonly EventRecord[]): SampledSubject[];
+/** The candidates a sweep would sample now: eligible, selected, not yet sampled. */
+export declare function pendingSamples(records: readonly EventRecord[], load: PolicyLoadResult, sampler: Sampler): AuditCandidate[];
+/** One `audit.sampled` this sweep appended. */
+export interface SampleAppended {
+    record: EventRecord;
+    candidate: AuditCandidate;
+}
+export interface SampleSweepResult {
+    ok: true;
+    /** The sampler in force. Carries the reason when sampling is off. */
+    sampler: Sampler;
+    appended: SampleAppended[];
+    /** Appends that were refused. Reported, never retried in place. */
+    refusals: AuditRefusal[];
+}
+export type SampleResult = SampleSweepResult | AuditRefusal;
+/**
+ * Sample every supervised execution the log does not yet carry an
+ * `audit.sampled` for, and append one event per selection.
+ *
+ * Re-reads the verified log before every append so the head each
+ * compare-and-append is made against is the head the decision was made from. A
+ * `head-moved` refusal is collected and reported rather than retried: only the
+ * next sweep, which re-derives the whole question from the log as it now is,
+ * knows whether the candidate is still a candidate.
+ *
+ * Returns `ok` with an empty `appended` list when sampling is disabled; the
+ * reason travels on `sampler`. A disabled sampler is not a refusal, because
+ * nothing was asked for and nothing failed. See `core/sampler.ts` on why a
+ * missing secret disables sampling rather than escalating everything.
+ */
+export declare function sampleSupervised(logPath: string, cwd: string, options?: AuditOptions): SampleResult;
+/** How a caller named the sample to review. */
+export type SubjectRef = {
+    kind: "seq";
+    seq: number;
+} | {
+    kind: "action-key";
+    actionKey: string;
+};
+/** Parse the CLI's one positional: a bare integer is a seq, anything else a key. */
+export declare function parseSubjectRef(text: string): SubjectRef;
+export interface ReviewResult {
+    ok: true;
+    record: EventRecord;
+    subject: SampledSubject;
+    /**
+     * The `reconciliation.required` this review created, on a denial only
+     * (APRV-127). `null` for an `ok` verdict, which obliges nothing.
+     */
+    obligation: EventRecord | null;
+}
+/** What a reviewer concluded (amended SPEC.md §5.2, APRV-127). */
+export type ReviewVerdict = "ok" | "denied";
+/**
+ * The graded reaction a review or a grant MAY carry (amended SPEC.md §5.2,
+ * APRV-237/APRV-239), in the order the schema's enum lists them: worst to best.
+ *
+ * **This is not enforcement, and it lives here rather than in an enforcement
+ * module for that reason.** `verdict` is the field the runtime acts on;
+ * `reaction` is what the human thought, travelling human-to-agent, and SPEC.md
+ * §11.1 invariant 10 says no routing, class matching, sampling, budget, token,
+ * gate-window or execution decision may read it. `tests/values-inert.test.ts`
+ * enforces that as a static guard over the enforcement modules, which is why the
+ * tuple is exported from `core/audit.ts` (the projection's home) and imported by
+ * the surfaces that show it, and by nothing that decides.
+ *
+ * The vocabulary is closed on purpose. Four words are a grade a person can give
+ * in one tap and an agent can read back without interpretation; an open field
+ * would accumulate synonyms across surfaces until "meh" and "indifferent" were
+ * two different signals. The absence of the field is absence: it is never read
+ * as `indifferent`, which is a thing a person had to actually say.
+ */
+export declare const REACTIONS: readonly ["disliked", "indifferent", "liked", "loved"];
+export type Reaction = (typeof REACTIONS)[number];
+/** Whether a string is one of the four graded reactions. Used at the CLI boundary. */
+export declare function isReaction(value: string): value is Reaction;
+/** The shape a denial's obligation takes. */
+export type Obligation = "gated-revert" | "policy-finding";
+export interface ReviewOptions extends AuditOptions {
+    /**
+     * The verdict. Defaults to `"ok"`: a review whose caller says nothing about
+     * what it concluded records the observation it always did, and the ABSENCE of
+     * a verdict is never read as a denial.
+     */
+    verdict?: ReviewVerdict;
+    /**
+     * The graded reaction, recorded beside the verdict when the reviewer gave one
+     * (APRV-239). Omitted means omitted: nothing is written, and no reader may
+     * substitute `indifferent` for a person who said nothing.
+     */
+    reaction?: Reaction;
+}
+/**
+ * The obligation a denial creates, chosen by the action's DECLARED
+ * reversibility (amended SPEC.md §5.2/§7, APRV-127).
+ *
+ * - `reversible: true` → `gated-revert`. The action can be undone, so the
+ *   obligation is to undo it *through the gate*: the revert is itself a
+ *   side-effecting action, and routing it through the gate is what closes the
+ *   loop inside the log rather than inside a promise.
+ * - `reversible: false` → `policy-finding`. There is nothing to revert. What is
+ *   left is the finding that the class should not have permitted this without a
+ *   human, and the sanctioned response is tightening the class; the obligation
+ *   is the review of that tightening.
+ * - **declared nothing** → `policy-finding`, the same as `false`. This is the
+ *   fail-closed direction, and the reason is worth stating: obliging a revert of
+ *   an action nobody said could be reverted would record an obligation that may
+ *   be impossible to discharge, and an impossible obligation is one that gets
+ *   closed dishonestly. A policy finding is always dischargeable, and it is the
+ *   heavier of the two: it puts the CLASS on the table rather than one action.
+ *
+ * ## Self-reported, and only ever in the safe direction
+ *
+ * `reversible` is written by the party whose action is under review, so global
+ * invariant 4 applies: it may never reduce scrutiny. Here it does not. It
+ * selects the SHAPE of an obligation that exists either way; it cannot remove
+ * one, delay one, or decide whether the denial happened. The one thing a false
+ * `reversible: true` buys is a revert obligation instead of a policy finding —
+ * and the revert obligation is the one whose satisfaction this runtime checks
+ * against the log (`revert-required`), so the lie makes the claimant's own exit
+ * harder rather than easier.
+ */
+export declare function obligationFor(reversible: boolean | null): Obligation;
+/**
+ * Append `audit.reviewed` for one open sample.
+ *
+ * HUMAN-ONLY, by the same rule as `grant`/`reject`/`revoke`: the whole content
+ * of the event is that a person looked. An agent- or system-authored review
+ * would be the party under oversight closing its own audit item, and a backlog
+ * that can be emptied by the thing it supervises measures nothing.
+ *
+ * No attestation is required, for the reason `execution resolve` states: review
+ * records an observation and exercises no policy authority. It authorizes
+ * nothing, spends no budget, and mints no token.
+ *
+ * `--note` is optional and recorded verbatim when present. It is not mandatory
+ * the way `execution resolve`'s is, because that verb writes an *outcome* the
+ * runtime does not know while this one writes only "seen".
+ */
+export declare function reviewSample(logPath: string, ref: SubjectRef, actor: string, note: string | null, options?: ReviewOptions): ReviewResult | AuditRefusal;
+/** One `reconciliation.required`, with the satisfaction that closes it. */
+export interface ReconciliationObligation {
+    /** `seq` of the `reconciliation.required` record. */
+    seq: number;
+    ts: string;
+    actionKey: string;
+    task: string | null;
+    class: string;
+    /** `seq` of the `audit.reviewed` that denied. */
+    reviewSeq: number;
+    obligation: Obligation;
+    reversible: boolean | null;
+    /** `seq` of the `reconciliation.satisfied`, or `null` while still open. */
+    satisfiedSeq: number | null;
+}
+/**
+ * Every reconciliation obligation the log carries, each tagged with the
+ * satisfaction that closes it.
+ *
+ * A satisfaction closes an obligation only when it comes **after** it in the
+ * chain and names its seq — the same "later, and names it" rule
+ * {@link sampledSubjects} applies to reviews, and for the same reason: a
+ * backlog that an earlier record could close is a backlog that empties itself.
+ *
+ * A malformed `reconciliation.required` (no action key, no class, no usable
+ * obligation shape) is SKIPPED rather than guessed at. Such a record cannot
+ * reach the log through this runtime — the event schema requires all three — so
+ * one that is there arrived some other way, and inventing the missing field
+ * would put a fact in the backlog that nobody wrote.
+ */
+export declare function reconciliationObligations(records: readonly EventRecord[]): ReconciliationObligation[];
+/** Obligations with no later satisfaction, oldest first. The loud backlog. */
+export declare function openObligations(records: readonly EventRecord[]): ReconciliationObligation[];
+export interface SatisfyResult {
+    ok: true;
+    record: EventRecord;
+    obligation: ReconciliationObligation;
+}
+/** What a human says they did to discharge an obligation. */
+export interface SatisfyInput {
+    /** What was done. REQUIRED — see the event schema on why. */
+    note: string;
+    /**
+     * For a `gated-revert` obligation, the action key of the revert. The log must
+     * carry an `execution.completed` for it.
+     */
+    revertActionKey?: string;
+}
+/**
+ * Close one reconciliation obligation.
+ *
+ * **HUMAN-ONLY**, by the same rule that governs `grant`, `reject`, `revoke` and
+ * `audit.reviewed`, and enforced twice: here in code and again by the event
+ * schema. The entire content of the record is that a person judged the
+ * obligation discharged. A runtime that could satisfy its own obligations would
+ * be a reconciliation backlog that empties itself, which is precisely the
+ * silence an unreconciled denial exists to break.
+ *
+ * Two checks beyond the actor, and both are about evidence rather than trust:
+ *
+ * - **A note is required.** `audit.reviewed` may record only "seen"; this record
+ *   asserts that something was DONE, and an assertion nobody described is one no
+ *   auditor can check.
+ * - **A `gated-revert` obligation requires a completed revert IN THIS LOG.** The
+ *   obligation was "undo it through the gate", so the discharge is a gated
+ *   action that ran, and the runtime looks for its `execution.completed` rather
+ *   than accepting a sentence saying it happened. That is what closes the loop
+ *   in the chain. A `policy-finding` obligation has no such artifact — the
+ *   sanctioned response is a policy amendment, which is a separate human
+ *   ceremony with its own `policy.updated` record — so the note is the discharge
+ *   there, and the note is required.
+ *
+ * No attestation is required, for the reason `audit review` and `execution
+ * resolve` state: this record exercises no policy authority, authorizes nothing,
+ * spends no budget, and mints no token.
+ */
+export declare function satisfyObligation(logPath: string, obligationSeq: number, actor: string, input: SatisfyInput, options?: AuditOptions): SatisfyResult | AuditRefusal;
+/** Which human gesture an entry came from. */
+export type FeedbackSource = "review" | "decision";
+/**
+ * One thing a human said about an action, as `approval feedback` prints it.
+ *
+ * Everything here is derived from records the caller already verified. Nothing
+ * is looked up in a file, no policy is resolved, and no clock is read: two
+ * callers handed the same records get the same list in the same order.
+ */
+export interface FeedbackEntry {
+    /** `seq` of the record carrying the reaction or note. */
+    seq: number;
+    ts: string;
+    source: FeedbackSource;
+    /** `audit.reviewed` or `approval.granted`, spelled as the log spells it. */
+    event: string;
+    /** The human who said it: the actor on the record itself. */
+    actor: string;
+    /** The graded reaction, or `null` when the record carries none. */
+    reaction: Reaction | null;
+    /** The human's words, or `null` when there were none. */
+    note: string | null;
+    /** The enforcement field, on a review only. `null` on a grant. */
+    verdict: ReviewVerdict | null;
+    actionKey: string | null;
+    task: string | null;
+    /** The class from the `task.registered` declaration, never from a payload claim. */
+    class: string | null;
+    /**
+     * The agent whose work this is about, NOT the human who reacted.
+     *
+     * Sourced from the `task.registered` record that declared the action key, and
+     * failing that from the `execution.started` that ran it. Never from a payload
+     * field: an actor is a property of who appended a record, and a self-reported
+     * one would let the party under oversight choose whose feedback this reads as
+     * (SPEC.md §11.1 invariant 4).
+     */
+    agentActor: string | null;
+    /** `seq` of the `audit.sampled` a review closed, or `null` on a grant. */
+    sampleSeq: number | null;
+}
+/**
+ * Every reaction and every note a human wrote about an action, oldest first.
+ *
+ * The HUMAN-TO-AGENT direction of the log (amended SPEC.md §5.2). Two sources,
+ * because a human says what they thought in two places: at the gate, answering a
+ * request (`approval.granted`), and afterwards, reviewing a sampled action
+ * (`audit.reviewed`). Rejections and revocations carry no reaction at all, so
+ * they are not a source: their reason IS their note, and the record already says
+ * what happened.
+ *
+ * **An entry with neither a reaction nor a note is omitted.** A grant with no
+ * words is the ordinary case, most grants are, and listing thousands of them as
+ * blank rows would bury the handful where somebody actually said something.
+ * Absence of feedback is not feedback.
+ *
+ * Reads only the records it is given, and callers pass VERIFIED records: this is
+ * a projection in the sense the rest of this module uses the word, it writes
+ * nothing, decides nothing, and no enforcement path reads it (SPEC.md §11.1
+ * invariant 10).
+ */
+export declare function humanFeedback(records: readonly EventRecord[]): FeedbackEntry[];