approval-md 0.1.0 → 0.3.0

package/dist/src/core/protected-path-guard.js

@@ -17,20 +17,32 @@
  * 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 — evidence in the committed hash-chained log that a human saw that edit.
- * A change with no evidence fails the pull request. Session wiring is not an
- * input.
+ * 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.
+ *
+ * ## The unit of judgment: one commit (APRV-375)
+ *
+ * This file answers about ONE PAIR OF BLOBS, whichever pair the caller hands
+ * it, so the caller's choice of pair is where the question is really settled.
+ * Both callers choose the same one: for every commit of the range, base is that
+ * commit's first parent and head is the commit, because a grant binds one edit
+ * and the combined diff of a branch is a change nobody made. `core/commit-guard.ts`
+ * enumerates the commits, builds the per-commit inputs, states the argument
+ * that nothing goes unjudged, and is shared by the CI script and by
+ * `approval doctor`'s dark-session arm A.
  *
  * ## 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 the
- * bound material of some grant. A path that was granted last Tuesday and edited
- * again today has a grant naming it and no grant covering today's lines, and
- * that fails. Naming remains necessary; it stopped being sufficient.
+ * 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.
  *
- * Three verdicts pass, and they are ordered by how much they prove:
+ * Four verdicts pass:
  *
  * 1. `attested` — the policy file, and the gate's ORGANS. `approval policy
  *    amend --commit` appends `policy.updated` carrying `{policy_path, sha256}`,
@@ -52,7 +64,41 @@
  *    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. `granted-file` — a file-tool edit. The hook binds the CHANGE rather than
+ *
+ *    Since APRV-338 the verdict ALSO covers an ordinary `policy.edit` path on a
+ *    `gate.path.signed_off` record carrying that path and the digest at head —
+ *    and it is reached LAST, after every grant search below has failed. That
+ *    ordering is the whole design. A sign-off is whole-file evidence: it says a
+ *    human read this file at these bytes, not that they saw a particular line
+ *    change. A grant binds the hunk. So a change a grant covers passes on the
+ *    grant and prints the grant as its reason, and the sign-off answers only
+ *    the case the pending-sign-off suffix was invented for — text a human has
+ *    read and agrees with, for which no grant was ever taken. The organ's
+ *    verdict stays first because an organ can have no grant at all, so for one
+ *    there is nothing weaker to prefer.
+ * 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.
+ *
+ *    The payload's `file` is the path the hook bound, and the hook binds an
+ *    ABSOLUTE one: `fileToolGate` resolves the declared target against the
+ *    session's `cwd`, so an Edit of SPEC.md in a worktree is recorded as
+ *    `/Users/carter/dev/approval-md/.claude/worktrees/<name>/SPEC.md`. This
+ *    tier accepts that shape and the bare repository-relative path, matching
+ *    an absolute one by its trailing segments (see
+ *    {@link namesProtectedFile}). Until APRV-337 it accepted only the relative
+ *    shape, which no hook has ever written, so every unsampled
+ *    supervised-live edit to SPEC.md failed CI (PR #393). Tail matching is
+ *    sound HERE because the bytes carry the proof: `before` has to occur in
+ *    the blob at base, `after` in the blob at head, and the replay has to
+ *    reach HEAD byte-identical, so a scratch copy holding other bytes covers
+ *    nothing whatever its path says. Verdict 4 below keeps the stricter
+ *    cwd-join rule, because a command payload describes no bytes.
+ * 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
@@ -62,7 +108,7 @@
  *    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.
- * 3. `granted-command` — a shell edit. The bound material is `{command, cwd}`
+ * 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
@@ -126,6 +172,22 @@
  * against the head commit would have been theatre. The finding says which of
  * the two it got, every time.
  *
+ * ## Two anchors, because git keeps two dates (APRV-339)
+ *
+ * A commit carries an author date and a committer date, and they answer
+ * different questions. ORDERING — could this record have written these bytes,
+ * or does it come after them — is measured against the COMMITTER date, the
+ * moment those bytes were committed: an amend or a rebase only ever moves it
+ * later, so it cannot turn a genuine earlier start into a post-hoc one.
+ * STALENESS — is this evidence about this change or about some edit months ago
+ * — is measured against the AUTHOR date, which a rebase does not move, so
+ * replaying history does not expire evidence. Measuring both against the author
+ * date is what refused PR #393: `git commit --amend` kept the first author date
+ * while the bytes were committed 98 seconds later, and the unattended start
+ * that wrote them sat between the two and was read as having happened after the
+ * change. A caller that has only one date supplies it alone, and it answers
+ * both questions, which is where every caller stood before this.
+ *
  * ## How a hunk is decided to be covered
  *
  * The unit is a line of text. `added` is the multiset of lines the head blob
@@ -137,6 +199,18 @@
  * several approved edits to one file; the finding names every contributing
  * grant and puts the strongest and nearest at the head.
  *
+ * A bound Edit may describe LESS than a line, because the hook binds exactly
+ * what the tool replaced: rewriting part of a long paragraph binds a fragment
+ * and covers neither the line it removed nor the line it added. So before the
+ * replay below there is a line-local step (APRV-340). A fragment that occurs
+ * exactly once in exactly one line of the blob at base has one possible
+ * effect — that line, rewritten — and when the line it rewrites is one this
+ * change removes and the line it produces is one this change adds, both lines
+ * are credited to it. It is a one-step replay that needs no search, and it
+ * carries every eligibility condition the replay carries; what it does not
+ * carry is the replay's budget, which a 200 KB file with forty naming
+ * candidates exhausts before reaching a proof (PR #393).
+ *
  * 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
@@ -190,8 +264,10 @@
  * This module appends nothing, reads no clock, and performs no IO of its own —
  * git plumbing and file reads live in the caller.
  */
-import { organAttestationOf } from "./attest.js";
-import { classifyCommand, isGateOrganPath, isProtectedPath, normalizePathSpelling, POLICY_EDIT_SUBCLASS, } from "./command-class.js";
+import { organAttestationOf, pathSignOffOf } from "./attest.js";
+import { parseApplyPatch } from "./apply-patch.js";
+import { classifyCommand, isGateOrganPath, isProtectedPath, normalizePathSpelling, POLICY_EDIT_SUBCLASS, protectedPathClass, } from "./command-class.js";
+import { payloadHash } from "./payload.js";
 /**
  * Classes whose grant authorizes a protected-path write.
  *
@@ -288,6 +364,10 @@ export const DEFAULT_LOOKBACK_MS = 7 * 24 * 60 * 60 * 1000;
  * fresh approval, which costs one tap.
  */
 export const DEFAULT_COMMAND_ATTRIBUTION_MS = 6 * 60 * 60 * 1000;
+/** Fail-closed resource bounds for exact protected-edit reconstruction. */
+export const EXACT_REPLAY_MAX_CANDIDATES = 128;
+export const EXACT_REPLAY_MAX_STATES = 2_048;
+export const EXACT_REPLAY_MAX_EXAMINED_BYTES = 64 * 1024 * 1024;
 /** Split on either separator, dropping empties and `.` noise. */
 function segmentsOf(candidate) {
     return candidate.split(/[/\\]+/u).filter((part) => part.length > 0 && part !== ".");
@@ -301,6 +381,50 @@ function endsWithSegments(candidate, want) {
     const offset = have.length - tail.length;
     return tail.every((segment, index) => segment === have[offset + index]);
 }
+/**
+ * Is this changed path the POLICY FILE, whichever end carries the longer
+ * spelling?
+ *
+ * The guard is handed a repository-relative path from git and a policy location
+ * from its caller, and either may be the more qualified of the two, so the test
+ * is run both ways. One named predicate rather than the comparison written out
+ * at each of the two sites that ask it.
+ */
+function namesPolicyFile(path, policyPath) {
+    return endsWithSegments(policyPath, path) || endsWithSegments(path, policyPath);
+}
+/**
+ * Does a bound payload's `file` name this checkout's copy of `path`?
+ *
+ * The hook writes the ABSOLUTE path: `fileToolGate` resolves the declared
+ * target against the session's `cwd`, so a real Edit of SPEC.md in a worktree
+ * binds `/Users/carter/dev/approval-md/.claude/worktrees/<name>/SPEC.md`. Two
+ * shapes pass: the repository-relative path itself, and an absolute path whose
+ * TRAILING segments are that path. A relative path carrying extra leading
+ * directories (`dry/SPEC.md`) is refused, as is any `..` segment or backslash,
+ * either of which would make the tail test claim something it cannot know.
+ *
+ * Matching an absolute path by its tail is safe for Edit and Write material,
+ * and only for that material, because there the bytes are the proof: `before`
+ * has to occur in the blob at base, `after` in the blob at head, and the
+ * replay has to reach HEAD byte-identical. A payload naming another checkout's
+ * copy of SPEC.md carries that copy's bytes, which are not these, so it covers
+ * nothing. Command material describes no bytes at all, which is why
+ * {@link commandTargetsPath} keeps the stricter cwd-join rule for it.
+ */
+function namesProtectedFile(file, path) {
+    if (file.includes("\\"))
+        return false;
+    const named = segmentsOf(file);
+    if (named.includes(".."))
+        return false;
+    const wanted = segmentsOf(path);
+    if (wanted.length === 0)
+        return false;
+    if (file.startsWith("/"))
+        return endsWithSegments(file, path);
+    return named.length === wanted.length && named.every((part, index) => part === wanted[index]);
+}
 /**
  * Does this command line WRITE `path`, as the runtime's own classifier reads it?
  *
@@ -413,6 +537,31 @@ function evidenceFor(material, path, policyProtectedPaths) {
     if (typeof material !== "object" || material === null || Array.isArray(material))
         return null;
     const map = material;
+    // Codex apply_patch is tagged explicitly. Parse it before the generic
+    // command fallback so patch text is never mistaken for a shell command and
+    // never receives time-based command attribution. Until a patch-to-blob
+    // proof exists, this is deliberately naming-only evidence and covers no
+    // bytes; it remains useful diagnosis without weakening the guard.
+    if (map["tool"] === "apply_patch" && typeof map["command"] === "string") {
+        const parsed = parseApplyPatch(map["command"]);
+        if (parsed.ok) {
+            const operation = parsed.operations.find((candidate) => endsWithSegments(candidate.path, path) ||
+                (candidate.kind === "update" &&
+                    candidate.moveTo !== undefined &&
+                    endsWithSegments(candidate.moveTo, path)));
+            if (operation !== undefined) {
+                return {
+                    kind: "granted-file",
+                    detail: `the granted material is a Codex apply_patch operation naming ${path}; patch bytes are not yet guard coverage`,
+                    after: null,
+                    before: null,
+                    whole: false,
+                    command: false,
+                };
+            }
+        }
+        return null;
+    }
     const file = map["file"];
     if (typeof file === "string" && endsWithSegments(file, path)) {
         const tool = typeof map["tool"] === "string" ? map["tool"] : "a file tool";
@@ -476,6 +625,412 @@ function evidenceFor(material, path, policyProtectedPaths) {
     }
     return null;
 }
+/** Every declaration of this action key that existed before the start. */
+function precedingBindings(records, start) {
+    const actionKey = start.action_key;
+    if (actionKey === undefined)
+        return [];
+    const found = [];
+    for (const record of records) {
+        if (record.seq >= start.seq || record.event !== "task.registered")
+            continue;
+        const actions = payloadOf(record)["actions"];
+        if (!Array.isArray(actions))
+            continue;
+        for (const raw of actions) {
+            if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+                continue;
+            const action = raw;
+            if (action["idempotency_key"] !== actionKey)
+                continue;
+            const cls = action["class"];
+            const hash = action["payload_hash"];
+            // Count malformed declarations too. A malformed entry sharing the key is
+            // ambiguity, never something a later well-formed entry can hide.
+            found.push({
+                record,
+                task: record.task ?? null,
+                actionKey,
+                cls: typeof cls === "string" ? cls : null,
+                payloadHash: typeof hash === "string" ? hash : null,
+            });
+        }
+    }
+    return found;
+}
+/** Exact file bytes, excluding fallback, command and apply_patch material. */
+function policyFileEvidence(material, path, policyProtectedPaths) {
+    if (typeof material !== "object" || material === null || Array.isArray(material))
+        return null;
+    const map = material;
+    const tool = map["tool"];
+    const file = map["file"];
+    if (typeof file !== "string" || !namesProtectedFile(file, path))
+        return null;
+    const keys = Object.keys(map);
+    const hasOnly = (allowed) => keys.every((key) => allowed.includes(key));
+    if (tool === "Edit") {
+        if (!hasOnly(["tool", "rule", "file", "before", "after", "replace_all"]) ||
+            (map["rule"] !== undefined && typeof map["rule"] !== "string") ||
+            typeof map["before"] !== "string" ||
+            typeof map["after"] !== "string" ||
+            (map["replace_all"] !== undefined && typeof map["replace_all"] !== "boolean"))
+            return null;
+    }
+    else if (tool === "Write") {
+        if (!hasOnly(["tool", "rule", "file", "content"]) ||
+            (map["rule"] !== undefined && typeof map["rule"] !== "string") ||
+            typeof map["content"] !== "string")
+            return null;
+    }
+    else {
+        return null;
+    }
+    const match = evidenceFor(material, path, policyProtectedPaths);
+    if (match === null || match.command || (match.after === null && match.before === null))
+        return null;
+    return {
+        ...match,
+        kind: "policy-authorized-file",
+        detail: match.detail.replace(/^the granted material is/u, "the policy-authorized material is"),
+    };
+}
+/** Differing applicable routes in an unlabeled policy union carry no single class. */
+function hasAmbiguousRoute(path, policyProtectedPaths) {
+    const candidate = segmentsOf(path);
+    const classes = new Set();
+    for (const entry of policyProtectedPaths) {
+        const raw = typeof entry === "string" ? entry : entry.path;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0 || trimmed.startsWith("/"))
+            continue;
+        const wanted = segmentsOf(trimmed);
+        if (wanted.includes("..") || wanted.length === 0 || wanted.length > candidate.length)
+            continue;
+        const directory = /[/\\]$/u.test(trimmed);
+        const matches = directory
+            ? candidate.some((_, start) => start + wanted.length <= candidate.length &&
+                wanted.every((segment, offset) => candidate[start + offset] === segment))
+            : wanted.every((segment, offset) => candidate[candidate.length - wanted.length + offset] === segment);
+        if (matches)
+            classes.add(typeof entry === "string" ? "policy.edit" : entry.class);
+    }
+    return classes.size > 1;
+}
+/** Normalize whatever the caller supplied into one {@link ChangeAnchor}. */
+function changeAnchorOf(supplied) {
+    const pair = supplied === null || typeof supplied === "string"
+        ? { author: supplied, committer: supplied }
+        : supplied;
+    const authorTs = pair.author ?? pair.committer;
+    const committerTs = pair.committer ?? pair.author;
+    const parse = (ts) => {
+        if (ts === null)
+            return null;
+        const ms = Date.parse(ts);
+        return Number.isNaN(ms) ? null : ms;
+    };
+    const authorMs = parse(authorTs);
+    const committerMs = parse(committerTs);
+    return {
+        authorTs,
+        committerTs,
+        authorMs: authorMs ?? committerMs,
+        committerMs: committerMs ?? authorMs,
+    };
+}
+/**
+ * Exact-file evidence from an unattended execution authorized by policy.
+ *
+ * The start must reproduce the one declaration that preceded it, and the
+ * committed payload must hash back to that declaration. A prior request means
+ * the action entered the human-decision path, so this tier cannot carry it.
+ */
+function policyAuthorizedEvidence(records, start, path, policyProtectedPaths, payloadFor, anchor, lookbackMs) {
+    if (start.event !== "execution.started")
+        return null;
+    const task = start.task;
+    const actionKey = start.action_key;
+    if (task === undefined || actionKey === undefined)
+        return null;
+    const started = payloadOf(start);
+    const harnessStart = started["execution"] === "harness";
+    const coreStart = !Object.hasOwn(started, "execution");
+    if ((!harnessStart && !coreStart) ||
+        Object.hasOwn(started, "grant_seq") ||
+        Object.hasOwn(started, "token_sha256"))
+        return null;
+    const cls = started["class"];
+    const hash = started["payload_hash"];
+    if (typeof cls !== "string" || typeof hash !== "string")
+        return null;
+    // The exact routed class is authority. Merely living in policy.edit.* is not.
+    if (hasAmbiguousRoute(path, policyProtectedPaths))
+        return null;
+    const routed = protectedPathClass(path, policyProtectedPaths);
+    if (routed === null || routed === "policy.core" || routed === "log.mutate" || cls !== routed) {
+        return null;
+    }
+    const bindings = precedingBindings(records, start);
+    if (bindings.length !== 1)
+        return null;
+    const binding = bindings[0];
+    if (binding.task !== task ||
+        binding.actionKey !== actionKey ||
+        binding.cls !== cls ||
+        binding.payloadHash !== hash)
+        return null;
+    if (records.some((record) => record.seq < start.seq &&
+        record.action_key === actionKey &&
+        record.event === "approval.requested"))
+        return null;
+    // A start cannot authorize a change that already happened, and a start from
+    // months ago is about some earlier edit. Ordering is asked of the COMMITTER
+    // date and staleness of the AUTHOR date (APRV-339). This tier also requires a
+    // usable commit timestamp; missing temporal evidence fails closed.
+    const { authorMs, committerMs } = anchor;
+    if (authorMs === null || committerMs === null)
+        return null;
+    const at = Date.parse(start.ts);
+    if (Number.isNaN(at) || at > committerMs || authorMs - at > lookbackMs)
+        return null;
+    const material = payloadFor(hash);
+    if (material === null)
+        return null;
+    try {
+        if (payloadHash(material) !== hash)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return policyFileEvidence(material, path, policyProtectedPaths);
+}
+/** The closed Edit shape, naming this path, eligible for byte replay. */
+function exactReplayEdit(material, path) {
+    if (typeof material !== "object" || material === null || Array.isArray(material))
+        return null;
+    const map = material;
+    const keys = Object.keys(map);
+    const allowed = ["tool", "rule", "file", "before", "after", "replace_all"];
+    if (keys.some((key) => !allowed.includes(key)))
+        return null;
+    if (map["tool"] !== "Edit" ||
+        typeof map["file"] !== "string" ||
+        !namesProtectedFile(map["file"], path) ||
+        (map["rule"] !== undefined && typeof map["rule"] !== "string") ||
+        typeof map["before"] !== "string" ||
+        map["before"].length === 0 ||
+        typeof map["after"] !== "string" ||
+        map["before"] === map["after"] ||
+        (map["replace_all"] !== undefined && map["replace_all"] !== false))
+        return null;
+    return { before: map["before"], after: map["after"] };
+}
+/** The one token or harness spend that proves this manual grant actually ran. */
+function startForReplayGrant(candidate, records, anchor, lookbackMs, path, policyProtectedPaths) {
+    const { authorMs, committerMs } = anchor;
+    if (authorMs === null || committerMs === null)
+        return null;
+    const grant = candidate.record;
+    const task = grant.task;
+    const actionKey = grant.action_key;
+    if (task === undefined || actionKey === undefined)
+        return null;
+    const granted = payloadOf(grant);
+    const cls = granted["class"];
+    const hash = granted["payload_hash"];
+    if (typeof cls !== "string" || typeof hash !== "string" || hash !== candidate.payloadHash)
+        return null;
+    if (hasAmbiguousRoute(path, policyProtectedPaths))
+        return null;
+    const routed = protectedPathClass(path, policyProtectedPaths);
+    if (routed === null || routed === "policy.core" || routed === "log.mutate" || cls !== routed) {
+        return null;
+    }
+    try {
+        if (payloadHash(candidate.material) !== hash)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const grantToken = granted["token_sha256"];
+    const starts = records.filter((record) => {
+        if (record.event !== "execution.started" ||
+            record.seq <= grant.seq ||
+            record.task !== task ||
+            record.action_key !== actionKey)
+            return false;
+        const started = payloadOf(record);
+        if (started["class"] !== cls || started["payload_hash"] !== hash)
+            return false;
+        if (Object.hasOwn(started, "execution") && started["execution"] !== "harness")
+            return false;
+        const hasGrantLink = Object.hasOwn(started, "grant_seq");
+        const hasTokenLink = Object.hasOwn(started, "token_sha256");
+        if (!hasGrantLink && !hasTokenLink)
+            return false;
+        if (hasGrantLink && started["grant_seq"] !== grant.seq)
+            return false;
+        if (hasTokenLink &&
+            (typeof grantToken !== "string" || started["token_sha256"] !== grantToken))
+            return false;
+        // Ordering against the committer date, staleness against the author date
+        // (APRV-339), exactly as the policy-authorized tier asks them.
+        const at = Date.parse(record.ts);
+        return !Number.isNaN(at) && at <= committerMs && authorMs - at <= lookbackMs;
+    });
+    if (starts.length !== 1)
+        return null;
+    const start = starts[0];
+    const bindings = precedingBindings(records, start);
+    if (bindings.length !== 1)
+        return null;
+    const binding = bindings[0];
+    if (binding.record.seq >= grant.seq ||
+        binding.task !== task ||
+        binding.actionKey !== actionKey ||
+        binding.cls !== cls ||
+        binding.payloadHash !== hash)
+        return null;
+    const requested = records.some((record) => {
+        if (record.event !== "approval.requested" ||
+            record.seq <= binding.record.seq ||
+            record.seq >= grant.seq ||
+            record.task !== task ||
+            record.action_key !== actionKey)
+            return false;
+        const payload = payloadOf(record);
+        return payload["class"] === cls && payload["payload_hash"] === hash;
+    });
+    return requested ? start : null;
+}
+/**
+ * Replay authorized exact edits in execution order and demand byte equality.
+ *
+ * The log may contain older edits whose anchors survive in BASE but which did
+ * not produce this change. Search deterministic ordered subsequences: skip a
+ * candidate first, and apply it only when its anchor occurs exactly once in the
+ * current state. An ambiguous candidate cannot be applied, but it does not make
+ * an independent later proof ambiguous. Only a non-empty sequence that turns
+ * BASE into HEAD byte for byte is evidence; there is no reordering, substring
+ * credit, or partial result.
+ *
+ * Search is bounded by candidate count, distinct states, and cumulative bytes
+ * examined. Crossing any bound refuses the fallback rather than pruning a
+ * potentially valid branch and claiming the remaining search was complete.
+ */
+function exactEditReplay(candidates, records, base, head, anchor, lookbackMs, path, policyProtectedPaths) {
+    if (base === null ||
+        head === null ||
+        base.includes("\uFFFD") ||
+        head.includes("\uFFFD"))
+        return { steps: null, bound: null };
+    const gathered = [];
+    for (const candidate of candidates) {
+        try {
+            if (payloadHash(candidate.material) !== candidate.payloadHash)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const edit = exactReplayEdit(candidate.material, path);
+        if (edit === null)
+            continue;
+        const start = candidate.source === "policy"
+            ? candidate.record
+            : startForReplayGrant(candidate, records, anchor, lookbackMs, path, policyProtectedPaths);
+        if (start !== null)
+            gathered.push({ candidate, start, ...edit });
+    }
+    gathered.sort((left, right) => left.start.seq - right.start.seq);
+    // A verified execution record can authorize at most one application. Collapse
+    // duplicate evidence views of the same binding. If two views give one start
+    // conflicting edit bytes, neither representation of that start is usable.
+    const byStart = new Map();
+    const conflictingStarts = new Set();
+    for (const step of gathered) {
+        const prior = byStart.get(step.start.seq);
+        if (prior === undefined) {
+            byStart.set(step.start.seq, step);
+            continue;
+        }
+        if (prior.before !== step.before || prior.after !== step.after) {
+            conflictingStarts.add(step.start.seq);
+        }
+    }
+    const steps = [...byStart.values()].filter((step) => !conflictingStarts.has(step.start.seq));
+    if (steps.length > EXACT_REPLAY_MAX_CANDIDATES) {
+        return { steps: null, bound: "candidate-limit" };
+    }
+    const headBytes = Buffer.byteLength(head, "utf8");
+    let examinedBytes = Buffer.byteLength(base, "utf8") + headBytes;
+    if (examinedBytes > EXACT_REPLAY_MAX_EXAMINED_BYTES) {
+        return { steps: null, bound: "byte-limit" };
+    }
+    let visitedStates = 0;
+    let exceeded = null;
+    // State equality is exact string equality, not a digest or lossy cache key.
+    // Empty/non-empty histories stay distinct because an empty replay is never
+    // evidence even when BASE already equals HEAD.
+    const visited = Array.from({ length: steps.length + 1 }, () => [new Set(), new Set()]);
+    const search = (index, replayed, applied) => {
+        if (exceeded !== null)
+            return null;
+        const replayedBytes = Buffer.byteLength(replayed, "utf8");
+        // Charge exact-state hashing/equality and the HEAD comparison before either
+        // can retain or accept this state.
+        const stateBytes = replayedBytes + headBytes;
+        if (examinedBytes + stateBytes > EXACT_REPLAY_MAX_EXAMINED_BYTES) {
+            exceeded = "byte-limit";
+            return null;
+        }
+        examinedBytes += stateBytes;
+        const seen = visited[index]?.[applied.length === 0 ? 0 : 1];
+        if (seen === undefined || seen.has(replayed))
+            return null;
+        seen.add(replayed);
+        visitedStates += 1;
+        if (visitedStates > EXACT_REPLAY_MAX_STATES) {
+            exceeded = "state-limit";
+            return null;
+        }
+        if (applied.length > 0 && replayed === head)
+            return [...applied];
+        if (index === steps.length)
+            return null;
+        // Deterministic skip-first DFS finds a late witness quickly and
+        // prevents irrelevant historical edits from polluting a valid proof.
+        const skipped = search(index + 1, replayed, applied);
+        if (skipped !== null || exceeded !== null)
+            return skipped;
+        const step = steps[index];
+        const scanBytes = replayedBytes * 2 +
+            Buffer.byteLength(step.before, "utf8");
+        if (examinedBytes + scanBytes > EXACT_REPLAY_MAX_EXAMINED_BYTES) {
+            exceeded = "byte-limit";
+            return null;
+        }
+        examinedBytes += scanBytes;
+        const first = replayed.indexOf(step.before);
+        if (first === -1 || replayed.indexOf(step.before, first + 1) !== -1)
+            return null;
+        // Bound the next allocation before constructing it. `replayed + after` is
+        // a conservative upper bound because the replacement removes `before`.
+        const prospectiveBytes = replayedBytes + Buffer.byteLength(step.after, "utf8");
+        if (examinedBytes + prospectiveBytes > EXACT_REPLAY_MAX_EXAMINED_BYTES) {
+            exceeded = "byte-limit";
+            return null;
+        }
+        examinedBytes += prospectiveBytes;
+        const next = `${replayed.slice(0, first)}${step.after}${replayed.slice(first + step.before.length)}`;
+        return search(index + 1, next, [...applied, step]);
+    };
+    const proof = search(0, base, []);
+    return { steps: proof, bound: exceeded };
+}
 /** A blob's lines, with the empty tail a trailing newline leaves dropped. */
 function linesOf(text) {
     const parts = text.split("\n");
@@ -483,6 +1038,38 @@ function linesOf(text) {
         parts.pop();
     return parts;
 }
+/**
+ * Where a fragment anchors in the blob at base, and what replacing it yields.
+ *
+ * `null` unless the fragment sits inside ONE line and occurs exactly once in
+ * the whole file: a fragment with two homes does not say which occurrence the
+ * human approved, and a guess is not evidence. A fragment carrying a newline is
+ * not line-local at all and belongs to the global replay.
+ *
+ * Applying a uniquely-anchored edit to base can only produce base with that one
+ * line rewritten, so this is a one-step replay stated as the line it changes —
+ * the arithmetic the caller then checks against the hunks (APRV-340).
+ */
+function lineLocalReplacement(baseLines, edit) {
+    if (edit.before.includes("\n"))
+        return null;
+    let found = null;
+    for (const line of baseLines) {
+        const first = line.indexOf(edit.before);
+        if (first === -1)
+            continue;
+        if (found !== null || line.indexOf(edit.before, first + 1) !== -1)
+            return null;
+        found = { line, at: first };
+    }
+    if (found === null)
+        return null;
+    const { line, at } = found;
+    return {
+        removed: line,
+        added: `${line.slice(0, at)}${edit.after}${line.slice(at + edit.before.length)}`,
+    };
+}
 /** A line that carries content. Blank lines neither need coverage nor give it. */
 function substantive(line) {
     return line.trim().length > 0;
@@ -555,8 +1142,8 @@ function windowText(window) {
 }
 /**
  * How far past the change commit a run may still start and be its cause: five
- * minutes, for clock disagreement between the log and git's author date. It is
- * a skew allowance, not an ordering allowance.
+ * minutes, for clock disagreement between the log and git's committer date. It
+ * is a skew allowance, not an ordering allowance.
  */
 const SKEW_GRACE_MS = 5 * 60 * 1000;
 /** Milliseconds as something a failure message can say out loud. */
@@ -580,7 +1167,12 @@ function spanText(ms) {
  * interval it actually occupied: a batch that started before the commit and
  * finished after it brackets the commit, which is the strongest form of this.
  */
-function attributeRun(grant, runs, anchorMs, attributionMs) {
+function attributeRun(grant, runs, anchor, attributionMs) {
+    // The same split the other two tiers make (APRV-339): "did this run start
+    // after the bytes were committed" is asked of the COMMITTER date, which an
+    // amend may only move later, and "how far from the change is it" of the
+    // AUTHOR date, which a rebase does not move.
+    const { authorMs, committerMs } = anchor;
     const key = grant.action_key;
     if (key === undefined) {
         return {
@@ -598,7 +1190,7 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
     }
     const completed = tied.filter((record) => record.event === "execution.completed");
     const endOf = (record) => completed.find((done) => done.seq > record.seq);
-    if (anchorMs === null) {
+    if (authorMs === null || committerMs === null) {
         const first = started[0];
         return {
             ok: true,
@@ -611,7 +1203,7 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
     // the record is appended before the process is spawned. The real log shows
     // what the symmetric window costs — a SPEC.md batch run four hours AFTER
     // PR #187's commit would otherwise have carried that commit's changes.
-    // `SKEW_GRACE_MS` is for the two clocks (the log's and git's author date)
+    // `SKEW_GRACE_MS` is for the two clocks (the log's and git's committer date)
     // disagreeing, not for ordering.
     let best = null;
     let laterOnly = null;
@@ -619,7 +1211,7 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
         const from = Date.parse(record.ts);
         if (Number.isNaN(from))
             continue;
-        if (from > anchorMs + SKEW_GRACE_MS) {
+        if (from > committerMs + SKEW_GRACE_MS) {
             if (laterOnly === null)
                 laterOnly = record;
             continue;
@@ -627,9 +1219,9 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
         const end = endOf(record);
         const to = end === undefined ? from : Date.parse(end.ts);
         const upper = Number.isNaN(to) ? from : to;
-        const distance = anchorMs >= Math.min(from, upper) && anchorMs <= Math.max(from, upper)
+        const distance = authorMs >= Math.min(from, upper) && authorMs <= Math.max(from, upper)
             ? 0
-            : Math.min(Math.abs(from - anchorMs), Math.abs(upper - anchorMs));
+            : Math.min(Math.abs(from - authorMs), Math.abs(upper - authorMs));
         if (best === null || distance < best.distance)
             best = { record, end, distance };
     }
@@ -667,7 +1259,41 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
  * spelled: two different (path, digest) pairs cannot collide into one key.
  */
 function organKey(organPath, sha256) {
-    return `${normalizePathSpelling(organPath)}${sha256}`;
+    return `${normalizePathSpelling(organPath)}\0${sha256}`;
+}
+/**
+ * May this path be evidenced by a `gate.path.signed_off` record? (APRV-338.)
+ *
+ * `policy.edit` and its sub-classes, and nothing else. The organs and the
+ * approval home are `policy.core` and answered by their own record; the log
+ * directory is `log.mutate` and answered by nobody. Asked with the policy's own
+ * entries, so a path a project routed to `policy.edit.design` is signable while
+ * a path no list protects is not.
+ */
+function signOffEligible(path, extra) {
+    const routed = protectedPathClass(path, extra);
+    return routed === "policy.edit" || (routed !== null && POLICY_EDIT_SUBCLASS.test(routed));
+}
+/**
+ * The sentence a failing `policy.edit` path gets about the sign-off route, or
+ * nothing at all.
+ *
+ * Deliberately last in every message it appears in, and deliberately hedged.
+ * The first repair for an uncovered change is to take it to the gate, which
+ * binds the hunk; a sign-off stands for the whole file and is what the
+ * pending-sign-off suffix was invented for — text a human has read at this
+ * commit and agrees with. Printing it first would read as an invitation to
+ * route around the gate, which is the one thing this guard exists to notice.
+ */
+function signOffRepair(path, digest) {
+    if (digest === null)
+        return "";
+    // The two flags are named because the digest is the thing that has to match,
+    // and the bytes under review are on the BRANCH while the log lives in the
+    // primary checkout. `--dir` says which bytes to hash and `--log` says where
+    // the record goes, so one command can span both without the log ever being
+    // written from a worktree.
+    return ` If a human has READ this change at this commit and stands behind the file as it now is, they may ratify it with \`approval policy attest --path ${path} --dir <a checkout at this commit> --log <the primary checkout's log> --as human:<id>\`, which must hash to ${digest}, followed by a log advance carrying that record; that is whole-file evidence and weaker than a grant, so prefer the gate wherever the edit can still go through it.`;
 }
 /** The ordering rule, stated identically on every failure that could be lag. */
 const ORDERING_RULE = "the committed log trails the primary checkout's live log, so if this edit WAS granted, " +
@@ -733,6 +1359,18 @@ export function evaluateProtectedPaths(input) {
             continue;
         organAttestations.set(organKey(fields.organPath, fields.sha256), record);
     }
+    // The SIGN-OFF index (APRV-338), keyed the same way and fed by its own event
+    // type, so a sign-off can never answer an organ's question or the policy
+    // file's and neither can answer a sign-off's. Built here and consulted at the
+    // END of each path's evidence search: see the module note on why hunk
+    // evidence has to be preferred over whole-file evidence.
+    const signOffs = new Map();
+    for (const record of records) {
+        const fields = pathSignOffOf(record);
+        if (fields === null)
+            continue;
+        signOffs.set(organKey(fields.path, fields.sha256), record);
+    }
     // The grants of a class that can authorize a protected write.
     const grants = records.filter((record) => record.event === "approval.granted" &&
         isGrantingClass(String(payloadOf(record)["class"] ?? "")));
@@ -757,8 +1395,7 @@ export function evaluateProtectedPaths(input) {
     const findings = [];
     for (const path of guarded) {
         // 1. The policy file, by attestation.
-        if (endsWithSegments(input.policyPath, path) ||
-            endsWithSegments(path, input.policyPath)) {
+        if (namesPolicyFile(path, input.policyPath)) {
             if (input.policySha256AtHead !== null) {
                 const attested = attestations.get(input.policySha256AtHead);
                 if (attested !== undefined) {
@@ -806,18 +1443,24 @@ export function evaluateProtectedPaths(input) {
         const lookbackMs = input.lookbackMs ?? DEFAULT_LOOKBACK_MS;
         // ONE derivation of the anchor, so the bound that is enforced and the bound
         // that is reported cannot disagree. An unparseable timestamp is no anchor,
-        // exactly as a missing one is not: both land in `anchorMs === null`.
-        const parsed = changeTs === null ? Number.NaN : Date.parse(changeTs);
-        const anchorMs = Number.isNaN(parsed) ? null : parsed;
+        // exactly as a missing one is not: both land in `anchorMs === null`. Two
+        // instants since APRV-339, and the one asked here is the AUTHOR date: this
+        // is the staleness pre-filter, and ordering belongs to the tiers that can
+        // say which record wrote which bytes.
+        const anchor = changeAnchorOf(changeTs);
+        const anchorMs = anchor.authorMs;
         const inWindow = (ts) => {
             if (anchorMs === null)
                 return true;
             const at = Date.parse(ts);
             return !Number.isNaN(at) && Math.abs(at - anchorMs) <= lookbackMs;
         };
+        const datedText = anchor.committerTs === null || anchor.committerTs === anchor.authorTs
+            ? `${anchor.authorTs}`
+            : `authored ${anchor.authorTs}, committed ${anchor.committerTs}`;
         const boundText = anchorMs === null
-            ? `no usable commit timestamp for this path (${changeTs === null ? "git named none" : `git named ${JSON.stringify(changeTs)}, which does not parse`}), so NO recency bound was applied and this evidence rests on the path match alone`
-            : `within ${Math.round(lookbackMs / 86_400_000)}d of the commit that changed it (${changeTs})`;
+            ? `no usable commit timestamp for this path (${anchor.authorTs === null ? "git named none" : `git named ${JSON.stringify(datedText)}, which does not parse`}), so NO recency bound was applied and this evidence rests on the path match alone`
+            : `within ${Math.round(lookbackMs / 86_400_000)}d of the commit that changed it (${datedText})`;
         // EVERY qualifying grant is collected and the best one is reported, rather
         // than the first one found. The first-match version passed commit 41d2c9f
         // on a `cp SPEC.md <dir>/` granted four days earlier while the grant that
@@ -844,8 +1487,21 @@ export function evaluateProtectedPaths(input) {
                 stale.push(grant);
                 continue;
             }
-            candidates.push({ grant, match: found });
+            candidates.push({ record: grant, match: found, source: "grant", material, payloadHash: hash });
         }
+        for (const start of records) {
+            const found = policyAuthorizedEvidence(records, start, path, input.policyProtectedPaths, input.payloadFor, anchor, lookbackMs);
+            const hash = payloadOf(start)["payload_hash"];
+            if (found !== null && typeof hash === "string") {
+                const material = input.payloadFor(hash);
+                if (material !== null) {
+                    candidates.push({ record: start, match: found, source: "policy", material, payloadHash: hash });
+                }
+            }
+        }
+        const evidenceNoun = candidates.every((candidate) => candidate.source === "grant")
+            ? `grant${candidates.length === 1 ? "" : "s"}`
+            : `evidence record${candidates.length === 1 ? "" : "s"}`;
         /** Distance from the change commit, or 0 when there is no anchor to measure from. */
         const distance = (grant) => {
             if (anchorMs === null)
@@ -853,9 +1509,9 @@ export function evaluateProtectedPaths(input) {
             const at = Date.parse(grant.ts);
             return Number.isNaN(at) ? Number.POSITIVE_INFINITY : Math.abs(at - anchorMs);
         };
-        const rank = (kind) => (kind === "granted-file" ? 0 : 1);
+        const rank = (kind) => kind === "granted-file" ? 0 : kind === "policy-authorized-file" ? 1 : 2;
         candidates.sort((left, right) => rank(left.match.kind) - rank(right.match.kind) ||
-            distance(left.grant) - distance(right.grant));
+            distance(left.record) - distance(right.record));
         // The change this pull request makes to the path. Read before any coverage
         // is attempted, and a failure to read it is a failure: a change the guard
         // cannot see is not a change it has checked (APRV-202).
@@ -865,7 +1521,7 @@ export function evaluateProtectedPaths(input) {
                 path,
                 ok: false,
                 code: "change-unreadable",
-                detail: `${path} is a protected path and changed between ${input.window.base} and ${input.window.head}, and its bytes could not be read at both commits (git could not show the blob, or it is binary), so no grant could be checked against the change. ${candidates.length} grant${candidates.length === 1 ? "" : "s"} name this path in the window, and naming is not coverage. ${ORDERING_RULE}.`,
+                detail: `${path} is a protected path and changed between ${input.window.base} and ${input.window.head}, and its bytes could not be read at both commits (git could not show the blob, or it is binary), so no evidence could be checked against the change. ${candidates.length} ${evidenceNoun} name this path in the window, and naming is not coverage. ${ORDERING_RULE}.`,
             });
             continue;
         }
@@ -881,14 +1537,21 @@ export function evaluateProtectedPaths(input) {
         const removedCover = new Set();
         let whole = false;
         for (const candidate of candidates) {
-            const { grant, match } = candidate;
-            const at = `the grant at seq ${grant.seq}`;
+            const { record, match, source } = candidate;
+            // An execution start says an exact file action was authorized, not that a
+            // mode-only or whitespace-only change happened. Legacy human grants retain
+            // their narrow no-substantive-hunk behavior; policy starts do not gain it.
+            if (hunks.identical && source === "policy")
+                continue;
+            const at = source === "grant"
+                ? `the grant at seq ${record.seq}`
+                : `the policy-authorized execution at seq ${record.seq}`;
             if (match.command) {
                 if (!commandTargetsPath(match.target ?? "", match.cwd, path)) {
                     rejected.push(`${at} writes ${JSON.stringify(match.target ?? "")} from ${JSON.stringify(match.cwd ?? "(no cwd recorded)")}, which is not this checkout's ${path}: a granted write to a copy of the file elsewhere (a dry run into a scratch directory, another worktree) authorizes nothing here`);
                     continue;
                 }
-                const run = attributeRun(grant, runs, anchorMs, attributionMs);
+                const run = attributeRun(record, runs, anchor, attributionMs);
                 if (!run.ok) {
                     rejected.push(run.why);
                     continue;
@@ -896,7 +1559,7 @@ export function evaluateProtectedPaths(input) {
                 // A command payload describes no bytes, so attribution is all or
                 // nothing: the run that wrote this file wrote whatever is in it.
                 whole = true;
-                contributors.push({ grant, kind: match.kind, why: `${match.detail}, and ${run.detail}`, whole: true });
+                contributors.push({ record, kind: match.kind, why: `${match.detail}, and ${run.detail}`, whole: true, source });
                 continue;
             }
             if (match.after === null && match.before === null) {
@@ -947,8 +1610,99 @@ export function evaluateProtectedPaths(input) {
                 if (parts.length > 0)
                     contributed = `${match.detail}, and ${parts.join(" and ")}`;
             }
-            if (contributed !== null)
-                contributors.push({ grant, kind: match.kind, why: contributed, whole: wholeHere });
+            if (contributed !== null) {
+                contributors.push({ record, kind: match.kind, why: contributed, whole: wholeHere, source });
+            }
+        }
+        // One fragment inside one line, credited by bytes alone (APRV-340).
+        //
+        // The hook binds exactly what the Edit tool replaced, so an edit that
+        // rewrites part of a long paragraph binds a fragment and whole-line set
+        // membership cannot credit either line. That used to leave only the global
+        // replay, which on a 200 KB file with forty naming candidates refuses on
+        // its byte limit before it can reach a proof (PR #393, the fragment inside
+        // SPEC.md line 139). A uniquely-anchored fragment needs no search: applying
+        // it to base can only produce base with that ONE line rewritten, so if the
+        // line it rewrites is a line this change removes and the line it produces
+        // is a line this change adds, the bytes have proved both lines at the cost
+        // of one scan. Every eligibility condition is the global replay's own — the
+        // material rehashed, the Edit shape naming this path, and the same start
+        // resolution, which for a grant is the registration, the request, the
+        // class, the spend and the timing. A line-local step substitutes for none
+        // of them; it only spends less to ask the same question.
+        //
+        // Bytes that did not decode are not bytes anyone can prove anything about,
+        // so a blob carrying U+FFFD is refused here exactly as the replay refuses
+        // it: byte equality against a lossy decoding says nothing.
+        if (!whole &&
+            !hunks.identical &&
+            !baseText.includes("\uFFFD") &&
+            !headText.includes("\uFFFD")) {
+            const baseLines = linesOf(baseText);
+            const addsLine = new Set(hunks.added);
+            const removesLine = new Set(hunks.removed);
+            for (const candidate of candidates) {
+                const edit = exactReplayEdit(candidate.material, path);
+                if (edit === null)
+                    continue;
+                try {
+                    if (payloadHash(candidate.material) !== candidate.payloadHash)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const start = candidate.source === "policy"
+                    ? candidate.record
+                    : startForReplayGrant(candidate, records, anchor, lookbackMs, path, input.policyProtectedPaths);
+                if (start === null)
+                    continue;
+                const local = lineLocalReplacement(baseLines, edit);
+                if (local === null)
+                    continue;
+                if (!removesLine.has(local.removed) || !addsLine.has(local.added))
+                    continue;
+                addedCover.add(local.added);
+                removedCover.add(local.removed);
+                const why = `replacing that fragment in the one line of the blob at base that carries it yields a line this change adds, and that base line is one this change removes (line-local replay at execution.started seq ${start.seq})`;
+                const already = contributors.find((one) => one.record.seq === candidate.record.seq);
+                if (already === undefined) {
+                    contributors.push({
+                        record: candidate.record,
+                        kind: candidate.match.kind,
+                        why: `${candidate.match.detail}, and ${why}`,
+                        whole: false,
+                        source: candidate.source,
+                    });
+                    continue;
+                }
+                already.why = `${already.why}, and ${why}`;
+            }
+        }
+        // Exact Edit payloads may bind fragments within a line, including several
+        // independent fragments of the same long line. Whole-line set membership
+        // cannot express that safely. Replay is the bounded fallback: genuine
+        // starts, execution order, unique anchors, and final byte equality.
+        const needsReplay = !whole &&
+            !hunks.identical &&
+            (hunks.reordered ||
+                hunks.added.some((line) => !addedCover.has(line)) ||
+                hunks.removed.some((line) => !removedCover.has(line)));
+        const replay = needsReplay
+            ? exactEditReplay(candidates, records, blobs.base, blobs.head, anchor, lookbackMs, path, input.policyProtectedPaths)
+            : { steps: null, bound: null };
+        if (replay.bound !== null) {
+            rejected.unshift(`exact BASE-to-HEAD replay refused after reaching its ${replay.bound.replace("-", " ")}`);
+        }
+        if (replay.steps !== null) {
+            whole = true;
+            contributors.splice(0, contributors.length, ...replay.steps.map((step) => ({
+                record: step.candidate.record,
+                kind: step.candidate.match.kind,
+                why: `${step.candidate.match.detail}, applied at execution.started seq ${step.start.seq} in an exact BASE-to-HEAD replay`,
+                whole: true,
+                source: step.candidate.source,
+            })));
         }
         // What the bytes alone cover, before any whole-file attribution. If this is
         // non-empty the change RESTS on the attribution, and the finding has to
@@ -976,12 +1730,14 @@ export function evaluateProtectedPaths(input) {
         const lead = restsOnAttribution
             ? (contributors.find((one) => one.whole) ?? contributors[0])
             : contributors[0];
-        const quiet = hunks.identical ? candidates[0] : undefined;
+        const quiet = hunks.identical
+            ? candidates.find((candidate) => candidate.source === "grant")
+            : undefined;
         const passing = lead !== undefined
-            ? { record: lead.grant, kind: lead.kind, why: lead.why }
+            ? { record: lead.record, kind: lead.kind, why: lead.why }
             : quiet !== undefined
                 ? {
-                    record: quiet.grant,
+                    record: quiet.record,
                     kind: quiet.match.kind,
                     why: `${quiet.match.detail}, and this change alters no substantive line (whitespace, mode or metadata only), so there is no hunk to cover`,
                 }
@@ -997,17 +1753,48 @@ export function evaluateProtectedPaths(input) {
                 seq: record.seq,
                 ts: record.ts,
                 actor: record.actor,
-                coveredBy: contributors.map((one) => one.grant.seq),
-                detail: `${path} was granted by ${record.actor} at seq ${record.seq} (${record.ts}), ${boundText}: ${why}. ${hunks.identical
-                    ? "there are no substantive hunks to cover"
-                    : whole
-                        ? "the whole change is attributed to that grant"
-                        : `${hunks.added.length} added and ${hunks.removed.length} removed line(s) all trace to granted material`}${contributors.length > 1
-                    ? ` (assembled from ${contributors.length} grants: seq ${contributors.map((one) => one.grant.seq).join(", ")}; the strongest and nearest leads)`
-                    : ""}`,
+                coveredBy: contributors.map((one) => one.record.seq),
+                detail: replay.steps !== null
+                    ? `${path}'s full change was reconstructed byte-for-byte from ${contributors.length} replayed authorization record${contributors.length === 1 ? "" : "s"} in execution order, ${boundText}. Evidence records in that order: seq ${contributors.map((one) => one.record.seq).join(", ")}. The first record, ${record.actor} at seq ${record.seq} (${record.ts}), leads the finding: ${why}.`
+                    : `${path} was ${kind === "policy-authorized-file" ? "authorized by policy for execution" : "granted"} by ${record.actor} at seq ${record.seq} (${record.ts}), ${boundText}: ${why}. ${hunks.identical
+                        ? "there are no substantive hunks to cover"
+                        : whole
+                            ? "the whole change is attributed to that authorization record"
+                            : `${hunks.added.length} added and ${hunks.removed.length} removed line(s) all trace to authorized material`}${contributors.length > 1
+                        ? ` (assembled from ${contributors.length} ${contributors.every((one) => one.source === "grant") ? "grants" : "evidence records"}: seq ${contributors.map((one) => one.record.seq).join(", ")}; the strongest and nearest leads)`
+                        : ""}`,
             });
             continue;
         }
+        // The LAST thing tried for this path, and deliberately last: a human's
+        // whole-file sign-off (APRV-338).
+        //
+        // Everything above is hunk evidence, and everything above has now failed
+        // to cover this change. Only here does the guard ask the weaker question —
+        // did a human read this file at exactly these bytes and say so — and the
+        // finding says in words that this is what it rests on, so a reader can
+        // never mistake it for a grant. Running it here rather than beside the
+        // organ verdict is what keeps that true: consulted first, a sign-off would
+        // have silently answered for every change a grant already covered, and the
+        // reasons this guard prints are half its value.
+        const signOffDigest = signOffEligible(path, input.policyProtectedPaths)
+            ? (input.pathSha256AtHead?.(path) ?? null)
+            : null;
+        if (signOffDigest !== null) {
+            const signed = signOffs.get(organKey(path, signOffDigest));
+            if (signed !== undefined) {
+                findings.push({
+                    path,
+                    ok: true,
+                    evidence: "attested",
+                    seq: signed.seq,
+                    ts: signed.ts,
+                    actor: signed.actor,
+                    detail: `${path} at ${input.window.head} hashes to ${signOffDigest}, which ${signed.actor} signed off FOR THAT PATH at seq ${signed.seq}. This is WHOLE-FILE evidence and weaker than a grant: it says a human read this file at these exact bytes, not that they saw this hunk. It was read only because no grant covers this change — ${candidates.length} ${evidenceNoun} name this path ${boundText}${contributors.length > 0 ? `, and ${contributors.length} of them covered part of it (seq ${contributors.map((one) => one.record.seq).join(", ")})` : ""}`,
+                });
+                continue;
+            }
+        }
         // Naming grants exist and the change is not made of them: the repeat-edit
         // shape. Its own code, because the reader's next move differs from
         // `no-evidence` — take THIS change to the gate, rather than hunt for a
@@ -1019,11 +1806,11 @@ export function evaluateProtectedPaths(input) {
                 ok: false,
                 code: "uncovered-hunk",
                 uncovered: sample,
-                detail: `${path} is a protected path and ${uncovered.length} line(s) of this change trace to no granted material. ${candidates.length} grant${candidates.length === 1 ? "" : "s"} name this path ${boundText}, and naming is not coverage: a grant authorizes the bytes it bound, and a later edit to the same file is a different decision. ${contributors.length > 0
-                    ? `${contributors.length} grant${contributors.length === 1 ? "" : "s"} covered part of it (seq ${contributors.map((one) => one.grant.seq).join(", ")}); `
+                detail: `${path} is a protected path and ${uncovered.length} line(s) of this change trace to no authorized material. ${candidates.length} ${evidenceNoun} name this path ${boundText}, and naming is not coverage: evidence authorizes only the bytes it binds, and a later edit to the same file is a different decision. ${contributors.length > 0
+                    ? `${contributors.length} evidence record${contributors.length === 1 ? "" : "s"} covered part of it (seq ${contributors.map((one) => one.record.seq).join(", ")}); `
                     : ""}${rejected.length > 0
                     ? `${rejected.slice(0, 6).join("; ")}${rejected.length > 6 ? `; … and ${rejected.length - 6} other naming grants set aside for the same kinds of reason` : ""}. `
-                    : ""}uncovered: ${sample.map((line) => JSON.stringify(line)).join(", ")}${uncovered.length > sample.length ? `, … ${uncovered.length - sample.length} more` : ""}. ${windowText(input.window)}. ${ORDERING_RULE}.`,
+                    : ""}uncovered: ${sample.map((line) => JSON.stringify(line)).join(", ")}${uncovered.length > sample.length ? `, … ${uncovered.length - sample.length} more` : ""}. ${windowText(input.window)}. ${ORDERING_RULE}.${signOffRepair(path, signOffDigest)}`,
             });
             continue;
         }
@@ -1037,10 +1824,16 @@ export function evaluateProtectedPaths(input) {
         if (unresolved.length > 0) {
             diagnosis.push(`${unresolved.length} grant payload${unresolved.length === 1 ? "" : "s"} could not be resolved from the committed payload store (${unresolved.slice(0, 3).join(", ")}${unresolved.length > 3 ? ", …" : ""}), and a grant whose bytes cannot be read is not evidence for any path`);
         }
-        if ((endsWithSegments(input.policyPath, path) || endsWithSegments(path, input.policyPath)) &&
-            input.policySha256AtHead !== null) {
+        if (namesPolicyFile(path, input.policyPath) && input.policySha256AtHead !== null) {
             diagnosis.push(`no policy.updated record attests the bytes this pull request would install (${input.policySha256AtHead}); an amendment lands through \`approval policy amend --commit\`, whose attestation record is the evidence`);
         }
+        if (signOffDigest !== null) {
+            // A protected path that COULD have been signed off and was not. Named
+            // second to the grant advice above, not first: taking the edit to the
+            // gate binds the hunk, and a sign-off stands for the whole file
+            // (APRV-338).
+            diagnosis.push(`no gate.path.signed_off record signs off ${path} at ${signOffDigest}, and a digest signed for some OTHER path is not evidence for this one`);
+        }
         if (isGateOrganPath(path)) {
             // The one failure in this guard whose repair is NOT "take the change to
             // the gate": there is no gate for it. `policy.core` is human-only, the
@@ -1056,7 +1849,7 @@ export function evaluateProtectedPaths(input) {
             path,
             ok: false,
             code: "no-evidence",
-            detail: `${path} is a protected path (edits classify policy.edit) and changed between ${input.window.base} and ${input.window.head}, and the committed log carries no evidence that a human decided it. ${windowText(input.window)}. ${diagnosis.join("; ")}. ${ORDERING_RULE}.`,
+            detail: `${path} is a protected path (edits classify policy.edit) and changed between ${input.window.base} and ${input.window.head}, and the committed log carries no evidence that a human decided it. ${windowText(input.window)}. ${diagnosis.join("; ")}. ${ORDERING_RULE}.${signOffRepair(path, signOffDigest)}`,
         });
     }
     return {