llm-relay 0.61.0 → 0.63.0

package/dist/accounting-store.js

@@ -8,7 +8,6 @@ import { emptyAccountingSpendCell, mergeAccountingSpendCells, ACCOUNTING_DAY_SCH
 import { DASHBOARD_REQUEST_ID_PATTERN, isDashboardAttemptId, isDashboardFailureKind, isDashboardOutcome, isDashboardSafeId, isDashboardUtcTimestamp, } from "./dashboard-contract.js";
 import { DEFAULT_FLUSH_DELAY_MS, MAX_FLUSH_DELAY_MS, WriteBehindTimer } from "./write-behind.js";
 export { ACCOUNTING_DAY_SCHEMA, ACCOUNTING_DEDUP_SCHEMA, ACCOUNTING_LIFETIME_SCHEMA, ACCOUNTING_MAX_DAY_ROWS, ACCOUNTING_MAX_DEDUP_IDS, ACCOUNTING_MAX_DETAIL_ATTEMPTS, ACCOUNTING_MAX_FILE_BYTES, ACCOUNTING_MAX_LOSS_MARKERS, ACCOUNTING_MAX_MONTHS, ACCOUNTING_MAX_PACKET_ATTEMPTS, ACCOUNTING_MAX_RECENT_ROWS, ACCOUNTING_MAX_ROWS_PER_CELL, ACCOUNTING_MAX_SAMPLES, ACCOUNTING_MINUTE_SCHEMA, ACCOUNTING_RECENT_SCHEMA, ACCOUNTING_STORE_VERSION, } from "./accounting-store-schema.js";
-/** Sized for a Claude Code session holding many parallel subagent streams in flight. */
 export const ACCOUNTING_MAX_PENDING_REQUESTS = 256;
 export const ACCOUNTING_MAX_PENDING_ATTEMPTS_PER_REQUEST = ACCOUNTING_MAX_PACKET_ATTEMPTS;
 export const ACCOUNTING_MAX_READ_DAYS = 31;
@@ -103,8 +102,6 @@ function emptyMetric() { return { sumMs: null, known: 0, unknown: 0, lost: 0, ov
 function emptyAggregate() {
     return { requests: 0, attempts: 0, served: 0, errored: 0, cancelled: 0, tokens: emptyTokens(), requestTokens: emptyTokens(), latency: emptyMetric(), commit: emptyMetric(), spend: emptySpend(), unpricedRequests: 0 };
 }
-// Cell keys are owned by the schema module's SPEND_CELL_KEYS; the adders below
-// reach them through emptyAccountingAggregateSpend() rather than a second list.
 function emptySpend() {
     return {
         providerPublishedReported: emptyAccountingSpendCell(),
@@ -113,26 +110,18 @@ function emptySpend() {
         referenceEstimated: emptyAccountingSpendCell(),
     };
 }
-/** Route one priced spend to its aggregate cell by (priceSource, tokenBasis). */
 function spendCell(spend, record) {
     if (record.priceSource === "provider_published") {
         return record.tokenBasis === "reported" ? spend.providerPublishedReported : spend.providerPublishedEstimated;
     }
     return record.tokenBasis === "reported" ? spend.referenceReported : spend.referenceEstimated;
 }
-/**
- * Fold one priced spend into an aggregate's ATTEMPT-side cells. First contributor
- * seeds the cell; later ones merge through the schema's checked integer adder so a
- * safe-integer overflow degrades the amount to null (announced by the caller's
- * exact flag) rather than wrapping.
- */
 function addAttemptSpend(target, record) {
     if (record === null)
         return true;
     target.spend ??= emptySpend();
     return addSpendIntoCells(target.spend, record);
 }
-/** Cell-level fold shared by both scopes. */
 function addSpendIntoCells(cells, record) {
     const cell = spendCell(cells, record);
     const knownBefore = cell.known;
@@ -156,16 +145,7 @@ function emptyDay(date) {
 function emptyLifetime() { return { schema: ACCOUNTING_LIFETIME_SCHEMA, version: ACCOUNTING_STORE_VERSION, firstRequestAt: null, lastRequestAt: null, aggregate: emptyAggregate(), months: {}, coverage: emptyCoverage() }; }
 function emptyRecent() { return { schema: ACCOUNTING_RECENT_SCHEMA, version: ACCOUNTING_STORE_VERSION, rows: [], details: {}, coverage: emptyCoverage() }; }
 function newUsageSide() { return { seen: false, exact: true, value: 0 }; }
-/**
- * Fold one token cell into a side. Any uncertainty marker (unknown/lost/overflow, or a null
- * value despite evidence) poisons the WHOLE side rather than being dropped: presenting a partial
- * sum as a measurement is exactly what the provenance invariant forbids.
- * Returns whether THIS cell carried a measured amount (drives the estimated-only detection below).
- */
 function noteUsageCell(side, cell) {
-    // Only a MEASURED amount counts as usage. An all-unknown cell (the store's way of saying "no
-    // token facts arrived") is absence of evidence, not evidence of consumption — counting it
-    // would turn every unreported request into a phantom "mixed" reading.
     if (!(cell.known > 0))
         return false;
     side.seen = true;
@@ -175,32 +155,15 @@ function noteUsageCell(side, cell) {
         side.value += cell.value;
     return true;
 }
-/** Input + output only: cache creation/read cells are deliberately excluded from this figure. */
 function noteUsageTokens(side, input, output) {
     const inputMeasured = noteUsageCell(side, input);
     const outputMeasured = noteUsageCell(side, output);
     return inputMeasured || outputMeasured;
 }
-/** Non-negative safe-integer counter, else 0 (callers convert a 0 total back to null). */
 function windowCounter(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
 }
 const USED_WINDOW_EMPTY = { requests: null, tokens: null, basis: null };
-/**
- * Combine the sides under the contract's reported/estimated/mixed vocabulary.
- *
- * Decision (review fix 2026-08-22): a window holding BOTH bases never sums them into one
- * scalar — the accounting invariant keeps reported and estimated accumulators separate precisely
- * so no total can quietly blend them, and a lone figure tagged "mixed" names the mix without
- * showing its split. Instead:
- * - every measured request carried reported tokens ⇒ the REPORTED figure stands alone, labelled
- *   `reported` (the estimated cells on those same requests cover unreported halves of the same
- *   requests, so the reported figure is a true measurement, merely narrower);
- * - any ESTIMATED-ONLY request sits beside reported ones ⇒ no number: `tokens: null`,
- *   `basis: "mixed"` — returning the reported figure alone would understate the window by every
- *   estimated-only request, and the sum would blend bases. Naming the mix without inventing the
- *   number is the provenance-safe direction.
- */
 function usageReading(requests, reported, estimated, estimatedOnlyRequest) {
     if (!reported.seen && !estimated.seen)
         return { requests, tokens: null, basis: null };
@@ -227,8 +190,6 @@ function sourceCell(value) {
     return {
         value: safeCounter(source.value),
         observedAt: validTimestamp(source.observedAt) ? source.observedAt : null,
-        // `isLoadableId`, not `isDashboardSafeId` — see `methodSnapshot`: the accept side must not
-        // admit what the loader will reject, or the whole day shard is quarantined on the next read.
         method: typeof source.method === "string" && isLoadableId(source.method) && Buffer.byteLength(source.method, "utf8") <= 256 ? source.method : null,
     };
 }
@@ -399,12 +360,9 @@ function addRequest(target, event, outcome) {
     exact &&= addMetric(target.latency, outcome === "cancelled" ? null : safeCounter(event.latencyMs), event.endedAt);
     exact &&= addMetric(target.commit, outcome === "success" ? safeCounter(event.commitMs) : null, event.endedAt);
     exact &&= addRawTokens(target.requestTokens, event.tokens, event.endedAt);
-    // Request spend mirrors request tokens: the WINNING serve only, so a
-    // retried-elsewhere request never double-counts its failed attempts.
     if (event.spend !== null) {
         target.requestSpend ??= emptySpend();
         exact &&= addSpendIntoCells(target.requestSpend, event.spend);
-        // A partial figure (unpriced cache kinds etc.) is priced but a lower bound.
         if (event.spend.coverage !== "full") {
             exact &&= increase(target, "partiallyPricedRequests");
         }
@@ -416,9 +374,6 @@ function addRequest(target, event, outcome) {
 }
 function addRootAttempt(target, attempt) {
     let exact = increase(target, "attempts");
-    // Root aggregates accumulate BOTH attempt-side axes, exactly as the dimension
-    // attempt rows do: dropping the token fold made every root disagree with its
-    // own rows while the spend fold looked complete.
     exact &&= addAggregateTokens(target.tokens, attempt.tokens);
     exact &&= addAttemptSpend(target, attempt.spend);
     return exact;
@@ -435,10 +390,6 @@ function addAttempt(target, attempt) {
 function rowKey(row) {
     return JSON.stringify([row.kind, row.role, row.provider, row.model, row.client, row.credentialId, row.attribution, row.outcome, row.failureKind]);
 }
-/**
- * Dimension fields are fixed when a row is created (only aggregate counters move
- * afterwards), so its serialized key is memoized rather than re-derived per scan.
- */
 const rowKeys = new WeakMap();
 function cachedRowKey(row) {
     const existing = rowKeys.get(row);
@@ -448,10 +399,6 @@ function cachedRowKey(row) {
     rowKeys.set(row, key);
     return key;
 }
-/**
- * In-memory membership index for a day's dedup array; the SORTED ARRAY remains
- * the persisted form. Keyed weakly so an evicted or pruned day drops its index.
- */
 const dedupMembership = new WeakMap();
 function dedupSet(day) {
     let ids = dedupMembership.get(day);
@@ -516,8 +463,6 @@ function makeAttempt(event) {
         model: safeId(event.model),
         credentialId: safeId(event.credentialId),
         tokens: tokenSnapshot(event.tokens, event.endedAt),
-        // The lifecycle already validated this record's provenance fields; a
-        // re-validation through the packet guard below keeps that guarantee total.
         spend: event.spend,
     };
     const parsed = parseAccountingAttemptPacketV1(value);
@@ -554,20 +499,11 @@ class AccountingStoreImpl {
     recentReadState = "missing";
     dirtyLifetime = false;
     dirtyRecent = false;
-    /** Fixed snapshots were not safely loaded yet; terminal facts must queue. */
     fixedLoadPending = false;
-    /** Quarantine/lower-bound evidence observed before both fixed reads complete. */
     pendingFixedLoss = false;
     pendingJournalLoss = false;
-    /** Losses observed before fixed snapshots load must not dirty empty state. */
     deferredGlobalLosses = [];
-    /**
-     * Retention is its own post-fact transaction.  Keep its intent separately so
-     * a fact commit followed by a failed tombstone commit cannot turn a retry
-     * into an apparently clean no-op.
-     */
     pendingRetention = null;
-    /** The exact pending journal shape, retained only to merge a later recovery. */
     pendingRetentionPlan = null;
     retryTimer = null;
     retryDelay = RETRY_MIN_MS;
@@ -597,10 +533,6 @@ class AccountingStoreImpl {
             maxTargets: 128,
             ...(options.ioHooks === undefined ? {} : { hooks: options.ioHooks }),
         });
-        // A read-only store never takes the writer lease and never replays or quarantines
-        // anything — every one of those is a write against a directory a live relay may be
-        // committing to. It observes committed snapshots only; unflushed in-memory deltas of
-        // the running process stay invisible, which the CLI reports as lag rather than repairing.
         if (this.readOnly) {
             this.writer = { status: "released", error: null, retryable: false };
             this.last = result("none", null, false, false);
@@ -649,8 +581,6 @@ class AccountingStoreImpl {
     flush() {
         if (this._closed)
             return result("invalid", "closed");
-        // Read-only: flushing is a write. Nothing is ever dirty here anyway because no
-        // record path runs; keep the answer explicit rather than relying on that accident.
         if (this.readOnly)
             return result("none", null, false, false);
         this.timer.clear();
@@ -668,10 +598,6 @@ class AccountingStoreImpl {
         if (recovered.lowerBoundLoss || recovered.status === "recovery-loss")
             this.consumeRecoveryLoss(recovered);
         if (recovered.status === "recovered" && this.pendingRetentionPlan !== null) {
-            // Never replace current memory with the journal's saved lifetime: records
-            // may have arrived after the failed retention write.  Reconcile only the
-            // durable pruning effects, then let the ordinary fact commit persist any
-            // newer in-memory facts.
             this.reconcileRecoveredRetention(this.pendingRetentionPlan);
         }
         this.drainQueued();
@@ -699,9 +625,6 @@ class AccountingStoreImpl {
             this.recentReadState = "ok";
         this.retryDelay = RETRY_MIN_MS;
         const retention = this.commitRetention(committedDates);
-        // A write-loaded shard stays outside the clean cache until this commit has
-        // made it durable. Re-admit it now, or evict it if every cache slot is
-        // still protected by dirty/in-flight facts.
         for (const date of [...committedDates].sort())
             this.rememberKnownDay(date);
         return retention ?? written;
@@ -712,9 +635,6 @@ class AccountingStoreImpl {
         this.timer.clear();
         this.clearRetry();
         const flushed = this.flush();
-        // Dirty facts and a recoverable journal still belong to this store. Keep
-        // it open so a later close can retry instead of irreversibly discarding
-        // the only in-process copy after one transient failure.
         if (flushed.retryable)
             return flushed;
         const closed = this.io.close();
@@ -731,8 +651,6 @@ class AccountingStoreImpl {
             const parsed = parsedDay(cached);
             return parsed === null ? { status: "corrupt", value: null, error: "schema" } : { status: "ok", value: this.withDayLoss(parsed) };
         }
-        // Quarantine renames a file; an out-of-process reader reports corruption instead of
-        // touching a shard a live relay may be about to rewrite.
         const read = this.io.readJson(targetForDay(date), (value) => parseAccountingDayShardV1(value).ok, { quarantineCorrupt: !this.readOnly });
         if (read.status === "missing")
             return { status: "missing", value: null };
@@ -793,8 +711,6 @@ class AccountingStoreImpl {
         if (parsed === null)
             return { status: "corrupt", value: null, error: "schema" };
         const requested = typeof options === "number" ? options : options?.limit;
-        // Unlike the constructor options, an EXPLICIT read limit is honoured exactly:
-        // 0 asks for zero rows, and only an omitted limit falls back to the default.
         const limit = typeof requested === "number" && Number.isSafeInteger(requested)
             ? Math.min(Math.max(requested, 0), this.recentLimit)
             : this.recentLimit;
@@ -814,24 +730,6 @@ class AccountingStoreImpl {
         const packet = parsed.details[requestId];
         return packet === undefined ? { status: "missing", value: null } : { status: "ok", value: frozenClone(packet) };
     }
-    /**
-     * Local usage for one credential in the CURRENT period — the `localUsed` half of spec §5.1
-     * rung 2. Reads ONLY in-memory state and never touches disk:
-     *
-     * - minute/day → this process's in-memory day shard (`this.days`, which holds today's shard
-     *   once any terminal request has been applied; a shard evicted from the read cache or not yet
-     *   reloaded after restart is invisible ⇒ null, never 0).
-     * - month → in-memory lifetime months only. Reading 31 day shards would put disk IO on the
-     *   availability path, so a month whose rollup was dropped by ACCOUNTING_MAX_MONTHS reports
-     *   null rather than a partial sum.
-     *
-     * Included: every TERMINAL event already applied to memory, including ones still awaiting the
-     * write-behind flush. NOT included: in-flight requests that have not completed, and anything
-     * recorded before this store instance loaded. Tokens are reported input+output when every
-     * measured request carried a provider report, estimated-only otherwise; a window holding both
-     * bases reports NO number (`basis: "mixed"`, tokens null) — see usageReading. An uncertain cell
-     * poisons its whole side instead of being silently dropped from the sum.
-     */
     usedInWindow(options) {
         const at = options.now ?? Date.now();
         if (!Number.isFinite(at))
@@ -843,15 +741,10 @@ class AccountingStoreImpl {
         let requests = null;
         const reported = newUsageSide();
         const estimated = newUsageSide();
-        // True when at least one counted request carried ONLY estimated tokens — the case that turns
-        // a reported figure into an understatement and forces basis "mixed" with no value.
         let estimatedOnlyRequest = false;
         if (options.period !== "month") {
-            // Request rows carry kind "request"; their aggregate counts requests exactly once per row.
             const day = this.days.get(date);
             if (day !== undefined) {
-                // Both sides are bare HH:MM strings, so lexicographic order is chronological. The day
-                // shard only contains THIS date's cells; the bound just drops clock-skewed future ones.
                 const minuteKeys = options.period === "minute" ? [minute] : Object.keys(day.cells).filter((cellMinute) => cellMinute <= minute);
                 let total = 0;
                 for (const cellMinute of minuteKeys) {
@@ -861,8 +754,6 @@ class AccountingStoreImpl {
                     for (const row of cell.rows) {
                         if (row.kind !== "request" || row.credentialId !== options.credentialId)
                             continue;
-                        // Unattributable traffic cannot be claimed by a named credential; a model filter
-                        // narrows further when given.
                         if (row.credentialId === null || (model !== null && row.model !== model))
                             continue;
                         total += windowCounter(row.requests);
@@ -877,18 +768,10 @@ class AccountingStoreImpl {
             }
         }
         else {
-            // The lifetime month rollup carries ROOT aggregates across ALL credentials — it cannot be
-            // narrowed to one slot. Feeding it to a per-credential rung-2 subtraction would charge every
-            // key's traffic to the one credential whose ceiling is being resolved, so BOTH figures
-            // decline until the rollup is per-credential: requests as well as tokens. A whole-relay
-            // count on a per-slot row is not "exact with stated scope" — the wire row has no scope
-            // marker to state it with, and a reader cannot tell. Null is the honest reading here; same
-            // fail-safe direction as everywhere else in this method.
             return USED_WINDOW_EMPTY;
         }
         return usageReading(requests, reported, estimated, estimatedOnlyRequest);
     }
-    /** Read paths may touch arbitrary dates; retain only a deterministic bounded hint. */
     rememberKnownDay(date) {
         if (!this.days.has(date) || this.knownDays.has(date) || this.knownDaysCap < 1)
             return;
@@ -903,10 +786,6 @@ class AccountingStoreImpl {
                 break;
             }
             if (!evicted) {
-                // Cache pressure may never discard a fact that is dirty or still has
-                // in-flight work. Those states are independently bounded by the
-                // transaction and pending-work caps; only a clean, unprotected read
-                // cache entry may be dropped here.
                 if (!this.dirtyDays.has(date) && !this.hasPendingDay(date))
                     this.days.delete(date);
                 return;
@@ -953,8 +832,6 @@ class AccountingStoreImpl {
     onAttemptCompleted(event) {
         const attempt = makeAttempt(event);
         if (attempt === null) {
-            // A packet that fails validation is a measurement quietly disappearing
-            // unless the loss is announced like every other drop path.
             this.markGlobalLoss("unknown", "truncated", "attempt_packet");
             return;
         }
@@ -990,10 +867,6 @@ class AccountingStoreImpl {
         if (existing !== undefined)
             return existing;
         if (this.pending.size >= this.pendingRequestLimit) {
-            // Evict the OLDEST-STARTED in-flight request, not merely the first
-            // inserted: parallel subagent streams do not start in insertion order.
-            // An entry whose start event has not arrived carries the least identity,
-            // so it is treated as older than every dated entry.
             let victim = null;
             let victimStartedAt = null;
             for (const [key, entry] of this.pending) {
@@ -1160,8 +1033,6 @@ class AccountingStoreImpl {
             model: authoritative?.model ?? safeId(event.model),
             credentialId: authoritative?.credentialId ?? safeId(event.credentialId),
             tokens: authoritative?.tokens ?? tokenSnapshot(event.tokens, event.endedAt),
-            // The WINNING serve's spend mirrors its tokens. Repair spend stays on the
-            // repair attempt rows (C1) so a later roll-up can add it back exactly once.
             spend: authoritative?.spend ?? null,
             attempts: retained,
             attemptMetadata: { total, stored: retained.length, dropped: total - retained.length },
@@ -1241,7 +1112,6 @@ class AccountingStoreImpl {
         ids.add(requestId);
         return true;
     }
-    /** Keep a fact transaction within the journal's bounded target set. */
     ensureTransactionRoom(date) {
         if (this.dirtyDays.has(date))
             return true;
@@ -1250,14 +1120,10 @@ class AccountingStoreImpl {
             return false;
         if (this.dirtyDays.size + 3 <= maximum)
             return true;
-        // A terminal request owns a day + lifetime + recent atomically.  Commit the
-        // previous bounded batch before accepting a new day rather than allowing an
-        // unrepresentable journal transaction to accumulate.
         const flushed = this.flush();
         return (flushed.status === "committed" || flushed.status === "recovered" || flushed.status === "none")
             && this.dirtyDays.size + 3 <= maximum;
     }
-    /** Read one named day through the namespace-restricted journal I/O only. */
     loadDayForWrite(date) {
         const cached = this.days.get(date);
         if (cached !== undefined)
@@ -1269,9 +1135,6 @@ class AccountingStoreImpl {
             return created;
         }
         if (read.status !== "ok" || read.value === null) {
-            // A quarantined day is intentionally restarted as a lower bound on the
-            // next queued pass.  A transient read failure remains queued and cannot
-            // overwrite an unreadable existing shard.
             if (read.status === "corrupt" || read.status === "oversize") {
                 this.markGlobalLoss("corrupt_recovery", "corrupt", "day");
             }
@@ -1286,7 +1149,6 @@ class AccountingStoreImpl {
         this.days.set(date, mutable);
         return mutable;
     }
-    /** Keep unread fixed snapshots immutable until a retry has loaded both safely. */
     deferFixedLoad(value) {
         this.fixedLoadPending = true;
         this.lifetimeReadState = "corrupt";
@@ -1300,13 +1162,6 @@ class AccountingStoreImpl {
         for (const loss of losses)
             this.markGlobalLoss(loss.reason, loss.kind, loss.field, loss.count);
     }
-    /**
-     * Read-only constructor load: read the two fixed snapshots WITHOUT the writer lease and
-     * without any recovery/quarantine write. A corrupt or unreadable snapshot stays corrupt
-     * (reported by `readLifetime`/`readRecent`) rather than being renamed aside. Day shards
-     * are deliberately NOT preloaded — `readDay` reads them on demand through the same
-     * no-write readJson path.
-     */
     loadFixedSnapshotsReadOnly() {
         const lifetime = this.io.readJson(LIFETIME_TARGET, (value) => parseAccountingLifetimeV1(value).ok, { quarantineCorrupt: false });
         this.lifetimeReadState = lifetime.status === "ok" && lifetime.value !== null
@@ -1321,7 +1176,6 @@ class AccountingStoreImpl {
         if (this.recentReadState === "ok")
             this.recent = mutableRecent(recent.value);
     }
-    /** Recover a committed journal first, then load the two fixed snapshots. */
     recoverAndLoad() {
         const recovered = this.io.recover();
         if (recovered.status === "failed" || recovered.status === "invalid") {
@@ -1397,7 +1251,6 @@ class AccountingStoreImpl {
         this.queueRecoveredRetention();
         this.last = recovered;
     }
-    /** Validate every outgoing canonical object before handing it to the journal. */
     factSnapshots() {
         const snapshots = {};
         const encode = (name, value) => {
@@ -1432,15 +1285,9 @@ class AccountingStoreImpl {
         }
         return snapshots;
     }
-    /**
-     * Retention never shares the fact transaction: a fact must be durable before
-     * its day can become eligible for a tombstone transaction.
-     */
     commitRetention(committedDates) {
         if (this.retentionDays === null)
             return null;
-        // A clock that previously rolled back may have caught the durable frontier
-        // since construction. Re-evaluate it on every flush, not only at startup.
         this.queueRecoveredRetention();
         const eligible = this.advanceTrustedDate(committedDates);
         if (eligible !== null)
@@ -1448,8 +1295,6 @@ class AccountingStoreImpl {
         const cutoff = this.pendingRetention;
         if (cutoff === null)
             return null;
-        // A recovered or already-completed transaction can leave a stale in-memory
-        // intent, but it must not cause an endless no-op retry.
         if (!this.retentionNeedsWork(cutoff)) {
             this.pendingRetention = null;
             this.pendingRetentionPlan = null;
@@ -1465,17 +1310,12 @@ class AccountingStoreImpl {
         const start = progress ?? dayFor(current.firstRequestAt ?? "");
         const retention = this.retentionCandidates(start, cutoff, Math.max(0, maximum - 1));
         const candidates = retention.dates;
-        // One target is consumed by lifetime.  Do not claim retention can make
-        // progress if a caller has configured no room for a tombstone at all.
         if (retention.truncated && candidates.length === 0) {
             return this.fail(result("invalid", "retention-targets", false, this.lowerBoundLoss));
         }
         const next = mutableLifetime(current);
         const lastCandidate = candidates.at(-1) ?? null;
         const advanced = lastCandidate === null ? null : nextDate(lastCandidate);
-        // `retentionFrom` is the durable cursor: it may reach the policy cutoff
-        // only once every bounded tombstone batch before it has committed.  This
-        // lets a restarted store continue without discovering directory entries.
         next.coverage.retentionFrom = advanced ?? (retention.truncated
             ? progress
             : progress === null || progress < cutoff ? cutoff : progress);
@@ -1505,8 +1345,6 @@ class AccountingStoreImpl {
         this.applyRetentionPlan(plan);
         this.pendingRetentionPlan = null;
         if (plan.truncated) {
-            // A complete transaction can still have more bounded work.  This is a
-            // continuation, not a dirty fact write, so wake it explicitly.
             this.pendingRetention = plan.cutoff;
             this.retryDelay = RETRY_MIN_MS;
             this.scheduleRetry();
@@ -1516,11 +1354,6 @@ class AccountingStoreImpl {
         }
         return written;
     }
-    /**
-     * A restart cannot scan a directory to rediscover old shards.  The durable
-     * lifetime lower date lets us name a bounded, deterministic tombstone range
-     * instead; absent days are harmless no-op tombstones.
-     */
     retentionCandidates(start, cutoff, limit) {
         const dates = new Set();
         let truncated = false;
@@ -1544,15 +1377,11 @@ class AccountingStoreImpl {
             }
         }
         if (start === null) {
-            // Only this bounded fallback needs ordering.  Normal retained data has a
-            // lifetime first-request date, so it names its whole deterministic range
-            // without retaining or sorting arbitrary read-path dates.
             for (const date of [...this.knownDays].sort())
                 add(date);
         }
         return { dates: [...dates].sort(), truncated };
     }
-    /** Apply a retention transaction known to have committed in this process. */
     applyRetentionPlan(plan) {
         this.lifetime = plan.next;
         this.lifetimeReadState = "ok";
@@ -1561,12 +1390,6 @@ class AccountingStoreImpl {
             this.knownDays.delete(date);
         }
     }
-    /**
-     * A retry may recover a durable retention journal after subsequent records
-     * have already changed memory.  Merge only its coverage cursor and exact
-     * tombstones; a later fact transaction writes the current aggregate rather
-     * than replacing it with the journal's stale lifetime payload.
-     */
     reconcileRecoveredRetention(plan) {
         this.pendingRetentionPlan = null;
         const current = parsedLifetime(this.lifetime);
@@ -1584,8 +1407,6 @@ class AccountingStoreImpl {
             markCoverage(next.coverage, "unknown", "truncated", "retention");
         this.lifetime = next;
         this.lifetimeReadState = "ok";
-        // It is harmless to rewrite an unchanged lifetime once; doing so is what
-        // makes the recovered durable state and any unflushed newer facts converge.
         this.dirtyLifetime = true;
         for (const date of plan.candidates) {
             if (this.dirtyDays.has(date))
@@ -1604,12 +1425,6 @@ class AccountingStoreImpl {
         const progress = validDate(current.coverage.retentionFrom) ? current.coverage.retentionFrom : null;
         return current.coverage.retentionDays !== this.retentionDays || progress === null || progress < cutoff;
     }
-    /**
-     * Backfilling a shard behind the durable cursor invalidates that cursor,
-     * including after a wall-clock rollback. Rewind coverage in the fact
-     * transaction, then queue pruning when the shard is already expired under
-     * the current clock.
-     */
     revisitLateRetentionDate(date) {
         if (this.retentionDays === null || !validDate(date))
             return;
@@ -1630,18 +1445,11 @@ class AccountingStoreImpl {
             return;
         this.pendingRetention = latest(this.pendingRetention, cutoff);
     }
-    /**
-     * `lastRequestAt` is durable evidence of the previous trusted frontier.  Do
-     * not derive it from a retention cursor: a partial cursor merely says where a
-     * tombstone batch stopped.  Keep a future frontier too, so a clock rollback
-     * cannot let a late fact move retention backwards before the clock catches up.
-     */
     seedTrustedDateFromLifetime() {
         const last = dayFor(this.lifetime.lastRequestAt ?? "");
         if (last !== null)
             this.trustedDate = latest(this.trustedDate, last);
     }
-    /** Resume an incomplete durable cursor only when its fact frontier is clock-eligible. */
     queueRecoveredRetention() {
         if (this.retentionDays === null || this.trustedDate === null)
             return;
@@ -1650,7 +1458,6 @@ class AccountingStoreImpl {
             return;
         this.queueRetentionForDate(this.trustedDate);
     }
-    /** A clock-gated, monotonic date: future and late facts cannot advance pruning. */
     advanceTrustedDate(committedDates) {
         const nowDate = this.clockDate();
         if (nowDate === null)
@@ -1690,7 +1497,6 @@ class AccountingStoreImpl {
         this.markGlobalLoss("corrupt_recovery", "corrupt", "journal");
         this.scheduleFlush();
     }
-    /** Record a loss where it can be surfaced without claiming an exact total. */
     markGlobalLoss(reason, kind, field, count = 1) {
         if (this.fixedLoadPending) {
             const existing = this.deferredGlobalLosses.find((loss) => loss.reason === reason && loss.kind === kind && loss.field === field);
@@ -1774,7 +1580,6 @@ class AccountingStoreImpl {
         return value;
     }
 }
-/** Accounting shares the common write-behind cadence, exported for callers/tests. */
 export const ACCOUNTING_FLUSH_DELAY_MS = DEFAULT_FLUSH_DELAY_MS;
 export const ACCOUNTING_MAX_FLUSH_DELAY_MS = MAX_FLUSH_DELAY_MS;
 export function createAccountingStore(options = {}) {