approval-md 0.1.0 → 0.2.0

package/dist/src/daemon/dark-session.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The dark-session sweep (APRV-192): the appending half, and only that.
+ *
+ * `core/dark-session.ts` observes git, resolves the payload store and reaches
+ * the verdict. This module does the one thing a reader must not: it writes the
+ * observation down. The split is not decorative — `approval doctor` reports the
+ * same findings from the same evaluator and must append nothing, and CLAUDE.md
+ * names the daemon as the log's single writer.
+ *
+ * ## What it appends, and what it deliberately does not
+ *
+ * A `dark` verdict appends one `audit.dark_session` (SPEC.md §8's event set,
+ * amended APRV-192), actor `system:daemon`, through `appendEvent` with
+ * `expectedHead` (§11.1 invariant 5) and a `ts` read from the injected clock at
+ * the write boundary (§11.1 invariant 2). The daemon records what IT saw, as
+ * itself; it never writes a record on behalf of the session it is reporting on,
+ * which would be fabricating exactly the evidence whose absence is the finding.
+ *
+ * An `undetermined` verdict appends NOTHING. It is reported on the daemon's
+ * event stream, as a warning, and by `approval doctor`, which is where an
+ * operator goes to ask what the runtime cannot see. The reasoning is the one
+ * `daemon/audit.ts` gives for a disabled sampler: a condition that recurs every
+ * tick and that nobody can act on from the record alone is noise, and a log full
+ * of "I could not tell" is a log people stop reading. Fail-closed binds the
+ * REPORT — an undetermined subject never counts as a pass and never clears
+ * `settled` — and not the append.
+ *
+ * ## Idempotent without remembering anything
+ *
+ * Same discipline as the audit sweep: no cursor, no seen-set, no state. Each
+ * finding carries an observation key (subject plus the state of the world it was
+ * seen in), and a key the verified log already carries is not appended again.
+ * A restarted daemon, a second daemon and an operator running a sweep by hand
+ * all converge on the same set, and a worktree that stays dark across a hundred
+ * ticks produces one record until it commits something new.
+ */
+import { type DarkSessionFinding, type DarkSessionReport, type DarkSessionSweepOptions } from "../core/dark-session.js";
+export type { DarkSessionSweepOptions, DarkSessionWatch } from "../core/dark-session.js";
+export { DEFAULT_DARK_INTERVAL_MS, DEFAULT_DARK_WINDOW_MS, reportDarkSessions, } from "../core/dark-session.js";
+/**
+ * SPEC.md §8: runtime-originated events carry a `system:` actor, and the daemon
+ * is the runtime. The same actor `envelope.drift` is written under, because the
+ * same process observed both.
+ */
+export declare const DARK_SESSION_ACTOR = "system:daemon";
+export interface DarkSessionSweepResult {
+    report: DarkSessionReport;
+    /** Findings that produced a new `audit.dark_session`, with its seq. */
+    appended: readonly {
+        finding: DarkSessionFinding;
+        seq: number;
+    }[];
+    /** Dark findings whose observation key the log already carried. */
+    repeated: readonly DarkSessionFinding[];
+    /** Findings that could not be established, with their codes. */
+    undetermined: readonly DarkSessionFinding[];
+    /** Appends that were refused, as messages for the caller's warning channel. */
+    refusals: readonly string[];
+}
+/**
+ * One sweep: observe, judge, append what is new. Decides nothing of its own —
+ * the verdict is `core/dark-session.ts`'s and the evidence rule is APRV-151's.
+ */
+export declare function sweepDarkSessions(options: DarkSessionSweepOptions): DarkSessionSweepResult;

package/dist/src/daemon/draw-child.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The live draw's relay child (APRV-208).
+ *
+ * ## Why a child process exists at all
+ *
+ * `core/gate.ts`'s request path is synchronous from end to end — `request`
+ * returns a value, the hook's wait loop sleeps synchronously — and Node has no
+ * synchronous Unix-socket client. APRV-188 hit the same wall and answered it
+ * with a published file, because the thing it needed (the log's verified head)
+ * is a fact the daemon can publish in advance. A live draw is not: the question
+ * contains bytes that did not exist when the daemon last woke up. It has to be
+ * asked.
+ *
+ * So: one `spawnSync` of this file, about 20-40 ms of Node start, paid only by a
+ * `supervised-live` class in a process with no sampling secret. It is off the
+ * pass-through path entirely.
+ *
+ * ## What it is allowed to do
+ *
+ * Open a socket, write one line, read one line, print it. That is the whole
+ * remit, and it is written to be worth nothing if it were replaced wholesale:
+ * it holds no secret, appends nothing, decides nothing, and the parent
+ * VALIDATES every field of what it relays (`core/live-draw.ts`'s
+ * `parseDrawAnswer`) rather than trusting it. A hostile relay can refuse to
+ * answer — which gates the action, which is the safe direction — and can put
+ * nothing past the parent that the daemon's MAC does not cover.
+ *
+ * ## The protocol
+ *
+ * `argv[2]` is the socket path. stdin is one JSON line, the question. stdout is
+ * one JSON line: `{"ok":true,"answer":{...}}` verbatim from the daemon, or
+ * `{"ok":false,"reason":"...","detail":"..."}` with one of
+ * `core/live-draw.ts`'s refusal reasons. Exit code is always 0: the parent
+ * reads the line, not the status.
+ */
+export {};

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

@@ -0,0 +1,154 @@
+/**
+ * The daemon's live-draw server (APRV-208).
+ *
+ * The daemon is the one process on this machine that legitimately holds the
+ * sampling secret: an operator starts it in a terminal where `eval "$(approval
+ * env)"` has run, and `core/child-env.ts` (APRV-205) strips `APPROVAL_*` from
+ * every child it spawns, so the secret goes no further. This module lets short
+ * lived gate processes that hold no secret — the harness hook, above all — ASK
+ * for a draw instead of failing closed on every action of a `supervised-live`
+ * class. `core/live-draw.ts` carries the protocol and the argument; this is the
+ * server half.
+ *
+ * ## Three things this server refuses to take on the asker's word
+ *
+ * 1. **The action.** It answers only for an `action_key` already carried by a
+ *    `task.registered` record in the VERIFIED log, declaring exactly this
+ *    `payload_hash`. That is what stops the socket being a private oracle: an
+ *    agent that wants to grind candidate payloads until one draws unsampled must
+ *    append a registration for each candidate first, in the append-only log,
+ *    where the attempt is permanent and countable. See `core/live-draw.ts`'s
+ *    header on why this matters more than the socket's file mode does.
+ * 2. **The rate.** It resolves the action's class against its own policy and
+ *    uses the `live_rate` IT derives. A `live_rate` in the question is a
+ *    proposal, never an instruction; the derived one is echoed back and the
+ *    asker refuses an answer to a different question.
+ * 3. **The policy.** Same: it checks its own attestation and echoes its own
+ *    `policy_sha256`. A daemon and a hook reading different policy files fail
+ *    closed rather than agreeing on the wrong rules.
+ *
+ * A fresh verified read per question is what makes (1) usable at all: the hook
+ * registers the task microseconds before it asks, and a daemon answering out of
+ * a tick's stale memory would refuse every real request. The read is cheap for
+ * the reason APRV-188 exists — the daemon's cache is warm and only the appended
+ * tail is walked.
+ *
+ * ## The secret
+ *
+ * Held in one private field, closed over by nothing, and never emitted: not in
+ * an answer, not in a warning, not in the `started` line. What leaves this
+ * process is a verdict and a MAC.
+ */
+import { type LiveSelectorUnavailableReason } from "../core/sampler.js";
+/**
+ * The server this environment can run, or the reason it cannot (APRV-208).
+ *
+ * ## Where the secret comes from, and why that is the whole opt-in
+ *
+ * From the daemon's OWN environment, and nowhere else. `.approval/env` is a
+ * source MAP and `core/env-file.ts`'s load-bearing rule is that no verb reads it
+ * into its own environment (the reason is `APPROVAL_HUMAN`: a working-tree file
+ * that could set identity would put the human-only gate one `echo >>` away from
+ * being nobody's gate). That rule is not weakened here. The operator runs `eval
+ * "$(approval env)"` in the terminal they start the daemon from — the same act
+ * `approval setup sampling` already documents, resolving the keychain item or the
+ * env file's declared source — and this reads what that established.
+ *
+ * That act is also the feature's opt-in, which is why there is no flag to turn
+ * it on. Serving draws changes VERDICTS: a class an operator declared
+ * `supervised-live` at 0.1 goes from gating 100% to gating 10%, and a default
+ * that moved that under someone on an upgrade would be the surprise this project
+ * exists to prevent. But it moves only for an operator who has exported the
+ * secret into the daemon's shell on purpose, having already amended their policy
+ * to declare the class live. Both halves are deliberate acts by the human. What
+ * exists instead is a way OUT — `approval daemon run --no-draw` — because the
+ * one thing an operator must always be able to do is take a control back.
+ */
+export declare function drawServerFor(options: Omit<DrawServerOptions, "secret"> & {
+    env?: NodeJS.ProcessEnv;
+}): {
+    ok: true;
+    server: DrawServer;
+} | {
+    ok: false;
+    reason: DrawUnavailableReason;
+    message: string;
+};
+/**
+ * Why {@link drawServerFor} built no server.
+ *
+ * The four inherited from `core/sampler.ts` are all worth telling an operator
+ * about: each one means a class they declared live is gating at 100%.
+ * `no-live-class` is the fifth and the only SILENT one, because it means the
+ * operator never asked for any of this — the reason a caller must branch on it
+ * rather than print every refusal alike.
+ */
+export type DrawUnavailableReason = LiveSelectorUnavailableReason | "no-live-class";
+/** Why the server declined to listen. Reported, never fatal to the daemon. */
+export type DrawServeRefusal = "path-too-long" | "directory-unusable" | "listen-failed";
+export interface DrawServerOptions {
+    logPath: string;
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    schemaDir?: string;
+    /** The operator's sampling secret, resolved by the caller from its own env. */
+    secret: string;
+    /** The clock for `answered_at`, which is outside the MAC and never logged. */
+    now?: () => string;
+}
+export type DrawServeResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: DrawServeRefusal;
+    detail: string;
+};
+/**
+ * A server that answers live draws for one log, over one owner-only socket.
+ *
+ * Started and stopped by the daemon loop. Every failure is a refusal to serve,
+ * never a throw into the loop: a daemon that could not open a socket must keep
+ * doing its job, and every asker fails closed to a human decision, which is
+ * exactly what happens today with no daemon at all.
+ */
+export declare class DrawServer {
+    private readonly options;
+    private server;
+    private answered;
+    private refused;
+    constructor(options: DrawServerOptions);
+    /** How many questions were answered and refused, for the daemon's report. */
+    stats(): {
+        answered: number;
+        refused: number;
+    };
+    start(): DrawServeResult;
+    close(): void;
+    private serve;
+    /**
+     * Answer one question, or refuse it.
+     *
+     * Returns the answer body; refusals go through `refuse` and this returns
+     * `undefined`, which `answer` above ignores because `done` is already set.
+     */
+    /** Where this daemon reads its policy from. One spelling, two readers. */
+    private policyWhere;
+    /**
+     * This daemon's report on its OWN sampler (APRV-271).
+     *
+     * Read through `core/sampler.ts` from this process's environment, which is
+     * the whole point: the operator exported the secret HERE, and every other
+     * process on the machine has had `APPROVAL_*` stripped from it. It carries
+     * the variable's NAME and the rate, both of which the policy file already
+     * states in the open, and never the value.
+     *
+     * No verified read, no attestation check and no MAC: this answer decides
+     * nothing. `core/live-draw.ts`'s header sets out what a caller may and may
+     * not conclude from it.
+     */
+    private samplingReport;
+    private decide;
+}

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.2.0";
+/** `user.name` on every commit this module makes. */
+export declare const GIT_EVIDENCE_AUTHOR_NAME = "approvald 0.2.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.2.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;