approval-md 0.3.0 → 0.4.1

package/dist/src/core/log.js

@@ -42,15 +42,53 @@
  *    canonicalization minus the `hash` field. One scheme, two inputs — a
  *    verifier strips `hash` and re-derives. Appended with a single `write(2)`
  *    on a handle opened `O_APPEND`.
+ * 5b. **Durable before ok (APRV-440).** The write is followed by `fsync(2)` on
+ *    the same descriptor, and only then does the append report ok. When this
+ *    append created the file, the log directory is fsynced too (and the parent
+ *    of every directory this call created), so the new name survives along with
+ *    its bytes. Without this, an acknowledged record lived in the page cache
+ *    only: a platform kill before writeback left the file extended over blocks
+ *    that were never written, which reads back as a NUL-filled unterminated tail
+ *    (observed on a hosted tenant on 2026-09-25: an acknowledged attestation
+ *    lost, 456 NUL bytes in its place). Atomicity against concurrent writers
+ *    was guarantee 5 all along; durability against the machine dying is this one.
+ *
+ * 6. **The writing daemon names itself, or is refused (APRV-383).** A record
+ *    appended by a declaring daemon process carries `daemon`, the id of the
+ *    instance that wrote it, so a tenant reading a log hosted by somebody else can
+ *    tell which daemon acted on their behalf. The id comes from this process's own
+ *    state (`core/daemon-identity.ts`) and never from the caller, and where the
+ *    attested policy lists the ids that may write, an unlisted one is refused here
+ *    with nothing written. Every earlier record, carrying no such field, validates
+ *    and verifies unchanged.
+ *
+ * 7. **A lock whose holder is provably gone is taken back, and the log says so
+ *    (APRV-479).** The lockfile carries its holder's record. A writer that has
+ *    waited out its whole lock timeout judges the holder once, and only a holder
+ *    provably gone (a dead pid in this process's own pid namespace and boot, or
+ *    an empty lockfile ten minutes old) loses the lock: the writer claims it
+ *    with one exclusive `link(2)`, takes it with one `rename(2)` of its own
+ *    lockfile over the lock's path, and appends `audit.lock_reclaimed` as the
+ *    first record under it. A live holder's lock, and any holder this process
+ *    cannot check, is never taken; the refusal names the human verb
+ *    `approval log unlock`. `core/log-lock.ts` holds the rules.
  *
  * Determinism: `ts` is supplied by the caller. This module never reads the
  * clock, because a hash-relevant field sourced from ambient state would make
- * the log irreproducible.
+ * the log irreproducible. The one exception is the record this module writes on
+ * its own behalf, the `audit.lock_reclaimed` of guarantee 7: no caller authors
+ * it, and its `ts` is assigned at the write boundary like any audit record's.
+ * `daemon` is ambient in the same sense and is not a counter-example: a log is reproducible per WRITER, the field says which writer,
+ * and a verifier re-derives the hash from the record's own bytes either way.
  */
 import { createHash } from "node:crypto";
-import { closeSync, fstatSync, mkdirSync, openSync, readSync, unlinkSync, writeSync, } from "node:fs";
-import { dirname } from "node:path";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readSync, } from "node:fs";
+import { basename, dirname } from "node:path";
+import { DAEMON_APPEND_REFUSAL_CODES, daemonStampForAppend, } from "./daemon-identity.js";
+import { systemClock } from "./clock.js";
 import { canonicalize, JcsError } from "./jcs.js";
+import { createLockFile, finishReclaim, guardTerminationWhileLocked, observeLock, reclaimStaleLock, releaseLockFile, settleTerminationGuards, takeLockForUnlock, } from "./log-lock.js";
+import { appendWriteLayer } from "./log-write-layer.js";
 import { validate } from "./validate.js";
 /** SPEC.md §8: the hash scheme identifier stamped on every v0.1 record. */
 export const ALG = "sha256/jcs";
@@ -85,9 +123,24 @@ export const APPEND_ERROR_CODES = [
      * caller made is stale. Nothing was written.
      */
     "head-moved",
+    /**
+     * The two identity refusals of APRV-383, spread in from
+     * `core/daemon-identity.ts` where the logic that emits them lives: a daemon that
+     * declared an unusable id, and a daemon whose id the attested policy's `daemons`
+     * list does not admit. Both leave the file byte-identical, like every member
+     * above them, and both are additions to the closed union rather than renames of
+     * anything in it.
+     */
+    ...DAEMON_APPEND_REFUSAL_CODES,
 ];
-const DEFAULT_LOCK_TIMEOUT_MS = 2_000;
-const DEFAULT_LOCK_RETRY_MS = 20;
+/**
+ * How long an append waits for `<log>.lock` before refusing `lock-timeout`, and
+ * how often it tries. Exported (APRV-478) so a caller that waits for the lock
+ * itself, on the event loop rather than in {@link acquireLock}'s synchronous
+ * retry, keeps the same bound and cadence as every other writer.
+ */
+export const DEFAULT_LOCK_TIMEOUT_MS = 2_000;
+export const DEFAULT_LOCK_RETRY_MS = 20;
 /**
  * Strip `hash` and canonicalize. Exported shape is documented on
  * {@link computeRecordHash}; kept separate so hashing and verification cannot
@@ -138,22 +191,124 @@ function sleepSync(ms) {
     const buffer = new Int32Array(new SharedArrayBuffer(4));
     Atomics.wait(buffer, 0, 0, ms);
 }
+/** `O_APPEND` writer flags; `O_EXCL` added for the first try, so creation is known. */
+const APPEND_FLAGS = fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT;
+/** The mode Node's `"a"` opens with; the umask applies as it always did. */
+const APPEND_MODE = 0o666;
+/**
+ * Open `logPath` for append and say whether this call created it. `O_EXCL`
+ * first: under the append lock no other sanctioned writer can race the create, so
+ * `EEXIST` means the file was already there and a plain append open follows.
+ */
+function openForAppend(logPath) {
+    const writeLayer = appendWriteLayer();
+    try {
+        return { fd: writeLayer.open(logPath, APPEND_FLAGS | fsConstants.O_EXCL, APPEND_MODE), created: true };
+    }
+    catch (cause) {
+        if (cause.code !== "EEXIST")
+            throw cause;
+    }
+    return { fd: writeLayer.open(logPath, APPEND_FLAGS, APPEND_MODE), created: false };
+}
+/**
+ * The errors a directory fsync returns on a filesystem that cannot sync a
+ * directory at all (some FUSE, SMB and drvfs mounts). PostgreSQL ignores the
+ * same set for the same reason: there, every first append would otherwise
+ * report io with record 1 already in the file, inviting a re-run and a
+ * duplicate. EIO and everything else still fail the append.
+ */
+const DIRECTORY_FSYNC_UNSUPPORTED = new Set(["EINVAL", "EBADF", "ENOTSUP", "EOPNOTSUPP"]);
+/**
+ * fsync a directory, so a name created in it survives a crash. Windows cannot
+ * open a directory for this and its filesystems journal names themselves, so it
+ * is skipped there, as is a filesystem that reports directory fsync as
+ * unsupported; everywhere else a failure is the caller's to report.
+ */
+function fsyncDirectory(dir) {
+    if (process.platform === "win32")
+        return;
+    const writeLayer = appendWriteLayer();
+    const fd = writeLayer.open(dir, fsConstants.O_RDONLY, 0);
+    try {
+        writeLayer.fsync(fd);
+    }
+    catch (cause) {
+        if (!DIRECTORY_FSYNC_UNSUPPORTED.has(cause.code ?? ""))
+            throw cause;
+    }
+    finally {
+        try {
+            writeLayer.close(fd);
+        }
+        catch {
+            // The fsync above is what mattered; a failed close of a read-only
+            // directory handle changes nothing on disk.
+        }
+    }
+}
+/**
+ * The directories whose entries a first append made new: the log's own
+ * directory (which gained the file), and, when `withAppendLock` had to create
+ * directories, the parent of each one it created, up to and including the
+ * parent of the topmost. Ordered innermost first.
+ */
+function directoriesToSync(logPath, firstCreatedDir) {
+    const dirs = [dirname(logPath)];
+    if (firstCreatedDir === undefined)
+        return dirs;
+    const stop = dirname(firstCreatedDir);
+    for (let dir = dirs[0]; dir !== stop;) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // the filesystem root: nothing above to sync
+        dirs.push(parent);
+        dir = parent;
+    }
+    return dirs;
+}
+/**
+ * How many times one wait may find, at its end, that the lock moved or that
+ * another writer is reclaiming it, and wait again, before it refuses.
+ */
+const MAX_RECLAIM_ROUNDS = 3;
 /**
  * Acquire `<logPath>.lock` by `open(…, "wx")` — atomic create-or-fail, which
- * needs no dependency and works on every platform Node supports. Retries with
- * a fixed delay until `timeoutMs` elapses, then reports `lock-timeout`. A
- * stale lock is never stolen: silently breaking someone else's lock is how two
- * writers end up sharing a `seq`.
+ * needs no dependency and works on every platform Node supports — and write
+ * this process's holder record into it (APRV-479). Retries with a fixed delay
+ * until `timeoutMs` elapses.
+ *
+ * A lock is never stolen from a holder that may be alive: silently breaking
+ * someone else's lock is how two writers end up sharing a `seq`. Only once the
+ * whole wait has passed does the writer judge the lock, once
+ * ({@link reclaimStaleLock}): a holder that is provably gone loses the lock to
+ * one atomic claim and take, and this writer then holds it with the reclaim to
+ * record first; a lock that moved, or that another writer is reclaiming, sends
+ * it back to wait again (at most {@link MAX_RECLAIM_ROUNDS} times); anything
+ * else is `lock-timeout`, whose message names the holder, why its lock was
+ * kept, and the human command.
+ *
+ * The termination-signal guard ({@link guardTerminationWhileLocked}) is
+ * installed BEFORE each create, so a lockfile never exists in this process
+ * without it, and is released and settled at once when the create fails, so
+ * the wait runs without it (a signal there kills the process holding nothing).
  */
-function acquireLock(logPath, timeoutMs, retryMs) {
+function acquireLock(logPath, timeoutMs, retryMs, op) {
     const path = `${logPath}.lock`;
-    const deadline = Date.now() + timeoutMs;
+    let deadline = Date.now() + timeoutMs;
+    let rounds = 0;
+    let kept;
+    // The lockfile as first refused in this wait (APRV-479 R3-8): an empty one
+    // is taken only if it is still that file when the wait ends.
+    let watched;
     for (;;) {
+        const releaseGuard = guardTerminationWhileLocked();
         try {
-            closeSync(openSync(path, "wx"));
-            return { ok: true, path };
+            return { ok: true, own: createLockFile(path, op), releaseGuard, reclaimed: null };
         }
         catch (cause) {
+            releaseGuard();
+            settleTerminationGuards();
             const code = cause.code;
             if (code !== "EEXIST") {
                 return {
@@ -161,26 +316,73 @@ function acquireLock(logPath, timeoutMs, retryMs) {
                     error: { code: "io", message: `lockfile ${path} could not be created: ${errorMessage(cause)}` },
                 };
             }
-            if (Date.now() >= deadline) {
-                return {
-                    ok: false,
-                    error: {
-                        code: "lock-timeout",
-                        message: `another writer holds ${path}; gave up after ${timeoutMs}ms`,
-                    },
-                };
-            }
+            if (watched === undefined)
+                watched = observeLock(logPath);
+        }
+        if (Date.now() < deadline) {
             sleepSync(retryMs);
+            continue;
+        }
+        if (rounds < MAX_RECLAIM_ROUNDS) {
+            rounds += 1;
+            const outcome = reclaimStaleLock(logPath, op, {
+                recordValid: reclaimRecordValid,
+                recordContext: () => reclaimRecordContext(logPath),
+                watched: watched ?? null,
+            });
+            if (outcome.kind === "taken") {
+                return { ok: true, own: outcome.own, releaseGuard: outcome.releaseGuard, reclaimed: outcome.note };
+            }
+            kept = outcome.why;
+            if (outcome.kind === "retry") {
+                deadline = Date.now() + timeoutMs;
+                watched = undefined;
+                continue;
+            }
         }
+        const holder = kept === undefined ? "" : ` (${kept})`;
+        return {
+            ok: false,
+            error: {
+                code: "lock-timeout",
+                // A zero timeout is a single try by request (APRV-478: a caller that
+                // waits for the lock on its own event loop), and "gave up after 0ms"
+                // would read as a writer that never tried.
+                message: timeoutMs <= 0
+                    ? `another writer holds ${path}; this append tried the lock once, as its caller asked, and did not wait${holder}`
+                    : `another writer holds ${path}; gave up after ${timeoutMs}ms${holder}`,
+            },
+        };
     }
 }
-function releaseLock(path) {
+/**
+ * Is `<logPath>.lock` present right now (APRV-478)?
+ *
+ * ADVISORY, and nothing else. It takes no lock, writes nothing, and authorizes
+ * nothing: the answer can be stale the instant it is returned. It exists so a
+ * caller that must not block its event loop (a harness hook between a grant and
+ * its spend, which has to stay answerable to a signal) can wait out another
+ * writer by sleeping on a timer, and only then make its one synchronous attempt
+ * (`lockTimeoutMs: 0`). That attempt is still {@link acquireLock}'s atomic
+ * create-or-fail, and the head is still compared under the lock, so a probe
+ * that said "free" and was wrong costs a refused attempt and never a shared
+ * `seq`. A probe that cannot stat the path answers `false`, and the attempt
+ * then meets the real error.
+ */
+export function appendLockHeld(logPath) {
+    return existsSync(`${logPath}.lock`);
+}
+/**
+ * Remove this process's own lockfile, and only it (APRV-479: a lockfile that is
+ * not the one this process wrote is somebody else's). Best effort: the lock is
+ * advisory and a failed unlink must not mask the append's own result.
+ */
+function releaseLock(own) {
     try {
-        unlinkSync(path);
+        releaseLockFile(own);
     }
     catch {
-        // Best effort: the lock is advisory and a failed unlink must not mask the
-        // append's own result.
+        // As above.
     }
 }
 /**
@@ -353,7 +555,8 @@ function readTail(logPath) {
             },
         };
     }
-    return { ok: true, tail: { seq, hash } };
+    const ts = record["ts"];
+    return { ok: true, tail: typeof ts === "string" ? { seq, hash, ts } : { seq, hash } };
 }
 /**
  * Evaluate the compare-and-append precondition against the tail read under the
@@ -385,8 +588,13 @@ function headPrecondition(logPath, expected, tail) {
  * Build a complete record from caller content plus chain state. Property
  * insertion order is irrelevant to the digest (JCS sorts keys) but is kept
  * readable here for anyone eyeballing the code.
+ *
+ * `daemon` comes from the writing process and never from `input`, which is why it
+ * is a parameter here rather than a member of {@link EventInput}: this function
+ * composes a record field by field, so there is no spelling of a caller's input
+ * that can put a `daemon` on a record.
  */
-function buildRecord(input, seq, prev) {
+function buildRecord(input, seq, prev, daemon) {
     const record = {
         seq,
         ts: input.ts,
@@ -396,6 +604,10 @@ function buildRecord(input, seq, prev) {
         prev,
         hash: "",
     };
+    // Beside `actor`, because it answers the same question about a different layer:
+    // who caused the event, and which process wrote it down.
+    if (daemon !== null)
+        record.daemon = daemon;
     if (input.task !== undefined)
         record.task = input.task;
     if (input.action_key !== undefined)
@@ -434,8 +646,17 @@ function buildRecord(input, seq, prev) {
  * guarantee that nobody else is appending while it works.
  */
 export function withAppendLock(logPath, run, options = {}) {
+    return lockedRun(logPath, () => run(), options, "hold");
+}
+/**
+ * {@link withAppendLock}, also telling `run` the first directory its `mkdir`
+ * created (`undefined` when the log's directory already existed), which the
+ * append needs to know which directory entries are new (APRV-440).
+ */
+function lockedRun(logPath, run, options, op) {
+    let firstCreatedDir;
     try {
-        mkdirSync(dirname(logPath), { recursive: true });
+        firstCreatedDir = mkdirSync(dirname(logPath), { recursive: true });
     }
     catch (cause) {
         return {
@@ -446,14 +667,147 @@ export function withAppendLock(logPath, run, options = {}) {
             },
         };
     }
-    const lock = acquireLock(logPath, options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, options.lockRetryMs ?? DEFAULT_LOCK_RETRY_MS);
+    const lock = acquireLock(logPath, options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, options.lockRetryMs ?? DEFAULT_LOCK_RETRY_MS, op);
     if (!lock.ok)
         return { ok: false, error: lock.error };
+    let reclaimWrote = false;
     try {
-        return { ok: true, value: run() };
+        try {
+            // A lock this writer took over from a dead holder is recorded first,
+            // before the caller reads the tail (APRV-479).
+            if (lock.reclaimed !== null) {
+                const recorded = recordReclaim(logPath, lock.reclaimed, "system:log", firstCreatedDir);
+                reclaimWrote = recorded.wrote;
+                if (!recorded.result.ok)
+                    return { ok: false, error: recorded.result.error };
+            }
+            return { ok: true, value: run(firstCreatedDir) };
+        }
+        finally {
+            releaseLock(lock.own);
+        }
+    }
+    finally {
+        lock.releaseGuard();
+        if (reclaimWrote)
+            noteAppend(logPath);
+    }
+}
+/** The `audit.lock_reclaimed` payload: the lockfile's base name, the reason, the age, and the strictly parsed holder. */
+function reclaimPayload(note) {
+    const payload = { lockfile: note.lockfile, reason: note.reason };
+    if (note.age_ms !== undefined)
+        payload["age_ms"] = note.age_ms;
+    if (note.holder !== undefined)
+        payload["holder"] = { pid: note.holder.pid, op: note.holder.op, created: note.holder.created };
+    return payload;
+}
+/**
+ * The write boundary's own verdict on the record a reclaim would append,
+ * computed before the reclaim is made: a reclaim whose record would be refused
+ * is not made.
+ */
+function reclaimRecordValid(note) {
+    try {
+        const record = buildRecord({ ts: systemClock(), event: "audit.lock_reclaimed", actor: "system:log", payload: reclaimPayload(note) }, 1, GENESIS_PREV, null);
+        return validate("event", record).ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether this writer could append the reclaim record now (APRV-479 R3-3): the
+ * two refusals {@link recordReclaim} would meet that the schema check cannot
+ * see, its daemon stamp and the log's tail, both read without the lock. A
+ * reclaim whose record would be refused is not made: the lock stays for a
+ * writer that can record it, and nothing is claimed or appended. When it
+ * could, the last record's `ts`, which bounds the holder `created` the record
+ * may carry (R3-7).
+ */
+function reclaimRecordContext(logPath) {
+    const stamp = daemonStampForAppend();
+    if (stamp.kind === "refuse")
+        return { ok: false, why: `its records are refused: ${stamp.code}` };
+    const tail = readTail(logPath);
+    if (!tail.ok) {
+        return { ok: false, why: `the log's tail refuses an append (${tail.error.code}), which a human repairs first; \`approval log verify\` shows where` };
+    }
+    const lastTs = tail.tail.ts === undefined ? Number.NaN : Date.parse(tail.tail.ts);
+    return { ok: true, lastTs: Number.isFinite(lastTs) ? lastTs : null };
+}
+/**
+ * The record of a lock taken over from a holder that is gone (APRV-479),
+ * appended as the first write under the lock that was taken: before the
+ * caller's own read of the tail, so the caller's compare-and-append sees it as
+ * the moved head it is. Written through the same path as every other record,
+ * with no head precondition (it decides nothing from the log) and the same
+ * daemon stamp. Only once it is in the log is the stale name removed; when it
+ * cannot be appended, nothing else is, and the stale name stays beside the lock
+ * as the evidence.
+ */
+function recordReclaim(logPath, note, actor, firstCreatedDir) {
+    const stamp = daemonStampForAppend();
+    if (stamp.kind === "refuse")
+        return { result: fail(stamp.code, stamp.message), wrote: false };
+    const daemon = stamp.kind === "stamp" ? stamp.id : null;
+    const recorded = appendUnderLock(logPath, { ts: systemClock(), event: "audit.lock_reclaimed", actor, payload: reclaimPayload(note) }, {}, firstCreatedDir, daemon);
+    if (recorded.result.ok) {
+        finishReclaim(note);
+        return recorded;
+    }
+    return {
+        result: {
+            ok: false,
+            error: {
+                ...recorded.result.error,
+                message: `${recorded.result.error.message} (${note.lockfile} was taken over from a holder that is gone, and the record of that could not be appended, so nothing else was; ${basename(note.stale)} is left beside the lock as the evidence)`,
+            },
+        },
+        wrote: recorded.wrote,
+    };
+}
+/**
+ * `approval log unlock --pid <n|none>` (APRV-479): a human takes over a lock no
+ * writer reclaims (another container, another boot, a holder that cannot be
+ * checked), with the same claim and take a writer's reclaim uses, and records
+ * it as `audit.lock_reclaimed` (reason `operator-cleared`) under their own
+ * `human:` actor as the first
+ * record under the lock taken. `pid` must be the pid the lockfile names, or
+ * `null` for one that names no holder. Human-only: the CLI resolves the actor,
+ * the schema refuses an `agent:` one, and the harness hook classifies the verb
+ * `policy.core`.
+ */
+export function unlockAppendLock(logPath, pid, actor) {
+    if (!existsSync(logPath)) {
+        return { kind: "refused", message: `${logPath} does not exist, so there is no log a record of the unlock could follow; remove ${basename(logPath)}.lock by hand` };
+    }
+    const context = reclaimRecordContext(logPath);
+    if (!context.ok) {
+        return { kind: "refused", message: `the record of the unlock could not be appended (${context.why}), so nothing was touched` };
+    }
+    const taken = takeLockForUnlock(logPath, pid, context.lastTs);
+    if (taken.kind === "none")
+        return { kind: "none" };
+    if (taken.kind === "refused")
+        return { kind: "refused", message: taken.why };
+    let wrote = false;
+    try {
+        try {
+            const recorded = recordReclaim(logPath, taken.note, actor, undefined);
+            wrote = recorded.wrote;
+            if (!recorded.result.ok)
+                return { kind: "failed", error: recorded.result.error };
+            return { kind: "unlocked", record: recorded.result.record, note: taken.note };
+        }
+        finally {
+            releaseLock(taken.own);
+        }
     }
     finally {
-        releaseLock(lock.path);
+        taken.releaseGuard();
+        if (wrote)
+            noteAppend(logPath);
     }
 }
 /**
@@ -467,7 +821,11 @@ export function withAppendLock(logPath, run, options = {}) {
  * not turn a written record into a failed one, so throws are swallowed.
  */
 const appendListeners = [];
-/** Subscribe to successful appends. Process-wide, memory-only, additive. */
+/**
+ * Subscribe to appends that put bytes in the file: every successful one, and
+ * since APRV-440 one that wrote and then failed to confirm them durable (a
+ * short write, a failed fsync). Process-wide, memory-only, additive.
+ */
 export function onLogAppended(listener) {
     appendListeners.push(listener);
 }
@@ -482,7 +840,44 @@ function noteAppend(logPath) {
     }
 }
 export function appendEvent(logPath, input, options = {}) {
-    const held = withAppendLock(logPath, () => {
+    // Which daemon is writing, and whether it may (APRV-383). Asked of this
+    // process's own state rather than of the caller, and asked BEFORE the lock
+    // because it reads no log state: taking a lock only to refuse would make every
+    // other writer wait for an answer that was never going to touch the file. It is
+    // the write boundary in the sense that matters — one code path, nothing written
+    // on the refused branch, and the record's own schema pins the field's shape so a
+    // malformed id could not land even if this check were absent.
+    const stamp = daemonStampForAppend();
+    if (stamp.kind === "refuse")
+        return fail(stamp.code, stamp.message);
+    const daemon = stamp.kind === "stamp" ? stamp.id : null;
+    // Set once bytes may reach the file, success or not: the read cache
+    // must re-prove a log whose bytes changed even when the append then failed to
+    // confirm them durable.
+    let wrote = false;
+    const held = lockedRun(logPath, (firstCreatedDir) => {
+        const appended = appendUnderLock(logPath, input, options, firstCreatedDir, daemon);
+        wrote = appended.wrote;
+        return appended.result;
+    }, options, "append");
+    const result = held.ok ? held.value : { ok: false, error: held.error };
+    // After the lock is released, for every append that put bytes in the file:
+    // the reader cache must not serve a prefix proof anchored before this write.
+    if (wrote)
+        noteAppend(logPath);
+    return result;
+}
+/**
+ * One append, with `<logPath>.lock` already held by this process: read the
+ * tail, compare the head, build, validate, write, fsync. The body of
+ * {@link appendEvent}, shared with the reclaim record (APRV-479) so that record
+ * goes through every check any other record does. `wrote` says whether bytes
+ * may have reached the file, success or not.
+ */
+function appendUnderLock(logPath, input, options, firstCreatedDir, daemon) {
+    let wrote = false;
+    const done = (result) => ({ result, wrote });
+    const run = () => {
         const tail = readTail(logPath);
         if (!tail.ok)
             return { ok: false, error: tail.error };
@@ -497,7 +892,7 @@ export function appendEvent(logPath, input, options = {}) {
         let record;
         let line;
         try {
-            record = buildRecord(input, tail.tail.seq + 1, tail.tail.hash);
+            record = buildRecord(input, tail.tail.seq + 1, tail.tail.hash, daemon);
             // Stored line = JCS of the complete record; digest input excluded `hash`.
             line = serializeRecord(record);
         }
@@ -512,35 +907,63 @@ export function appendEvent(logPath, input, options = {}) {
         if (!validation.ok) {
             return fail("validation", `event failed schema validation at the write boundary; log left unchanged`, validation.errors);
         }
-        let fd;
+        let opened;
         try {
-            fd = openSync(logPath, "a");
+            opened = openForAppend(logPath);
         }
         catch (cause) {
             return fail("io", `log ${logPath} could not be opened for append: ${errorMessage(cause)}`);
         }
+        const { fd, created } = opened;
+        const writeLayer = appendWriteLayer();
+        const bytes = Buffer.from(`${line}\n`, "utf8");
         try {
             // Single write syscall on an O_APPEND handle: the line lands whole or not at all.
-            writeSync(fd, `${line}\n`);
-        }
-        catch (cause) {
-            return fail("io", `log ${logPath} could not be written: ${errorMessage(cause)}`);
+            // Set BEFORE the write: one that throws may still have put bytes in the
+            // file, and a needless re-proof by the read cache costs only time.
+            wrote = true;
+            let written;
+            try {
+                written = writeLayer.write(fd, bytes);
+            }
+            catch (cause) {
+                return fail("io", `log ${logPath} could not be written: ${errorMessage(cause)}`);
+            }
+            if (written !== bytes.length) {
+                return fail("io", `log ${logPath} took ${String(written)} of ${String(bytes.length)} bytes of seq ${String(record.seq)}: the write was short, so the file now ends with a torn line and the record was not appended`);
+            }
+            // Durable before ok (guarantee 5b). Until this returns, the record exists
+            // in the page cache only, and a kill before writeback leaves the file
+            // extended over unwritten blocks: a NUL-filled tail where the record was.
+            try {
+                writeLayer.fsync(fd);
+            }
+            catch (cause) {
+                return fail("io", `log ${logPath}: seq ${String(record.seq)} was written but fsync failed (${errorMessage(cause)}), so it is not known to be durable: it may be in the file now and gone after a crash. Re-read the log before deciding anything from it.`);
+            }
         }
         finally {
             try {
-                closeSync(fd);
+                writeLayer.close(fd);
             }
             catch {
-                // Nothing actionable; the data is already handed to the kernel.
+                // Nothing actionable: the bytes are written and, on the ok path, synced.
+            }
+        }
+        // A new file is a new directory entry, and fsync of the file does not make
+        // its NAME durable: without this a crash can keep the bytes and lose the file.
+        if (created) {
+            for (const dir of directoriesToSync(logPath, firstCreatedDir)) {
+                try {
+                    fsyncDirectory(dir);
+                }
+                catch (cause) {
+                    return fail("io", `log ${logPath}: seq ${String(record.seq)} was written and synced but its directory ${dir} could not be (${errorMessage(cause)}), so the newly created file is not known to survive a crash. Re-read the log before deciding anything from it.`);
+                }
             }
         }
         return { ok: true, record, line };
-    }, options);
-    const result = held.ok ? held.value : { ok: false, error: held.error };
-    // After the lock is released and only for a record that actually landed: the
-    // reader cache must not serve a prefix proof anchored before this write.
-    if (result.ok)
-        noteAppend(logPath);
-    return result;
+    };
+    return done(run());
 }
 //# sourceMappingURL=log.js.map