approval-md 0.1.0 → 0.2.0

package/dist/src/core/prompt-layout.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Prompt layout: which INFORMATIONAL rows a channel puts in front of an
+ * approver, as a policy decision rather than a code decision (APRV-218).
+ *
+ * SPEC.md §5.2 gains `channels.<name>.prompt`; SPEC.md §10.3 already says a
+ * channel holds no truth, and this module is what keeps that so — the block
+ * decides what is SHOWN, never what is true, and every field it can reach was
+ * already on the `ChannelRequest` and already in `--json`, `approval queue` and
+ * the web page. Nothing here reads the log, and no key added here lets a
+ * channel learn anything about it.
+ *
+ * ## Why this is a policy key at all
+ *
+ * The Telegram prompt was slimmed deliberately: APRV-143 dropped the `ttl` row
+ * because the `waiting … expires HH:MM UTC` line already states the deadline,
+ * and APRV-163 dropped six bookkeeping rows and made three health rows render
+ * only when abnormal. That layout fits ONE operator's workflow. Another wants
+ * the budget line on every prompt, or the TTL as a duration, or the task id
+ * always visible. Those are preferences about a screen, and preferences about a
+ * screen belong in the policy file beside the other things an operator chooses,
+ * not in a `git blame` argument about a default.
+ *
+ * ## What a layout may NOT do
+ *
+ * A layout chooses among rows the approver may read. It cannot touch what the
+ * approver SIGNS. Three things are therefore out of its reach entirely:
+ *
+ * 1. **The canonical block** (SPEC.md §9's "what you see is what you sign") is
+ *    not a row. It carries the payload bytes, the renderer version, the class,
+ *    the kind and the bound `payload sha256`, it is rendered verbatim, and no
+ *    key in this module can reorder, shorten, or remove it.
+ * 2. **The computed/claimed split.** A row's side of the boundary is a property
+ *    of the field (`TaggedField.kind`), not of the layout. `rows` reorders; it
+ *    cannot move a claimed line into the computed block, because a channel
+ *    partitions by kind AFTER it applies the order. That is the property
+ *    APRV-144's CLAIMED heading exists for, and a test pins it.
+ * 3. **{@link REQUIRED_PROMPT_ROWS}**, the rows the contract marks as required
+ *    for a decision. Naming one in `hide` is a policy that fails to load.
+ *
+ * The buttons are not a row either, for the same reason the block is not: a
+ * prompt with no way to answer it is not a prompt.
+ *
+ * ## Fail directions
+ *
+ * Soft on ABSENCE, closed on INVALIDITY, which is the split every other policy
+ * key in this runtime keeps. No `prompt` block, or a policy that did not load,
+ * means today's rows: a layout is not a permission, and an unrelated typo in a
+ * class rule must not silently redecorate a phone screen. An unknown row name
+ * or a required row in `hide` is a statement the runtime cannot honour, so the
+ * WHOLE policy fails schema validation and every class resolves to `manual` —
+ * the operator repairs the file, and until they do the gate is at its
+ * strictest.
+ *
+ * Pure: no clock, no IO, no environment. It sits in `core/` rather than in
+ * `channels/` for `core/telegram-config.ts`'s reason — more than one layer asks
+ * "which rows does this policy want?" and none of them may answer differently —
+ * and it imports nothing from `channels/`, so `tests/layering.test.ts` stays
+ * true. The row names below are the `ChannelRequest` member names spelled as
+ * plain strings for exactly that reason.
+ */
+import type { Policy, PolicyLoadResult } from "./policy-load.js";
+import type { ValidationError } from "./validate.js";
+/**
+ * The row vocabulary: every `ChannelRequest` member a channel renders as a row.
+ *
+ * Closed, and closed for `delivery`'s reason (APRV-216): a name this runtime
+ * cannot place is a row the author believes is in force that nothing reads, and
+ * guessing at it would be the silent no-op the whole policy schema is shaped to
+ * prevent.
+ *
+ * `fullPayload` is deliberately ABSENT. The canonical block is not a row.
+ */
+export declare const PROMPT_ROWS: readonly ["action_key", "task", "class", "command_breakdown", "protected_path", "policy_diff", "policy_load", "autonomy", "provenance", "state", "requested_ts", "waiting", "ttl_remaining_ms", "payload_hash", "attestation", "budgets", "chain", "token_delivery", "est_cost_usd", "gloss", "summary", "rationale", "confidence"];
+/** One row name from {@link PROMPT_ROWS}. */
+export type PromptRow = (typeof PROMPT_ROWS)[number];
+/** Whether a string is a row name this runtime knows how to place. */
+export declare function isPromptRow(value: unknown): value is PromptRow;
+/**
+ * The rows an operator may reorder but never remove.
+ *
+ * Each is required for a DECISION rather than for a screen. `action_key`
+ * identifies which request the gesture answers; `class` is the resolution the
+ * whole gate turns on; `command_breakdown` and `protected_path` are APRV-144
+ * and APRV-143's answer to "what does this command actually do, and which
+ * protected path earned the class", derived from the bound bytes by the same
+ * classifier the hook decided with; `policy_diff` and `policy_load` are what
+ * SPEC.md §10.3 requires of an attestation prompt, where "a prompt carrying
+ * only a hash asks a human to sign for sixty-four characters and is a
+ * conformance failure".
+ *
+ * `payload_hash` is NOT here, and its absence is not an oversight. The bound
+ * hash is stated inside the canonical block on every channel, and the block is
+ * out of a layout's reach, so an operator who hides the row removes a
+ * duplicate rather than the binding. Telegram's default layout already does
+ * exactly that (APRV-163).
+ *
+ * A required row a request does not CARRY renders nothing, as it does today.
+ * Requirement is about what a policy may instruct, not about what a particular
+ * request happens to hold.
+ */
+export declare const REQUIRED_PROMPT_ROWS: readonly PromptRow[];
+/**
+ * How a row renders when nothing in the policy says otherwise.
+ *
+ * - `always` — on every prompt the request carries the field for.
+ * - `abnormal` — only when the value is the reason to look. APRV-163's
+ *   argument: a row that says "everything is fine" on every ordinary request is
+ *   a row a reader learns to skip, and the skipping does not stop on the one
+ *   request where it says something else.
+ * - `off` — the channel does not render it by default. The field still travels
+ *   on the request, so `--json`, `approval queue` and the web page carry it.
+ */
+export type RowVisibility = "always" | "abnormal" | "off";
+/** A resolved layout: the order rows render in, and each row's visibility. */
+export interface PromptLayout {
+    /** Every row in {@link PROMPT_ROWS}, in render order. */
+    order: readonly PromptRow[];
+    /** Visibility per row. Total: every row name has an entry. */
+    visibility: Readonly<Record<PromptRow, RowVisibility>>;
+}
+/** The channels this runtime ships (SPEC.md §10.3). */
+export declare const PROMPT_CHANNELS: readonly ["cli", "web", "telegram"];
+/** One of the three shipped channel names. */
+export type PromptChannel = (typeof PROMPT_CHANNELS)[number];
+/**
+ * Telegram's default layout: the slimmed phone prompt, exactly as APRV-143 and
+ * APRV-163 left it.
+ *
+ * The ORDER of the rows that render is load-bearing and must not drift: it is
+ * the sequence a reader's eye has learned. The `off` rows are interleaved where
+ * they belong if an operator turns them on, which costs nothing while they are
+ * off and saves an operator from writing a `rows` list to get a sensible
+ * position.
+ *
+ * `action_key` is `off` here because Telegram renders it STRUCTURALLY, as the
+ * message's second line in a `<code>` span. It is required, so it cannot be
+ * hidden, and it is not a bullet, so promoting it changes nothing.
+ */
+export declare const TELEGRAM_PROMPT_LAYOUT: PromptLayout;
+/**
+ * The CLI channel's default layout: every row the request carries.
+ *
+ * A terminal has room, and a one-shot rendering an operator asked for by typing
+ * a verb is not the place to economise on lines the way a push notification is.
+ */
+export declare const CLI_PROMPT_LAYOUT: PromptLayout;
+/** The web channel's default layout. Same reasoning as the CLI's: a page scrolls. */
+export declare const WEB_PROMPT_LAYOUT: PromptLayout;
+/** Default layout per shipped channel. What an absent `prompt` block means. */
+export declare const DEFAULT_PROMPT_LAYOUTS: Readonly<Record<PromptChannel, PromptLayout>>;
+/**
+ * A `channels.<name>.prompt` block as a policy may write it.
+ *
+ * Three keys, and each does ONE thing, because a key that both orders and
+ * hides would leave an operator guessing which of the two a short list meant:
+ *
+ * - `rows` — ORDER ONLY. The rows it names render in that order, ahead of every
+ *   row it does not name; those keep their default relative order behind them.
+ *   It is never a whitelist, so a `ChannelRequest` widened by a later task
+ *   cannot silently lose a field to a list written before that field existed —
+ *   the same property `orderedFields` has held since APRV-23.
+ * - `always` — visibility UP. A row that is `abnormal` or `off` by default
+ *   renders on every prompt.
+ * - `hide` — visibility DOWN. A row never renders. Refused for
+ *   {@link REQUIRED_PROMPT_ROWS}.
+ *
+ * `always` and `hide` naming the same row is refused rather than resolved by
+ * precedence: a policy that says both things about one row has an author who
+ * believes one of them, and picking for them is the guess this schema does not
+ * make.
+ */
+export interface PromptBlock {
+    rows?: PromptRow[];
+    always?: PromptRow[];
+    hide?: PromptRow[];
+}
+/**
+ * The layout in force for `channel`.
+ *
+ * Fail-soft in the same direction as `telegramDeliveryFor`: a policy that did
+ * not load declares nothing, an absent block declares nothing, and a layout is
+ * not a permission. Anything structurally wrong that reaches here (a hand-built
+ * load result, a key from a later version) falls back to the default rather
+ * than being guessed at — a LOADED policy cannot carry such a block, because
+ * {@link promptBlockErrors} refuses it at load.
+ */
+export declare function promptLayoutFor(load: PolicyLoadResult, channel: string): PromptLayout;
+/**
+ * Apply a block to a layout. Pure, total, and exported so a caller holding a
+ * block already can resolve it without going back through a policy file, which
+ * is what the tests do and what a future `approval policy explain` of a channel
+ * would need. Nothing outside the tests calls it today, and that is fine: the
+ * split keeps {@link promptLayoutFor} to one job, reading the block.
+ */
+export declare function applyPromptBlock(base: PromptLayout, block: PromptBlock): PromptLayout;
+/** The machine-readable reasons a `prompt` block refuses (APRV-218). */
+export declare const PROMPT_BLOCK_ERROR_KEYWORDS: readonly [
+/** A row name this runtime cannot place. */
+"prompt-row-unknown", 
+/** {@link REQUIRED_PROMPT_ROWS} named in `hide`. */
+"prompt-row-required", 
+/** `rows`, `always` or `hide` is not an array of strings. */
+"prompt-block-shape", 
+/** One row named by both `always` and `hide`. */
+"prompt-row-conflict", 
+/** A key the `prompt` block does not define. */
+"prompt-key-unknown"];
+/**
+ * Validate every `channels.<name>.prompt` in a policy. Empty means clean.
+ *
+ * This runs on top of the JSON Schema rather than instead of it, and the
+ * duplication is deliberate. The schema types the three channels this runtime
+ * ships and closes the row enum there, which is where SPEC.md §8's
+ * validate-at-the-write-boundary rule wants it; but `channels` admits UNKNOWN
+ * channel names as free-form objects on purpose, so a third-party transport
+ * plugin does not invalidate a whole policy, and a `prompt` block written under
+ * such a name would otherwise reach a renderer unchecked. Both nets return the
+ * same verdict — the policy does not load, everything is `manual` — so an
+ * operator never has to know which one caught them.
+ */
+export declare function promptBlockErrors(policy: Policy): ValidationError[];

package/dist/src/core/protected-path-guard.d.ts

@@ -0,0 +1,453 @@
+/**
+ * The protected-path guard (APRV-151): CI asks the log, not the session.
+ *
+ * ## The hole this closes
+ *
+ * `approval hook claude-code` classifies a file-tool call before it applies,
+ * and when the target is a protected path the answer is `policy.edit` and the
+ * phone buzzes. That control is only as good as the wiring: a session whose
+ * PreToolUse hook never loaded edits SPEC.md with no prompt, no denial, and —
+ * this is the part that hurts — no refused-request record either. Nothing in
+ * the log says the edit happened, because the thing that would have written
+ * the record is the thing that did not run. Two incidents (2026-08-29 SPEC.md
+ * in worktree `aprv-145-land`, 2026-08-30 `.github/workflows/ci.yml` in
+ * `agent-a3f5d255372d43ac0`) are the same shape.
+ *
+ * A detector that asked the session whether it was hooked would be asking the
+ * party under oversight to report its own oversight, which SPEC.md §11 rules
+ * out on principle. So this one never talks to a session. It takes two commits,
+ * asks git which protected paths changed between them, and requires — for each
+ * one — exact evidence in the committed hash-chained log that either a human
+ * granted that edit or the runtime recorded that policy authorized its
+ * execution. A change with no evidence fails the pull request. Session wiring
+ * is not an input.
+ *
+ * ## What counts as evidence
+ *
+ * Evidence is about the CHANGE, not about the path (APRV-202). The guard reads
+ * the blob at both commits, reduces the difference to the lines this pull
+ * request adds and removes, and requires every one of them to trace back to
+ * bound material in an authorization record. A path authorized last Tuesday
+ * and edited again today has evidence naming it and none covering today's
+ * lines, and that fails. Naming remains necessary; it stopped being sufficient.
+ *
+ * Four verdicts pass:
+ *
+ * 1. `attested` — the policy file, and the gate's ORGANS. `approval policy
+ *    amend --commit` appends `policy.updated` carrying `{policy_path, sha256}`,
+ *    the SHA-256 of the policy bytes a human attested. So for `APPROVAL.md` the
+ *    guard does not look for a grant at all: it hashes the file's bytes AT THE
+ *    HEAD COMMIT and requires that exact digest in the log. This is the
+ *    strongest match in the system — content-level, not path-level — and it is
+ *    why amendment PRs pass without a `policy.edit` grant, which they would
+ *    never have.
+ *
+ *    Since APRV-272 the same verdict covers the gate's organs, the harness
+ *    files that install the hook (`.claude/settings.json` and kin), on a
+ *    `gate.organ.attested` record carrying that path and that digest. They need
+ *    it for a stronger reason than the policy file does: an organ is
+ *    `policy.core`, `policy.core` is human-only, and the gate mints NOTHING for
+ *    a human-only class — so `granted-file` and `granted-command` cannot exist
+ *    for one however correctly a human edited it, and before this the guard
+ *    could only ever fail such a change (PR #300). The path is part of the
+ *    match: a digest attested for one organ is not evidence for another, which
+ *    is why the organ record carries a whole relative path where the policy
+ *    record carries a basename.
+ * 2. `policy-authorized-file` — an exact Edit or Write whose verified
+ *    `execution.started` is preceded by its unique matching registration and no
+ *    approval request. The registration, start and recomputed stored payload
+ *    must agree on task, action, class and hash. The start must precede the
+ *    change and the recorded class must be the class this path is routed to.
+ *    This records authorization to execute, not successful completion; the
+ *    exact hunk checks below establish whether those bytes landed.
+ * 3. `granted-file` — a file-tool edit. The hook binds the CHANGE rather than
+ *    the touch (APRV-124), so the bound material carries `file` plus the exact
+ *    edit: `{before, after}` for an Edit, `{content}` for a Write. That is
+ *    HUNK-level evidence, and it is used as such. The granted `after` bytes
+ *    have to occur verbatim in the blob at head before any added line is
+ *    credited to them, and the granted `before` bytes have to occur in the blob
+ *    at base before any removed line is. A granted edit whose after-state is not
+ *    in head is a grant for something that did not land, and covers nothing.
+ *    Some payloads carry the `{input}` fallback shape instead, which describes
+ *    no bytes; those name the path and cover nothing.
+ * 4. `granted-command` — a shell edit. The bound material is `{command, cwd}`
+ *    or `{argv, cwd}`, and the guard re-runs the runtime's own
+ *    {@link classifyCommand} over it, requiring a segment that classifies as a
+ *    granting class BECAUSE of a word naming this path. A mention is not a
+ *    grant: `cat SPEC.md` is `read.shell` and proves nothing, and the first
+ *    draft of this module, which substring-matched, accepted `hook classify --
+ *    vi SPEC.md` as evidence for a later SPEC.md edit.
+ *
+ *    A command payload cannot describe hunks: `node scripts/apply.mjs` names
+ *    the file it will rewrite and says nothing about the bytes. So this kind is
+ *    attributed rather than covered, and three things all have to hold:
+ *
+ *    - The write lands on THIS checkout's copy of the path. The payload's `cwd`
+ *      joined with the repository-relative path has to be exactly the word the
+ *      classifier matched (see {@link commandTargetsPath}). Three of the grants
+ *      that would otherwise have carried PR #187's SPEC.md change were dry runs
+ *      into `$SCRATCH/dry/SPEC.md`.
+ *    - The grant was SPENT: an `execution.started` for its `action_key`, and
+ *      its `execution.completed` when the log has one. A grant nobody spent
+ *      authorized a command that never ran.
+ *    - That run sits within {@link DEFAULT_COMMAND_ATTRIBUTION_MS} of the
+ *      commit AND does not start after it. A command's effect follows its own
+ *      `execution.started`, so a run four hours after the commit did not write
+ *      it — a real batch, on 2026-09-02, that a symmetric window would have
+ *      credited with PR #187's changes.
+ *
+ *    The finding names the run it attributed the change to, so a reader can
+ *    check the attribution rather than take it. It stays weaker than
+ *    `granted-file` because time is a weaker link than bytes: everything the
+ *    approved run wrote to that path in its window is carried by it.
+ *
+ * There is deliberately no class-level pass. A `policy.edit` grant that exists
+ * in the window but names some other file is not evidence that anybody saw
+ * THIS edit, and accepting it would let one approved edit launder every other
+ * edit in the same window. Class-level grants appear in the failure detail as
+ * diagnosis, never as a verdict.
+ *
+ * ## Grants go stale
+ *
+ * Naming the path is necessary and not sufficient, because grants accumulate
+ * forever. Run without a recency rule against the real log, this guard passed a
+ * SPEC.md edit made on 2026-08-29 on the strength of a `git add SPEC.md`
+ * granted on 2026-08-20: once any edit to a path has ever been approved, every
+ * later edit to that path would inherit the approval. So evidence must also sit
+ * within {@link DEFAULT_LOOKBACK_MS} of the commit that introduced the change,
+ * on either side of it. Either side, because both orderings are real: a grant
+ * shortly BEFORE the commit is the ordinary case, and a grant shortly after is
+ * the grant-follows-write anomaly (APRV-117/150 adjacent) — a defect in its own
+ * right, but a complete consent trail all the same, and not this guard's to
+ * adjudicate.
+ *
+ * That bound used to be the guard's weakest joint: a repeat edit to the same
+ * path inside the window inherited the earlier grant, and the guard passed
+ * PR #187, #196 and #207 on grants that authorized some earlier edit. APRV-202
+ * closes it, and the window is now the cheap pre-filter in front of the real
+ * question. A grant inside the window still has to cover the lines: an
+ * uncovered change fails `uncovered-hunk` however fresh the grants naming its
+ * path are. Attestation is exempt from the bound, because it matches CONTENT: bytes that
+ * hash to an attested digest are the attested bytes whenever they were signed.
+ * And when git cannot date the change at all, no bound is applied rather than a
+ * weaker one invented: see `changeTsFor` on {@link GuardInput} for why a bound
+ * against the head commit would have been theatre. The finding says which of
+ * the two it got, every time.
+ *
+ * ## How a hunk is decided to be covered
+ *
+ * The unit is a line of text. `added` is the multiset of lines the head blob
+ * has and the base blob does not; `removed` is the converse. A line is covered
+ * when its exact text appears in the granted material of some in-window grant
+ * (in `after`/`content` for an added line, in `before` for a removed one) and
+ * that material is anchored to the blob it claims, as described above. Coverage
+ * may be assembled from several grants, because one pull request may carry
+ * several approved edits to one file; the finding names every contributing
+ * grant and puts the strongest and nearest at the head.
+ *
+ * Three properties of that choice are worth stating, because each is a limit:
+ *
+ * - A blob that differs while its line multiset does not is a REORDERING, and
+ *   it is reported as one uncovered hunk rather than as no change. A rule that
+ *   compared multisets alone would pass a rewrite that only moved paragraphs.
+ * - Blank and whitespace-only lines neither need coverage nor give it. They
+ *   carry no content, and treating them as material would let one granted edit
+ *   containing an empty line cover every blank line added anywhere.
+ * - Coverage is by line text, not by position. An added line whose exact text
+ *   appears in some granted edit counts as covered even if it landed somewhere
+ *   else in the file. Tightening that to positions would trade a narrow
+ *   laundering channel (repeating a line the human already approved) for false
+ *   failures on every rebase and re-indent, and the first is the cheaper loss.
+ *
+ * ## The evidence surface is not a protected write surface
+ *
+ * `.approval/` is protected wherever it sits, and the daemon appends to it
+ * every time anything is approved — so a records / log-advance pull request
+ * changes `.approval/log/events.jsonl`, the payload store beside it, and the
+ * regenerated `QUEUE.md`. Requiring a grant for those would require a grant for
+ * the evidence, which is circular and would make it impossible to land the very
+ * commits this guard reads. {@link EXEMPT_PREFIXES} names that surface, and
+ * nothing else under `.approval/` is exempt: the vault, the environment map and
+ * anything else that lands there is still a protected write.
+ *
+ * ## The lag, and the ordering rule it implies
+ *
+ * The log on `main` trails the primary checkout's live log; advances land
+ * periodically as records pull requests. A grant made this morning may not be
+ * on `main` yet, and this module can only see the records its caller hands it.
+ * That is not a bug to paper over, it is an ordering rule, and every failure
+ * states it: **the log advance carrying the grant must be pushed to a records
+ * branch or merged to main before or with the protected-path pull request.**
+ * Each failure also names the window it searched (the seq and timestamp range
+ * of the records it was given) so the reader can tell "the grant is not there"
+ * from "the grant is newer than this log".
+ *
+ * A records branch counts because the caller may read further along the same
+ * chain than the head commit does (APRV-260): `scripts/protected-path-guard.mjs`
+ * takes the freshest committed copy that carries head's own last record at
+ * head's index, so an advance that is pushed but not yet merged is already
+ * evidence. Nothing here changes: this module still reads only the verified
+ * records it was handed, and the window it reports is the window it searched.
+ *
+ * ## Fail closed
+ *
+ * A missing log, a log that does not pass chain verification, and a protected
+ * path with no evidence are all failures, each with its own code. Records that
+ * have not passed verification are never read for evidence (SPEC.md §11.1
+ * invariant 1): the caller hands this module the verified records or none.
+ * This module appends nothing, reads no clock, and performs no IO of its own —
+ * git plumbing and file reads live in the caller.
+ */
+import { type ProtectedPathEntry } from "./command-class.js";
+import type { EventRecord } from "./log.js";
+/**
+ * Classes whose grant authorizes a protected-path write.
+ *
+ * `policy.edit` is what the hook and this repository's policy use.
+ * `policy.core` is accepted alongside it because SPEC.md §7's taxonomy admits
+ * a stricter sibling and a policy that routed the highest-value edits there
+ * should not lose its evidence.
+ */
+export declare const GRANTING_CLASSES: readonly string[];
+/**
+ * Does a grant of this class authorize a protected-path write? (APRV-266.)
+ *
+ * The named classes above, plus any `policy.edit` sub-class a policy routes a
+ * path to. Both directions of the cross-check matter and both are accepted:
+ *
+ * - A grant of the ROUTED class is the ordinary case once a policy adopts
+ *   routing. `policy.edit.spec` is the class the hook asked about and the class
+ *   the human decided, so it is the class the record carries.
+ * - A grant of `policy.edit` ITSELF is accepted for a path now routed, because
+ *   a routing is a policy edit and the two are not synchronized: a grant taken
+ *   under yesterday's string-only policy, or under the daemon's own fallback
+ *   when the policy would not load, names `policy.edit` for a path today's
+ *   policy routes. Refusing it would make adopting a routing retroactively
+ *   invalidate evidence that was correct when it was taken.
+ *
+ * What this does NOT do is loosen the guard: the class only opens the door, and
+ * the naming test — the grant's own material has to name THIS path, and since
+ * APRV-202 has to cover the actual hunks — is unchanged and is what decides.
+ * A sub-class name is not authority over anything; the namespace is closed to
+ * `policy.edit.*` in the classifier, so no grant of `log.mutate` or
+ * `policy.core` can be manufactured by naming one (SPEC.md §11.1 invariant 9).
+ */
+export declare function isGrantingClass(actionClass: string): boolean;
+/**
+ * The daemon's own append surface: evidence, not a protected write.
+ *
+ * Repository-relative, `/`-separated prefixes. A changed path equal to one of
+ * these, or under one of the directory ones, is skipped before any evidence is
+ * sought. See the module note for why this carve-out is narrow on purpose.
+ */
+export declare const EXEMPT_PREFIXES: readonly string[];
+/** Every way this guard can refuse, as stable codes. */
+export declare const GUARD_FAILURE_CODES: readonly [
+/** The log blob does not exist at the head commit at all. */
+"log-missing", 
+/** The log exists and does not pass chain verification. */
+"log-unverified", 
+/** A protected path changed and nothing in the log is evidence for it. */
+"no-evidence", 
+/**
+ * Grants DO name this path, inside the window, and some added or removed line
+ * of this change traces to none of their bound material (APRV-202).
+ *
+ * Distinct from `no-evidence` on purpose, because the two ask different
+ * things of the reader. `no-evidence` says nobody approved anything about
+ * this file and the question is whether the hook fired at all.
+ * `uncovered-hunk` says somebody approved something about this file and it
+ * was not this, which is the repeat-edit shape: the grant is real, the
+ * consent trail for THESE bytes is missing, and the fix is to take the
+ * change to the gate rather than to hunt for a lost record.
+ */
+"uncovered-hunk", 
+/**
+ * The blobs at base and head could not be read for this path (git could not
+ * show them, or they are binary), so no coverage could be established.
+ * Failing is the fail-closed direction: a change the guard cannot read is not
+ * a change it has checked.
+ */
+"change-unreadable"];
+export type GuardFailureCode = (typeof GUARD_FAILURE_CODES)[number];
+/** How the verified log and bound material authorize this exact path. */
+export type EvidenceKind = "attested" | "policy-authorized-file" | "granted-file" | "granted-command";
+/**
+ * How far from the commit that introduced a change a grant may sit and still be
+ * evidence for it: seven days, either side. See the module note.
+ */
+export declare const DEFAULT_LOOKBACK_MS: number;
+/**
+ * How far from the change commit a granted command's RUN may sit and still be
+ * the run that produced it: six hours, either side.
+ *
+ * Deliberately much tighter than {@link DEFAULT_LOOKBACK_MS}, because it is
+ * carrying much more weight. A file grant is checked against the bytes, so the
+ * recency bound is only a sanity rail around a content match. A command grant
+ * has no bytes to check, so time is the whole attribution, and a week of it
+ * would re-open exactly the hole this closes: every later edit to a path some
+ * approved script once wrote would inherit that script's grant. Six hours is
+ * about a working session, which is the unit of "this run produced this
+ * commit"; a batch that legitimately takes longer than that is asked for a
+ * fresh approval, which costs one tap.
+ */
+export declare const DEFAULT_COMMAND_ATTRIBUTION_MS: number;
+/** Fail-closed resource bounds for exact protected-edit reconstruction. */
+export declare const EXACT_REPLAY_MAX_CANDIDATES = 128;
+export declare const EXACT_REPLAY_MAX_STATES = 2048;
+export declare const EXACT_REPLAY_MAX_EXAMINED_BYTES: number;
+export interface GuardFinding {
+    /** The changed path, repository-relative. */
+    path: string;
+    ok: boolean;
+    /** Present on a pass. */
+    evidence?: EvidenceKind;
+    /** The log record that is the evidence, on a pass. */
+    seq?: number;
+    ts?: string;
+    actor?: string;
+    /**
+     * Every grant that covered part of this change, in report order, strongest
+     * and nearest first. `seq` is the head of this list.
+     */
+    coveredBy?: readonly number[];
+    /** Present on a failure. */
+    code?: GuardFailureCode;
+    /**
+     * On `uncovered-hunk`, a sample of the lines that traced to no granted
+     * material, `+` for added and `-` for removed.
+     */
+    uncovered?: readonly string[];
+    /** Prose a reader can act on, on either outcome. */
+    detail: string;
+}
+/** A protected path's bytes at both ends of the range the guard is checking. */
+export interface ChangeBlobs {
+    /** The blob at base, or `null` when this pull request adds the file. */
+    base: string | null;
+    /** The blob at head, or `null` when this pull request deletes it. */
+    head: string | null;
+}
+/** The window of log the guard could see, for the failure messages. */
+export interface LogWindow {
+    /** Lowest and highest `seq` in the log at head, or `null` for an empty log. */
+    firstSeq: number | null;
+    lastSeq: number | null;
+    firstTs: string | null;
+    lastTs: string | null;
+    /** The commit range the caller diffed. */
+    base: string;
+    head: string;
+}
+export interface GuardInput {
+    /** Repository-relative paths that differ between base and head, deletions included. */
+    changedPaths: readonly string[];
+    /**
+     * Records from the log at HEAD that have passed chain verification.
+     * `null` means the log could not be verified or could not be read; pair it
+     * with `logStatus` so the guard can say which.
+     */
+    records: readonly EventRecord[] | null;
+    logStatus: "ok" | "missing" | "unverified";
+    /** Why the log did not verify, when `logStatus` is not `ok`. */
+    logDetail?: string;
+    /** `policy.protected_paths` from the policy, widening the built-in set. */
+    policyProtectedPaths: readonly ProtectedPathEntry[];
+    /**
+     * SHA-256 of the policy file's bytes at the head commit, or `null` when the
+     * head tree carries no policy file. Only used for the `attested` verdict.
+     */
+    policySha256AtHead: string | null;
+    /** The policy file's repository-relative path, e.g. `APPROVAL.md`. */
+    policyPath: string;
+    /**
+     * SHA-256 of one GATE ORGAN's bytes at the head commit, or `null` when the
+     * head tree does not carry that path (APRV-272).
+     *
+     * The per-path counterpart of {@link policySha256AtHead}, computed the same
+     * way and from the same place — the blob at the head COMMIT, never the
+     * working tree. Only used for the `attested` verdict on an organ.
+     *
+     * OPTIONAL, and a caller that omits it gets no organ verdict at all rather
+     * than a weaker one: an organ change then falls through to the grant search
+     * and fails like any other unevidenced protected path. That is the
+     * fail-closed direction, and it is what keeps a caller written before this
+     * field existed correct rather than newly permissive.
+     *
+     * A DELETED organ resolves to `null` here, so removing one cannot pass by
+     * attestation: there are no bytes at head for a human to have signed. That is
+     * deliberate — the repair for a deletion is a grant or a human's own commit
+     * outside a pull request, not a record about bytes that no longer exist.
+     */
+    organSha256AtHead?: (path: string) => string | null;
+    /**
+     * Resolve bound material from the committed payload store, by hash.
+     * Returns `null` when the head tree does not carry that payload.
+     */
+    payloadFor: (hash: string) => unknown | null;
+    /**
+     * The author timestamp of the newest commit in `base..head` that touched this
+     * path, as an ISO-8601 instant, or `null` when git could not say.
+     *
+     * With no anchor — `null`, or a value that does not parse — NO recency bound
+     * is applied to this path, and the finding says so in its own text rather
+     * than reporting a bound it did not enforce.
+     *
+     * That is stated plainly because it is the accepting direction and it would
+     * be easy to dress up. The alternative considered was to bound the grant
+     * against the head commit instead, and it was rejected as theatre: every
+     * record in the log AT head is already before head by construction, so the
+     * rule would pass everything it was asked about while reading like a check.
+     * A guard that reports a bound it cannot enforce is worse than one that
+     * admits it has none, because only the first kind gets trusted.
+     *
+     * In practice the anchor is missing only when git cannot date a path it just
+     * reported in the diff, which is a broken-git condition rather than an
+     * attacker-reachable one; refusing on it would fire only on that breakage.
+     * The path-level evidence requirement is unaffected and still holds.
+     */
+    changeTsFor: (path: string) => string | null;
+    /**
+     * The path's bytes at base and at head, or `null` when they could not be
+     * read (git could not show them, or the blob is binary).
+     *
+     * This is what makes the guard's question "was THIS change approved" rather
+     * than "was this path approved once" (APRV-202). `null` fails the path with
+     * `change-unreadable` rather than falling back to the path-level rule: the
+     * fallback is the hole.
+     */
+    blobsFor: (path: string) => ChangeBlobs | null;
+    /** Override {@link DEFAULT_LOOKBACK_MS}. */
+    lookbackMs?: number;
+    /** Override {@link DEFAULT_COMMAND_ATTRIBUTION_MS}. */
+    commandAttributionMs?: number;
+    window: LogWindow;
+}
+export interface GuardReport {
+    ok: boolean;
+    /** Every protected path that changed, in the order git reported them. */
+    findings: readonly GuardFinding[];
+    /** Changed paths skipped as the daemon's own append surface. */
+    exempt: readonly string[];
+    window: LogWindow;
+}
+/** Is this changed path the daemon's own evidence surface? */
+export declare function isExemptPath(path: string): boolean;
+/**
+ * Is this changed path one whose edit requires a human decision?
+ *
+ * The guarded set is exactly the hook's ({@link isProtectedPath}, built-ins
+ * plus `policy.protected_paths`) minus the evidence surface. Sharing the
+ * predicate is the point: a CI guard whose idea of "protected" drifted from the
+ * hook's would fail the changes the hook already gated and pass the ones it
+ * would have caught.
+ */
+export declare function isGuardedPath(path: string, policyProtectedPaths: readonly ProtectedPathEntry[]): boolean;
+/**
+ * Evaluate a candidate against the committed log. Pure: no IO, no clock.
+ *
+ * @see GuardInput for what the caller has to gather.
+ */
+export declare function evaluateProtectedPaths(input: GuardInput): GuardReport;
+/** The report as the lines CI prints. Pure. */
+export declare function renderGuardReport(report: GuardReport): string;