approval-md 0.1.0 → 0.3.0

package/dist/src/core/attest.d.ts

@@ -0,0 +1,635 @@
+/**
+ * Policy attestation (SPEC.md §5.2, §11) — the mechanical form of "agents MUST
+ * NOT be able to modify `APPROVAL.md`".
+ *
+ * The problem this solves is not that an agent *can* edit the policy file — on
+ * a single machine nothing stops it — but that an edited policy would otherwise
+ * take effect silently. Attestation closes that: a human runs
+ * `approval policy attest`, which appends a `policy.updated` event carrying the
+ * SHA-256 of the policy file's exact bytes. From then on the live file either
+ * hashes to the latest attestation or it does not, and {@link checkAttestation}
+ * says which. Gate operations (request intake, grant recording, token minting —
+ * APRV-16) refuse on anything but a match. An edited policy is inoperative
+ * until a human re-attests it.
+ *
+ * ## What this proves, and what it does not
+ *
+ * Human identity at v0.1 is **config-declared**: `--as human:<id>` or the
+ * `APPROVAL_HUMAN` environment variable (see {@link resolveHumanActor}). The
+ * trust boundary is the local machine. Anyone who can set that environment
+ * variable and write to the log is inside the boundary, so an attestation
+ * proves that *someone with local control* signed off — not *who*. There is no
+ * cryptographic identity here and this module claims none; that is future work,
+ * stated plainly rather than dressed up. What attestation buys, even so, is
+ * real: a policy edit made by an agent mid-run cannot become operative without
+ * a separate, deliberate, logged human act.
+ *
+ * ## Fail closed, in this order
+ *
+ * A policy file that cannot be read is `unreadable`, never `attested`. No
+ * attestation at all is `not-attested`. Bytes that do not match the latest
+ * attestation are `hash-mismatch`. Only an exact match is `attested`.
+ *
+ * Everything here is read-only except {@link appendAttestation}, which writes
+ * through `core/log.ts`'s `appendEvent` — the one sanctioned append path — and
+ * therefore inherits its locking, chain stamping, and write-boundary schema
+ * validation. Nothing in this file opens the log itself.
+ */
+import { type ClockOptions } from "./clock.js";
+import { type ProtectedPathEntry } from "./command-class.js";
+import { type AppendOptions, type EventRecord } from "./log.js";
+import type { ValidationError } from "./validate.js";
+/** Environment variable naming the human on whose behalf the CLI attests. */
+export declare const HUMAN_ACTOR_ENV = "APPROVAL_HUMAN";
+/**
+ * The machine-readable refusal code emitted when policy is not attested.
+ *
+ * Deliberately distinct from any generic policy-load failure. A caller must be
+ * able to tell "the policy says manual" from "the policy is unverified", because
+ * the repairs are different: the first is answered by asking a human to approve
+ * an action, the second by asking a human to attest a file.
+ */
+export declare const ATTESTATION_REFUSAL = "policy-not-attested";
+/**
+ * The payload field carrying the attested policy hash a gate event was decided
+ * under (APRV-118, amended SPEC.md §5.2).
+ *
+ * Written on `approval.requested` and `approval.granted`, and named here rather
+ * than in `core/gate.ts` because the value is this module's: it is the SHA-256
+ * the live policy file matched when {@link checkAttestation} said `attested`.
+ * Pinning it lets a reader of the log answer a question attestation alone cannot
+ * — whether the approver decided under the rules the requester was routed by.
+ */
+export declare const POLICY_HASH_FIELD = "policy_sha256";
+/** Is `value` a lowercase-hex SHA-256, the shape {@link POLICY_HASH_FIELD} takes? */
+export declare function isPolicySha256(value: unknown): value is string;
+/** Why an attestation check refused. Mirrors the non-`attested` statuses. */
+export type AttestationRefusalDetail = "not-attested" | "hash-mismatch" | "unreadable";
+/** The refusal a gate operation surfaces to its caller (APRV-16 consumes it). */
+export interface AttestationRefusal {
+    code: typeof ATTESTATION_REFUSAL;
+    detail: AttestationRefusalDetail;
+    message: string;
+}
+/**
+ * Why an attestation append failed: every reason `appendEvent` can give, plus
+ * the one rule this module enforces on its own.
+ *
+ * ### Why `actor-not-human` lives here and not in `core/log.ts`
+ *
+ * Until APRV-20 pass two the non-human-actor refusal reused `validation`, which
+ * conflated two different facts: "the record failed `event.schema.json` at the
+ * write boundary" and "the caller is not allowed to perform this verb". A
+ * caller branching on `validation` could not tell a malformed event from a
+ * forbidden one, and the two call for opposite responses (fix the record;
+ * fetch a human).
+ *
+ * The fix does **not** add the code to `APPEND_ERROR_CODES`. That union is the
+ * log writer's vocabulary — the ways a byte can fail to reach the file — and
+ * "only humans may attest" is a fact about attestation, not about writing.
+ * Widening the writer's union to carry a caller's policy rule would oblige every
+ * future append site to consider a code that can only ever come from this one,
+ * and would make `core/log.ts` the place people look for permission rules.
+ * Instead this module widens the union *for itself*: `AppendResult` remains
+ * assignable to {@link AttestationAppendResult}, so nothing downstream is
+ * forced to change, and the CLI adds one case.
+ */
+export declare const ATTEST_ERROR_CODES: readonly ["lock-timeout", "corrupt-tail", "validation", "canonicalization", "io", "head-moved", "actor-not-human"];
+export type AttestErrorCode = (typeof ATTEST_ERROR_CODES)[number];
+export interface AttestError {
+    code: AttestErrorCode;
+    message: string;
+    /** Schema errors, present when `code` is "validation". */
+    errors?: ValidationError[];
+}
+/** {@link appendAttestation}'s result: `AppendResult` widened by one code. */
+export type AttestationAppendResult = {
+    ok: true;
+    record: EventRecord;
+    line: string;
+} | {
+    ok: false;
+    error: AttestError;
+};
+/** Options for {@link appendAttestation}: the append's, plus the clock. */
+export interface AttestOptions extends AppendOptions, ClockOptions {
+    /**
+     * When supplied, append only if the file bytes read by this call have this
+     * digest. A ceremony that displayed bytes before asking for confirmation can
+     * thereby bind the record to what it showed rather than silently signing a
+     * replacement written between display and append.
+     */
+    expectedSha256?: string;
+}
+/** The result of comparing the live policy file against the log. */
+export type AttestationStatus = {
+    status: "attested";
+    seq: number;
+    sha256: string;
+} | {
+    status: "not-attested";
+} | {
+    status: "hash-mismatch";
+    attestedSha256: string;
+    liveSha256: string;
+    seq: number;
+} | {
+    status: "unreadable";
+    message: string;
+};
+/**
+ * SHA-256 (lowercase hex) of a file's **exact bytes**.
+ *
+ * Bytes, not text: no encoding round-trip, no newline normalization, no parse.
+ * A policy file that differs only in trailing whitespace is a different policy
+ * file as far as attestation is concerned, which is the conservative reading
+ * and the only one that survives an adversary who knows what gets normalized.
+ *
+ * Throws if the file cannot be read; callers that need a status rather than an
+ * exception use {@link checkAttestation}, which converts that into
+ * `unreadable`.
+ */
+export declare function policyFileHash(path: string): string;
+/**
+ * SHA-256 (lowercase hex) of policy bytes a caller has already read.
+ *
+ * The same digest {@link policyFileHash} computes, over bytes rather than a
+ * path. It exists so a gate operation can read `APPROVAL.md` once and hash the
+ * exact buffer it is also about to parse (APRV-142): hashing by path a second
+ * time would reopen the window where the attestation check and the parse can
+ * see different bytes.
+ */
+export declare function policyBytesHash(bytes: Uint8Array): string;
+/**
+ * Append a `policy.updated` attestation for `policyPath` to `logPath`.
+ *
+ * `actor` MUST match `^human:.+`. An `agent:` or `system:` actor is refused
+ * before anything is read or written — the refusal is a structured result,
+ * never a throw, consistent with the rest of the write path. Its code is
+ * `actor-not-human`, this module's own (see {@link ATTEST_ERROR_CODES}): the
+ * actor failed the rule *this verb* enforces, which is a different fact from a
+ * record failing the event schema, and the two used to share `validation`.
+ *
+ * The event is deliberately minimal:
+ *
+ * ```json
+ * { "event": "policy.updated", "actor": "human:alice",
+ *   "payload": { "policy_path": "APPROVAL.md", "sha256": "<64 hex>" } }
+ * ```
+ *
+ * `policy_path` is the **basename**, not the absolute path: the log is meant to
+ * be copied, exported, and read on other machines, and an absolute path would
+ * leak the writer's home directory into a permanent record while saying nothing
+ * a reader can use. `sha256` is the file's byte digest — the field
+ * {@link checkAttestation} compares against.
+ *
+ * `ts` is **not** a parameter. `policy.updated` is one of the gate-typed events
+ * of amended SPEC.md §8 (A2), so its timestamp is assigned by the runtime at the
+ * write boundary — read once from {@link AttestOptions.clock}, which defaults to
+ * the real clock and which tests inject. Attestation is the verb that decides
+ * which policy bytes are operative from a moment onward; a caller that could
+ * choose that moment could backdate the answer.
+ *
+ * ## Why this append carries no `expectedHead` (APRV-20 finding B1)
+ *
+ * Every *other* append site in the codebase reads the log, decides something
+ * from what it read, and must therefore prove the log has not moved before it
+ * writes. This one does not read the log at all. Its only precondition is the
+ * actor check and the policy file's bytes — neither of which the log can
+ * invalidate — so there is no check-then-act window to close. A concurrent
+ * appender simply means this attestation lands after that record, which is
+ * correct: attestation is an unconditional assertion about a file's bytes at a
+ * moment, and the *latest* attestation is the one `checkAttestation` honors.
+ * Passing a precondition here would only manufacture spurious failures.
+ */
+/**
+ * The value a terminal attestation stores for the bytes it attests (APRV-356).
+ *
+ * One author for the shape, because two parties need it and they must agree:
+ * {@link appendAttestation} writes it, and `cli/amend.ts` has to name the file
+ * it will land in before the append happens, so the ceremony commit can carry
+ * it. A second spelling of `{ text }` anywhere would be a store file the
+ * ceremony quietly left behind.
+ *
+ * Deliberately narrower than `proposalPayloadValue` in `core/policy-proposal.ts`,
+ * which carries `policy_path` beside the text: a proposal is a prompt and names
+ * the file it is asking about, while an attestation is a binding and the bytes
+ * are the whole of it. The two therefore address different files in the store
+ * for the same policy, which costs one duplicate and keeps each record's
+ * binding meaning exactly one thing.
+ */
+export declare function attestedPolicyPayload(text: string): {
+    text: string;
+};
+/** The store hash {@link attestedPolicyPayload} addresses for these bytes. */
+export declare function attestedPolicyPayloadHash(text: string): string;
+export declare function appendAttestation(logPath: string, policyPath: string, actor: string, options?: AttestOptions): AttestationAppendResult;
+/**
+ * Is this record an attestation — a `policy.updated` carrying a `sha256`?
+ *
+ * `policy.updated` records **without** a `payload.sha256` are ignored for
+ * attestation purposes. Two reasons, one forward and one backward: the event
+ * type predates this verb (SPEC.md §8 has always had it, and the schema keeps
+ * it base-only with no required payload fields), so pre-attestation logs and
+ * hand-rolled tooling may carry `policy.updated` events that assert nothing
+ * about bytes; and treating such a record as an attestation would mean a
+ * payload-less event could *satisfy* the guard, which is exactly backwards.
+ * Ignoring them means an old log reads as `not-attested` — fail closed.
+ */
+export declare function attestationSha256(record: EventRecord): string | null;
+/**
+ * Compare the live policy file against the latest attestation in `records`.
+ *
+ * `records` is the log in append order, as a caller has already read and
+ * verified it; this function does no I/O on the log and never writes. The
+ * **latest** attestation wins — re-attesting after an edit is the supported
+ * repair, and an older attestation must not be able to vouch for bytes that a
+ * newer one already disagreed with.
+ *
+ * `payload.policy_path` is recorded but deliberately **not** matched against
+ * `policyPath`: v0.1 has exactly one policy file per approval home (SPEC.md
+ * §5), and a filename filter would let an attestation of `APPROVALS.md` and a
+ * live `APPROVAL.md` drift apart silently. Comparing only bytes means the
+ * mismatch surfaces as a mismatch.
+ */
+export declare function checkAttestation(records: EventRecord[], policyPath: string): AttestationStatus;
+/** The `unreadable` status for a policy read the caller performed itself. */
+export declare function unreadablePolicyStatus(policyPath: string, cause: string): AttestationStatus;
+/**
+ * {@link checkAttestation} against bytes the caller already holds.
+ *
+ * Same comparison, no read. A gate operation reads the policy file once and
+ * passes that one buffer here and to the parser (APRV-142), which is what makes
+ * "attested one policy, enforced another" structurally impossible rather than
+ * merely unlikely.
+ *
+ * The `unreadable` status has no counterpart here: bytes that exist were read.
+ * A caller whose read failed calls {@link unreadablePolicyStatus} instead, so
+ * the fail-closed ordering of {@link checkAttestation} survives the split.
+ */
+export declare function checkAttestationOfBytes(records: EventRecord[], bytes: Uint8Array): AttestationStatus;
+/**
+ * The refusal for a non-`attested` status, or `null` when policy is attested.
+ *
+ * One code (`policy-not-attested`) with a `detail` discriminator, rather than
+ * three codes: a caller that wants to refuse needs to branch on one value, and
+ * a caller that wants to explain has `detail` and `message`.
+ */
+export declare function attestationRefusal(status: AttestationStatus): AttestationRefusal | null;
+/**
+ * The human identity to record as `actor`, or `null` when none is declared.
+ *
+ * Precedence: `options.actor` (the CLI's `--as`) first, then the
+ * `APPROVAL_HUMAN` environment variable. An explicit `--as` that does not match
+ * `^human:.+` yields `null` rather than falling back to the environment —
+ * silently substituting a different identity for the one the caller typed would
+ * be worse than refusing.
+ *
+ * This is **config-declared identity**. The trust boundary is the local
+ * machine: whoever can set `APPROVAL_HUMAN` and write to the log is inside it.
+ * v0.1 makes no cryptographic claim about who attested, only that a locally
+ * privileged act occurred and was recorded.
+ */
+export declare function resolveHumanActor(options?: {
+    actor?: string;
+}): string | null;
+/**
+ * The event an ORGAN attestation is: a human's sign-off on the exact bytes of
+ * one of the gate's own organ files.
+ *
+ * ## Why the organs need this at all
+ *
+ * `.claude/settings.json` and Cursor's hook files classify `policy.core`, and
+ * `policy.core` is human-only in this repository's policy and inert to agents
+ * by §11.1 invariant 9. So the gate mints NOTHING for them: `core/gate.ts`
+ * refuses a human-only class before any record is appended, which means the
+ * protected-path guard's `granted-file` and `granted-command` verdicts cannot
+ * exist for an organ, however correctly a human edited it. PR #300 is that hole,
+ * exactly: a human hand-committed hook entries and CI failed the change because
+ * the only evidence the guard could accept was evidence the gate is designed
+ * never to produce.
+ *
+ * Attestation is the primitive that already fits. It records "a human saw these
+ * exact bytes", it needs no grant, and it matches CONTENT rather than a path, so
+ * the guard can hash the blob at head and ask the log about it.
+ *
+ * ## Why a separate event type
+ *
+ * `core/log.ts`'s `EventType` note carries the argument in full. In one line:
+ * every reader of the POLICY attestation selects on `event === "policy.updated"`,
+ * so a distinct type is invisible to all of them by construction, and
+ * {@link checkAttestationOfBytes} returns at the first `sha256`-bearing record
+ * it meets scanning backwards — an organ record wearing `policy.updated` would
+ * have made a correctly attested policy read as `hash-mismatch`.
+ */
+export declare const ORGAN_ATTESTATION_EVENT: "gate.organ.attested";
+/**
+ * The payload field naming which organ was attested.
+ *
+ * Repository-relative and `/`-separated, never absolute: the log is meant to be
+ * copied and read on other machines, and an absolute path would leak the
+ * writer's home directory into a permanent record. Unlike the policy
+ * attestation, which records a BASENAME because v0.1 has exactly one policy file
+ * per approval home, an organ record has to carry the whole relative path —
+ * there are several organs, they live in different directories, and the guard's
+ * rule is that a digest attested for one path is not evidence for another.
+ */
+export declare const ORGAN_PATH_FIELD = "organ_path";
+/**
+ * Why an organ attestation was refused: the policy attestation's codes, plus
+ * the two rules this verb has of its own.
+ *
+ * Two codes and not one, because the repairs are different and a caller must be
+ * able to tell them apart. `path-is-policy` means the caller aimed the organ
+ * verb at the policy file, whose attestation is `approval policy attest` with no
+ * `--organ` and which the gate reads on every operation. `path-not-organ` covers
+ * everything else the runtime will not attest this way: the approval home, whose
+ * contents are the human's own ceremony surface, and any ordinary file, which is
+ * not part of the gate and needs no attestation to be edited.
+ */
+export declare const ORGAN_ATTEST_ERROR_CODES: readonly ["lock-timeout", "corrupt-tail", "validation", "canonicalization", "io", "head-moved", "actor-not-human", "path-not-organ", "path-is-policy"];
+export type OrganAttestErrorCode = (typeof ORGAN_ATTEST_ERROR_CODES)[number];
+export interface OrganAttestError {
+    code: OrganAttestErrorCode;
+    message: string;
+    /** Schema errors, present when `code` is "validation". */
+    errors?: ValidationError[];
+}
+/** {@link appendOrganAttestation}'s result: the append's, widened by two codes. */
+export type OrganAttestationAppendResult = {
+    ok: true;
+    record: EventRecord;
+    line: string;
+} | {
+    ok: false;
+    error: OrganAttestError;
+};
+/**
+ * Which file to attest, in the two spellings that are not the same fact.
+ *
+ * `path` is the identity the record carries and the guard matches on, so it is
+ * repository-relative. `root` is where that path is rooted on THIS machine, and
+ * it never reaches the log. Splitting them is what keeps an absolute path out
+ * of a permanent record without making the record ambiguous about which of
+ * several organs it names.
+ */
+export interface OrganTarget {
+    /** Repository-relative, e.g. `.claude/settings.json`. */
+    path: string;
+    /** The checkout `path` is relative to; `join(root, path)` is hashed. */
+    root: string;
+}
+/** The identity and digest an organ attestation carries, or `null`. */
+export interface OrganAttestationFields {
+    organPath: string;
+    sha256: string;
+}
+/** An organ attestation found in the log, with the record it came from. */
+export interface OrganAttestation extends OrganAttestationFields {
+    record: EventRecord;
+}
+/**
+ * Append a `gate.organ.attested` record for `target` to `logPath`.
+ *
+ * The rules, all of them refused as structured results and never as throws, in
+ * the order they are checked:
+ *
+ * 1. `actor` MUST match `^human:.+`. Attestation is the verb an agent must not
+ *    perform, and it is refused here in code and again at the CLI, exactly as
+ *    {@link appendAttestation} is.
+ * 2. The path must be repository-relative: absolute paths and `..` are refused,
+ *    because the recorded identity has to mean the same file on the machine
+ *    that later reads the log.
+ * 3. The policy file is refused with its own code. It has its own attestation
+ *    and the gate reads it on every operation; letting the organ verb write a
+ *    record about it would create a second thing that looks like a policy
+ *    attestation and is not one.
+ * 4. The path must be a gate organ ({@link isGateOrganPath}). Nothing else is
+ *    attestable this way, so the verb cannot be turned into a general
+ *    "bless these bytes" primitive for any file at all.
+ *
+ * The digest is computed by the runtime from the file's exact bytes. There is
+ * no parameter for it, which is the same reason there is no `ts` parameter: a
+ * caller who could supply the hash could attest bytes nobody read, and a caller
+ * who could supply the moment could backdate what was operative when.
+ *
+ * Like {@link appendAttestation} this append carries no `expectedHead`. It reads
+ * nothing from the log, so it has no check-then-act window to close; a
+ * concurrent appender only means this record lands after theirs.
+ */
+export declare function appendOrganAttestation(logPath: string, target: OrganTarget, actor: string, options?: AttestOptions): OrganAttestationAppendResult;
+/**
+ * Is this record an organ attestation, and which bytes of which file does it
+ * vouch for?
+ *
+ * A record missing either field is ignored, for the reason a `policy.updated`
+ * with no `sha256` is ignored: a record that asserts nothing about bytes must
+ * never be able to SATISFY a check about bytes. Fail closed.
+ */
+export declare function organAttestationOf(record: EventRecord): OrganAttestationFields | null;
+/**
+ * The record in which a human attested THIS digest FOR THIS path, latest first,
+ * or `null`.
+ *
+ * Both halves are required and that is the whole rule: a digest attested for
+ * some other organ is not evidence for this one. Two organ files with identical
+ * bytes (two checkouts of the same hook entry, say) are still two files, and a
+ * human who signed one has said nothing about the other.
+ *
+ * Unlike the policy attestation there is no "latest wins" supersession here.
+ * Every organ attestation stands for the bytes it names: the guard asks about a
+ * blob at a commit that may be months old, and the newest attestation of a file
+ * says nothing about whether an older set of bytes was once signed off. The
+ * gate reads none of these records, so a stale one authorizes nothing on its
+ * own — it is evidence about a change, and evidence does not expire the way an
+ * operative policy does.
+ */
+export declare function findOrganAttestation(records: readonly EventRecord[], organPath: string, sha256: string): EventRecord | null;
+/**
+ * The most recent attestation of `organPath` at ANY digest, or `null`.
+ *
+ * What a status surface needs to tell "this file has never been attested" from
+ * "this file was attested and has been edited since". Nothing enforcing reads
+ * it: {@link findOrganAttestation} is the question the guard asks.
+ */
+export declare function latestOrganAttestation(records: readonly EventRecord[], organPath: string): OrganAttestation | null;
+/**
+ * The event a protected-path SIGN-OFF is: a human's statement that they read
+ * one `policy.edit` file at these exact bytes and stand behind them.
+ *
+ * ## The hole this fills
+ *
+ * SPEC.md's amendment-provenance rule says text that reached a protected file
+ * without a grant carries `(Amended APRV-n, pending sign-off.)` until a human
+ * ratifies it, and doubt resolves to pending. Nothing recorded the
+ * ratification. A human who had read a diff and agreed with it had exactly two
+ * ways to get it past the protected-path guard: re-make the edit under a grant,
+ * or change the guard. Both are the wrong shape — the first re-does work the
+ * human has already done with their eyes, and the second edits an enforcement
+ * path to admit one change.
+ *
+ * ## Why it is not the organ record, and not a grant either
+ *
+ * It sits between them, and the ordering is the point.
+ *
+ * A grant binds the exact hunk: `{before, after}` bytes a human saw in a
+ * prompt. It is the strongest evidence in the system about a CHANGE, and
+ * nothing here weakens it — {@link findPathSignOff} is asked only after the
+ * guard's hunk search has failed, so a covered change still passes on its
+ * grants and still prints them as its reason.
+ *
+ * {@link ORGAN_ATTESTATION_EVENT} is the other end. An organ is `policy.core`,
+ * a policy may resolve `policy.core` to `human-only`, and the gate mints
+ * nothing for a human-only class (§11.1 invariant 9), so for an organ content
+ * attestation is not the weaker evidence, it is the only evidence that can
+ * exist. A protected path is not in that position: a `policy.edit` grant for it
+ * is obtainable, so this record must never be the first thing a reader reaches
+ * for. A separate type is what makes that ordering structural rather than a
+ * convention every reader has to remember, and it is why the organ verb's
+ * refusals and this one's are not merged.
+ *
+ * The `gate.` prefix is deliberate: SPEC.md §8 keys the write-boundary clock on
+ * it, and a signer who could supply the moment could place a sign-off before
+ * bytes they had not yet seen.
+ */
+export declare const PATH_SIGN_OFF_EVENT: "gate.path.signed_off";
+/**
+ * The payload field naming which file was signed off.
+ *
+ * Repository-relative and `/`-separated, for the reason {@link ORGAN_PATH_FIELD}
+ * is: the log is copied and read on other machines, and an absolute path would
+ * leak the signer's home directory into a permanent record. Spelled `path`
+ * rather than `signed_path` because the record type already says what kind of
+ * statement it is, and a reader should not have to learn a second noun.
+ */
+export declare const SIGN_OFF_PATH_FIELD = "path";
+/**
+ * Why a sign-off was refused: the attestation codes, plus the three path rules
+ * this verb has of its own.
+ *
+ * Three and not one, because the repair differs in each case and a caller has
+ * to be able to tell them apart without reading prose:
+ *
+ * - `path-is-policy` — the policy file, whose sign-off is its attestation and
+ *   which the gate reads on every operation. A second record that looked like
+ *   a statement about the policy's bytes is exactly what the organ verb refuses
+ *   to create, for the same reason.
+ * - `path-is-core` — a `policy.core` surface or the log directory. An organ is
+ *   signed off with `--organ`, which is a different record under different
+ *   rules; the approval home and the log are the human's own ceremony surface
+ *   and are not ratified by any verb at all.
+ * - `path-not-protected` — an ordinary file, or a path that is not
+ *   repository-relative. Nothing to ratify: an unprotected file's edits are not
+ *   gated, so a record about them would assert authority over nothing.
+ */
+export declare const PATH_SIGN_OFF_ERROR_CODES: readonly ["lock-timeout", "corrupt-tail", "validation", "canonicalization", "io", "head-moved", "actor-not-human", "path-not-protected", "path-is-policy", "path-is-core"];
+export type PathSignOffErrorCode = (typeof PATH_SIGN_OFF_ERROR_CODES)[number];
+export interface PathSignOffError {
+    code: PathSignOffErrorCode;
+    message: string;
+    /** Schema errors, present when `code` is "validation". */
+    errors?: ValidationError[];
+}
+/** {@link appendPathSignOff}'s result: the append's, widened by three codes. */
+export type PathSignOffAppendResult = {
+    ok: true;
+    record: EventRecord;
+    line: string;
+} | {
+    ok: false;
+    error: PathSignOffError;
+};
+/**
+ * Which file to sign off, in the two spellings that are not the same fact,
+ * plus the policy's own protected list.
+ *
+ * `path` is the identity the record carries and the checker matches on, so it
+ * is repository-relative; `root` is where that path is rooted on THIS machine
+ * and never reaches the log. `protectedPaths` is `policy.protected_paths`: a
+ * project that widened its protected surface may sign off the files it added,
+ * and a caller that omits the list gets the built-in set alone, which is the
+ * strictly NARROWER answer and therefore the fail-closed one.
+ */
+export interface SignOffTarget {
+    /** Repository-relative, e.g. `SPEC.md`. */
+    path: string;
+    /** The checkout `path` is relative to; `join(root, path)` is hashed. */
+    root: string;
+    /** `policy.protected_paths`, widening which paths are signable. */
+    protectedPaths?: readonly ProtectedPathEntry[];
+}
+/** The identity and digest a sign-off carries, or `null`. */
+export interface PathSignOffFields {
+    path: string;
+    sha256: string;
+}
+/** A sign-off found in the log, with the record it came from. */
+export interface PathSignOff extends PathSignOffFields {
+    record: EventRecord;
+}
+/**
+ * Append a `gate.path.signed_off` record for `target` to `logPath`.
+ *
+ * The rules, refused as structured results and never as throws, in the order
+ * they are checked — and the order is normative, because a path can break more
+ * than one of them and the caller's repair depends on which they are told:
+ *
+ * 1. `actor` MUST match `^human:.+`. This is the verb an agent must not
+ *    perform: a record the party under oversight could write would let it
+ *    ratify its own text, which is the whole of what the pending-sign-off
+ *    suffix exists to prevent (§11.1 invariants 4 and 9).
+ * 2. The path must be repository-relative: absolute paths and `..` are refused,
+ *    because the recorded identity has to mean the same file on the machine
+ *    that later reads the log.
+ * 3. The policy file is refused with its own code; it has its own attestation.
+ * 4. `policy.core` and `log.mutate` surfaces are refused with their own code.
+ * 5. What remains must classify `policy.edit` or a `policy.edit.*` sub-class.
+ *    Anything else is not a protected path, and this verb is not a general
+ *    "bless these bytes" primitive.
+ *
+ * Every one of those is decided BEFORE the file is read, so a path this verb
+ * would never sign off is refused whether or not it exists.
+ *
+ * The digest is computed by the runtime from the file's exact bytes. There is
+ * no parameter for it and none for `ts`, for the reason
+ * {@link appendOrganAttestation} has neither: a caller who could supply the
+ * hash could ratify bytes nobody read, and one who could supply the moment
+ * could backdate what they had seen when.
+ *
+ * Like the attestations this append carries no `expectedHead`: it reads nothing
+ * from the log, so it has no check-then-act window to close.
+ */
+export declare function appendPathSignOff(logPath: string, target: SignOffTarget, actor: string, options?: AttestOptions): PathSignOffAppendResult;
+/**
+ * Is this record a protected-path sign-off, and which bytes of which file does
+ * it stand behind?
+ *
+ * A record missing either field is ignored, for the reason a `policy.updated`
+ * with no `sha256` is ignored: a record that asserts nothing about bytes must
+ * never be able to SATISFY a check about bytes. Fail closed.
+ */
+export declare function pathSignOffOf(record: EventRecord): PathSignOffFields | null;
+/**
+ * The record in which a human signed off THIS digest FOR THIS path, latest
+ * first, or `null`.
+ *
+ * Both halves are required and that is the whole rule, exactly as it is for an
+ * organ: a digest signed for some other file is not evidence about this one,
+ * and bytes edited after a sign-off are bytes nobody signed. Two files that
+ * happen to hash alike are still two files, and a human who read one has said
+ * nothing about the other.
+ *
+ * There is no "latest wins" supersession. A sign-off stands for the bytes it
+ * names: the checker asks about a blob at a commit that may be old, and the
+ * newest sign-off of a file says nothing about whether an earlier state was
+ * once ratified.
+ */
+export declare function findPathSignOff(records: readonly EventRecord[], path: string, sha256: string): EventRecord | null;
+/**
+ * The most recent sign-off of `path` at ANY digest, or `null`.
+ *
+ * What a status surface needs to tell "this file was never signed off" from
+ * "this file was signed off and has been edited since". Nothing enforcing reads
+ * it: {@link findPathSignOff} is the question the guard asks.
+ */
+export declare function latestPathSignOff(records: readonly EventRecord[], path: string): PathSignOff | null;