approval-md 0.3.0 → 0.4.0

package/dist/src/core/harness-version.js

@@ -54,7 +54,14 @@
 import { spawnSync } from "node:child_process";
 import { childEnvironment } from "./child-env.js";
 /** The harnesses this runtime speaks a hook protocol for. */
-export const HARNESS_KINDS = ["claude-code", "cursor", "codex", "grok", "muse"];
+export const HARNESS_KINDS = [
+    "claude-code",
+    "cursor",
+    "codex",
+    "grok",
+    "muse",
+    "hermes",
+];
 /** Is `value` one of the harnesses this runtime knows? */
 export function isHarnessKind(value) {
     return typeof value === "string" && HARNESS_KINDS.includes(value);
@@ -71,6 +78,7 @@ export const HARNESS_BINARY = {
     codex: "codex",
     grok: "grok",
     muse: "muse",
+    hermes: "hermes",
 };
 /**
  * How long a version string may be, and the reason there is a cap at all.
@@ -121,7 +129,40 @@ export function normalizeHarnessVersion(raw) {
  */
 export const HARNESS_PROBE_TIMEOUT_MS = 10_000;
 /**
- * Run `<binary> --version` once, uncached, and normalize what came back.
+ * How long the RAW first line of `<binary> --version` may be.
+ *
+ * Wider than {@link HARNESS_VERSION_LIMIT} because it holds a different kind of
+ * value for a different reader: nothing capped by this number is ever appended to
+ * the log (only {@link normalizeHarnessVersion}'s output is), and what needs the
+ * raw line is a diagnostic that must be able to read a build stamp a harness
+ * prints beside its semver. Hermes prints
+ * `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`, which the log's own
+ * rule rejects on the non-ASCII separator alone. Capped and stripped of control
+ * characters all the same: this is third-party output on its way to a terminal.
+ */
+export const HARNESS_RAW_VERSION_LIMIT = 200;
+/**
+ * The first line of a `--version` output, as a line a diagnostic may print.
+ *
+ * One line, trimmed, control characters removed, capped. `null` for empty output
+ * or a line past the cap. It keeps non-ASCII bytes, which is the whole difference
+ * from {@link normalizeHarnessVersion}: a build stamp behind a typographic
+ * separator is exactly the fact a version floor has to read, and it is exactly
+ * the fact the write boundary will not accept.
+ */
+export function rawHarnessVersionLine(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const first = raw.split("\n", 1)[0] ?? "";
+    // `\p{Cc}` rather than an escaped range: the class is the Unicode CONTROL
+    // category, which is the thing being removed, and it reads as that.
+    const text = first.replace(/\p{Cc}/gu, "").trim();
+    if (text.length === 0 || text.length > HARNESS_RAW_VERSION_LIMIT)
+        return null;
+    return text;
+}
+/**
+ * Run `<binary> --version` once, uncached, and return its raw first line.
  *
  * Every failure is a value rather than an exception, in the manner of
  * {@link spawnGloss}: a missing binary, a non-zero exit and a timeout kill are
@@ -132,7 +173,7 @@ export const HARNESS_PROBE_TIMEOUT_MS = 10_000;
  * vault passphrase, and it has no use for either. Nothing is declared, because
  * reading a version is not a granted action.
  */
-export function probeHarnessVersion(kind) {
+export function probeHarnessVersionRaw(kind) {
     let result;
     try {
         result = spawnSync(HARNESS_BINARY[kind], ["--version"], {
@@ -150,32 +191,158 @@ export function probeHarnessVersion(kind) {
     }
     if (result.error !== undefined || result.status !== 0)
         return null;
-    return normalizeHarnessVersion(result.stdout);
+    return rawHarnessVersionLine(result.stdout);
+}
+/**
+ * Run `<binary> --version` once, uncached, and normalize what came back.
+ *
+ * The recordable form: one line, printable ASCII, capped. Exported for the test
+ * that proves the memo below is a memo.
+ */
+export function probeHarnessVersion(kind) {
+    return normalizeHarnessVersion(probeHarnessVersionRaw(kind));
 }
 /**
  * The memo. Holds the FAILURES too: a harness that is not on PATH is not on
  * PATH, and asking a second time in the same process would pay a second spawn
  * for the same `null`.
- */
-const probed = new Map();
-/**
- * The installed version of `kind`, read at most once per process.
  *
- * This is the only entry point callers should use. `probeHarnessVersion` is
- * exported for the test that proves the memo is a memo.
+ * It holds the RAW line rather than the recordable one, so the two readers — the
+ * provenance field and the version floor — still cost ONE spawn per process
+ * between them. A harness whose raw line the write boundary rejects has a
+ * `null` recordable version and a readable raw one, which is precisely Hermes's
+ * case and precisely why the floor is not read off a record.
  */
-export function installedHarnessVersion(kind) {
+const probed = new Map();
+/** The raw first line of `<binary> --version`, read at most once per process. */
+export function installedHarnessVersionRaw(kind) {
     const memo = probed.get(kind);
     if (memo !== undefined)
         return memo;
-    const value = probeHarnessVersion(kind);
+    const value = probeHarnessVersionRaw(kind);
     probed.set(kind, value);
     return value;
 }
+/**
+ * The installed version of `kind`, read at most once per process.
+ *
+ * This is the only entry point callers should use for a RECORDABLE version.
+ * `probeHarnessVersion` is exported for the test that proves the memo is a memo.
+ */
+export function installedHarnessVersion(kind) {
+    return normalizeHarnessVersion(installedHarnessVersionRaw(kind));
+}
 /** Drop the memo. TEST ONLY: a process reads a version once, by design. */
 export function resetHarnessVersionCache() {
     probed.clear();
 }
+// ---------------------------------------------------------------------------
+// The Hermes fail-closed version floor (APRV-415)
+// ---------------------------------------------------------------------------
+/**
+ * The build at which Hermes Agent starts honouring `fail_closed` (APRV-415).
+ *
+ * ## Why a floor exists at all, and why it is a DATE rather than a version
+ *
+ * `approval hook hermes` is enforcement rather than a backstop only because of a
+ * per-entry `fail_closed: true` that makes a hook crash, a hook timeout and
+ * unparseable hook output BLOCK. The live probe measured both halves of that on
+ * two builds of the same harness, and the answer differs between them:
+ *
+ * - `main` at `118984d7`, built 2026-09-20: crash, garbage and hang were all
+ *   REFUSED (the hang at the 300s per-entry cap). The key works;
+ * - `v0.21.3`, built 2026.9.14: all three PROCEEDED. That build does not know the
+ *   key and ignores it SILENTLY. `hermes hooks list` renders no `fail_closed`
+ *   flag on either build, so the listing cannot be used to tell them apart.
+ *
+ * The two builds report the SAME semver. `hermes --version` on the older one
+ * prints `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`, and the update
+ * that fixed the behaviour moved 670 commits without moving `0.21.3`. So a floor
+ * expressed as a semantic version would compare the one field that did not
+ * change, and would pass a build that fails open. The build DATE and the upstream
+ * commit are the two fields that did move, and they are what this compares.
+ *
+ * ## What it can and cannot do
+ *
+ * It can only ADD a red line to `approval doctor` (SPEC.md §11.1 invariant 4: a
+ * self-reported field never reduces scrutiny). A build claiming a later date buys
+ * nothing — it defeats a row that would have asked a human to look — and nothing
+ * in the runtime reads this to widen a verdict, skip a wait or lower a class. The
+ * refusals the adapter emits are the same on every build; what changes below the
+ * floor is whether a BROKEN hook stops the call, which no code in this repository
+ * can observe from inside the hook it is broken in.
+ */
+export const HERMES_FAIL_CLOSED_FLOOR = {
+    /** The first build observed to honour the key, by upstream commit. */
+    upstream: "118984d7",
+    /** That build's date, in the `YYYY.M.D` stamp `hermes --version` prints. */
+    date: { year: 2026, month: 9, day: 20 },
+    /** The one sentence every surface quotes, so they cannot drift apart. */
+    statement: "a build at or after main 118984d7 of 2026-09-20; v0.21.3 (2026.9.14) fails open silently",
+};
+/**
+ * Read the fields out of `hermes --version`'s first line, or `null`.
+ *
+ * Shape-only and forgiving in one direction: a field this cannot find is `null`
+ * rather than a guess, and a line naming none of the three is not a Hermes
+ * version line at all. The observed line is
+ * `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`; the separator is read
+ * past rather than required, because a release that changes its punctuation must
+ * not silently turn the floor check into an unknown.
+ */
+export function parseHermesVersion(raw) {
+    const line = rawHarnessVersionLine(raw);
+    if (line === null)
+        return null;
+    const semver = /\bv(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/u.exec(line);
+    const stamp = /\((\d{4})\.(\d{1,2})\.(\d{1,2})\)/u.exec(line);
+    const upstream = /\bupstream\s+([0-9a-f]{7,40})\b/iu.exec(line);
+    if (semver === null && stamp === null && upstream === null)
+        return null;
+    return {
+        semver: semver?.[1] ?? null,
+        date: stamp === null
+            ? null
+            : {
+                year: Number(stamp[1]),
+                month: Number(stamp[2]),
+                day: Number(stamp[3]),
+            },
+        upstream: upstream?.[1]?.toLowerCase() ?? null,
+    };
+}
+/**
+ * Does this Hermes build honour `fail_closed`?
+ *
+ * - `"honours"` — its upstream commit IS the floor's, or its build date is on or
+ *   after the floor's date;
+ * - `"ignores"` — its build date is BEFORE the floor's. This is the one answer
+ *   that names a fault, and it is the state a live probe measured rather than
+ *   inferred;
+ * - `"unknown"` — no version could be read, or the line carries neither a build
+ *   date nor the floor's commit. Two commit hashes cannot be ORDERED without a
+ *   repository, so a build stamped with an unfamiliar commit and no date is
+ *   honestly unknown rather than quietly either.
+ *
+ * `"unknown"` is not a synonym for `"ignores"`, deliberately. This value feeds a
+ * health check, and a health check that cried fault on every unreadable banner
+ * would train an operator to stop reading it, which costs more than the case it
+ * would catch. What guards the unknown case instead is the doc, the help block
+ * and the probe's own report, all of which state {@link
+ * HERMES_FAIL_CLOSED_FLOOR.statement} verbatim.
+ */
+export function hermesFailClosedSupport(raw) {
+    const fields = parseHermesVersion(raw);
+    if (fields === null)
+        return "unknown";
+    const floor = HERMES_FAIL_CLOSED_FLOOR;
+    if (fields.upstream !== null && fields.upstream.startsWith(floor.upstream))
+        return "honours";
+    if (fields.date === null)
+        return "unknown";
+    const asNumber = (date) => date.year * 10_000 + date.month * 100 + date.day;
+    return asNumber(fields.date) >= asNumber(floor.date) ? "honours" : "ignores";
+}
 /**
  * Build the pair for `kind`, preferring the version the hook event supplied.
  *

package/dist/src/core/harness-version.js.map

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

package/dist/src/core/harness-wait.d.ts

@@ -2,13 +2,16 @@
  * How long a harness hook waits, and how long the question it opened outlives
  * that wait (APRV-287).
  *
- * Two numbers with two readers each, which is the whole reason they live here
- * rather than beside either one. `cli/hook.ts` uses them to decide when a
- * request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
+ * Three numbers with two readers each, which is the whole reason they live
+ * here rather than beside any one of them. `cli/hook.ts` uses them to decide
+ * when a request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
  * to decide which pending requests on a listener's first cycle are stale enough
  * to collapse into one message. Two copies of the same duration would be two
  * answers to "is anybody still waiting on this", and the channel would collapse
  * questions the hook was still holding open, or leave a dead queue on a phone.
+ * The third, APRV-423's margin, is read by the hook (which refuses a harness
+ * ceiling too short to hold a human's answer) and by `core/state.ts` (which
+ * judges every request against the window that ceiling leaves).
  *
  * Nothing here reads a clock, a policy or the log: these are durations, and
  * every judgment made with them is made by a caller that already holds the
@@ -53,3 +56,79 @@ export declare const HOOK_RETRY_GRACE_MS: number;
  * caller states about when it started waiting.
  */
 export declare function abandonedAfterMs(waitMs: number, graceMs: number): number;
+/**
+ * How far below a harness's own timeout a hook-originated request must lapse
+ * (APRV-423).
+ *
+ * A harness bounds the hook process: Hermes caps a `pre_tool_call` entry at
+ * 300 s, Claude Code kills the hook at the `timeout` in its settings file, and
+ * every one of them treats the killed process as a NON-BLOCKING error and runs
+ * the tool call. So when the harness gives up first the hook is already gone,
+ * the request is still pending on somebody's phone, and the tap that arrives
+ * afterwards is recorded as a grant on a call nobody holds (APRV-410, observed
+ * 2026-09-20). The two records then disagree about the same moment: one says
+ * denied, the other says approved.
+ *
+ * The fix is to make the question end BEFORE the process that asked it does,
+ * and this is the distance between the two. It is 60 s because the daemon's
+ * TTL sweep runs on a 30 s interval (`daemon/daemon.ts`'s
+ * `DEFAULT_INTERVAL_MS`): a request that lapses one millisecond after a sweep
+ * waits a whole interval for the next one, so a margin of two intervals leaves
+ * the `approval.expired` append a full tick of room in the common case, and it
+ * lands inside the cap. Anything smaller would make the ordering this task is
+ * about depend on where in the sweep cycle the lapse fell.
+ *
+ * The common case, and not a guarantee. `Daemon.tick` skips a sweep when the
+ * previous tick is still running, and the request record's `ts` is stamped at
+ * the write boundary, some intake latency after the harness spawned the hook,
+ * so the cap runs from an instant slightly before the one the margin counts
+ * from. An overrunning tick plus a slow intake can put the `approval.expired`
+ * record after the kill. What keeps a late tap safe regardless is not this
+ * margin but the lazy refusal: `core/state.ts` judges the lapse by arithmetic
+ * whether or not the record exists, so `decide` refuses the tap `expired` and
+ * materialises the record then. The margin buys the ORDERING in the common
+ * case, so the two records agree without a human ever seeing the disagreement;
+ * the refusal is what makes the grant impossible in every case.
+ *
+ * It is a floor on the cap as well as a subtraction from it. A cap at or below
+ * the margin leaves no window in which a human could answer at all: `cli/hook.ts`
+ * refuses such a configuration rather than opening a question that is already
+ * dead, and `schema/event.schema.json` refuses a record carrying one at the
+ * write boundary (its `minimum` is this constant plus one, pinned equal by
+ * `tests/harness-cap-ttl.test.ts`).
+ */
+export declare const HARNESS_CAP_MARGIN_MS = 60000;
+/**
+ * The deadline a hook-originated request is judged by: the SHORTER of the
+ * policy's TTL and the harness's cap minus {@link HARNESS_CAP_MARGIN_MS}
+ * (APRV-423).
+ *
+ * `null` means no deadline, exactly as `defaults.approval_ttl`'s absence means
+ * it (SPEC.md §6): nothing lapses, and no duration is invented for a policy
+ * that declared none.
+ *
+ * **The cap may only shorten.** It is a self-reported field (the hook states
+ * the ceiling its own harness runs it under), and SPEC.md §11.1 invariant 4
+ * says such a field never reduces scrutiny. Recording it raw and taking the
+ * minimum HERE is what makes that structural: a cap larger than the policy TTL
+ * changes nothing, a cap of an hour under a one-minute TTL changes nothing, and
+ * the only direction a requester can move its own deadline is earlier. The same
+ * shape as `core/gate-window.ts`'s `expires_at`, which clamps a claimed window
+ * against the derived one for the same reason.
+ *
+ * A cap that does not clear the margin yields `0`, which reads as lapsed from
+ * the instant the request is written. That is the fail-closed answer for a
+ * harness whose ceiling leaves no room for a human, and it is unreachable
+ * through the write path: the hook refuses the configuration before it
+ * appends, and the event schema refuses the record for any caller that did
+ * not come through the hook.
+ */
+export declare function harnessCappedTtlMs(policyTtlMs: number | null, capMs: number | null): number | null;
+/**
+ * Does `capMs` leave a window a human could answer in?
+ *
+ * The one question `cli/hook.ts` asks before it opens a request under a cap.
+ * Strictly greater: a cap EQUAL to the margin yields a zero-length window,
+ * which is a question that expires as it is asked.
+ */
+export declare function harnessCapFitsMargin(capMs: number): boolean;

package/dist/src/core/harness-wait.js

@@ -2,13 +2,16 @@
  * How long a harness hook waits, and how long the question it opened outlives
  * that wait (APRV-287).
  *
- * Two numbers with two readers each, which is the whole reason they live here
- * rather than beside either one. `cli/hook.ts` uses them to decide when a
- * request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
+ * Three numbers with two readers each, which is the whole reason they live
+ * here rather than beside any one of them. `cli/hook.ts` uses them to decide
+ * when a request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
  * to decide which pending requests on a listener's first cycle are stale enough
  * to collapse into one message. Two copies of the same duration would be two
  * answers to "is anybody still waiting on this", and the channel would collapse
  * questions the hook was still holding open, or leave a dead queue on a phone.
+ * The third, APRV-423's margin, is read by the hook (which refuses a harness
+ * ceiling too short to hold a human's answer) and by `core/state.ts` (which
+ * judges every request against the window that ceiling leaves).
  *
  * Nothing here reads a clock, a policy or the log: these are durations, and
  * every judgment made with them is made by a caller that already holds the
@@ -55,4 +58,87 @@ export const HOOK_RETRY_GRACE_MS = 5 * 60_000;
 export function abandonedAfterMs(waitMs, graceMs) {
     return Math.max(0, waitMs) + Math.max(0, graceMs);
 }
+/**
+ * How far below a harness's own timeout a hook-originated request must lapse
+ * (APRV-423).
+ *
+ * A harness bounds the hook process: Hermes caps a `pre_tool_call` entry at
+ * 300 s, Claude Code kills the hook at the `timeout` in its settings file, and
+ * every one of them treats the killed process as a NON-BLOCKING error and runs
+ * the tool call. So when the harness gives up first the hook is already gone,
+ * the request is still pending on somebody's phone, and the tap that arrives
+ * afterwards is recorded as a grant on a call nobody holds (APRV-410, observed
+ * 2026-09-20). The two records then disagree about the same moment: one says
+ * denied, the other says approved.
+ *
+ * The fix is to make the question end BEFORE the process that asked it does,
+ * and this is the distance between the two. It is 60 s because the daemon's
+ * TTL sweep runs on a 30 s interval (`daemon/daemon.ts`'s
+ * `DEFAULT_INTERVAL_MS`): a request that lapses one millisecond after a sweep
+ * waits a whole interval for the next one, so a margin of two intervals leaves
+ * the `approval.expired` append a full tick of room in the common case, and it
+ * lands inside the cap. Anything smaller would make the ordering this task is
+ * about depend on where in the sweep cycle the lapse fell.
+ *
+ * The common case, and not a guarantee. `Daemon.tick` skips a sweep when the
+ * previous tick is still running, and the request record's `ts` is stamped at
+ * the write boundary, some intake latency after the harness spawned the hook,
+ * so the cap runs from an instant slightly before the one the margin counts
+ * from. An overrunning tick plus a slow intake can put the `approval.expired`
+ * record after the kill. What keeps a late tap safe regardless is not this
+ * margin but the lazy refusal: `core/state.ts` judges the lapse by arithmetic
+ * whether or not the record exists, so `decide` refuses the tap `expired` and
+ * materialises the record then. The margin buys the ORDERING in the common
+ * case, so the two records agree without a human ever seeing the disagreement;
+ * the refusal is what makes the grant impossible in every case.
+ *
+ * It is a floor on the cap as well as a subtraction from it. A cap at or below
+ * the margin leaves no window in which a human could answer at all: `cli/hook.ts`
+ * refuses such a configuration rather than opening a question that is already
+ * dead, and `schema/event.schema.json` refuses a record carrying one at the
+ * write boundary (its `minimum` is this constant plus one, pinned equal by
+ * `tests/harness-cap-ttl.test.ts`).
+ */
+export const HARNESS_CAP_MARGIN_MS = 60_000;
+/**
+ * The deadline a hook-originated request is judged by: the SHORTER of the
+ * policy's TTL and the harness's cap minus {@link HARNESS_CAP_MARGIN_MS}
+ * (APRV-423).
+ *
+ * `null` means no deadline, exactly as `defaults.approval_ttl`'s absence means
+ * it (SPEC.md §6): nothing lapses, and no duration is invented for a policy
+ * that declared none.
+ *
+ * **The cap may only shorten.** It is a self-reported field (the hook states
+ * the ceiling its own harness runs it under), and SPEC.md §11.1 invariant 4
+ * says such a field never reduces scrutiny. Recording it raw and taking the
+ * minimum HERE is what makes that structural: a cap larger than the policy TTL
+ * changes nothing, a cap of an hour under a one-minute TTL changes nothing, and
+ * the only direction a requester can move its own deadline is earlier. The same
+ * shape as `core/gate-window.ts`'s `expires_at`, which clamps a claimed window
+ * against the derived one for the same reason.
+ *
+ * A cap that does not clear the margin yields `0`, which reads as lapsed from
+ * the instant the request is written. That is the fail-closed answer for a
+ * harness whose ceiling leaves no room for a human, and it is unreachable
+ * through the write path: the hook refuses the configuration before it
+ * appends, and the event schema refuses the record for any caller that did
+ * not come through the hook.
+ */
+export function harnessCappedTtlMs(policyTtlMs, capMs) {
+    if (capMs === null)
+        return policyTtlMs;
+    const fromCap = Math.max(0, capMs - HARNESS_CAP_MARGIN_MS);
+    return policyTtlMs === null ? fromCap : Math.min(policyTtlMs, fromCap);
+}
+/**
+ * Does `capMs` leave a window a human could answer in?
+ *
+ * The one question `cli/hook.ts` asks before it opens a request under a cap.
+ * Strictly greater: a cap EQUAL to the margin yields a zero-length window,
+ * which is a question that expires as it is asked.
+ */
+export function harnessCapFitsMargin(capMs) {
+    return capMs > HARNESS_CAP_MARGIN_MS;
+}
 //# sourceMappingURL=harness-wait.js.map

package/dist/src/core/harness-wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"harness-wait.js","sourceRoot":"","sources":["../../../src/core/harness-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"harness-wait.js","sourceRoot":"","sources":["../../../src/core/harness-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAA0B,EAC1B,KAAoB;IAEpB,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,qBAAqB,CAAC,CAAC;IAC3D,OAAO,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,GAAG,qBAAqB,CAAC;AACvC,CAAC"}

package/dist/src/core/log-subscribe.d.ts

@@ -25,6 +25,27 @@ export interface LogSubscriptionOptions {
     signal?: AbortSignal;
     /** Bounded fallback when filesystem notifications are missing. */
     pollIntervalMs?: number;
+    /**
+     * Drain the currently verified snapshot and RETURN, rather than waiting for
+     * appends (APRV-421).
+     *
+     * The streaming form is what `approval log follow` wants: a foreground
+     * process that stays. A PAGED reader wants the opposite and has nowhere to
+     * put a wait. `approval serve`'s `log/follow` answers one request with the
+     * records after a cursor and the cursor they end at, and the caller comes
+     * back with that cursor when it wants more. Expressing "we are caught up" as
+     * a race between the iterator and a timer is a timing heuristic; expressing
+     * it here is one flag, because this module already knows exactly when the
+     * verified snapshot is exhausted.
+     *
+     * It changes nothing about what is emitted or what is refused. The
+     * genesis-to-head verification, the cursor binding, the retained hash and
+     * every terminal failure are the ones below; this decides only whether the
+     * generator waits after the drain or ends. No watcher is established either,
+     * which matters for the caller this exists for: a server that left one file
+     * watcher behind per request would leak handles at the rate it is polled.
+     */
+    once?: boolean;
 }
 /**
  * Yield verified records after an exclusive cursor, then wait for appends.

package/dist/src/core/log-subscribe.js

@@ -86,12 +86,16 @@ export async function* subscribeVerifiedLog(logPath, options = {}) {
     options.signal?.addEventListener("abort", abort, { once: false });
     // Watch the directory so creation of an initially absent log is visible.
     // Failure to establish a watch is harmless: bounded polling remains active.
-    try {
-        watcher = watch(dirname(logPath), { persistent: false }, hint);
-        watcher.on("error", hint);
-    }
-    catch {
-        watcher = null;
+    // A `once` subscription never reaches the wait below, so it establishes no
+    // watch at all rather than opening and closing one per call.
+    if (options.once !== true) {
+        try {
+            watcher = watch(dirname(logPath), { persistent: false }, hint);
+            watcher.on("error", hint);
+        }
+        catch {
+            watcher = null;
+        }
     }
     try {
         while (!options.signal?.aborted) {
@@ -131,6 +135,12 @@ export async function* subscribeVerifiedLog(logPath, options = {}) {
             }
             if (options.signal?.aborted)
                 return;
+            // The verified snapshot is exhausted and this caller asked for exactly
+            // that much (APRV-421). Everything above ran unchanged: the chain was
+            // verified from genesis, the cursor was bound, and a mismatch already
+            // threw. What is skipped is only the waiting.
+            if (options.once === true)
+                return;
             // An append between watcher setup/read/drain and this point changes the
             // version and causes an immediate verification instead of a lost wakeup.
             if (wakeVersion !== versionBeforeRead)

package/dist/src/core/log-subscribe.js.map

@@ -1 +1 @@
-{"version":3,"file":"log-subscribe.js","sourceRoot":"","sources":["../../../src/core/log-subscribe.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,EAAkB,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,UAAU,EAA4B,MAAM,aAAa,CAAC;AAInE,gFAAgF;AAChF,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAA6B;IACjC,MAAM,CAAiD;IAEhE,YACE,IAAgC,EAChC,OAAe,EACf,MAAM,GAAmD,IAAI;QAE7D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAaD,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,SAAS,YAAY,CAAC,OAAe;IACnC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAClE,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,oBAAoB,CAAC,IAAI,EAAE,OAAO,OAAO,uBAAuB,MAAM,EAAE,CAAC,CAAC;IACtF,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,OAAe;IACtC,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5D,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAC3C,MAAM,IAAI,oBAAoB,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACzC,MAAM,IAAI,oBAAoB,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC;AAED,SAAS,eAAe,CAAC,OAA+B;IAKtD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,SAAS,CAAC,iDAAiD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,IAAI,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;QAC1F,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;IAC1E,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CACjB,uDAAuD,MAAM,CAAC,cAAc,CAAC,EAAE,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,cAAc,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,oBAAoB,CACzC,OAAe,EACf,OAAO,GAA2B,EAAE;IAEpC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC;IAC5B,IAAI,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC;IACrC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,IAAI,GAAwB,IAAI,CAAC;IACrC,IAAI,OAAO,GAAqB,IAAI,CAAC;IACrC,IAAI,KAAK,GAAyC,IAAI,CAAC;IAEvD,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,WAAW,IAAI,CAAC,CAAC;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC;QACrB,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO,EAAE,EAAE,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,GAAS,EAAE,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAElE,yEAAyE;IACzE,4EAA4E;IAC5E,IAAI,CAAC;QACH,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAC/D,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAChC,MAAM,iBAAiB,GAAG,WAAW,CAAC;YACtC,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,OAAO,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;YAEzC,IAAI,SAAS,GAAG,OAAO,EAAE,CAAC;gBACxB,MAAM,IAAI,oBAAoB,CAC5B,WAAW,EACX,OAAO,OAAO,gBAAgB,MAAM,CAAC,OAAO,CAAC,oCAAoC,MAAM,CAAC,SAAS,CAAC,mEAAmE,EACrK,iBAAiB,CAClB,CAAC;YACJ,CAAC;YACD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;gBAClB,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;gBACtC,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,EAAE,CAAC;oBACrF,MAAM,IAAI,oBAAoB,CAC5B,WAAW,EACX,OAAO,OAAO,2CAA2C,MAAM,CAAC,SAAS,CAAC,GACxE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,UAAU,EACrD,0EAA0E,EAC1E,iBAAiB,CAClB,CAAC;gBACJ,CAAC;gBACD,oEAAoE;gBACpE,mEAAmE;gBACnE,uEAAuE;gBACvE,UAAU,KAAK,MAAM,CAAC,IAAI,CAAC;YAC7B,CAAC;YAED,yEAAyE;YACzE,wEAAwE;YACxE,KAAK,IAAI,KAAK,GAAG,SAAS,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC/D,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;oBAAE,OAAO;gBACpC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC9B,IAAI,MAAM,KAAK,SAAS;oBAAE,MAAM;gBAChC,iEAAiE;gBACjE,qEAAqE;gBACrE,uEAAuE;gBACvE,kCAAkC;gBAClC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC;gBAC/B,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC;gBACjC,MAAM,MAAM,CAAC;gBACb,SAAS,GAAG,WAAW,CAAC;gBACxB,UAAU,GAAG,YAAY,CAAC;YAC5B,CAAC;YAED,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;gBAAE,OAAO;YACpC,wEAAwE;YACxE,yEAAyE;YACzE,IAAI,WAAW,KAAK,iBAAiB;gBAAE,SAAS;YAEhD,MAAM,iBAAiB,GAAG,WAAW,CAAC;YACtC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,IAAI,GAAG,OAAO,CAAC;gBACf,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;gBAChD,mEAAmE;gBACnE,qEAAqE;gBACrE,gEAAgE;gBAChE,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,WAAW,KAAK,iBAAiB;oBAAE,IAAI,EAAE,CAAC;YAC3E,CAAC,CAAC,CAAC;YACH,IAAI,KAAK,KAAK,IAAI;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,KAAK,KAAK,IAAI;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO,EAAE,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}
+{"version":3,"file":"log-subscribe.js","sourceRoot":"","sources":["../../../src/core/log-subscribe.ts"],"names":[],"mappings":"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"}

package/dist/src/core/log-write-layer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The filesystem calls that put durable bytes on disk: `core/log.ts`'s append
+ * (APRV-440) and `core/payload-store.ts`'s atomic write (APRV-457). They are
+ * kept in their own module so that `core/log.ts`'s public surface stays what
+ * `tests/log.test.ts` pins: no mutation, no reorder, no truncate, and no way to
+ * change how its bytes reach the disk.
+ *
+ * Why a seam at all. The durability claim is "fsync after the write and before
+ * ok", and a page cache that was flushed reads back exactly like one that was
+ * not until the machine dies. Only a layer that records the ORDER of the calls
+ * can prove the claim, so `tests/log-fsync.test.ts` and
+ * `tests/payload-fsync.test.ts` install one that records every call and then
+ * delegates to the real one, which keeps each log they build a real log built
+ * through the real append path.
+ *
+ * One seam for both writers, deliberately. A log record is only as durable as
+ * the payload it binds: a record that survives a crash while its payload comes
+ * back NUL-filled verifies and points at nothing (APRV-457). Proving the two
+ * through one layer keeps one model of "what reached the disk" for both.
+ *
+ * Nothing in `src/` calls {@link setAppendWriteLayerForTests}. It changes how
+ * the bytes reach the disk and nothing about which bytes, so every check before
+ * the write (lock, tail, compare-and-append, schema, payload hashing) runs as in
+ * production.
+ */
+export interface AppendWriteLayer {
+    /** `open(2)` with numeric flags; throws like `fs.openSync`. */
+    open(path: string, flags: number, mode: number): number;
+    /** One `write(2)` of the whole buffer; returns the bytes written. */
+    write(fd: number, data: Buffer): number;
+    /** `fsync(2)` of a file or directory descriptor; throws on failure. */
+    fsync(fd: number): void;
+    close(fd: number): void;
+    /**
+     * `rename(2)`; throws like `fs.renameSync`. Used by the payload store's
+     * temp-then-rename write (APRV-457); the log append never renames.
+     */
+    rename(from: string, to: string): void;
+}
+/** The layer the next append (or payload store write) uses. */
+export declare function appendWriteLayer(): AppendWriteLayer;
+/**
+ * Replace the append's write layer, or restore Node's with `null`. For tests
+ * and the opt-in benchmarks only.
+ */
+export declare function setAppendWriteLayerForTests(layer: AppendWriteLayer | null): void;
+/**
+ * fsync a directory through the current layer, so a name created or renamed
+ * into it survives a crash. Skipped on Windows (a directory cannot be opened
+ * for this there, and its filesystems journal names themselves) and tolerated
+ * where the filesystem reports directory fsync as unsupported; every other
+ * failure throws for the caller to report. The read-only handle is closed even
+ * when the fsync throws.
+ */
+export declare function fsyncDirectory(dir: string): void;