approval-md 0.1.0 → 0.3.0

package/dist/src/daemon/git-evidence.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Per-event git commits — SPEC.md §8's optional hardening (APRV-42).
+ *
+ * > "Optionally, the log directory is a git repo and the daemon commits per
+ * > event with its own identity, giving signed, distributed tamper evidence for
+ * > free."
+ *
+ * The chain in `events.jsonl` already detects mutation and truncation on its
+ * own. What a git repository adds is a *second, independent* record of the same
+ * bytes: a mutation that is plausible against one layer has to be plausible
+ * against the other at the same time, and the second layer is one an operator
+ * can clone, mirror, and diff from somewhere the tamperer does not control.
+ * Neither layer is trusted to police the other, which is the point of having
+ * two: `approval log verify` never consults git, and nothing here ever reads a
+ * verdict out of a commit.
+ *
+ * ## Opt-in, and only for a standalone log deployment
+ *
+ * This is off unless the operator asks for it, and refuses to turn on unless the
+ * log's own directory is a repository *root*. The two layouts do not mix:
+ *
+ * - **Standalone log deployment.** The log home (`.approval/`, or whatever
+ *   directory holds the log when it is not under a `log/` folder) is its own git
+ *   repository, containing the log, the payload store, and nothing else. Enable
+ *   the opt-in here.
+ * - **Nested project layout** — this repository's own dogfood arrangement, where
+ *   `.approval/` is committed as part of a larger project repo. Perfectly valid,
+ *   and the opt-in is REFUSED for it.
+ *
+ * Why refuse the nested case rather than make it work? Because a hash chain does
+ * not survive a merge. Two branches that each append independently produce a
+ * chain that is corrupt by construction, and no merge strategy repairs the
+ * semantics. An outer repository's ordinary history operations — rebase, amend,
+ * squash, force-push, `filter-branch` — rewrite the very bytes the evidence is
+ * made of, and a daemon committing into someone else's branch would be a second
+ * writer to a history the project's humans also write. Evidence that the subject
+ * of the investigation can rewrite is not evidence. So the runtime does not try
+ * to be clever about it: own-root repository, or no git evidence at all.
+ *
+ * ## What it does, precisely
+ *
+ * After every tick in which the log moved, the daemon calls {@link
+ * GitEvidenceRecorder.commit} with the verified head it just read. The recorder
+ * stages the log file and the payload store, and commits with a message naming
+ * the head's `(seq, hash)`. Batching is **one commit per tick**, not literally
+ * one per event: ticks are the only moment the daemon has a verified head in
+ * hand, and a commit is only meaningful against a head that verified. A tick
+ * that observed three appends produces one commit naming the new head and the
+ * number of records it covers — the intermediate states are still fully
+ * recoverable from the log itself, which is the artifact being witnessed.
+ *
+ * ## What it deliberately does not do
+ *
+ * It never pushes, never fetches, never creates or moves a branch by name, never
+ * touches a remote, and never writes to any git config outside the single
+ * `git commit` invocation (identity is passed with `-c`, per command, so the
+ * operator's `user.name` is neither read into the commit nor overwritten on
+ * disk). Commits are local, to the log's own repository, authored by the daemon
+ * as itself. A failure to commit is a warning, never a stop: git evidence is
+ * hardening on top of the chain, and a daemon that halted approvals because a
+ * disk was full of git objects would have converted a redundancy into a
+ * dependency.
+ */
+import type { LogHead } from "../core/log.js";
+/**
+ * The daemon's own git identity. Never the operator's: a commit that says a
+ * human made it is a false statement about who wrote the evidence, and the whole
+ * value of the second layer is that its authorship is unambiguous.
+ *
+ * The version is pinned to `package.json` by a test rather than read at runtime,
+ * because a module that resolves its own package root differs between the source
+ * tree and the build output for no benefit at all.
+ */
+export declare const APPROVALD_VERSION = "0.3.0";
+/** `user.name` on every commit this module makes. */
+export declare const GIT_EVIDENCE_AUTHOR_NAME = "approvald 0.3.0";
+/** `user.email` on every commit: fixed, and deliberately undeliverable. */
+export declare const GIT_EVIDENCE_AUTHOR_EMAIL = "approvald@noreply.approval.md";
+/**
+ * Why enabling git evidence was refused. **Frozen union**, additive-only, in the
+ * same sense as every other refusal vocabulary in this codebase (SPEC.md §11.1
+ * invariant 6: refusals are machine-readable and distinct). An operator's
+ * supervisor branches on these to tell "install git" apart from "your layout is
+ * wrong", and the repair differs for every one of them.
+ */
+export declare const GIT_EVIDENCE_REFUSAL_CODES: readonly [
+/** No usable `git` on PATH. The daemon runs fine without the opt-in. */
+"git-unavailable", 
+/** The directory that would hold the evidence repository does not exist. */
+"log-dir-missing", 
+/** It exists and is not a git repository. The repair is `git init` there. */
+"log-dir-not-repo", 
+/**
+ * It is inside a working tree it does not own — either some outer repository
+ * tracks it, or it is a repository whose root is somewhere above. Hash chains
+ * do not survive merges and an outer history rewrites evidence.
+ */
+"log-dir-nested"];
+export type GitEvidenceRefusalCode = (typeof GIT_EVIDENCE_REFUSAL_CODES)[number];
+export interface GitEvidenceRefusal {
+    ok: false;
+    code: GitEvidenceRefusalCode;
+    message: string;
+}
+/**
+ * One line of git-evidence output. Its own frozen shape, reported through the
+ * callback the CLI supplies, so that `daemon/daemon.ts`'s event union stays
+ * exactly as it was: the hardening layer speaks for itself and the loop's
+ * contract is untouched.
+ */
+export type GitEvidenceEvent = {
+    event: "git_evidence";
+    /** The abbreviated commit this tick produced. */
+    commit: string;
+    /** The verified head the commit witnesses. */
+    seq: number;
+    hash: string;
+    /**
+     * Log lines added since the commit this one builds on — the batch size.
+     * The log is append-only, so a line is a record. `null` only when git
+     * declined to say, which is a reporting gap and never a correctness one.
+     */
+    records: number | null;
+} | {
+    event: "git_evidence_failed";
+    /** The git invocation that failed, as a bare subcommand name. */
+    step: string;
+    message: string;
+};
+/** Where git-evidence output goes. Injected, so this module writes to nothing. */
+export type GitEvidenceSink = (event: GitEvidenceEvent) => void;
+/**
+ * The hook the daemon calls. One method, taking the verified head of the log it
+ * just read, so that the loop's edit is a single line and no scheduling
+ * knowledge leaks into this file.
+ */
+export interface GitEvidenceRecorder {
+    commit(head: LogHead | null): void;
+}
+/**
+ * The directory that must be the evidence repository's root, for a given log.
+ *
+ * The same rule `payloadStoreDirFor` uses, for the same reason: SPEC.md §9 fixes
+ * the log at `<home>/log/events.jsonl` and the payload store at
+ * `<home>/payloads/`, so the only directory that contains *both* is `<home>`.
+ * Rooting the repository at the log's immediate directory would leave every
+ * payload file outside the evidence, which is precisely where a tamperer would
+ * then work. When a caller points `--log` somewhere flatter, the log's own
+ * directory is the home and the rule still holds.
+ */
+export declare function evidenceRootFor(logPath: string): string;
+export type EnableGitEvidenceResult = {
+    ok: true;
+    root: string;
+    recorder: GitEvidenceRecorder;
+} | GitEvidenceRefusal;
+/**
+ * Check every precondition and, when they all hold, build the recorder.
+ *
+ * Fail closed and fail *loudly*: each refusal is distinct, names the directory
+ * it judged, and states the repair. An operator who mistyped `--log` and an
+ * operator whose log lives inside a project repository need different sentences,
+ * and a single "git evidence unavailable" would have sent both of them looking
+ * in the wrong place.
+ */
+export declare function enableGitEvidence(logPath: string, sink: GitEvidenceSink): EnableGitEvidenceResult;
+/**
+ * The commit message: the head's `(seq, hash)` on the subject line, so a reader
+ * of `git log --oneline` can check a commit against the chain without opening
+ * anything, and the batch size in the body so the per-tick batching is visible
+ * rather than inferred.
+ */
+export declare function message(head: LogHead, records: number | null): string;

package/dist/src/daemon/git-evidence.js

@@ -75,7 +75,7 @@ import { PAYLOAD_STORE_DIRNAME } from "../core/payload-store.js";
  * because a module that resolves its own package root differs between the source
  * tree and the build output for no benefit at all.
  */
-export const APPROVALD_VERSION = "0.1.0";
+export const APPROVALD_VERSION = "0.3.0";
 /** `user.name` on every commit this module makes. */
 export const GIT_EVIDENCE_AUTHOR_NAME = `approvald ${APPROVALD_VERSION}`;
 /** `user.email` on every commit: fixed, and deliberately undeliverable. */

package/dist/src/daemon/projection.d.ts

@@ -0,0 +1,180 @@
+/**
+ * The daemon's pure projections (SPEC.md §6.3, §10.2).
+ *
+ * Everything the daemon *decides* lives here, and everything it *does* lives in
+ * `daemon.ts`. The split is the same one `core/loop.ts` draws for loop safety:
+ * a projection over verified records is a pure function of (records, instant,
+ * TTL), so it can be replayed, unit-tested against an injected clock, and never
+ * disagrees with itself between two callers.
+ *
+ * Nothing here reads the clock, the filesystem, or the network, and nothing
+ * here appends. Three questions are answered:
+ *
+ * 1. **What does the log say a task's envelope `state:` should be?**
+ *    {@link taskEnvelopeState}. §6.3: "`state` is a projection of log events;
+ *    the file is updated by the daemon after the event is appended, never the
+ *    reverse." The daemon compares the file's claim against this answer, and a
+ *    file that contradicts it is `envelope.drift`.
+ * 2. **Which live requests have lapsed with no `approval.expired` on record?**
+ *    {@link lapsedRequests}. The gate already judges TTL lazily at decision
+ *    time (a late grant is refused whether or not an expiry event exists), so
+ *    the sweep changes no verdict; it makes the verdict *visible* in the log
+ *    and in every projection built from it.
+ * 3. **Has this exact drift already been recorded?** {@link driftAlreadyLogged}.
+ *    A watcher fires on every save and the periodic tick re-scans regardless,
+ *    so without a dedupe rule one unfixed file would append an unbounded run of
+ *    identical events. The rule is stated on that function.
+ *
+ * The state derivation itself is NOT reimplemented here: every action's state
+ * comes from `core/state.ts`'s `requestState`, the same derivation the gate,
+ * the token module, and the executor read. This module only rolls action states
+ * up to the task level, and that rollup is the one new rule it owns.
+ */
+import type { EventRecord } from "../core/log.js";
+import { type RequestDerivation } from "../core/state.js";
+/**
+ * The envelope's `state:` vocabulary (`envelope.schema.json`, SPEC.md §6.3).
+ *
+ * Spelled here rather than imported from the schema because the schema is data
+ * read at runtime and this is a type; `tests/daemon-projection.test.ts` pins the
+ * two against each other so they cannot drift apart.
+ */
+export declare const ENVELOPE_STATES: readonly ["proposed", "awaiting", "approved", "executed", "rejected", "expired", "revoked"];
+export type EnvelopeState = (typeof ENVELOPE_STATES)[number];
+/** Is this the envelope's `state:` value? Used to read an untrusted file. */
+export declare function isEnvelopeState(value: unknown): value is EnvelopeState;
+/** One declared action of a task, as the log records it, with its derived state. */
+export interface ActionProjection {
+    actionKey: string;
+    derivation: RequestDerivation;
+}
+/** What the log says about one task. */
+export interface TaskProjection {
+    task: string;
+    /** A `task.registered` record exists for this task id. */
+    registered: boolean;
+    /** The envelope `state:` the log implies (SPEC.md §6.3). */
+    state: EnvelopeState;
+    /** Every action key the latest registration declared, with its derivation. */
+    actions: ActionProjection[];
+}
+/** Every action key the latest `task.registered` for `task` declared, in order. */
+export declare function registeredActionKeys(records: EventRecord[], task: string): string[];
+/**
+ * The envelope `state:` the log implies for `task`, at instant `ts`.
+ *
+ * ## The rollup rule, stated once
+ *
+ * §6.3's lifecycle is drawn for one action; a task may declare several, so the
+ * projection needs a rule for a task whose actions disagree. It is this, in
+ * order, and the order is the point:
+ *
+ * 1. any action with a live request → **awaiting**. A human owes an answer, and
+ *    that fact outranks every other, because it is the only state that asks
+ *    something of a person.
+ * 2. else any granted action that has not executed → **approved**.
+ * 3. else any action with an `execution.completed` → **executed**.
+ * 4. else **revoked**, then **rejected**, then **expired** — human decisions
+ *    outrank a runtime lapse, so a task with one revoked and one expired action
+ *    reads as revoked, naming the decision a person actually made.
+ * 5. else **proposed**: registered (or not) and nothing has happened.
+ *
+ * A task with exactly one action — the common case — collapses to §6.3's
+ * lifecycle exactly, which is the property the rule was chosen for.
+ *
+ * An unregistered task projects to `proposed`: the log knows of no declaration,
+ * so nothing has been proposed *to the gate* yet. A file claiming `approved`
+ * for a task the log never registered therefore contradicts the log, which is
+ * exactly the reading §6.3 wants.
+ */
+export declare function taskEnvelopeState(records: EventRecord[], task: string, ts: string, ttlMs: number | null): TaskProjection;
+/** One request the TTL sweep would materialise an `approval.expired` for. */
+export interface LapsedRequest {
+    actionKey: string;
+    task: string | null;
+    /** The `ts` of the `approval.requested` that lapsed. */
+    requestedTs: string | null;
+}
+/**
+ * Live requests whose TTL has lapsed and which carry no `approval.expired`.
+ *
+ * Idempotence is structural rather than remembered: the answer is re-derived
+ * from the verified log every sweep, and an action whose expiry has been
+ * appended no longer satisfies the predicate. Two sweeps over the same log
+ * therefore produce the same list, and a sweep that follows a successful one
+ * produces an empty list — with no state carried between them, and no way for a
+ * restarted daemon to expire something twice.
+ *
+ * `ttlMs === null` (a policy that declares no `defaults.approval_ttl`) yields no
+ * candidates at all: nothing lapses when nothing was bounded, and inventing a
+ * deadline is not the daemon's to invent.
+ *
+ * Returned in first-request order, so a sweep's appends land in a deterministic
+ * sequence.
+ */
+export declare function lapsedRequests(records: EventRecord[], ts: string, ttlMs: number | null): LapsedRequest[];
+/**
+ * Why an `envelope.drift` record was written (APRV-63).
+ *
+ * `state-mismatch` is the original reading of SPEC.md §6.3: the file makes a
+ * claim about `state:` and the log implies another one. `envelope-missing` is
+ * the loss case observed live in APRV-60: the log holds a `task.registered` for
+ * the task, and the file that declared it now carries no `approval:` key at all.
+ * They are separated because they call for different human actions — one is an
+ * edit to reconcile, the other is a *deletion to restore* — and a reader who
+ * could not tell them apart would treat a lost envelope as a stale one.
+ *
+ * `reason` is absent from records written before this vocabulary existed;
+ * readers (including {@link driftAlreadyLogged}) treat absence as
+ * `state-mismatch`, which is what every such record was.
+ */
+export declare const DRIFT_REASONS: readonly ["state-mismatch", "envelope-missing"];
+export type DriftReason = (typeof DRIFT_REASONS)[number];
+export { latestRegistration } from "../core/registration.js";
+/** The facts one `envelope.drift` record carries, and the dedupe key. */
+export interface DriftFacts {
+    /** The `state:` the file claims, or `null` when it declares none. */
+    declaredState: string | null;
+    /** The state the log implies (SPEC.md §6.3). */
+    derivedState: EnvelopeState;
+    /**
+     * SHA-256 over the RFC 8785 form of the file's whole `approval:` envelope, or
+     * `null` when the envelope could not be canonicalized. Part of the dedupe key
+     * so that editing a file from one contradiction into a different one is a new
+     * drift and not a suppressed one.
+     */
+    envelopeDigest: string | null;
+    /**
+     * Which kind of drift this is (APRV-63). Part of the dedupe key: a file that
+     * contradicts the log and a file that lost its envelope are different facts
+     * about the same task, and neither may suppress the other. Absent means
+     * `state-mismatch`, matching every record written before the vocabulary
+     * existed.
+     */
+    reason?: DriftReason;
+}
+/**
+ * Has this exact drift already been recorded for `task`?
+ *
+ * The rule: compare against the **latest** `envelope.drift` for the task. Equal
+ * `(reason, declared_state, derived_state, envelope_sha256)` means the situation
+ * the log already describes is the situation now, so nothing is appended. Any
+ * difference
+ * — the human edited the file again, or the log moved and the derived state
+ * changed — is a new fact and is recorded.
+ *
+ * Comparing against the latest record rather than against any record is
+ * deliberate: a task that drifts, is repaired, and drifts the same way again has
+ * genuinely drifted twice, and an audit that collapsed those into one would be
+ * hiding a repetition from the person whose attention this system spends.
+ *
+ * For `envelope-missing` (APRV-63) the same rule reads as: one record per
+ * episode of loss, re-derived every tick from the file and the log rather than
+ * remembered, and a new record when the derived state moves underneath a file
+ * that is still stripped. Its limit is stated where it is felt: a file whose
+ * envelope is restored by hand *in agreement with the log* leaves no record of
+ * the restoration, so a second loss at the same derived state reads as the same
+ * episode and is not appended twice. Recording the restoration would need an
+ * event nobody has specified; detection does not invent one.
+ */
+export declare function driftAlreadyLogged(records: EventRecord[], task: string, facts: DriftFacts): boolean;

package/dist/src/daemon/prune.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Payload retention pruning — the enforcement half of amended SPEC.md §5.2
+ * (APRV-38's vocabulary, APRV-41's daemon).
+ *
+ * > "A payload is prunable once the action it is bound to has been in a terminal
+ * > state (`executed`, `rejected`, `expired`, `revoked`) for longer than the
+ * > duration. A payload whose action is not terminal is never prunable, at any
+ * > age […]. Orphaned payloads (bytes with no recorded binding) are prunable
+ * > regardless of the key. […] Pruning is performed by the daemon and by nothing
+ * > else, and each removal appends a `payload.pruned` event, so a log states what
+ * > its store no longer holds."
+ *
+ * ## Write-ahead, always in that order
+ *
+ * For every file this module removes, the `payload.pruned` event lands in the
+ * log **first** and the `unlink` follows. The ordering is the whole design: a
+ * crash between the two leaves a file on disk that the log already says is gone,
+ * which the next tick completes by unlinking it and appending nothing further
+ * ({@link PrunePlan.completions}). The opposite order would leave the other
+ * failure — bytes deleted with no record of the deletion — which is the one
+ * outcome a store holding the material evidence of what a human approved cannot
+ * afford. Deleting evidence is acceptable; deleting it silently is not.
+ *
+ * Idempotence needs no remembered state: a hash that already carries a
+ * `payload.pruned` event is never given a second one, and the plan is re-derived
+ * from the verified log on every tick.
+ *
+ * ## Terminal time comes from the log, never from the filesystem
+ *
+ * The clock that decides whether retention has elapsed reads the timestamp of the
+ * event that made the action terminal (`execution.completed`, `approval.rejected`,
+ * `approval.revoked`, `approval.expired`). File mtimes are not evidence: they are
+ * rewritten by a copy, a checkout, a backup restore, or an `rsync`, and pruning on
+ * them would let a routine filesystem operation decide when approval evidence
+ * disappears.
+ *
+ * A **lazily** expired request (the TTL has arithmetically lapsed but no
+ * `approval.expired` record exists) is deliberately not terminal here. The
+ * daemon's own TTL sweep appends that event on the same tick; the payload becomes
+ * prunable once the log says so, and retention is then measured from the recorded
+ * moment rather than from one this module computed for itself.
+ *
+ * `execution.failed` is likewise not terminal: a failed action may be retried
+ * against the very bytes in question, and loop escalation (SPEC.md §10.2) exists
+ * precisely because failures recur.
+ *
+ * ## The orphan rule, resolved conservatively (flagged for review)
+ *
+ * §5.2 says orphaned payloads are "prunable regardless of the key", which reads
+ * as though orphans could be swept even with `payload_retention` absent. APRV-41's
+ * acceptance criteria say the absent key means no pruning at all. This module
+ * takes the strictest reading that satisfies both:
+ *
+ * - **`payload_retention` absent: the pruning subsystem does not run.** Nothing is
+ *   deleted, orphan or not, and no `payload.pruned` is appended. Retention is an
+ *   operator's explicit choice to forget, and an operator who never made it never
+ *   asked this runtime to delete anything.
+ * - **`payload_retention` present: orphans are prunable at any age**, which is
+ *   what "regardless of the key" then means — the duration governs bound payloads
+ *   and does not gate residue nothing ever bound.
+ *
+ * An orphan is a file whose hash appears in **no** log record other than a
+ * `payload.pruned` (head-moved residue: the gate stored the bytes, its append was
+ * refused, and no request ever declared them). A hash mentioned by any other
+ * record is bound, and a binding this module cannot attribute to an action key is
+ * treated as live rather than as an orphan — fail closed in both directions.
+ *
+ * ## Nothing else here decides anything
+ *
+ * Which hashes the log already binds, and which it already says are pruned, is
+ * `core/payload-census.ts`'s — the same computation the reporting surfaces read,
+ * so what a reader is shown and what this module would delete can never drift
+ * apart. Approval state per action is `core/state.ts`'s `requestState`; the append is
+ * `core/log.ts`'s `appendEvent` with `expectedHead` (compare-and-append, SPEC.md
+ * §11.1 invariant 5); the unlink is `core/payload-store.ts`'s. The timestamp on
+ * every `payload.pruned` is the runtime's, read from the injected clock at the
+ * write boundary, and the actor is `system:daemon` — a party under oversight must
+ * never be able to author either.
+ */
+import { type Clock } from "../core/clock.js";
+import { type EventRecord } from "../core/log.js";
+/**
+ * SPEC.md §8 and `event.schema.json`: `payload.pruned` carries a `system:` actor.
+ * Declared here rather than imported from `daemon.ts` so the pruner has no
+ * dependency on the loop that calls it.
+ */
+export declare const PRUNE_ACTOR = "system:daemon";
+/** The terminal states of amended SPEC.md §5.2, and nothing beyond them. */
+export type TerminalState = "executed" | "rejected" | "revoked" | "expired";
+/** Why a payload is prunable. Mirrors `payload.pruned`'s `reason`. */
+export type PruneReason = "payload_retention" | "orphaned";
+/** One file the plan says may go, and the evidence for saying so. */
+export interface PruneCandidate {
+    hash: string;
+    reason: PruneReason;
+    /** The action whose terminal state released the bytes; `null` for an orphan. */
+    actionKey: string | null;
+    task: string | null;
+    terminalState: TerminalState | null;
+    /** The `ts` of the event that made it terminal; retention is measured from it. */
+    terminalTs: string | null;
+}
+/**
+ * What one tick would do.
+ *
+ * `completions` are hashes whose `payload.pruned` is already in the log while the
+ * file is still on disk — a crash between the append and the unlink, or a store
+ * that was restored from a backup taken before the prune. They are unlinked and
+ * **no second event is appended**: the log already states the fact.
+ */
+export interface PrunePlan {
+    candidates: PruneCandidate[];
+    completions: string[];
+}
+/**
+ * What may be pruned right now. Pure: no I/O, no clock, no policy loading.
+ *
+ * `retentionMs` is `null` when the policy declares no `payload_retention` — or
+ * when the policy could not be loaded at all, which fails closed to the same
+ * answer. Either way the plan is empty: the subsystem does not run.
+ *
+ * `nowIso` is the evaluation moment, injected. A pruner that read the clock
+ * itself could not be replayed, and retention arithmetic that cannot be replayed
+ * cannot be audited.
+ */
+export declare function planPrune(records: EventRecord[], presentHashes: string[], nowIso: string, retentionMs: number | null): PrunePlan;
+/** Why a prune pass complained. Reported to the caller; never thrown. */
+export type PruneWarningCode = 
+/** The verified read refused, so nothing was planned this pass. */
+"log-unreadable"
+/** A `payload.pruned` append was refused; the file stays, untouched. */
+ | "append-refused"
+/** The event landed but the file could not be removed. The next tick retries. */
+ | "unlink-failed";
+export interface PruneWarning {
+    code: PruneWarningCode;
+    message: string;
+}
+/**
+ * One prune that completed: the event landed AND the bytes went (APRV-57).
+ *
+ * Reported separately from {@link PruneReport.appended} because only these carry
+ * a `seq` and only these are finished. A candidate whose append landed and whose
+ * unlink FAILED appears in `appended` and in `warnings`, never here: the store
+ * still holds the bytes, and a success line for it would say otherwise.
+ *
+ * Crash-window completions ({@link PrunePlan.completions}) are absent for the
+ * opposite reason: they append nothing, so there is no record for a `seq` to
+ * name, and the log said the file was gone on some earlier tick already.
+ */
+export interface PrunedRecord {
+    candidate: PruneCandidate;
+    /** `seq` of the appended `payload.pruned` record. */
+    seq: number;
+}
+export interface PruneReport {
+    /** `payload_retention` in milliseconds, or `null` when the subsystem is off. */
+    retentionMs: number | null;
+    /** Hashes for which a `payload.pruned` was appended this pass. */
+    appended: PruneCandidate[];
+    /** Appended-and-unlinked prunes, with the seq of each event (APRV-57). */
+    pruned: PrunedRecord[];
+    /** Hashes whose file was removed (appended-then-unlinked, plus completions). */
+    removed: string[];
+    /** Crash-window files finished without a second event. */
+    completed: string[];
+    warnings: PruneWarning[];
+}
+export interface PruneOptions {
+    /** The append-only log. Re-read before every append. */
+    logPath: string;
+    /** The payload store. Defaults to the store beside `logPath`. */
+    storeDir?: string;
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    schemaDir?: string;
+    /** The write-boundary clock (amended SPEC.md §8). Tests inject; production does not. */
+    clock?: Clock;
+}
+/**
+ * Read `payload_retention` from the policy in force right now.
+ *
+ * Fails closed to `null` exactly as the daemon's TTL read does: a policy that
+ * cannot be loaded declares no retention, so nothing is pruned on its behalf. An
+ * unparseable duration is likewise `null` — the schema's duration pattern makes
+ * that unreachable through a validated policy, and a retention rule this module
+ * cannot read is not one it may guess at.
+ */
+export declare function retentionMsOf(policy: {
+    dir?: string;
+    file?: string;
+}, schemaDir?: string): number | null;
+/**
+ * One pruning pass: plan, append, unlink, repeat.
+ *
+ * The log is re-read before each append rather than once for the pass, because
+ * each append moves the head the next one is compared against and because a CLI
+ * verb may have appended in between. `expectedHead` therefore always names the
+ * head the decision was made from; a `head-moved` refusal drops the candidate and
+ * the next tick re-derives it.
+ *
+ * Nothing is retried in place, and no state survives the call.
+ */
+export declare function prunePayloads(options: PruneOptions): PruneReport;