import { createHash, type Hash } from "node:crypto";
import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, appendFileSync } from "node:fs";
import { join } from "node:path";
import { getConfigDir } from "../config";
import type { CodexAffinityMove, CodexAffinityReason } from "../codex/routing";
import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
import { recordOwnedConfigPath } from "../lib/config-ownership";
import { redactSecretString, sanitizeLogMetadataString } from "../lib/redact";
import { usageDisplayTotalTokens } from "./totals";
import {
  normalizePersistedJevDecision,
  type PersistedJevDecisionV1,
} from "./jev-stats";
import { normalizeAttemptDeliverySummary } from "./attempt-delivery";
import {
  isRequestCloseReason,
  isRequestTerminalStatus,
  type RequestCloseReason,
  type RequestTerminalStatus,
} from "./request-outcome";
import type { AttemptTierOutcome, OcxUsage } from "../types";
import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
import { parseProtocolTraceV1, type ProtocolTraceV1 } from "../protocols/dto";
import { ACCOUNT_LOG_LABEL_RE, CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
import { claudeCompatibilityReason, normalizeClaudeFeatureCodes, type ClaudeFeatureCode } from "../claude/compatibility";
import type { CodexWsStageRecord } from "../server/responses/codex-ws-wire";
import {
  ATTEMPT_RECOVERY_KIND_ROSTER,
  ATTEMPT_RECOVERY_WITHHELD_ROSTER,
  REQUEST_FAILURE_CAUSES,
  REQUEST_FAILURE_STAGES,
  REQUEST_TRANSPORT_PHASES,
  type AttemptRecoveryKind,
  type AttemptRecoveryWithheld,
  type AttemptDeliverySummary,
  type RequestFailureCause,
  type RequestFailureStage,
  type RequestSpendTotals,
} from "./telemetry-contract";

// Re-exported so every existing importer keeps its path. The declarations moved to a leaf the
// dashboard can import without pulling node:fs and the config barrel into the browser build.
export { ATTEMPT_RECOVERY_KIND_ROSTER, ATTEMPT_RECOVERY_WITHHELD_ROSTER, REQUEST_FAILURE_CAUSES, REQUEST_FAILURE_STAGES };
export type { AttemptRecoveryKind, AttemptRecoveryWithheld, RequestFailureCause, RequestFailureStage, RequestSpendTotals };

export interface PersistedClaudeCompatibilityLog {
  decision: "shadow";
  featureCodes: ClaudeFeatureCode[];
  reason?: string;
}

/** Disk and in-memory callers share a closed-code projection; free-form reasons are discarded. */
export function normalizeClaudeCompatibilityUsageLog(value: unknown): PersistedClaudeCompatibilityLog | undefined {
  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
  const row = value as Record<string, unknown>;
  if (row.decision !== "shadow") return undefined;
  const featureCodes = normalizeClaudeFeatureCodes(row.featureCodes);
  const reason = claudeCompatibilityReason(featureCodes, true);
  if (!reason) return undefined;
  return { decision: "shadow", featureCodes, reason };
}

export type UsageStatus = "reported" | "unreported" | "unsupported" | "estimated";
/**
 * A persisted account label: a Codex pool account (`main`/`p<hex6>`) or a non-Codex OAuth
 * provider account (`o<hex6>`, #2699).
 *
 * The old name `CodexUsageAccountLogLabel` is kept as an alias because it is exported and used
 * across modules; the two predicates below are what callers should choose between.
 */
export type UsageAccountLogLabel = "main" | `p${string}` | `o${string}` | `k${string}`;
export type CodexUsageAccountLogLabel = UsageAccountLogLabel;

/**
 * Accepts EITHER label family. This is the predicate the persistence writers use, so widening
 * it here is what stops six separate call sites from silently dropping an `o`-label -- including
 * two in the live request path (`request-log.ts:972` and `:1187`).
 *
 * The name is unchanged deliberately: renaming it would touch every call site for no behavior,
 * and the widened contract is what every one of those sites wanted.
 */
export function isCodexUsageAccountLogLabel(value: unknown): value is UsageAccountLogLabel {
  return value === "main" || (typeof value === "string" && ACCOUNT_LOG_LABEL_RE.test(value));
}

/** Strictly a Codex pool label. Use when the Codex-only distinction actually matters. */
export function isCodexPoolAccountLogLabel(value: unknown): value is "main" | `p${string}` {
  return value === "main" || (typeof value === "string" && CODEX_ACCOUNT_LOG_LABEL_RE.test(value));
}

/** Request-time upstream credential class, never a credential or account identifier. */
export type UsageCredentialSource = "grok-oauth" | "xai-api-key";

/**
 * Where a row's cache-token detail came from.
 *
 * Strict-client normalization emits zero-default token-detail objects on every bridged wire
 * (`responsesUsage` in src/bridge.ts), so a `cached_tokens: 0` read back off that wire is a
 * wire-compatibility artifact and not a measured cache miss. The three values stay distinct all
 * the way to the summary because folding `synthesized` or `unknown` into `observed` is what
 * lets a pool that discarded every warm prefix still report a plausible cache hit rate (#4546).
 */
export type CacheTelemetryProvenance = "observed" | "synthesized" | "unknown";

const KNOWN_CACHE_PROVENANCE = new Set<CacheTelemetryProvenance>([
  "observed", "synthesized", "unknown",
]);

export function isKnownCacheTelemetryProvenance(value: unknown): value is CacheTelemetryProvenance {
  return typeof value === "string" && KNOWN_CACHE_PROVENANCE.has(value as CacheTelemetryProvenance);
}

/**
 * Classify one usage record's cache detail.
 *
 * `wireParsed` means the counts were read back off a response wire rather than reported raw by
 * the adapter. An all-zero cache detail from that source cannot be told apart from the zero
 * defaults the normalizer writes, so it is `synthesized`; the same shape reported raw is a real
 * zero and stays `observed`. A record with no cache fields at all is `unknown`, which is not a
 * zero either.
 */
export function classifyCacheTelemetryProvenance(
  usage: OcxUsage | undefined,
  options: { wireParsed?: boolean } = {},
): CacheTelemetryProvenance {
  if (!usage) return "unknown";
  const present = [usage.cachedInputTokens, usage.cacheReadInputTokens, usage.cacheCreationInputTokens]
    .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
  if (present.length === 0) return "unknown";
  if (present.some(value => value > 0)) return "observed";
  return options.wireParsed === true ? "synthesized" : "observed";
}

export interface PersistedUsageAttempt {
  ordinal: number;
  provider: string;
  /** Absent on historic attempts and routes whose subscription attribution is unknown. */
  credentialSource?: UsageCredentialSource;
  model: string;
  adapter: string;
  status: number;
  durationMs: number;
  /**
   * True only when the upstream stream died after its 200 head was committed,
   * so the row must not meter as a success the client never received.
   * Absent on ordinary attempts so old rows keep their exact shape.
   */
  streamAborted?: boolean;
  /** TTFT relative to THIS attempt's start (WP4); unset for non-streaming/tool-only. */
  firstOutputMs?: number;
  sendCount: number;
  recoveryKinds: AttemptRecoveryKind[];
  /**
   * Recoveries this attempt was eligible for and did not make. Absent on ordinary attempts so
   * old rows keep their exact shape.
   */
  recoveryWithheld?: AttemptRecoveryWithheld[];
  usageStatus: UsageStatus;
  /**
   * True when the proxy answered this turn locally and issued no upstream request. It travels on
   * the attempt itself rather than as a `finishRequestAttempt` argument because that function is
   * called from six places, and a new parameter would silently default to the wrong answer at any
   * one of them that was missed. Absent on ordinary attempts so old rows keep their exact shape.
   */
  locallyAnswered?: boolean;
  /** Stable non-PII identity for the Codex pool account that served this attempt. */
  accountLogLabel?: CodexUsageAccountLogLabel;
  inputTokenEstimate?: number;
  usage?: OcxUsage;
  totalTokens?: number;
  errorCode?: string;
  /**
   * Provenance of this attempt's cache detail. Absent on rows written before the distinction
   * existed, where `classifyCacheTelemetryProvenance` reconstructs the pre-existing reading.
   */
  cacheProvenance?: CacheTelemetryProvenance;
  /** Installation-local exact Compatibility Lab route-subject digest for this attempt. */
  labRouteSubjectId?: string;
  /** Target-specific reasoning intent and exact adapter-normalized wire parameter. */
  requestedEffort?: string;
  effectiveEffort?: string;
  reasoningWireField?: string;
  reasoningWireValue?: string | number | boolean;
  /** Adapter-produced tier fact for this physical attempt; absent on pre-B0 rows. */
  tierOutcome?: AttemptTierOutcome;
  /**
   * #4191: content-free stage record of a Codex WS upstream exchange that
   * served this attempt (frame size, counters, close code, versions). Absent
   * on HTTP-transport attempts and pre-instrumentation rows. Numbers,
   * booleans, and semver strings only — never reason text, headers, or
   * account identifiers.
   */
  codexWsStage?: CodexWsStageRecord;
  /**
   * What this attempt delivered, as five bounded counts (#3983). Absent on attempts whose
   * transport does not pass through the Responses bridge and on pre-instrumentation rows.
   */
  deliverySummary?: AttemptDeliverySummary;
  /**
   * How far this attempt's exchange got and why it failed, in the shared vocabulary (#2366).
   *
   * Both values are closed roster members, so the pair can be a metric label and a grouping key
   * without a masking pass. Absent on a completed attempt and on every row written before the
   * attribution existed. The resend verdict these two imply is NOT stored: it is derived at read
   * time, so a stored row can never carry a verdict the current table would no longer reach.
   */
  failureStage?: RequestFailureStage;
  failureCause?: RequestFailureCause;
}

/**
 * What one logical request spent upstream, and why (#4546, devlog 040 slice D).
 *
 * `sendCount` counts physical sends per ATTEMPT, which answers the wrong question: a user turn
 * that failed over twice and fanned out to three combo targets is one turn, and the number an
 * operator needs is the total that reached upstream carrying the full prompt. These fields are
 * that total, decomposed by how much of it is explained.
 */
export interface PersistedRequestSpend extends RequestSpendTotals {
  /** Budget profile that produced `reserved`, so a count can be read against the policy it obeyed. */
  policyVersion?: string;
  /**
   * Why the pool binding moved during this request. A move discards the warmed prompt-cache
   * prefix, so the reason belongs next to the send count rather than a page away from it.
   */
  moveReasons?: CodexAffinityReason[];
}

const MAX_PERSISTED_MOVE_REASONS = 8;
// Model selectors are NOT length-bound at admission: configured and discovered
// model ids reach MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH, and the wire `model`
// field is raw client input. Persisting a plain prefix would merge selectors
// that share it, so over-long selectors persist as prefix + a digest of the
// FULL selector — bounded, deterministic, and still exact-matchable.
const MAX_PERSISTED_REQUESTED_MODEL_LEN = 130;
const REQUESTED_MODEL_DIGEST_HEX_LEN = 16;
const LOGICAL_REQUEST_ID_RE = /^[A-Za-z0-9_.:-]{1,64}$/;

/**
 * Persisted form of the wire model selector. Selectors within the bound persist
 * verbatim; longer selectors persist as a prefix plus a short digest of the full
 * value, so two distinct selectors that share the prefix never collapse into one
 * persisted identity. Exact-match readers (`requested_model = ?`) must encode
 * lookup input through this same function. Idempotent — encoded forms fit the
 * bound — which matters because rows are normalized again on read.
 *
 * Idempotence has one cost: a literal selector that equals another selector's
 * persisted form is indistinguishable from it, so both rows share one display
 * value and one exact-match filter. Reaching that needs the caller to send the
 * exact prefix-and-digest string; keeping them apart would need a separate
 * full-selector digest column.
 */
export function encodePersistedRequestedModel(selector: string): string {
  if (selector.length <= MAX_PERSISTED_REQUESTED_MODEL_LEN) return selector;
  const digest = createHash("sha256")
    .update(selector)
    .digest("hex")
    .slice(0, REQUESTED_MODEL_DIGEST_HEX_LEN);
  const prefixLen = MAX_PERSISTED_REQUESTED_MODEL_LEN - REQUESTED_MODEL_DIGEST_HEX_LEN - 1;
  return `${selector.slice(0, prefixLen)}~${digest}`;
}

export function isLogicalRequestId(value: unknown): value is string {
  return typeof value === "string" && LOGICAL_REQUEST_ID_RE.test(value);
}

/**
 * A spend record is trusted only when every count is a non-negative integer and the decomposition
 * holds. A hand-edited row that reports more settled spend than it sent would understate exactly
 * the quantity the record exists to expose, so the whole record is dropped instead.
 */
export function normalizeRequestSpend(value: unknown): PersistedRequestSpend | undefined {
  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
  const spend = value as Record<string, unknown>;
  const count = (raw: unknown): number | null =>
    typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : null;
  const sends = count(spend.sends);
  const settled = count(spend.settled);
  const unresolved = count(spend.unresolved);
  if (sends === null || settled === null || unresolved === null) return undefined;
  if (settled > sends) return undefined;
  const reserved = "reserved" in spend ? count(spend.reserved) : undefined;
  if (reserved === null) return undefined;
  const moveReasons = Array.isArray(spend.moveReasons)
    ? [...new Set(spend.moveReasons.filter(isKnownAffinityReason))].slice(0, MAX_PERSISTED_MOVE_REASONS)
    : [];
  return {
    sends,
    settled,
    unresolved,
    ...(reserved !== undefined ? { reserved } : {}),
    ...(typeof spend.policyVersion === "string" && spend.policyVersion
      ? { policyVersion: capMetadataString(spend.policyVersion) }
      : {}),
    ...(moveReasons.length > 0 ? { moveReasons } : {}),
  };
}

export interface PersistedUsageEntry {
  requestedAlias?: string;
  requestId: string;
  /**
   * Identity of the ONE logical request this row belongs to (#4546), minted by
   * `createRequestExecutionBudget` at ingress. `requestId` identifies a log row; a retry layer,
   * a repair leg and a combo child are all the same logical request, and only this field says so.
   */
  logicalRequestId?: string;
  timestamp: number;
  provider: string;
  model: string;
  surface?: "claude" | "claude-desktop" | "grok";
  /** Matched configured key id; absent for environment/loopback admissions and
   *  for every row written before attribution existed. */
  apiKeyId?: string;
  admissionKind?: "configured" | "environment" | "loopback";
  /** The inbound wire, not the client product — see `surface`. */
  inboundProtocol?: "responses" | "chat" | "messages";
  /** Stable non-PII identity for Codex Pool usage; absent for Direct/non-Codex traffic. */
  accountLogLabel?: CodexUsageAccountLogLabel;
  /** Best-effort chat/session correlation for Logs grouping (#330). */
  conversationId?: string;
  resolvedModel?: string;
  /** Model the upstream actually served (openai-model header or response body). */
  servedModel?: string;
  /** The exact model id sent upstream when it differs from the client-facing `model`. */
  wireModel?: string;
  requestedModel?: string;
  /** Original bare helper model when the opt-in shadow-call route rewrote this request. */
  shadowCallRewrittenFrom?: string;
  /** Reasoning effort / service-tier metadata for GUI Logs after restart. */
  requestedEffort?: string;
  /** Adapter-normalized tier and exact upstream parameter emitted for this request. */
  effectiveEffort?: string;
  reasoningWireField?: string;
  reasoningWireValue?: string | number | boolean;
  /** Raw caller tier captured before routing, sanitized and bounded for durable logs. */
  callerServiceTier?: string;
  requestedServiceTier?: string;
  requestedSpeedLabel?: string;
  configuredServiceTier?: string;
  configuredSpeedLabel?: string;
  modelSupportsServiceTier?: boolean;
  responseServiceTier?: string;
  /** Summary of the final physical attempt for dashboard consumers. */
  tierOutcome?: AttemptTierOutcome;
  status: number;
  durationMs: number;
  /** TTFT relative to the request start (WP4); unset for non-streaming/tool-only. */
  firstOutputMs?: number;
  usageStatus: UsageStatus;
  usage?: OcxUsage;
  totalTokens?: number;
  attempts?: PersistedUsageAttempt[];
  /** Aggregated upstream spend for this logical request; additive, older rows omit it. */
  spend?: PersistedRequestSpend;
  /** Provenance of this row's cache detail; absent rows are reconstructed, never assumed observed. */
  cacheProvenance?: CacheTelemetryProvenance;
  // Failure diagnostics (devlog/_plan/260716_claudecode_hardening/030): persisted for
  // status>=400 or non-completed terminals so incidents survive the in-memory ring buffer.
  errorCode?: string;
  /**
   * Closed, like `closeReason` beside it has always been. It was `string` while it was only
   * rendered; it is a grouping-key slot now, and the value is assembled from an upstream
   * terminal frame, so an open type here is the one way upstream text could reach that key.
   */
  terminalStatus?: RequestTerminalStatus;
  closeReason?: RequestCloseReason;
  /** Already redacted + capped at capture (request-log.ts redactSecretString().slice(0,500)). */
  upstreamError?: string;
  /** Where the terminal/failure was observed; absent on historic rows. */
  transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse";
  /** Whether the terminal came from upstream or a proxy-generated tail. */
  terminalSource?: "upstream" | "synthetic";
  /**
   * What happened to this request's Codex pool binding, and why (#4546). A move discards the
   * prompt-cache prefix warmed on the previous account, so it is recorded as an event rather
   * than left to be inferred from account labels across rows. Additive; older rows omit it.
   */
  affinity?: CodexAffinityMove;
  affinityReason?: CodexAffinityReason;
  /**
   * Set when this request dropped account-bound continuation after a Codex pool
   * account change. Never an account identifier.
   */
  conversationStateScrub?: "account-change";
  /**
   * Bounded route-decision trace (RI-01): why this provider/model/account was
   * selected. Additive field; old rows without it parse unchanged. Never
   * contains prompts, credentials, or hidden reasoning.
   */
  routeDecision?: RouteDecisionTraceV1;
  /** Privacy-bounded JEV selection metadata; model usage remains in attempts[]. */
  jevDecision?: PersistedJevDecisionV1;
  /** Closed Claude protocol codes only; absent on older rows. */
  claudeCompatibility?: PersistedClaudeCompatibilityLog;
  /**
   * Observed protocol path (PF-02): fixed vocabulary only. Re-validated on every read; older
   * rows and rows that fail validation carry none, and are never back-filled by guessing.
   */
  protocolTrace?: ProtocolTraceV1;
  /**
   * How far this request got and why it failed (#2366). Projected from the attempt that ended
   * the request so every surface reads the answer off the same row. Absent on a completed
   * request and on rows written before the attribution existed.
   */
  failureStage?: RequestFailureStage;
  failureCause?: RequestFailureCause;
}

/**
 * Attribution for the logical request, projected from the attempt that ended it (#2366).
 *
 * Carried on the entry as well as the attempt because the three surfaces that have to agree read
 * the entry: a projection that had to reach into `attempts` to answer "why did this fail" would
 * be reading a different row from the exporter, which is the disagreement the landed terminal
 * classifier already removed once.
 */
export interface PersistedRequestFailureAttribution {
  failureStage?: RequestFailureStage;
  failureCause?: RequestFailureCause;
}

const KNOWN_REQUEST_FAILURE_STAGES: ReadonlySet<string> = new Set(REQUEST_FAILURE_STAGES);
const KNOWN_REQUEST_FAILURE_CAUSES: ReadonlySet<string> = new Set(REQUEST_FAILURE_CAUSES);

/**
 * Same closed-set discipline as `isKnownTransportPhase`, with the set DERIVED from the roster
 * rather than restated. The recovery vocabulary was written twice once -- as a union and as the
 * read-back whitelist -- and a member present in only one of them is written to disk and dropped
 * on the next read, which loses exactly the field that says why the row failed.
 */
export function isKnownRequestFailureStage(value: unknown): value is RequestFailureStage {
  return typeof value === "string" && KNOWN_REQUEST_FAILURE_STAGES.has(value);
}

export function isKnownRequestFailureCause(value: unknown): value is RequestFailureCause {
  return typeof value === "string" && KNOWN_REQUEST_FAILURE_CAUSES.has(value);
}

/** The stage/cause pair a normalizer keeps, dropping either half that is not a roster member. */
export function normalizeRequestFailureAttribution(
  raw: { failureStage?: unknown; failureCause?: unknown },
): PersistedRequestFailureAttribution {
  return {
    ...(isKnownRequestFailureStage(raw.failureStage) ? { failureStage: raw.failureStage } : {}),
    ...(isKnownRequestFailureCause(raw.failureCause) ? { failureCause: raw.failureCause } : {}),
  };
}

const KNOWN_USAGE_SURFACES = new Set<NonNullable<PersistedUsageEntry["surface"]>>([
  "claude",
  "claude-desktop",
  "grok",
]);

/**
 * The serializer guard for `surface`. Two failure modes shaped this: a literal
 * whitelist ("claude" | "claude-desktop" only) silently dropped every NEW surface at
 * write time, while a plain truthy spread would persist junk values from hand-edited
 * logs. Membership in this set is the middle path: adding a surface here is one edit,
 * and unknown values are still dropped.
 */
export function isKnownUsageSurface(value: unknown): value is NonNullable<PersistedUsageEntry["surface"]> {
  return typeof value === "string" && KNOWN_USAGE_SURFACES.has(value as NonNullable<PersistedUsageEntry["surface"]>);
}

const KNOWN_ADMISSION_KINDS = new Set<NonNullable<PersistedUsageEntry["admissionKind"]>>([
  "configured", "environment", "loopback",
]);

const KNOWN_INBOUND_PROTOCOLS = new Set<NonNullable<PersistedUsageEntry["inboundProtocol"]>>([
  "responses", "chat", "messages",
]);

/** Same closed-set discipline as `isKnownUsageSurface`: an old or corrupted row
 *  carrying an unexpected value drops the field instead of poisoning the enum. */
export function isKnownAdmissionKind(value: unknown): value is NonNullable<PersistedUsageEntry["admissionKind"]> {
  return typeof value === "string" && KNOWN_ADMISSION_KINDS.has(value as NonNullable<PersistedUsageEntry["admissionKind"]>);
}

export function isKnownInboundProtocol(value: unknown): value is NonNullable<PersistedUsageEntry["inboundProtocol"]> {
  return typeof value === "string" && KNOWN_INBOUND_PROTOCOLS.has(value as NonNullable<PersistedUsageEntry["inboundProtocol"]>);
}

const KNOWN_TRANSPORT_PHASES: ReadonlySet<string> = new Set(REQUEST_TRANSPORT_PHASES);

export function isKnownTransportPhase(value: unknown): value is NonNullable<PersistedUsageEntry["transportPhase"]> {
  return typeof value === "string" && KNOWN_TRANSPORT_PHASES.has(value);
}

const KNOWN_TERMINAL_SOURCES = new Set<NonNullable<PersistedUsageEntry["terminalSource"]>>([
  "upstream", "synthetic",
]);

export function isKnownTerminalSource(value: unknown): value is NonNullable<PersistedUsageEntry["terminalSource"]> {
  return typeof value === "string" && KNOWN_TERMINAL_SOURCES.has(value as NonNullable<PersistedUsageEntry["terminalSource"]>);
}

/**
 * The persisted entry is built by an explicit whitelist, so a field the writer sets but this
 * normalizer does not name is dropped without a word. #4592 added the affinity record at the
 * call site and it never reached disk for exactly that reason.
 */
const KNOWN_AFFINITY_MOVES = new Set<NonNullable<PersistedUsageEntry["affinity"]>>([
  "reused", "held", "detour", "rebound", "new_bind", "cleared",
]);
const KNOWN_AFFINITY_REASONS = new Set<NonNullable<PersistedUsageEntry["affinityReason"]>>([
  "healthy", "quota_headroom", "quota_refusal", "transient", "transient_hold_expired",
  "unusable", "paused", "plan_excluded", "cooldown", "quota_avoided", "generation",
  "expired", "model_lane",
]);
const KNOWN_CONVERSATION_STATE_SCRUBS = new Set<NonNullable<PersistedUsageEntry["conversationStateScrub"]>>([
  "account-change",
]);

export function isKnownAffinityMove(value: unknown): value is NonNullable<PersistedUsageEntry["affinity"]> {
  return typeof value === "string" && KNOWN_AFFINITY_MOVES.has(value as NonNullable<PersistedUsageEntry["affinity"]>);
}

export function isKnownAffinityReason(value: unknown): value is NonNullable<PersistedUsageEntry["affinityReason"]> {
  return typeof value === "string" && KNOWN_AFFINITY_REASONS.has(value as NonNullable<PersistedUsageEntry["affinityReason"]>);
}

export function usageLogPath(configDir?: string): string {
  return join(configDir ?? getConfigDir(), "usage.jsonl");
}

export function usageTotalTokens(usage: OcxUsage | undefined): number | undefined {
  return usageDisplayTotalTokens(usage);
}

/**
 * Providers whose adapters can only estimate usage (no authoritative per-turn frame).
 * Callers should pass the route ADAPTER when available; the name-prefix match is a
 * fallback for paths that only know the configured provider name (e.g. "cursor-mykey").
 */
function isEstimatedUsageProvider(providerOrAdapter: string): boolean {
  return providerOrAdapter === "kiro" || providerOrAdapter.startsWith("kiro-")
    || providerOrAdapter === "cursor" || providerOrAdapter.startsWith("cursor-");
}

export function usageForFinalLog(
  provider: string,
  usage: OcxUsage | undefined,
  /**
   * True when the proxy answered this turn locally and issued no upstream request. Such a turn's
   * zero counts are EXACT, so the provider-wide estimated marking must not apply: Kiro and Cursor
   * are marked estimated because their adapters can only guess a real inference's usage, and a
   * turn with no inference has nothing to guess. Without this, a no-send turn is indistinguishable
   * from a real one whose usage frame never arrived.
   */
  locallyAnswered = false,
): OcxUsage | undefined {
  if (!usage) return undefined;
  if (locallyAnswered) return usage;
  if (usage.estimated || isEstimatedUsageProvider(provider)) return { ...usage, estimated: true };
  return usage;
}

export function usageStatusForFinalLog(usage: OcxUsage | undefined): UsageStatus {
  if (!usage) return "unreported";
  return usage.estimated ? "estimated" : "reported";
}

function normalizeUsageValue(usage: OcxUsage | undefined): OcxUsage | undefined {
  if (!usage) return undefined;
  return {
    inputTokens: usage.inputTokens,
    outputTokens: usage.outputTokens,
    // Absolute active-context checkpoint (types.ts). Stateful providers such as Kiro report
    // per-attempt usage only, so this field is the ONLY carrier of the cumulative context
    // figure once the log records raw adapter usage instead of re-parsing the bridged wire
    // (usageFromBridge, request-log.ts). Omitting it here silently dropped Kiro's context
    // growth from every persisted row. It is deliberately NOT folded into totalTokens:
    // a checkpoint is not a per-request total and must never be summed across requests.
    ...(typeof usage.contextTotalTokens === "number" ? { contextTotalTokens: usage.contextTotalTokens } : {}),
    ...(typeof usage.totalTokens === "number" ? { totalTokens: usage.totalTokens } : {}),
    ...(typeof usage.cachedInputTokens === "number" ? { cachedInputTokens: usage.cachedInputTokens } : {}),
    ...(typeof usage.cacheReadInputTokens === "number" ? { cacheReadInputTokens: usage.cacheReadInputTokens } : {}),
    ...(typeof usage.cacheCreationInputTokens === "number" ? { cacheCreationInputTokens: usage.cacheCreationInputTokens } : {}),
    ...(typeof usage.reasoningOutputTokens === "number" ? { reasoningOutputTokens: usage.reasoningOutputTokens } : {}),
    ...(isNonNegativeFiniteNumber(usage.providerCredits) ? { providerCredits: usage.providerCredits } : {}),
    ...(usage.estimated ? { estimated: true } : {}),
  };
}

const ATTEMPT_RECOVERY_KINDS: ReadonlySet<AttemptRecoveryKind> = new Set(ATTEMPT_RECOVERY_KIND_ROSTER);
const ATTEMPT_RECOVERY_WITHHELD: ReadonlySet<AttemptRecoveryWithheld> = new Set(ATTEMPT_RECOVERY_WITHHELD_ROSTER);
const USAGE_STATUSES = new Set<UsageStatus>([
  "reported",
  "unreported",
  "unsupported",
  "estimated",
]);
const LAB_ROUTE_SUBJECT_ID_RE = /^[0-9a-f]{64}$/;
const FAST_OUTCOMES = new Set<AttemptTierOutcome["fastOutcome"]>([
  "not-requested", "applied", "downgraded", "unknown",
]);
const TIER_CONFIRMATIONS = new Set<AttemptTierOutcome["confirmation"]>([
  "confirmed", "assumed", "downgraded", "unknown",
]);
const FAST_DOWNGRADE_REASONS = new Set<NonNullable<AttemptTierOutcome["fastDowngradeReason"]>>([
  "route-unsupported", "wire-unavailable", "response-declined",
]);

export function isLabRouteSubjectId(value: unknown): value is string {
  return typeof value === "string" && LAB_ROUTE_SUBJECT_ID_RE.test(value);
}

function isNonNegativeFiniteNumber(value: unknown): value is number {
  return typeof value === "number" && Number.isFinite(value) && value >= 0;
}

function normalizeAttemptUsage(raw: unknown): OcxUsage | null {
  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
  const usage = raw as Record<string, unknown>;
  if (!isNonNegativeFiniteNumber(usage.inputTokens)
    || !isNonNegativeFiniteNumber(usage.outputTokens)) return null;
  for (const key of [
    "contextTotalTokens",
    "totalTokens",
    "cachedInputTokens",
    "cacheReadInputTokens",
    "cacheCreationInputTokens",
    "reasoningOutputTokens",
    "providerCredits",
  ] as const) {
    if (key in usage && !isNonNegativeFiniteNumber(usage[key])) return null;
  }
  if ("estimated" in usage && typeof usage.estimated !== "boolean") return null;
  return normalizeUsageValue(usage as unknown as OcxUsage) ?? null;
}

function normalizeAttemptTierOutcome(raw: unknown): AttemptTierOutcome | null {
  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
  const outcome = raw as Record<string, unknown>;
  if (typeof outcome.fastOutcome !== "string"
    || !FAST_OUTCOMES.has(outcome.fastOutcome as AttemptTierOutcome["fastOutcome"])
    || typeof outcome.confirmation !== "string"
    || !TIER_CONFIRMATIONS.has(outcome.confirmation as AttemptTierOutcome["confirmation"])) {
    return null;
  }
  if ("canonical" in outcome && outcome.canonical !== "priority") return null;
  if ("wireKind" in outcome
    && outcome.wireKind !== null
    && outcome.wireKind !== "service-tier"
    && outcome.wireKind !== "anthropic-speed"
    && outcome.wireKind !== "cursor-variant"
    && outcome.wireKind !== "model-variant") return null;
  if ("wireValue" in outcome && outcome.wireValue !== null && typeof outcome.wireValue !== "string") return null;
  if ("fastDowngradeReason" in outcome
    && (typeof outcome.fastDowngradeReason !== "string"
      || !FAST_DOWNGRADE_REASONS.has(outcome.fastDowngradeReason as NonNullable<AttemptTierOutcome["fastDowngradeReason"]>))) {
    return null;
  }
  if ("callerTierDropped" in outcome && typeof outcome.callerTierDropped !== "boolean") return null;
  if ("callerFastSuppressedByConfig" in outcome
    && typeof outcome.callerFastSuppressedByConfig !== "boolean") return null;
  if ("responseServiceTier" in outcome && typeof outcome.responseServiceTier !== "string") return null;
  if ("responseTierAuthoritative" in outcome && typeof outcome.responseTierAuthoritative !== "boolean") return null;
  const wireValue = sanitizeLogMetadataString(outcome.wireValue);
  const responseServiceTier = sanitizeLogMetadataString(outcome.responseServiceTier);
  return {
    ...(outcome.canonical === "priority" ? { canonical: "priority" as const } : {}),
    ...(outcome.wireKind === null
      || outcome.wireKind === "service-tier"
      || outcome.wireKind === "anthropic-speed"
      || outcome.wireKind === "cursor-variant"
      || outcome.wireKind === "model-variant"
      ? { wireKind: outcome.wireKind }
      : {}),
    ...(outcome.wireValue === null
      ? { wireValue: null }
      : wireValue ? { wireValue } : {}),
    fastOutcome: outcome.fastOutcome as AttemptTierOutcome["fastOutcome"],
    ...(typeof outcome.fastDowngradeReason === "string"
      ? { fastDowngradeReason: outcome.fastDowngradeReason as NonNullable<AttemptTierOutcome["fastDowngradeReason"]> }
      : {}),
    ...(typeof outcome.callerTierDropped === "boolean" ? { callerTierDropped: outcome.callerTierDropped } : {}),
    ...(typeof outcome.callerFastSuppressedByConfig === "boolean"
      ? { callerFastSuppressedByConfig: outcome.callerFastSuppressedByConfig }
      : {}),
    confirmation: outcome.confirmation as AttemptTierOutcome["confirmation"],
    ...(typeof outcome.responseTierAuthoritative === "boolean"
      ? { responseTierAuthoritative: outcome.responseTierAuthoritative }
      : {}),
    ...(responseServiceTier ? { responseServiceTier } : {}),
  };
}

function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
  const attempt = raw as Record<string, unknown>;
  if (typeof attempt.ordinal !== "number" || !Number.isInteger(attempt.ordinal)
    || attempt.ordinal < 1
    || typeof attempt.provider !== "string" || !attempt.provider
    || typeof attempt.model !== "string" || !attempt.model
    || typeof attempt.adapter !== "string" || !attempt.adapter
    || typeof attempt.status !== "number" || !Number.isInteger(attempt.status)
    || attempt.status < 100 || attempt.status > 599
    || typeof attempt.durationMs !== "number" || !Number.isFinite(attempt.durationMs)
    || attempt.durationMs < 0
    || typeof attempt.sendCount !== "number" || !Number.isInteger(attempt.sendCount)
    || attempt.sendCount < 0
    || typeof attempt.usageStatus !== "string"
    || !USAGE_STATUSES.has(attempt.usageStatus as UsageStatus)) {
    return null;
  }
  if ("inputTokenEstimate" in attempt
    && !isNonNegativeFiniteNumber(attempt.inputTokenEstimate)) return null;
  if ("firstOutputMs" in attempt
    && !isNonNegativeFiniteNumber(attempt.firstOutputMs)) return null;
  if ("totalTokens" in attempt
    && !isNonNegativeFiniteNumber(attempt.totalTokens)) return null;
  const usage = "usage" in attempt ? normalizeAttemptUsage(attempt.usage) : undefined;
  if ("usage" in attempt && usage === null) return null;
  const tierOutcome = "tierOutcome" in attempt
    ? normalizeAttemptTierOutcome(attempt.tierOutcome)
    : undefined;
  const codexWsStage = "codexWsStage" in attempt
    ? normalizeCodexWsStageRecord(attempt.codexWsStage)
    : undefined;
  const deliverySummary = "deliverySummary" in attempt
    ? normalizeAttemptDeliverySummary(attempt.deliverySummary)
    : undefined;
  const recoveryKinds = Array.isArray(attempt.recoveryKinds)
    ? [...new Set(attempt.recoveryKinds.filter(
      (value): value is AttemptRecoveryKind => typeof value === "string"
        && ATTEMPT_RECOVERY_KINDS.has(value as AttemptRecoveryKind),
    ))]
    : [];
  // Same shape as `recoveryKinds`: unknown values are dropped rather than failing the row, so a
  // log written by a newer build stays readable by an older one.
  const recoveryWithheld = Array.isArray(attempt.recoveryWithheld)
    ? [...new Set(attempt.recoveryWithheld.filter(
      (value): value is AttemptRecoveryWithheld => typeof value === "string"
        && ATTEMPT_RECOVERY_WITHHELD.has(value as AttemptRecoveryWithheld),
    ))]
    : [];
  return {
    ordinal: attempt.ordinal as number,
    provider: attempt.provider,
    ...(attempt.provider === "xai"
      && (attempt.credentialSource === "grok-oauth" || attempt.credentialSource === "xai-api-key")
      ? { credentialSource: attempt.credentialSource }
      : {}),
    model: attempt.model,
    adapter: attempt.adapter,
    status: attempt.status,
    durationMs: attempt.durationMs,
    // Absent by default; only the literal `true` marker survives the round trip.
    ...(attempt.streamAborted === true ? { streamAborted: true } : {}),
    ...(attempt.locallyAnswered === true ? { locallyAnswered: true } : {}),
    ...(isNonNegativeFiniteNumber(attempt.firstOutputMs)
      ? { firstOutputMs: attempt.firstOutputMs }
      : {}),
    sendCount: attempt.sendCount as number,
    recoveryKinds,
    ...(recoveryWithheld.length ? { recoveryWithheld } : {}),
    usageStatus: attempt.usageStatus as UsageStatus,
    ...(isCodexUsageAccountLogLabel(attempt.accountLogLabel)
      ? { accountLogLabel: attempt.accountLogLabel }
      : {}),
    ...(isNonNegativeFiniteNumber(attempt.inputTokenEstimate)
      ? { inputTokenEstimate: attempt.inputTokenEstimate }
      : {}),
    ...(usage ? { usage } : {}),
    ...(isNonNegativeFiniteNumber(attempt.totalTokens)
      ? { totalTokens: attempt.totalTokens }
      : {}),
    ...(typeof attempt.errorCode === "string" ? { errorCode: attempt.errorCode } : {}),
    ...(isKnownCacheTelemetryProvenance(attempt.cacheProvenance)
      ? { cacheProvenance: attempt.cacheProvenance }
      : {}),
    ...(isLabRouteSubjectId(attempt.labRouteSubjectId)
      ? { labRouteSubjectId: attempt.labRouteSubjectId }
      : {}),
    ...(typeof attempt.requestedEffort === "string" && attempt.requestedEffort
      ? { requestedEffort: capMetadataString(attempt.requestedEffort) }
      : {}),
    ...(typeof attempt.effectiveEffort === "string" && attempt.effectiveEffort
      ? { effectiveEffort: capMetadataString(attempt.effectiveEffort) }
      : {}),
    ...(typeof attempt.reasoningWireField === "string" && attempt.reasoningWireField
      ? { reasoningWireField: capMetadataString(attempt.reasoningWireField) }
      : {}),
    ...(isValidReasoningWireValue(attempt.reasoningWireField, attempt.reasoningWireValue)
      ? typeof attempt.reasoningWireValue === "string"
        ? { reasoningWireValue: capMetadataString(attempt.reasoningWireValue) }
        : { reasoningWireValue: attempt.reasoningWireValue }
      : {}),
    ...(tierOutcome ? { tierOutcome } : {}),
    ...(codexWsStage ? { codexWsStage } : {}),
    ...(deliverySummary ? { deliverySummary } : {}),
    ...normalizeRequestFailureAttribution(attempt),
  };
}

/**
 * #4191: a persisted stage record is trusted only when every field matches the
 * exchange's own shapes. Anything else — a hand-edited number as a string, an
 * injected free-form field — drops the whole record rather than passing
 * attacker text into the DTO.
 */
function normalizeCodexWsStageRecord(value: unknown): CodexWsStageRecord | undefined {
  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
  const stage = value as Record<string, unknown>;
  for (const key of ["upstreamFrames", "controlFrames", "relayedEvents", "pings", "pongs"] as const) {
    if (!isNonNegativeFiniteNumber(stage[key])) return undefined;
  }
  if (!(stage.requestBytes === null || isNonNegativeFiniteNumber(stage.requestBytes))) return undefined;
  if (!(stage.firstFrameMs === null || isNonNegativeFiniteNumber(stage.firstFrameMs))) return undefined;
  // Records written before firstResponseMs existed omit it; read them as unmeasured.
  const firstResponseMs = stage.firstResponseMs === undefined ? null : stage.firstResponseMs;
  if (!(firstResponseMs === null || isNonNegativeFiniteNumber(firstResponseMs))) return undefined;
  if (!(stage.elapsedMs === null || isNonNegativeFiniteNumber(stage.elapsedMs))) return undefined;
  if (!(stage.closeCode === null || (typeof stage.closeCode === "number"
    && Number.isInteger(stage.closeCode) && stage.closeCode >= 1000 && stage.closeCode <= 4999))) {
    return undefined;
  }
  if (typeof stage.sent !== "boolean" || typeof stage.reused !== "boolean") return undefined;
  if (typeof stage.ocxVersion !== "string" || !stage.ocxVersion || stage.ocxVersion.length > 32) return undefined;
  if (typeof stage.bunVersion !== "string" || !stage.bunVersion || stage.bunVersion.length > 32) return undefined;
  return {
    requestBytes: stage.requestBytes as number | null,
    sent: stage.sent,
    upstreamFrames: stage.upstreamFrames as number,
    controlFrames: stage.controlFrames as number,
    relayedEvents: stage.relayedEvents as number,
    firstFrameMs: stage.firstFrameMs as number | null,
    firstResponseMs: firstResponseMs as number | null,
    elapsedMs: stage.elapsedMs as number | null,
    pings: stage.pings as number,
    pongs: stage.pongs as number,
    closeCode: stage.closeCode as number | null,
    reused: stage.reused,
    ocxVersion: stage.ocxVersion,
    bunVersion: stage.bunVersion,
  };
}

/**
 * Pairing rule for reasoning diagnostics, shared with the live request-log capture path:
 * a non-empty string, a non-negative finite number, or a boolean only for
 * `reasoning.enabled`. The field name itself is validated separately at capture time;
 * persisted rows may carry legacy field names, so this checks only the value shape.
 */
export function isValidReasoningWireValue(
  wireField: unknown,
  wireValue: unknown,
): wireValue is string | number | boolean {
  return (typeof wireValue === "string" && wireValue.length > 0)
    || (typeof wireValue === "number" && Number.isFinite(wireValue) && wireValue >= 0)
    || (wireField === "reasoning.enabled" && typeof wireValue === "boolean");
}

function normalizedAttempts(raw: unknown): PersistedUsageAttempt[] {
  if (!Array.isArray(raw)) return [];
  return raw.map(normalizeUsageAttempt)
    .filter((attempt): attempt is PersistedUsageAttempt => attempt !== null);
}

const MAX_METADATA_STRING_LEN = 64;
function capMetadataString(s: string): string {
  return s.length > MAX_METADATA_STRING_LEN ? s.slice(0, MAX_METADATA_STRING_LEN) : s;
}

const MAX_SERVED_MODEL_LENGTH = 200;
/**
 * An upstream model is an identifier, never free-form text to truncate into one. A value the
 * secret redactor would change is dropped rather than logged, because credential-shaped text can
 * fit the identifier alphabet.
 */
export function sanitizeServedModel(value: unknown): string | undefined {
  return typeof value === "string"
    && value.length <= MAX_SERVED_MODEL_LENGTH
    && /^[A-Za-z0-9._:/@+-]+$/.test(value)
    && redactSecretString(value) === value
    ? value
    : undefined;
}

/** The identity fields that decide whether a response model is ocx's own echo. */
export interface ServedModelEchoSource {
  provider?: string;
  model?: string;
  wireModel?: string;
  requestedAlias?: string;
  requestedModel?: string;
  /** Client-facing selector this proxy wrote into `response.model` (Anthropic routes keep it). */
  responseModelEcho?: string;
}

/**
 * True when `served` is the client's own selector echoed back rather than a model the upstream
 * reported. Anthropic routes answer with the Codex-facing selector (`anthropic/claude-opus-5-5`),
 * and recording that as the served model painted every such row as rerouted. A value equal to
 * the wire model is never an echo. On adapter paths the upstream's real model is not observable
 * at all, so this only removes a false signal; passthrough `openai-model` observations are kept.
 */
export function isClientSelectorEcho(source: ServedModelEchoSource, served: string | undefined): boolean {
  if (served === undefined) return false;
  const wire = source.wireModel ?? source.model;
  if (served === wire) return false;
  return served === source.responseModelEcho
    || served === source.requestedAlias
    || served === source.requestedModel
    || (source.provider !== undefined && wire !== undefined && served === `${source.provider}/${wire}`);
}

/** Record a response-body model as the served model when it is a real upstream observation. */
export function recordObservedServedModel(
  target: ServedModelEchoSource & { servedModel?: string; resolvedModel?: string; preserveResolvedModelFromRoute?: boolean },
  value: unknown,
): void {
  const servedModel = sanitizeServedModel(value);
  if (!servedModel || isClientSelectorEcho(target, servedModel)) return;
  target.servedModel = servedModel;
  if (!target.preserveResolvedModelFromRoute) target.resolvedModel = servedModel;
}

/**
 * Model identity fields for a log row. The served model is sanitized, and a resolvedModel that
 * only echoed a dropped served model is dropped with it, so the rejected value cannot survive
 * under the other name. A client-selector echo is dropped the same way, which also repairs
 * rows persisted before the echo was filtered at capture.
 */
export function modelIdentityLogFields(source: ServedModelEchoSource & { resolvedModel?: string; servedModel?: unknown }): {
  resolvedModel?: string; servedModel?: string; wireModel?: string;
} {
  const sanitized = sanitizeServedModel(source.servedModel);
  const servedModel = isClientSelectorEcho(source, sanitized) ? undefined : sanitized;
  const resolvedModel = source.servedModel !== undefined && source.resolvedModel === source.servedModel && !servedModel
    ? undefined : source.resolvedModel;
  return {
    ...(resolvedModel ? { resolvedModel } : {}),
    ...(servedModel ? { servedModel } : {}),
    ...(source.wireModel ? { wireModel: source.wireModel } : {}),
  };
}

/** Test seam: the normalization branch old rows take is worth asserting directly. */
export function normalizeUsageEntryForTest(entry: PersistedUsageEntry): PersistedUsageEntry {
  return normalizeUsageEntry(entry);
}

function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
  const attempts = normalizedAttempts(entry.attempts);
  const tierOutcome = entry.tierOutcome ? normalizeAttemptTierOutcome(entry.tierOutcome) : undefined;
  const callerServiceTier = sanitizeLogMetadataString(entry.callerServiceTier);
  const responseServiceTier = sanitizeLogMetadataString(entry.responseServiceTier);
  const shadowCallRewrittenFrom = sanitizeLogMetadataString(entry.shadowCallRewrittenFrom);
  const { servedModel, resolvedModel } = modelIdentityLogFields(entry);
  const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
  const transportPhase = isKnownTransportPhase(entry.transportPhase) ? entry.transportPhase : undefined;
  const terminalSource = isKnownTerminalSource(entry.terminalSource) ? entry.terminalSource : undefined;
  const affinity = isKnownAffinityMove(entry.affinity) ? entry.affinity : undefined;
  // A reason without a move describes nothing, so it is only kept alongside one.
  const affinityReason = affinity !== undefined && isKnownAffinityReason(entry.affinityReason)
    ? entry.affinityReason
    : undefined;
  const conversationStateScrub = typeof entry.conversationStateScrub === "string"
    && KNOWN_CONVERSATION_STATE_SCRUBS.has(entry.conversationStateScrub)
    ? entry.conversationStateScrub
    : undefined;
  const routeDecision = entry.routeDecision
    ? normalizeRouteDecisionTrace(entry.routeDecision)
    : undefined;
  const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
  const spend = normalizeRequestSpend(entry.spend);
  const protocolTrace = parseProtocolTraceV1(entry.protocolTrace);
  return {
    requestId: entry.requestId,
    ...(isLogicalRequestId(entry.logicalRequestId) ? { logicalRequestId: entry.logicalRequestId } : {}),
    timestamp: entry.timestamp,
    provider: entry.provider,
    model: entry.model,
    ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
    ...(typeof entry.apiKeyId === "string" && entry.apiKeyId.trim()
      // Deliberately NOT capped. `capMetadataString` protects free-form metadata
      // from unbounded growth, but this is a lookup key: truncating it makes the
      // persisted id stop matching the configured one, and the rollup silently
      // reports zero for a key that is very much in use.
      ? { apiKeyId: entry.apiKeyId }
      : {}),
    ...(isKnownAdmissionKind(entry.admissionKind) ? { admissionKind: entry.admissionKind } : {}),
    ...(isKnownInboundProtocol(entry.inboundProtocol) ? { inboundProtocol: entry.inboundProtocol } : {}),
    ...(isCodexUsageAccountLogLabel(entry.accountLogLabel)
      ? { accountLogLabel: entry.accountLogLabel }
      : {}),
    ...(typeof entry.conversationId === "string" && entry.conversationId.trim()
      ? { conversationId: entry.conversationId.trim().slice(0, 128) }
      : {}),
    ...(resolvedModel ? { resolvedModel } : {}),
    ...(servedModel ? { servedModel } : {}),
    ...(entry.wireModel ? { wireModel: entry.wireModel } : {}),
    ...(typeof entry.requestedModel === "string" && entry.requestedModel
      ? { requestedModel: encodePersistedRequestedModel(entry.requestedModel) }
      : {}),
    ...(shadowCallRewrittenFrom ? { shadowCallRewrittenFrom } : {}),
    ...(typeof entry.requestedEffort === "string" && entry.requestedEffort
      ? { requestedEffort: capMetadataString(entry.requestedEffort) }
      : {}),
    ...(typeof entry.effectiveEffort === "string" && entry.effectiveEffort
      ? { effectiveEffort: capMetadataString(entry.effectiveEffort) }
      : {}),
    ...(typeof entry.reasoningWireField === "string" && entry.reasoningWireField
      ? { reasoningWireField: capMetadataString(entry.reasoningWireField) }
      : {}),
    ...(isValidReasoningWireValue(entry.reasoningWireField, entry.reasoningWireValue)
      ? typeof entry.reasoningWireValue === "string"
        ? { reasoningWireValue: capMetadataString(entry.reasoningWireValue) }
        : { reasoningWireValue: entry.reasoningWireValue }
      : {}),
    ...(callerServiceTier ? { callerServiceTier } : {}),
    ...(typeof entry.requestedServiceTier === "string" && entry.requestedServiceTier
      ? { requestedServiceTier: capMetadataString(entry.requestedServiceTier) }
      : {}),
    ...(typeof entry.requestedSpeedLabel === "string" && entry.requestedSpeedLabel
      ? { requestedSpeedLabel: capMetadataString(entry.requestedSpeedLabel) }
      : {}),
    ...(typeof entry.configuredServiceTier === "string" && entry.configuredServiceTier
      ? { configuredServiceTier: capMetadataString(entry.configuredServiceTier) }
      : {}),
    ...(typeof entry.configuredSpeedLabel === "string" && entry.configuredSpeedLabel
      ? { configuredSpeedLabel: capMetadataString(entry.configuredSpeedLabel) }
      : {}),
    ...(typeof entry.modelSupportsServiceTier === "boolean"
      ? { modelSupportsServiceTier: entry.modelSupportsServiceTier }
      : {}),
    ...(responseServiceTier ? { responseServiceTier } : {}),
    ...(tierOutcome ? { tierOutcome } : {}),
    status: entry.status,
    durationMs: entry.durationMs,
    ...(isNonNegativeFiniteNumber(entry.firstOutputMs)
      ? { firstOutputMs: entry.firstOutputMs }
      : {}),
    usageStatus: entry.usageStatus,
    ...(entry.usage ? { usage: normalizeUsageValue(entry.usage) } : {}),
    ...(typeof entry.totalTokens === "number" ? { totalTokens: entry.totalTokens } : {}),
    ...(Array.isArray(entry.attempts) ? { attempts } : {}),
    ...(spend ? { spend } : {}),
    ...(isKnownCacheTelemetryProvenance(entry.cacheProvenance)
      ? { cacheProvenance: entry.cacheProvenance }
      : {}),
    ...(transportPhase ? { transportPhase } : {}),
    ...(terminalSource ? { terminalSource } : {}),
    ...(affinity ? { affinity } : {}),
    ...(affinityReason ? { affinityReason } : {}),
    ...(conversationStateScrub ? { conversationStateScrub } : {}),
    ...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
    // Validated rather than copied on truthiness, like the inbound protocol and transport phase
    // above. Harmless while these were only rendered; not harmless once the terminal status is
    // a grouping-key slot, because the string is assembled from an upstream frame.
    ...(isRequestTerminalStatus(entry.terminalStatus) ? { terminalStatus: entry.terminalStatus } : {}),
    ...(isRequestCloseReason(entry.closeReason) ? { closeReason: entry.closeReason } : {}),
    ...(entry.upstreamError ? { upstreamError: entry.upstreamError } : {}),
    ...(routeDecision ? { routeDecision } : {}),
    ...(jevDecision ? { jevDecision } : {}),
    ...(claudeCompatibility ? { claudeCompatibility } : {}),
    ...(protocolTrace ? { protocolTrace } : {}),
    ...normalizeRequestFailureAttribution(entry),
  };
}

// Bound hot-path filesystem hardening to once per second while ensuring an external mode
// widening cannot suppress write-triggered repair for the lifetime of the process.
const USAGE_LOG_PERMISSION_RECHECK_MS = 1_000;

type UsageLogPermissionCheck = {
  path: string;
  checkedAt: number;
};

let ensuredUsageLogDir: UsageLogPermissionCheck | null = null;
let ensuredUsageLogFile: UsageLogPermissionCheck | null = null;

function usageLogPermissionCheckIsCurrent(
  check: UsageLogPermissionCheck | null,
  path: string,
  now: number,
): boolean {
  return check?.path === path
    && now >= check.checkedAt
    && now - check.checkedAt < USAGE_LOG_PERMISSION_RECHECK_MS;
}

function ensureUsageLogDir(now: number): void {
  const dir = getConfigDir();
  if (usageLogPermissionCheckIsCurrent(ensuredUsageLogDir, dir, now)) return;
  recordOwnedConfigPath(dir, usageLogPath());
  mkdirSync(dir, { recursive: true, mode: 0o700 });
  try { chmodSync(dir, 0o700); } catch { /* best-effort on platforms that ignore chmod */ }
  ensuredUsageLogDir = { path: dir, checkedAt: now };
}

/**
 * One owner hook, run after an append lands.
 *
 * A slot rather than a direct call, because the only consumer -- ledger retention -- reads this
 * module's revision helpers, and importing it back here would be a static cycle. The hook runs
 * INSIDE the synchronous append call stack on purpose: that is what makes "no in-process append
 * can interleave with a compaction" true rather than merely likely.
 */
let afterUsageLedgerAppend: (() => void) | null = null;

export function setUsageLedgerAppendHook(hook: (() => void) | null): void {
  afterUsageLedgerAppend = hook;
}

export function appendUsageEntry(entry: PersistedUsageEntry): void {
  const line = `${JSON.stringify(normalizeUsageEntry(entry))}\n`;
  const path = usageLogPath();
  const now = Date.now();
  const doAppend = (): void => {
    ensureUsageLogDir(now);
    const filePermissionsCurrent = usageLogPermissionCheckIsCurrent(ensuredUsageLogFile, path, now);
    appendFileSync(path, line, { encoding: "utf-8", mode: 0o600 });
    if (!filePermissionsCurrent) {
      try { chmodSync(path, 0o600); } catch { /* best-effort on platforms that ignore chmod */ }
      ensuredUsageLogFile = { path, checkedAt: now };
    }
  };
  try {
    doAppend();
  } catch (error: any) {
    if (error?.code === "ENOENT") {
      ensuredUsageLogDir = null;
      ensuredUsageLogFile = null;
      doAppend();
      afterUsageLedgerAppend?.();
      return;
    }
    throw error;
  }
  afterUsageLedgerAppend?.();
}

export type UsageLogRevision = {
  path: string;
  dev: number;
  ino: number;
  birthtimeMs: number;
  size: number;
  mtimeMs: number;
  ctimeMs: number;
};

let usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
const MANAGEMENT_USAGE_MAX_READ_BYTES = 64 * 1024 * 1024;
const RECENT_USAGE_MAX_READ_BYTES = 64 * 1024 * 1024;
const MANAGEMENT_USAGE_READ_CHUNK_BYTES = 1024 * 1024;
const MANAGEMENT_USAGE_MAX_ENTRIES_DEFAULT = 500_000;
/**
 * Row cap for a management snapshot. Overridable only so tests can reach the cap without
 * building a half-million-row fixture; production always uses the default.
 */
let MANAGEMENT_USAGE_MAX_ENTRIES = MANAGEMENT_USAGE_MAX_ENTRIES_DEFAULT;

export function setManagementUsageMaxEntriesForTests(value: number | null): void {
  MANAGEMENT_USAGE_MAX_ENTRIES = value ?? MANAGEMENT_USAGE_MAX_ENTRIES_DEFAULT;
}
const MANAGEMENT_USAGE_FLIGHT_STALE_MS = 30_000;
export interface ManagementUsageSnapshot {
  entries: PersistedUsageEntry[];
  revision: UsageLogRevision;
  truncatedPrefixBytes: number;
  entriesTruncated: boolean;
  entriesDropped: number;
  /** Digest of the covered prefix, used to detect an in-place rewrite before reuse. */
  prefixDigest: string;
  /**
   * Byte offset where the RETAINED ROWS begin.
   *
   * Distinct from `truncatedPrefixBytes`, which is the API-visible "bytes skipped by the
   * byte window" signal and must stay independent of entry-count truncation. When the
   * entry cap drops rows, those bytes are not window truncation, but the retained rows do
   * start later -- this field tracks that so the byte accounting stays exact.
   */
  rowsBeginAtBytes: number;
  /**
   * Byte length of each returned row, in order, including its newline.
   *
   * Lets a later read trim rows that have fallen out of the bounded window without
   * re-reading or re-parsing them, which is what keeps the returned set equal to the
   * window the caller asked for.
   */
  entryLengths: number[];
  /** Unparseable bytes after the last returned row; the next read folds them forward. */
  trailingSkippedBytes: number;
}
let managementUsageReadInflight: {
  key: string;
  openedSize: number;
  promise: Promise<ManagementUsageSnapshot>;
  startedAt: number;
  abort: AbortController;
} | null = null;

/**
 * Append-tolerant snapshot of the last management read.
 *
 * The management reader parses a 64 MiB tail into ~53k objects, which costs roughly
 * 640 MB of transient RSS per cold call. The JS objects are collected promptly, but
 * the allocator does not return those pages, so every cold miss ratchets process RSS
 * upward and never comes back down (observed: 7.9 GiB RSS against a 130 MB JS heap).
 *
 * Reparsing an unchanged prefix is what makes that transient recur. `usage.jsonl` is
 * append-only under a stable identity, so when the file has only grown we keep the
 * previously parsed rows and parse just the appended bytes. This is retained state, so
 * it is registered with the app-owned memory budget and is evictable under pressure.
 */
interface RetainedUsageSnapshot {
  identityKey: string;
  maxReadBytes: number;
  /** Absolute end offset in the file that `entries` already covers. */
  coveredThroughBytes: number;
  /**
   * Digest of the last bytes of the covered prefix, re-verified before extending.
   *
   * Identity (path/dev/ino/birthtime) intentionally ignores size and mtime so appends
   * can share work, which also means an in-place rewrite that keeps the inode is
   * invisible to it. A hand-edit or external compaction can therefore replace history
   * under a stable identity without shrinking the file. Re-reading this trailing window
   * catches that: if the bytes behind `coveredThroughBytes` changed, the retained rows
   * no longer describe the file and must not be extended.
   */
  prefixDigest: string;
  /** Bytes of the file skipped ahead of the retained window. */
  truncatedPrefixBytes: number;
  /** Byte length of each retained row, so out-of-window rows can be trimmed exactly. */
  entryLengths: number[];
  /** Unparseable bytes after the last retained row; folded into the next row's span. */
  trailingSkippedBytes: number;
  /** Byte offset where the retained rows begin; see ManagementUsageSnapshot. */
  rowsBeginAtBytes: number;
  entries: PersistedUsageEntry[];
  entriesTruncated: boolean;
  entriesDropped: number;
  revision: UsageLogRevision;
  retainedAt: number;
  approxBytes: number;
}
let retainedUsageSnapshot: RetainedUsageSnapshot | null = null;

/** Rough per-row retained cost; exact sizing would cost another full serialization pass. */
const RETAINED_USAGE_ENTRY_BYTES = 512;

/** Chunk size used when digesting a retained region. */
const RETAINED_USAGE_DIGEST_CHUNK_BYTES = 1024 * 1024;

/**
 * Digest a byte range into `hash`; false when it cannot be read.
 *
 * Deliberately not sampled. A sampled digest covers a vanishing fraction of a large
 * prefix (32 KiB of 64 MiB is 0.05%), so an ordinary fixed-width in-place edit -- a
 * redaction script fixing one field, a compaction rewriting a middle region -- lands in
 * a gap by default and the stale rows are served.
 *
 * Hashing from byte 0 on every call is also wrong: that is O(file) per poll while the
 * read it protects is capped at maxReadBytes, so the ratio degrades as the ledger grows
 * and becomes SLOWER than a full read past roughly 1-2 GB. Only the retained REGION
 * (truncatedPrefixBytes..coveredThroughBytes) is hashed. It is never wider than the
 * window, and bytes below the retained start describe no retained row, so reading them
 * would prove nothing.
 */
function updateUsageDigest(hash: Hash, fd: number, from: number, to: number): boolean {
  if (to <= from) return true;
  const buffer = Buffer.allocUnsafe(Math.min(RETAINED_USAGE_DIGEST_CHUNK_BYTES, to - from));
  for (let position = from; position < to;) {
    const length = Math.min(buffer.byteLength, to - position);
    let offset = 0;
    while (offset < length) {
      const read = readSync(fd, buffer, offset, length - offset, position + offset);
      if (read === 0) return false;
      offset += read;
    }
    hash.update(buffer.subarray(0, length));
    position += length;
  }
  return true;
}

/**
 * Digest of `from`..`to`; null when it cannot be read.
 *
 * The range is bound into the digest so a region cannot be confused with an equal-length
 * region at a different offset.
 */
function usageRegionDigest(fd: number, from: number, to: number): string | null {
  if (to <= from) return `${from}:${to}:empty`;
  const hash = createHash("sha256");
  if (!updateUsageDigest(hash, fd, from, to)) return null;
  return `${from}:${to}:${hash.digest("hex")}`;
}

function retainedUsageSnapshotBytes(entries: PersistedUsageEntry[]): number {
  return entries.length * RETAINED_USAGE_ENTRY_BYTES;
}

export function discardRetainedUsageSnapshot(): number {
  const released = retainedUsageSnapshot?.approxBytes ?? 0;
  retainedUsageSnapshot = null;
  return released;
}

export function retainedUsageSnapshotStats(): {
  count: number;
  bytes: number;
  oldestAt: number | null;
} {
  if (!retainedUsageSnapshot) return { count: 0, bytes: 0, oldestAt: null };
  return {
    count: 1,
    bytes: retainedUsageSnapshot.approxBytes,
    oldestAt: retainedUsageSnapshot.retainedAt,
  };
}

/** Test-only observability for proving that unchanged prefixes are not reparsed. */
export function usageReadCacheStatsForTests(): Readonly<typeof usageReadCacheStats> {
  return { ...usageReadCacheStats };
}

export function resetUsageReadCacheForTests(): void {
  usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
  managementUsageReadInflight?.abort.abort();
  managementUsageReadInflight = null;
  retainedUsageSnapshot = null;
  ensuredUsageLogDir = null;
  ensuredUsageLogFile = null;
}

function readExactly(fd: number, length: number, position: number): Buffer | null {
  const output = Buffer.allocUnsafe(length);
  let offset = 0;
  while (offset < length) {
    const read = readSync(fd, output, offset, length - offset, position + offset);
    if (read === 0) return null;
    offset += read;
  }
  return output;
}

function usageLogRevision(path: string, stat: ReturnType<typeof fstatSync>): UsageLogRevision {
  if (!stat.isFile()) throw new Error("usage log is not a regular file");
  return {
    path,
    dev: Number(stat.dev),
    ino: Number(stat.ino),
    birthtimeMs: Number(stat.birthtimeMs),
    size: Number(stat.size),
    mtimeMs: Number(stat.mtimeMs),
    ctimeMs: Number(stat.ctimeMs),
  };
}

export function usageLogRevisionKey(revision: UsageLogRevision | null): string {
  if (!revision) return "missing";
  return [
    revision.path,
    revision.dev,
    revision.ino,
    revision.birthtimeMs,
    revision.size,
    revision.mtimeMs,
    revision.ctimeMs,
  ].join("\0");
}

/** Identity of the usage ledger file, excluding size/mtime/ctime so appends can share work. */
export function usageLogIdentityKey(revision: UsageLogRevision | null): string {
  if (!revision) return "missing";
  return [revision.path, revision.dev, revision.ino, revision.birthtimeMs].join("\0");
}

export function currentUsageLogRevision(): UsageLogRevision | null {
  const path = usageLogPath();
  if (!existsSync(path)) return null;
  let fd: number | undefined;
  try {
    fd = openSync(path, "r");
    return usageLogRevision(path, fstatSync(fd));
  } finally {
    if (fd !== undefined) closeSync(fd);
  }
}

async function parseUsageTextCooperatively(text: string, signal: AbortSignal): Promise<{
  entries: PersistedUsageEntry[];
  entriesDropped: number;
  entryLengths: number[];
  /** Bytes of unparseable lines after the final accepted row. */
  trailingSkippedBytes: number;
  /** Bytes of rows removed by the entry cap, which move into the skipped prefix. */
  cappedPrefixBytes: number;
}> {
  // Split on "\n" only, so a CRLF line keeps its "\r" and its byte length stays exact.
  // Splitting on /\r?\n/ consumes two bytes but leaves no way to tell that it did, which
  // made the recorded lengths short by one byte per line on a CRLF ledger and failed the
  // accounting self-check. JSON.parse tolerates the trailing "\r".
  const lines = text.split("\n");
  usageReadCacheStats.parsedLines += lines.filter(line => line.trim()).length;
  const entries: PersistedUsageEntry[] = [];
  // Byte length of each accepted row including its newline, so a later read can trim
  // rows that fall out of the bounded window without re-reading the file.
  const entryLengths: number[] = [];
  const batchSize = 1_000;
  // Bytes of lines that did not yield an entry (malformed JSON, missing requestId, a
  // torn final write). They still occupy space in the file, so they are folded into the
  // next accepted row's recorded length. Dropping them would make the recorded lengths
  // sum to less than the real byte span, and the window trim -- which walks forward by
  // summing those lengths -- would consume extra rows to reach the window start,
  // silently hiding history and desynchronizing truncatedPrefixBytes.
  let pendingSkippedBytes = 0;
  for (let offset = 0; offset < lines.length; offset += batchSize) {
    if (signal.aborted) throw signal.reason;
    const batch = lines.slice(offset, offset + batchSize);
    for (let index = 0; index < batch.length; index++) {
      const line = batch[index]!;
      // The split leaves a trailing "" after the final newline; it occupies no bytes.
      const isLastLine = offset + index === lines.length - 1;
      const lineBytes = Buffer.byteLength(line, "utf-8") + (isLastLine && line === "" ? 0 : 1);
      const parsed = parseUsageLines([line]);
      if (parsed.length === 0) {
        pendingSkippedBytes += lineBytes;
        continue;
      }
      entries.push(parsed[0]!);
      entryLengths.push(lineBytes + pendingSkippedBytes);
      pendingSkippedBytes = 0;
    }
    if (offset + batchSize < lines.length) {
      // JSON parsing dominates large-log startup. Yield between bounded batches so
      // Bun can continue serving health and settings requests on the same thread.
      await new Promise<void>(resolve => setTimeout(resolve, 0));
    }
  }
  // Skipped bytes AFTER the last accepted row belong to no entry length, so report them
  // separately; the trim arithmetic adds them back to keep lengths summing to the span.
  const trailingSkippedBytes = pendingSkippedBytes;
  if (entries.length <= MANAGEMENT_USAGE_MAX_ENTRIES) {
    return { entries, entriesDropped: 0, entryLengths, trailingSkippedBytes, cappedPrefixBytes: 0 };
  }
  const entriesDropped = entries.length - MANAGEMENT_USAGE_MAX_ENTRIES;
  return {
    entries: entries.slice(-MANAGEMENT_USAGE_MAX_ENTRIES),
    entriesDropped,
    entryLengths: entryLengths.slice(-MANAGEMENT_USAGE_MAX_ENTRIES),
    trailingSkippedBytes,
    // Bytes of the rows the cap removed. The caller adds them to its skipped prefix so
    // the recorded lengths keep summing to the byte span they describe.
    cappedPrefixBytes: entryLengths
      .slice(0, entryLengths.length - MANAGEMENT_USAGE_MAX_ENTRIES)
      .reduce((total, length) => total + length, 0),
  };
}

async function readUsageEntriesFullCooperatively(
  path: string,
  signal: AbortSignal,
  maxReadBytes: number,
): Promise<ManagementUsageSnapshot> {
  let fd: number | undefined;
  try {
    fd = openSync(path, "r");
    const stat = fstatSync(fd);
    const size = Number(stat.size);
    const start = Math.max(0, size - maxReadBytes);
    const chunks: Buffer[] = [];
    for (let position = start; position < size;) {
      if (signal.aborted) throw signal.reason;
      const length = Math.min(MANAGEMENT_USAGE_READ_CHUNK_BYTES, size - position);
      const chunk = readExactly(fd, length, position);
      if (chunk === null) throw new Error("usage log changed while it was being read");
      chunks.push(chunk);
      position += length;
    }
    let bytes = Buffer.concat(chunks);
    let truncatedPrefixBytes = start;
    if (start > 0) {
      const preceding = readExactly(fd, 1, start - 1);
      if (preceding === null) throw new Error("usage log changed while it was being read");
      if (preceding[0] !== 0x0a) {
        const newline = bytes.indexOf(0x0a);
        if (newline < 0) {
          truncatedPrefixBytes += bytes.byteLength;
          bytes = Buffer.alloc(0);
        } else {
          truncatedPrefixBytes += newline + 1;
          bytes = bytes.subarray(newline + 1);
        }
      }
    }
    const parsed = await parseUsageTextCooperatively(bytes.toString("utf-8"), signal);
    usageReadCacheStats.fullReads += 1;
    // Rows removed by the entry cap start the retained rows later in the file. That is
    // NOT byte-window truncation, so it must not move truncatedPrefixBytes -- the two
    // signals are independent in the API. It is tracked separately for the byte
    // accounting the incremental reader relies on.
    const rowsBeginAtBytes = truncatedPrefixBytes + parsed.cappedPrefixBytes;
    // Digest the exact prefix these rows describe, so a later incremental read can
    // prove the file was appended to rather than rewritten under the same inode.
    const prefixDigest = usageRegionDigest(fd, rowsBeginAtBytes, Number(stat.size));
    if (prefixDigest === null) throw new Error("usage log changed while it was being read");
    return {
      entries: parsed.entries,
      revision: usageLogRevision(path, stat),
      truncatedPrefixBytes,
      entriesTruncated: parsed.entriesDropped > 0,
      entriesDropped: parsed.entriesDropped,
      prefixDigest,
      entryLengths: parsed.entryLengths,
      trailingSkippedBytes: parsed.trailingSkippedBytes,
      rowsBeginAtBytes,
    };
  } finally {
    if (fd !== undefined) closeSync(fd);
  }
}

/**
 * Parse only the bytes appended since the retained snapshot's covered offset.
 *
 * Returns null when the retained snapshot cannot be extended safely — a different
 * identity or read window, a file that shrank (replacement/truncation), or a covered
 * offset that no longer sits on a record boundary. Callers then fall back to a full
 * bounded read.
 */
async function readUsageEntriesIncrementally(
  path: string,
  signal: AbortSignal,
  maxReadBytes: number,
  retained: RetainedUsageSnapshot,
): Promise<ManagementUsageSnapshot | null> {
  let fd: number | undefined;
  try {
    fd = openSync(path, "r");
    const stat = fstatSync(fd);
    const revision = usageLogRevision(path, stat);
    if (usageLogIdentityKey(revision) !== retained.identityKey) return null;
    const size = Number(stat.size);
    // A shrink means truncation or replacement-in-place; the retained rows may no
    // longer correspond to file contents, so refuse to extend them.
    if (size < retained.coveredThroughBytes) return null;
    // Retained-state reuse is only an optimization. A burst larger than the configured
    // window must re-anchor through the bounded full-tail reader instead of reading and
    // parsing every byte appended since the previous poll.
    if (size - retained.coveredThroughBytes > maxReadBytes) return null;
    // Verify the retained REGION is unchanged before anything is reused. Identity keeps
    // dev/ino/birthtime, and an append and an in-place rewrite both move mtime/ctime
    // forward, so only the bytes themselves settle it.
    //
    // Only `truncatedPrefixBytes..coveredThroughBytes` is hashed: that is exactly the
    // span the retained rows were parsed from, and after trimming it is never wider than
    // maxReadBytes. Hashing from byte 0 instead would make every poll O(file) -- cheaper
    // than a reparse on a 245 MB ledger but MORE expensive past roughly 1-2 GB, turning
    // this optimization into a pessimization on exactly the growth curve an append-only
    // ledger follows. Bytes before the retained start are not described by any retained
    // row, so re-reading them proves nothing.
    const covered = usageRegionDigest(fd, retained.rowsBeginAtBytes, retained.coveredThroughBytes);
    if (covered === null || covered !== retained.prefixDigest) return null;
    // Read and parse ONLY the appended bytes.
    let appendedEntries: PersistedUsageEntry[] = [];
    let appendedLengths: number[] = [];
    let appendedDropped = 0;
    let appendedTrailingSkipped = retained.trailingSkippedBytes;
    if (size > retained.coveredThroughBytes) {
      // The covered offset must land immediately after a newline, or the retained rows
      // and the appended text do not join on a record boundary.
      if (retained.coveredThroughBytes > 0) {
        const preceding = readExactly(fd, 1, retained.coveredThroughBytes - 1);
        if (preceding === null || preceding[0] !== 0x0a) return null;
      }
      const chunks: Buffer[] = [];
      for (let position = retained.coveredThroughBytes; position < size;) {
        if (signal.aborted) throw signal.reason;
        const length = Math.min(MANAGEMENT_USAGE_READ_CHUNK_BYTES, size - position);
        const chunk = readExactly(fd, length, position);
        if (chunk === null) throw new Error("usage log changed while it was being read");
        chunks.push(chunk);
        position += length;
      }
      const appended = await parseUsageTextCooperatively(Buffer.concat(chunks).toString("utf-8"), signal);
      appendedEntries = appended.entries;
      appendedLengths = appended.entryLengths;
      appendedDropped = appended.entriesDropped;
      // A capped appended chunk is not joinable: its dropped rows sit between the
      // retained rows and the kept ones, so the lengths no longer describe a contiguous
      // span. Fall back to a full read.
      if (appended.cappedPrefixBytes > 0) return null;
      // If the appended chunk produced rows, its own trailing skipped bytes become the
      // new trailing remainder; otherwise the earlier remainder still stands and the new
      // skipped bytes add to it.
      appendedTrailingSkipped = appended.entries.length > 0
        ? appended.trailingSkippedBytes
        : retained.trailingSkippedBytes + appended.trailingSkippedBytes;
    }
    // Re-anchor the window in place. Rows that have fallen outside `size - maxReadBytes`
    // are dropped using their recorded byte lengths, so the result is exactly the rows a
    // fresh bounded read would load -- no superset, and truncatedPrefixBytes and
    // snapshotWindow keep describing the read honestly. Refusing here instead would make
    // this path dead code on any ledger past the window, which is precisely the case it
    // exists for.
    const windowStart = Math.max(0, size - maxReadBytes);
    let entries = retained.entries.concat(appendedEntries);
    // Skipped bytes trailing the retained rows sit BETWEEN them and the appended rows, so
    // they belong to the first appended row's span. Folding them in keeps the recorded
    // lengths summing to the true byte distance, which is what the trim walk relies on.
    const joinedLengths = appendedLengths.slice();
    if (retained.trailingSkippedBytes > 0 && joinedLengths.length > 0) {
      joinedLengths[0] = joinedLengths[0]! + retained.trailingSkippedBytes;
    }
    let lengths = retained.entryLengths.concat(joinedLengths);
    let rowsBeginAtBytes = retained.rowsBeginAtBytes;
    // Byte-window truncation advances ONLY here, so it stays exactly what a cold read of
    // this window reports. The entry cap below is entry-count truncation and must not
    // move it -- the two are independent signals in the API.
    let windowTruncatedBytes = retained.truncatedPrefixBytes;
    let dropIndex = 0;
    while (dropIndex < lengths.length && rowsBeginAtBytes < windowStart) {
      rowsBeginAtBytes += lengths[dropIndex]!;
      windowTruncatedBytes += lengths[dropIndex]!;
      dropIndex += 1;
    }
    // If every row is gone and a trailing unparseable remainder still sits before the
    // window start, nothing is left to advance the offset with: the retained span would
    // keep growing past maxReadBytes on each malformed-only append while the accounting
    // still balanced. Re-anchor with a full read instead.
    if (rowsBeginAtBytes < windowStart) return null;
    if (dropIndex > 0) {
      entries = entries.slice(dropIndex);
      lengths = lengths.slice(dropIndex);
    }
    let entriesDropped = retained.entriesDropped + appendedDropped;
    if (entries.length > MANAGEMENT_USAGE_MAX_ENTRIES) {
      // A cold read applies the entry cap to the whole window and reports byte
      // truncation for the window boundary alone. An incremental read arrives at the cap
      // by a different route and cannot reconstruct that ordering from retained state, so
      // continuing here would report a truncatedPrefixBytes that disagrees with a fresh
      // read of the same window. Re-anchor instead.
      //
      // This is reachable in production, not a theoretical branch: rows average ~118
      // bytes on a real ledger, so 500,000 of them occupy ~56 MiB and fit inside the
      // 64 MiB window. Both truncations can therefore apply at once.
      return null;
    }
    // The recorded lengths plus the trailing remainder must account for every byte from
    // the retained rows' start to EOF; if they do not, the lengths and the file have
    // diverged and the retained rows cannot be trusted.
    let accounted = appendedTrailingSkipped;
    for (const length of lengths) accounted += length;
    if (rowsBeginAtBytes + accounted !== size) return null;
    usageReadCacheStats.tailReads += 1;
    // Byte-window truncation is what the API reports, and it stays independent of
    // entry-count truncation. A cold read reports the record boundary it actually landed
    // on, which is where the rows begin MINUS whatever the entry cap removed -- the cap
    // is not window truncation. When nothing was skipped by the window at all, a cold
    // read reports 0.
    const truncatedPrefixBytes = windowTruncatedBytes;
    return {
      entries,
      revision,
      truncatedPrefixBytes,
      // ENTRY-count truncation only. Byte-window truncation is reported by
      // truncatedPrefixBytes, and the route ORs the two itself; folding bytes in here
      // would make a byte-truncated read claim rows were dropped when none were.
      entriesTruncated: entriesDropped > 0,
      entriesDropped,
      // Reuse this read's verified digest only for identical bounds. Growth or trimming
      // needs a new digest of the returned region; metadata alone never proves reuse.
      prefixDigest: rowsBeginAtBytes === retained.rowsBeginAtBytes && size === retained.coveredThroughBytes
        ? covered : usageRegionDigest(fd, rowsBeginAtBytes, size) ?? "",
      entryLengths: lengths,
      trailingSkippedBytes: appendedTrailingSkipped,
      rowsBeginAtBytes,
    };
  } finally {
    if (fd !== undefined) closeSync(fd);
  }
}

/**
 * Management API reader: full parses yield between bounded batches and concurrent
 * callers share work when they observe the same ledger identity and byte window.
 * Appends keep that identity; replacements (inode/birthtime change) start a new flight.
 * The parsed tail is retained under the app-owned memory budget so an append reparses
 * only the appended bytes; the retained rows are evictable and are copied per caller.
 */
export async function readUsageSnapshotForManagement(maxReadBytes = MANAGEMENT_USAGE_MAX_READ_BYTES): Promise<{
  entries: PersistedUsageEntry[];
  revision: UsageLogRevision | null;
  truncatedPrefixBytes: number;
  entriesTruncated: boolean;
  entriesDropped: number;
}> {
  if (!Number.isSafeInteger(maxReadBytes) || maxReadBytes <= 0) throw new RangeError("management usage max read bytes must be positive");
  const path = usageLogPath();
  if (!existsSync(path)) return { entries: [], revision: null, truncatedPrefixBytes: 0, entriesTruncated: false, entriesDropped: 0 };
  const observed = currentUsageLogRevision();
  const key = `${usageLogIdentityKey(observed)}\0${maxReadBytes}`;
  const observedSize = observed?.size ?? 0;
  const existing = managementUsageReadInflight;
  const replacement = Boolean(existing && observedSize < existing.openedSize);
  if (!replacement && existing?.key === key && Date.now() - existing.startedAt <= MANAGEMENT_USAGE_FLIGHT_STALE_MS) {
    const shared = await existing.promise;
    return { ...shared, entries: shared.entries.slice() };
  }
  if (existing && (existing.key !== key || replacement || Date.now() - existing.startedAt > MANAGEMENT_USAGE_FLIGHT_STALE_MS)) {
    existing.abort.abort(new Error("management usage read superseded"));
  } else if (existing) {
    const shared = await existing.promise;
    return { ...shared, entries: shared.entries.slice() };
  }
  const abort = new AbortController();
  const retained = retainedUsageSnapshot;
  const reusable = retained
    && retained.identityKey === usageLogIdentityKey(observed)
    && retained.maxReadBytes === maxReadBytes
      ? retained
      : null;
  const promise = (async (): Promise<ManagementUsageSnapshot> => {
    if (reusable) {
      const incremental = await readUsageEntriesIncrementally(path, abort.signal, maxReadBytes, reusable);
      if (incremental) return incremental;
      // The retained rows could not be extended safely; drop them before the full read
      // so a stale window is never combined with freshly parsed bytes.
      discardRetainedUsageSnapshot();
    }
    return readUsageEntriesFullCooperatively(path, abort.signal, maxReadBytes);
  })();
  managementUsageReadInflight = { key, openedSize: observedSize, promise, startedAt: Date.now(), abort };
  try {
    const snapshot = await promise;
    retainedUsageSnapshot = {
      identityKey: usageLogIdentityKey(snapshot.revision),
      maxReadBytes,
      coveredThroughBytes: snapshot.revision.size,
      prefixDigest: snapshot.prefixDigest,
      truncatedPrefixBytes: snapshot.truncatedPrefixBytes,
      entryLengths: snapshot.entryLengths,
      trailingSkippedBytes: snapshot.trailingSkippedBytes,
      rowsBeginAtBytes: snapshot.rowsBeginAtBytes,
      entries: snapshot.entries,
      entriesTruncated: snapshot.entriesTruncated,
      entriesDropped: snapshot.entriesDropped,
      revision: snapshot.revision,
      retainedAt: Date.now(),
      approxBytes: retainedUsageSnapshotBytes(snapshot.entries),
    };
    enforceAppOwnedMemoryBudget();
    return { ...snapshot, entries: snapshot.entries.slice() };
  } finally {
    if (managementUsageReadInflight?.promise === promise) managementUsageReadInflight = null;
  }
}

export async function readUsageEntriesForManagement(): Promise<PersistedUsageEntry[]> {
  return (await readUsageSnapshotForManagement()).entries;
}

/** Keep legacy optional fields permissive, but reject rows that cannot be safely attributed. */
export function normalizePersistedUsageRow(value: unknown): PersistedUsageEntry | undefined {
  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
  const row = value as Record<string, unknown>;
  if (typeof row.requestId !== "string" || typeof row.provider !== "string") return undefined;
  return normalizeUsageEntry(row as unknown as PersistedUsageEntry);
}

export function readUsageEntries(): PersistedUsageEntry[] {
  const path = usageLogPath();
  if (!existsSync(path)) return [];
  const lines = readFileSync(path, "utf-8").split(/\r?\n/);
  const entries: PersistedUsageEntry[] = [];
  for (const line of lines) {
    if (!line.trim()) continue;
    try {
      const parsed = normalizePersistedUsageRow(JSON.parse(line));
      if (parsed) entries.push(parsed);
    } catch {
      /* keep reading after a partially written or hand-edited line */
    }
  }
  return entries;
}

function parseUsageLines(lines: string[]): PersistedUsageEntry[] {
  const entries: PersistedUsageEntry[] = [];
  for (const line of lines) {
    if (!line.trim()) continue;
    try {
      const parsed = normalizePersistedUsageRow(JSON.parse(line));
      if (parsed) entries.push(parsed);
    } catch {
      /* skip partial / hand-edited lines */
    }
  }
  return entries;
}

/**
 * Read only the newest `limit` usage.jsonl rows without loading the whole append-only
 * file into memory. Used by request-log hydration on `ocx start`.
 */
export function readRecentUsageEntries(limit: number, configDir?: string): PersistedUsageEntry[] {
  if (!Number.isFinite(limit) || limit <= 0) return [];
  const path = usageLogPath(configDir);
  if (!existsSync(path)) return [];
  let fd: number | undefined;
  try {
    fd = openSync(path, "r");
    const size = fstatSync(fd).size;
    if (size <= 0) return [];
    // Trace-sized rows need a larger per-row budget than the pre-trace ledger,
    // but startup hydration must never grow into an unbounded whole-file read.
    const maxWindowBytes = Math.min(size, RECENT_USAGE_MAX_READ_BYTES);
    let windowBytes = Math.min(maxWindowBytes, Math.max(64 * 1024, Math.ceil(limit) * 20 * 1024));
    while (true) {
      const start = Math.max(0, size - windowBytes);
      const buf = Buffer.alloc(size - start);
      readSync(fd, buf, 0, buf.length, start);
      let text = buf.toString("utf-8");
      if (start > 0) {
        const nl = text.indexOf("\n");
        if (nl < 0) {
          if (start === 0 || windowBytes >= maxWindowBytes) break;
          windowBytes = Math.min(maxWindowBytes, windowBytes * 4);
          continue;
        }
        text = text.slice(nl + 1);
      }
      const lines = text.split(/\r?\n/).filter(line => line.trim());
      // Parse ALL lines first, then take the last N valid entries. This way corrupt
      // or partial lines are filtered out during parsing and we always return the
      // most recent N valid rows (not N physical lines minus corrupt ones).
      const entries = parseUsageLines(lines);
      if (entries.length >= limit || start === 0 || windowBytes >= maxWindowBytes) return entries.slice(-limit);
      windowBytes = Math.min(maxWindowBytes, windowBytes * 4);
    }
    return [];
  } catch {
    return [];
  } finally {
    if (fd !== undefined) {
      try { closeSync(fd); } catch { /* ignore */ }
    }
  }
}
