approval-md 0.3.0 → 0.4.0

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

@@ -104,6 +104,12 @@ import { type PruneReason } from "./prune.js";
 export declare const DAEMON_ACTOR = "system:daemon";
 /** Backlog.md's conventional task folder, relative to the working directory. */
 export { DEFAULT_TASKS_DIR } from "../core/registration.js";
+/**
+ * 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 declare function resetDriftDeferrals(): void;
 /** How often the daemon looks, absent any watcher event. */
 export declare const DEFAULT_INTERVAL_MS = 30000;
 /** How long a burst of watcher events is allowed to settle before a tick. */
@@ -203,6 +209,18 @@ export type DaemonEvent = {
      * a person.
      */
     dangling_advances?: string[];
+    /**
+     * Which daemon instance this run is (APRV-383), and `null` when the id it
+     * was launched with is unusable. Additive, like every other growth of this
+     * union.
+     *
+     * On the FIRST line for the reason `read_proof` and `draw` are: it is the
+     * name every record this run appends will carry, a tenant reading a hosted
+     * log identifies the process by it, and it is not something an operator
+     * should have to ask the process about. `null` is the state in which this
+     * run will refuse every append, which the warning beside it says in words.
+     */
+    daemon?: string | null;
 } | {
     event: "drift";
     task: string;
@@ -216,6 +234,18 @@ export type DaemonEvent = {
      * appeared on all of them would change a shape supervisors already parse.
      */
     reason?: "envelope-missing";
+    /**
+     * This append is the one an earlier tick of THIS run deferred (APRV-403).
+     * Present only when it is true, so the shape a supervisor already parses is
+     * unchanged for every other drift record.
+     *
+     * It closes a `drift-deferred` warning, exactly as `sampled.retry` closes a
+     * `sample-deferred` one: the pair is what tells an operator that the
+     * transient failure they read resolved, and which record resolved it. A
+     * fresh process makes the same append and claims no retry, because this
+     * loop says only what it witnessed.
+     */
+    retry?: true;
 } | {
     /**
      * A task file's `state:` was rewritten to match the log (SPEC.md §6.3).
@@ -252,6 +282,18 @@ export type DaemonEvent = {
     seq: number;
     /** `seq` of the `execution.started` record the sample named. */
     subject_seq: number;
+    /**
+     * This append is the one an earlier tick of THIS run deferred (APRV-381).
+     * Present only when it is true, so the shape a supervisor already parses is
+     * unchanged for every other sample.
+     *
+     * It closes a `sample-deferred` warning: the pair is what tells an operator
+     * that the transient failure they read resolved, and which sample resolved
+     * it. Absent on a run that did not itself defer the sample, including a
+     * fresh process picking up a deferral the previous one printed, because this
+     * loop says only what it witnessed.
+     */
+    retry?: true;
 } | {
     /**
      * A payload's bytes were removed under `payload_retention` (APRV-41,
@@ -551,6 +593,19 @@ export declare const DAEMON_WARNING_CODES: readonly [
  * 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
@@ -566,7 +621,54 @@ export declare const DAEMON_WARNING_CODES: readonly [
  * while it stands, and that is a thing to know rather than to discover from a
  * month of taps.
  */
-"draw-unavailable"];
+"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"];
 export type DaemonWarningCode = (typeof DAEMON_WARNING_CODES)[number];
 /** Where daemon output goes. Injected, so the loop itself writes to nothing. */
 export interface DaemonSink {
@@ -838,6 +940,16 @@ export declare class Daemon {
     private previousSelfWrites;
     private settle;
     private finished;
+    /**
+     * 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.
+     */
+    private readonly identity;
+    /** Has the unlisted-id warning already been said this run? */
+    private reportedIdentityRefusal;
     /** Whether {@link DaemonOptions.draw} actually bound (APRV-208). */
     private drawServing;
     constructor(options: DaemonOptions);
@@ -1025,6 +1137,23 @@ export declare class Daemon {
      */
     private read;
     private readOnce;
+    /** Where this daemon's policy is, in `loadPolicy`'s own vocabulary. */
+    private policyWhere;
+    /**
+     * 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.
+     */
+    private refreshIdentity;
     /** The TTL in force right now, re-read every pass: policy files change. */
     private ttlMs;
     private gateOptions;
@@ -1045,8 +1174,46 @@ export declare 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.
      */
     private scanForDrift;
+    /**
+     * 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.
+     */
+    private deferDrift;
     /** Every `*.md` under the task folder, sorted, non-recursive. */
     private taskFiles;
     private checkOneFile;
@@ -1116,7 +1283,7 @@ export declare 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
@@ -1138,6 +1305,11 @@ export declare 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