approval-md 0.1.0 → 0.3.0

package/dist/src/core/live-draw.d.ts

@@ -0,0 +1,436 @@
+/**
+ * The daemon-answered live draw (APRV-208).
+ *
+ * ## The hole this closes
+ *
+ * `supervised-live` (APRV-127) puts a declared fraction of a class through the
+ * human gate, chosen by HMAC over the payload hash under an operator-held
+ * secret. `core/sampler.ts`'s {@link import("./sampler.js").resolveLiveSelector}
+ * reads that secret out of the DECIDING PROCESS's own environment, and the
+ * deciding process is usually the harness hook — a short-lived child of an
+ * agent session. Nothing sources the secret there, and nothing may: a secret an
+ * agent-launched process can read is a secret the agent can read, and an agent
+ * that can compute its own luck can grind its payload until the draw comes up
+ * unsampled. SPEC.md §5.2 forbids exactly that.
+ *
+ * So the draw failed closed, correctly and permanently: measured on this
+ * repository's own log, 15 of 15 supervised-live actions since the seq 5147
+ * ceremony gated to a human (APRV-184). A class an operator asked to sample at
+ * 10% was gated at 100%, which is safe and is also the setting never once
+ * having been live.
+ *
+ * The fix is not to hand the hook the secret. It is to move the DRAW to the one
+ * process that legitimately holds it — the daemon, started by the operator in a
+ * terminal where `eval "$(approval env)"` has run — and let the hook ASK.
+ *
+ * ## The protocol, and what each part is for
+ *
+ * One owner-only Unix socket under the approval home
+ * (`.approval/daemon/draw.sock`, directory 0700, socket 0600). One JSON line in,
+ * one JSON line out, connection closed.
+ *
+ * ```
+ * ->  {"v":1,"action_key":"...","payload_hash":"<64hex>","policy_hash":"<64hex>","live_rate":0.1}
+ * <-  {"v":1,"question":{...},"selected":true,"mac":"<64hex>","daemon_pid":123,"answered_at":"..."}
+ * ```
+ *
+ * - **The question is a PROPOSAL; the echoed question is the daemon's own
+ *   derivation.** The daemon does not take `live_rate` or `policy_hash` on the
+ *   asker's word — it resolves the class from its own policy and echoes what it
+ *   derived. The asker requires the echo to equal what it asked. A daemon and a
+ *   hook reading different policies therefore fail closed instead of agreeing on
+ *   the wrong rate, and no answer is ever MAC'd over a rate the daemon did not
+ *   itself compute.
+ * - **The MAC binds the whole question AND the verdict.** `HMAC-SHA-256(secret,
+ *   domain || canonical question || "\n" || selected)`. An answer is worth
+ *   nothing without it: the asker cannot check it (it holds no secret), so it
+ *   records it, and an operator who holds the secret recomputes it later from
+ *   the record's own `action_key`, `payload_hash` and `policy_sha256`. That is
+ *   what keeps SPEC.md §11's "self-reported fields never reduce scrutiny" true
+ *   here — the answer is not believed, it is EVIDENCED, and an answer that
+ *   cannot be evidenced (absent daemon, dead daemon, malformed reply) is refused
+ *   and the action gates.
+ * - **A domain separator.** The MAC message is prefixed with
+ *   {@link DRAW_MAC_DOMAIN} so a MAC can never be confused with, or substituted
+ *   for, the selection value `core/sampler.ts` derives from the same key over a
+ *   bare payload hash.
+ *
+ * ## Why the socket is not a free oracle
+ *
+ * An owner-only socket is reachable by any process of the same user, and an
+ * agent session runs as that user. If the daemon answered any question put to
+ * it, the agent could ask "would these bytes be sampled?" for a thousand
+ * candidate payloads and pick one that is not — the very grinding attack the
+ * secret exists to prevent, restored through the front door.
+ *
+ * `daemon/draw.ts` closes it by refusing to answer for an action that is not
+ * ALREADY REGISTERED in the verified log with exactly this payload hash. To ask
+ * a question you must first append a `task.registered` naming the bytes, so
+ * every candidate an agent grinds is permanently in the append-only log, in
+ * order, countable by anyone. The oracle still exists; it just cannot be
+ * consulted in secret, which is the property this project trades in.
+ *
+ * ## The secret is never here
+ *
+ * This module takes a secret as a parameter in exactly two pure functions
+ * ({@link drawMac}, {@link verifyDrawAnswer}) and stores it nowhere. Nothing in
+ * the client half ever sees one: the asking process holds no secret, which is
+ * the entire point.
+ */
+/** The protocol version. A mismatch is a refusal, never a negotiation. */
+export declare const DRAW_PROTOCOL_VERSION = 1;
+/** The socket's basename under the approval home's `daemon/` directory. */
+export declare const DRAW_SOCKET_NAME = "draw.sock";
+/** The MAC's domain separator. See the module header. */
+export declare const DRAW_MAC_DOMAIN = "approval.md/live-draw/v1";
+/**
+ * The longest socket path this runtime will bind or dial.
+ *
+ * `sockaddr_un.sun_path` is 104 bytes on macOS and 108 on Linux, and a `bind`
+ * past it fails with a message an operator cannot act on. Checked on both sides
+ * so the daemon reports it as a refusal to serve and the asker reports it as an
+ * absent daemon, rather than either of them producing an `ENAMETOOLONG` nobody
+ * expected.
+ */
+export declare const DRAW_SOCKET_PATH_LIMIT = 100;
+/** How long the asking child waits for a connection and an answer. */
+export declare const DRAW_TIMEOUT_MS = 500;
+/** The whole child invocation, including Node's own start. */
+export declare const DRAW_SPAWN_TIMEOUT_MS = 5000;
+/**
+ * The approval home's `daemon/` directory for a log, derived and never
+ * configured.
+ *
+ * `logPath` is `<home>/log/events.jsonl`, so the home is two levels up. One log
+ * has one daemon directory: a reader that had to be TOLD where to look could be
+ * pointed at another instance's daemon, and answers would cross between
+ * instances that share a machine.
+ */
+export declare function drawDirFor(logPath: string): string;
+/** Where the draw socket for `logPath` lives. */
+export declare function drawSocketPathFor(logPath: string): string;
+/**
+ * Which class patterns this policy declares `supervised-live`, sorted.
+ *
+ * The one question that decides whether any of this machinery is the operator's
+ * business at all: with no live class, no draw is ever made, so a missing
+ * socket is not a fault, an unset secret is not a misconfiguration, and neither
+ * deserves a doctor row or a line on the daemon's stderr. Shared by the doctor
+ * row and the daemon's server so the two cannot come to different conclusions
+ * about the same file.
+ *
+ * `defaults.autonomy` is not consulted, and cannot be: `supervised-live` carries
+ * a required rate that `defaults` has no field to hold, which `policy.schema.json`
+ * enforces. Only a class rule can be live.
+ */
+export declare function liveClassesOf(policy: {
+    classes?: Record<string, {
+        autonomy?: string;
+    } | undefined>;
+}): string[];
+/**
+ * What is asked, and what a MAC is computed over.
+ *
+ * Deliberately without a timestamp. A caller-supplied clock inside MAC'd
+ * material would let the same question be asked again for a different MAC, and
+ * SPEC.md §11's rule that gate-typed events take no caller timestamp is the
+ * same rule wearing a different hat. The answer carries the daemon's own
+ * `answered_at` outside the MAC, for an operator reading a live socket, and it
+ * is not recorded in the log.
+ */
+export interface DrawQuestion {
+    v: number;
+    action_key: string;
+    payload_hash: string;
+    /** The `policy_sha256` the asker is routing under, echoed by the daemon. */
+    policy_hash: string;
+    /** The class's `live_rate`, echoed by the daemon from its OWN resolution. */
+    live_rate: number;
+}
+/** What the daemon answers. */
+export interface DrawAnswer {
+    v: number;
+    /** The daemon's own derivation of the question. Compared field for field. */
+    question: DrawQuestion;
+    selected: boolean;
+    /** {@link drawMac} over `question` and `selected`. 64 lowercase hex. */
+    mac: string;
+    daemon_pid: number;
+    answered_at: string;
+}
+/** Is this a well-formed 64-character lowercase hex digest? */
+export declare function isHex64(value: unknown): value is string;
+/**
+ * The canonical bytes a MAC covers: RFC 8785 over the question.
+ *
+ * `core/jcs.ts` is the runtime's one canonicalizer, so the asker, the daemon and
+ * a later verifier cannot drift apart over key order or number spelling.
+ */
+export declare function canonicalQuestion(question: DrawQuestion): string;
+/** `HMAC-SHA-256(secret, domain || question || verdict)`, lowercase hex. */
+export declare function drawMac(secret: string, question: DrawQuestion, selected: boolean): string;
+/**
+ * Does this MAC belong to this question and this verdict, under this secret?
+ *
+ * Constant-time, which costs nothing and removes the argument about whether it
+ * matters. A malformed MAC is `false` rather than a throw: this is a verifier,
+ * and every wrong answer is one answer.
+ */
+export declare function verifyDrawAnswer(secret: string, question: DrawQuestion, selected: boolean, mac: string): boolean;
+/**
+ * Why a delegated draw produced no usable answer. Machine-readable, closed and
+ * DISTINCT (SPEC.md §11 invariant 6), because the operator's action differs:
+ * "start the daemon", "your daemon is wedged or was killed", "something
+ * answered and it was not a daemon holding your secret".
+ *
+ * Every one of them gates the action, exactly as an unavailable secret does
+ * today. None of them is a degraded mode.
+ */
+export declare const DRAW_REFUSAL_REASONS: readonly [
+/** No socket at the derived path: no daemon has ever served draws here. */
+"draw-daemon-absent", 
+/** A socket that cannot be dialled, times out, or names a pid that is gone. */
+"draw-daemon-stale", 
+/** An answer that is malformed, off-version, off-question, or badly MAC'd. */
+"draw-answer-invalid"];
+export type DrawRefusalReason = (typeof DRAW_REFUSAL_REASONS)[number];
+/** What the asker got back. */
+export type DrawOutcome = {
+    ok: true;
+    answer: DrawAnswer;
+} | {
+    ok: false;
+    reason: DrawRefusalReason;
+    detail: string;
+};
+/**
+ * The `live_draw` field an `approval.requested` carries when the draw was
+ * DELEGATED (APRV-208).
+ *
+ * ## Why this is recorded at all, when APRV-127 records nothing
+ *
+ * APRV-127 deliberately wrote nothing about the selection to the log, and that
+ * property is unchanged for an in-process draw: when the deciding process holds
+ * the secret it IS the operator's process, its verdict needs no evidence, and a
+ * sampled request stays byte-for-byte a manual one (pinned by
+ * `tests/autonomy-split.test.ts`).
+ *
+ * A DELEGATED verdict is a different object. The deciding process did not
+ * compute it; another process asserted it. An assertion recorded without its
+ * proof is a self-reported field, and SPEC.md §11 says those never reduce
+ * scrutiny. So the delegation is recorded WITH the MAC that makes it checkable,
+ * and a delegation that cannot be evidenced is not recorded at all — it gates,
+ * and the field says which of the three refusals happened.
+ *
+ * What is never recorded: the secret, the selection value, or any timestamp the
+ * asker or the daemon supplied. The MAC is a digest under a key nobody in this
+ * process holds, and the operator recomputes it from the record's own fields.
+ */
+export interface LiveDrawRecord {
+    v: number;
+    /**
+     * `"daemon"` — a MAC'd answer, recorded with its proof.
+     * `"unavailable"` — no usable answer; `reason` says which refusal.
+     */
+    source: "daemon" | "unavailable";
+    /** `selected` for a daemon answer, else the {@link DrawRefusalReason}. */
+    reason: "selected" | DrawRefusalReason;
+    /** The rate the draw was made at, so a verifier reconstructs the question. */
+    live_rate: number;
+    /** The daemon's verdict. Present only with a MAC to check it against. */
+    selected?: boolean;
+    mac?: string;
+    daemon_pid?: number;
+}
+/**
+ * Recompute a recorded delegation, from the record and the operator's secret.
+ *
+ * This is the whole point of the MAC, and it is deliberately a function of the
+ * RECORD rather than of anything the asker kept: `action_key` and
+ * `payload_hash` are the request's own fields and `policy_sha256` is assigned at
+ * the write boundary, so a verifier reconstructs the question from bytes the
+ * requester could not choose freely and could not alter afterwards without
+ * breaking the chain.
+ *
+ * `false` for a record with no MAC (a refusal), for a tampered MAC, and for a
+ * flipped verdict. Never throws.
+ */
+export declare function verifyLiveDrawRecord(secret: string, fields: {
+    actionKey: string;
+    payloadHash: string;
+    policyHash: string;
+    draw: LiveDrawRecord;
+}): boolean;
+/**
+ * Read one answer line against the question that was asked.
+ *
+ * Every check can only REJECT. The asker holds no secret, so it cannot check the
+ * MAC; what it CAN check is that the answer is this protocol's version, is an
+ * answer to this exact question (the daemon's own derivation, field for field),
+ * carries a MAC of the right shape, and names a live process. Anything else is
+ * `draw-answer-invalid` and the action gates.
+ */
+export declare function parseDrawAnswer(text: string, asked: DrawQuestion): DrawOutcome;
+/** The seam a caller (and every test) substitutes for the real spawn. */
+export type DrawAsker = (logPath: string, question: DrawQuestion) => DrawOutcome;
+/** Where the relay child lives, beside this module in the built tree. */
+export declare function drawChildPath(): string;
+/**
+ * What an asker concludes about the socket file, before anything is dialled.
+ *
+ * Exported since APRV-281 for a second, non-asking caller: the hook prints a
+ * line saying where a request went and whether anything is there to consume it,
+ * and "anything is there" is exactly this question. Nothing is connected here,
+ * so a `{ ok: true }` says the file looks like this user's live daemon rather
+ * than that the far side answers; a caller that needs the stronger claim asks a
+ * question through {@link askDaemonDraw}.
+ *
+ * One predicate rather than a copy per caller, for the reason `liveClassesOf`
+ * is shared: two readers of the same file that reach different conclusions
+ * about whether a daemon is up would each be right in its own words and
+ * useless together.
+ */
+export declare function drawSocketUsable(path: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: DrawRefusalReason;
+    detail: string;
+};
+/**
+ * Ask the daemon, synchronously, from a process that holds no secret.
+ *
+ * A child process, and the module header of `daemon/draw-child.ts` says why:
+ * the gate's request path is synchronous end to end (APRV-188 measured and
+ * documented the same constraint), `node:net` is not, and there is no
+ * synchronous Unix-socket client in Node. So one `spawnSync` of a tiny relay,
+ * about 20-40 ms of Node start. That cost is affordable HERE and nowhere else:
+ * this runs only for a `supervised-live` class whose deciding process has no
+ * secret, which is off the pass-through path entirely — no `Read`, no ordinary
+ * `Edit`, no autonomous class ever reaches it.
+ *
+ * The child is given a deliberately bare environment. It needs `PATH` for
+ * nothing and holds no secret; passing the session's environment to it would
+ * hand a relay every credential the session was launched with, which is the
+ * scrub `core/child-env.ts` exists to prevent.
+ */
+export declare function askDaemonDraw(logPath: string, question: DrawQuestion): DrawOutcome;
+/**
+ * The second thing this socket answers: not "would these bytes be sampled" but
+ * "is your sampler running at all" (APRV-271).
+ *
+ * ## Why the socket, and not the asker's own environment
+ *
+ * `approval doctor`'s `audit-sampling` row read `APPROVAL_SAMPLING_SECRET` out
+ * of the shell doctor was launched in, and reported `secret-unset` whenever it
+ * was not there. It is never there: the secret lives in the ONE terminal the
+ * operator ran `eval "$(approval env)"` in and started the daemon from, and
+ * `core/child-env.ts` strips `APPROVAL_*` from every child. So the row was red
+ * on machines where sampling was running perfectly, which is the same shape of
+ * bug APRV-208 fixed for the draw itself, in the row next door.
+ *
+ * The process that legitimately knows is the daemon. This asks it.
+ *
+ * ## What it deliberately is not
+ *
+ * **Not MAC'd, and not believed the way a draw is.** A draw answer decides a
+ * verdict, so it is evidenced: recorded with a MAC an operator recomputes later
+ * (see {@link LiveDrawRecord}). This one decides nothing. It authorizes no
+ * action, spends no budget, gates nothing and is written to no log; it changes
+ * the wording and the colour of one diagnostic row. What bounds who may make
+ * the claim is the socket itself, which {@link askDaemonSampling} requires to
+ * be owner-only and owned by this euid before it will dial it.
+ *
+ * That bound is why the caller must keep the question narrow. The only sampler
+ * state another process may honestly answer for is `secret-unset`, which is a
+ * fact about a PROCESS ENVIRONMENT. Every other disabled reason (`rate-absent`,
+ * `rate-invalid`, `rate-zero`, `secret-env-unnamed`, `policy-unreadable`) is a
+ * fact about the policy FILE, which the asker is reading for itself and no
+ * daemon's answer may soften. `cli/doctor.ts` consults this on that one branch
+ * and nowhere else.
+ *
+ * **Never the secret.** The report carries the variable's NAME, which the
+ * policy file already states in the open, and the rate, which it also states.
+ * The value is in one field of one process and leaves it in nothing but a MAC.
+ */
+export declare const SAMPLING_QUERY = "sampling";
+/** A daemon's report on its OWN sampler. Values are facts, not instructions. */
+export interface SamplingReport {
+    /** Is `core/sampler.ts` enabled in the answering process? */
+    enabled: boolean;
+    /** The machine-readable disabled reason, or `null` when it is enabled. */
+    reason: string | null;
+    /** The NAME of the secret's environment variable. Never its value. */
+    secret_env: string | null;
+    /** The global fallback rate, `null` when only class rules declare one. */
+    rate: number | null;
+    /** Which class patterns the daemon's policy declares `supervised-live`. */
+    live_classes: string[];
+}
+/** What the daemon answers a {@link SAMPLING_QUERY} with. */
+export interface SamplingAnswer {
+    v: number;
+    sampling: SamplingReport;
+    daemon_pid: number;
+    answered_at: string;
+}
+/** What the asker got back, with the socket it asked, for the report. */
+export type SamplingOutcome = {
+    ok: true;
+    answer: SamplingAnswer;
+    socket: string;
+} | {
+    ok: false;
+    reason: DrawRefusalReason;
+    detail: string;
+    socket: string;
+};
+/** Is this line a status question rather than a draw? Used by the server. */
+export declare function isSamplingQuery(line: string): boolean;
+/**
+ * Read one status answer.
+ *
+ * Every field is taken apart and rebuilt rather than passed through, so an
+ * answer carrying keys this protocol never defined loses them here: a report
+ * printed by a diagnostic must not be able to carry text of the answerer's
+ * choosing into an operator's terminal.
+ */
+export declare function parseSamplingAnswer(text: string): {
+    ok: true;
+    answer: SamplingAnswer;
+} | {
+    ok: false;
+    reason: DrawRefusalReason;
+    detail: string;
+};
+/**
+ * Open the draw socket, optionally exchange one line, and hang up.
+ *
+ * ASYNCHRONOUS, unlike {@link askDaemonDraw}, and that difference is the whole
+ * reason it can exist without a relay child. The draw is asked from the gate's
+ * synchronous request path, which is why it pays for a `spawnSync`; every
+ * caller of this one is a diagnostic that is already inside an async function,
+ * so it dials the socket directly and costs no process at all.
+ *
+ * `request` of `null` connects and closes without saying anything, which is how
+ * a caller asks the only question a socket file cannot answer by existing:
+ * whether anything is listening on it.
+ */
+export declare function dialDrawSocket(path: string, request: string | null, timeoutMs?: number): Promise<{
+    ok: true;
+    line: string | null;
+} | {
+    ok: false;
+    reason: DrawRefusalReason;
+    detail: string;
+}>;
+/**
+ * Ask the running daemon what its own sampler is doing.
+ *
+ * The same pre-checks a draw makes, for the same reasons: a path past the
+ * address limit, an absent file, a foreign owner and a group- or world-writable
+ * mode each mean no answer from here can be attributed to this user's daemon.
+ * The pid is checked for liveness afterwards, because a socket that outlived
+ * its server is a file answering for a process that is gone.
+ */
+export declare function askDaemonSampling(logPath: string, timeoutMs?: number): Promise<SamplingOutcome>;

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

@@ -0,0 +1,89 @@
+/**
+ * Chain drift: how two copies of one log relate to each other (APRV-125).
+ *
+ * Two verbs and one doctor check ask the same question in three places. `approval
+ * log sync` asks it after a fast-forward pull ("is the committed baseline a
+ * prefix of the chain I was holding, or did the two fork?"), `approval doctor`
+ * asks it standing still ("is my working log ahead of what is committed, and by
+ * how much?"), and a future ambient runtime will ask it before offering to
+ * advance. Three implementations of one comparison would be three chances to
+ * disagree about whether a repository has forked, so there is one, and it lives
+ * here.
+ *
+ * ## What a comparison is allowed to read
+ *
+ * Only verified records. Both sides go through `core/verify.ts` before a single
+ * `seq` is compared, and a side that does not verify clean is a refusal rather
+ * than an answer: a torn or broken chain has no head worth naming, and
+ * "diverged" would be the wrong word for "unreadable". This is SPEC §11.1's
+ * "enforcement paths read only verified records" applied to the one path that
+ * decides whether a working log may be put back after a pull.
+ *
+ * ## The four relations, and why `behind` is not a fork
+ *
+ * The chains are compared record by record on their hashes, which is the whole
+ * comparison: a hash equality at position i means every byte of records 1..i is
+ * shared, because each hash covers its own record and its predecessor's.
+ *
+ * - `equal` — the same chain. Nothing to do.
+ * - `ahead` — the committed chain is a strict PREFIX of the working one. The
+ *   working file carries appends that are not committed yet; this is the normal
+ *   state of a machine that has been granting approvals.
+ * - `behind` — the working chain is a strict prefix of the committed one. The
+ *   pull brought records this machine did not have. Adopting the longer chain
+ *   extends the working log and rewinds nothing, so it is not a fork either.
+ * - `diverged` — the chains agree up to some point and then do not. Two
+ *   appenders built different records on the same predecessor. Hash chains do
+ *   not merge and nothing in this codebase may try to merge them; the only
+ *   honest answer is the seq where they parted and a refusal.
+ */
+import type { LogHead } from "./log.js";
+import type { ValidateOptions } from "./validate.js";
+/** How the working chain stands relative to the committed one. */
+export type LogRelation = "equal" | "ahead" | "behind" | "diverged";
+/** The comparison's answer. Every field is present in every relation. */
+export interface LogDrift {
+    relation: LogRelation;
+    /** Records the working chain holds beyond the committed one. */
+    ahead: number;
+    /** Records the committed chain holds beyond the working one. */
+    behind: number;
+    workingHead: LogHead | null;
+    committedHead: LogHead | null;
+    /**
+     * The first `seq` at which the two chains carry different records. `null`
+     * unless `relation` is `diverged`; a prefix relationship has no such point.
+     */
+    firstDivergentSeq: number | null;
+}
+/** Why a comparison could not be made. Distinct from any relation. */
+export type ReconcileRefusalCode = "working-unverified" | "committed-unverified";
+export type ReconcileResult = {
+    ok: true;
+    drift: LogDrift;
+} | {
+    ok: false;
+    code: ReconcileRefusalCode;
+    message: string;
+};
+/** One side of the comparison, named so a refusal can say which side failed. */
+export interface ChainSide {
+    /** How this side is named in messages ("the working log", "HEAD:<path>"). */
+    label: string;
+    /** The whole file, as text. An absent file is the empty string. */
+    text: string;
+}
+/**
+ * Compare a working chain against a committed one.
+ *
+ * `working` is the chain a machine is holding (the file on disk, or a snapshot
+ * of it); `committed` is the chain in version control. The relation is stated
+ * from the working chain's point of view, which is the direction both callers
+ * report in: doctor says "ahead by 3", sync says "the committed baseline is a
+ * prefix, so the snapshot goes back".
+ */
+export declare function compareChains(working: ChainSide, committed: ChainSide, options?: ValidateOptions): ReconcileResult;
+/** A head, as messages and runbooks spell one. */
+export declare function describeHead(head: LogHead | null): string;
+/** One sentence naming the relation, shared by sync's report and doctor's detail. */
+export declare function describeDrift(drift: LogDrift): string;

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

@@ -0,0 +1,36 @@
+/**
+ * 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 type { EventRecord } from "./log.js";
+import { type VerifyFailureReason } from "./verify.js";
+export type LogSubscriptionFailureKind = "integrity" | "torn-tail" | "io";
+/** A terminal subscription failure, mapped by the CLI to the existing exits. */
+export declare class LogSubscriptionError extends Error {
+    readonly kind: LogSubscriptionFailureKind;
+    readonly reason: VerifyFailureReason | "cursor-mismatch" | null;
+    constructor(kind: LogSubscriptionFailureKind, message: string, reason?: VerifyFailureReason | "cursor-mismatch" | null);
+}
+export interface LogSubscriptionOptions {
+    /** Exclusive cursor. Zero replays the whole verified log. */
+    from?: number;
+    /** Hash of record `from`, retained outside the log by the consumer. */
+    expectedHash?: string;
+    /** Cancellation closes the watcher, timer, and signal listener. */
+    signal?: AbortSignal;
+    /** Bounded fallback when filesystem notifications are missing. */
+    pollIntervalMs?: number;
+}
+/**
+ * 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 declare function subscribeVerifiedLog(logPath: string, options?: LogSubscriptionOptions): AsyncGenerator<EventRecord, void, void>;