approval-md 0.3.0 → 0.4.1

package/dist/src/daemon/daemon.js

@@ -92,6 +92,10 @@ import { watch } from "node:fs";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { writeQueue } from "../channels/render-queue.js";
+// APRV-403. The classifier is APRV-381's, shared rather than copied: one closed
+// list of transient append codes means the drift scan and the sampling sweep
+// cannot come to disagree about which failures a retry fixes.
+import { isTransientAppendError } from "../core/audit.js";
 import { tick as readClock } from "../core/clock.js";
 import { parseFrontmatter, readTaskFile } from "../core/frontmatter.js";
 import { expire } from "../core/gate.js";
@@ -105,6 +109,8 @@ import { validate } from "../core/validate.js";
 import { publishedState } from "../cli/log-advance.js";
 import { isAdvanceBookkeeping } from "../core/advance-cycle.js";
 import { markDaemonProcess } from "../core/daemon-actor.js";
+import { declareDaemonIdentityFor, refreshDaemonAllowlist, } from "../core/daemon-host.js";
+import { daemonIdentity } from "../core/daemon-identity.js";
 import { repoRoot } from "../cli/git-scope.js";
 import { checkLogAnchor, resolveAnchor } from "../cli/log-anchor.js";
 import { checkLogCheckpoints, checkpointPolicyOf, } from "../core/checkpoint.js";
@@ -122,6 +128,61 @@ import { driftAlreadyLogged, lapsedRequests, latestRegistration, taskEnvelopeSta
 export const DAEMON_ACTOR = "system:daemon";
 /** Backlog.md's conventional task folder, relative to the working directory. */
 export { DEFAULT_TASKS_DIR } from "../core/registration.js";
+// ---------------------------------------------------------------------------
+// The drift scan's deferral memory (APRV-403)
+// ---------------------------------------------------------------------------
+/**
+ * `envelope.drift` records this PROCESS deferred and has not yet seen appended,
+ * keyed by log path, task and drift reason.
+ *
+ * Exactly the standing `daemon/audit.ts` gives its own deferral memory, and
+ * deliberately the same shape: process-lifetime, memory-only, and a
+ * de-duplicator for OUTPUT. Nothing here is consulted before an append, and
+ * nothing is gated or suppressed by it. The RETRY needs no memory to happen,
+ * because the drift scan re-derives the whole question from the verified log on
+ * every tick; what this buys is the word "retry" on one line, so an operator can
+ * pair the deferral they read with the record that resolved it.
+ *
+ * It is consulted in exactly one other place, and that one is not cosmetic: the
+ * write-back pass skips a file whose drift record this tick could not append, so
+ * the file is not repaired off the record (SPEC.md §6.3's fixed order). Losing
+ * the memory there costs a repair one tick, never a lost record.
+ *
+ * Keyed by log path as well as task, because one process can be pointed at more
+ * than one gate over its lifetime and a task id is only unique inside one.
+ * Bounded, so a long run cannot accumulate entries for a file that drifts, is
+ * deferred, and is then deleted.
+ */
+const driftDeferrals = new Set();
+/** How many deferred drift records one process remembers for the retry wording. */
+const DRIFT_DEFERRAL_LIMIT = 256;
+function driftDeferralKey(logPath, task, reason) {
+    return JSON.stringify([logPath, task, reason]);
+}
+function rememberDriftDeferral(logPath, task, reason) {
+    const key = driftDeferralKey(logPath, task, reason);
+    if (driftDeferrals.has(key))
+        return;
+    // A `Set` iterates in insertion order, so "the oldest" needs no timestamp.
+    if (driftDeferrals.size >= DRIFT_DEFERRAL_LIMIT) {
+        const oldest = driftDeferrals.values().next();
+        if (!oldest.done)
+            driftDeferrals.delete(oldest.value);
+    }
+    driftDeferrals.add(key);
+}
+/** Whether this process deferred this record, consuming the memory of it. */
+function takeDriftDeferral(logPath, task, reason) {
+    return driftDeferrals.delete(driftDeferralKey(logPath, task, reason));
+}
+/**
+ * Forget every deferral. Exported for tests, used nowhere else: the memory is
+ * output bookkeeping, so a suite that shares a process needs to be able to start
+ * from nothing and to exercise what a restarted daemon does.
+ */
+export function resetDriftDeferrals() {
+    driftDeferrals.clear();
+}
 /** How often the daemon looks, absent any watcher event. */
 export const DEFAULT_INTERVAL_MS = 30_000;
 /** How long a burst of watcher events is allowed to settle before a tick. */
@@ -237,6 +298,19 @@ export const DAEMON_WARNING_CODES = [
      * repair, and the next tick asks again.
      */
     "anchor-behind",
+    /**
+     * The working log changed between this tick's opening read and the anchor
+     * check's own read of the file, so the check read it again (APRV-389).
+     *
+     * A line rather than a stop, and rather than a silence. `approval log sync`
+     * and a records pull both rewrite `events.jsonl` under a running daemon
+     * (baseline, fast-forward, restore), and this loop reads without the append
+     * lock, so a tick can hold a view the file has already moved past. That is a
+     * fact about reads, never a fork: the anchor comparison is made again from the
+     * file and the verdict beside this line is the second read's. The line is the
+     * one an operator acts on when the writer was not a sync they ran.
+     */
+    "anchor-reread",
     /**
      * `audit.checkpoint_every` says a human-signed checkpoint is due and the log
      * carries none that recent (APRV-220). A WARNING and never a stop, at every
@@ -253,6 +327,53 @@ export const DAEMON_WARNING_CODES = [
      * month of taps.
      */
     "draw-unavailable",
+    /**
+     * This daemon's own id is not one the attested policy's `daemons` list admits,
+     * or the id it was launched with is not a usable id at all (APRV-383).
+     *
+     * A warning rather than a stop, and the distinction matters: the refusal itself
+     * happens at the write boundary, one append at a time, so the loop keeps
+     * reading, keeps rendering the queue and keeps reporting, and writes nothing.
+     * The line exists because an operator should learn that from the first tick
+     * rather than from a day of `append-refused` messages. The repair is a line in
+     * a policy a human re-attests, or a launch environment fixed, and neither is
+     * something this process can do for itself.
+     */
+    "daemon-identity-refused",
+    /**
+     * An `audit.sampled` append met a held lock or a moved head, so the sample was
+     * postponed to the next tick (APRV-381). Appended to this union, so no existing
+     * entry changed meaning.
+     *
+     * Distinct from `append-refused` because the operator's next move is different:
+     * `append-refused` on a sample is a fact about the record or the file and wants
+     * a person, and this is contention between writers that the next sweep resolves
+     * by re-deriving the sample from the log. It is still a warning rather than a
+     * silence, because a tick that keeps deferring is a log under contention and
+     * that is a thing to know, and the `sampled` line that closes it carries
+     * `retry`.
+     */
+    "sample-deferred",
+    /**
+     * An `envelope.drift` append met a held lock or a moved head, so the record was
+     * postponed to the next tick (APRV-403). Appended to this union, so no existing
+     * entry changed meaning.
+     *
+     * The same split APRV-381 made for `audit.sampled`, for the same reason and
+     * from the same closed list of transient codes. Found while landing that task:
+     * the end-to-end test that holds the append lockfile for a whole tick showed
+     * the drift scan printing `append-refused … (lock-timeout)`, which is true and
+     * reads as a lost record, while the next tick re-derived the drift from the
+     * verified log and appended it. An operator's next move differs between the
+     * two: `append-refused` on a drift record is a fact about the record or the
+     * file and wants a person, and this is contention between writers that the
+     * scan resolves by itself.
+     *
+     * Still a warning rather than a silence: a scan that keeps deferring is a log
+     * under contention, which is a thing to know. The `drift` line that closes it
+     * carries `retry`.
+     */
+    "drift-deferred",
 ];
 function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
@@ -355,6 +476,16 @@ export class Daemon {
     previousSelfWrites = new Set();
     settle = null;
     finished = false;
+    /**
+     * What this process resolved as its own daemon id (APRV-383), kept so the
+     * `started` line can name it and the startup check can say what is wrong with
+     * it. The id in FORCE lives in `core/daemon-identity.ts`'s process state, which
+     * is what the write boundary reads; this field is the resolution that produced
+     * it, and nothing reads it to decide anything.
+     */
+    identity;
+    /** Has the unlisted-id warning already been said this run? */
+    reportedIdentityRefusal = false;
     /** Whether {@link DaemonOptions.draw} actually bound (APRV-208). */
     drawServing = false;
     constructor(options) {
@@ -367,6 +498,15 @@ export class Daemon {
         // `--once` tick and a test driving this object one tick at a time are all
         // the same actor as the loop.
         markDaemonProcess();
+        // APRV-383. WHICH daemon this process is, declared in the same breath and at
+        // the same moment for the same reason. The resolution is the launch
+        // environment's `APPROVAL_DAEMON_ID` or the id derived from this log's
+        // instance; an unusable declared id is declared as an identity with NO id,
+        // which refuses every append at the write boundary rather than leaving a
+        // daemon writing records nothing can attribute. The CLI verbs refuse to start
+        // on the same resolution, so this is the belt on that brace, and it is what
+        // covers a `Daemon` constructed directly by an embedder or a test.
+        this.identity = declareDaemonIdentityFor(this.options.logPath);
     }
     /** Run until stopped (or, with `once`, for exactly one tick). */
     run() {
@@ -418,7 +558,19 @@ export class Daemon {
                 // would be a write nobody asked for yet. Seeded into `reportedDangling`
                 // so the tick that immediately follows does not repeat it.
                 dangling_advances: this.listDanglingAdvancesAtStartup(),
+                // APRV-383. Resolved in the constructor, printed here, and `null` for an
+                // id this process could not use at all.
+                daemon: this.identity.ok ? this.identity.id : null,
             });
+            // APRV-383. Said once, before the first tick, when this run cannot write:
+            // a bad launch id is knowable without reading anything, and the allowlist
+            // is knowable from the attested policy the first tick resolves. An operator
+            // who reads it here does not have to infer it from a day of
+            // `append-refused` lines.
+            if (!this.identity.ok) {
+                this.reportedIdentityRefusal = true;
+                this.warn("daemon-identity-refused", `${this.identity.message}. Every append this run makes will be refused \`daemon-id-invalid\` until that is fixed; nothing is written and nothing is retried`);
+            }
             const outcome = this.tick();
             if (outcome !== null) {
                 this.finish(outcome);
@@ -729,6 +881,14 @@ export class Daemon {
             const opening = this.read();
             if (!opening.ok)
                 return this.fatal(opening);
+            // WHICH daemons this log's ATTESTED policy admits (APRV-383), put in force
+            // before anything below appends. Resolved every tick, from this tick's own
+            // verified read, so a `daemons` list a human adds and attests takes effect
+            // on the next tick rather than at the next restart; a resolution that FAILS
+            // (the policy will not load, or is not attested) leaves the previous one
+            // standing, so a policy that becomes unreadable is not a way out of the list
+            // it carried a moment ago.
+            this.refreshIdentity(opening.records);
             // The anchor check (APRV-219), on the full re-proof cadence and on the
             // first tick, which is always a cold walk. Placed immediately after the
             // opening read and before any append this tick could make: a log that
@@ -740,6 +900,17 @@ export class Daemon {
                     if (anchor.status === "diverged") {
                         return { kind: "anchor-diverged", message: anchor.message };
                     }
+                    // The log was rewritten between this tick's opening read and the
+                    // check's own read of the file (APRV-389), so the check read it again
+                    // and this verdict is the second read's. ONE line, and no stop: a
+                    // `log sync` or a records pull replacing `events.jsonl` under this
+                    // process is housekeeping on the container, the append lock keeps it
+                    // from interleaving with any append, and the daemon's every other step
+                    // re-reads the log for itself anyway. The line is here because a
+                    // writer nobody expected is a thing to know, and because this is the
+                    // read that used to be reported as a fork.
+                    if (anchor.reread !== undefined)
+                        this.warn("anchor-reread", anchor.reread.detail);
                     if (anchor.status === "behind") {
                         this.warn("anchor-behind", `${anchor.detail}. Nothing was appended onto the shorter chain by this check; run \`approval log sync\` before this daemon writes anything`);
                     }
@@ -798,14 +969,19 @@ export class Daemon {
                 ...(this.options.schemaDir === undefined ? {} : { schemaDir: this.options.schemaDir }),
                 ...(this.options.clock === undefined ? {} : { clock: this.options.clock }),
                 warn: (message) => this.warn("append-refused", message),
+                // APRV-381. Contention with another writer gets its own code, so the
+                // window an operator reads distinguishes "this sample is coming" from
+                // "an audit record was not written".
+                defer: (message) => this.warn("sample-deferred", message),
                 // One line per sample appended (APRV-57). The sweep names no event; it
                 // hands back what it wrote and the loop says it in the loop's own words.
-                sampled: (sample) => this.emit({
+                sampled: (sample, retry) => this.emit({
                     event: "sampled",
                     action_key: sample.candidate.actionKey,
                     task: sample.candidate.task,
                     seq: sample.record.seq,
                     subject_seq: sample.candidate.seq,
+                    ...(retry ? { retry: true } : {}),
                 }),
             }));
             // The dark-session sweep (APRV-192), on its own cadence. Placed with the
@@ -1379,14 +1555,45 @@ export class Daemon {
             ...(this.options.readProof === undefined ? {} : { readProof: this.options.readProof }),
         });
     }
-    /** The TTL in force right now, re-read every pass: policy files change. */
-    ttlMs() {
+    /** Where this daemon's policy is, in `loadPolicy`'s own vocabulary. */
+    policyWhere() {
         const where = this.options.policy.file !== undefined
             ? { file: this.options.policy.file }
             : { dir: this.options.policy.dir ?? this.options.cwd };
         if (this.options.schemaDir !== undefined)
             where.schemaDir = this.options.schemaDir;
-        const load = loadPolicy(where);
+        return where;
+    }
+    /**
+     * Put the attested policy's `daemons` allowlist in force for this tick
+     * (APRV-383).
+     *
+     * Called once per tick, immediately after the opening verified read and before
+     * any sweep that appends. It never widens: a resolution that fails sets nothing,
+     * so whatever was last resolved stays in force, and a run whose policy was never
+     * attested is unrestricted exactly as every run before this key existed was.
+     *
+     * The warning is said ONCE per run. A line every thirty seconds forever stops
+     * being read (the `reportedDangling` set above exists for the same reason), and
+     * the write boundary is where the refusal actually happens: every refused append
+     * carries its own `append-refused` line with the reason in it.
+     */
+    refreshIdentity(records) {
+        refreshDaemonAllowlist(records, loadPolicy(this.policyWhere()));
+        if (this.reportedIdentityRefusal)
+            return;
+        const state = daemonIdentity();
+        if (state === null || state.id === null)
+            return;
+        const allowed = state.allowed;
+        if (allowed === null || allowed.includes(state.id))
+            return;
+        this.reportedIdentityRefusal = true;
+        this.warn("daemon-identity-refused", `this daemon's id is ${state.id} and the attested policy's \`daemons\` list admits ${allowed.length === 0 ? "no daemon at all" : allowed.join(", ")}: every append this run makes is refused \`daemon-not-allowed\` and nothing is written. Add ${state.id} to \`daemons\` and re-attest the policy, or run the daemon whose id the list already names`);
+    }
+    /** The TTL in force right now, re-read every pass: policy files change. */
+    ttlMs() {
+        const load = loadPolicy(this.policyWhere());
         // Fail closed exactly as the gate does: an unloadable policy declares no
         // TTL, so nothing lapses and nothing is expired on its behalf.
         return load.ok ? load.durations.approvalTtlMs : null;
@@ -1419,6 +1626,29 @@ export class Daemon {
      * malformed file is not a *contradiction* of the log, it is a file the runtime
      * cannot read a claim out of at all, and inventing a `declared_state` for it
      * would put a fact in the log that nobody wrote.
+     *
+     * ## A deferred drift record is not a lost one (APRV-403)
+     *
+     * An append here can fail two ways that call for different things. A held
+     * lockfile or a head that moved under the compare-and-append means the log was
+     * not written and nothing about the file changed; the next tick re-reads the
+     * folder, re-derives the disagreement from the verified log, and appends it.
+     * A validation refusal, a canonicalization failure, a corrupt tail or an I/O
+     * error is a fact about the record or the file that no retry repairs.
+     *
+     * Both used to read as `append-refused … was not appended`, which for the
+     * first is true and reads as a loss. So the transient half now goes out as
+     * {@link deferDrift}'s own `drift-deferred` line, naming the task and saying
+     * that the scan retries, and the `drift` record that closes it carries
+     * `retry`. Everything else keeps the form it had.
+     *
+     * Nothing about the APPEND changed, which is the part that matters for
+     * SPEC.md §11.1 invariant 5: the record is still placed by `appendEvent`
+     * against the `expectedHead` of a read taken immediately before it, and the
+     * whole decision is still remade against that read. A `head-moved` here IS
+     * compare-and-append working — another writer landed a record between this
+     * scan's read and its append — and deferring is the only answer that does not
+     * either write against a head this scan never saw or lose the observation.
      */
     scanForDrift() {
         // ONE verified read for the whole scan (APRV-211). The scan asks the same
@@ -1446,6 +1676,24 @@ export class Daemon {
         }
         return { appended, stop: null };
     }
+    /**
+     * Say that an `envelope.drift` append did not happen YET, and remember it
+     * (APRV-403).
+     *
+     * Two things this line has to do that `append-refused` did not. It names the
+     * TASK KEY, so an operator can match the deferral to the record that closes
+     * it, and it says in words that the next tick retries — because the sentence
+     * it replaced ended at "was not appended", which is true and reads as a loss.
+     *
+     * The claim is safe to make because the scan carries nothing between ticks:
+     * the next one re-reads the folder, re-derives the state from the verified
+     * log, and finds the same disagreement, so the retry is a property of how the
+     * scan is written rather than a promise this method is keeping.
+     */
+    deferDrift(task, reason, error) {
+        rememberDriftDeferral(this.options.logPath, task, reason);
+        this.warn("drift-deferred", `envelope.drift${reason === "state-mismatch" ? "" : ` (${reason})`} for ${task} was deferred (${error.code}): ${error.message} The record is NOT lost: the disagreement is still there in the log's own terms, and the scan re-derives it and retries on the next tick.`);
+    }
     /** Every `*.md` under the task folder, sorted, non-recursive. */
     taskFiles() {
         let entries;
@@ -1566,10 +1814,22 @@ export class Daemon {
             expectedHead: records.head,
         });
         if (!result.ok) {
-            this.warn("append-refused", `envelope.drift for ${id} was not appended (${result.error.code}): ${result.error.message}`);
+            // APRV-403. A held lock or a moved head says the log was not written and
+            // nothing about this file changed, which is a different fact from a record
+            // the write boundary will never take; the scan re-derives and retries the
+            // first, and only a person repairs the second. `isTransientAppendError`
+            // and its closed list are `core/audit.ts`'s, shared rather than copied, so
+            // the two sweeps cannot disagree about what transient means.
+            if (isTransientAppendError(result.error)) {
+                this.deferDrift(id, "state-mismatch", result.error);
+            }
+            else {
+                this.warn("append-refused", `envelope.drift for ${id} was not appended (${result.error.code}): ${result.error.message}`);
+            }
             return { appended: false, stop: null };
         }
         this.drifts += 1;
+        const retried = takeDriftDeferral(this.options.logPath, id, "state-mismatch");
         this.emit({
             event: "drift",
             task: id,
@@ -1577,6 +1837,7 @@ export class Daemon {
             declared_state: declaredState,
             derived_state: facts.derivedState,
             seq: result.record.seq,
+            ...(retried ? { retry: true } : {}),
         });
         return { appended: true, stop: null };
     }
@@ -1647,10 +1908,20 @@ export class Daemon {
             expectedHead: records.head,
         });
         if (!result.ok) {
-            this.warn("append-refused", `envelope.drift (envelope-missing) for ${task} was not appended (${result.error.code}): ${result.error.message}`);
+            // The same split as the mismatch path above (APRV-403). Both sites take
+            // it, because contention does not care which reason the record carries and
+            // an operator reading a deferral for one and a refusal for the other would
+            // be reading two answers to one question.
+            if (isTransientAppendError(result.error)) {
+                this.deferDrift(task, "envelope-missing", result.error);
+            }
+            else {
+                this.warn("append-refused", `envelope.drift (envelope-missing) for ${task} was not appended (${result.error.code}): ${result.error.message}`);
+            }
             return { appended: false, stop: null };
         }
         this.drifts += 1;
+        const retried = takeDriftDeferral(this.options.logPath, task, "envelope-missing");
         this.emit({
             event: "drift",
             task,
@@ -1659,6 +1930,7 @@ export class Daemon {
             derived_state: facts.derivedState,
             seq: result.record.seq,
             reason: "envelope-missing",
+            ...(retried ? { retry: true } : {}),
         });
         return { appended: true, stop: null };
     }
@@ -1773,7 +2045,7 @@ export class Daemon {
      * log, and produces bytes only through `core/task-file.ts`. A file can no more
      * teach the log a state than a screenshot can teach a database a row.
      *
-     * Four rules, each of which is a way of not making things worse:
+     * Five rules, each of which is a way of not making things worse:
      *
      * 1. **Only files that already have an envelope.** `set-state` refuses
      *    `no-envelope`, and that refusal is honoured silently: a task with no
@@ -1795,6 +2067,11 @@ export class Daemon {
      *    envelope: each was warned about a few milliseconds ago by
      *    {@link scanForDrift} over the same folder. Repeating it here would double
      *    every line an operator reads without adding a fact.
+     * 5. **No repair for a drift record that was deferred** (APRV-403). See the
+     *    check inside the loop: a file whose `envelope.drift` this tick could not
+     *    append is left exactly as it is, because repairing it would correct the
+     *    disagreement off the record and erase what the retry is supposed to
+     *    re-derive.
      *
      * Loop safety comes from the comparison, not from a remembered flag: the next
      * tick derives the same state from the same log, finds the file already
@@ -1844,6 +2121,20 @@ export class Daemon {
             const derived = taskEnvelopeState(records.records, id, ts, ttlMs).state;
             if (declaredState === derived)
                 continue;
+            // APRV-403, and it is rule 5 of this list. The drift scan earlier in this
+            // tick DEFERRED the record for this task, so the disagreement has not been
+            // written down yet. Repairing the file now would correct it off the record
+            // and, worse, remove the evidence: the next tick would find the file
+            // agreeing with the log, the retry would have nothing to re-derive, and
+            // the deferral an operator was told about would resolve into silence.
+            //
+            // SPEC.md §6.3 fixes the order — the event is appended first and the file
+            // is updated second, never the reverse — and a transient append failure is
+            // exactly the case where "never the reverse" has to be enforced rather
+            // than assumed. So the file waits for the record, and the tick that lands
+            // the record repairs the file after it.
+            if (driftDeferrals.has(driftDeferralKey(this.options.logPath, id, "state-mismatch")))
+                continue;
             const rewritten = rewriteTaskFile(text, { kind: "set-state", state: derived }, rewriteOptions);
             if (!rewritten.ok) {
                 if (rewritten.code === "no-envelope")