approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,505 @@
+/**
+ * Derived state: the one place the runtime turns the log into answers
+ * (SPEC.md §6.3, §7, §8).
+ *
+ * Everything the gate, the token module, and the executor believe about an
+ * action comes from here. The module exists for two reasons, both structural,
+ * both from the APRV-20 review:
+ *
+ * 1. **Verified reads (finding S1).** {@link readVerifiedRecords} is the only
+ *    sanctioned way for a decision-making module to read the log. It runs the
+ *    *full* chain verification — hash recompute, schema validation, `prev`/`seq`
+ *    walk — by calling `core/verify.ts`'s {@link verifyWithRecords}, and refuses
+ *    a corrupt log outright. Before this, the gate parsed lines as JSON and
+ *    trusted them: a forged or spliced record could authorize an action, and the
+ *    corruption would surface only when someone ran `approval log verify`. A
+ *    permission system that reads its own evidence without checking it is not a
+ *    permission system.
+ *
+ *    APRV-43 lifted the linear cost that S1 accepted; see "The verified-read
+ *    cache" below. What it did not lift is the rule: a decision is still made
+ *    only from records this process verified in full, against bytes it proved
+ *    unchanged.
+ *
+ * 2. **One derivation, no cycle (finding S4).** {@link requestState} used to
+ *    live in `core/gate.ts`, which `core/token.ts` imported — while
+ *    `core/gate.ts` imported `core/token.ts` to mint at grant. That import cycle
+ *    made "which module owns approval state?" unanswerable. The derivation lives
+ *    here now; `gate.ts`, `token.ts`, and `execute.ts` all import it, and the
+ *    only remaining edge between them is the intended one, gate → token, at the
+ *    mint seam. `gate.ts` re-exports the moved names so existing importers (the
+ *    CLI, the tests) are unaffected.
+ *
+ * ## The verified-read cache (APRV-43), and why it is not a bypass
+ *
+ * A daemon re-reads the log on every watch event. Re-verifying from genesis
+ * every time makes a session quadratic in the log it is watching, so
+ * {@link readVerifiedRecords} keeps a process-lifetime, memory-only cache of the
+ * last log it verified clean: the prefix bytes' length, a SHA-256 over those
+ * bytes, the head line's bytes at their offset, the chain head, and the records
+ * the walk produced. On the next read of the same path, a prefix proved
+ * byte-identical is not re-walked; only the appended suffix is verified, chained
+ * onto the cached head.
+ *
+ * **Global invariant 1 ("enforcement paths read only verified records") is what
+ * this touches, so the argument is written out rather than assumed.**
+ *
+ * The tempting design is the cheap one: remember the head line and its offset,
+ * and on a re-read accept the prefix if the head line is byte-identical where it
+ * was. That design is unsound, and the specific attack says why. Append-only
+ * growth is a convention the *writer* honors; it is not a property of the file.
+ * An attacker with write access can mutate a record strictly before the head
+ * without changing its length — swap two characters of a `summary`, flip a digit
+ * of `est_cost_usd` — leaving the file size, the head line, and the head line's
+ * offset all identical. Nothing in the suffix walk touches those bytes. The
+ * forged record would be handed to the gate as verified, and a hash chain would
+ * have been defeated by a cache. "Byte-identical head at the same offset" does
+ * not imply "unchanged prefix", and no amount of `stat` makes it imply that.
+ *
+ * So the cache pays for what it claims: it stores a SHA-256 over the entire
+ * verified prefix and **re-hashes those bytes on every cached read**. A match
+ * proves the prefix on disk is bit-for-bit the prefix this process verified in
+ * full, in this process lifetime. Verification is a pure function of (bytes,
+ * schema files, options) — `core/verify.ts` says so and holds no state — so
+ * identical bytes verify identically, and replaying the walk over them could
+ * only reproduce the records already held. The cache therefore never *admits* a
+ * record: it declines to recompute a conclusion it has already computed from
+ * bytes it has just re-proved. Every record the caller receives was walked
+ * through the full check ladder (parse, `alg`, schema, hash recompute, `seq`
+ * succession, `prev` link) by this process, over exactly these bytes.
+ *
+ * **APRV-217 makes the last sentence conditional, and only under a policy that
+ * says so.** Under the default proof (`full`) the paragraph above is exactly
+ * what happens on every cached read. Under `incremental`, an operator's policy
+ * trades "re-hash the whole prefix on every read" for "hash the appended bytes,
+ * and re-hash the whole prefix on a cadence" — same guards, same walk, same
+ * verdicts, a bounded window in which an in-place rewrite of the prefix would be
+ * served from cache. The argument for that trade, and what it costs, is in the
+ * "incremental prefix proof" section below and in
+ * `docs/proposals/incremental-prefix-proof.md`.
+ *
+ * That is still a large win, because the two costs are not comparable: hashing
+ * bytes is a single linear pass at memory bandwidth, while the walk it replaces
+ * is a JSON parse, an Ajv schema validation, a JCS canonicalization, and a
+ * SHA-256 *per record*. The cache trades a full re-verification for a hash of
+ * the same bytes and a real verification of the new tail.
+ *
+ * Everything else the cache records is a discard trigger and never a licence:
+ *
+ * - **Size** shrinking below the cached prefix discards the entry. A shorter
+ *   file cannot contain the prefix, and a truncated log must be re-read cold so
+ *   that the head reported is the file's head, never the remembered one.
+ * - **mtime** is a staleness hint with no evidentiary weight. It can only cause
+ *   a discard (a same-size file whose mtime moved is suspicious), never skip a
+ *   check. Correctness does not depend on its granularity, on the clock being
+ *   monotonic, or on the filesystem storing it at all: delete the mtime
+ *   comparison and the cache is exactly as sound.
+ * - **The head line's bytes at their recorded offset** are compared before the
+ *   prefix hash. This is a fast rejection of the ordinary tamper, not the proof;
+ *   the prefix hash covers those same bytes and is what the soundness argument
+ *   rests on.
+ * - **The schema directory** is part of the key. Records verified against one
+ *   schema set are not evidence under another.
+ *
+ * Only a `clean` verdict populates the cache. A torn tail or a corrupt log
+ * leaves the previous entry in place unused (it is discarded on the mismatch
+ * that revealed the damage), so nothing derived from a broken read can ever be
+ * resumed from. And the cache is memory-only and process-lifetime: no file, no
+ * shared state between processes, nothing an attacker can pre-seed. A CLI
+ * invocation is a fresh process with an empty cache and behaves exactly as it
+ * did before this existed.
+ *
+ * Records handed out from the cache are deep-frozen, because a caller that
+ * mutated a returned record would otherwise corrupt the next reader's evidence.
+ * Freezing makes the aliasing safe instead of merely unlikely.
+ *
+ * Determinism: `requestState` and everything downstream of it read no clock, no
+ * network, and no cache; `ts` is a parameter everywhere, so a derivation can be
+ * replayed from the log exactly as it was made. The cache sits strictly above
+ * that line, in the read path, and is observationally invisible: for the same
+ * bytes it returns the same records and the same verdict as a cold read, which
+ * `tests/state-cache.test.ts` asserts scenario by scenario.
+ */
+import { type EventRecord, type LogHead } from "./log.js";
+import { type VerifiedLog, type VerifyOptions } from "./verify.js";
+/**
+ * Why a verified read refused. These names are shared verbatim by the gate, the
+ * token module, and the executor, so the CLI maps all three onto the frozen exit
+ * table with one function.
+ */
+export type LogReadRefusalCode = 
+/** The log could not be opened (permissions, a directory, a broken path). */
+"log-unreadable"
+/** The log's final line is unterminated: the signature of a crashed write. */
+ | "log-torn-tail"
+/**
+ * The chain does not verify: a mutated, spliced, reordered, or schema-invalid
+ * record. Distinct from `log-unreadable` because the facts are different — one
+ * is a filesystem problem, the other is evidence of tampering — and the
+ * repairs are different. `approval log verify` owns the detailed vocabulary
+ * (`hash-mismatch`, `seq-gap`, …); this code says only "the log is not
+ * trustworthy, so nothing may be authorized from it".
+ */
+ | "log-corrupt";
+/** A refused read. Structurally a subset of every consumer's refusal shape. */
+export interface LogReadRefusal {
+    ok: false;
+    code: LogReadRefusalCode;
+    message: string;
+}
+/** A successful verified read: the records and the head they end at. */
+export interface VerifiedRecords {
+    ok: true;
+    records: EventRecord[];
+    /**
+     * The chain head — `(seq, hash)` of the last record, or `null` for an empty
+     * log. This is what a caller passes as `appendEvent`'s `expectedHead`, so that
+     * a decision made from these records cannot be appended onto a log that moved
+     * underneath it (APRV-20 finding B1).
+     */
+    head: LogHead | null;
+}
+export type ReadRecordsResult = VerifiedRecords | LogReadRefusal;
+/** Options accepted by {@link readVerifiedRecords}. */
+export interface ReadVerifiedOptions extends VerifyOptions {
+    /**
+     * Verified-read cache to use.
+     *
+     * Defaults to {@link processReadCache}, so a repeat reader (the daemon's watch
+     * loop) is accelerated with no wiring and a one-shot CLI process cannot tell
+     * the difference. Pass an own {@link VerifiedReadCache} to keep a private one,
+     * or `null` to force a cold verification from genesis — which is what an
+     * explicit audit wants, and what the equivalence tests compare against.
+     */
+    cache?: VerifiedReadCache | null;
+    /**
+     * Publish a verified-head snapshot beside the log after a clean read
+     * (APRV-188).
+     *
+     * Off by default, and set by exactly one caller: the daemon, whose warm cache
+     * makes it the process that has already done the walk every hook process
+     * would otherwise repeat. It is set on the READ rather than done afterwards
+     * so the bytes endorsed are the bytes verified — a publisher that re-read the
+     * file to hash it could endorse a digest of bytes nobody walked.
+     */
+    publishSnapshot?: boolean;
+    /**
+     * Which prefix proof a cached read runs (APRV-217).
+     *
+     * Absent means {@link FULL_READ_PROOF}: today's behaviour, byte for byte, for
+     * every caller that does not ask otherwise. It is set by exactly one kind of
+     * caller — a long-lived process (the daemon) that was handed a policy or a
+     * flag naming `incremental`. One-shot processes, the hook included, never set
+     * it, and a `cache: null` read ignores it entirely.
+     */
+    readProof?: ReadProof;
+}
+/**
+ * Set (or clear, with `null`) the default proof for this process's reads.
+ *
+ * Called by exactly one kind of caller: the two long-lived operator verbs, at
+ * startup, after they have resolved the flag against the policy.
+ */
+export declare function useReadProof(proof: ReadProof | null): void;
+/** The default proof in force here. Diagnostics and tests. */
+export declare function readProofInForce(): ReadProof;
+/** Opt this process into (or out of) snapshot-resumed reads. */
+export declare function useVerifiedSnapshots(enabled: boolean): void;
+/** Whether snapshot-resumed reads are enabled here. Diagnostics and tests. */
+export declare function verifiedSnapshotsEnabled(): boolean;
+/** The head of a record list: the last record's `(seq, hash)`, or `null`. */
+export declare function headOf(records: EventRecord[]): LogHead | null;
+/** Which prefix proof a read runs. `full` is today's, byte for byte. */
+export type ReadProofMode = "full" | "incremental";
+/** Reads between full re-proofs under `incremental` (SPEC-signed default). */
+export declare const DEFAULT_FULL_REPROOF_EVERY = 50;
+/** Milliseconds between full re-proofs under `incremental`. */
+export declare const DEFAULT_FULL_REPROOF_AFTER_MS = 60000;
+/** The proof a read runs, with the cadence that bounds `incremental`. */
+export interface ReadProof {
+    mode: ReadProofMode;
+    /** A full re-proof runs at least this often, counted in reads. */
+    everyReads: number;
+    /** …and at least this often in wall-clock milliseconds. */
+    afterMs: number;
+}
+/**
+ * What a reader gets when it asks for nothing: today's proof on every read.
+ *
+ * The default is `full` because it is the behaviour this repository has today
+ * and the one an operator has attested to. `incremental` is reached only by a
+ * caller that was handed a policy (or a flag) saying so.
+ */
+export declare const FULL_READ_PROOF: ReadProof;
+/** Bytes hashed by the verified-read cache so far. Diagnostics and tests. */
+export declare function hashedByteCount(): number;
+/** Reset {@link hashedByteCount}. Tests only. */
+export declare function resetHashedByteCount(): void;
+/**
+ * What one read may do with the published snapshot beside the log (APRV-188).
+ *
+ * Both halves default to off. `consume` is set from the process-wide switch
+ * `useVerifiedSnapshots` (the hook turns it on); `publish` is set per call by
+ * the daemon.
+ */
+export interface SnapshotUse {
+    consume?: boolean;
+    publish?: boolean;
+}
+/**
+ * Process-lifetime, memory-only store of last-verified log state.
+ *
+ * Nothing here is written to disk and nothing is shared between processes. An
+ * instance is safe to construct per caller (the daemon may want its own); the
+ * default is {@link processReadCache}, which is why a repeat reader gets the
+ * acceleration without asking for it and a one-shot CLI process cannot notice
+ * it exists.
+ */
+export declare class VerifiedReadCache {
+    #private;
+    /** Forget everything. Tests use this to force a genuinely cold read. */
+    clear(): void;
+    /** How many logs are remembered. Diagnostics and tests only. */
+    get size(): number;
+    /**
+     * Reads that reused a proved prefix, and reads that verified from genesis.
+     *
+     * Diagnostics, and the one way a test can tell the two paths apart: reusing a
+     * prefix is *designed* to be invisible in the result, so a test that wants to
+     * assert "this tamper discarded the cache" has nothing else to look at.
+     */
+    get stats(): {
+        hits: number;
+        misses: number;
+        resumed: number;
+        fullReproofs: number;
+    };
+    /**
+     * Require a full re-proof of `logPath` on this cache's next read (APRV-217).
+     *
+     * Called by `core/log.ts` after a successful append, through the listener it
+     * registers below. Can only add work: the next read hashes the whole prefix
+     * exactly as a `full` read does.
+     */
+    requireFullReproof(logPath: string): void;
+    /**
+     * Verify `logPath`, reusing a proved-identical prefix when there is one.
+     *
+     * The whole file is read once, and every decision is made from that single
+     * snapshot: nothing is re-`stat`ed and re-read behind its own conclusion.
+     */
+    read(logPath: string, options: VerifyOptions, snapshot?: SnapshotUse, proof?: ReadProof): VerifiedLog;
+}
+/**
+ * The cache {@link readVerifiedRecords} uses when a caller names none.
+ *
+ * Shared per process, which is what makes a watch loop fast without any wiring:
+ * the daemon calls `readVerifiedRecords` exactly as every other consumer does.
+ */
+export declare const processReadCache: VerifiedReadCache;
+/**
+ * Read the log and refuse unless the whole chain verifies.
+ *
+ * An absent log is an empty log (nothing has happened yet), exactly as
+ * `appendEvent` and `approval log verify` treat it.
+ *
+ * The file is opened once as a readability probe *before* verification so that
+ * "I could not open this file" stays an I/O fact (`log-unreadable`) and never
+ * arrives dressed as corruption — the same split the CLI's exit table draws, and
+ * the one thing `verify()` alone cannot express, since from inside the chain
+ * walker an unreadable log is indistinguishable from a broken one.
+ *
+ * Torn-tail behavior is unchanged from the pre-APRV-20 reader: the tear is
+ * reported as `log-torn-tail` and nothing is repaired, because truncating a torn
+ * line is a human decision.
+ *
+ * Reads go through the verified-read cache by default (see the module header):
+ * a prefix re-proved byte-identical is not re-walked, the appended suffix is
+ * verified in full, and any mismatch falls back to genesis. The result is the
+ * result of a cold read on the same bytes, always. `cache: null` opts out.
+ */
+export declare function readVerifiedRecords(logPath: string, options?: ReadVerifiedOptions): ReadRecordsResult;
+/**
+ * One action's approval state, derived from the log.
+ *
+ * These are the gate's names for the approval lifecycle of SPEC.md §6.3. The
+ * envelope's `state:` enum is the projection of the same thing over a whole
+ * task (`proposed`/`awaiting`/`approved`/…); the mapping is one-to-one for the
+ * action-scoped states and is applied by the projection layer, not here.
+ */
+export type RequestState = 
+/** No `approval.requested` for this key. */
+"none"
+/** Requested and undecided — the envelope's `awaiting`. */
+ | "requested"
+/** A human granted it — the envelope's `approved`. */
+ | "granted" | "rejected" | "revoked"
+/** TTL lapsed, by event or by arithmetic. */
+ | "expired"
+/**
+ * The requester took the question back while it was still pending (APRV-106,
+ * amended SPEC.md §6.3).
+ *
+ * Terminal, and terminal in the same sense `rejected` is: the gate refuses a
+ * grant, a rejection, a revocation or a second withdrawal afterwards. It is
+ * NOT a decision — nobody answered — which is why the projection layer reads
+ * it as "back to proposed" rather than as a refusal, and why no authorization
+ * is implied in either direction.
+ */
+ | "withdrawn";
+/** The three terminal decisions a human can record, plus runtime expiry. */
+export type Decision = "grant" | "reject" | "revoke";
+/**
+ * Why a requester retracted a pending request (amended SPEC.md §6.3, APRV-106).
+ *
+ * Closed, and mirrored by `event.schema.json`: a withdrawal that does not say
+ * why is a fact audit cannot use. `timeout` is the one the hook writes — the
+ * requester stopped waiting, so a decision on this request can no longer be
+ * consumed by anyone.
+ */
+export declare const WITHDRAW_REASONS: readonly ["timeout", "cancelled", "superseded"];
+export type WithdrawReason = (typeof WITHDRAW_REASONS)[number];
+/** Is `value` one of the closed withdrawal reasons? */
+export declare function isWithdrawReason(value: unknown): value is WithdrawReason;
+/**
+ * What the request declared, copied out of the `approval.requested` payload.
+ *
+ * ## The scrutiny ratchet (amended SPEC.md §11), stated where it binds
+ *
+ * `summary` and `est_cost_usd` are **claimed** fields: the party under
+ * oversight authored them. So is `route.confidence`, which this derivation
+ * deliberately does not carry at all — nothing in the resolution, sampling, or
+ * refusal paths reads it, and `tests/ratchet.test.ts` scans the source to keep
+ * it that way. Claimed fields MAY raise scrutiny, inform display, or feed
+ * retrospective analysis; they MUST NOT reduce sampling probability, downgrade
+ * a resolved autonomy level, or shortcut any refusal path. `est_cost_usd: 0`
+ * therefore still consumes one action of every action-count budget, and a
+ * confident summary buys nothing. Scrutiny only ratchets upward on self-report.
+ *
+ * `class` and `payload_hash` sit on the other side of that line: `class` is
+ * matched against policy the human attested, and `payload_hash` is *checked*
+ * against the bytes an executor presents (`core/payload.ts`), so a false one
+ * refuses rather than relaxes.
+ */
+export interface DeclaredAction {
+    class: string | null;
+    /**
+     * The declared cost as a canonical decimal USD string (APRV-121), or `null`
+     * when the request declared none. A record written before that change carries
+     * a JSON number and is normalized to the same string here, so every reader
+     * downstream sees one representation regardless of when its record was
+     * written.
+     */
+    est_cost_usd: string | null;
+    reversible: boolean | null;
+    summary: string | null;
+    /**
+     * The content binding of amended SPEC.md §6.2, copied from the registered
+     * declaration onto `approval.requested` so the grant can copy it in turn.
+     * `null` for a request that declared none — which the gate admits only off
+     * the manual path.
+     */
+    payload_hash: string | null;
+    /**
+     * `"harness"` when the requester declared that it will never run this action
+     * through `approval run` (APRV-106, the Claude Code hook): the harness
+     * executes the command itself and the gate's answer is a permission decision,
+     * not a key. A grant on such a request mints no execution token.
+     *
+     * On the ratchet's safe side (SPEC.md §11.1), and deliberately so. It is a
+     * self-reported field, and every effect it has REMOVES capability from the
+     * party that reported it: no token is minted, so `approval run` and
+     * `approval consume` refuse the key outright. There is no reading of a false
+     * `harness` claim that authorizes anything the truthful claim would not.
+     */
+    execution: "harness" | null;
+    /**
+     * The deadline the requester says it will wait until, ISO-8601, or `null`.
+     *
+     * Display only, and claimed: channels render it so an approver can see that
+     * an answer after this instant reaches nobody (APRV-106). Nothing in the
+     * gate, the token module, the budgets or the TTL reads it — the TTL is the
+     * policy's and is the only deadline that governs anything — so a requester
+     * that lies about it can only make its own request look MORE urgent than it
+     * is, never less.
+     */
+    wait_until: string | null;
+    /**
+     * The SHA-256 of the attested policy in force when the runtime evaluated the
+     * request (APRV-118, amended SPEC.md §5.2), or `null` for a record written
+     * before the field existed.
+     *
+     * Computed, never claimed: the requester has no parameter that reaches it, and
+     * the gate assigns it at the write boundary from its own read of the attested
+     * file, exactly as it assigns `ts`. The grant path compares it against the hash
+     * in force at decision time and refuses `policy-drift` on a difference, so a
+     * value that disagrees with the runtime's can only refuse a grant, never
+     * produce one.
+     */
+    policy_sha256: string | null;
+}
+/** Execution facts for the action key: the seq of each event, or `null`. */
+export interface ExecutionFacts {
+    started: number | null;
+    completed: number | null;
+    failed: number | null;
+}
+/** The full derivation, so a caller never re-walks the log to explain itself. */
+export interface RequestDerivation {
+    actionKey: string;
+    state: RequestState;
+    task: string | null;
+    requestSeq: number | null;
+    requestTs: string | null;
+    /**
+     * The actor of the `approval.requested` record that opened the current cycle
+     * (APRV-106). The gate compares a withdrawal's actor against it: only the
+     * party that asked may take the question back.
+     */
+    requestActor: string | null;
+    decision: "granted" | "rejected" | "revoked" | "expired" | "withdrawn" | null;
+    decisionSeq: number | null;
+    decisionTs: string | null;
+    /** An `approval.expired` record exists for the current request. */
+    expiredByEvent: boolean;
+    /** The TTL lapsed by arithmetic, with no `approval.expired` record. */
+    expiredLazily: boolean;
+    declared: DeclaredAction;
+    execution: ExecutionFacts;
+}
+/** A record's payload as a map, or `{}` when it has none. */
+export declare function payloadOf(record: EventRecord): Record<string, unknown>;
+/**
+ * Derive `actionKey`'s approval state from `records`.
+ *
+ * Pure: no I/O, no clock. `ts` is the moment the question is being asked and is
+ * **required** — lazy expiry is arithmetic on it, and a state function that read
+ * the clock could not be replayed.
+ *
+ * Sequencing rules, all of them deliberate:
+ *
+ * - An `approval.requested` **resets** the derivation. A key that was rejected
+ *   or expired may be requested again; the new request starts a fresh cycle and
+ *   the old decision no longer governs. (An action that has *executed* is a
+ *   different matter — `core/gate.ts`'s `request` refuses that on idempotency
+ *   grounds.)
+ * - The **first** decision after a request wins. The gate refuses to append a
+ *   second one, so a log carrying two is a log written by something else; the
+ *   fail-closed reading is that the earliest human decision stands rather than
+ *   that a later append can overwrite it.
+ * - Execution facts accumulate across the whole log for the key, independent of
+ *   the request cycle: an action that has executed has executed, and no
+ *   subsequent request un-executes it.
+ * - Withdrawal (APRV-106): an `approval.withdrawn` settles the request like any
+ *   other terminal event, and is the only one of them that records no decision.
+ *   It participates in the "first settlement wins" rule above, so a withdrawal
+ *   appended after a human's answer does not erase the answer; the gate refuses
+ *   to append one at all in that case.
+ * - Expiry: an `approval.expired` record sets `expiredByEvent`. With no such
+ *   record, `ttlMs !== null` and `ts > requestTs + ttlMs` sets `expiredLazily`.
+ *   Both yield `state: "expired"`. An unparseable `requestTs` or `ts` also
+ *   yields `expired`: liveness that cannot be demonstrated is not assumed. (The
+ *   event schema's `date-time` format makes that unreachable through the real
+ *   append path; it is a backstop, not a live branch.)
+ */
+export declare function requestState(records: EventRecord[], actionKey: string, ts: string, ttlMs: number | null): RequestDerivation;