approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,466 @@
+/**
+ * The daemon's log advance, on a cadence and through the gate (APRV-204).
+ *
+ * ## Why the daemon does this at all
+ *
+ * The committed log is this project's truth, and until this module its
+ * freshness depended on somebody remembering to run `approval log advance`. The
+ * daemon is already the committed log's sole writer in the primary checkout, it
+ * is already awake, and since the seq 7413 ceremony `log.advance` resolves
+ * `supervised-live 0.1` — a class that needs no hand on the keyboard for nine
+ * runs in ten. So the bookkeeping moves here, and the human's part shrinks to
+ * the tenth run and the merge.
+ *
+ * ## It borrows every mechanism and owns none
+ *
+ * - The advance itself is `cli/log-advance.ts`'s `logAdvance`, called
+ *   unmodified: the same append lock, the same chain verify, the same staged-set
+ *   refusal, the same commit-on-the-remote-without-a-checkout. A second
+ *   implementation would be a second thing to get wrong about the one file
+ *   nothing may rewind.
+ * - The authorization is `core/gate.ts`'s `register` + `request` and
+ *   `core/execute.ts`'s `startExecution` / `finishExecution`, in that order and
+ *   with no shortcuts. The daemon proposes as `agent:daemon` and the runtime
+ *   decides, exactly as it decides for a session.
+ * - The cadence and the reporting are the only decisions here, and neither
+ *   touches the log.
+ *
+ * ## What happens when the gate says no
+ *
+ * A `supervised-live` draw that SELECTS this advance, a class amended to
+ * `manual`, a policy that will not load: all three end the attempt with nothing
+ * committed and nothing pushed. The outcome is reported on the daemon's event
+ * stream and readable afterwards from the log itself, and the next tick tries
+ * again — after the cadence interval, never immediately, because the
+ * last-attempt clock is set by a refusal exactly as it is by a success. There
+ * is no retry loop and no backoff ladder: the cadence IS the backoff.
+ *
+ * ## The merge: armed here, performed by nobody (APRV-284)
+ *
+ * This file still calls no merge. What it does is ask `logAdvance` to ARM one:
+ * `gh pr merge <branch> --merge --auto` on the day's records pull request, so
+ * the pull request lands when its checks and the repository's branch rules say
+ * it may, and never earlier. Before APRV-284 it sat at CLEAN until a person
+ * clicked, which is the failure mode CLAUDE.md's workflow item 7 is written
+ * against — and clicking was never a review, because a records branch carries
+ * only the log, `QUEUE.md` and `.approval/payloads/`, the three paths CI's
+ * protected-path guard exempts.
+ *
+ * Two things keep that from being a daemon approving its own evidence. The arm
+ * is `vcs.push.main` in this project's taxonomy — the same class as the same
+ * command in a session's hands — and it rides the SAME `log.advance`
+ * authorization this cycle already holds rather than opening a second question
+ * or claiming a second grant: one authorization, one act. And `cli/log-advance.
+ * ts`'s `armAutoMerge` withholds the arm outright when the branch it pushed
+ * carries a path an advance may not carry, so what gets armed is only ever
+ * evidence. `--no-advance-auto-merge` turns the whole thing off.
+ *
+ * ## The self-perpetuation trap, and how the trigger avoids it
+ *
+ * One advance cycle appends three records of its own (`task.registered`,
+ * `execution.started`, `execution.completed`). Two of them land before the
+ * commit and ride it; the third lands after, so every successful advance leaves
+ * the log one record ahead of the records branch. A trigger that counted those
+ * would advance forever on an idle repository. So the TRIGGER counts only
+ * records that are not an advance's own bookkeeping (`PublishedState.substantive`),
+ * while the count REPORTED to an operator is the honest raw one.
+ *
+ * ## Where the pieces live
+ *
+ * The cycle's vocabulary (the actor, the class, the task and key shapes, and
+ * reading the last cycle back out of the log) is `core/advance-cycle.ts`, and
+ * the git-side "what is already published" question is `cli/log-advance.ts`.
+ * Both are shared with `approval doctor`, which reports the same numbers in a
+ * different process — and a CLI module may not import the daemon.
+ */
+import { type Clock } from "../core/clock.js";
+import { type DanglingAdvance } from "../core/advance-cycle.js";
+import { type FailureReason } from "../core/execute.js";
+import type { EventRecord } from "../core/log.js";
+import { type AutoMergeState } from "../cli/log-advance.js";
+/**
+ * How often the daemon advances, absent the record-count trigger: 15 minutes.
+ *
+ * Chosen against what a records pull request costs and what staleness costs. A
+ * shorter interval publishes a pull request whose diff is a handful of lines
+ * and burns a CI run for each; a longer one leaves the guards that read the
+ * committed log (the CI protected-path cross-check especially) looking at a log
+ * that is hours behind the decisions it is supposed to evidence.
+ */
+export declare const DEFAULT_ADVANCE_INTERVAL_MS = 900000;
+/**
+ * How many unpublished records force an advance before the interval elapses: 20.
+ *
+ * The busy-hour case. Twenty records is a few minutes of an active session, and
+ * a records branch that far behind is a records branch a person starts doing
+ * arithmetic against.
+ */
+export declare const DEFAULT_ADVANCE_AFTER_RECORDS = 20;
+/** The cadence, as the daemon is configured with it. */
+export interface AdvanceCadence {
+    /** Minimum time between attempts, successful or not. */
+    intervalMs: number;
+    /** Attempt as soon as this many substantive records are unpublished. */
+    afterRecords: number;
+    remote: string;
+    /** The remote branch the first advance of a day is parented on. */
+    base: string | null;
+    /** Open or update the day's pull request. */
+    pr: boolean;
+    /**
+     * Arm auto-merge on that pull request (APRV-284). Read only when `pr` is set.
+     */
+    autoMerge: boolean;
+}
+/** The default cadence, spelled once. */
+export declare function defaultCadence(): AdvanceCadence;
+/**
+ * How an attempt ended. Machine-readable and closed (SPEC.md §11.1 invariant 6).
+ *
+ * - `advanced` — records were committed and pushed.
+ * - `nothing-owed` — the records branch already carries every record.
+ * - `gated` — the gate sent this advance to a human (the live draw selected it,
+ *   or the class resolves `manual`). Nothing was committed.
+ * - `refused` — the gate refused it outright (unattested policy, an escalated
+ *   task, a `human-only` class, a budget). Nothing was committed.
+ * - `failed` — the advance itself did not complete (a rejected push, a diverged
+ *   remote, an unreadable index). The failure is recorded as an
+ *   `execution.failed`.
+ */
+export type AdvanceOutcome = "advanced" | "nothing-owed" | "gated" | "refused" | "failed";
+/** One attempt, as the daemon reports it and as a status reader recovers it. */
+export interface AdvanceAttempt {
+    outcome: AdvanceOutcome;
+    /** The runtime's own clock reading, taken once at the top of the attempt. */
+    ts: string;
+    /** Records not yet on a records branch, counted honestly (bookkeeping included). */
+    recordsPending: number;
+    recordsBranch: string | null;
+    commit: string | null;
+    prUrl: string | null;
+    /** True when this attempt OPENED the day's pull request rather than updating it. */
+    prCreated: boolean;
+    /**
+     * What became of the auto-merge arm (APRV-284), or `null` when no pull
+     * request step ran. `cli/log-advance.ts`'s `AutoMergeState` documents each.
+     */
+    autoMerge: AutoMergeState | null;
+    /** Why the arm was withheld or refused; `null` when it was not. */
+    autoMergeNote: string | null;
+    range: {
+        from: number;
+        to: number;
+    } | null;
+    /** The refusal code, for every outcome that carries one. */
+    code: string | null;
+    message: string;
+    /**
+     * True when the day's records branch was REBUILT on the base rather than
+     * stacked on its own tip (APRV-234), and the ref it was rebuilt on.
+     */
+    rebuilt: boolean;
+    rebuiltOn: string | null;
+    /**
+     * The outcome this attempt observed and could NOT record (APRV-233).
+     *
+     * `null` in the ordinary case, where `execution.completed` or
+     * `execution.failed` landed. Non-null when the bounded head-moved retry was
+     * spent and the execution is therefore left open: the advance's effect has
+     * happened, this process knows how it ended, and the log does not yet. The
+     * daemon carries it to the next tick and settles it there
+     * ({@link settleAdvanceFinish}) before it evaluates any trigger, which is
+     * what stops a lost outcome record from reading as "no advance yet".
+     */
+    pendingFinish: PendingAdvanceFinish | null;
+}
+/**
+ * An advance outcome that happened and is not yet in the log (APRV-233).
+ *
+ * Every field is an OBSERVATION this runtime made, carried forward verbatim: a
+ * later tick appends exactly the record the failing one would have appended.
+ * Nothing here is re-derived and nothing is guessed — a dangling execution
+ * whose outcome this process does not hold stays dangling for a human, exactly
+ * as `core/execute.ts` says it must.
+ */
+export interface PendingAdvanceFinish {
+    actionKey: string;
+    exitCode: number;
+    reason?: FailureReason;
+    note?: FailureReason;
+}
+/** What {@link attemptAdvance} needs. Everything is injected; nothing is ambient. */
+export interface AdvanceInput {
+    logPath: string;
+    /** The working directory the advance runs in: the primary checkout. */
+    cwd: string;
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    schemaDir?: string;
+    clock?: Clock;
+    cadence: AdvanceCadence;
+    /** The day the records branch is named for. Injected by tests. */
+    today?: string;
+    /**
+     * The child that runs the git side effect for {@link runAdvanceAsync}, when
+     * something other than this module's own runner should run it (APRV-211).
+     *
+     * A test seam and nothing else: production spawns `daemon/advance-child.js`
+     * under `process.execPath`. It exists because the property AC7 pins — a tap
+     * answered while an advance is in flight — needs an advance that stays in
+     * flight for longer than a real one does, and the alternative (making the
+     * daemon's own git work slow to order) would put test-only branches on the
+     * path that publishes the log.
+     */
+    runner?: {
+        command: string;
+        args: readonly string[];
+    };
+    /**
+     * How many times the outcome record is re-derived against a moved head
+     * (APRV-233). Clamped to 1..`core/head-retry.ts`'s `HEAD_MOVED_ATTEMPTS` by
+     * that module's own `attemptsOf`, and downward only.
+     *
+     * The seam a test uses to pin BOTH shapes with one harness, exactly as
+     * `GateOptions.retryOnHeadMoved` does for the harness writers: `1` is the
+     * pre-APRV-233 writer, whose lost race left the execution dangling. A caller
+     * may ask for less tolerance of a moved head, never for more; ambiguity — a
+     * zero, a fraction, a negative, a larger number — resolves to the runtime's
+     * own value rather than the caller's.
+     */
+    retryOnHeadMoved?: number;
+    /**
+     * The other half of that seam (APRV-261), forwarded to the finish path as
+     * `FinishOptions.afterRead`: a callback fired between one attempt's read and
+     * its append, which is where a test puts the record that moves the head.
+     *
+     * `retryOnHeadMoved` pins how hard the writer tries; this pins that it has to
+     * try at all. Together they let one harness drive both shapes with no
+     * sleeping anywhere: the pre-APRV-233 writer at `1`, and the retried writer
+     * at the default. Production sets neither.
+     */
+    afterFinishRead?: () => void;
+}
+/** The argv the payload binds to: the verb this attempt is authorization for. */
+export declare function advanceArgv(cadence: AdvanceCadence): string[];
+/**
+ * The half of an attempt that talks to the gate, with nothing committed yet.
+ *
+ * Split out in APRV-211 so the two halves can run in different places: the
+ * authorization stays in the DAEMON's own process, where the launch environment
+ * carries the sampling secret the `supervised-live` draw needs and where the
+ * append lock is held for milliseconds, while the git side effect may move to a
+ * child (`runAdvanceAsync`) whose environment is scrubbed of exactly that
+ * secret (`core/child-env.ts`). Authorization is fast and must be trusted;
+ * `git fetch` + `git push` + `gh pr create` is slow and needs no trust at all.
+ */
+export type AdvanceAuthorization = {
+    authorized: false;
+    attempt: AdvanceAttempt;
+} | {
+    authorized: true;
+    /** The clock reading the attempt was opened with. */
+    ts: string;
+    today: string;
+    root: string;
+    recordsBranch: string;
+    /** The key the execution was started under: the one the human answered. */
+    actionKey: string;
+    recordsPending: number;
+    /**
+     * True when this authorization rode a decision an EARLIER tick asked for
+     * rather than one this tick opened. Reported so an operator reading the
+     * event stream can tell "the human just said yes" from "the human said
+     * yes at 11:04 and this is the tick that spent it".
+     */
+    adopted: boolean;
+};
+/**
+ * Close an execution whose outcome an EARLIER tick observed and could not
+ * record (APRV-233).
+ *
+ * The second half of the fix, and the one that matters after a restart of the
+ * loop rather than of the process: the outcome is carried in memory as a
+ * {@link PendingAdvanceFinish} and re-attempted here, on the fresh head,
+ * before the next tick evaluates any trigger. It appends the same record the
+ * failed attempt would have appended, through the same bounded retry.
+ *
+ * `already-finished` is a SUCCESS here: something (a concurrent settle, a
+ * human's `approval execution resolve`) closed the cycle in the meantime, the
+ * log holds an outcome, and there is nothing left to carry.
+ */
+export declare function settleAdvanceFinish(input: AdvanceInput, pending: PendingAdvanceFinish): {
+    ok: boolean;
+    code: string | null;
+    message: string;
+};
+/**
+ * Every open advance cycle, with what this checkout's refs prove (APRV-264).
+ *
+ * One `publishedState` for the whole list rather than one per key: it is the
+ * git read on the tick's hot path, and the answer it gives is the same for
+ * every key — the highest published seq, and the ref that carries it.
+ *
+ * Read from the log rather than from this process's memory, so a daemon that
+ * restarted still sees that an advance HAPPENED. It is the fact the cadence was
+ * missing on 2026-09-02: with no outcome record, nothing but an in-process
+ * clock said the branch had just been pushed.
+ */
+export declare function proveDanglingAdvancesFor(input: AdvanceInput, records: readonly EventRecord[]): DanglingAdvance[];
+/** One key the sweep closed, or could not. */
+export interface SweptAdvance {
+    actionKey: string;
+    /** The ref that proved it, on a settled entry. */
+    provenBy: string | null;
+    message: string;
+}
+/** What one sweep did, and what it left for a person (APRV-264). */
+export interface AdvanceSweep {
+    /** Cycles this sweep closed, in log order, each with the ref that proved it. */
+    settled: SweptAdvance[];
+    /**
+     * Cycles nothing in this checkout can prove, plus the ones whose append was
+     * refused. Both are a person's now, and both block a new advance.
+     */
+    outstanding: SweptAdvance[];
+}
+/** Is this sweep's work done — nothing open, nothing owed to a person? */
+export declare function sweepIsClear(sweep: AdvanceSweep): boolean;
+/**
+ * Close EVERY dangling advance cycle whose outcome the git refs still show
+ * (APRV-233, widened by APRV-264).
+ *
+ * ## The loop this breaks
+ *
+ * From Carter's terminal, 2026-09-02, with the APRV-211 build running: tick two
+ * advanced and pushed; its `execution.completed` lost the head race (expected
+ * 14874, found 14875) and `daemon-log-advance-1-14871` was left open. Tick
+ * three's authorization then reached `startExecution` on that same key and was
+ * refused `already-executed: an idempotency key is single-use and nothing here
+ * reconciles or reruns it` — which is the gate saying, correctly, that
+ * somebody has to close the books. Nobody did, so the span moved and the daemon
+ * pushed again, and again, every ninety seconds under a fifteen-minute
+ * interval.
+ *
+ * ## Why it sweeps rather than reconciles one
+ *
+ * APRV-233's version closed the LAST open cycle and returned. On 2026-09-05
+ * that was not enough: `approval status` listed FIVE, left by the 2026-09-02
+ * loop and by the restarts after it, the daemon refused one advance per tick
+ * naming one key each, and Carter closed all five by hand with five
+ * near-identical commands. One key per tick is a repair rate of one every
+ * thirty seconds behind a refusal that stops the cadence entirely, so the sweep
+ * takes every key it can prove in one pass and reports the rest together.
+ *
+ * ## What is and is not a guess here
+ *
+ * {@link settleAdvanceFinish} covers the case this process still holds the
+ * outcome for. This covers the other one — cycles left open by an earlier
+ * process, or by ticks whose memory of them is gone — and it closes each only
+ * on EVIDENCE: the records the cycle was authorized to publish are demonstrably
+ * on a records branch, read from git's own object store through the same
+ * `publishedState` the cadence and the doctor row read. When the evidence is
+ * there the outcome is recorded as the completion it was, with a note saying
+ * which ref proved it and that the RUNTIME observed it. When it is NOT there,
+ * nothing is written: the execution stays open for a person, the daemon warns
+ * once, and no new advance is started over work nobody has accounted for. A
+ * false `execution.failed` for an advance that actually published would be
+ * worse than the dangling record.
+ *
+ * The actor is {@link ADVANCE_ACTOR} and the record carries no
+ * `attested_by_human`: human attestation is for what a person went and looked
+ * at, and this is the runtime reading its own refs. The note says so in as many
+ * words, so no reader has to infer it from the actor field alone.
+ *
+ * This is a deliberate, narrow carve-out to `core/execute.ts`'s rule that
+ * nothing closes a dangling execution automatically. Narrow because it closes
+ * only executions THIS runtime started, for its own `log.advance` cycles, whose
+ * entire effect is a git ref this runtime can look at and did.
+ */
+export declare function sweepDanglingAdvances(input: AdvanceInput, records: readonly EventRecord[]): AdvanceSweep;
+/**
+ * The refusal that stands while any advance cycle is open, naming all of them.
+ *
+ * One sentence for every outstanding key rather than one refusal per key per
+ * tick: the operator's next act is the same command whichever key they read
+ * first, so the command is on the line and every key it will close is under it.
+ */
+export declare function unreconciledRefusal(keys: readonly string[]): string;
+/**
+ * Register, request, start. The authorization, and not one byte of side effect.
+ *
+ * The order is the whole point and none of it is optional: nothing is committed
+ * before the gate has answered, and nothing the gate answered for goes
+ * unrecorded. `execution.started` is appended BEFORE the advance runs, so the
+ * commit the advance builds carries the record of its own authorization; the
+ * `execution.completed` that follows lands after the commit and is published by
+ * the next advance, which is why the trigger discounts it.
+ *
+ * ## What APRV-211 changed: the tick asks the log what it already asked
+ *
+ * Observed live on 2026-09-02: three ticks over ONE owed advance put three
+ * questions on Carter's phone, because the idempotency key embedded the log
+ * HEAD and the head moved with each gated attempt's own two records. Two things
+ * fix it and both are here.
+ *
+ * 1. The key and the payload span end at `substantiveSeq` — the last unpublished
+ *    record that is not an advance cycle's own bookkeeping — so a tick that
+ *    appended only its own question computes the SAME key and the SAME hash.
+ * 2. Before it registers anything, the tick reads {@link openAdvanceRequest}.
+ *    A question still open is ADOPTED (nothing is appended, the outcome is
+ *    `gated`, and the human keeps the one question they already have); a grant
+ *    on it is SPENT (straight to `startExecution` on that key, with the hash
+ *    that key declared, so the single-use rule the log already enforces makes
+ *    one decision authorise exactly one advance); a terminal answer on the
+ *    CURRENT owed span is HONOURED (`advance-decided`, and nothing is asked
+ *    again until the span itself changes).
+ */
+export declare function authorizeAdvance(input: AdvanceInput, records: readonly EventRecord[]): AdvanceAuthorization;
+/**
+ * The advance, on this stack, start to finish. The shutdown flush's path.
+ *
+ * Kept synchronous deliberately: `finish()` runs inside the daemon's shutdown,
+ * where there is no loop left to return to and an advance that settled after
+ * the process exited would be an advance nobody recorded.
+ */
+export declare function runAdvanceSync(input: AdvanceInput, auth: Extract<AdvanceAuthorization, {
+    authorized: true;
+}>): AdvanceAttempt;
+/**
+ * The advance, with the git work in a child, so this loop keeps answering.
+ *
+ * ## Why a child rather than an `await`
+ *
+ * The second half of the 2026-09-02 incident: `answerCallbackQuery: HTTP 400`,
+ * over and over, around the grants. Telegram drops a callback query that is not
+ * answered inside its window, and `approval up` runs the channel listener and
+ * the daemon in ONE process on ONE loop. `logAdvance` is `spawnSync` from end to
+ * end — `git fetch`, a scratch-index commit, `git push`, `gh pr create` — so
+ * every tap that arrived during an advance waited for the push to finish, and
+ * the human got a button that never toasted. A promise would not have helped:
+ * synchronous work does not yield no matter what it is wrapped in. Only another
+ * process does.
+ *
+ * ## What does NOT move
+ *
+ * The gate work. `core/child-env.ts` strips `APPROVAL_*` from a child's
+ * environment (APRV-205), and the `supervised-live` draw's secret is exactly
+ * such a variable, so a child that asked the gate would be a child that could
+ * not draw and would fail closed on every tick. Authorization happens in
+ * {@link authorizeAdvance}, in this process, before the child is spawned;
+ * {@link recordFinish} closes the execution in this process, after it settles.
+ * The child gets one job — the git side effect — and no authority whatsoever.
+ * It never touches the log: it cannot append, and everything it says comes back
+ * as one JSON line on its stdout.
+ */
+export declare function runAdvanceAsync(input: AdvanceInput, auth: Extract<AdvanceAuthorization, {
+    authorized: true;
+}>): Promise<AdvanceAttempt>;
+/**
+ * Register, request, start, advance, finish. One attempt, on this stack.
+ *
+ * The whole cycle for a caller that has no loop to protect: the shutdown flush,
+ * `--once`, and every test that asserts on what one tick did.
+ */
+export declare function attemptAdvance(input: AdvanceInput, records: readonly EventRecord[]): AdvanceAttempt;

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

@@ -0,0 +1,87 @@
+/**
+ * The daemon's audit-sampling sweep (SPEC.md §10.2: "samples supervised actions
+ * for audit").
+ *
+ * `daemon/daemon.ts` calls {@link sweepAuditSampling} once per tick and nothing
+ * else. The scheduling question — when to look — is the daemon's; every other
+ * question is answered in `core/audit.ts` and `core/sampler.ts`, which is the
+ * same division the drift scan and the TTL sweep already follow: the daemon
+ * decides nothing of its own.
+ *
+ * ## Why the sweep is idempotent without remembering anything
+ *
+ * `core/audit.ts` re-derives the candidate set from the verified log every call
+ * and subtracts the subjects already sampled. A tick that samples nothing new is
+ * the normal case; a restarted daemon, a second daemon, and an operator running
+ * a sweep by hand all converge on exactly the same set. This module therefore
+ * holds no state at all — no seen-set, no cursor, no cache.
+ *
+ * ## Reporting, and why it goes through `warning`
+ *
+ * The sweep reports failures through the daemon's existing `warning` channel.
+ * Successful samples were originally left implicit, visible only as `QUEUE.md`'s
+ * sampled-audit backlog and the `rendered` event's `audit_backlog` growing later
+ * in the same tick, which is what let APRV-40 leave `DaemonEvent` untouched.
+ * APRV-57 grew that union additively, so a sample now also reports through the
+ * optional {@link AuditSweepOptions.sampled} sink, which the daemon renders as
+ * its `sampled` line. Both channels remain the caller's: this module names no
+ * event and writes to no stream.
+ *
+ * ## A disabled sampler is not a failure
+ *
+ * When no sampling secret is configured, `core/sampler.ts` returns a disabled
+ * sampler with a machine-readable reason. That is a standing configuration fact,
+ * not an error, so it is NOT routed through the failure channel: a warning that
+ * fires every tick for something the operator chose is noise that trains them to
+ * scroll past the channel that also carries real refusals. It is reported
+ * instead through the optional {@link AuditSweepOptions.notice} sink (once per
+ * reason per process), and standingly by `approval status`, which is where an
+ * operator goes to ask what is switched on. See `core/sampler.ts` for why an
+ * unconfigured sampler disables sampling rather than escalating everything.
+ */
+import { type SampleAppended } from "../core/audit.js";
+import type { Clock } from "../core/clock.js";
+import type { SamplerDisabledReason } from "../core/sampler.js";
+/** What the daemon hands the sweep. Everything is injected; nothing is ambient. */
+export interface AuditSweepOptions {
+    logPath: string;
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    /** Reported relative to this, and the fallback policy directory. */
+    cwd: string;
+    schemaDir?: string;
+    /** The write-boundary clock (amended SPEC.md §8). */
+    clock?: Clock;
+    /** Environment the sampling secret is read from. Injected by tests. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * One FAILURE line: an append the sampler could not make, or a log it could
+     * not read. Mapped by the caller onto its own warning vocabulary.
+     */
+    warn(message: string): void;
+    /**
+     * One CONFIGURATION line: sampling is switched off and here is why. Optional,
+     * and the daemon does not pass it — see the module header. `approval status`
+     * reports the same fact standingly, from the same resolver.
+     */
+    notice?(message: string): void;
+    /**
+     * One SUCCESS line per `audit.sampled` appended (APRV-57). Optional, and
+     * injected exactly as {@link AuditSweepOptions.warn} is, so the sweep still
+     * reports in the caller's vocabulary and owns no output of its own.
+     */
+    sampled?(sample: SampleAppended): void;
+}
+export interface AuditSweepSummary {
+    /** How many `audit.sampled` events this sweep appended. */
+    sampled: number;
+    /** `null` when sampling ran; the reason when it did not. */
+    disabled: SamplerDisabledReason | null;
+}
+/** Reset the once-per-process notice. Exported for tests, used nowhere else. */
+export declare function resetAuditSweepNotices(): void;
+/** One sampling sweep. Appends through `core/audit.ts` and decides nothing. */
+export declare function sweepAuditSampling(options: AuditSweepOptions): AuditSweepSummary;