approval-md 0.2.0 → 0.4.0

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

@@ -14,7 +14,10 @@
  * and subtracts the subjects already sampled. A tick that samples nothing new is
  * the normal case; a restarted daemon, a second daemon, and an operator running
  * a sweep by hand all converge on exactly the same set. This module therefore
- * holds no state at all — no seen-set, no cursor, no cache.
+ * holds no state that any APPEND depends on: no seen-set, no cursor, no cache.
+ * The two process-lifetime sets below are output bookkeeping (which notice has
+ * been printed, which deferral was promised), and every decision about what to
+ * append is made from the log on every call.
  *
  * ## Reporting, and why it goes through `warning`
  *
@@ -27,6 +30,58 @@
  * its `sampled` line. Both channels remain the caller's: this module names no
  * event and writes to no stream.
  *
+ * ## A deferred sample is not a lost one (APRV-381)
+ *
+ * On 2026-09-19 a tick printed `append-refused audit sampling: append-failed:
+ * audit.sampled for hook:…:vcs.push.main was not appended (lock-timeout)` while a
+ * lane's hook append and a records advance were writing the same log. Nothing was
+ * lost, and the next ticks appended the sample; the operator reading the window
+ * had no way to know that, because the line said an audit record had not been
+ * written and stopped there.
+ *
+ * So the two outcomes are now said differently. `core/audit.ts` classifies
+ * `lock-timeout` and `head-moved` as transient (see its `TRANSIENT_APPEND_CODES`)
+ * and hands them back on `deferred`; this module reports each on {@link
+ * AuditSweepOptions.defer} with the action key and the fact that the next tick
+ * retries it, and reports everything else on {@link AuditSweepOptions.warn} in
+ * the form it always had. When the caller passes no `defer` sink the deferral
+ * goes to `warn` instead: a deferral nobody prints is indistinguishable, to the
+ * person who has to trust this log, from a sample that was dropped.
+ *
+ * The retry is then named as one. `pendingSamples` re-derives pendency from the
+ * verified log, so the retry needs no memory to HAPPEN; saying "this is the retry
+ * of what I deferred" is a fact about this process's own output, and it is kept
+ * here as such (see {@link rememberDeferral}).
+ *
+ * ## The lock wait: skip and retry, at `core/log.ts`'s own 2000 ms (APRV-381)
+ *
+ * The daemon is the one writer that could afford to wait longer, and it
+ * deliberately does not. Four reasons, recorded here because the number itself is
+ * a one-line change and the reasoning is not:
+ *
+ * 1. A tick is serial. This sweep sits between the TTL sweep and the queue
+ *    render, so every millisecond it blocks is a millisecond an expiry line, a
+ *    `state:` write-back and `QUEUE.md` wait. A longer wait spends latency a
+ *    person notices on a record that costs nothing to postpone.
+ * 2. The contenders hold the lock for spans no polite wait covers. `approval log
+ *    advance` holds it across a whole verify-and-commit, `approval log sync`
+ *    across a baseline move. A wait long enough to win those races reliably is a
+ *    wait long enough to stall the loop for seconds, and it would still time out
+ *    sometimes, so the transient path has to exist either way.
+ * 3. Deferring loses nothing, provably. The sample's pendency is a property of
+ *    the log (eligible, selected, no `audit.sampled` yet), not of this process, so
+ *    the retry bound is the tick interval, and an append by anyone else also wakes
+ *    the log watcher, which usually makes it the next debounce.
+ * 4. The appends this sweep contends with are the ones somebody is waiting on: a
+ *    hook's gate verdict, a lane's execution record, an advance's commit. The
+ *    writer with nobody blocked on it is the writer that should yield.
+ *
+ * "Skip" here means letting the append refuse and classifying the refusal. It
+ * explicitly does NOT mean peeking at `events.jsonl.lock` before sweeping: that
+ * read can be wrong in both directions (a lock released a microsecond later, a
+ * lock taken a microsecond after the peek), and `appendEvent`'s own acquisition
+ * under the lock is the only authority on whether an append can be made.
+ *
  * ## A disabled sampler is not a failure
  *
  * When no sampling secret is configured, `core/sampler.ts` returns a disabled
@@ -58,10 +113,21 @@ export interface AuditSweepOptions {
     /** Environment the sampling secret is read from. Injected by tests. */
     env?: NodeJS.ProcessEnv;
     /**
-     * One FAILURE line: an append the sampler could not make, or a log it could
-     * not read. Mapped by the caller onto its own warning vocabulary.
+     * One FAILURE line: an append the sampler could not make for a reason retrying
+     * cannot fix, or a log it could not read. Mapped by the caller onto its own
+     * warning vocabulary.
      */
     warn(message: string): void;
+    /**
+     * One TRANSIENT line: an append that did not happen because another writer held
+     * the lock or moved the head, and that the next sweep will make (APRV-381).
+     *
+     * Optional, and a caller that passes none gets the same text on {@link
+     * AuditSweepOptions.warn}: the one thing this module will not do is let a
+     * deferral go unsaid. Callers that have a quieter channel for "later" should
+     * pass one; the daemon maps it onto its own `sample-deferred` warning code.
+     */
+    defer?(message: string): void;
     /**
      * One CONFIGURATION line: sampling is switched off and here is why. Optional,
      * and the daemon does not pass it — see the module header. `approval status`
@@ -72,8 +138,13 @@ export interface AuditSweepOptions {
      * One SUCCESS line per `audit.sampled` appended (APRV-57). Optional, and
      * injected exactly as {@link AuditSweepOptions.warn} is, so the sweep still
      * reports in the caller's vocabulary and owns no output of its own.
+     *
+     * `retry` is true when THIS process deferred this same sample earlier and is
+     * now making the append it promised (APRV-381), so the caller can say so. It is
+     * a statement about output, never about the record: the appended event is
+     * byte-identical either way.
      */
-    sampled?(sample: SampleAppended): void;
+    sampled?(sample: SampleAppended, retry: boolean): void;
 }
 export interface AuditSweepSummary {
     /** How many `audit.sampled` events this sweep appended. */
@@ -81,7 +152,11 @@ export interface AuditSweepSummary {
     /** `null` when sampling ran; the reason when it did not. */
     disabled: SamplerDisabledReason | null;
 }
-/** Reset the once-per-process notice. Exported for tests, used nowhere else. */
+/**
+ * Reset the once-per-process notice and the deferral memory. Exported for tests,
+ * used nowhere else: both are output bookkeeping, so a suite that shares a
+ * process needs to be able to start from nothing.
+ */
 export declare function resetAuditSweepNotices(): void;
 /** One sampling sweep. Appends through `core/audit.ts` and decides nothing. */
 export declare function sweepAuditSampling(options: AuditSweepOptions): AuditSweepSummary;

package/dist/src/daemon/audit.js

@@ -14,7 +14,10 @@
  * and subtracts the subjects already sampled. A tick that samples nothing new is
  * the normal case; a restarted daemon, a second daemon, and an operator running
  * a sweep by hand all converge on exactly the same set. This module therefore
- * holds no state at all — no seen-set, no cursor, no cache.
+ * holds no state that any APPEND depends on: no seen-set, no cursor, no cache.
+ * The two process-lifetime sets below are output bookkeeping (which notice has
+ * been printed, which deferral was promised), and every decision about what to
+ * append is made from the log on every call.
  *
  * ## Reporting, and why it goes through `warning`
  *
@@ -27,6 +30,58 @@
  * its `sampled` line. Both channels remain the caller's: this module names no
  * event and writes to no stream.
  *
+ * ## A deferred sample is not a lost one (APRV-381)
+ *
+ * On 2026-09-19 a tick printed `append-refused audit sampling: append-failed:
+ * audit.sampled for hook:…:vcs.push.main was not appended (lock-timeout)` while a
+ * lane's hook append and a records advance were writing the same log. Nothing was
+ * lost, and the next ticks appended the sample; the operator reading the window
+ * had no way to know that, because the line said an audit record had not been
+ * written and stopped there.
+ *
+ * So the two outcomes are now said differently. `core/audit.ts` classifies
+ * `lock-timeout` and `head-moved` as transient (see its `TRANSIENT_APPEND_CODES`)
+ * and hands them back on `deferred`; this module reports each on {@link
+ * AuditSweepOptions.defer} with the action key and the fact that the next tick
+ * retries it, and reports everything else on {@link AuditSweepOptions.warn} in
+ * the form it always had. When the caller passes no `defer` sink the deferral
+ * goes to `warn` instead: a deferral nobody prints is indistinguishable, to the
+ * person who has to trust this log, from a sample that was dropped.
+ *
+ * The retry is then named as one. `pendingSamples` re-derives pendency from the
+ * verified log, so the retry needs no memory to HAPPEN; saying "this is the retry
+ * of what I deferred" is a fact about this process's own output, and it is kept
+ * here as such (see {@link rememberDeferral}).
+ *
+ * ## The lock wait: skip and retry, at `core/log.ts`'s own 2000 ms (APRV-381)
+ *
+ * The daemon is the one writer that could afford to wait longer, and it
+ * deliberately does not. Four reasons, recorded here because the number itself is
+ * a one-line change and the reasoning is not:
+ *
+ * 1. A tick is serial. This sweep sits between the TTL sweep and the queue
+ *    render, so every millisecond it blocks is a millisecond an expiry line, a
+ *    `state:` write-back and `QUEUE.md` wait. A longer wait spends latency a
+ *    person notices on a record that costs nothing to postpone.
+ * 2. The contenders hold the lock for spans no polite wait covers. `approval log
+ *    advance` holds it across a whole verify-and-commit, `approval log sync`
+ *    across a baseline move. A wait long enough to win those races reliably is a
+ *    wait long enough to stall the loop for seconds, and it would still time out
+ *    sometimes, so the transient path has to exist either way.
+ * 3. Deferring loses nothing, provably. The sample's pendency is a property of
+ *    the log (eligible, selected, no `audit.sampled` yet), not of this process, so
+ *    the retry bound is the tick interval, and an append by anyone else also wakes
+ *    the log watcher, which usually makes it the next debounce.
+ * 4. The appends this sweep contends with are the ones somebody is waiting on: a
+ *    hook's gate verdict, a lane's execution record, an advance's commit. The
+ *    writer with nobody blocked on it is the writer that should yield.
+ *
+ * "Skip" here means letting the append refuse and classifying the refusal. It
+ * explicitly does NOT mean peeking at `events.jsonl.lock` before sweeping: that
+ * read can be wrong in both directions (a lock released a microsecond later, a
+ * lock taken a microsecond after the peek), and `appendEvent`'s own acquisition
+ * under the lock is the only authority on whether an append can be made.
+ *
  * ## A disabled sampler is not a failure
  *
  * When no sampling secret is configured, `core/sampler.ts` returns a disabled
@@ -39,7 +94,7 @@
  * operator goes to ask what is switched on. See `core/sampler.ts` for why an
  * unconfigured sampler disables sampling rather than escalating everything.
  */
-import { sampleSupervised } from "../core/audit.js";
+import { sampleSupervised, } from "../core/audit.js";
 /**
  * Disablement reasons already reported in this process, so a standing
  * configuration fact is stated once rather than every tick. Process-lifetime and
@@ -47,9 +102,52 @@ import { sampleSupervised } from "../core/audit.js";
  * losing it costs one extra warning line and nothing else.
  */
 const reported = new Set();
-/** Reset the once-per-process notice. Exported for tests, used nowhere else. */
+/**
+ * Samples this process deferred and has not yet seen appended (APRV-381), keyed
+ * by log path and subject hash.
+ *
+ * Exactly the same standing as {@link reported}: process-lifetime, memory-only,
+ * and a de-duplicator for OUTPUT. Nothing here is consulted before an append,
+ * gates nothing, and suppresses no line. Losing it (a restart, a second daemon,
+ * an operator sweeping by hand) costs the word "retry" on one line and nothing
+ * else, which is why the retry itself is derived from the log and never from
+ * here.
+ *
+ * Bounded so a long run cannot accumulate: an entry is dropped when its sample
+ * lands, and the oldest is evicted past {@link DEFERRAL_MEMORY_LIMIT} for the
+ * candidate that is deferred and then stops being a candidate (a policy edit that
+ * drops its class, a rate that no longer selects it). A `Set` iterates in
+ * insertion order, so "the oldest" needs no timestamp.
+ */
+const deferrals = new Set();
+/** How many deferred samples this process will remember for the retry wording. */
+const DEFERRAL_MEMORY_LIMIT = 256;
+function deferralKey(logPath, subjectHash) {
+    return JSON.stringify([logPath, subjectHash]);
+}
+function rememberDeferral(logPath, subjectHash) {
+    const key = deferralKey(logPath, subjectHash);
+    if (deferrals.has(key))
+        return;
+    if (deferrals.size >= DEFERRAL_MEMORY_LIMIT) {
+        const oldest = deferrals.values().next();
+        if (!oldest.done)
+            deferrals.delete(oldest.value);
+    }
+    deferrals.add(key);
+}
+/** Whether this process deferred this sample, consuming the memory of it. */
+function takeDeferral(logPath, subjectHash) {
+    return deferrals.delete(deferralKey(logPath, subjectHash));
+}
+/**
+ * Reset the once-per-process notice and the deferral memory. Exported for tests,
+ * used nowhere else: both are output bookkeeping, so a suite that shares a
+ * process needs to be able to start from nothing.
+ */
 export function resetAuditSweepNotices() {
     reported.clear();
+    deferrals.clear();
 }
 /** One sampling sweep. Appends through `core/audit.ts` and decides nothing. */
 export function sweepAuditSampling(options) {
@@ -80,11 +178,33 @@ export function sweepAuditSampling(options) {
     for (const refusal of result.refusals) {
         options.warn(`audit sampling: ${refusal.code}: ${refusal.message}`);
     }
+    // The transient half (APRV-381). Said BEFORE the successes of this same sweep
+    // are said, because the sweep stops at the first deferral: anything it did
+    // append, it appended before the contention, and the reading order should match
+    // the order it happened in.
+    for (const entry of result.deferred) {
+        rememberDeferral(options.logPath, entry.candidate.hash);
+        (options.defer ?? options.warn)(deferralLine(entry));
+    }
     const sampled = options.sampled;
-    if (sampled !== undefined) {
-        for (const entry of result.appended)
-            sampled(entry);
+    for (const entry of result.appended) {
+        // Consumed whether or not anyone is listening, so a caller with no `sampled`
+        // sink cannot leave a stale deferral behind to mislabel a later sample.
+        const retry = takeDeferral(options.logPath, entry.candidate.hash);
+        if (sampled !== undefined)
+            sampled(entry, retry);
     }
     return { sampled: result.appended.length, disabled: null };
 }
+/**
+ * The deferral line: what was not appended, why, and that it is coming.
+ *
+ * "retries it on the next tick" is load-bearing wording. The line an
+ * operator read before APRV-381 ended at "was not appended", which is true and
+ * reads as a loss; this one has to answer the question that sentence provokes
+ * before they go looking for a missing audit record.
+ */
+function deferralLine(entry) {
+    return `audit sampling deferred ${entry.candidate.actionKey} (${entry.append.code}): ${entry.append.message} The sample is NOT lost: it is still pending in the log's own terms (eligible, drawn, no audit.sampled yet), and the sweep retries it on the next tick.`;
+}
 //# sourceMappingURL=audit.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/daemon/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,gBAAgB,EAA0C,MAAM,kBAAkB,CAAC;AA0C5F;;;;;GAKG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;AAEnC,gFAAgF;AAChF,MAAM,UAAU,sBAAsB;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,OAA0B;IAC3D,MAAM,YAAY,GAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC9D,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,YAAY,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAChF,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,YAAY,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IACpE,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS;QAAE,YAAY,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAE9D,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAE5E,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,4EAA4E;QAC5E,2EAA2E;QAC3E,4EAA4E;QAC5E,OAAO,CAAC,IAAI,CACV,gDAAgD,MAAM,CAAC,IAAI,MAAM,MAAM,CAAC,OAAO,EAAE,CAClF,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxC,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClB,MAAM,CACJ,0BAA0B,MAAM,CAAC,OAAO,CAAC,MAAM,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,2KAA2K,CACvP,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;IACzD,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,mBAAmB,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/daemon/audit.ts"],"names":[],"mappings":"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"}

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