approval-md 0.1.0 → 0.2.0

package/dist/src/core/verified-snapshot.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The verified-head snapshot (APRV-188): what a process that already walked the
+ * log publishes, so the next process does not have to walk it again.
+ *
+ * ## The cost this removes
+ *
+ * Every hook-gated tool call is a fresh process with an empty
+ * {@link VerifiedReadCache}, so it verifies the log from genesis before it may
+ * decide anything. APRV-186 and APRV-206 made that walk as cheap as a walk can
+ * be; what they could not change is that it is O(records) per gated command.
+ * Measured on this repository's shape at 10k records: 65 ms of the 371 ms a
+ * gated invocation costs, growing at 6.5 ms per thousand records, which is the
+ * term that turns into seconds as a log grows. The daemon, meanwhile, holds a
+ * warm cache and re-verifies only the tail on every tick. This module is how
+ * what it verified reaches the next hook process.
+ *
+ * ## Why a file and not a socket
+ *
+ * The hook's request path is synchronous end to end — `commandHook` returns an
+ * exit code, and the wait loop sleeps synchronously — so a `node:net` client
+ * could not be awaited from it, and a `spawnSync` helper to do the awaiting
+ * would cost more node startup (20-40 ms) than the walk it saves. A published
+ * file needs one `readFileSync`. It also spawns no child and opens no socket,
+ * so there is no environment to scrub (APRV-205) and no fd to leak.
+ *
+ * ## What a snapshot is, and what it is emphatically not
+ *
+ * It is an **endorsement of bytes**. It says: *the first `byte_length` bytes of
+ * this log, whose SHA-256 is this, verified clean, and they end at this head.*
+ * It carries no records, and a reader never learns anything from it that it
+ * cannot check against the log file in its own hands. A reader that cannot
+ * re-prove every one of those claims ignores the file and walks the log, which
+ * is the behaviour with no snapshot at all.
+ *
+ * ## Global invariant 1, "enforcement paths read only verified records"
+ *
+ * This is the invariant the module touches, so the argument is written out
+ * rather than assumed. The structure is APRV-43's, with the verifier in another
+ * process:
+ *
+ *  - {@link admitSnapshot} hashes the prefix bytes **it read itself** and
+ *    requires the digest the snapshot names. That is what makes "the bytes the
+ *    publisher verified" and "the bytes on disk now" the same bytes; it is the
+ *    identical proof the in-process cache pays on every cached read, and no
+ *    amount of `stat` substitutes for it.
+ *  - The reader parses the prefix lines itself and re-derives the head and the
+ *    line count from its own parse. A snapshot naming a different head, or a
+ *    different number of lines, is rejected by the reader's own arithmetic.
+ *  - The reader then re-checks the chain links (`alg`, `seq` succession, `prev`
+ *    linkage, hash shape) over those parsed records. This is a deliberate
+ *    SUBSET of `core/verify.ts`'s ladder and never a replacement for it: it can
+ *    only reject. `core/verify.ts` remains the one implementation of the
+ *    verdict, and the appended tail beyond the prefix is walked by it in full.
+ *  - What is therefore taken on the publisher's word is exactly two checks over
+ *    bytes already proved identical: the `event` schema validation and the
+ *    per-record hash recompute.
+ *
+ * **Why that residue is not a new capability.** A snapshot can only endorse
+ * bytes that are already in the log file. To exploit the residue an attacker
+ * must write `verified-head.json`, which sits in the same directory as
+ * `events.jsonl` under the same permissions — and the chain is unkeyed, so an
+ * attacker who can write that directory can simply recompute a self-consistent
+ * forged log, which passes a *cold* walk too. The snapshot grants nothing that
+ * write access to the log directory did not already grant. The ownership and
+ * permission checks in {@link readSnapshot} are what keep that sentence true
+ * under a loose umask: a snapshot any other user could have written is refused
+ * before it is read.
+ *
+ * Fail closed throughout. Every check here can only reject, every rejection
+ * falls back to the cold walk, and nothing in this module can turn a log that
+ * does not verify into a verdict — the reader either proves the prefix or walks
+ * it.
+ */
+import type { LogHead } from "./log.js";
+import type { VerifiedPrefix } from "./verify.js";
+/** The snapshot format version. A reader admits exactly this one. */
+export declare const SNAPSHOT_VERSION = 1;
+/**
+ * The published snapshot, as it sits on disk.
+ *
+ * Field names are snake_case to match every other file this project writes.
+ * There is no JSON Schema for it, deliberately: schemas in `schema/` describe
+ * the log's records, which are evidence, and this file is not evidence. It is
+ * validated field by field by {@link parseSnapshot}, strictly, in one place.
+ */
+export interface VerifiedSnapshot {
+    v: number;
+    /** Resolved path of the log these bytes belong to. */
+    log: string;
+    /** Resolved schema directory the publisher verified against ("" = default). */
+    schema_dir: string;
+    /** Length of the endorsed prefix in bytes. Always ends just after a newline. */
+    byte_length: number;
+    /** SHA-256 (hex) over exactly those bytes. The proof a reader re-computes. */
+    sha256: string;
+    /** Complete lines in the prefix, so a resumed walk numbers lines absolutely. */
+    lines: number;
+    /** The prefix's chain head. A reader re-derives it and must agree. */
+    head: LogHead;
+    /** When it was published. Diagnostics only; no check depends on it. */
+    verified_at: string;
+    /** Publisher pid. Diagnostics only; no check depends on it. */
+    pid: number;
+}
+/**
+ * Where the snapshot for `logPath` lives: beside the log, named for what it is.
+ *
+ * Derived, never configured. One log has one snapshot, and a reader that had to
+ * be *told* where to look could be pointed at a snapshot for another log — a
+ * mistake the `log` field would catch and that this removes entirely.
+ */
+export declare function snapshotPathFor(logPath: string): string;
+/** Forget what this process published. For tests, and for {@link clearSnapshot}. */
+export declare function forgetPublishedSnapshots(logPath?: string): void;
+/**
+ * Publish a snapshot for a log the caller has just verified clean.
+ *
+ * `raw` must be the exact bytes the caller verified, `sha256` their digest,
+ * `head` the head that walk produced and `lines` its record count: this function
+ * checks none of that and cannot — it is the caller's own verification being
+ * published. Every caller is therefore immediately after a `clean` verdict over
+ * these bytes. The digest is a parameter rather than a recomputation because the
+ * caller has just proved it (APRV-206's argument, and APRV-211's measurement:
+ * hashing megabytes twice per read was 45% of a tick).
+ *
+ * The write is atomic (a temp file in the same directory, then `rename`) so a
+ * reader never sees half a snapshot, and mode 0600 so the ownership argument in
+ * the module header holds. Any failure is swallowed: a snapshot is an
+ * optimization, and a daemon must not die because a cache file could not be
+ * written. The return value says whether it landed, for the tests and the
+ * doctor row; `false` also covers "these exact bytes are already published",
+ * which is a write skipped rather than a write that failed.
+ */
+export declare function publishSnapshot(logPath: string, raw: Uint8Array, digest: string, lines: number, head: LogHead, schemaDir: string | undefined, now?: () => string): boolean;
+/**
+ * {@link publishSnapshot} for a caller that never held the whole file.
+ *
+ * The incremental read (APRV-217) reads the head line and the appended bytes
+ * and proves the digest from a carried hash state, so it has the two facts this
+ * function needs — how long the verified prefix is and whether it ends at a
+ * line boundary — without a buffer of the log to derive them from. Nothing else
+ * differs: the same suppression memo, the same atomic 0600 write, the same
+ * snapshot fields. `publishSnapshot` is this function with those two facts read
+ * off a buffer.
+ */
+export declare function publishVerifiedPrefix(logPath: string, byteLength: number, endsWithNewline: boolean, digest: string, lines: number, head: LogHead, schemaDir: string | undefined, now?: () => string): boolean;
+/**
+ * Why a snapshot was not used. Every value means the same thing operationally —
+ * walk the log — and exists so the doctor row and the tests can say which check
+ * rejected it.
+ */
+export type SnapshotRefusal = "absent" | "unreadable" | "not-a-file" | "foreign-owner" | "loose-permissions" | "malformed" | "version" | "other-log" | "other-schema-dir" | "shorter-file" | "not-line-aligned" | "digest-mismatch" | "line-count-mismatch" | "head-mismatch" | "chain-broken";
+export interface SnapshotRejected {
+    ok: false;
+    reason: SnapshotRefusal;
+    detail: string;
+}
+export type SnapshotRead = {
+    ok: true;
+    snapshot: VerifiedSnapshot;
+} | SnapshotRejected;
+/**
+ * Read the snapshot for `logPath`, refusing one this user did not write.
+ *
+ * The ownership and permission checks are taken from the open file descriptor
+ * rather than from the path, so what is checked and what is read are the same
+ * inode: a snapshot swapped between the `stat` and the read cannot be admitted
+ * on the strength of the file that used to be there.
+ */
+export declare function readSnapshot(logPath: string): SnapshotRead;
+export type SnapshotAdmission = {
+    ok: true;
+    prefix: VerifiedPrefix;
+    /**
+     * SHA-256 of the endorsed prefix, as this call re-proved it. Handed back
+     * so a caller that caches the prefix does not hash the same bytes twice.
+     */
+    digest: string;
+} | SnapshotRejected;
+/**
+ * Decide whether `snapshot` may stand for the first bytes of `raw`, and return
+ * the {@link VerifiedPrefix} a resumed walk chains onto when it may.
+ *
+ * `raw` is the caller's own read of the whole log. Every check below is made
+ * against those bytes; nothing is re-`stat`ed, re-read, or taken from the
+ * snapshot without being re-derived. The order is cheapest-first, but only the
+ * digest is load-bearing — everything before it rejects an obviously
+ * inapplicable snapshot without hashing megabytes, and everything after it
+ * re-derives from the reader's own parse what the snapshot merely claimed.
+ */
+export declare function admitSnapshot(logPath: string, raw: Uint8Array, snapshot: VerifiedSnapshot, schemaDir: string | undefined): SnapshotAdmission;
+/**
+ * {@link readSnapshot} then {@link admitSnapshot}: the whole path a reader takes.
+ *
+ * Returns the prefix to resume behind, or the reason there is none. Every reason
+ * means "walk the log", which is what the caller does with no snapshot at all.
+ */
+export declare function snapshotPrefix(logPath: string, raw: Uint8Array, schemaDir: string | undefined): SnapshotAdmission;
+/** Read the snapshot's own text, for the doctor row. Never throws. */
+export declare function snapshotSummary(logPath: string): SnapshotRead;
+/** Remove a snapshot. Used by tests and by anything that invalidates one. */
+export declare function clearSnapshot(logPath: string): void;
+/** Read the log's bytes, for callers that want the same view a reader admits. */
+export declare function logBytes(logPath: string): Uint8Array | null;

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

@@ -0,0 +1,336 @@
+/**
+ * Hash-chain verification for `.approval/log/events.jsonl` (SPEC.md §8:
+ * "`approval log verify` MUST detect any mutation or truncation").
+ *
+ * This module is the read side of the append-only log. It re-derives every
+ * record's digest from its canonical serialization and walks the `prev` chain
+ * and the `seq` succession end to end, reporting the *first* place the log
+ * stops being self-consistent.
+ *
+ * **Read-only, by definition.** Verification opens the log for reading and
+ * nothing else: it never truncates, never rewrites, never repairs, and never
+ * creates a lockfile. A torn tail is *reported*, never auto-truncated — a log
+ * that heals itself is a log that can be made to forget. Repair is a human
+ * decision, made explicitly: a later CLI task may offer it behind an explicit
+ * flag, but the core provides detection only.
+ *
+ * **What verification detects.** Any mutation of a record without a full
+ * recompute of every descendant; truncation of the tail (with an external
+ * anchor); deletion, insertion, reorder, or splice anywhere in the chain;
+ * `alg` tampering; a malformed or schema-invalid line; a duplicated or skipped
+ * `seq`; a non-genesis first record; and — given an anchor — a fully
+ * recomputed forged suffix.
+ *
+ * **The detection boundary — state it plainly.** A hash chain is
+ * tamper-*evident*, not tamper-*proof*. A forger who rewrites record N and then
+ * recomputes every descendant (new hash, fixed `prev`) produces a file that is
+ * internally self-consistent in every respect, and `verify(logPath)` on that
+ * file alone CANNOT distinguish it from an honest log. The same is true of
+ * dropping records off the tail: the surviving prefix is a valid chain. Closing
+ * that gap requires something the forger does not control:
+ *
+ * - an externally anchored head — pass {@link VerifyOptions.expectedHead} with
+ *   a `(seq, hash)` pair recorded elsewhere (a channel message, another host, a
+ *   human's notes); a mismatch is reported as `head-mismatch`;
+ * - a retained copy of the log held outside the writer's reach;
+ * - the optional per-event git commits of SPEC.md §8, where the daemon commits
+ *   each record under its own identity, giving signed, distributed evidence.
+ *
+ * Three questions that keep arriving separately have one answer (APRV-141, F7):
+ * the digest covers each record's CANONICAL CONTENT, its RFC 8785
+ * serialization, and never the bytes of the line it was read from, so a
+ * re-serialization that changes only byte format verifies clean, a line
+ * carrying a duplicate key is settled by the JSON parse that precedes
+ * canonicalization rather than by the chain, and an unanchored tail truncation
+ * leaves a valid prefix that nothing inside the file can contradict.
+ *
+ * **Anomalies, which are reported and never enforced (APRV-40).** SPEC.md §8
+ * requires that "verification treats gate-type events with implausible skew
+ * relative to their neighbors as a reportable anomaly, never silently accepted".
+ * Every non-corrupt result therefore carries {@link VerifyResult.anomalies}, a
+ * list that says nothing about integrity: a clean log with anomalies is clean,
+ * exits 0, and authorizes exactly what it authorized before. The separation is
+ * the point. Chain integrity is a proof, skew is a judgment, and folding a
+ * judgment into a proof would turn `log verify` into a check people learn to
+ * pass a flag to silence. See {@link chainAnomalies}.
+ *
+ * Determinism: the result is a pure function of (log bytes, schema files,
+ * options). No clock, no network, no cross-call state — the anomaly pass reads
+ * the records' own timestamps and never the current time.
+ */
+import { type EventRecord, type LogHead } from "./log.js";
+import { type ValidateOptions } from "./validate.js";
+/**
+ * A chain head: the last record's position and digest.
+ *
+ * Defined in `core/log.ts` (the writer needs it for its compare-and-append
+ * precondition and cannot import this module) and re-exported here, where
+ * readers expect to find it. One definition, one meaning.
+ */
+export type { LogHead };
+/**
+ * The skew allowance, in milliseconds, before a backwards step between two
+ * gate-typed records is reported.
+ *
+ * ### Why 2 seconds, and why any number at all
+ *
+ * Gate-typed timestamps are stamped by `core/clock.ts` at the write boundary. In
+ * one process they come from one `Date.now()` and never go backwards. Across
+ * processes and hosts — the daemon on one machine, a CLI verb on another, both
+ * appending to a shared log — they come from separate wall clocks, and two
+ * healthy NTP-disciplined clocks routinely disagree by tens of milliseconds and
+ * occasionally by a few hundred during a step correction. A tolerance of zero
+ * would therefore report ordinary distributed operation as an anomaly, which is
+ * the fastest way to make an anomaly channel ignored.
+ *
+ * 2000 ms is chosen as roughly an order of magnitude above the disagreement a
+ * synchronized fleet actually exhibits, and two to three orders of magnitude
+ * below the skew that a *useful* lie requires. The thing this check exists to
+ * catch is a timestamp placed to change a judgment: a `ts` inside a lapsed TTL
+ * (minutes to hours), or one moved outside a rolling budget window (hours). No
+ * attack is bought by 1.9 seconds, and no healthy fleet needs 2.1.
+ *
+ * It is the DEFAULT rather than the only value since APRV-58: an operator
+ * running a single host may tighten it to 250 ms, one running across a WAN with
+ * poor time discipline may loosen it to 5 s, and `audit.skew_tolerance` in the
+ * policy is where they say so. A policy that declares nothing (or that fails to
+ * load at all) leaves this number in force, so the reference runtime still has
+ * exactly one value that every reader can see.
+ *
+ * Widening the tolerance permits nothing: the threshold is report-only in both
+ * directions, so a loosened value hides evidence from a human and cannot make
+ * any action allowed that was refused before.
+ */
+export declare const GATE_TS_SKEW_TOLERANCE_MS = 2000;
+/**
+ * `audit.skew_tolerance` in milliseconds, or the default when it says nothing.
+ *
+ * Fails closed to the default exactly as `daemon/prune.ts`'s retention read
+ * does: a policy that cannot be loaded configures nothing, and for THIS key the
+ * safe fallback is the shipped number rather than zero — a zero allowance would
+ * report every ordinary clock disagreement as an anomaly, and an anomaly channel
+ * that cries wolf is one operators stop reading. An unparseable duration never
+ * reaches here: the schema's duration pattern rejects it and `loadPolicy` fails
+ * the whole policy, precisely as a bad `defaults.approval_ttl` does.
+ */
+export declare function skewToleranceMsOf(policy: {
+    dir?: string;
+    file?: string;
+}, schemaDir?: string): number;
+/**
+ * Machine-readable anomaly kinds. Closed union, additive-only, each pinned by a
+ * test — the same contract every other frozen union in this codebase carries.
+ */
+export declare const CHAIN_ANOMALY_KINDS: readonly [
+/**
+ * A gate-typed record's `ts` is earlier than the previous gate-typed record's
+ * `ts` by more than {@link GATE_TS_SKEW_TOLERANCE_MS}.
+ *
+ * One kind covers both directions SPEC.md §8 describes. "Earlier than its
+ * predecessor" and "later than its successor" are the same disagreement seen
+ * from the two ends of one adjacent pair, and reporting it twice would double
+ * every entry without adding a fact.
+ */
+"gate-ts-regression"];
+export type ChainAnomalyKind = (typeof CHAIN_ANOMALY_KINDS)[number];
+/** One reportable oddity in a log that verifies. Never a verdict. */
+export interface ChainAnomaly {
+    kind: ChainAnomalyKind;
+    /** The record the anomaly is reported against. */
+    seq: number;
+    ts: string;
+    event: string;
+    /** The gate-typed record it was compared with. */
+    previousSeq: number;
+    previousTs: string;
+    /** How far back the step is, in milliseconds. Always positive. */
+    skewMs: number;
+    message: string;
+}
+/**
+ * Timestamp anomalies among the gate-typed records of a verified chain.
+ *
+ * Pure: a function of the records alone, with no clock and no I/O. Comparison is
+ * between each gate-typed record and the previous **gate-typed** record, not the
+ * previous record of any kind, for the reason {@link isGateTyped} states.
+ *
+ * This changes no verdict. A log full of anomalies is still `clean` if its chain
+ * verifies, still exits 0, and still authorizes exactly what it authorized
+ * before. Skew is evidence for a human to weigh, and a verifier that refused on
+ * it would be refusing on a heuristic — which is how a tamper-evidence tool
+ * starts being run with a flag that turns it off.
+ */
+export declare function chainAnomalies(records: readonly EventRecord[], toleranceMs?: number): ChainAnomaly[];
+/** Machine-readable reason a log failed verification. Closed set. */
+export type VerifyFailureReason = "malformed-line" | "schema-invalid" | "bad-alg" | "hash-mismatch" | "prev-mismatch" | "seq-gap" | "seq-duplicate" | "not-genesis" | "head-mismatch";
+/**
+ * Outcome of a verification run. A discriminated union on `status`:
+ *
+ * - `clean` — every complete line verified; `head` is `null` for an empty or
+ *   absent log.
+ * - `torn-tail` — the file's final line is torn (it is not newline-terminated,
+ *   i.e. a writer died mid-line) while every complete line before it verifies.
+ *   This is the crashed-write signature and is deliberately distinct from
+ *   corruption: it is an incomplete write, not evidence of tampering.
+ * - `corrupt` — everything else, reported at the first offending record.
+ */
+export type VerifyResult = {
+    status: "clean";
+    records: number;
+    head: LogHead | null;
+    anomalies: ChainAnomaly[];
+} | {
+    status: "torn-tail";
+    records: number;
+    intactThroughSeq: number;
+    message: string;
+    anomalies: ChainAnomaly[];
+} | {
+    status: "corrupt";
+    firstBadSeq: number | null;
+    reason: VerifyFailureReason;
+    message: string;
+    anomalies: ChainAnomaly[];
+};
+/** Options accepted by {@link verify}. */
+export interface VerifyOptions extends ValidateOptions {
+    /**
+     * Externally anchored head. When supplied, a log that verifies internally is
+     * additionally required to end at exactly this `(seq, hash)`. This is the
+     * only defence against tail truncation and against a fully recomputed forged
+     * suffix; see the detection boundary in the module header.
+     */
+    expectedHead?: LogHead;
+    /**
+     * Where the policy carrying `audit.skew_tolerance` lives (APRV-58), with
+     * `loadPolicy`'s semantics. Supplied by a caller that has a policy to hand;
+     * absent means {@link GATE_TS_SKEW_TOLERANCE_MS}.
+     *
+     * It reaches exactly one thing, the anomaly threshold, and anomalies change no
+     * verdict. Verification's answer to "does this chain hold" is a function of
+     * the log bytes and the schemas, and no policy — loadable, absent, hostile, or
+     * edited — can move it.
+     */
+    policy?: {
+        dir?: string;
+        file?: string;
+    };
+    /**
+     * The tolerance, already resolved, in milliseconds. Overrides
+     * {@link VerifyOptions.policy} when both are given, and exists so the pure
+     * paths and the tests can state a threshold without a file on disk.
+     */
+    skewToleranceMs?: number;
+    /**
+     * Called as the walk advances, so a caller can say what is taking so long
+     * (APRV-167).
+     *
+     * `approval policy amend` sat silent for thirty-three seconds re-verifying a
+     * three-thousand-record chain before it printed its first line, read as
+     * frozen, and was once abandoned mid-ceremony — which left the repository's
+     * gate fail-closed for every agent session until somebody tried again. The
+     * work was never the problem; the silence was.
+     *
+     * It OBSERVES and never decides. Nothing in the walk consults it, no verdict,
+     * message, line number or record depends on whether it was supplied, and a
+     * listener that throws would fail the verification of a sound log — so
+     * callers must not throw from it. Counts are absolute over the whole log
+     * (a resumed read behind a {@link VerifiedPrefix} reports the same numbers a
+     * cold one does) and strictly increasing within one run. The final call
+     * reports `done === total` when the chain held, and the length of the
+     * verified prefix when it did not — a meter must not claim work that was
+     * refused.
+     */
+    onProgress?: VerifyProgressListener;
+}
+/** How far along a verification walk is. Counts are records, not bytes. */
+export interface VerifyProgress {
+    /** Records verified so far. Monotonically increasing within one run. */
+    done: number;
+    /** Records this run will cover in total, known before the walk starts. */
+    total: number;
+}
+export type VerifyProgressListener = (progress: VerifyProgress) => void;
+/**
+ * How many records pass between progress calls.
+ *
+ * Count-based rather than time-based, and reported here rather than throttled
+ * here: this module has no clock, a listener that fires on a deterministic
+ * schedule is a listener a test can assert on exactly, and the decision about
+ * how often a HUMAN should see a repaint belongs to the thing holding the
+ * terminal (`cli/progress.ts`), which is the only layer that knows whether
+ * there is one.
+ */
+export declare const PROGRESS_INTERVAL = 250;
+/**
+ * A verification run plus the records it verified.
+ *
+ * `records` holds every record the walk accepted, in log order: the whole log
+ * when `result.status` is `clean`, the intact prefix when it is `torn-tail`, and
+ * the prefix before the first failure when it is `corrupt` (where it carries no
+ * authority and callers must ignore it).
+ */
+export interface VerifiedLog {
+    result: VerifyResult;
+    records: EventRecord[];
+}
+/**
+ * {@link verify}, returning the verified records alongside the verdict.
+ *
+ * This exists so that a reader which needs *both* — the gate, the token module,
+ * the executor, via `core/state.ts` — can have one walk produce both, rather
+ * than verifying with this module and then parsing the same bytes a second time
+ * with a private walk that could disagree with it (APRV-20 finding S1).
+ */
+export declare function verifyWithRecords(logPath: string, options?: VerifyOptions): VerifiedLog;
+/**
+ * A prefix of a log that *this process* has already verified in full, together
+ * with the evidence needed to resume behind it.
+ *
+ * Handing one of these to {@link verifyText} skips re-verification of the prefix
+ * entirely, which is sound only under the caller's obligation stated on
+ * {@link records}: the bytes now on disk in `[0, byteLength)` must be proved
+ * byte-identical to the bytes that produced these records. `core/state.ts` is
+ * the only caller, and it discharges that obligation by re-hashing the prefix
+ * bytes on every use. Verification is a pure function of (bytes, schemas,
+ * options), so identical bytes re-verify identically by construction; nothing
+ * weaker (a matching size, a matching mtime, a matching head line) implies it.
+ */
+export interface VerifiedPrefix {
+    /** Byte length of the prefix. Always immediately after a newline. */
+    byteLength: number;
+    /** Number of complete lines in the prefix, for file-absolute line numbers. */
+    lines: number;
+    /** The prefix's chain head, which the resumed walk chains onto. */
+    head: LogHead;
+    /** The records the prefix verified to, in log order. */
+    records: readonly EventRecord[];
+}
+/**
+ * {@link verifyWithRecords} over text already in hand, optionally resuming
+ * behind a {@link VerifiedPrefix}.
+ *
+ * With `prefix === null`, `text` is the whole log and the walk starts at
+ * genesis: this is exactly what {@link verifyWithRecords} does, and the two
+ * share every check, message, and line number as a result. With a `prefix`,
+ * `text` is the *remainder* of the file (the bytes from `prefix.byteLength` on)
+ * and the walk chains onto `prefix.head` with line numbers offset by
+ * `prefix.lines`, so a resumed verdict is textually identical to the cold one.
+ *
+ * Exported for `core/state.ts`'s verified-read cache and for nothing else. Every
+ * schema check, hash recompute, `seq` succession check, and `prev` link check
+ * still runs on every record the walk covers; resuming changes only *which*
+ * records are covered, never how.
+ */
+export declare function verifyText(logPath: string, text: string, options?: VerifyOptions, prefix?: VerifiedPrefix | null): VerifiedLog;
+/**
+ * Verify the hash chain of the log at `logPath`.
+ *
+ * An absent file is an empty log, which is clean with zero records and a `null`
+ * head — an audit trail that has recorded nothing is not evidence of tampering.
+ *
+ * The file is opened for reading only; see the module header for the recovery
+ * stance and the detection boundary. This is {@link verifyWithRecords} with the
+ * records dropped — one walk, one implementation.
+ */
+export declare function verify(logPath: string, options?: VerifyOptions): VerifyResult;

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

@@ -0,0 +1,8 @@
+/**
+ * Version constants for the approval.md runtime.
+ *
+ * `SPEC_VERSION` tracks the version of SPEC.md this build implements.
+ */
+export declare const SPEC_VERSION = "0.1.0-draft";
+/** Policy schema version accepted in `APPROVAL.md` frontmatter (`version:`). */
+export declare const POLICY_VERSION = "0.1";