@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/usage/failure-fingerprint.ts

@@ -0,0 +1,118 @@
+/**
+ * A versioned, content-free identity for one kind of request failure (#3748).
+ *
+ * #3748 proposed a second SQLite store under src/telemetry/ holding a free-text `signature`
+ * masked by regular expressions. Both halves are replaced here. The store is replaced by a
+ * projection rebuilt from usage.jsonl, and the masked signature is replaced by a tuple of closed
+ * roster members -- because a regular expression can only assert that it removed what it matched,
+ * while a tuple whose every slot is a member of a frozen list has nothing to remove.
+ *
+ * That is the whole design: the input type cannot express a provider alias, a model, an account,
+ * an error message, a prompt, a request id or a timestamp, so no amount of upstream text can
+ * reach a fingerprint.
+ */
+import { createHash } from "node:crypto";
+import type { RequestFailureCause } from "../lib/request-failure-model";
+import type { RequestCloseReason, RequestTerminalStatus } from "./request-outcome";
+import type { PersistedUsageEntry } from "./log";
+
+/**
+ * The tuple layout and its meaning are one contract.
+ *
+ * Adding, removing, reordering or reinterpreting a position changes what a stored fingerprint
+ * means, so any of those requires incrementing this. Tests import it rather than writing `1`,
+ * so a bump cannot be silently contradicted by a test that still expects the old prefix.
+ */
+export const FAILURE_FINGERPRINT_VERSION = 1 as const;
+
+/**
+ * The status reduced to its class.
+ *
+ * The exact code is not in the tuple: a 502 and a 503 that both failed for `upstream-fault` are
+ * one problem to an operator, and keeping the code would split every group by whichever number
+ * an origin happened to send.
+ */
+export const FAILURE_STATUS_CLASSES = Object.freeze([
+  "1xx", "2xx", "3xx", "4xx", "5xx", "unknown",
+] as const);
+
+export type FailureStatusClass = typeof FAILURE_STATUS_CLASSES[number];
+
+export type FailureFingerprint = `v${typeof FAILURE_FINGERPRINT_VERSION}:${string}`;
+
+/**
+ * Everything a fingerprint is allowed to read, and nothing else.
+ *
+ * Every slot is either a member of a frozen roster or `null`. `providerClass` is the one field
+ * that starts life as free text: the durable `provider` is a name the user chose, so it is
+ * resolved against the provider registry first and becomes `null` when it is not a registry
+ * member. A configured alias therefore cannot reach the key whatever it was named.
+ */
+export interface FailureFingerprintFacts {
+  readonly cause: RequestFailureCause;
+  readonly statusClass: FailureStatusClass;
+  readonly providerClass: string | null;
+  readonly inboundProtocol: NonNullable<PersistedUsageEntry["inboundProtocol"]> | null;
+  readonly terminalStatus: RequestTerminalStatus | null;
+  readonly closeReason: RequestCloseReason | null;
+  readonly transportPhase: NonNullable<PersistedUsageEntry["transportPhase"]> | null;
+  readonly terminalSource: NonNullable<PersistedUsageEntry["terminalSource"]> | null;
+}
+
+/**
+ * Fixed positions, with every absent fact written as an explicit `null`.
+ *
+ * Omitting an absent field, or joining the present ones with a delimiter, would let two
+ * different failures collide: `[a, null, b]` and `[a, b]` are the same string once the nulls
+ * are dropped. A fixed-arity tuple cannot collide that way, which is why the shape is a tuple
+ * rather than an object with optional keys.
+ */
+export type FailureFingerprintTuple = readonly [
+  version: typeof FAILURE_FINGERPRINT_VERSION,
+  cause: FailureFingerprintFacts["cause"],
+  statusClass: FailureFingerprintFacts["statusClass"],
+  providerClass: FailureFingerprintFacts["providerClass"],
+  inboundProtocol: FailureFingerprintFacts["inboundProtocol"],
+  terminalStatus: FailureFingerprintFacts["terminalStatus"],
+  closeReason: FailureFingerprintFacts["closeReason"],
+  transportPhase: FailureFingerprintFacts["transportPhase"],
+  terminalSource: FailureFingerprintFacts["terminalSource"],
+];
+
+export function failureStatusClass(status: unknown): FailureStatusClass {
+  if (typeof status !== "number" || !Number.isInteger(status) || status < 100 || status > 599) {
+    return "unknown";
+  }
+  const index = Math.floor(status / 100) - 1;
+  return FAILURE_STATUS_CLASSES[index] ?? "unknown";
+}
+
+export function canonicalFailureFingerprintTuple(
+  facts: FailureFingerprintFacts,
+): FailureFingerprintTuple {
+  return [
+    FAILURE_FINGERPRINT_VERSION,
+    facts.cause,
+    facts.statusClass,
+    facts.providerClass,
+    facts.inboundProtocol,
+    facts.terminalStatus,
+    facts.closeReason,
+    facts.transportPhase,
+    facts.terminalSource,
+  ];
+}
+
+/**
+ * The version travels in the value, not only in the hashed input.
+ *
+ * Both matter and for different reasons: hashing it means two versions of the same failure never
+ * collide, and prefixing it means a reader holding an old fingerprint can tell that it is old
+ * instead of concluding the failure stopped happening.
+ */
+export function computeFailureFingerprint(facts: FailureFingerprintFacts): FailureFingerprint {
+  const digest = createHash("sha256")
+    .update(JSON.stringify(canonicalFailureFingerprintTuple(facts)))
+    .digest("hex");
+  return `v${FAILURE_FINGERPRINT_VERSION}:${digest}`;
+}

package/src/usage/failure-projection-cache.ts

@@ -0,0 +1,174 @@
+/**
+ * The scan owner for the failure projection: one checkpointed pass over usage.jsonl.
+ *
+ * Shaped after `src/server/management/usage-aggregate-cache.ts`, which solved the same problem
+ * for the usage summary. That similarity is deliberate -- the correctness here is entirely in
+ * the checkpoint discipline, and two subtly different versions of it is how a projection quietly
+ * extends stale groups across a file that was replaced under it.
+ *
+ * Every bound this projection obeys belongs to the scanner it calls, not to itself: the 1 MiB
+ * row ceiling, the 1 MiB chunk, the cooperative yield, the opened-EOF snapshot boundary and the
+ * path/device/inode/birthtime identity with its 64 KiB boundary digest. A projection with its
+ * own limits would be a second storage policy, which is what this lane exists to avoid.
+ */
+import {
+  currentUsageLogRevision,
+  usageLogIdentityKey,
+  usageLogRevisionKey,
+  type UsageLogRevision,
+} from "./log";
+import {
+  scanUsageLedgerCooperatively,
+  UsageLedgerRebuildRequiredError,
+} from "./ledger-scanner";
+import {
+  createFailureProjectionAccumulator,
+  type FailureProjectionAccumulator,
+  type FailureProjectionSnapshot,
+} from "./failure-projection";
+
+export type FailureProjectionUpdate = "unchanged" | "append" | "rebuild";
+
+export interface FailureProjectionResult extends FailureProjectionSnapshot {
+  update: FailureProjectionUpdate;
+  /** True once any row was skipped for exceeding the scanner's row ceiling. Sticky. */
+  historyIncomplete: boolean;
+}
+
+interface RetainedProjection {
+  accumulator: FailureProjectionAccumulator;
+  historyIncomplete: boolean;
+  revision: UsageLogRevision | null;
+  identityKey: string;
+  revisionKey: string;
+  processedThroughBytes: number;
+  processedThroughDigest: string;
+}
+
+const MAX_REBUILD_ATTEMPTS = 2;
+let retained: RetainedProjection | null = null;
+let inFlight: Promise<FailureProjectionResult> | null = null;
+
+function resultFrom(state: RetainedProjection, update: FailureProjectionUpdate): FailureProjectionResult {
+  return { ...state.accumulator.snapshot(), update, historyIncomplete: state.historyIncomplete };
+}
+
+function retain(
+  accumulator: FailureProjectionAccumulator,
+  scan: Awaited<ReturnType<typeof scanUsageLedgerCooperatively>>,
+  historyIncomplete: boolean,
+): RetainedProjection {
+  return {
+    accumulator,
+    historyIncomplete: historyIncomplete || scan.oversizedRows > 0,
+    revision: scan.revision,
+    identityKey: usageLogIdentityKey(scan.revision),
+    revisionKey: usageLogRevisionKey(scan.revision),
+    processedThroughBytes: scan.processedThroughBytes,
+    processedThroughDigest: scan.processedThroughDigest,
+  };
+}
+
+async function rebuild(signal: AbortSignal | undefined): Promise<FailureProjectionResult> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_REBUILD_ATTEMPTS; attempt += 1) {
+    const accumulator = createFailureProjectionAccumulator();
+    try {
+      const scan = await scanUsageLedgerCooperatively({
+        ...(signal ? { signal } : {}),
+        onEntry: entry => accumulator.add(entry),
+      });
+      retained = retain(accumulator, scan, false);
+      return resultFrom(retained, "rebuild");
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof UsageLedgerRebuildRequiredError) || attempt + 1 >= MAX_REBUILD_ATTEMPTS) throw error;
+    }
+  }
+  throw lastError ?? new Error("failure projection rebuild did not settle");
+}
+
+/**
+ * Whether the observed ledger can still be read as an append onto the retained state.
+ *
+ * A same-size file whose revision metadata moved is a replacement or an in-place edit, not an
+ * append. Treating it as one would extend groups built from rows that no longer exist, so it
+ * forces a rebuild even though the byte count is unchanged.
+ */
+function requiresRebuild(state: RetainedProjection, observed: UsageLogRevision | null): boolean {
+  if (state.identityKey !== usageLogIdentityKey(observed)) return true;
+  if (!state.revision || !observed) return state.revision !== observed;
+  if (observed.size < state.revision.size) return true;
+  return observed.size === state.revision.size && usageLogRevisionKey(observed) !== state.revisionKey;
+}
+
+async function append(
+  state: RetainedProjection,
+  signal: AbortSignal | undefined,
+): Promise<FailureProjectionResult> {
+  // Clone first and publish only after the scanner verifies the captured suffix, so a mutation
+  // discovered mid-scan leaves the retained state exactly as it was.
+  const candidate = state.accumulator.clone();
+  try {
+    const scan = await scanUsageLedgerCooperatively({
+      ...(signal ? { signal } : {}),
+      startAtBytes: state.processedThroughBytes,
+      expectedIdentityKey: state.identityKey,
+      expectedProcessedThroughDigest: state.processedThroughDigest,
+      onEntry: entry => candidate.add(entry),
+    });
+    retained = retain(candidate, scan, state.historyIncomplete);
+    return resultFrom(retained, "append");
+  } catch (error) {
+    if (retained === state) retained = null;
+    if (error instanceof UsageLedgerRebuildRequiredError) return rebuild(signal);
+    throw error;
+  }
+}
+
+async function refresh(signal: AbortSignal | undefined): Promise<FailureProjectionResult> {
+  const state = retained;
+  if (!state) return rebuild(signal);
+  const observed = currentUsageLogRevision();
+  if (requiresRebuild(state, observed)) return rebuild(signal);
+  if (observed && state.revision && observed.size === state.revision.size) {
+    return resultFrom(state, "unchanged");
+  }
+  return append(state, signal);
+}
+
+/**
+ * The current grouping, refreshed from the ledger.
+ *
+ * Single-flighted: two concurrent readers would otherwise run two scans of the same file and
+ * one of them would publish over the other's checkpoint.
+ */
+export async function getFailureProjection(
+  options: { signal?: AbortSignal } = {},
+): Promise<FailureProjectionResult> {
+  if (inFlight) return inFlight;
+  const flight = refresh(options.signal).finally(() => {
+    if (inFlight === flight) inFlight = null;
+  });
+  inFlight = flight;
+  return flight;
+}
+
+/**
+ * Drop the retained projection.
+ *
+ * Safe at any time and for any reason: it is rebuildable from the ledger by construction, which
+ * is the property that lets memory pressure discard the whole thing rather than prune individual
+ * groups. Pruning groups would make this projection a retention policy of its own.
+ */
+export function discardRetainedFailureProjection(): number {
+  const count = retained?.accumulator.groupCount ?? 0;
+  retained = null;
+  return count;
+}
+
+/** Test-only process-state reset for isolated harnesses. */
+export function resetFailureProjectionCacheForTests(): void {
+  retained = null;
+  inFlight = null;
+}

package/src/usage/failure-projection.ts

@@ -0,0 +1,174 @@
+/**
+ * Failures grouped by what they have in common, rebuilt from the canonical ledger.
+ *
+ * This is the derived form of #3748. The original built a second durable store; this holds only
+ * a count and two timestamps per group, and every one of them falls out of a scan of
+ * usage.jsonl. Delete a row from the ledger and it leaves this projection on the next rebuild,
+ * which is what it means for retention to have one owner rather than four.
+ *
+ * What it deliberately does NOT hold: the occurrence list the original retained (a second copy
+ * of history with its own retention policy), and the mutable monitoring/dispatched/fixed/ignored
+ * remediation status with its free-text notes. Those are operator state, not event history: they
+ * cannot be reconstructed from immutable request rows, so presenting them as a derived ledger
+ * would be presenting a claim this projection cannot make. They need their own owner if they are
+ * wanted, keyed by the fingerprint below.
+ */
+import { getProviderRegistryEntry } from "../providers/registry";
+import { baseProviderLabel } from "../providers/label";
+import {
+  computeFailureFingerprint,
+  failureStatusClass,
+  FAILURE_FINGERPRINT_VERSION,
+  type FailureFingerprint,
+  type FailureFingerprintFacts,
+} from "./failure-fingerprint";
+import {
+  classifyRequestOutcome,
+  isRequestCloseReason,
+  isRequestTerminalStatus,
+} from "./request-outcome";
+import {
+  isKnownInboundProtocol,
+  isKnownRequestFailureCause,
+  isKnownTerminalSource,
+  isKnownTransportPhase,
+  type PersistedUsageEntry,
+} from "./log";
+
+/**
+ * The configured provider name reduced to a registry member, or null.
+ *
+ * The durable `provider` is whatever the user named their provider entry, so it is open text and
+ * cannot enter a key that promises to carry no content. Resolving it against the registry makes
+ * the value closed by construction: either it is one of the ids this build ships, or it is
+ * nothing. A user who names a provider after themselves groups under `null`, which is the
+ * correct answer -- the projection does not know which provider it is.
+ */
+export function failureProviderClass(provider: string): string | null {
+  return getProviderRegistryEntry(baseProviderLabel(provider))?.id ?? null;
+}
+
+export interface FailureProjectionGroup extends FailureFingerprintFacts {
+  fingerprint: FailureFingerprint;
+  firstSeen: number;
+  lastSeen: number;
+  count: number;
+}
+
+export interface FailureProjectionSnapshot {
+  fingerprintVersion: typeof FAILURE_FINGERPRINT_VERSION;
+  groups: readonly FailureProjectionGroup[];
+  /**
+   * Failed rows written before the recorder stored a cause. Counted rather than bucketed under
+   * an invented "unknown" cause, because a group an operator cannot act on is worse than a
+   * number that says how much history predates the field.
+   */
+  unattributedFailures: number;
+  /** Failed rows whose timestamp is not a finite number, so they cannot date a group. */
+  invalidTimestampFailures: number;
+}
+
+export interface FailureProjectionAccumulator {
+  add(entry: PersistedUsageEntry): void;
+  clone(): FailureProjectionAccumulator;
+  snapshot(): FailureProjectionSnapshot;
+  readonly groupCount: number;
+}
+
+interface MutableGroup extends FailureFingerprintFacts {
+  fingerprint: FailureFingerprint;
+  firstSeen: number;
+  lastSeen: number;
+  count: number;
+}
+
+function factsFor(entry: PersistedUsageEntry): FailureFingerprintFacts | null {
+  if (!isKnownRequestFailureCause(entry.failureCause)) return null;
+  return {
+    cause: entry.failureCause,
+    statusClass: failureStatusClass(entry.status),
+    providerClass: failureProviderClass(entry.provider),
+    inboundProtocol: isKnownInboundProtocol(entry.inboundProtocol) ? entry.inboundProtocol : null,
+    // Validated rather than copied. This is the one tuple slot whose durable type is a plain
+    // string, and it is assembled from an upstream terminal frame, so an unvalidated value is
+    // the single way upstream-controlled text could reach a grouping key.
+    terminalStatus: isRequestTerminalStatus(entry.terminalStatus) ? entry.terminalStatus : null,
+    closeReason: isRequestCloseReason(entry.closeReason) ? entry.closeReason : null,
+    transportPhase: isKnownTransportPhase(entry.transportPhase) ? entry.transportPhase : null,
+    terminalSource: isKnownTerminalSource(entry.terminalSource) ? entry.terminalSource : null,
+  };
+}
+
+function createFrom(groups: Map<string, MutableGroup>, counters: {
+  unattributed: number;
+  invalidTimestamp: number;
+}): FailureProjectionAccumulator {
+  let unattributedFailures = counters.unattributed;
+  let invalidTimestampFailures = counters.invalidTimestamp;
+
+  return {
+    add(entry: PersistedUsageEntry): void {
+      // The shared classifier decides what a failure is, so this projection and the exporter
+      // agree on which rows are in scope. An incomplete turn is not here: it has no cause.
+      if (classifyRequestOutcome(entry) !== "failed") return;
+      const facts = factsFor(entry);
+      if (facts === null) {
+        unattributedFailures += 1;
+        return;
+      }
+      if (typeof entry.timestamp !== "number" || !Number.isFinite(entry.timestamp)) {
+        invalidTimestampFailures += 1;
+        return;
+      }
+      const fingerprint = computeFailureFingerprint(facts);
+      const existing = groups.get(fingerprint);
+      if (existing === undefined) {
+        groups.set(fingerprint, {
+          ...facts,
+          fingerprint,
+          firstSeen: entry.timestamp,
+          lastSeen: entry.timestamp,
+          count: 1,
+        });
+        return;
+      }
+      // Min and max rather than first-and-last-written: a ledger is append-ordered in practice
+      // but nothing in the format promises it, and a projection that assumed order would report
+      // a first-seen later than its last-seen for a hand-merged file.
+      existing.firstSeen = Math.min(existing.firstSeen, entry.timestamp);
+      existing.lastSeen = Math.max(existing.lastSeen, entry.timestamp);
+      existing.count += 1;
+    },
+
+    clone(): FailureProjectionAccumulator {
+      const copy = new Map<string, MutableGroup>();
+      for (const [key, group] of groups) copy.set(key, { ...group });
+      return createFrom(copy, {
+        unattributed: unattributedFailures,
+        invalidTimestamp: invalidTimestampFailures,
+      });
+    },
+
+    snapshot(): FailureProjectionSnapshot {
+      // Most recent first, then by fingerprint, so two runs over the same ledger produce the
+      // same order. A tie broken by insertion order would depend on scan chunking.
+      const ordered = [...groups.values()]
+        .map(group => ({ ...group }))
+        .sort((a, b) => b.lastSeen - a.lastSeen || (a.fingerprint < b.fingerprint ? -1 : a.fingerprint > b.fingerprint ? 1 : 0));
+      return {
+        fingerprintVersion: FAILURE_FINGERPRINT_VERSION,
+        groups: ordered,
+        unattributedFailures,
+        invalidTimestampFailures,
+      };
+    },
+
+    get groupCount(): number {
+      return groups.size;
+    },
+  };
+}
+
+export function createFailureProjectionAccumulator(): FailureProjectionAccumulator {
+  return createFrom(new Map(), { unattributed: 0, invalidTimestamp: 0 });
+}

package/src/usage/ledger-retention.ts

@@ -0,0 +1,165 @@
+/**
+ * Opt-in size limit for the canonical usage ledger (#5063).
+ *
+ * Retention on usage.jsonl is the right architecture -- the alternative is a projection that
+ * deletes rows the ledger still has, which is a second retention policy. What #5063's version
+ * could not promise is that a row appended by another writer between its size snapshot and its
+ * rename survived: it captured a size, copied a suffix, and renamed over whatever was there.
+ *
+ * Two things close that here. The append is synchronous and this runs inside the same call
+ * stack, with no await between the append and the publication, so no in-process append can
+ * interleave. And `validateBeforeRename` re-opens the target immediately before the rename and
+ * refuses unless its identity, size and revision metadata are byte-for-byte what was copied --
+ * so an append from anywhere else aborts the replacement instead of losing the row. The original
+ * file and that append both survive; the next append retries from a fresh revision.
+ *
+ * What remains outside the contract: a program that ignores the OpenCodex ledger owner entirely
+ * can still write between the final comparison and the rename. No portable conditional rename
+ * exists to prevent that, and the honest claim is that the race is closed for every cooperating
+ * writer and detected up to the last possible moment for anything else.
+ */
+import { closeSync, fstatSync, openSync, readSync, writeSync } from "node:fs";
+import { atomicWriteFileStreamed } from "../config/atomic-write";
+import {
+  currentUsageLogRevision,
+  usageLogIdentityKey,
+  usageLogPath,
+  usageLogRevisionKey,
+  type UsageLogRevision,
+} from "./log";
+import {
+  MIN_USAGE_LEDGER_MAX_BYTES,
+  USAGE_LEDGER_RETENTION_TARGET_RATIO,
+} from "./retention-contract";
+
+/** Bounded copy buffer. Matches the ledger scanner's chunk so one storage policy governs both. */
+const COPY_CHUNK_BYTES = 1024 * 1024;
+
+export class UsageLedgerRevisionChangedError extends Error {
+  readonly code = "usage_ledger_revision_changed";
+
+  constructor() {
+    super("usage ledger changed while its retained span was being published");
+    this.name = "UsageLedgerRevisionChangedError";
+  }
+}
+
+export type UsageLedgerRetentionResult =
+  | { kind: "disabled" }
+  | { kind: "unchanged"; currentBytes: number }
+  | { kind: "replaced"; currentBytes: number; removedBytes: number }
+  | { kind: "deferred"; currentBytes: number; reason: "revision-changed" | "no-boundary" };
+
+/**
+ * The first LF at or after `from`, so the retained span starts on a row boundary.
+ *
+ * Any nonempty suffix that is not LF-terminated is uncommitted by the scanner's definition, even
+ * if it happens to parse. Starting anywhere but after an LF would publish half a row as a whole
+ * one, which is the shape that makes a ledger unreadable rather than merely shorter.
+ */
+function firstRowBoundary(fd: number, from: number, end: number): number | null {
+  const buffer = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
+  for (let position = from; position < end;) {
+    const read = readSync(fd, buffer, 0, Math.min(buffer.byteLength, end - position), position);
+    if (read <= 0) return null;
+    const index = buffer.subarray(0, read).indexOf(0x0a);
+    if (index >= 0) return position + index + 1;
+    position += read;
+  }
+  return null;
+}
+
+function copyRange(sourceFd: number, targetFd: number, from: number, to: number): void {
+  const buffer = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
+  for (let position = from; position < to;) {
+    const read = readSync(sourceFd, buffer, 0, Math.min(buffer.byteLength, to - position), position);
+    if (read <= 0) throw new Error("usage ledger shrank while its retained span was copied");
+    let written = 0;
+    while (written < read) written += writeSync(targetFd, buffer, written, read - written);
+    position += read;
+  }
+}
+
+function sameRevision(a: UsageLogRevision | null, b: UsageLogRevision | null): boolean {
+  return a !== null && b !== null
+    && usageLogIdentityKey(a) === usageLogIdentityKey(b)
+    && usageLogRevisionKey(a) === usageLogRevisionKey(b)
+    && a.size === b.size;
+}
+
+/**
+ * Trim the ledger to the newest whole rows when it exceeds `maxBytes`.
+ *
+ * Rows are copied BYTE FOR BYTE and never parsed or re-serialized. That is what keeps the
+ * failure stage and cause, the attempts, the spend record and any field a later build adds
+ * intact through a compaction: a retention pass that understood the row shape would silently
+ * drop every field it was written before.
+ */
+export function enforceUsageLedgerSizeLimit(
+  maxBytes: number | undefined,
+  /**
+   * Runs after the retained span is copied and before the pre-rename check.
+   *
+   * A parameter rather than an exported flag, so the only way to reach this window is to be the
+   * caller. The revision guard below is the one piece of this module that cannot be observed
+   * from its inputs and outputs, and a contract nothing can drive is a contract nobody has
+   * checked.
+   */
+  options: { onSpanCopied?: () => void } = {},
+): UsageLedgerRetentionResult {
+  if (maxBytes === undefined || !Number.isSafeInteger(maxBytes) || maxBytes < MIN_USAGE_LEDGER_MAX_BYTES) {
+    return { kind: "disabled" };
+  }
+  const captured = currentUsageLogRevision();
+  if (!captured || captured.size <= maxBytes) {
+    return captured ? { kind: "unchanged", currentBytes: captured.size } : { kind: "disabled" };
+  }
+  const path = usageLogPath();
+  // Trim below the ceiling rather than to it, so an append does not immediately re-cross the
+  // line and make every subsequent append pay for a full rewrite.
+  const target = Math.floor(maxBytes * USAGE_LEDGER_RETENTION_TARGET_RATIO);
+  let sourceFd: number;
+  try {
+    sourceFd = openSync(path, "r");
+  } catch {
+    return { kind: "deferred", currentBytes: captured.size, reason: "revision-changed" };
+  }
+  let sourceClosed = false;
+  try {
+    const opened = fstatSync(sourceFd);
+    if (Number(opened.size) !== captured.size || Number(opened.ino) !== captured.ino) {
+      return { kind: "deferred", currentBytes: captured.size, reason: "revision-changed" };
+    }
+    const start = firstRowBoundary(sourceFd, Math.max(0, captured.size - target), captured.size);
+    // No LF in the retained window means one row is larger than the whole target. Deleting it
+    // would empty the ledger to satisfy a ceiling it cannot meet, so nothing is done.
+    if (start === null || start >= captured.size) {
+      return { kind: "deferred", currentBytes: captured.size, reason: "no-boundary" };
+    }
+    atomicWriteFileStreamed(path, descriptor => {
+      copyRange(sourceFd, descriptor, start, captured.size);
+      // Windows cannot replace a destination held open by this reader. The
+      // copied bytes are complete; keep the pathname revision guard below.
+      closeSync(sourceFd);
+      sourceClosed = true;
+      options.onSpanCopied?.();
+    }, {
+      // The last possible moment. Anything that appended, replaced or rewrote the ledger while
+      // the copy ran moves size, inode or revision metadata, and the throw leaves both the
+      // original file and that write exactly as they are.
+      validateBeforeRename: () => {
+        if (!sameRevision(currentUsageLogRevision(), captured)) {
+          throw new UsageLedgerRevisionChangedError();
+        }
+      },
+    });
+    return { kind: "replaced", currentBytes: captured.size - start, removedBytes: start };
+  } catch (error) {
+    if (error instanceof UsageLedgerRevisionChangedError) {
+      return { kind: "deferred", currentBytes: captured.size, reason: "revision-changed" };
+    }
+    throw error;
+  } finally {
+    if (!sourceClosed) closeSync(sourceFd);
+  }
+}