faberun 0.29.0 → 0.31.0

package/src/campaign/metrics.mjs

@@ -22,14 +22,30 @@
  * 1 only when a whole run had to be re-authored after a failure that
  * `resume` could not repair.
  *
+ * Costs are split the way the ledger separates them: the stages of a planning
+ * run, a judge's calls, and the worker calls that remain, with the retries the
+ * attempt counter records reported beside the split. Unmeasured spend stays
+ * unknown at every level — a class with no priced record is absent from the
+ * map and named in `unknownCountByClass` instead, never folded into a measured
+ * zero.
+ *
+ * The optional reserve a campaign configures (ADR 0011) is projected beside
+ * the spend: what is still held, what was released when the real charge
+ * arrived, and the part of a late charge that went past its reservation. A
+ * reservation blocks a new dispatch; it is not an absolute cap, and the
+ * projection says so rather than implying provider-side enforcement. All of
+ * that arithmetic is `spend.mjs`; this module projects the indicators.
+ *
  * Filesystem reads and the `faberun metrics` command's flags live in
  * `metrics-command.mjs`; keeping them separate leaves this module a pure
  * function over parsed records.
  */
 
 import { jsonObjectOf, round4, timestampMs } from "./metrics-evals.mjs";
-import { UNKNOWN_COST_REASONS } from "../run/usage.mjs";
 import { MAX_ATTEMPTS as NOTIFY_MAX_ATTEMPTS } from "../notify/index.mjs";
+import { costByClassOf, costTotalsOf, pricedCostOf, reserveOf, retryRecordsOf } from "./spend.mjs";
+
+/** @typedef {import("./spend.mjs").ReserveProjection} ReserveProjection */
 
 /** Node statuses that are not terminal: everything else settles a logical node. */
 const OPEN_STATUSES = new Set(["pending", "running"]);
@@ -44,8 +60,6 @@ const SETTLED_NOTIFY_STATUSES = new Set(["delivered", "no_transport", "filtered"
 /** Target latency for a terminal/attention event to carry a settled receipt (TECH-SPEC section 6). */
 const NOTIFY_TARGET_SEC = 60;
 const SECONDS_PER_HOUR = 3600;
-/** A usage record with no provider-reported cost is `unknown` provenance (`appendUsageRecord`). */
-const UNKNOWN_COST_PROVENANCE = "unknown";
 
 /** @typedef {Record<string, unknown>} JsonObject */
 /** @typedef {"down"|"up"|"informative"} Direction */
@@ -53,6 +67,7 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
 /** @typedef {Indicator & {unknownCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}} CostIndicator */
 /** @typedef {Indicator & {unknownCount: number}} JudgeCostShareIndicator */
 /** @typedef {{value: Record<string, number>|null, direction: Direction, count: number, numerator?: Record<string, number>, denominator?: Record<string, number>, excludedRunIds?: string[], missingSources?: string[]}} GroupedIndicator */
+/** @typedef {GroupedIndicator & {unknownCount: number, unknownCountByClass: Record<string, number>}} ClassCostIndicator */
 /** @typedef {{atMs: number, index: number, event: JsonObject}} RunEvent */
 /** @typedef {{runId: string, id: string, status: string, attempt?: number|null, revisions?: number|null, review?: string|null, judgeIndependence?: string|null}} RunNode */
 
@@ -66,6 +81,7 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
  *   campaign?: JsonObject,
  *   requirements?: unknown[],
  *   excludedRunIds?: string[],
+ *   planningRunIds?: string[],
  *   missingSources?: string[],
  *   now?: number,
  * }} MetricsInput
@@ -80,6 +96,8 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
  *   usageTokensByKind: GroupedIndicator,
  *   usageTokensByKindByRuntime: GroupedIndicator,
  *   usageCostUsd: CostIndicator,
+ *   usageCostUsdByClass: ClassCostIndicator,
+ *   retryCostUsd: CostIndicator,
  *   judgeFindingRate: Indicator,
  *   judgeCostShare: JudgeCostShareIndicator,
  *   blockingJudgeFirstPassRate: GroupedIndicator,
@@ -98,16 +116,14 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
  * @param {MetricsInput} [input]
  * @returns {CampaignMetrics}
  */
-export function projectMetrics({ events = [], usageRecords = [], notifications = [], nodes = [], journal = [], campaign = undefined, requirements = undefined, excludedRunIds = [], missingSources = [], now = Date.now() } = {}) {
+export function projectMetrics({ events = [], usageRecords = [], notifications = [], nodes = [], journal = [], campaign = undefined, requirements = undefined, excludedRunIds = [], planningRunIds = [], missingSources = [], now = Date.now() } = {}) {
   void now;
   const eventList = events.map(jsonObjectOf).filter((event) => event !== null);
   const excluded = excludedRunIdsFor(campaign, excludedRunIds);
   const eligibleNodes = nodes.filter((node) => !excluded.includes(node.runId));
   const eligibleEvents = eventList.filter((event) => typeof event.runId !== "string" || !excluded.includes(event.runId));
-  const eligibleUsageRecords = usageRecords.filter((record) => {
-    const object = jsonObjectOf(record);
-    return object === null || typeof object.runId !== "string" || !excluded.includes(object.runId);
-  });
+  const usageRecordList = usageRecords.map(jsonObjectOf).filter((record) => record !== null);
+  const eligibleUsageRecords = usageRecordList.filter((record) => typeof record.runId !== "string" || !excluded.includes(record.runId));
   const eligibleNotifications = notifications.filter((record) => {
     const object = jsonObjectOf(record);
     return object === null || typeof object.runId !== "string" || !excluded.includes(object.runId);
@@ -116,7 +132,11 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
   const runs = runsPerCampaignOf(nodes, eventList);
   const closedCheckpoints = closedCheckpointsOf(nodes);
   const span = eventSpanOf(eventList);
-  const usage = usageTotalsOf(usageRecords);
+  // Spend is campaign-wide, exactly like `usageCostUsd`: a run a replacement
+  // took out of the rates still spent what it spent.
+  const usage = usageTotalsOf(usageRecordList);
+  const usageByClass = costByClassOf(usageRecordList, planningRunIds);
+  const retries = costTotalsOf(retryRecordsOf(usageRecordList));
   const judgeYield = judgeYieldOf(eligibleEvents, eligibleUsageRecords);
   const gates = blockingJudgeFirstPassRateOf(eligibleNodes, eligibleEvents);
   const notify = notifyReceiptRateOf(eligibleNotifications);
@@ -137,6 +157,17 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
       unknownCountByReason: usage.unknownCountByReason,
       unknownFractionByReason: usage.unknownFractionByReason,
     },
+    usageCostUsdByClass: {
+      ...grouped("down", usageByClass.count, usageByClass.value),
+      unknownCount: usageByClass.unknownCount,
+      unknownCountByClass: usageByClass.unknownCountByClass,
+    },
+    retryCostUsd: {
+      ...measured("down", retries.costCount, retries.costUsd),
+      unknownCount: retries.unknownCount,
+      unknownCountByReason: retries.unknownCountByReason,
+      unknownFractionByReason: retries.unknownFractionByReason,
+    },
     judgeFindingRate: rate("up", judgeYield.findings, judgeYield.judged, excluded),
     judgeCostShare: {
       ...measured("down", usage.costCount, usage.costUsd === null ? null : usage.judgeCostUsd / usage.costUsd),
@@ -148,7 +179,7 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
     intentToVerifiedSeconds: northStar,
     humanTouches: touches,
   };
-  const projected = /** @type {CampaignMetrics & {effectiveJudgeIndependence: string|null}} */ (applyMissingSources(metrics, missingSources));
+  const projected = /** @type {CampaignMetrics & {effectiveJudgeIndependence: string|null, reserve: ReserveProjection}} */ (applyMissingSources(metrics, missingSources));
   // R36: the effective judge-independence mode the launch recorded on the run
   // snapshots, read back from the reduced node input rather than re-derived
   // from the contract or the machine config. It is metadata about the sources,
@@ -158,9 +189,21 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
     value: recordedJudgeIndependenceOf(eligibleNodes),
     enumerable: false,
   });
+  // The optional reserve is policy state derived from the same records, not a
+  // section-6 indicator: non-enumerable for the same reason, and nulled out
+  // when the usage source it reads was not preserved.
+  Object.defineProperty(projected, "reserve", {
+    value: reserveOf(usageRecordList, campaign, missingUsageSources(projected)),
+    enumerable: false,
+  });
   return projected;
 }
 
+/** @param {CampaignMetrics} metrics @returns {string[]} */
+function missingUsageSources(metrics) {
+  return Array.isArray(metrics.usageCostUsd.missingSources) ? metrics.usageCostUsd.missingSources : [];
+}
+
 /**
  * The effective judge-independence mode the launch recorded on the run
  * snapshots, reduced to the `judgeIndependence` field of the node input. The
@@ -202,6 +245,8 @@ function applyMissingSources(metrics, missingSources) {
     usageTokensByKind: withMissing(metrics.usageTokensByKind, ["usage.jsonl"]),
     usageTokensByKindByRuntime: withMissing(metrics.usageTokensByKindByRuntime, ["usage.jsonl"]),
     usageCostUsd: withMissing(metrics.usageCostUsd, ["usage.jsonl"]),
+    usageCostUsdByClass: withMissing(metrics.usageCostUsdByClass, ["usage.jsonl"]),
+    retryCostUsd: withMissing(metrics.retryCostUsd, ["usage.jsonl"]),
     judgeFindingRate: withMissing(metrics.judgeFindingRate, ["events.jsonl", "usage.jsonl"]),
     judgeCostShare: withMissing(metrics.judgeCostShare, ["usage.jsonl"]),
     blockingJudgeFirstPassRate: withMissing(metrics.blockingJudgeFirstPassRate, ["nodes.json", "events.jsonl"]),
@@ -433,30 +478,24 @@ function eventSpanOf(events) {
  * Tokens by kind and total cost across every linked run's usage records, both
  * as a campaign total and broken out per runtime (TECH-SPEC section 6). A
  * record contributes exactly what it recorded: uncached input, cache-read
- * input and output tokens are independent totals. Cost sums only records
- * whose provenance is not `unknown` (`appendUsageRecord` sets `unknown`
- * exactly when the provider reported no cost); every other record's
- * invocation is counted separately rather than folded into a measured zero.
+ * input and output tokens are independent totals. The cost half is
+ * `costTotalsOf`: it sums only records whose provenance is not `unknown`
+ * (`appendUsageRecord` sets `unknown` exactly when the provider reported no
+ * cost) and counts every other record separately rather than folding it into a
+ * measured zero.
  *
- * @param {unknown[]} usageRecords
+ * @param {JsonObject[]} records
  * @returns {{tokensByKind: Record<string, number>, tokensByKindByRuntime: Record<string, number>, tokenCount: number, costUsd: number|null, judgeCostUsd: number, costCount: number, unknownCount: number, unknownJudgeCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}}
  */
-function usageTotalsOf(usageRecords) {
+function usageTotalsOf(records) {
   const tokensByKind = { inputTokens: 0, cacheReadInputTokens: 0, outputTokens: 0 };
   /** @type {Record<string, number>} */
   const tokensByKindByRuntime = {};
   let tokenCount = 0;
-  let costUsd = 0;
   let judgeCostUsd = 0;
-  let costCount = 0;
-  let unknownCount = 0;
   let unknownJudgeCount = 0;
-  /** @type {Record<string, number>} */
-  const unknownCountByReason = {};
   const kinds = /** @type {("inputTokens"|"cacheReadInputTokens"|"outputTokens")[]} */ (["inputTokens", "cacheReadInputTokens", "outputTokens"]);
-  for (const raw of usageRecords) {
-    const record = jsonObjectOf(raw);
-    if (record === null) continue;
+  for (const record of records) {
     let measuredAny = false;
     const runtime = typeof record.runtimeId === "string" && record.runtimeId !== "" ? record.runtimeId : null;
     for (const kind of kinds) {
@@ -467,34 +506,25 @@ function usageTotalsOf(usageRecords) {
       measuredAny = true;
     }
     if (measuredAny) tokenCount += 1;
-    if (typeof record.costUsd === "number" && Number.isFinite(record.costUsd) && record.costProvenance !== UNKNOWN_COST_PROVENANCE) {
-      costUsd += record.costUsd;
-      if (record.role === "judge") judgeCostUsd += record.costUsd;
-      costCount += 1;
-    } else {
-      unknownCount += 1;
-      if (record.role === "judge") unknownJudgeCount += 1;
-      const reason = typeof record.unknownReason === "string" && UNKNOWN_COST_REASONS.includes(record.unknownReason)
-        ? record.unknownReason
-        : "legacy";
-      unknownCountByReason[reason] = (unknownCountByReason[reason] ?? 0) + 1;
-    }
+    if (record.role !== "judge") continue;
+    // The judge share divides the same priced dollars this class split reports,
+    // so a judge retry stays judge cost here and counts as a retry too.
+    const judgeCost = pricedCostOf(record);
+    if (judgeCost === null) unknownJudgeCount += 1;
+    else judgeCostUsd += judgeCost;
   }
-  const totalCount = costCount + unknownCount;
-  const unknownFractionByReason = Object.fromEntries(
-    Object.entries(unknownCountByReason).map(([reason, count]) => [reason, round4(count / totalCount)]),
-  );
+  const cost = costTotalsOf(records);
   return {
     tokensByKind,
     tokensByKindByRuntime,
     tokenCount,
-    costUsd: costCount === 0 ? null : costUsd,
+    costUsd: cost.costUsd,
     judgeCostUsd,
-    costCount,
-    unknownCount,
+    costCount: cost.costCount,
+    unknownCount: cost.unknownCount,
     unknownJudgeCount,
-    unknownCountByReason,
-    unknownFractionByReason,
+    unknownCountByReason: cost.unknownCountByReason,
+    unknownFractionByReason: cost.unknownFractionByReason,
   };
 }
 

package/src/campaign/record.mjs

@@ -11,7 +11,7 @@ import { errorCode } from "../util.mjs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { assertObject, requireId, requirePacketHash, requireString, requireText, requireTimestamp } from "../contract/assert.mjs";
+import { assertObject, nonNegativeNumber, requireId, requirePacketHash, requireString, requireText, requireTimestamp } from "../contract/assert.mjs";
 
 /** @typedef {import("./index.mjs").Campaign} Campaign */
 /** @typedef {import("../notify/index.mjs").JsonObject} JsonObject */
@@ -122,6 +122,13 @@ export function validateCampaign(campaign) {
     }
   }
   if (record.landBranch !== undefined) requireText(record.landBranch, "campaign.landBranch");
+  // The optional balance the reserve gate gates new known-cost dispatches
+  // against (ADR 0011). Absent means no reserve policy at all, which must stay
+  // distinct from a balance of zero — zero gates every known-cost dispatch —
+  // so the field is never defaulted on read, and present it must be a finite
+  // non-negative number, because anything else either gates everything or
+  // reserves money the campaign does not have.
+  if (record.reserveUsd !== undefined) nonNegativeNumber(record.reserveUsd, "campaign.reserveUsd");
   // The ledger preservation marker is optional on read (a record written
   // before it existed reads as not preserved), but once written it must be a
   // boolean so removal can rely on the state it carries.

package/src/campaign/reserve.mjs

@@ -0,0 +1,340 @@
+/**
+ * The enforcement half of the optional campaign balance (ADR 0011): the one
+ * mutator that arms `campaign.reserveUsd` on the record, and the reservation
+ * store a dispatch gate holds, releases and reconciles against.
+ *
+ * The balance is one field on `campaign.json`; the reservations against it
+ * are runtime state, so they live in their own file under the campaign
+ * directory instead of in a record every mutator rewrites whole — a
+ * check-and-deduct cannot be atomic under a last-writer-wins whole-file
+ * write, and two runs' controllers dispatching under one campaign do race.
+ * Every state mutation therefore runs under a lock that reuses the run
+ * controller lock's mechanics (`../run/lock.mjs`), which brings pid-liveness
+ * takeover: a holder that crashed mid-reservation cannot wedge the gate shut.
+ *
+ * Known costs hold their amount before dispatch and settle to released or
+ * charged. A cost the provider never priced is recorded with `costUsd: null`
+ * and holds nothing — the exposure stays unknown instead of reading as free —
+ * and its reconciliation charges the real amount with no late difference,
+ * because there was no reservation to be late against. A charge above its
+ * reservation settles anyway and records the overshoot: the reserve gates new
+ * dispatches, it is never an absolute ceiling.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { acquire, LockBusyError } from "../run/lock.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
+import { nonNegativeNumber } from "../contract/assert.mjs";
+import { sleepSync } from "../util.mjs";
+import { CAMPAIGN_FILE } from "./layout.mjs";
+import { round4 } from "./metrics-evals.mjs";
+import { readCampaign } from "./record.mjs";
+
+/** @typedef {import("./index.mjs").Campaign} Campaign */
+
+/**
+ * The record as the reserve reads it: the shared `Campaign` typedef lives in
+ * `index.mjs`, and this module's writes and reads of the balance are typed
+ * against the field added here, so a record without the field reads as
+ * unconfigured — never as a zero.
+ *
+ * @typedef {Campaign & {reserveUsd?: number}} CampaignWithReserve
+ */
+
+/** The campaign-directory subdirectory holding the reserve's lock and state. */
+export const RESERVE_DIR = "reserve";
+/** The reservation state file inside `RESERVE_DIR`. */
+export const RESERVE_STATE_FILE = "state.json";
+const RESERVE_STATE_SCHEMA_VERSION = 1;
+// No measurement behind these bounds: a critical section is two atomic file
+// writes, so a 5 s wait exceeds it by orders of magnitude on any machine, and
+// the budget is what turns a wedged live holder into a loud throw instead of
+// an unbounded queue.
+const LOCK_WAIT_BUDGET_MS = 5_000;
+const LOCK_RETRY_MS = 5;
+
+/**
+ * One reservation against the balance. `status` is `held` from admission,
+ * then `released` (no charge to reconcile) or `charged` (the real cost
+ * arrived). A `costUsd: null` reservation holds nothing and is the unknown
+ * exposure ADR 0011 keeps visible until a real charge reconciles it.
+ *
+ * @typedef {{
+ *   id: string,
+ *   at: string,
+ *   runId?: string,
+ *   node?: string,
+ *   costUsd: number|null,
+ *   status: "held"|"released"|"charged",
+ *   chargedUsd?: number,
+ *   lateChargeUsd?: number|null,
+ *   settledAt?: string,
+ * }} Reservation
+ */
+/** @typedef {{schemaVersion: number, reservations: Reservation[]}} ReserveState */
+/**
+ * @typedef {{
+ *   armed: boolean,
+ *   configuredUsd: number|null,
+ *   heldUsd: number,
+ *   chargedUsd: number,
+ *   availableUsd: number|null,
+ *   unknownExposureCount: number,
+ *   reservations: Reservation[],
+ * }} ReserveStatus
+ */
+/**
+ * @typedef {{
+ *   admitted: boolean,
+ *   armed: boolean,
+ *   reservation: Reservation|null,
+ *   availableUsd: number|null,
+ * }} ReserveDecision
+ */
+
+/**
+ * The one writer of `campaign.reserveUsd` (docs/FIELD-OWNERSHIP.md): arm the
+ * optional balance a campaign gates new known-cost dispatches with. The
+ * amount is validated by the same schema that reads the record back; a closed
+ * campaign refuses, like every other record mutator.
+ *
+ * @param {string} campaignPath
+ * @param {number} reserveUsd
+ * @param {{at?: string}} [options]
+ * @returns {Campaign}
+ */
+export function configureCampaignReserve(campaignPath, reserveUsd, { at = new Date().toISOString() } = {}) {
+  nonNegativeNumber(reserveUsd, "reserveUsd");
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status === "closed") throw new Error(`campaign is closed: ${campaign.id}`);
+  /** @type {CampaignWithReserve} */
+  const updated = { ...campaign, reserveUsd, updatedAt: at };
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), updated);
+  return updated;
+}
+
+/**
+ * Reserve a dispatch's cost against the campaign balance before the dispatch
+ * happens. A campaign with no configured balance admits without writing any
+ * state — the reserve is only applied where it was armed. A cost with no
+ * provider price (`costUsd` null) is admitted without holding anything and
+ * recorded as an unknown exposure, never as a zero. Atomic: the
+ * check-and-deduct runs under the campaign's reserve lock, so two competing
+ * reservations cannot both be admitted when their combined cost passes the
+ * available balance.
+ *
+ * @param {string} campaignPath
+ * @param {{runId?: string, node?: string, costUsd?: number|null, at?: string}} request
+ *   an absent `costUsd` is an unknown cost, the same as an explicit null
+ * @returns {ReserveDecision}
+ */
+export function reserveCampaignCost(campaignPath, { runId, node, costUsd, at = new Date().toISOString() } = {}) {
+  if (costUsd !== null && costUsd !== undefined) nonNegativeNumber(costUsd, "costUsd");
+  return withReserveLock(campaignPath, () => {
+    const configured = reserveUsdOf(readCampaign(campaignPath));
+    if (configured === undefined) {
+      return { admitted: true, armed: false, reservation: null, availableUsd: null };
+    }
+    const state = readStateFile(campaignPath);
+    const available = availableUsdOf(configured, state);
+    // Rounded on both sides so float dust cannot refuse a reservation that
+    // exactly empties the balance (measured shape of the failure: 100 - 30 -
+    // 70 lands 4.5e-15 above zero).
+    if (costUsd !== null && costUsd !== undefined && round4(costUsd) > round4(available)) {
+      return { admitted: false, armed: true, reservation: null, availableUsd: available };
+    }
+    /** @type {Reservation} */
+    const reservation = { id: randomUUID(), at, costUsd: costUsd ?? null, status: "held" };
+    if (runId !== undefined) reservation.runId = runId;
+    if (node !== undefined) reservation.node = node;
+    state.reservations.push(reservation);
+    writeStateFile(campaignPath, state);
+    const spent = reservation.costUsd === null ? 0 : reservation.costUsd;
+    return { admitted: true, armed: true, reservation, availableUsd: round4(available - spent) };
+  });
+}
+
+/**
+ * Give a reservation's hold back without a charge: the gated call never
+ * launched, or ended with no provider cost to reconcile. Idempotent: an
+ * already settled reservation is returned unchanged.
+ *
+ * @param {string} campaignPath
+ * @param {string} reservationId
+ * @param {{at?: string}} [options]
+ * @returns {Reservation}
+ */
+export function releaseCampaignReservation(campaignPath, reservationId, { at = new Date().toISOString() } = {}) {
+  return withReserveLock(campaignPath, () => {
+    const state = readStateFile(campaignPath);
+    const reservation = findReservation(state, reservationId);
+    if (reservation.status === "held") {
+      reservation.status = "released";
+      reservation.settledAt = at;
+      writeStateFile(campaignPath, state);
+    }
+    return reservation;
+  });
+}
+
+/**
+ * Reconcile a reservation against the charge that actually arrived. A charge
+ * above the reservation settles anyway and records the difference as the
+ * late charge; a reservation of an unmeasured cost charges the real amount
+ * with `lateChargeUsd: null`, because there was no reservation to be late
+ * against. Idempotent by amount: reconciling the same charge twice returns
+ * the settled reservation instead of charging twice, and a different amount
+ * for an already charged reservation refuses.
+ *
+ * @param {string} campaignPath
+ * @param {string} reservationId
+ * @param {number|null} costUsd a null charge is refused by the same validation
+ *   that reads the record: reconciling must carry a real number, never another
+ *   unknown
+ * @param {{at?: string}} [options]
+ * @returns {Reservation}
+ */
+export function reconcileCampaignReservation(campaignPath, reservationId, costUsd, { at = new Date().toISOString() } = {}) {
+  const charge = nonNegativeNumber(costUsd, "costUsd");
+  return withReserveLock(campaignPath, () => {
+    const state = readStateFile(campaignPath);
+    const reservation = findReservation(state, reservationId);
+    if (reservation.status === "charged") {
+      if (reservation.chargedUsd === charge) return reservation;
+      throw new Error(`reservation ${reservationId} already charged ${reservation.chargedUsd} USD, refusing to recharge at ${charge} USD`);
+    }
+    if (reservation.status === "released") {
+      throw new Error(`reservation ${reservationId} was released without a charge; it cannot take one afterwards`);
+    }
+    reservation.status = "charged";
+    reservation.chargedUsd = charge;
+    reservation.lateChargeUsd = reservation.costUsd === null ? null : round4(Math.max(0, charge - reservation.costUsd));
+    reservation.settledAt = at;
+    writeStateFile(campaignPath, state);
+    return reservation;
+  });
+}
+
+/**
+ * Read the reserve's current state beside the record that armed it. The
+ * numbers are derived from the reservation list on every read, so a state
+ * file written by an older admission carries no migration.
+ *
+ * @param {string} campaignPath
+ * @returns {ReserveStatus}
+ */
+export function readCampaignReserve(campaignPath) {
+  const configured = reserveUsdOf(readCampaign(campaignPath));
+  const state = readStateFile(campaignPath);
+  let heldUsd = 0;
+  let chargedUsd = 0;
+  let unknownExposureCount = 0;
+  for (const reservation of state.reservations) {
+    if (reservation.status === "held") {
+      if (reservation.costUsd === null) unknownExposureCount += 1;
+      else heldUsd += reservation.costUsd;
+    } else if (reservation.status === "charged") {
+      chargedUsd += reservation.chargedUsd ?? 0;
+    }
+  }
+  return {
+    armed: configured !== undefined,
+    configuredUsd: configured ?? null,
+    heldUsd: round4(heldUsd),
+    chargedUsd: round4(chargedUsd),
+    availableUsd: configured === undefined ? null : availableUsdOf(configured, state),
+    unknownExposureCount,
+    reservations: state.reservations,
+  };
+}
+
+/**
+ * The balance off the record. Read through one cast instead of spreading
+ * `any` over the module: the schema validates the field, and an unconfigured
+ * record must reach readers as `undefined`, not as a zero.
+ *
+ * @param {Campaign} campaign
+ * @returns {number|undefined}
+ */
+function reserveUsdOf(campaign) {
+  return /** @type {number|undefined} */ (/** @type {CampaignWithReserve} */ (campaign).reserveUsd);
+}
+
+/**
+ * @param {number} configured
+ * @param {ReserveState} state
+ * @returns {number}
+ */
+function availableUsdOf(configured, state) {
+  let held = 0;
+  let charged = 0;
+  for (const reservation of state.reservations) {
+    if (reservation.status === "held") {
+      if (reservation.costUsd !== null) held += reservation.costUsd;
+    } else if (reservation.status === "charged") {
+      charged += reservation.chargedUsd ?? 0;
+    }
+  }
+  return round4(configured - held - charged);
+}
+
+/**
+ * @template T
+ * @param {string} campaignPath
+ * @param {() => T} body
+ * @returns {T}
+ */
+function withReserveLock(campaignPath, body) {
+  const deadline = Date.now() + LOCK_WAIT_BUDGET_MS;
+  for (;;) {
+    let lock;
+    try {
+      lock = acquire(join(campaignPath, RESERVE_DIR));
+    } catch (error) {
+      if (!(error instanceof LockBusyError) || Date.now() >= deadline) {
+        throw error instanceof LockBusyError
+          ? new Error(`campaign reserve lock still held after ${LOCK_WAIT_BUDGET_MS} ms: ${error.message}`)
+          : error;
+      }
+      sleepSync(LOCK_RETRY_MS);
+      continue;
+    }
+    try {
+      return body();
+    } finally {
+      lock.release();
+    }
+  }
+}
+
+/**
+ * @param {string} campaignPath
+ * @returns {ReserveState}
+ */
+function readStateFile(campaignPath) {
+  const path = join(campaignPath, RESERVE_DIR, RESERVE_STATE_FILE);
+  if (!existsSync(path)) return { schemaVersion: RESERVE_STATE_SCHEMA_VERSION, reservations: [] };
+  const state = /** @type {ReserveState} */ (JSON.parse(readFileSync(path, "utf8")));
+  if (!Array.isArray(state.reservations)) throw new TypeError(`reserve state ${path} has no reservations array`);
+  return state;
+}
+
+/**
+ * @param {string} campaignPath
+ * @param {ReserveState} state
+ */
+function writeStateFile(campaignPath, state) {
+  writeJsonAtomic(join(campaignPath, RESERVE_DIR, RESERVE_STATE_FILE), state);
+}
+
+/**
+ * @param {ReserveState} state
+ * @param {string} reservationId
+ * @returns {Reservation}
+ */
+function findReservation(state, reservationId) {
+  const reservation = state.reservations.find((entry) => entry.id === reservationId);
+  if (reservation === undefined) throw new Error(`no reservation ${reservationId} in the campaign's reserve`);
+  return reservation;
+}