approval-md 0.0.1 → 0.2.0

package/dist/src/core/coverage-sources/git.js

@@ -0,0 +1,269 @@
+/**
+ * The git coverage source (APRV-245).
+ *
+ * Git history is the cheapest witness this project has that it does not write:
+ * a commit, a merge into the trunk and a tag are all effects an agent produced,
+ * all recorded by a tool with no idea approval.md exists, and all readable back
+ * long after the session that made them is gone.
+ *
+ * **Never the working tree.** Every fact here comes from `git log`, `git show`
+ * and `git for-each-ref` over committed objects. An uncommitted edit is not an
+ * effect yet — it is a file a person can still delete — and reading the tree
+ * would make the report depend on whatever happened to be lying around when it
+ * ran, which is the opposite of the determinism a witness needs.
+ *
+ * ## The class mapping
+ *
+ * The classes are SPEC.md §7's own, spelled as `core/command-class.ts` spells
+ * them, because a source that invented a class would produce effects no record
+ * could ever match:
+ *
+ * - a commit REACHABLE FROM `origin/main` is `vcs.push.main`. What the class
+ *   names is the trunk moving, and a commit on the trunk moved it however it
+ *   got there (a merge, a fast-forward, a direct push);
+ * - a commit the trunk does not reach but SOME remote-tracking ref does
+ *   (`refs/remotes/*`) is `vcs.push.branch`, which is the class the classifier
+ *   gives `git push origin <branch>`: the commit left the machine, and the
+ *   action a task declares for that is the push, never the commit;
+ * - any other commit in the range is `vcs.commit.branch`, which is the class the
+ *   classifier gives a bare `git commit`: it exists only here;
+ * - a tag is `release.publish`, which is the class the classifier gives
+ *   `git tag`;
+ * - a protected path a commit changed is `policy.edit`, reported as its own
+ *   effect carrying the `path`, so `core/coverage.ts` can put the
+ *   protected-path guard's byte-level verdict against it rather than the
+ *   class-and-window rule.
+ *
+ * A merge commit is a `vcs.push.main` like any other trunk commit and says so in
+ * its detail line; it is not given a class of its own, because the policy has
+ * none for it and an effect nobody can declare is an effect nothing can cover.
+ *
+ * Nothing here reads the clock: every timestamp is git's author date for the
+ * object being reported.
+ */
+import { isProtectedPath } from "../command-class.js";
+import { git } from "../git-run.js";
+/** The default trunk ref. Overridable so a fork with another name still reports. */
+export const DEFAULT_TRUNK_REF = "origin/main";
+/**
+ * How many commits one run will describe.
+ *
+ * A bound rather than a stream, because each commit costs one `git show` for
+ * its changed paths and an unbounded range would turn a reporting verb into a
+ * repository walk. A truncated run says so in the source's `reason`, so the
+ * number is never quietly wrong.
+ */
+export const MAX_COMMITS = 200;
+/** The unit separator: it cannot occur in a subject line or an email address. */
+const SEP = "";
+const LOG_FORMAT = ["%H", "%aI", "%aE", "%aN", "%P", "%s"].join(SEP);
+function parseCommits(stdout) {
+    const commits = [];
+    for (const line of stdout.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        const parts = line.split(SEP);
+        if (parts.length < 6)
+            continue;
+        commits.push({
+            sha: parts[0],
+            at: parts[1],
+            email: parts[2],
+            name: parts[3],
+            parents: parts[4].split(" ").filter((word) => word.length > 0),
+            subject: parts[5],
+        });
+    }
+    return commits;
+}
+/** The paths one commit changed, from `git show`. Empty when git could not say. */
+function changedPaths(root, sha) {
+    const shown = git(["show", "--no-color", "--pretty=format:", "--name-only", sha], root);
+    if (!shown.ok)
+        return [];
+    return shown.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+/** A short sha, the way a person reads one. */
+function short(sha) {
+    return sha.slice(0, 12);
+}
+/** The first non-empty line of whatever a failed command printed. */
+export function firstLine(text) {
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    return "no output";
+}
+/**
+ * What git witnessed between `base` and `head`.
+ *
+ * Never throws: a directory that is not a repository, a ref that does not
+ * resolve and an absent git all come back as `available: false` with the reason
+ * git printed. A reporting verb that crashed on a checkout without a remote
+ * would be a verb people stop running.
+ */
+export function observeGit(root, options) {
+    const unavailable = (reason) => ({
+        name: "git",
+        available: false,
+        reason,
+        effects: [],
+    });
+    const inside = git(["rev-parse", "--show-toplevel"], root);
+    if (!inside.ok)
+        return unavailable("not a git checkout");
+    const range = `${options.base}..${options.head}`;
+    const listed = git(["log", `--format=${LOG_FORMAT}`, range], root);
+    if (!listed.ok) {
+        return unavailable(`git log ${range} failed: ${firstLine(listed.stderr)}`);
+    }
+    const all = parseCommits(listed.stdout);
+    const max = options.maxCommits ?? MAX_COMMITS;
+    const commits = all.slice(0, max);
+    // The trunk set, in ONE call: `rev-list <range> --not <trunk>` names the
+    // commits of the range that the trunk does NOT reach, so everything else in
+    // the range does. Asking `merge-base --is-ancestor` per commit would be one
+    // process per commit for the same answer.
+    const trunk = options.trunk ?? DEFAULT_TRUNK_REF;
+    const offTrunk = new Set();
+    let trunkKnown = false;
+    const excluded = git(["rev-list", range, "--not", trunk], root);
+    if (excluded.ok) {
+        trunkKnown = true;
+        for (const line of excluded.stdout.split("\n")) {
+            const sha = line.trim();
+            if (sha.length > 0)
+                offTrunk.add(sha);
+        }
+    }
+    // The published set, the same way: `rev-list <range> --not --remotes` names
+    // the commits no remote-tracking ref reaches, so everything else in the range
+    // has been pushed somewhere. A checkout with no remotes answers with the whole
+    // range, which is the right answer: nothing there has left the machine.
+    const unpublished = new Set();
+    let remotesKnown = false;
+    const local = git(["rev-list", range, "--not", "--remotes"], root);
+    if (local.ok) {
+        remotesKnown = true;
+        for (const line of local.stdout.split("\n")) {
+            const sha = line.trim();
+            if (sha.length > 0)
+                unpublished.add(sha);
+        }
+    }
+    const protectedPaths = options.policyProtectedPaths ?? [];
+    const effects = [];
+    for (const commit of commits) {
+        // With no trunk ref to compare against (a checkout with no remote, a fresh
+        // fixture repository), every commit is reported as a branch commit. That is
+        // the lower claim about an unknown, and the source says the trunk was
+        // unknown in its own reason so the choice stays visible.
+        const onTrunk = trunkKnown && !offTrunk.has(commit.sha);
+        const pushed = remotesKnown && !unpublished.has(commit.sha);
+        const merge = commit.parents.length > 1;
+        const who = commit.email.length > 0 ? commit.email : commit.name;
+        effects.push({
+            source: "git",
+            id: commit.sha,
+            class: onTrunk ? "vcs.push.main" : pushed ? "vcs.push.branch" : "vcs.commit.branch",
+            at: commit.at,
+            actorHint: who.length > 0 ? who : null,
+            detail: `${merge ? "merge " : ""}commit ${short(commit.sha)} ${commit.subject}`,
+        });
+        for (const path of changedPaths(root, commit.sha)) {
+            if (!isProtectedPath(path, protectedPaths))
+                continue;
+            effects.push({
+                source: "git",
+                id: `${short(commit.sha)}:${path}`,
+                class: "policy.edit",
+                at: commit.at,
+                actorHint: who.length > 0 ? who : null,
+                detail: `${path} changed by ${short(commit.sha)}`,
+                path,
+            });
+        }
+    }
+    for (const tag of observeTags(root, new Set(commits.map((commit) => commit.sha)))) {
+        effects.push(tag);
+    }
+    const notes = [];
+    if (all.length > commits.length) {
+        notes.push(`${all.length - commits.length} older commit(s) beyond the ${max}-commit bound are not reported`);
+    }
+    if (!trunkKnown)
+        notes.push(`${trunk} does not resolve, so no commit is reported as trunk`);
+    return {
+        name: "git",
+        available: true,
+        ...(notes.length === 0 ? {} : { reason: notes.join("; ") }),
+        effects,
+    };
+}
+/** Tags whose target commit is inside the range, from `git for-each-ref`. */
+function observeTags(root, inRange) {
+    const format = [
+        "%(refname:short)",
+        "%(creatordate:iso-strict)",
+        "%(objectname)",
+        "%(*objectname)",
+        "%(taggeremail)",
+    ].join(SEP);
+    const listed = git(["for-each-ref", `--format=${format}`, "refs/tags"], root);
+    if (!listed.ok)
+        return [];
+    const effects = [];
+    for (const line of listed.stdout.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        const parts = line.split(SEP);
+        if (parts.length < 5)
+            continue;
+        const name = parts[0];
+        const at = parts[1];
+        // An annotated tag's `%(objectname)` is the tag object and `%(*objectname)`
+        // the commit it points at; a lightweight tag has only the first.
+        const starred = parts[3];
+        const target = starred.length > 0 ? starred : parts[2];
+        if (!inRange.has(target))
+            continue;
+        const tagger = parts[4].replace(/^<|>$/gu, "");
+        effects.push({
+            source: "git",
+            id: `tag:${name}`,
+            // `git tag` classifies release.publish (core/command-class.ts), and a tag
+            // in this project's history is how a release is cut.
+            class: "release.publish",
+            at,
+            actorHint: tagger.length > 0 ? tagger : null,
+            detail: `tag ${name} on ${short(target)}`,
+        });
+    }
+    return effects;
+}
+/**
+ * The default commit range: `merge-base <trunk> HEAD`, falling back to `HEAD~20`.
+ *
+ * The fallback is announced rather than silent. A checkout with no `origin/main`
+ * (a fresh clone of a fork, a fixture repository, a detached CI checkout) has no
+ * merge base to take, and a range of "the last twenty commits" is a guess; a
+ * reader has to be able to see that the answer they are looking at came from a
+ * guess and not from the trunk.
+ */
+export function defaultRange(root, trunk = DEFAULT_TRUNK_REF) {
+    const merged = git(["merge-base", trunk, "HEAD"], root);
+    const sha = merged.stdout.trim();
+    if (merged.ok && sha.length > 0)
+        return { base: sha, head: "HEAD" };
+    return {
+        base: "HEAD~20",
+        head: "HEAD",
+        note: `${trunk} does not resolve here, so the range is the last 20 commits rather than everything since the trunk`,
+    };
+}
+//# sourceMappingURL=git.js.map

package/dist/src/core/coverage-sources/git.js.map

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

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;