approval-md 0.2.0 → 0.4.0

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

@@ -36,6 +36,7 @@
  * 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. */
@@ -93,7 +94,7 @@ export interface AttestationRefusal {
  * 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 declare const ATTEST_ERROR_CODES: readonly ["lock-timeout", "corrupt-tail", "validation", "canonicalization", "io", "head-moved", "daemon-id-invalid", "daemon-not-allowed", "actor-not-human"];
 export type AttestErrorCode = (typeof ATTEST_ERROR_CODES)[number];
 export interface AttestError {
     code: AttestErrorCode;
@@ -201,7 +202,41 @@ export declare function policyBytesHash(bytes: Uint8Array): string;
  * 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`.
  *
@@ -258,6 +293,23 @@ export declare function attestationRefusal(status: AttestationStatus): Attestati
 export declare function resolveHumanActor(options?: {
     actor?: string;
 }): string | null;
+/**
+ * Who attested the policy at `seq`: the `actor` of the attestation record a
+ * status names, or `null` when no record at that seq is an attestation
+ * (APRV-449).
+ *
+ * `records` are VERIFIED records, as {@link checkAttestation}'s are. The answer
+ * is read from the log and never from the policy file: a tenant asking who set
+ * their starting policy is asking what was recorded, and an `approvers:` block
+ * in the file names who MAY decide, which is a different fact. Records are
+ * appended in seq order, so the record at index `seq - 1` is tried first and a
+ * scan is the fallback for a slice that does not start at genesis.
+ *
+ * The identity is config-declared (see {@link resolveHumanActor}), so this
+ * reports the identity the attesting process declared. It does not authenticate
+ * it, and a caller rendering it should not imply that it does.
+ */
+export declare function attesterAt(records: readonly EventRecord[], seq: number): 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.
@@ -312,7 +364,7 @@ export declare const ORGAN_PATH_FIELD = "organ_path";
  * 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 declare const ORGAN_ATTEST_ERROR_CODES: readonly ["lock-timeout", "corrupt-tail", "validation", "canonicalization", "io", "head-moved", "daemon-id-invalid", "daemon-not-allowed", "actor-not-human", "path-not-organ", "path-is-policy"];
 export type OrganAttestErrorCode = (typeof ORGAN_ATTEST_ERROR_CODES)[number];
 export interface OrganAttestError {
     code: OrganAttestErrorCode;
@@ -418,3 +470,183 @@ export declare function findOrganAttestation(records: readonly EventRecord[], or
  * 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", "daemon-id-invalid", "daemon-not-allowed", "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;

package/dist/src/core/attest.js

@@ -39,8 +39,10 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { basename, isAbsolute, join } from "node:path";
 import { tick } from "./clock.js";
-import { builtinProtectedPathClass, isGateOrganPath, normalizePathSpelling, } from "./command-class.js";
+import { builtinProtectedPathClass, isGateOrganPath, normalizePathSpelling, POLICY_EDIT_SUBCLASS, protectedPathClass, } from "./command-class.js";
 import { APPEND_ERROR_CODES, appendEvent, } from "./log.js";
+import { payloadHash } from "./payload.js";
+import { payloadStoreDirFor, storePayload } from "./payload-store.js";
 /**
  * Actors permitted to attest. Deliberately narrower than the event schema's
  * `^(human|agent|system):.+`: attestation is the one verb an agent must not be
@@ -170,6 +172,29 @@ export function policyBytesHash(bytes) {
  * 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 function attestedPolicyPayload(text) {
+    return { text };
+}
+/** The store hash {@link attestedPolicyPayload} addresses for these bytes. */
+export function attestedPolicyPayloadHash(text) {
+    return payloadHash(attestedPolicyPayload(text));
+}
 export function appendAttestation(logPath, policyPath, actor, options = {}) {
     if (!HUMAN_ACTOR.test(actor)) {
         return {
@@ -181,11 +206,14 @@ export function appendAttestation(logPath, policyPath, actor, options = {}) {
         };
     }
     let sha256;
+    let text;
     try {
-        // One read supplies both the expected-digest check and the recorded digest.
-        // A later edit naturally leaves the live policy hash-mismatched; it cannot
-        // make this record attest bytes other than the ones checked here.
-        sha256 = policyBytesHash(readFileSync(policyPath));
+        // One read supplies the expected-digest check, the recorded digest AND the
+        // bytes that go to the store (APRV-356). One read and not three, because
+        // three could disagree with each other about a file being edited.
+        const bytes = readFileSync(policyPath);
+        sha256 = policyBytesHash(bytes);
+        text = bytes.toString("utf8");
     }
     catch (cause) {
         return {
@@ -205,11 +233,40 @@ export function appendAttestation(logPath, policyPath, actor, options = {}) {
             },
         };
     }
+    // APRV-356. The attested BYTES go to the content-addressed store and the
+    // record binds their hash, so the policy in force is recoverable from any
+    // chain attested after this lands.
+    //
+    // Before it, only an attestation that answered a phone PROPOSAL left
+    // recoverable bytes (`policy.proposed` binds the whole text, SPEC.md §10.4),
+    // and a chain only ever attested at a terminal — this repository included —
+    // had none. `inForcePolicyText` then failed, and the privileged-gesture rule
+    // of APRV-324 fell back to refusing, which is safe and leaves the residual
+    // that an amendment REMOVING a sender mapping is indistinguishable from a
+    // policy that never had one.
+    //
+    // A store that cannot be written REFUSES the attestation, and nothing is
+    // appended. That is the fail-closed direction and it is deliberate: a record
+    // claiming a binding whose bytes are absent would be a worse artifact than no
+    // record, and the store sits beside the log, which this verb is about to
+    // write anyway. The alternative considered — append without the binding, as
+    // before — was rejected because it would make the recoverability guarantee
+    // conditional on a condition no reader of the record can see.
+    const stored = storePayload(payloadStoreDirFor(logPath), attestedPolicyPayload(text));
+    if (!stored.ok) {
+        return {
+            ok: false,
+            error: {
+                code: "io",
+                message: `the attested bytes of ${basename(policyPath)} could not be stored beside the log (${stored.message}); the log was left unchanged, because an attestation whose bytes are unrecoverable is the state this verb exists to end`,
+            },
+        };
+    }
     return appendEvent(logPath, {
         ts: tick(options),
         event: "policy.updated",
         actor,
-        payload: { policy_path: basename(policyPath), sha256 },
+        payload: { policy_path: basename(policyPath), sha256, payload_hash: stored.hash },
     }, options);
 }
 /**
@@ -224,7 +281,7 @@ export function appendAttestation(logPath, policyPath, actor, options = {}) {
  * payload-less event could *satisfy* the guard, which is exactly backwards.
  * Ignoring them means an old log reads as `not-attested` — fail closed.
  */
-function attestationSha256(record) {
+export function attestationSha256(record) {
     if (record.event !== "policy.updated")
         return null;
     const payload = record.payload;
@@ -353,6 +410,31 @@ export function resolveHumanActor(options = {}) {
         return fromEnv;
     return null;
 }
+/**
+ * Who attested the policy at `seq`: the `actor` of the attestation record a
+ * status names, or `null` when no record at that seq is an attestation
+ * (APRV-449).
+ *
+ * `records` are VERIFIED records, as {@link checkAttestation}'s are. The answer
+ * is read from the log and never from the policy file: a tenant asking who set
+ * their starting policy is asking what was recorded, and an `approvers:` block
+ * in the file names who MAY decide, which is a different fact. Records are
+ * appended in seq order, so the record at index `seq - 1` is tried first and a
+ * scan is the fallback for a slice that does not start at genesis.
+ *
+ * The identity is config-declared (see {@link resolveHumanActor}), so this
+ * reports the identity the attesting process declared. It does not authenticate
+ * it, and a caller rendering it should not imply that it does.
+ */
+export function attesterAt(records, seq) {
+    const direct = records[seq - 1];
+    const record = direct !== undefined && direct.seq === seq
+        ? direct
+        : records.find((candidate) => candidate.seq === seq);
+    if (record === undefined || attestationSha256(record) === null)
+        return null;
+    return record.actor;
+}
 // ===========================================================================
 // Organ attestation (APRV-272, amended SPEC.md §5.2 and §8)
 // ===========================================================================
@@ -586,4 +668,257 @@ export function latestOrganAttestation(records, organPath) {
     }
     return null;
 }
+// ===========================================================================
+// Protected-path sign-off (APRV-338, amended SPEC.md §5.2, §8 and §10.1)
+// ===========================================================================
+/**
+ * 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 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 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 const PATH_SIGN_OFF_ERROR_CODES = [
+    ...ATTEST_ERROR_CODES,
+    "path-not-protected",
+    "path-is-policy",
+    "path-is-core",
+];
+/**
+ * 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 function appendPathSignOff(logPath, target, actor, options = {}) {
+    if (!HUMAN_ACTOR.test(actor)) {
+        return {
+            ok: false,
+            error: {
+                code: "actor-not-human",
+                message: `signing off a protected path requires a human actor matching ^human:.+, got ${JSON.stringify(actor)}; this record is what resolves the pending-sign-off suffix, so an agent that could write one could ratify its own text, and the log was left unchanged`,
+            },
+        };
+    }
+    const refusal = signOffPathRefusal(target.path, target.protectedPaths ?? []);
+    if (refusal !== null)
+        return { ok: false, error: refusal };
+    const path = normalizePathSpelling(target.path);
+    let sha256;
+    try {
+        sha256 = policyFileHash(join(target.root, path));
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            error: {
+                code: "io",
+                message: `protected path ${path} could not be read under ${target.root} for sign-off: ${detail(cause)}`,
+            },
+        };
+    }
+    return appendEvent(logPath, {
+        ts: tick(options),
+        event: PATH_SIGN_OFF_EVENT,
+        actor,
+        payload: { [SIGN_OFF_PATH_FIELD]: path, sha256 },
+    }, options);
+}
+/** Rules 2 to 5 of {@link appendPathSignOff}, or `null` when the path passes. */
+function signOffPathRefusal(candidate, extra) {
+    const normalized = normalizePathSpelling(candidate);
+    if (normalized.length === 0 || isAbsolute(candidate) || normalized.split("/").includes("..")) {
+        return {
+            code: "path-not-protected",
+            message: `${JSON.stringify(candidate)} is not a repository-relative path; a sign-off records the path itself, so it must name the same file on every machine that later reads the log`,
+        };
+    }
+    const builtin = builtinProtectedPathClass(normalized);
+    if (builtin === "policy.core") {
+        const last = normalized.split("/").pop() ?? normalized;
+        if (POLICY_FILE_NAMES.includes(last)) {
+            return {
+                code: "path-is-policy",
+                message: `${normalized} is the policy file, whose sign-off is its attestation: \`approval policy attest\` with no --path, which the gate reads on every operation. A second record about those bytes would be a thing that looks like an attestation and is not one`,
+            };
+        }
+        return {
+            code: "path-is-core",
+            message: isGateOrganPath(normalized)
+                ? `${normalized} is one of the gate's organs, which is signed off by content with \`approval policy attest --organ ${normalized}\`; that is a different record under different rules, because an organ is policy.core and can have no grant at all, while a protected path can`
+                : `${normalized} is inside the approval home, which is the human's own ceremony surface and is ratified by no verb`,
+        };
+    }
+    if (builtin === "log.mutate") {
+        return {
+            code: "path-is-core",
+            message: `${normalized} is inside the log directory, which no verb of this runtime signs off: the log is append-only and its contents are evidence rather than text anyone ratifies`,
+        };
+    }
+    const routed = protectedPathClass(normalized, extra);
+    if (routed === "policy.edit" || (routed !== null && POLICY_EDIT_SUBCLASS.test(routed))) {
+        return null;
+    }
+    return {
+        code: "path-not-protected",
+        message: `${normalized} does not classify policy.edit or a policy.edit.* sub-class${extra.length === 0 ? " under the built-in protected set (no policy.protected_paths were supplied, which is the narrower reading)" : " under the built-in protected set widened by policy.protected_paths"}, so it is not a protected path and nothing about it is gated; a sign-off on it would assert authority over nothing`,
+    };
+}
+/**
+ * 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 function pathSignOffOf(record) {
+    if (record.event !== PATH_SIGN_OFF_EVENT)
+        return null;
+    const payload = record.payload;
+    if (payload === undefined)
+        return null;
+    const path = payload[SIGN_OFF_PATH_FIELD];
+    const sha256 = payload["sha256"];
+    if (typeof path !== "string" || typeof sha256 !== "string")
+        return null;
+    const normalized = normalizePathSpelling(path);
+    if (normalized.length === 0)
+        return null;
+    return { path: normalized, sha256 };
+}
+/**
+ * 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 function findPathSignOff(records, path, sha256) {
+    const want = normalizePathSpelling(path);
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const record = records[index];
+        const fields = pathSignOffOf(record);
+        if (fields === null)
+            continue;
+        if (fields.path === want && fields.sha256 === sha256)
+            return record;
+    }
+    return 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 function latestPathSignOff(records, path) {
+    const want = normalizePathSpelling(path);
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const record = records[index];
+        const fields = pathSignOffOf(record);
+        if (fields === null)
+            continue;
+        if (fields.path === want)
+            return { ...fields, record };
+    }
+    return null;
+}
 //# sourceMappingURL=attest.js.map