approval-md 0.1.0 → 0.2.0

package/dist/src/core/log-subscribe.js

@@ -0,0 +1,162 @@
+/**
+ * Pull-based subscription to the verified event log (APRV-322).
+ *
+ * A filesystem notification is only a hint that another read may be useful.
+ * Every emitted batch comes from one complete, genesis-to-head verification;
+ * a notification, a parsed line, or an intact prefix is never authority by
+ * itself. The iterator queues no events: while a consumer is slow it retains
+ * only the current verified snapshot and coalesces every wakeup into one bit.
+ */
+import { readFileSync, watch } from "node:fs";
+import { dirname } from "node:path";
+import { verifyText } from "./verify.js";
+/** A terminal subscription failure, mapped by the CLI to the existing exits. */
+export class LogSubscriptionError extends Error {
+    kind;
+    reason;
+    constructor(kind, message, reason = null) {
+        super(message);
+        this.name = "LogSubscriptionError";
+        this.kind = kind;
+        this.reason = reason;
+    }
+}
+const DEFAULT_POLL_INTERVAL_MS = 500;
+function readSnapshot(logPath) {
+    try {
+        return readFileSync(logPath, "utf8");
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return "";
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new LogSubscriptionError("io", `log ${logPath} could not be read: ${detail}`);
+    }
+}
+function checkedSnapshot(logPath) {
+    const verified = verifyText(logPath, readSnapshot(logPath));
+    if (verified.result.status === "torn-tail") {
+        throw new LogSubscriptionError("torn-tail", verified.result.message);
+    }
+    if (verified.result.status === "corrupt") {
+        throw new LogSubscriptionError("integrity", verified.result.message, verified.result.reason);
+    }
+    return verified.records;
+}
+function validateOptions(options) {
+    const from = options.from ?? 0;
+    if (!Number.isSafeInteger(from) || from < 0) {
+        throw new TypeError(`from must be a non-negative safe integer, got ${String(from)}`);
+    }
+    if (options.expectedHash !== undefined) {
+        if (from === 0)
+            throw new TypeError("expectedHash requires from to be greater than zero");
+        if (!/^[a-f0-9]{64}$/u.test(options.expectedHash)) {
+            throw new TypeError("expectedHash must be a lowercase 64-character SHA-256 digest");
+        }
+    }
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 1) {
+        throw new TypeError(`pollIntervalMs must be a positive safe integer, got ${String(pollIntervalMs)}`);
+    }
+    return { from, expectedHash: options.expectedHash, pollIntervalMs };
+}
+/**
+ * Yield verified records after an exclusive cursor, then wait for appends.
+ *
+ * The optional expected hash binds the first read to the caller's stored
+ * cursor. After every yield, the iterator carries that same binding forward,
+ * so truncation or replacement during one process lifetime is also refused.
+ */
+export async function* subscribeVerifiedLog(logPath, options = {}) {
+    const parsed = validateOptions(options);
+    let cursorSeq = parsed.from;
+    let cursorHash = parsed.expectedHash;
+    let wakeVersion = 0;
+    let wake = null;
+    let watcher = null;
+    let timer = null;
+    const hint = () => {
+        wakeVersion += 1;
+        const pending = wake;
+        wake = null;
+        pending?.();
+    };
+    const abort = () => hint();
+    options.signal?.addEventListener("abort", abort, { once: false });
+    // Watch the directory so creation of an initially absent log is visible.
+    // Failure to establish a watch is harmless: bounded polling remains active.
+    try {
+        watcher = watch(dirname(logPath), { persistent: false }, hint);
+        watcher.on("error", hint);
+    }
+    catch {
+        watcher = null;
+    }
+    try {
+        while (!options.signal?.aborted) {
+            const versionBeforeRead = wakeVersion;
+            const records = checkedSnapshot(logPath);
+            const headSeq = records.at(-1)?.seq ?? 0;
+            if (cursorSeq > headSeq) {
+                throw new LogSubscriptionError("integrity", `log ${logPath} ends at seq ${String(headSeq)}, before subscription cursor seq ${String(cursorSeq)}: records have been removed or this cursor belongs to another log`, "cursor-mismatch");
+            }
+            if (cursorSeq > 0) {
+                const actual = records[cursorSeq - 1];
+                if (actual === undefined || (cursorHash !== undefined && actual.hash !== cursorHash)) {
+                    throw new LogSubscriptionError("integrity", `log ${logPath} does not match subscription cursor seq ${String(cursorSeq)}${cursorHash === undefined ? "" : ` hash ${cursorHash}`}: the retained prefix was truncated, replaced, or belongs to another log`, "cursor-mismatch");
+                }
+                // A sequence-only bootstrap is weaker on its first read, by design,
+                // but once this process has verified that prefix it can retain the
+                // actual digest and detect any later replacement even while caught up.
+                cursorHash ??= actual.hash;
+            }
+            // No slice: it would duplicate an arbitrarily large suffix. The verified
+            // snapshot is the only event-bearing allocation retained by this batch.
+            for (let index = cursorSeq; index < records.length; index += 1) {
+                if (options.signal?.aborted)
+                    return;
+                const record = records[index];
+                if (record === undefined)
+                    break;
+                // The yielded object is ordinary mutable JavaScript. Capture the
+                // verified cursor before handing it to untrusted consumer code, so a
+                // mutation cannot change where this iterator resumes or what prefix it
+                // binds on the next verification.
+                const verifiedSeq = record.seq;
+                const verifiedHash = record.hash;
+                yield record;
+                cursorSeq = verifiedSeq;
+                cursorHash = verifiedHash;
+            }
+            if (options.signal?.aborted)
+                return;
+            // An append between watcher setup/read/drain and this point changes the
+            // version and causes an immediate verification instead of a lost wakeup.
+            if (wakeVersion !== versionBeforeRead)
+                continue;
+            const versionBeforeWait = wakeVersion;
+            await new Promise((resolve) => {
+                wake = resolve;
+                timer = setTimeout(hint, parsed.pollIntervalMs);
+                // Close the last race: an abort or append may land after the check
+                // above and before `wake` is installed. Its version change must turn
+                // into an immediate retry, not a wait for the polling fallback.
+                if (options.signal?.aborted || wakeVersion !== versionBeforeWait)
+                    hint();
+            });
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = null;
+            wake = null;
+        }
+    }
+    finally {
+        if (timer !== null)
+            clearTimeout(timer);
+        wake = null;
+        watcher?.close();
+        options.signal?.removeEventListener("abort", abort);
+    }
+}
+//# sourceMappingURL=log-subscribe.js.map

package/dist/src/core/log-subscribe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-subscribe.js","sourceRoot":"","sources":["../../../src/core/log-subscribe.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,EAAkB,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,UAAU,EAA4B,MAAM,aAAa,CAAC;AAInE,gFAAgF;AAChF,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAA6B;IACjC,MAAM,CAAiD;IAEhE,YACE,IAAgC,EAChC,OAAe,EACf,MAAM,GAAmD,IAAI;QAE7D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAaD,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,SAAS,YAAY,CAAC,OAAe;IACnC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAClE,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,oBAAoB,CAAC,IAAI,EAAE,OAAO,OAAO,uBAAuB,MAAM,EAAE,CAAC,CAAC;IACtF,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,OAAe;IACtC,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5D,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAC3C,MAAM,IAAI,oBAAoB,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACzC,MAAM,IAAI,oBAAoB,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC;AAED,SAAS,eAAe,CAAC,OAA+B;IAKtD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,SAAS,CAAC,iDAAiD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,IAAI,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;QAC1F,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;IAC1E,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CACjB,uDAAuD,MAAM,CAAC,cAAc,CAAC,EAAE,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,cAAc,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,oBAAoB,CACzC,OAAe,EACf,OAAO,GAA2B,EAAE;IAEpC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC;IAC5B,IAAI,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC;IACrC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,IAAI,GAAwB,IAAI,CAAC;IACrC,IAAI,OAAO,GAAqB,IAAI,CAAC;IACrC,IAAI,KAAK,GAAyC,IAAI,CAAC;IAEvD,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,WAAW,IAAI,CAAC,CAAC;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC;QACrB,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO,EAAE,EAAE,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,GAAS,EAAE,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAElE,yEAAyE;IACzE,4EAA4E;IAC5E,IAAI,CAAC;QACH,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAC/D,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAChC,MAAM,iBAAiB,GAAG,WAAW,CAAC;YACtC,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,OAAO,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;YAEzC,IAAI,SAAS,GAAG,OAAO,EAAE,CAAC;gBACxB,MAAM,IAAI,oBAAoB,CAC5B,WAAW,EACX,OAAO,OAAO,gBAAgB,MAAM,CAAC,OAAO,CAAC,oCAAoC,MAAM,CAAC,SAAS,CAAC,mEAAmE,EACrK,iBAAiB,CAClB,CAAC;YACJ,CAAC;YACD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;gBAClB,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;gBACtC,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,EAAE,CAAC;oBACrF,MAAM,IAAI,oBAAoB,CAC5B,WAAW,EACX,OAAO,OAAO,2CAA2C,MAAM,CAAC,SAAS,CAAC,GACxE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,UAAU,EACrD,0EAA0E,EAC1E,iBAAiB,CAClB,CAAC;gBACJ,CAAC;gBACD,oEAAoE;gBACpE,mEAAmE;gBACnE,uEAAuE;gBACvE,UAAU,KAAK,MAAM,CAAC,IAAI,CAAC;YAC7B,CAAC;YAED,yEAAyE;YACzE,wEAAwE;YACxE,KAAK,IAAI,KAAK,GAAG,SAAS,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC/D,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;oBAAE,OAAO;gBACpC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC9B,IAAI,MAAM,KAAK,SAAS;oBAAE,MAAM;gBAChC,iEAAiE;gBACjE,qEAAqE;gBACrE,uEAAuE;gBACvE,kCAAkC;gBAClC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC;gBAC/B,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC;gBACjC,MAAM,MAAM,CAAC;gBACb,SAAS,GAAG,WAAW,CAAC;gBACxB,UAAU,GAAG,YAAY,CAAC;YAC5B,CAAC;YAED,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;gBAAE,OAAO;YACpC,wEAAwE;YACxE,yEAAyE;YACzE,IAAI,WAAW,KAAK,iBAAiB;gBAAE,SAAS;YAEhD,MAAM,iBAAiB,GAAG,WAAW,CAAC;YACtC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,IAAI,GAAG,OAAO,CAAC;gBACf,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;gBAChD,mEAAmE;gBACnE,qEAAqE;gBACrE,gEAAgE;gBAChE,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,WAAW,KAAK,iBAAiB;oBAAE,IAAI,EAAE,CAAC;YAC3E,CAAC,CAAC,CAAC;YACH,IAAI,KAAK,KAAK,IAAI;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,KAAK,KAAK,IAAI;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO,EAAE,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,278 @@
+/**
+ * Append-only event log writer (SPEC.md §8, `.approval/log/events.jsonl`).
+ *
+ * The log is the truth. This module is the *only* sanctioned way to put a line
+ * into it, and its public API deliberately exposes no mutation, reorder,
+ * rewrite, or truncate operation — there is nothing here to call that could
+ * disturb an existing byte. Reading, verifying, and projecting live elsewhere.
+ *
+ * Guarantees, in the order they are enforced by {@link appendEvent}:
+ *
+ * 1. **Exclusive access.** A dependency-free advisory lockfile (`<log>.lock`,
+ *    created `wx`) serializes the read-tail → compute → write sequence, so two
+ *    concurrent appenders cannot both read seq N and both write seq N+1.
+ * 1b. **Compare-and-append (APRV-20 finding B1).** The lock serializes *writes*,
+ *    but every caller that checks the log before appending — "no live request
+ *    exists", "this token is unspent", "the budget has room" — made that check
+ *    outside the lock, against a log that could have moved on before its own
+ *    append took the lock. {@link AppendOptions.expectedHead} closes that
+ *    window: the caller states the `(seq, hash)` it read, this module compares
+ *    it against the actual tail **under the lock**, and refuses `head-moved`
+ *    when they differ. Nothing is written. The refusal is deliberately *not*
+ *    retried here: only the caller knows whether re-deriving its decision
+ *    against the newer log is safe, so the core reports and stops.
+ * 2. **Refuse to build on a corrupt tail.** If the file's last line is
+ *    truncated (no terminating newline) or unparseable, the append is
+ *    rejected. Chaining onto a half-written record would bake the corruption
+ *    into every subsequent hash. Since APRV-206 that tail is read from the END
+ *    of the file rather than by reading the whole log: an append needs the last
+ *    line and nothing else, and paying one full read of an ever-growing file per
+ *    append put log length into the latency of every grant. Every refusal above
+ *    is unchanged, byte for byte.
+ * 3. **The runtime stamps the chain fields.** Callers supply content only;
+ *    `seq`, `prev`, `alg`, and `hash` are computed here. `alg` is always
+ *    `sha256/jcs` (SPEC.md §8 defines exactly one value at v0.1).
+ * 4. **Validate at the write boundary.** The complete record — chain fields
+ *    included — must pass the `event` JSON Schema before any byte is written.
+ *    On failure the file is left byte-identical and a structured error is
+ *    returned. Fail closed: nothing here throws a validation problem past the
+ *    caller as a partially-written line.
+ * 5. **One line, one write.** The stored line is the JCS canonicalization of
+ *    the complete record (`hash` included); the digest input is that same
+ *    canonicalization minus the `hash` field. One scheme, two inputs — a
+ *    verifier strips `hash` and re-derives. Appended with a single `write(2)`
+ *    on a handle opened `O_APPEND`.
+ *
+ * Determinism: `ts` is supplied by the caller. This module never reads the
+ * clock, because a hash-relevant field sourced from ambient state would make
+ * the log irreproducible.
+ */
+import { type ValidateOptions, type ValidationError } from "./validate.js";
+/** SPEC.md §8: the hash scheme identifier stamped on every v0.1 record. */
+export declare const ALG = "sha256/jcs";
+/**
+ * SPEC.md §8: `prev` of the first record in a log. `null`, not a zero digest —
+ * the schema and the `genesis-null-prev` fixture both encode this choice.
+ */
+export declare const GENESIS_PREV: null;
+/**
+ * The closed set of event types (SPEC.md §8, mirrored by the schema enum).
+ *
+ * `payload.pruned` (APRV-38) is the first addition after the v0.1 draft set of
+ * sixteen: the daemon appends one per payload file it removes under
+ * `payload_retention`, so a log states what its payload store no longer holds.
+ * `approval.withdrawn` (APRV-106) is the second: the requester's retraction of
+ * a request nobody has answered yet (amended SPEC.md §6.3).
+ * `execution.indeterminate` and `execution.reconciled` (APRV-120) are the third
+ * and fourth: a side effect that was attempted and whose outcome is unknown, and
+ * the human resolution that later says which it was (amended SPEC.md §6.3,
+ * §10.4).
+ * `reconciliation.required` / `reconciliation.satisfied` (APRV-127) are the
+ * fifth and sixth: the obligation a retrospective DENIAL creates, and the
+ * human act that discharges it (amended SPEC.md §5.2).
+ * `policy.proposed` / `policy.declined` (APRV-109) are the seventh and eighth:
+ * an agent asking a human to attest prepared policy bytes, and the human's
+ * refusal (amended SPEC.md §10.1, §10.3). The acceptance is `policy.updated`,
+ * which already existed and is still the only event an attestation is.
+ * `audit.dark_session` (APRV-192) is the ninth: the daemon recording git
+ * activity it can see for which the log carries no corresponding record
+ * (amended SPEC.md §10.2). It is an observation the RUNTIME makes about a
+ * session, never a record written on a session's behalf, so it carries a
+ * `system:` actor and the schema refuses any other.
+ * `gate.opened`, `gate.closed` and `gate.bypassed` (APRV-214) are the tenth,
+ * eleventh and twelfth: a human time-boxing a full harness bypass so the gate
+ * itself can be debugged, that human closing it early, and one gated tool call
+ * the hook allowed while it stood (amended SPEC.md §5.2). The window's whole
+ * state is these records, deliberately: a file the runtime read on its own
+ * would let anything able to write it act as the human. The first two carry a
+ * `human:` actor and the schema refuses any other.
+ * `log.checkpoint` (APRV-220) is the thirteenth: a human's signature over the
+ * chain head at a moment, made with a key no agent process holds. The chain is
+ * unkeyed, so a party with write access to this file can truncate it and
+ * recompute a self-consistent forgery; a checkpoint is a witness that survives
+ * them, because a rewritten chain cannot reproduce a signature over the hashes
+ * it replaced. Human actor, for the reason `gate.opened` carries one.
+ * `audit.decision_refused` (APRV-235) is the fourteenth: a human decided
+ * through a channel or the CLI and the gate refused to record the decision, so
+ * the log states that the answer was given and could not be taken (amended
+ * SPEC.md §5.2). Audit tier — it grants nothing, and no verdict, budget, streak
+ * or sampling path reads it. `system:` actor, like `audit.dark_session`: it is
+ * the runtime's statement about its own refusal, and the human whose decision
+ * it was is named in the payload. Refusals handed to AGENTS are not recorded;
+ * the asymmetry is deliberate, and `core/decision-refusal.ts` states why.
+ * `gate.organ.attested` (APRV-272) is the fifteenth: a human's sign-off on the
+ * exact bytes of one of the gate's ORGANS, the harness files that install the
+ * hook (amended SPEC.md §5.2, §8). Those files are `policy.core`, which is
+ * human-only, so the gate mints no record of any kind for them and no
+ * grant-shaped evidence for a hand edit to one can exist; content attestation
+ * is the only evidence there is, and this is it. `human:` actor and the schema
+ * refuses any other, for the reason `gate.opened` carries the same rule.
+ *
+ * It is a type of its own rather than a `policy.updated` variant, and that is
+ * the load-bearing choice: every reader of the POLICY attestation selects on
+ * `event === "policy.updated"` (`core/attest.ts`, `core/policy-proposal.ts`,
+ * `cli/amend.ts`, `cli/channel-telegram.ts`, `core/protected-path-guard.ts`),
+ * so a distinct type is ignored by all of them by construction rather than by a
+ * filter each one would have to remember. `checkAttestationOfBytes` returns at
+ * the FIRST record carrying a `sha256` as it scans backwards, so an organ
+ * attestation written as a `policy.updated` would have reported a correctly
+ * attested policy as `hash-mismatch` and refused every gate operation until
+ * somebody re-attested it. The `gate.` prefix already carries the write-boundary
+ * clock in `core/verify.ts`, which is what an attestation's `ts` has to be.
+ */
+export type EventType = "task.registered" | "route.proposed" | "route.accepted" | "approval.requested" | "approval.granted" | "approval.rejected" | "approval.expired" | "approval.revoked" | "approval.withdrawn" | "execution.started" | "execution.completed" | "execution.failed" | "execution.indeterminate" | "execution.reconciled" | "budget.exceeded" | "policy.updated" | "policy.proposed" | "policy.declined" | "envelope.drift" | "audit.sampled" | "audit.reviewed" | "audit.dark_session" | "audit.decision_refused" | "reconciliation.required" | "reconciliation.satisfied" | "payload.pruned" | "gate.opened" | "gate.closed" | "gate.bypassed" | "gate.organ.attested" | "log.checkpoint";
+/** Caller-supplied content of an event. Chain fields are not accepted. */
+export interface EventInput {
+    /** RFC 3339 timestamp. Supplied by the caller; never read from the clock. */
+    ts: string;
+    event: EventType;
+    /** `human:`, `agent:`, or `system:` prefixed identity (SPEC.md §8). */
+    actor: string;
+    task?: string;
+    action_key?: string;
+    channel?: string;
+    payload?: Record<string, unknown>;
+}
+/** A complete log record: caller content plus runtime-stamped chain fields. */
+export interface EventRecord extends EventInput {
+    seq: number;
+    alg: typeof ALG;
+    hash: string;
+    prev: string | null;
+}
+/** The hash input: a record with every field except `hash`. */
+export type UnhashedRecord = Omit<EventRecord, "hash">;
+/**
+ * Why an append was refused. Every failure is one of these, never a throw.
+ *
+ * Frozen public API in the same sense the gate's refusal codes are: callers
+ * branch on these strings, so adding one is a spec change and renaming one is a
+ * breaking change. `head-moved` is the APRV-20 addition (finding B1), sanctioned
+ * by the human decision of 2026-08-07.
+ */
+export declare const APPEND_ERROR_CODES: readonly [
+/** The lockfile was held by another writer for longer than the timeout. */
+"lock-timeout", 
+/** The file's last line is truncated or unparseable; nothing may chain onto it. */
+"corrupt-tail", 
+/** The complete record failed the `event` schema at the write boundary. */
+"validation", 
+/** The record could not be canonicalized (RFC 8785). */
+"canonicalization", 
+/** The log could not be created, opened, or written. */
+"io", 
+/**
+ * The caller supplied {@link AppendOptions.expectedHead} and the log's actual
+ * tail, read under the lock, is a different `(seq, hash)`. Someone appended
+ * between the caller's read and this append, so every read-dependent check the
+ * caller made is stale. Nothing was written.
+ */
+"head-moved"];
+export type AppendErrorCode = (typeof APPEND_ERROR_CODES)[number];
+export interface AppendError {
+    code: AppendErrorCode;
+    message: string;
+    /** Schema errors, present when `code` is "validation". */
+    errors?: ValidationError[];
+}
+export type AppendResult = {
+    ok: true;
+    record: EventRecord;
+    line: string;
+} | {
+    ok: false;
+    error: AppendError;
+};
+/**
+ * A chain head: the last record's position and digest.
+ *
+ * Defined here rather than in `core/verify.ts` because the writer needs it for
+ * {@link AppendOptions.expectedHead} and the writer cannot import the verifier
+ * (the verifier imports the writer). `core/verify.ts` re-exports this exact
+ * type, so there is one definition and one meaning.
+ */
+export interface LogHead {
+    seq: number;
+    hash: string;
+}
+/** Options for {@link appendEvent}. */
+export interface AppendOptions extends ValidateOptions {
+    /** Milliseconds to keep retrying the lockfile before giving up. */
+    lockTimeoutMs?: number;
+    /** Milliseconds between lock acquisition attempts. */
+    lockRetryMs?: number;
+    /**
+     * Compare-and-append precondition (guarantee 1b in the module header).
+     *
+     * - a `LogHead` — the append proceeds only if the log's tail is exactly that
+     *   `(seq, hash)`;
+     * - `null` — the append proceeds only if the log is empty or absent;
+     * - absent/`undefined` — no precondition, the pre-APRV-20 behavior.
+     *
+     * Evaluated **under the lock**, after the tail is read and before anything is
+     * computed or written. A mismatch is `head-moved` and writes nothing. Callers
+     * that made a decision from the log MUST pass the head they read; callers with
+     * no read-dependent decision (an unconditional append) legitimately omit it.
+     */
+    expectedHead?: LogHead | null;
+}
+/** How long a whole-operation lock holder waits before reporting `lock-timeout`. */
+export interface LockOptions {
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+}
+/** The outcome of {@link withAppendLock}: the callback's value, or a refusal. */
+export type LockedResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AppendError;
+};
+/**
+ * The record's digest under `alg: "sha256/jcs"`.
+ *
+ * Hash input = **the full record minus its `hash` property**, with `prev`
+ * included, serialized per RFC 8785 (JCS) and digested with SHA-256. Output is
+ * lowercase hex. Passing an already-hashed record is fine: the `hash` field is
+ * removed before canonicalization, so `computeRecordHash(r)` is stable whether
+ * or not `r` carries a digest.
+ */
+export declare function computeRecordHash(record: UnhashedRecord | EventRecord): string;
+/**
+ * Inverse of {@link computeRecordHash}: recompute and compare. Lives beside
+ * the writer so the two can never diverge; the M1 chain verifier consumes it.
+ */
+export declare function verifyRecordHash(record: EventRecord): boolean;
+/** The stored line for a record: its canonical serialization (no newline). */
+export declare function serializeRecord(record: EventRecord): string;
+/**
+ * Append exactly one event to `logPath`, stamping `seq`, `prev`, `alg`, and
+ * `hash`.
+ *
+ * Returns a structured result rather than throwing: an append that cannot be
+ * made safely leaves the file byte-identical and says why.
+ *
+ * Pass {@link AppendOptions.expectedHead} whenever the append is authorized by
+ * something read from the log: the head is compared under the lock and a moved
+ * head refuses `head-moved` without writing.
+ */
+/**
+ * Hold `<logPath>.lock` for the whole of `run`, then release it.
+ *
+ * The lockfile exists so that a read-tail → compute → write sequence cannot
+ * interleave with another writer's. Some operations need that exclusion over a
+ * span much longer than one append: `approval log sync` (APRV-125) reads the
+ * chain, moves the file aside, lets git advance the committed baseline, and
+ * puts the chain back, and an append landing anywhere inside that window is
+ * exactly the interleaving that forked this repository's own log on 2026-08-20.
+ *
+ * The callback is handed no lock handle and no write primitive: this module
+ * still exposes nothing that mutates an existing byte, and a caller holding the
+ * lock has the same append-only API everyone else has. What it gains is the
+ * guarantee that nobody else is appending while it works.
+ */
+export declare function withAppendLock<T>(logPath: string, run: () => T, options?: LockOptions): LockedResult<T>;
+/** Subscribe to successful appends. Process-wide, memory-only, additive. */
+export declare function onLogAppended(listener: (logPath: string) => void): void;
+export declare function appendEvent(logPath: string, input: EventInput, options?: AppendOptions): AppendResult;