approval-md 0.1.0 → 0.3.0

package/dist/src/core/read-scope.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Read scope: which directories an agent may read from (APRV-347).
+ *
+ * ## The hole this closes
+ *
+ * Writes and deletes have been path-scoped for a while. `files.delete.scratch`
+ * versus `files.delete.out_of_scope` is decided by comparing a resolved target
+ * against roots the caller supplied (`ClassifierContext.scratchRoots`), and the
+ * file tools carry their target into the payload a grant binds. Reads had none
+ * of that: every shell reader classified `read.shell` with no path bound, and
+ * `Read`, `Glob` and `Grep` were answered `allow` before classification ever
+ * ran. So a policy could say a great deal about what an agent may WRITE and
+ * nothing at all about what it may SEE, and an agent working in one directory
+ * could read every sibling of it.
+ *
+ * This module is the pure half of the read-side mirror. It holds the class
+ * name, the roots arithmetic, and the one genuinely fiddly question — which
+ * words of a read command are paths — and it touches no disk, reads no
+ * environment and resolves nothing. The impure half (relative paths resolved
+ * against a working directory, symlinks followed, the escape that only the
+ * filesystem can see) lives in `src/cli/hook.ts`, exactly where the delete
+ * rule's second pass lives, and it can only ever TIGHTEN this file's answer.
+ *
+ * ## Fail closed, in three places
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path. Here that is
+ *
+ * 1. a target this file cannot read as a path (a `$VAR`, a glob, a `~`) is out
+ *    of scope, because what it expands to is not in the text;
+ * 2. a read command naming NO target reads the working directory, so it is
+ *    checked against the working directory rather than waved through;
+ * 3. an empty root list means nothing is in scope — but a caller that passes no
+ *    roots at all gets today's answer instead (see {@link ClassifierContext}),
+ *    because a caller that forgot the field must not have every read it makes
+ *    turned into a decision.
+ *
+ * ## What a root is
+ *
+ * The gate root (the directory holding the policy file the runtime resolved),
+ * the session scratchpad, and the system temp root. A policy may WIDEN that
+ * with `read_scope.roots`; it may not narrow it below the gate root, because a
+ * runtime that cannot read its own policy, log and workspace cannot run at all.
+ */
+/**
+ * The class a read outside every root takes.
+ *
+ * A sibling of `read.shell` rather than a replacement for it: a read INSIDE the
+ * roots is the same ordinary, autonomous act it has always been, and a policy
+ * that says nothing about this class gets `defaults.autonomy` for it, which is
+ * the fail-closed direction for a name nobody has declared.
+ */
+export declare const READ_OUT_OF_SCOPE_CLASS = "read.file.out_of_scope";
+/**
+ * The `read_scope` block of a policy (SPEC.md §5, amended APRV-347).
+ *
+ * Additive and optional, with the same discipline `protected_paths` has: the
+ * built-in roots stand whatever this says, so a policy can widen the scope and
+ * never shrink it. A relative entry is resolved against the gate root, so a
+ * policy stays portable between a checkout and a clone of it.
+ */
+export interface ReadScope {
+    roots?: string[];
+}
+/**
+ * Is `candidate` AT or under `root`, by path segment?
+ *
+ * At-or-under rather than the delete rule's strictly-under: `ls <gate root>` is
+ * a read of the workspace an agent is working in, and a rule that made the root
+ * itself out of scope would classify the most ordinary command in the session.
+ *
+ * Segment matching, never string prefixes: `/dev/muse-other` must not match a
+ * root of `/dev/muse`, and `startsWith` says it does.
+ */
+export declare function isAtOrUnderReadRoot(candidate: string, root: string): boolean;
+/** Is this path inside ANY of these roots? */
+export declare function isInReadScope(candidate: string, roots: readonly string[]): boolean;
+/**
+ * A value whose expansion the classifier cannot see, and therefore may not
+ * vouch for. The same test the delete rule applies, and for the same reason:
+ * `cat $SOMEWHERE` reads whatever that variable holds.
+ */
+export declare function isUnreadableTarget(word: string): boolean;
+/**
+ * The effective read roots: the built-ins, plus whatever the policy added.
+ *
+ * Pure, and every input is the caller's. `gateRoot` is the directory holding
+ * the policy file the runtime resolved; `systemRoots` are the scratchpad and
+ * temp roots the caller already resolved (`resolveScratchRoots` in the hook);
+ * `declared` is `read_scope.roots` verbatim.
+ *
+ * A declared entry that is relative is joined onto the gate root. A declared
+ * entry the caller cannot vouch for — empty, or one this file can see is not a
+ * path at all — is DROPPED rather than accepted, because a root is an
+ * authorization and a malformed one must not become `/`.
+ *
+ * The result is de-duplicated and otherwise in the order given, so the first
+ * root a path matches is the most specific one a reader would expect.
+ */
+export declare function effectiveReadRoots(options: {
+    gateRoot: string;
+    declared?: readonly string[] | undefined;
+    systemRoots?: readonly string[] | undefined;
+}): string[];
+/**
+ * How a reader's positionals map to paths.
+ *
+ * - `all`: every positional is a file or directory (`cat a b`, `ls src`,
+ *   `diff a b`, `cut -d: -f1 /etc/passwd` — `cut`'s delimiter and field list
+ *   are flags, so none of its positionals is a pattern).
+ * - `after-pattern`: the FIRST positional is a pattern or a script and the rest
+ *   are paths (`grep needle src`, `sed -n 1,5p file`, `jq .x file.json`) —
+ *   UNLESS the pattern arrived through a flag (`-e`, `-f`), in which case every
+ *   positional is a path and the shape collapses to `all`.
+ * - `walk`: `find`'s shape — positionals up to the first primary are paths.
+ *
+ * Binaries absent from this table are absent on purpose, and each omission is a
+ * decision not to widen anything:
+ *
+ * - `echo`, `printf`, `tr`, `test`, `type`, `which`, `pwd`, `true`, `false`,
+ *   `cd`: their positionals are not files, or name a file without reading its
+ *   contents. A rule that treated `echo /etc/passwd` as a read of that file
+ *   would route text through a human.
+ * - `basename`, `dirname`, `readlink`, `realpath`: they manipulate or resolve a
+ *   path and never open it. What leaks is the existence of a name, which is not
+ *   what this class is about.
+ * - `less` and `more` are NOT added to the classifier's reader list by this
+ *   task. Adding them would take them from `unclassified` (a deny) to
+ *   `read.shell` (this repository's policy: autonomous), which is a widening,
+ *   and a task that exists to narrow reads has no business doing that in
+ *   passing. They are named in the follow-up in `docs/sandboxed-exec.md`.
+ */
+export type ReadTargetShape = "all" | "after-pattern" | "walk";
+/** Which readers take paths, and where. Keyed by the binary's basename. */
+export declare const READ_TARGET_SHAPES: Readonly<Record<string, ReadTargetShape>>;
+/**
+ * The paths a read command will open, or `null` when this binary is not one
+ * whose reads this module scopes.
+ *
+ * An empty array is a real answer and is NOT the same as `null`: it means this
+ * reader opens the working directory (`ls`, `find`, `grep needle` with no file
+ * operand), and the caller checks the working directory in its place. `null`
+ * means "not a scoped reader", and the caller leaves the segment alone.
+ *
+ * Treating a non-path positional as a path costs nothing: a bare word resolves
+ * against the working directory, which is inside a root in every session this
+ * module is meant for. Treating a path as a non-path costs the whole property.
+ */
+export declare function readTargetsOf(bin: string, positionals: readonly string[], args?: readonly string[]): string[] | null;
+/**
+ * The verdict the PURE half can reach for one target.
+ *
+ * `out-of-scope` and `in-scope` are final. `needs-disk` is the honest answer
+ * for a relative path: its meaning depends on a working directory this file
+ * does not have, and the caller with the disk decides it. A caller that cannot
+ * do the second pass must treat `needs-disk` as out of scope — which is what
+ * `hook classify` and `hook <harness>` both do, through the same function.
+ */
+export type ReadTargetVerdict = "in-scope" | "out-of-scope" | "needs-disk";
+/**
+ * Read one target against the roots, as far as text alone can settle it.
+ *
+ * Absolute and inside a root: in scope. Absolute and outside every root: out of
+ * scope, decided here, no disk needed. Unreadable (a variable, a glob, a `~`):
+ * out of scope, because what it names is not in the text. Anything relative, or
+ * carrying a `..`, is `needs-disk`.
+ */
+export declare function readTargetVerdict(target: string, roots: readonly string[]): ReadTargetVerdict;
+/**
+ * The roots, rendered for a human: `approval policy check`'s line and the
+ * hook's verdict note say the same sentence.
+ */
+export declare function renderReadRoots(roots: readonly string[]): string;

package/dist/src/core/read-scope.js

@@ -0,0 +1,252 @@
+/**
+ * Read scope: which directories an agent may read from (APRV-347).
+ *
+ * ## The hole this closes
+ *
+ * Writes and deletes have been path-scoped for a while. `files.delete.scratch`
+ * versus `files.delete.out_of_scope` is decided by comparing a resolved target
+ * against roots the caller supplied (`ClassifierContext.scratchRoots`), and the
+ * file tools carry their target into the payload a grant binds. Reads had none
+ * of that: every shell reader classified `read.shell` with no path bound, and
+ * `Read`, `Glob` and `Grep` were answered `allow` before classification ever
+ * ran. So a policy could say a great deal about what an agent may WRITE and
+ * nothing at all about what it may SEE, and an agent working in one directory
+ * could read every sibling of it.
+ *
+ * This module is the pure half of the read-side mirror. It holds the class
+ * name, the roots arithmetic, and the one genuinely fiddly question — which
+ * words of a read command are paths — and it touches no disk, reads no
+ * environment and resolves nothing. The impure half (relative paths resolved
+ * against a working directory, symlinks followed, the escape that only the
+ * filesystem can see) lives in `src/cli/hook.ts`, exactly where the delete
+ * rule's second pass lives, and it can only ever TIGHTEN this file's answer.
+ *
+ * ## Fail closed, in three places
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path. Here that is
+ *
+ * 1. a target this file cannot read as a path (a `$VAR`, a glob, a `~`) is out
+ *    of scope, because what it expands to is not in the text;
+ * 2. a read command naming NO target reads the working directory, so it is
+ *    checked against the working directory rather than waved through;
+ * 3. an empty root list means nothing is in scope — but a caller that passes no
+ *    roots at all gets today's answer instead (see {@link ClassifierContext}),
+ *    because a caller that forgot the field must not have every read it makes
+ *    turned into a decision.
+ *
+ * ## What a root is
+ *
+ * The gate root (the directory holding the policy file the runtime resolved),
+ * the session scratchpad, and the system temp root. A policy may WIDEN that
+ * with `read_scope.roots`; it may not narrow it below the gate root, because a
+ * runtime that cannot read its own policy, log and workspace cannot run at all.
+ */
+/**
+ * The class a read outside every root takes.
+ *
+ * A sibling of `read.shell` rather than a replacement for it: a read INSIDE the
+ * roots is the same ordinary, autonomous act it has always been, and a policy
+ * that says nothing about this class gets `defaults.autonomy` for it, which is
+ * the fail-closed direction for a name nobody has declared.
+ */
+export const READ_OUT_OF_SCOPE_CLASS = "read.file.out_of_scope";
+/** Non-empty path segments, `.` dropped. Identical to the classifier's own. */
+function segmentsOf(candidate) {
+    return candidate
+        .split(/[/\\]+/u)
+        .filter((segment) => segment.length > 0 && segment !== ".");
+}
+/**
+ * Is `candidate` AT or under `root`, by path segment?
+ *
+ * At-or-under rather than the delete rule's strictly-under: `ls <gate root>` is
+ * a read of the workspace an agent is working in, and a rule that made the root
+ * itself out of scope would classify the most ordinary command in the session.
+ *
+ * Segment matching, never string prefixes: `/dev/muse-other` must not match a
+ * root of `/dev/muse`, and `startsWith` says it does.
+ */
+export function isAtOrUnderReadRoot(candidate, root) {
+    const want = segmentsOf(root);
+    const have = segmentsOf(candidate);
+    if (want.length === 0)
+        return false;
+    if (have.length < want.length)
+        return false;
+    return want.every((segment, index) => segment === have[index]);
+}
+/** Is this path inside ANY of these roots? */
+export function isInReadScope(candidate, roots) {
+    return roots.some((root) => isAtOrUnderReadRoot(candidate, root));
+}
+/**
+ * A value whose expansion the classifier cannot see, and therefore may not
+ * vouch for. The same test the delete rule applies, and for the same reason:
+ * `cat $SOMEWHERE` reads whatever that variable holds.
+ */
+export function isUnreadableTarget(word) {
+    return (word.includes("$") ||
+        word.includes("*") ||
+        word.includes("?") ||
+        word.includes("[") ||
+        word.startsWith("~"));
+}
+/**
+ * The effective read roots: the built-ins, plus whatever the policy added.
+ *
+ * Pure, and every input is the caller's. `gateRoot` is the directory holding
+ * the policy file the runtime resolved; `systemRoots` are the scratchpad and
+ * temp roots the caller already resolved (`resolveScratchRoots` in the hook);
+ * `declared` is `read_scope.roots` verbatim.
+ *
+ * A declared entry that is relative is joined onto the gate root. A declared
+ * entry the caller cannot vouch for — empty, or one this file can see is not a
+ * path at all — is DROPPED rather than accepted, because a root is an
+ * authorization and a malformed one must not become `/`.
+ *
+ * The result is de-duplicated and otherwise in the order given, so the first
+ * root a path matches is the most specific one a reader would expect.
+ */
+export function effectiveReadRoots(options) {
+    const roots = [];
+    const add = (candidate) => {
+        if (candidate.length === 0)
+            return;
+        if (!roots.includes(candidate))
+            roots.push(candidate);
+    };
+    add(options.gateRoot);
+    for (const root of options.systemRoots ?? [])
+        add(root);
+    for (const entry of options.declared ?? []) {
+        if (typeof entry !== "string" || entry.length === 0)
+            continue;
+        if (isUnreadableTarget(entry))
+            continue;
+        add(entry.startsWith("/") ? entry : `${options.gateRoot}/${entry}`);
+    }
+    return roots;
+}
+/** Which readers take paths, and where. Keyed by the binary's basename. */
+export const READ_TARGET_SHAPES = {
+    cat: "all",
+    cksum: "all",
+    cut: "all",
+    diff: "all",
+    du: "all",
+    file: "all",
+    find: "walk",
+    grep: "after-pattern",
+    head: "all",
+    jq: "after-pattern",
+    ls: "all",
+    md5sum: "all",
+    rg: "after-pattern",
+    sed: "after-pattern",
+    sha256sum: "all",
+    shasum: "all",
+    sort: "all",
+    stat: "all",
+    tail: "all",
+    tree: "all",
+    uniq: "all",
+    wc: "all",
+};
+/**
+ * `find` primaries: the first word starting with `-` ends the path list.
+ *
+ * `find` is the one reader whose arguments are a little language, and its shape
+ * is `find [paths…] [expression]`. This one reads the RAW argument list rather
+ * than the flag-filtered positionals, because the filter is what tells the
+ * paths from the expression: in `find . -name '*.ts'` the pattern `*.ts` is a
+ * positional too, and a rule fed the filtered list would read it as a path,
+ * find it unreadable, and call an ordinary walk of the workspace out of scope.
+ */
+function walkTargets(args) {
+    const targets = [];
+    for (const word of args) {
+        if (word.startsWith("-"))
+            break;
+        targets.push(word);
+    }
+    return targets;
+}
+/**
+ * Flags that carry the pattern or the script, so every positional is a path.
+ *
+ * `grep -e needle src`, `sed -f script.sed file`, `rg --regexp needle dir`: the
+ * first positional is the FILE, and a rule that skipped it would leave the one
+ * target that matters unchecked. Under-detection is the failure mode that
+ * matters here — an unchecked read is a read outside the jail — so the shape
+ * widens to `all` whenever one of these appears.
+ */
+const PATTERN_BEARING_FLAGS = [
+    "-e",
+    "-f",
+    "--regexp",
+    "--expression",
+    "--file",
+];
+/** Did the pattern (or script) arrive through a flag rather than a positional? */
+function patternCameFromFlag(args) {
+    return args.some((arg) => PATTERN_BEARING_FLAGS.includes(arg) ||
+        PATTERN_BEARING_FLAGS.some((flag) => flag.startsWith("--") && arg.startsWith(`${flag}=`)));
+}
+/**
+ * The paths a read command will open, or `null` when this binary is not one
+ * whose reads this module scopes.
+ *
+ * An empty array is a real answer and is NOT the same as `null`: it means this
+ * reader opens the working directory (`ls`, `find`, `grep needle` with no file
+ * operand), and the caller checks the working directory in its place. `null`
+ * means "not a scoped reader", and the caller leaves the segment alone.
+ *
+ * Treating a non-path positional as a path costs nothing: a bare word resolves
+ * against the working directory, which is inside a root in every session this
+ * module is meant for. Treating a path as a non-path costs the whole property.
+ */
+export function readTargetsOf(bin, positionals, args = []) {
+    const shape = READ_TARGET_SHAPES[basenameOf(bin)];
+    if (shape === undefined)
+        return null;
+    switch (shape) {
+        case "all":
+            return [...positionals];
+        case "after-pattern":
+            return patternCameFromFlag(args) ? [...positionals] : positionals.slice(1);
+        case "walk":
+            return walkTargets(args.length === 0 ? positionals : args);
+    }
+}
+/** The last segment of a command word, so `/usr/bin/cat` reads as `cat`. */
+function basenameOf(bin) {
+    const segments = segmentsOf(bin);
+    return segments[segments.length - 1] ?? bin;
+}
+/**
+ * Read one target against the roots, as far as text alone can settle it.
+ *
+ * Absolute and inside a root: in scope. Absolute and outside every root: out of
+ * scope, decided here, no disk needed. Unreadable (a variable, a glob, a `~`):
+ * out of scope, because what it names is not in the text. Anything relative, or
+ * carrying a `..`, is `needs-disk`.
+ */
+export function readTargetVerdict(target, roots) {
+    if (target.length === 0)
+        return "needs-disk";
+    if (isUnreadableTarget(target))
+        return "out-of-scope";
+    if (!target.startsWith("/"))
+        return "needs-disk";
+    if (segmentsOf(target).includes(".."))
+        return "needs-disk";
+    return isInReadScope(target, roots) ? "in-scope" : "out-of-scope";
+}
+/**
+ * The roots, rendered for a human: `approval policy check`'s line and the
+ * hook's verdict note say the same sentence.
+ */
+export function renderReadRoots(roots) {
+    return roots.length === 0 ? "(none)" : roots.join(", ");
+}
+//# sourceMappingURL=read-scope.js.map

package/dist/src/core/read-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-scope.js","sourceRoot":"","sources":["../../../src/core/read-scope.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,25 @@
+/**
+ * Registration lookups shared by the gate, the daemon, and the doctor.
+ *
+ * Both exports are pure facts about the log and the Backlog.md layout that
+ * more than one layer needs. They lived in `daemon/` until APRV-59's layering
+ * guard (`tests/layering.test.ts`) made the rule explicit: `src/cli/` imports
+ * from `core/`, never from `daemon/`, so anything the CLI needs from the
+ * daemon's projection code moves here instead of widening the exception list.
+ */
+import type { EventRecord } from "./log.js";
+/**
+ * Where Backlog.md keeps task files, relative to the project directory. The
+ * daemon watches it and doctor's `--tasks` defaults to it.
+ */
+export declare const DEFAULT_TASKS_DIR = "backlog/tasks";
+/**
+ * The latest `task.registered` record for `task`, or `null`.
+ *
+ * `loose` matches the task id case-insensitively, for the one caller that has
+ * no frontmatter to read an id out of and must work from the Backlog.md file
+ * name (`task-3 - Slug.md` for a board key written `TASK-3`). It is a matching
+ * relaxation only: the record returned, and therefore the id every later step
+ * uses, is the log's, never the file name's.
+ */
+export declare function latestRegistration(records: EventRecord[], task: string, loose?: boolean): EventRecord | null;

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

@@ -0,0 +1,99 @@
+/**
+ * The SQLite index projection (SPEC.md §9.2, `.approval/index.sqlite`).
+ *
+ * **The database is a cache; the log is the truth.** Everything in this module
+ * follows from that one sentence:
+ *
+ * - The index is *derived*. It is rebuilt from scratch on every call — there is
+ *   no incremental path, no upsert, no "catch up from seq N". A projection that
+ *   can drift is a second source of truth, and this project only has one.
+ * - Deleting `index.sqlite` loses nothing. Every byte in it is recomputable
+ *   from `events.jsonl`; the file is a query surface, never a record.
+ * - Nothing here writes to the log. {@link reindex} opens `logPath` for reading
+ *   only: it never appends, never truncates, never repairs a torn tail.
+ * - It refuses to index what it cannot vouch for. Chain verification (APRV-7)
+ *   runs *first*, always. A corrupt log is refused outright; a torn tail is
+ *   refused unless the caller explicitly opts in, and even then only the intact
+ *   prefix is indexed and the truncation is recorded in the index metadata. An
+ *   index that silently contains tampered rows is worse than no index at all.
+ *
+ * **Determinism.** The same log always produces the same index *content*: rows
+ * are inserted in `seq` order inside a single transaction, `payload` is stored
+ * as its RFC 8785 canonicalization (so key order cannot vary), and no clock,
+ * hostname, or random value is ever written. SQLite's internal file bytes are
+ * explicitly *not* claimed to be reproducible — page layout and freelist state
+ * are the engine's business. Equality is asserted at the SQL level: identical
+ * logs yield identical query results.
+ *
+ * **Crash safety.** The index is built at a temporary path in the *same*
+ * directory and `rename(2)`d over `indexPath` once complete. A reindex killed
+ * halfway therefore never leaves a half-built index where a reader expects a
+ * whole one: the previous index survives untouched, and the temp file is
+ * cleaned up.
+ *
+ * **Staleness** is the caller's call to make, not this module's. The index
+ * records the log head `(seq, hash)` it was built from; {@link indexHead} reads
+ * it back so a caller can compare it against a fresh {@link verify} head and
+ * decide whether to rebuild.
+ *
+ * Dependency note: `better-sqlite3`, exact-pinned. `node:sqlite` was ruled out —
+ * `engines.node` is `>=20` and `node:sqlite` does not exist before Node 22.5.
+ */
+import type { ValidateOptions } from "./validate.js";
+import { type LogHead, type VerifyResult } from "./verify.js";
+/**
+ * Version of the index's own table layout. Bumped whenever the SQL schema
+ * below changes shape, so a reader can tell an index it understands from one it
+ * does not. It is not the log's version: the log is versioned by SPEC.md.
+ */
+export declare const INDEX_SCHEMA_VERSION = 1;
+/** Why a reindex was refused. Every failure is one of these, never a throw. */
+export type ReindexErrorCode = "not-clean" | "torn-tail" | "io";
+export interface ReindexError {
+    code: ReindexErrorCode;
+    message: string;
+    /** The verification result behind the refusal, when there is one. */
+    verify?: VerifyResult;
+}
+export type ReindexResult = {
+    ok: true;
+    /** Rows written to `events`. */
+    records: number;
+    /** The log head the index was built from; `null` for an empty log. */
+    head: LogHead | null;
+    /** True when only an intact prefix was indexed (forced torn tail). */
+    truncated: boolean;
+} | {
+    ok: false;
+    error: ReindexError;
+};
+/** Options for {@link reindex}. */
+export interface ReindexOptions extends ValidateOptions {
+    /**
+     * Index the intact prefix of a torn-tail log (records `1..intactThroughSeq`)
+     * instead of refusing. The truncation is recorded in `meta`. This never
+     * repairs the log — the torn line stays exactly where it is.
+     */
+    force?: boolean;
+}
+/**
+ * Rebuild the SQLite index at `indexPath` from the log at `logPath`.
+ *
+ * Always verifies the chain first. Returns a structured result rather than
+ * throwing; on any refusal the existing index (if any) is left exactly as it
+ * was and no new file is created.
+ */
+export declare function reindex(logPath: string, indexPath: string, options?: ReindexOptions): ReindexResult;
+/**
+ * The provenance recorded in an existing index: the log head it was built from,
+ * and whether it covers only an intact prefix.
+ *
+ * Returns `null` when the file is missing, unreadable, or carries no `meta`
+ * row — all of which mean the same thing to a caller: there is no index to
+ * trust, rebuild. Compare `head` against a fresh `verify(logPath).head` to
+ * detect staleness. Deleting `indexPath` loses nothing.
+ */
+export declare function indexHead(indexPath: string): {
+    head: LogHead | null;
+    truncated: boolean;
+} | null;