approval-md 0.1.0 → 0.3.0

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;