approval-md 0.0.1 → 0.2.0

package/dist/src/core/coverage.js

@@ -0,0 +1,337 @@
+/**
+ * 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 { payloadOf } from "./state.js";
+/** How far BACK of an effect a record may sit and still be about it: 24 hours. */
+export const COVERAGE_LOOKBACK_MS = 24 * 60 * 60 * 1000;
+/**
+ * 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 const COVERAGE_AHEAD_MS = 5 * 60 * 1000;
+/** The record types that can be evidence, in the order they occur in a life. */
+export const EVIDENCE_EVENTS = [
+    "task.registered",
+    "approval.granted",
+    "execution.started",
+    "execution.completed",
+];
+/**
+ * The classes a record declares, as a set.
+ *
+ * Four shapes, because four record types say it four ways and one reader is
+ * better than four:
+ *
+ * - `payload.class` — what `approval.requested`, `approval.granted` and
+ *   `execution.started` carry;
+ * - `payload.actions[].class` — what `task.registered` carries, because one
+ *   registration declares every action of the task;
+ * - the class of the `execution.started` sharing this record's `action_key`,
+ *   for an `execution.completed`, which records an outcome and not a class;
+ * - nothing, for a record that declares none. Such a record is evidence for no
+ *   effect, which is the fail-closed direction: an unclassified record must not
+ *   cover an effect of a class it never named.
+ */
+function classesOf(record, startedClasses) {
+    const found = new Set();
+    const payload = payloadOf(record);
+    const direct = payload["class"];
+    if (typeof direct === "string" && direct.length > 0)
+        found.add(direct);
+    const actions = payload["actions"];
+    if (Array.isArray(actions)) {
+        for (const action of actions) {
+            if (typeof action !== "object" || action === null || Array.isArray(action))
+                continue;
+            const cls = action["class"];
+            if (typeof cls === "string" && cls.length > 0)
+                found.add(cls);
+        }
+    }
+    if (found.size === 0) {
+        const key = record.action_key;
+        if (typeof key === "string") {
+            for (const cls of startedClasses.get(key) ?? [])
+                found.add(cls);
+        }
+    }
+    return found;
+}
+/**
+ * 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 function classFamily(cls) {
+    const parts = cls.split(".");
+    return parts.length <= 2 ? cls : `${parts[0]}.${parts[1]}`;
+}
+/**
+ * The provider references the log carries, keyed by adapter and id (APRV-251).
+ *
+ * Built from `execution.completed` records alone, because that is the only event
+ * SPEC.md §8 lets carry one. EARLIEST wins, on the same reasoning the
+ * class-and-window rule uses: records arrive in seq order, and a later record
+ * naming the same effect cannot improve on the first one that did.
+ *
+ * The key is the pair. An id alone would let one provider's identifier be read
+ * as evidence about another provider's effect that happens to share the string,
+ * and the pair costs nothing: the source name a witness reports (`agentmail`) is
+ * the adapter name the contract wrote (`agentmail`), because the same adapter is
+ * both the executor and the observer. A source whose name does not match the
+ * adapter that executed simply falls through to the class-and-window rule, which
+ * is the weaker answer rather than a wrong one.
+ */
+function providerRefIndex(records) {
+    const found = new Map();
+    for (const record of records) {
+        if (record.event !== "execution.completed")
+            continue;
+        const ref = payloadOf(record)["provider_ref"];
+        if (typeof ref !== "object" || ref === null || Array.isArray(ref))
+            continue;
+        const { adapter, id } = ref;
+        if (typeof adapter !== "string" || adapter.length === 0)
+            continue;
+        if (typeof id !== "string" || id.length === 0)
+            continue;
+        const key = providerRefKey(adapter, id);
+        if (!found.has(key))
+            found.set(key, { seq: record.seq, event: record.event });
+    }
+    return found;
+}
+/** The index key: a NUL separator, which neither half can contain. */
+function providerRefKey(adapter, id) {
+    return `${adapter}\u0000${id}`;
+}
+/** The guard's verdict for `path`, or `null` when the report has none that passed. */
+function guardVerdict(guard, path) {
+    if (guard === undefined || guard === null || path === undefined)
+        return null;
+    for (const finding of guard.findings) {
+        if (finding.path !== path || !finding.ok)
+            continue;
+        // `granted-command` is deliberately not surfaced here. It is the guard's
+        // weakest verdict — a run attributed by time rather than by bytes — and
+        // reporting it beside `attested` under one column would flatten exactly the
+        // distinction the guard spent its module note drawing. Such a path falls
+        // through to the class-and-window rule below, which is the same strength of
+        // claim and is labelled as such.
+        if (finding.evidence === "attested" || finding.evidence === "granted-file") {
+            return finding.evidence;
+        }
+    }
+    return null;
+}
+/** A timestamp in milliseconds, or `null` when it does not parse. */
+function instant(ts) {
+    const at = Date.parse(ts);
+    return Number.isNaN(at) ? null : at;
+}
+/**
+ * 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 function coverageReport(effects, records, options = {}) {
+    const lookbackMs = options.lookbackMs ?? COVERAGE_LOOKBACK_MS;
+    const aheadMs = options.aheadMs ?? COVERAGE_AHEAD_MS;
+    // One pass to learn which class each action key was started under, so an
+    // `execution.completed` (which records an outcome and no class) can be read
+    // as evidence for the class its own start declared.
+    const startedClasses = new Map();
+    for (const record of records) {
+        if (record.event !== "execution.started")
+            continue;
+        const key = record.action_key;
+        const cls = payloadOf(record)["class"];
+        if (typeof key !== "string" || typeof cls !== "string" || cls.length === 0)
+            continue;
+        const bucket = startedClasses.get(key);
+        if (bucket === undefined)
+            startedClasses.set(key, new Set([cls]));
+        else
+            bucket.add(cls);
+    }
+    /** The candidate records, pre-reduced to (seq, event, ts, classes). */
+    const candidates = records
+        .filter((record) => EVIDENCE_EVENTS.includes(record.event))
+        .map((record) => ({
+        seq: record.seq,
+        event: record.event,
+        at: instant(record.ts),
+        classes: classesOf(record, startedClasses),
+    }))
+        .filter((candidate) => candidate.at !== null && candidate.classes.size > 0);
+    // APRV-251. Read once, consulted per effect.
+    const references = providerRefIndex(records);
+    const entries = [];
+    for (const effect of effects) {
+        // The id-level answer outranks both the guard's and the window's, and it is
+        // the only one of the three that is about this effect rather than about a
+        // class, a path or a span of time.
+        const named = references.get(providerRefKey(effect.source, effect.id));
+        if (named !== undefined) {
+            entries.push({ effect, evidence: named, match: "provider-ref" });
+            continue;
+        }
+        const verdict = guardVerdict(options.guard, effect.path);
+        if (verdict !== null) {
+            entries.push({ effect, evidence: { verdict }, match: "protected-path" });
+            continue;
+        }
+        const when = instant(effect.at);
+        if (when === null) {
+            // An effect whose timestamp does not parse cannot be placed against any
+            // record, and inventing a placement would be the report asserting
+            // something no witness said. It is a gap, and it is a gap for a reason a
+            // reader can see in the detail line the source wrote.
+            entries.push({ effect, evidence: null, match: "none" });
+            continue;
+        }
+        const family = classFamily(effect.class);
+        let exact = null;
+        let loose = null;
+        for (const candidate of candidates) {
+            const at = candidate.at;
+            if (at < when - lookbackMs || at > when + aheadMs)
+                continue;
+            if (candidate.classes.has(effect.class)) {
+                // EARLIEST wins: records arrive in seq order, so the first exact match
+                // seen is the earliest one and nothing later can improve on it.
+                if (exact === null)
+                    exact = { seq: candidate.seq, event: candidate.event };
+                break;
+            }
+            if (loose === null) {
+                for (const cls of candidate.classes) {
+                    if (classFamily(cls) === family) {
+                        loose = { seq: candidate.seq, event: candidate.event };
+                        break;
+                    }
+                }
+            }
+        }
+        if (exact !== null)
+            entries.push({ effect, evidence: exact, match: "exact" });
+        else if (loose !== null)
+            entries.push({ effect, evidence: loose, match: "family" });
+        else
+            entries.push({ effect, evidence: null, match: "none" });
+    }
+    const bySource = totalsBy(entries, (entry) => entry.effect.source);
+    const byClass = totalsBy(entries, (entry) => entry.effect.class);
+    return {
+        entries,
+        bySource,
+        byClass,
+        observed: entries.length,
+        covered: entries.filter((entry) => entry.evidence !== null).length,
+    };
+}
+/** Observed and covered counts per key, sorted by key. */
+function totalsBy(entries, keyOf) {
+    const totals = new Map();
+    for (const entry of entries) {
+        const key = keyOf(entry);
+        const existing = totals.get(key) ?? { key, observed: 0, covered: 0 };
+        existing.observed += 1;
+        if (entry.evidence !== null)
+            existing.covered += 1;
+        totals.set(key, existing);
+    }
+    return [...totals.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+//# sourceMappingURL=coverage.js.map

package/dist/src/core/coverage.js.map

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

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/credential-spec.js

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=credential-spec.js.map

package/dist/src/core/credential-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-spec.js","sourceRoot":"","sources":["../../../src/core/credential-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}