approval-md 0.0.1 → 0.2.0

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

@@ -0,0 +1,211 @@
+/**
+ * Which harness binary issued a hook-written record (APRV-227).
+ *
+ * ## The hole
+ *
+ * A harness upgrade — `claude update`, a global npm install, an unattended
+ * updater on a launchd timer — swaps the binary that hosts the PreToolUse hook
+ * without a line anywhere. A new harness release can change the hook envelope
+ * semantics and quietly stop the gate firing, and the first evidence would be
+ * an action nobody was asked about. The gate cannot stop a person upgrading
+ * their own machine, and should not. What it can do is notice the effect: the
+ * records the hook writes name the harness that issued them, and `approval
+ * doctor` says so when the installed binary no longer matches the last one the
+ * log saw.
+ *
+ * ## What this field is, and what it is emphatically not
+ *
+ * It is INFORMATIONAL. Nothing in the runtime reads it back as an input:
+ * no class resolution, no irreversibility floor, no loop-escalation streak, no
+ * budget arithmetic, no sampling draw. SPEC.md §11.1 invariant 4 says a
+ * self-reported field never reduces scrutiny, and the discipline that keeps
+ * that true here is that the value has exactly one reader — a doctor row that
+ * can only ADD a red line — and exactly one direction it can move a human's
+ * attention, which is toward the log rather than away from it. A harness that
+ * lies about its own version buys itself nothing: the row it defeats is a row
+ * that would have asked for a look.
+ *
+ * It is also OPTIONAL and additive. A record written before the field existed
+ * carries neither half and still validates and still verifies; a hook that
+ * cannot establish a version writes neither half rather than a guess.
+ *
+ * ## Where the value comes from, in order
+ *
+ * 1. The hook event's own version field, where the harness supplies one.
+ *    Claude Code's PreToolUse event may carry it; Cursor's does not.
+ * 2. `<binary> --version`, read at most ONCE per process ({@link
+ *    installedHarnessVersion} memoizes, including the failures) with a short
+ *    hard timeout.
+ * 3. Absent.
+ *
+ * Step 2 is why this module is careful about cost. A hook process exists per
+ * gated tool call, and APRV-186/188/212 each removed a term from what that
+ * process pays. So the probe is reached only on a path that is about to WRITE a
+ * record — a registration or a bypass — and never on the pass-through path that
+ * answers `cat README.md`. The memo makes a multi-class command pay once.
+ *
+ * ## Why the binary name is not configurable
+ *
+ * `cli/gloss.ts` already settled this: a runtime that let a policy or an
+ * environment variable name the executable it runs would have invented a new
+ * way to be told what to execute. The map below is the whole list, PATH is the
+ * only seam, and a test puts a stub binary in front of it.
+ */
+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"];
+/** Is `value` one of the harnesses this runtime knows? */
+export function isHarnessKind(value) {
+    return typeof value === "string" && HARNESS_KINDS.includes(value);
+}
+/**
+ * The executable each harness installs on PATH.
+ *
+ * Not configurable, deliberately (see the header). A harness whose binary is
+ * not one of these has no version to read here, and the field is simply absent.
+ */
+export const HARNESS_BINARY = {
+    "claude-code": "claude",
+    cursor: "cursor-agent",
+    codex: "codex",
+};
+/**
+ * How long a version string may be, and the reason there is a cap at all.
+ *
+ * `<binary> --version` is the output of a third-party process, and this value
+ * is appended to an append-only log. SPEC.md §11.1 invariant 3 has no exception
+ * for provenance: a field that accepted arbitrary bytes is a field where a
+ * banner, a stack trace, or the credential quoted inside one arrives and stays
+ * forever. So the write boundary takes one line, printable ASCII only, capped.
+ */
+export const HARNESS_VERSION_LIMIT = 64;
+/** Printable ASCII, no control characters, no newline. The schema pins the same. */
+const PRINTABLE = /^[\x20-\x7e]+$/u;
+/**
+ * The one spelling of a harness version this runtime ever writes or compares.
+ *
+ * First line, trimmed, and nothing else: `claude --version` prints
+ * `2.0.14 (Claude Code)` and a future release may add a second line of banner.
+ * Both the hook (which records) and doctor (which compares) call this, so the
+ * comparison is between two values normalized identically — a row that failed
+ * because one side kept a trailing newline would be a false alarm, and a false
+ * alarm in a health check trains an operator to ignore it.
+ *
+ * Returns `null` for anything that is not a usable version: empty output, a
+ * line that is not printable ASCII, or one longer than the cap. Absence is
+ * always available and always honest.
+ */
+export function normalizeHarnessVersion(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const first = raw.split("\n", 1)[0] ?? "";
+    const text = first.trim();
+    if (text.length === 0 || text.length > HARNESS_VERSION_LIMIT)
+        return null;
+    return PRINTABLE.test(text) ? text : null;
+}
+/**
+ * How long the probe may take before it is killed and reported as absent.
+ *
+ * A bound against a HUNG binary, not a latency target: `<binary> --version`
+ * answers in milliseconds on any machine that is not already in trouble, and
+ * this number is only ever reached by one that is. It is generous for the same
+ * reason `cli/gloss.ts`'s is (20s there): a timeout tuned to a healthy machine
+ * turns a loaded one into a silent, intermittent absence, and an absence that
+ * appears under load is the least useful failure a provenance field could have.
+ * The cost is bounded by the fact that this runs only where a record is being
+ * written, and at most once per process.
+ */
+export const HARNESS_PROBE_TIMEOUT_MS = 10_000;
+/**
+ * Run `<binary> --version` once, uncached, and normalize what came back.
+ *
+ * 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
+ * all reported on the result object, and all of them are simply "no version".
+ *
+ * The child is STARVED, for the reason the gloss runner is: this is a
+ * third-party CLI spawned by a process that may be holding a bot token and a
+ * 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) {
+    let result;
+    try {
+        result = spawnSync(HARNESS_BINARY[kind], ["--version"], {
+            encoding: "utf8",
+            env: childEnvironment().env,
+            timeout: HARNESS_PROBE_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+            // A version is a few dozen bytes. A binary that answers with a megabyte
+            // is a binary whose answer is dropped rather than buffered.
+            maxBuffer: 64 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (result.error !== undefined || result.status !== 0)
+        return null;
+    return normalizeHarnessVersion(result.stdout);
+}
+/**
+ * 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.
+ */
+export function installedHarnessVersion(kind) {
+    const memo = probed.get(kind);
+    if (memo !== undefined)
+        return memo;
+    const value = probeHarnessVersion(kind);
+    probed.set(kind, value);
+    return value;
+}
+/** Drop the memo. TEST ONLY: a process reads a version once, by design. */
+export function resetHarnessVersionCache() {
+    probed.clear();
+}
+/**
+ * Build the pair for `kind`, preferring the version the hook event supplied.
+ *
+ * `eventVersion` is whatever the harness put in its own event, unvalidated:
+ * it goes through {@link normalizeHarnessVersion} exactly as the probe's
+ * output does, because it arrives from the same untrusted side of the boundary
+ * and the write boundary does not have two standards.
+ */
+export function harnessProvenance(kind, eventVersion = null) {
+    const stated = normalizeHarnessVersion(eventVersion);
+    const version = stated ?? installedHarnessVersion(kind);
+    return version === null ? null : { harness: kind, harness_version: version };
+}
+/**
+ * The provenance pair carried by an already-written record's payload, or
+ * `null` when it carries none (or carries half of one).
+ *
+ * The read side of the same contract, used by `approval doctor`. Strict on
+ * purpose: a record whose `harness` is a string this runtime does not know is a
+ * record from a harness this build cannot probe, so it is not evidence about
+ * any binary here and is skipped rather than guessed at.
+ */
+export function readHarnessProvenance(payload) {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+        return null;
+    const fields = payload;
+    const kind = fields["harness"];
+    if (!isHarnessKind(kind))
+        return null;
+    const version = fields["harness_version"];
+    if (typeof version !== "string" || normalizeHarnessVersion(version) !== version)
+        return null;
+    return { harness: kind, harness_version: version };
+}
+//# sourceMappingURL=harness-version.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,55 @@
+/**
+ * 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
+ * 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.
+ *
+ * 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
+ * instant it is judging against.
+ */
+/**
+ * The hook's default wait, chosen to sit inside Claude Code's own 60s hook
+ * default. The string form is what the flag parser takes; the millisecond form
+ * is what a comparison takes.
+ */
+export declare const HOOK_DEFAULT_WAIT = "55s";
+/** {@link HOOK_DEFAULT_WAIT} in milliseconds. */
+export declare const HOOK_DEFAULT_WAIT_MS = 55000;
+/**
+ * How long a request outlives the wait that opened it, before the hook takes it
+ * back (APRV-287).
+ *
+ * The window exists for exactly one thing: the retry. A hook whose wait expires
+ * leaves its question open because a decision inside the policy's TTL still
+ * authorizes an identical retry of the identical command (APRV-117), and the
+ * agent that was denied usually retries within a minute or two. So the question
+ * stays live for that long and no longer.
+ *
+ * Past it, nobody is coming back for the answer. The request was accruing on an
+ * approver's phone as one more message a restarted listener would re-deliver,
+ * and on 2026-09-06 a dozen of those arrived at once behind a dead daemon. A
+ * request nothing will adopt is withdrawn (reason `timeout`), which authorizes
+ * nothing, refuses a late tap in the approver's own words, and leaves the log
+ * saying exactly what happened: the asker gave up.
+ *
+ * Five minutes because it is longer than any retry loop this runtime has been
+ * observed to take and shorter than the shortest TTL an operator is likely to
+ * write. It is a default: `--retry-grace` moves it per invocation, and `0`
+ * withdraws at the moment the wait expires.
+ */
+export declare const HOOK_RETRY_GRACE_MS: number;
+/**
+ * How old a request opened under `waitMs` must be before the grace has run out.
+ *
+ * Measured from the `approval.requested` record's own timestamp, which is the
+ * instant the runtime wrote at the write boundary, and never from anything a
+ * caller states about when it started waiting.
+ */
+export declare function abandonedAfterMs(waitMs: number, graceMs: number): number;

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

@@ -0,0 +1,58 @@
+/**
+ * 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
+ * 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.
+ *
+ * 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
+ * instant it is judging against.
+ */
+/**
+ * The hook's default wait, chosen to sit inside Claude Code's own 60s hook
+ * default. The string form is what the flag parser takes; the millisecond form
+ * is what a comparison takes.
+ */
+export const HOOK_DEFAULT_WAIT = "55s";
+/** {@link HOOK_DEFAULT_WAIT} in milliseconds. */
+export const HOOK_DEFAULT_WAIT_MS = 55_000;
+/**
+ * How long a request outlives the wait that opened it, before the hook takes it
+ * back (APRV-287).
+ *
+ * The window exists for exactly one thing: the retry. A hook whose wait expires
+ * leaves its question open because a decision inside the policy's TTL still
+ * authorizes an identical retry of the identical command (APRV-117), and the
+ * agent that was denied usually retries within a minute or two. So the question
+ * stays live for that long and no longer.
+ *
+ * Past it, nobody is coming back for the answer. The request was accruing on an
+ * approver's phone as one more message a restarted listener would re-deliver,
+ * and on 2026-09-06 a dozen of those arrived at once behind a dead daemon. A
+ * request nothing will adopt is withdrawn (reason `timeout`), which authorizes
+ * nothing, refuses a late tap in the approver's own words, and leaves the log
+ * saying exactly what happened: the asker gave up.
+ *
+ * Five minutes because it is longer than any retry loop this runtime has been
+ * observed to take and shorter than the shortest TTL an operator is likely to
+ * write. It is a default: `--retry-grace` moves it per invocation, and `0`
+ * withdraws at the moment the wait expires.
+ */
+export const HOOK_RETRY_GRACE_MS = 5 * 60_000;
+/**
+ * How old a request opened under `waitMs` must be before the grace has run out.
+ *
+ * Measured from the `approval.requested` record's own timestamp, which is the
+ * instant the runtime wrote at the write boundary, and never from anything a
+ * caller states about when it started waiting.
+ */
+export function abandonedAfterMs(waitMs, graceMs) {
+    return Math.max(0, waitMs) + Math.max(0, graceMs);
+}
+//# sourceMappingURL=harness-wait.js.map

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

@@ -0,0 +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"}

package/dist/src/core/head-retry.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The bounded head-moved retry, in one place (APRV-150, APRV-236).
+ *
+ * ## The fact this module is about
+ *
+ * `core/log.ts` takes a compare-and-append precondition: a writer states the
+ * `(seq, hash)` its checks were made against, and the append is refused under
+ * the lock when the tail is something else. That refusal is `append-failed`
+ * with `append.code === "head-moved"`, and it is correct: every read-dependent
+ * check that authorized the write is stale.
+ *
+ * Stale is not the same as wrong. A moved head says the verdict must be
+ * computed again; it does not say what the verdict is. Treating the two as the
+ * same is what turned a busy log into a lottery, twice:
+ *
+ *  - 2026-08-29 (APRV-150): a session's first `git status` — class `read.shell`,
+ *    autonomous, no human anywhere near it — was denied by the Claude Code hook
+ *    because an unrelated record landed a few milliseconds earlier.
+ *  - 2026-09-02 (APRV-236): `approval grant` refused a human's decision with
+ *    `head moved: expected seq 14218, found 14219` while two lanes and the
+ *    daemon were appending. The human ran it again. Twice more.
+ *
+ * The second one is the worse of the two, because the caller it handed the
+ * retry to was a person. A compare-and-append refusal is a fact about timing
+ * rather than about authority, and asking a human to retype is the wrong party
+ * to hand it to.
+ *
+ * ## What a retry is here, and what it is not
+ *
+ * The unit of retry is the WHOLE read-check-append cycle: a new read of the
+ * verified log, a new read of the policy, a fresh attestation, a fresh
+ * derivation of the request's state, fresh escalation, single-use, intake and
+ * budget checks, and a new append against the head that the new read observed.
+ * Nothing crosses an attempt except the caller's own inputs.
+ *
+ * The append is never retried on its own. That distinction is the whole safety
+ * argument, and it is worth stating as three properties:
+ *
+ *  - **compare-and-append is untouched.** Every attempt supplies the head it
+ *    read, and a stale write is still refused under the lock. SPEC.md §11.1
+ *    invariant 5 holds per attempt, which is where it has to hold.
+ *  - **A changed verdict is the new verdict.** If the record that moved the head
+ *    decided the request, spent the key, exhausted the budget, lapsed the TTL or
+ *    re-attested a different policy, the next attempt derives that and refuses
+ *    it with the code those fresh facts produce — `already-decided`,
+ *    `request-withdrawn`, `already-executed`, `budget-exceeded`, `expired`,
+ *    `policy-drift` — never `append-failed`. A retry cannot launder a denial
+ *    into an allow, because it never replays the earlier conclusion.
+ *  - **Only `head-moved` retries.** Every other refusal, a real verdict included,
+ *    is returned on the first attempt. So is a lock timeout, a corrupt log and a
+ *    schema refusal at the write boundary: retrying those would be either
+ *    pointless or a second write.
+ *
+ * The bound is what keeps a busy log from turning one call into an unbounded
+ * write loop. When it is spent the last `head-moved` refusal is returned with
+ * its code and its `append` error unchanged, and with the attempt count added to
+ * its message so a reader can tell one lost race from a log under sustained
+ * contention. The caller fails closed on it exactly as it always did.
+ */
+import type { AppendError } from "./log.js";
+/**
+ * How many times a gate writer re-derives its verdict against a moved head
+ * before it gives up. Small, fixed, and not configurable upward.
+ *
+ * APRV-150 chose three for the hook's writers; APRV-236 gives the same three to
+ * every other writer a human or a session drives, rather than inventing a
+ * second number for the same fact.
+ */
+export declare const HEAD_MOVED_ATTEMPTS = 3;
+/**
+ * The shape this module needs of a writer's result: an `ok` discriminator, and
+ * on the refusal side a code and the append error beneath it.
+ *
+ * Deliberately structural. `GateRefusal`, `ExecuteRefusal`, `TokenRefusal` and
+ * `GateWindowRefusal` are four frozen unions in four modules that must not
+ * learn about each other; what they share is this, and this is all the helper
+ * reads.
+ */
+export interface HeadRetryable {
+    ok: boolean;
+    code?: string;
+    message?: string;
+    append?: AppendError;
+}
+/** Did this refusal come from the compare-and-append precondition alone? */
+export declare function isHeadMoved(result: HeadRetryable): boolean;
+/**
+ * The attempt budget for one operation: `ceiling` unless the caller asked for
+ * fewer.
+ *
+ * Clamped rather than trusted, and clamped in the one direction that matters: a
+ * caller may ask for LESS tolerance of a moved head (a test pinning the
+ * unretried behaviour, a caller that would rather fail fast), never for more.
+ * Ambiguity — a non-integer, a zero, a negative — resolves to the value the
+ * runtime chose, not the caller's.
+ */
+export declare function attemptsOf(asked: number | undefined, ceiling?: number): number;
+/**
+ * Run one whole read-check-append cycle, and run it again from the top while it
+ * loses the race, up to `attempts` times.
+ *
+ * `cycle` MUST be the entire operation: it re-reads, re-runs every check on the
+ * head it just read, and returns either the append it attempted or the refusal
+ * those fresh facts produced. A `cycle` that closes over a stale read would
+ * defeat the only property that makes this safe.
+ */
+export declare function withHeadRetry<T extends HeadRetryable>(attempts: number, cycle: () => T): T;

package/dist/src/core/head-retry.js

@@ -0,0 +1,121 @@
+/**
+ * The bounded head-moved retry, in one place (APRV-150, APRV-236).
+ *
+ * ## The fact this module is about
+ *
+ * `core/log.ts` takes a compare-and-append precondition: a writer states the
+ * `(seq, hash)` its checks were made against, and the append is refused under
+ * the lock when the tail is something else. That refusal is `append-failed`
+ * with `append.code === "head-moved"`, and it is correct: every read-dependent
+ * check that authorized the write is stale.
+ *
+ * Stale is not the same as wrong. A moved head says the verdict must be
+ * computed again; it does not say what the verdict is. Treating the two as the
+ * same is what turned a busy log into a lottery, twice:
+ *
+ *  - 2026-08-29 (APRV-150): a session's first `git status` — class `read.shell`,
+ *    autonomous, no human anywhere near it — was denied by the Claude Code hook
+ *    because an unrelated record landed a few milliseconds earlier.
+ *  - 2026-09-02 (APRV-236): `approval grant` refused a human's decision with
+ *    `head moved: expected seq 14218, found 14219` while two lanes and the
+ *    daemon were appending. The human ran it again. Twice more.
+ *
+ * The second one is the worse of the two, because the caller it handed the
+ * retry to was a person. A compare-and-append refusal is a fact about timing
+ * rather than about authority, and asking a human to retype is the wrong party
+ * to hand it to.
+ *
+ * ## What a retry is here, and what it is not
+ *
+ * The unit of retry is the WHOLE read-check-append cycle: a new read of the
+ * verified log, a new read of the policy, a fresh attestation, a fresh
+ * derivation of the request's state, fresh escalation, single-use, intake and
+ * budget checks, and a new append against the head that the new read observed.
+ * Nothing crosses an attempt except the caller's own inputs.
+ *
+ * The append is never retried on its own. That distinction is the whole safety
+ * argument, and it is worth stating as three properties:
+ *
+ *  - **compare-and-append is untouched.** Every attempt supplies the head it
+ *    read, and a stale write is still refused under the lock. SPEC.md §11.1
+ *    invariant 5 holds per attempt, which is where it has to hold.
+ *  - **A changed verdict is the new verdict.** If the record that moved the head
+ *    decided the request, spent the key, exhausted the budget, lapsed the TTL or
+ *    re-attested a different policy, the next attempt derives that and refuses
+ *    it with the code those fresh facts produce — `already-decided`,
+ *    `request-withdrawn`, `already-executed`, `budget-exceeded`, `expired`,
+ *    `policy-drift` — never `append-failed`. A retry cannot launder a denial
+ *    into an allow, because it never replays the earlier conclusion.
+ *  - **Only `head-moved` retries.** Every other refusal, a real verdict included,
+ *    is returned on the first attempt. So is a lock timeout, a corrupt log and a
+ *    schema refusal at the write boundary: retrying those would be either
+ *    pointless or a second write.
+ *
+ * The bound is what keeps a busy log from turning one call into an unbounded
+ * write loop. When it is spent the last `head-moved` refusal is returned with
+ * its code and its `append` error unchanged, and with the attempt count added to
+ * its message so a reader can tell one lost race from a log under sustained
+ * contention. The caller fails closed on it exactly as it always did.
+ */
+/**
+ * How many times a gate writer re-derives its verdict against a moved head
+ * before it gives up. Small, fixed, and not configurable upward.
+ *
+ * APRV-150 chose three for the hook's writers; APRV-236 gives the same three to
+ * every other writer a human or a session drives, rather than inventing a
+ * second number for the same fact.
+ */
+export const HEAD_MOVED_ATTEMPTS = 3;
+/** Did this refusal come from the compare-and-append precondition alone? */
+export function isHeadMoved(result) {
+    return !result.ok && result.code === "append-failed" && result.append?.code === "head-moved";
+}
+/**
+ * The attempt budget for one operation: `ceiling` unless the caller asked for
+ * fewer.
+ *
+ * Clamped rather than trusted, and clamped in the one direction that matters: a
+ * caller may ask for LESS tolerance of a moved head (a test pinning the
+ * unretried behaviour, a caller that would rather fail fast), never for more.
+ * Ambiguity — a non-integer, a zero, a negative — resolves to the value the
+ * runtime chose, not the caller's.
+ */
+export function attemptsOf(asked, ceiling = HEAD_MOVED_ATTEMPTS) {
+    if (asked === undefined || !Number.isInteger(asked) || asked < 1)
+        return ceiling;
+    return Math.min(asked, ceiling);
+}
+/**
+ * Run one whole read-check-append cycle, and run it again from the top while it
+ * loses the race, up to `attempts` times.
+ *
+ * `cycle` MUST be the entire operation: it re-reads, re-runs every check on the
+ * head it just read, and returns either the append it attempted or the refusal
+ * those fresh facts produced. A `cycle` that closes over a stale read would
+ * defeat the only property that makes this safe.
+ */
+export function withHeadRetry(attempts, cycle) {
+    let result = cycle();
+    let made = 1;
+    for (; made < attempts && isHeadMoved(result); made += 1) {
+        result = cycle();
+    }
+    return isHeadMoved(result) ? exhausted(result, made) : result;
+}
+/**
+ * The refusal handed back once the bound is spent.
+ *
+ * The code stays `append-failed` and the `append` error stays the writer's own,
+ * because that is what a caller branches on and it is still the true reason.
+ * What is added is the count, so the message says how hard the writer tried:
+ * one lost race and a log under sustained contention are different operational
+ * facts, and a reader who cannot tell them apart cannot act on either.
+ */
+function exhausted(result, attempts) {
+    const note = `; ${String(attempts)} attempt${attempts === 1 ? " was" : "s were"} made, each a fresh read, fresh checks and a fresh compare-and-append, and the head had moved again every time. Nothing was appended.`;
+    // A copy, never a mutation: the caller's refusal objects are values, and the
+    // only field that changes is the human-readable one. The cast restores `T`
+    // after the spread, which widens `message` to `string | undefined`.
+    return { ...result, message: `${result.message ?? "the head moved"}${note}` };
+}
+//# sourceMappingURL=head-retry.js.map

package/dist/src/core/head-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head-retry.js","sourceRoot":"","sources":["../../../src/core/head-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAIH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAkBrC,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,KAAK,YAAY,CAAC;AAC/F,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,KAAyB,EAAE,OAAO,GAAG,mBAAmB;IACjF,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACjF,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAA0B,QAAgB,EAAE,KAAc;IACrF,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;IACrB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,IAAI,GAAG,QAAQ,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,GAAG,KAAK,EAAE,CAAC;IACnB,CAAC;IACD,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAA0B,MAAS,EAAE,QAAgB;IACrE,MAAM,IAAI,GAAG,KAAK,MAAM,CAAC,QAAQ,CAAC,WAChC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAC5B,uIAAuI,CAAC;IACxI,6EAA6E;IAC7E,2EAA2E;IAC3E,oEAAoE;IACpE,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,IAAI,gBAAgB,GAAG,IAAI,EAAE,EAAO,CAAC;AACrF,CAAC"}