approval-md 0.1.0 → 0.3.0

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

@@ -0,0 +1,217 @@
+/**
+ * Coverage of observed side effects (APRV-245, SPEC.md §10.1).
+ *
+ * ## Why a verb that witnesses rather than gates
+ *
+ * MCP use is voluntary. An agent connected to `approval mcp serve --http` can
+ * call `request`, `wait` and `run`, or it can simply act. Nothing in this
+ * runtime observes the act, because the runtime is not in the path: a gate an
+ * agent may route around reports only on the actions routed through it, and a
+ * report that counts only its own inputs is a report that cannot go down.
+ *
+ * What makes the arrangement honest is that side effects leave witnesses THIS
+ * PROJECT DOES NOT WRITE. Git history records commits, merges and tags. `gh`
+ * records pull requests. AgentMail records the messages an inbox actually sent.
+ * None of those are appended by approval.md, none of them are reachable by an
+ * agent editing its own log, and each of them can be read back and joined
+ * against the verified records to ask one question per effect: does the log say
+ * a human, or a policy, ever saw this?
+ *
+ * This module is that join, and nothing else. It performs no IO, reads no clock,
+ * spawns nothing and appends nothing. The sources under `coverage-sources/`
+ * gather the effects; `cli/coverage.ts` prints the answer.
+ *
+ * ## What counts as evidence, stated exactly
+ *
+ * The strongest answer first (APRV-251): an `execution.completed` may carry
+ * `payload.provider_ref`, the identifier the provider filed the effect under
+ * (SPEC.md §8), and an effect whose source and id match one is covered by that
+ * record, reported as `provider-ref`. No window is applied to it, because an id
+ * names one effect and a class in a span of time names a period. That is the
+ * whole difference the reference buys: without it, a gated send covers an
+ * ungated one of the same class sitting beside it in the window, and with it
+ * the log answers about the message actually in front of the reader.
+ *
+ * Otherwise, for one {@link ObservedEffect}, evidence is the EARLIEST record
+ * that is all three of:
+ *
+ * 1. one of `task.registered`, `approval.granted`, `execution.started`,
+ *    `execution.completed` — the four records that mean "this runtime was told
+ *    about an action of this class", from the declaration through the human's
+ *    decision to the spend;
+ * 2. of a matching class: EXACT first ({@link classesOf} against the effect's
+ *    class), and only if nothing matches exactly, a FAMILY match on the first
+ *    two dotted segments, reported distinctly as `family` so a reader is never
+ *    shown a weaker match dressed as a strong one;
+ * 3. inside the window `[at - 24h, at + 5m]`.
+ *
+ * The window is asymmetric on purpose and both halves are arguable, so both are
+ * written down. **24 hours back**, because the ordinary shape is register →
+ * request → grant → act, and the gap between the human's tap and the effect is
+ * a working day at worst; a week back would let one grant carry every later
+ * effect of its class, which is the laundering hole APRV-202 closed in the
+ * protected-path guard. **5 minutes forward**, because that is clock skew
+ * between git's author date (or a provider's timestamp) and this log, and not an
+ * ordering allowance: a record appended an hour after an effect is a record
+ * about some other action, whatever its class.
+ *
+ * The one place this rule is not used is a protected FILE path. Those already
+ * have a stronger answer: `core/protected-path-guard.ts` matches a change's
+ * BYTES against the material a grant bound, and its `attested` and
+ * `granted-file` verdicts are content-level rather than time-level. So an effect
+ * carrying a `path` takes the guard's verdict when the caller supplies a report
+ * that covers it, and the class-and-window rule is what everything else gets.
+ *
+ * ## Verified records only, and no writes
+ *
+ * The caller reads through `readVerifiedRecords` (SPEC.md §11.1 invariant 1);
+ * this function is handed records that already passed chain verification and has
+ * no way to read any others. It writes nothing anywhere, which is what lets it be
+ * informational: the whole report is derived, and running it changes no state
+ * that any later verdict depends on.
+ *
+ * ## What a green line does NOT say
+ *
+ * Coverage is a witness, not a control. An effect made with a credential the
+ * AGENT itself holds — an API key pasted into a chat surface, a token in a
+ * shell profile — leaves a witness only where the provider keeps one this verb
+ * can read. The remedy for that tier is custody (SPEC.md §10.4: adapters hold
+ * the credentials and answer only to a token), not a bigger report, and
+ * `docs/cli-reference.md#coverage` writes the three tiers out so that a green
+ * coverage line is never read as the claim that nothing else happened.
+ */
+import type { EventRecord } from "./log.js";
+import type { GuardReport } from "./protected-path-guard.js";
+/**
+ * One side effect a witness outside this runtime recorded.
+ *
+ * Every field is a FACT ABOUT THE WORLD, gathered from git, `gh` or a provider,
+ * and none of it is self-reported by the party under oversight. `actorHint` is
+ * named a hint deliberately: a commit author email is whatever the committer
+ * configured, so it is printed for a reader and never matched on (SPEC.md §11.1
+ * invariant 4 — a self-reported field never reduces scrutiny).
+ */
+export interface ObservedEffect {
+    /** Which source saw it: `git`, `gh`, `agentmail`. */
+    source: string;
+    /** The witness's own identifier: a commit sha, a PR number, a message id. */
+    id: string;
+    /** The side-effect class (SPEC.md §7) this effect would have been declared under. */
+    class: string;
+    /** When the witness says it happened, RFC 3339. */
+    at: string;
+    /** Who the witness says did it, or `null`. Printed, never matched on. */
+    actorHint: string | null;
+    /** One line a person can read. Never a message body, never a secret. */
+    detail: string;
+    /** For a file effect, the repository-relative path it changed. */
+    path?: string;
+}
+/**
+ * The span an observation covers, as two RFC 3339 instants.
+ *
+ * Both ends are supplied by the caller and neither is read from a clock here,
+ * so two runs over the same window ask every provider the same question.
+ */
+export interface ObservationWindow {
+    since: string;
+    until: string;
+}
+/**
+ * What the log says about one effect.
+ *
+ * `null` is a GAP: no record of a matching class sits in the window. The two
+ * shapes carry different kinds of proof, so they are different shapes rather
+ * than one object with optional halves — a record seq is something a reader can
+ * paste into `approval log tail`, and a guard verdict is a statement about
+ * bytes.
+ */
+export type Evidence = {
+    seq: number;
+    event: string;
+} | {
+    verdict: "attested" | "granted-file";
+} | null;
+/** How the evidence was found, so a weaker match is never read as a stronger one. */
+export type CoverageMatch = 
+/**
+ * An `execution.completed` names this exact effect by the provider's own
+ * identifier (APRV-251). The strongest answer this join can give: it is about
+ * one effect rather than about a class in a span of time.
+ */
+"provider-ref"
+/** The record's declared class equals the effect's class. */
+ | "exact"
+/** Only the class FAMILY matched (the first two dotted segments). */
+ | "family"
+/** The protected-path guard answered for this path, on bytes rather than time. */
+ | "protected-path"
+/** Nothing matched. `evidence` is `null`. */
+ | "none";
+/** One effect, and what the log had to say about it. */
+export interface CoverageEntry {
+    effect: ObservedEffect;
+    evidence: Evidence;
+    match: CoverageMatch;
+}
+/** Observed and covered counts for one grouping key. */
+export interface CoverageTotals {
+    key: string;
+    observed: number;
+    covered: number;
+}
+export interface CoverageReport {
+    entries: readonly CoverageEntry[];
+    /** Totals per source, sorted by source name. */
+    bySource: readonly CoverageTotals[];
+    /** Totals per class, sorted by class name. */
+    byClass: readonly CoverageTotals[];
+    observed: number;
+    covered: number;
+}
+/** How far BACK of an effect a record may sit and still be about it: 24 hours. */
+export declare const COVERAGE_LOOKBACK_MS: number;
+/**
+ * How far AHEAD of an effect a record may sit: five minutes.
+ *
+ * A skew allowance between two clocks, not an ordering allowance. See the
+ * module note for why the window is asymmetric.
+ */
+export declare const COVERAGE_AHEAD_MS: number;
+/** The record types that can be evidence, in the order they occur in a life. */
+export declare const EVIDENCE_EVENTS: readonly string[];
+export interface CoverageOptions {
+    /** Override {@link COVERAGE_LOOKBACK_MS}. */
+    lookbackMs?: number;
+    /** Override {@link COVERAGE_AHEAD_MS}. */
+    aheadMs?: number;
+    /**
+     * The protected-path guard's report for the same range, when the caller ran
+     * one. An effect whose `path` has a passing finding there takes that verdict
+     * instead of the class-and-window rule: it is content-level evidence, and
+     * content beats time.
+     */
+    guard?: GuardReport | null;
+}
+/**
+ * The family of a class: its first two dotted segments.
+ *
+ * `vcs.push.main` and `vcs.push.branch` are one family; `vcs.push.main` and
+ * `vcs.commit.branch` are not. Two segments rather than one, because a single
+ * segment would make every `vcs.*` record evidence for every other, and the
+ * pushes and the commits are different decisions. A class with fewer than two
+ * segments is its own family.
+ */
+export declare function classFamily(cls: string): string;
+/**
+ * Join observed effects against verified records.
+ *
+ * Deterministic and total: the same effects and the same records produce the
+ * same report, in the same order, every time. Entries come back in the order the
+ * effects were given, and the totals are sorted by key so that a `--json`
+ * consumer can pin the whole object with a `deepEqual`.
+ *
+ * @param effects what the witnesses outside this runtime saw
+ * @param records records that have ALREADY passed chain verification
+ */
+export declare function coverageReport(effects: readonly ObservedEffect[], records: readonly EventRecord[], options?: CoverageOptions): CoverageReport;

package/dist/src/core/credential-spec.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The credential manifest type (SPEC.md §10.4; APRV-78).
+ *
+ * An adapter reads named values out of the vault, and until this file existed
+ * the only place those names were written down was the adapter's own `act`,
+ * where a human setting the vault up cannot read them. A manifest moves that
+ * knowledge one level out: the adapter DECLARES what it needs, and a generic
+ * interactive writer (`cli/setup-flow.ts`) asks for it, validates it, stores it
+ * and reports on it without knowing anything about email or SMTP.
+ *
+ * **This module is a type and nothing else.** No I/O, no imports, no runtime
+ * values, deliberately: it is imported by `src/adapters/*` (which must not
+ * depend on the CLI) and by `src/cli/*` (which must not depend on a particular
+ * adapter), so anything with behaviour in it would make one of those two edges
+ * a dependency on the other. The behaviour lives at both ends; the vocabulary
+ * lives here.
+ *
+ * A spec carries no default for a `secret`, and it never carries a VALUE of any
+ * kind: the manifest is printed, in checklists and in non-interactive hints, and
+ * a field that could hold a credential would be a credential in a terminal.
+ */
+/**
+ * What kind of thing a credential is, from the operator's point of view.
+ *
+ * Three, not two, because the collection differs for each: a `config` value is
+ * typed in the clear with its default shown, a `choice` is picked from a
+ * numbered list so a typo cannot become a silently wrong transport, and a
+ * `secret` is read with no echo. The vault stores all three identically — it
+ * has no notion of a non-secret entry — so this distinction exists purely to
+ * decide what the human is asked and what may be echoed back at them.
+ */
+export type CredentialKind = "secret" | "config" | "choice";
+/** One value an adapter reads from the vault, described well enough to ask for. */
+export interface CredentialSpec {
+    /** The vault name, exactly as the adapter's `act` asks for it. */
+    name: string;
+    kind: CredentialKind;
+    /** A short label for a prompt: `SMTP host`. */
+    label: string;
+    /** One sentence for the checklist: what this is and why the adapter wants it. */
+    describe: string;
+    /**
+     * Must the vault hold this before the adapter can work?
+     *
+     * `false` does not mean "unimportant": the email adapter's user and password
+     * are both optional and both-or-neither, which no per-field flag can express.
+     * That is what {@link CredentialSpec.validate}'s cross-field companion (the
+     * flow's `check` hook) is for.
+     */
+    required: boolean;
+    /** Offered as `[default]` at the prompt. Never present on a `secret`. */
+    default?: string;
+    /** For `kind: "choice"`: the closed set, each with a one-line explanation. */
+    choices?: readonly {
+        value: string;
+        describe: string;
+    }[];
+    /**
+     * Per-field validation, run on the value the operator typed.
+     *
+     * Returns the refusal SENTENCE rather than a code, because the sentence is
+     * the whole point: it must be the same one the adapter's own `act` would
+     * print later, so an operator does not learn at send time that the port they
+     * typed at setup time was never a port.
+     */
+    validate?(value: string): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+}

package/dist/src/core/daemon-actor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Is THIS process the daemon? (APRV-382.)
+ *
+ * One fact, held in one place, so the gated advance path can ask it without
+ * being told it. `log.advance.daemon` is autonomous in this repository's policy
+ * and `log.advance` is not, which means something has to decide which of the
+ * two a cycle asks under — and that decision must not be an argument a caller
+ * passes, because a field a caller sets is a self-reported field, and SPEC.md
+ * §11.1 invariant 4 says a self-reported field never reduces scrutiny.
+ *
+ * So the mark is set by the daemon runtime itself, at construction, and read
+ * from module state that no exported function will set on another process's
+ * behalf: {@link markDaemonProcess} takes no arguments and records
+ * `process.pid`, and {@link isDaemonProcess} answers true only while that
+ * recorded pid is still this process's own. A child inherits nothing — module
+ * state does not cross a `spawn` — so the advance child, which holds no
+ * authority by design, answers false here as it should.
+ *
+ * What this is NOT: a security boundary against code already running in the
+ * daemon's process. Anything executing there can call {@link markDaemonProcess}
+ * the way the daemon does. The boundary that keeps an agent out of this process
+ * is elsewhere and unchanged: `approval daemon run` and `approval up` classify
+ * `gate.self`, which this repository's policy leaves at the fail-closed manual
+ * default, so an agent cannot start a daemon unattended in the first place.
+ * What this module removes is the smaller and likelier failure — a future
+ * caller wiring the autonomous route through a struct field, in a session, by
+ * accident.
+ */
+/**
+ * Declare this process the daemon runtime. Called by the daemon, and only by it.
+ *
+ * Idempotent, and argument-free on purpose: there is no spelling of this call
+ * that marks a process other than the caller's own.
+ */
+export declare function markDaemonProcess(): void;
+/**
+ * Forget the mark. For tests, and for a runtime that stops being a daemon.
+ *
+ * Present so a suite can exercise both actors in one file without a second
+ * process. Clearing is always the STRICTER direction — an unmarked process
+ * takes the supervised route — so nothing widens by calling it.
+ */
+export declare function clearDaemonProcess(): void;
+/** Is this process the daemon runtime? */
+export declare function isDaemonProcess(): boolean;

package/dist/src/core/daemon-actor.js

@@ -0,0 +1,54 @@
+/**
+ * Is THIS process the daemon? (APRV-382.)
+ *
+ * One fact, held in one place, so the gated advance path can ask it without
+ * being told it. `log.advance.daemon` is autonomous in this repository's policy
+ * and `log.advance` is not, which means something has to decide which of the
+ * two a cycle asks under — and that decision must not be an argument a caller
+ * passes, because a field a caller sets is a self-reported field, and SPEC.md
+ * §11.1 invariant 4 says a self-reported field never reduces scrutiny.
+ *
+ * So the mark is set by the daemon runtime itself, at construction, and read
+ * from module state that no exported function will set on another process's
+ * behalf: {@link markDaemonProcess} takes no arguments and records
+ * `process.pid`, and {@link isDaemonProcess} answers true only while that
+ * recorded pid is still this process's own. A child inherits nothing — module
+ * state does not cross a `spawn` — so the advance child, which holds no
+ * authority by design, answers false here as it should.
+ *
+ * What this is NOT: a security boundary against code already running in the
+ * daemon's process. Anything executing there can call {@link markDaemonProcess}
+ * the way the daemon does. The boundary that keeps an agent out of this process
+ * is elsewhere and unchanged: `approval daemon run` and `approval up` classify
+ * `gate.self`, which this repository's policy leaves at the fail-closed manual
+ * default, so an agent cannot start a daemon unattended in the first place.
+ * What this module removes is the smaller and likelier failure — a future
+ * caller wiring the autonomous route through a struct field, in a session, by
+ * accident.
+ */
+/** The pid of the process that declared itself the daemon, or `null`. */
+let daemonPid = null;
+/**
+ * Declare this process the daemon runtime. Called by the daemon, and only by it.
+ *
+ * Idempotent, and argument-free on purpose: there is no spelling of this call
+ * that marks a process other than the caller's own.
+ */
+export function markDaemonProcess() {
+    daemonPid = process.pid;
+}
+/**
+ * Forget the mark. For tests, and for a runtime that stops being a daemon.
+ *
+ * Present so a suite can exercise both actors in one file without a second
+ * process. Clearing is always the STRICTER direction — an unmarked process
+ * takes the supervised route — so nothing widens by calling it.
+ */
+export function clearDaemonProcess() {
+    daemonPid = null;
+}
+/** Is this process the daemon runtime? */
+export function isDaemonProcess() {
+    return daemonPid !== null && daemonPid === process.pid;
+}
+//# sourceMappingURL=daemon-actor.js.map

package/dist/src/core/daemon-actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-actor.js","sourceRoot":"","sources":["../../../src/core/daemon-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,yEAAyE;AACzE,IAAI,SAAS,GAAkB,IAAI,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,eAAe;IAC7B,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,OAAO,CAAC,GAAG,CAAC;AACzD,CAAC"}