approval-md 0.1.0 → 0.3.0

package/dist/src/core/dark-session.d.ts

@@ -0,0 +1,432 @@
+/**
+ * The dark-session detector (APRV-192): the log is asked what git already knows.
+ *
+ * ## The hole this closes
+ *
+ * APRV-151 built the CI-side grant cross-check, and its root cause is the thing
+ * that check cannot reach. A session whose harness never invoked the hook writes
+ * NO records at all: not a grant, not a refusal, not a request. Nothing inside
+ * such a session is in a position to notice, because the component that would
+ * have written the record is the component that did not run, and asking a
+ * session whether it is hooked asks the party under oversight to report its own
+ * oversight (SPEC.md §11). The CI guard sees only the diffs that reach a pull
+ * request; a session that ran dark and pushed nothing, or pushed to a branch
+ * nobody opened a pull request for, leaves the guard with nothing to read.
+ *
+ * So the direction is reversed. APRV-42's git evidence asks "does every log
+ * entry match git?"; this asks **"does every piece of git activity match a log
+ * entry?"** Git is the artifact a session cannot help producing: a commit has an
+ * author, a date and a tree, a linked worktree has a root and a birth, and none
+ * of those is authored by the runtime's hook. The absence of a record beside
+ * them is the signal.
+ *
+ * ## Two arms, because there are two questions
+ *
+ * **Arm A, evidence.** For each commit in the window, every guarded path it
+ * changed must carry evidence in the verified log that a human decided it. This
+ * is not reimplemented: it is {@link evaluateProtectedPaths}, APRV-151's own
+ * evaluator, called per commit, so the verdict vocabulary (`attested`,
+ * `granted-file`, `granted-command`), the recency bound, the exempt evidence
+ * surface and the `no-evidence` code are one implementation with two callers.
+ * Arm A runs over EVERY checkout, the primary included, because a guarded-path
+ * commit with no evidence is dark wherever it was made.
+ *
+ * **Arm B, silence.** A linked worktree that produced commits in the window (or
+ * that came into existence in it) and to which NOT ONE record in the window can
+ * be attributed is a dark session, whatever it touched. This is the arm that
+ * catches the APRV-151 root cause on paths the CI guard never sees, and it is
+ * the arm that needs an attribution rule.
+ *
+ * ## How a record is attributed to a worktree
+ *
+ * Hook task ids are `hook:<session>:<tool-use>` and carry no checkout, so the
+ * id is not the key. The bound material is. Every gated file-tool call binds
+ * `{tool, rule, file, …}` with `file` ABSOLUTE (`cli/hook.ts`), and every gated
+ * shell call binds `{command, cwd}` with `cwd` absolute. A record whose bound
+ * material names a path inside a worktree root was written by a session working
+ * in that worktree. That is PR #169's checkout-root anchoring, which APRV-151's
+ * notes recorded as the stronger answer to the two-checkouts problem and did not
+ * have a caller for; it has one now.
+ *
+ * The branch name is the second key, and a weak one: a branch `aprv-192-…`
+ * names task `APRV-192`, and a `task.registered` for that id in the window is
+ * attribution. Weak because a branch name is chosen by the party under
+ * oversight, so it may only ever ADD attribution (SPEC.md §11.1 invariant 4:
+ * a self-reported field may raise scrutiny and never lower it) — which is
+ * exactly what it does here, since attribution is what stops an alarm. Stated
+ * plainly rather than hidden: a session that names its branch after a task some
+ * other session registered escapes arm B. It does not escape arm A, and the
+ * cost of the alternative (no branch key at all) is an alarm on every worktree
+ * whose session worked entirely outside the payload store's reach.
+ *
+ * ## What unit arm A judges, merges included (APRV-374)
+ *
+ * One commit, base to commit, which is the unit a grant binds and the unit the
+ * CI guard judges since APRV-375. The inputs are built by
+ * `core/commit-guard.ts`, so the two sides cannot drift apart.
+ *
+ * A MERGE commit is judged on what it invented and on nothing else. `git log
+ * --name-only` reports no path at all for a merge, so until APRV-374 every
+ * merge dropped out of arm A, which is right for an ordinary merge and wrong
+ * for the evil one: a conflict resolution, or a hand edit made while resolving,
+ * is the merge commit's own work, made in the checkout that made the merge, and
+ * no other commit carries those bytes. So a merge is judged for the paths whose
+ * DENSE COMBINED PATCH (`git log --cc`, {@link denseCombinedPaths}) is
+ * non-empty, against its FIRST PARENT, which is the state the checkout was in
+ * before the merge and therefore the before-state a grant for the resolution
+ * would have bound.
+ *
+ * The dense patch and not `--cc --name-only`, which over-reports: a merge blob
+ * differs from every parent blob whenever both sides edited one file, so
+ * `--name-only` lists a file two lanes happened to edit concurrently and git
+ * merged without a human in the room. Replaying that as the merge's own change
+ * would report dark for work every side of it had evidence for, which is the
+ * class of false alarm APRV-369 and APRV-375 exist to remove. The dense patch
+ * is empty for exactly those merges and non-empty for the resolutions.
+ *
+ * Scope is the guard's scope: guarded paths. A merge that resolved a conflict
+ * in a file no policy protects is not this detector's business, so the dense
+ * question is only ever asked about paths {@link isGuardedPath} accepts.
+ *
+ * ## Fail closed in the report
+ *
+ * Uncertainty is never "fine". A log that does not verify, a payload whose
+ * bytes will not resolve, a commit git could not date, a worktree whose root
+ * cannot be placed: each is its own `undetermined` verdict with its own code,
+ * counted separately from the clean ones, and the renderer never folds an
+ * undetermined subject into the pass count. What this module does NOT do is
+ * escalate on uncertainty, because a detector is not an enforcement path: it
+ * reports, a human reads, and nothing here changes what the gate authorizes.
+ *
+ * ## What keeps the human's own commits quiet (AC4)
+ *
+ * Three exemptions, narrow and documented, and each of them fails NOISY when it
+ * does not apply:
+ *
+ * 1. A commit that touches only the daemon's own append surface
+ *    ({@link EXEMPT_PREFIXES}) is a records advance carrying evidence, not a
+ *    session doing work. Requiring evidence for the evidence is circular.
+ * 2. A commit authored by the git-evidence identity is the daemon's own
+ *    (`daemon/git-evidence.ts`), and the daemon is not a session.
+ * 3. Arm B's subject is LINKED WORKTREES ONLY. The agent-session artifact is
+ *    the worktree; the human commits in the primary checkout, where the policy
+ *    ceremony and the genesis events are made. The primary is not thereby
+ *    passed: it stays wholly subject to arm A, so a ceremony commit passes on
+ *    its attestation and an unevidenced guarded-path commit there is still
+ *    reported. And the limit is stated on every report as its own coverage
+ *    line, so an agent session that ran in the primary checkout shows up as a
+ *    gap in the report rather than as silence.
+ *
+ * ## Layout
+ *
+ * The evaluator ({@link evaluateDarkSessions}) takes no clock and reads no
+ * file, so a fixture drives everything but arm A's replay: the ONE thing it
+ * runs git for is reading the blobs of a commit it is judging, which cannot be
+ * carried in the observation because which blobs are wanted is not known until
+ * the verdict is being computed. A fixture whose commits change no guarded path
+ * needs no repository at all. The observing half below the fold runs the rest
+ * of the git and reads the payload store,
+ * and it lives here rather than under `daemon/` because `approval doctor`
+ * reports the same findings and `src/cli/` may not import `src/daemon/`
+ * (APRV-59). The one thing that stays in `daemon/dark-session.ts` is the
+ * append, which is the one thing a reader must never do.
+ */
+import type { ProtectedPathEntry } from "./command-class.js";
+import { type Clock } from "./clock.js";
+import type { EventRecord } from "./log.js";
+/**
+ * The events a hooked session cannot avoid writing.
+ *
+ * A registration opens the question, a request puts it to a human, and a start
+ * records that something ran. A session that made any gated tool call at all
+ * wrote at least one of these; a session that wrote none of them made no gated
+ * call the runtime ever saw, which is the definition of dark.
+ */
+export declare const SESSION_EVENTS: readonly string[];
+/**
+ * How a subject came out. **Frozen union**, additive-only, in the same sense as
+ * every other verdict vocabulary here (SPEC.md §11.1 invariant 6).
+ */
+export declare const DARK_SESSION_VERDICTS: readonly ["hooked", "dark", "exempt", "undetermined"];
+export type DarkSessionVerdict = (typeof DARK_SESSION_VERDICTS)[number];
+/**
+ * Why a subject got the verdict it got. **Frozen union**, additive-only.
+ *
+ * `no-evidence` is spelled exactly as APRV-151 spells it, because it IS
+ * APRV-151's finding, arrived at through the same evaluator.
+ */
+export declare const DARK_SESSION_CODES: readonly [
+/** Arm B: git activity in the window, and not one attributable record. */
+"no-records", 
+/** Arm A: a guarded path changed and the log carries no evidence for it. */
+"no-evidence", 
+/**
+ * Arm A, and EVERY failing commit arrived here through a merge (APRV-369).
+ *
+ * The same failure as `no-evidence` and the same `dark` verdict — nothing is
+ * excused by it — reported under its own code because the checkout it names
+ * is the one that SYNCED the change rather than the one that made it. The
+ * repair is in whatever branch or worktree authored the commit, which the
+ * detail names.
+ */
+"no-evidence-merged", 
+/** Exempt: the commits touch only the daemon's own append surface. */
+"evidence-surface", 
+/** Exempt: authored by the daemon's own git identity. */
+"daemon-authored", 
+/** Exempt from arm B (never from arm A): the primary checkout. */
+"primary-checkout", 
+/** Undetermined: the log did not verify, so nothing may be read from it. */
+"log-unverified", 
+/** Undetermined: git could not be run, or answered nothing. */
+"git-unavailable", 
+/** Undetermined: bound material would not resolve, so records cannot be placed. */
+"payload-unresolvable", 
+/** Undetermined: git named no usable date for the activity. */
+"activity-undated"];
+export type DarkSessionCode = (typeof DARK_SESSION_CODES)[number];
+/**
+ * The codes a `dark` verdict can carry, and therefore the ones that reach the
+ * log on an `audit.dark_session` record (APRV-369).
+ *
+ * A separate, smaller list than {@link DARK_SESSION_CODES} because it is the
+ * one the event schema constrains: an exempt or undetermined subject is never
+ * recorded, so its code has no business in a write-boundary enum. Pinned equal
+ * to that enum by a test, for the reason APRV-358 gave: a code the sweep can
+ * produce and the schema refuses is an observation that never reaches a human,
+ * and nothing fails loudly when it happens.
+ */
+export declare const DARK_VERDICT_CODES: readonly ["no-records", "no-evidence", "no-evidence-merged"];
+/** One commit the observer saw, as git reported it. */
+export interface ObservedCommit {
+    /** The full sha. */
+    sha: string;
+    /** Author instant, ISO-8601, or `null` when git would not say. */
+    ts: string | null;
+    /** `Name <email>`, verbatim from git. */
+    author: string;
+    /** The author's email alone, lowercased, or `""` when git named none. */
+    authorEmail: string;
+    /**
+     * Repository-relative, `/`-separated paths this commit changed.
+     *
+     * For a MERGE commit these are the guarded paths whose result differs from
+     * every parent hunk by hunk — the merge's own resolution work, and nothing
+     * its parents did (APRV-374). An ordinary merge has none.
+     */
+    changedPaths: readonly string[];
+    /**
+     * The commit's parents in git's own order, when the observer asked.
+     *
+     * OPTIONAL, and absence means "unknown", which the per-commit input builder
+     * reads as "assume it has a parent": the modest direction, since the base it
+     * then judges against is the first parent rather than nothing at all.
+     * Two or more parents is what makes a commit a merge here.
+     */
+    parents?: readonly string[];
+    /** The branch or worktree this commit was observed on, for the message. */
+    ref: string;
+    /**
+     * Did this commit reach the checkout through a merge rather than being made
+     * on it? (APRV-369.)
+     *
+     * True when the commit is reachable from the observed HEAD but is NOT on its
+     * first-parent history, which is what "somebody else's branch was merged in"
+     * looks like in git: a lane's commits, a contributor's, or anything that
+     * arrived by fast-forward from the trunk. A commit made in this checkout and
+     * committed on the branch it is standing on is on the first-parent path and
+     * is `false`.
+     *
+     * OPTIONAL, and absence means `false` — attributed to this checkout. That is
+     * the direction that keeps a caller written before this field existed
+     * honest: an observer that cannot say where a commit came from must not be
+     * read as saying it came from somewhere else.
+     */
+    arrivedByMerge?: boolean;
+}
+/** One checkout the observer saw: the primary, or a linked worktree. */
+export interface ObservedCheckout {
+    /** Absolute, symlink-resolved root. */
+    root: string;
+    /** How it is named in the report (the worktree directory's base name). */
+    name: string;
+    /** True for the primary checkout, false for a linked worktree. */
+    primary: boolean;
+    /** The checked-out branch, or `null` on a detached HEAD. */
+    branch: string | null;
+    /** Its birth instant, when the observer could stat it; else `null`. */
+    born: string | null;
+    /** Commits observed on it inside the window. */
+    commits: readonly ObservedCommit[];
+}
+/** What the observer gathered, and what it could not. */
+export interface GitActivity {
+    checkouts: readonly ObservedCheckout[];
+    /**
+     * Why git could not be asked, when it could not. A non-null value makes every
+     * subject `undetermined` rather than passing them for lack of evidence.
+     */
+    unavailable: string | null;
+}
+/** The window the sweep judged, as instants. */
+export interface DarkSessionWindow {
+    from: string;
+    to: string;
+}
+export interface DarkSessionInput {
+    activity: GitActivity;
+    /**
+     * Records from the log that have passed chain verification, or `null` when it
+     * did not verify. `null` makes every subject `undetermined`; nothing here
+     * reads an unverified record (SPEC.md §11.1 invariant 1).
+     */
+    records: readonly EventRecord[] | null;
+    /** Why the log could not be used, when `records` is `null`. */
+    logDetail?: string;
+    /** `policy.protected_paths`, widening the built-in guarded set. */
+    policyProtectedPaths: readonly ProtectedPathEntry[];
+    /** The policy file's repository-relative path, e.g. `APPROVAL.md`. */
+    policyPath: string;
+    /** SHA-256 of the policy bytes now on disk, for the `attested` verdict. */
+    policySha256: string | null;
+    /** Resolve bound material by hash from the live payload store. */
+    payloadFor: (hash: string) => unknown | null;
+    /** Author emails whose commits are the daemon's own, lowercased. */
+    daemonEmails: readonly string[];
+    /** The instants the observer swept between. */
+    window: DarkSessionWindow;
+    /** Override the recency bound `evaluateProtectedPaths` applies. */
+    lookbackMs?: number;
+}
+/** One subject's verdict. A subject is one checkout. */
+export interface DarkSessionFinding {
+    /** The checkout's name — the worktree directory, or `primary`. */
+    subject: string;
+    root: string;
+    primary: boolean;
+    branch: string | null;
+    verdict: DarkSessionVerdict;
+    code: DarkSessionCode | null;
+    /** Commits observed on this subject in the window. */
+    commits: number;
+    /** Guarded paths this subject changed in the window. */
+    guardedPaths: readonly string[];
+    /** Records in the window attributed to this subject. */
+    attributed: readonly number[];
+    /**
+     * The newest sha observed on this subject, or `null` when it produced no
+     * commit. Half of the observation key: an alarm is about a state of the
+     * world, and the same state must not be recorded twice.
+     */
+    newestSha: string | null;
+    /** Stable across ticks for one observation; see {@link observationKey}. */
+    key: string;
+    /** Prose a reader can act on, on every verdict. */
+    detail: string;
+}
+export interface DarkSessionReport {
+    /** True when no subject came out `dark`. Says nothing about what was seen. */
+    ok: boolean;
+    /**
+     * True when every subject was ESTABLISHED, one way or the other.
+     *
+     * Kept separate from {@link DarkSessionReport.ok} on purpose. A report with
+     * no dark subject and three undetermined ones is not a clean sweep, and a
+     * single boolean would have to lie about one of the two facts: either it
+     * alarms on uncertainty (and an operator learns to ignore the alarm) or it
+     * calls uncertainty fine (and the detector reports a pass it did not earn).
+     * Two booleans say both things, and every surface reads the one it means.
+     */
+    settled: boolean;
+    findings: readonly DarkSessionFinding[];
+    window: DarkSessionWindow;
+    /**
+     * What this sweep could not see, always stated. Arm B covers linked worktrees
+     * only, so a session that ran in the primary checkout is outside it, and a
+     * report that did not say so would be claiming coverage it does not have.
+     */
+    coverage: string;
+}
+/** The observation key: one subject, one state of the world. */
+export declare function observationKey(subject: string, newestSha: string | null, born: string | null): string;
+/** The Backlog.md task id a branch name begins with, upper-cased (`aprv-192-x`). */
+export declare function taskIdFromBranch(branch: string | null): string | null;
+/**
+ * Evaluate what git showed against what the log carries. Pure: no IO, no clock.
+ */
+export declare function evaluateDarkSessions(input: DarkSessionInput): DarkSessionReport;
+/** The report as lines an operator reads. Pure. */
+export declare function renderDarkSessionReport(report: DarkSessionReport): string;
+/**
+ * Everything below this line does IO, and it lives here rather than in
+ * `daemon/` for one reason: `approval doctor` reports the same findings and
+ * `src/cli/` may not import `src/daemon/` (APRV-59, `tests/layering.test.ts`).
+ * Two observers would be two answers to one question, so there is one, and the
+ * daemon's module keeps only the thing a reader must never do — the append.
+ */
+/** How far back a sweep looks, absent an operator saying otherwise. */
+export declare const DEFAULT_DARK_WINDOW_MS: number;
+/** How often the sweep runs, absent an operator saying otherwise. */
+export declare const DEFAULT_DARK_INTERVAL_MS: number;
+/**
+ * The git identities whose commits are the runtime's own.
+ *
+ * Spelled here rather than imported from `daemon/git-evidence.ts`, which is
+ * where the daemon's commit identity is defined: core must not depend on the
+ * daemon. `tests/dark-session.test.ts` pins the two against each other so they
+ * cannot drift apart, the same device `APPROVALD_VERSION` uses for its own
+ * duplicate of the package version.
+ */
+export declare const DAEMON_EVIDENCE_EMAILS: readonly string[];
+/** The opt-in, as the daemon carries it. */
+export interface DarkSessionWatch {
+    /** How far back each sweep looks. */
+    windowMs: number;
+    /** How often a sweep runs. The tick interval is the floor. */
+    intervalMs: number;
+}
+/**
+ * Everything git could tell the sweep about a repository in one window.
+ *
+ * `protectedPaths` is the policy's `protected_paths`, and omitting it asks the
+ * merge question about the BUILT-IN guarded set only. That is the fail-closed
+ * direction for a caller that has no policy to hand: it narrows which merges
+ * are examined and never which evidence is required, and
+ * {@link reportDarkSessions} always passes the loaded list.
+ */
+export declare function observeGitActivity(root: string, from: string, to: string, protectedPaths?: readonly ProtectedPathEntry[]): GitActivity;
+export interface DarkSessionSweepOptions {
+    logPath: string;
+    /** The checkout to observe. The daemon's own `cwd`; never an agent worktree. */
+    root: string;
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    schemaDir?: string;
+    /** The write-boundary clock (amended SPEC.md §8). */
+    clock?: Clock;
+    windowMs: number;
+    /** Verified records. The caller has already read them; nothing re-reads. */
+    records: readonly EventRecord[] | null;
+    logDetail?: string;
+    /**
+     * Test seam: an observer that answers without running git.
+     *
+     * It is offered the policy's protected paths as a fourth argument, which the
+     * real observer needs to know which merges to ask git about (APRV-374); a
+     * seam that ignores it answers exactly as it did before.
+     */
+    observe?: (root: string, from: string, to: string, protectedPaths: readonly ProtectedPathEntry[]) => GitActivity;
+}
+/**
+ * Observe and judge, appending nothing.
+ *
+ * The read-only half, which is the half `approval doctor` calls: doctor reports
+ * and the daemon writes, so two processes never become two writers of one fact.
+ */
+export declare function reportDarkSessions(options: DarkSessionSweepOptions): {
+    report: DarkSessionReport;
+    window: DarkSessionWindow;
+};