approval-md 0.0.1 → 0.2.0

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;