approval-md 0.0.1 → 0.2.0

package/dist/src/daemon/projection.js

@@ -0,0 +1,233 @@
+/**
+ * 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 { payloadOf, requestState } 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 const ENVELOPE_STATES = [
+    "proposed",
+    "awaiting",
+    "approved",
+    "executed",
+    "rejected",
+    "expired",
+    "revoked",
+];
+/** Is this the envelope's `state:` value? Used to read an untrusted file. */
+export function isEnvelopeState(value) {
+    return typeof value === "string" && ENVELOPE_STATES.includes(value);
+}
+/** Every action key the latest `task.registered` for `task` declared, in order. */
+export function registeredActionKeys(records, task) {
+    let latest = null;
+    for (const record of records) {
+        if (record.event === "task.registered" && record.task === task)
+            latest = record;
+    }
+    if (latest === null)
+        return [];
+    const declared = payloadOf(latest)["actions"];
+    if (!Array.isArray(declared))
+        return [];
+    const keys = [];
+    for (const entry of declared) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const key = entry["idempotency_key"];
+        if (typeof key === "string" && key.length > 0 && !keys.includes(key))
+            keys.push(key);
+    }
+    return keys;
+}
+/**
+ * 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 function taskEnvelopeState(records, task, ts, ttlMs) {
+    const keys = registeredActionKeys(records, task);
+    const registered = keys.length > 0 || records.some((record) => record.event === "task.registered" && record.task === task);
+    const actions = keys.map((actionKey) => ({
+        actionKey,
+        derivation: requestState(records, actionKey, ts, ttlMs),
+    }));
+    const any = (predicate) => actions.some(predicate);
+    let state = "proposed";
+    if (any((entry) => entry.derivation.state === "requested"))
+        state = "awaiting";
+    else if (any((entry) => entry.derivation.state === "granted" && entry.derivation.execution.completed === null)) {
+        state = "approved";
+    }
+    else if (any((entry) => entry.derivation.execution.completed !== null))
+        state = "executed";
+    else if (any((entry) => entry.derivation.state === "revoked"))
+        state = "revoked";
+    else if (any((entry) => entry.derivation.state === "rejected"))
+        state = "rejected";
+    else if (any((entry) => entry.derivation.state === "expired"))
+        state = "expired";
+    return { task, registered, state, actions };
+}
+/**
+ * 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 function lapsedRequests(records, ts, ttlMs) {
+    if (ttlMs === null)
+        return [];
+    const keys = [];
+    for (const record of records) {
+        if (record.event !== "approval.requested")
+            continue;
+        const key = record.action_key;
+        if (typeof key === "string" && key.length > 0 && !keys.includes(key))
+            keys.push(key);
+    }
+    const lapsed = [];
+    for (const actionKey of keys) {
+        const derivation = requestState(records, actionKey, ts, ttlMs);
+        // `expiredLazily` is precisely "the TTL has passed and no event says so".
+        // Anything decided, revoked, or already expired by event fails it.
+        if (derivation.state === "expired" && derivation.expiredLazily && !derivation.expiredByEvent) {
+            lapsed.push({
+                actionKey,
+                task: derivation.task,
+                requestedTs: derivation.requestTs,
+            });
+        }
+    }
+    return lapsed;
+}
+/**
+ * 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 const DRIFT_REASONS = ["state-mismatch", "envelope-missing"];
+/** What an `envelope.drift` payload's `reason` says, defaulting for old records. */
+function reasonOf(payload) {
+    const value = payload["reason"];
+    return typeof value === "string" ? value : "state-mismatch";
+}
+export { latestRegistration } from "../core/registration.js";
+/**
+ * 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 function driftAlreadyLogged(records, task, facts) {
+    let latest = null;
+    for (const record of records) {
+        if (record.event === "envelope.drift" && record.task === task)
+            latest = record;
+    }
+    if (latest === null)
+        return false;
+    const payload = payloadOf(latest);
+    const declared = payload["declared_state"];
+    const derived = payload["derived_state"];
+    const digest = payload["envelope_sha256"];
+    return (reasonOf(payload) === (facts.reason ?? "state-mismatch") &&
+        (declared === undefined ? null : declared) === facts.declaredState &&
+        derived === facts.derivedState &&
+        (digest === undefined ? null : digest) === facts.envelopeDigest);
+}
+//# sourceMappingURL=projection.js.map

package/dist/src/daemon/projection.js.map

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

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;