/**
 * Cost estimation core (devlog/_plan/260720_toks_speed_price_columns/010).
 *
 * All prices are display-time ESTIMATES (~$), never billing reproductions:
 * - cache detail comes from provider usage as-reported (no session heuristics);
 * - matching is exact native provider/model ID via the jawcode alias table
 *   (no fuzzy, no case-fold, no resolvedModel/requestedModel fallback);
 * - user-configured provider overlay wins, then jawcode nonzero price, then the expected-price overlay
 *   (verified / verified-derived only), otherwise null => UI shows em dash;
 * - combo sums per-attempt costs and fails closed when any attempt is unpriced.
 */
import {
  findVendorCostByModelId,
  getModelMetadata,
  resolveMetadataProvider,
} from "../generated/model-metadata";
import type { AttemptTierOutcome, OcxUsage } from "../types";
import type { PromptLengthPricing } from "../types/provider";
import { canonicalFastTierMarker } from "../providers/fastwire";
import { CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
import { baseProviderLabel } from "../providers/label";
import type { PersistedUsageAttempt, UsageStatus } from "./log";
import { cacheObservationFromUsage } from "./cache-provenance";
import { canonicalAntigravityUsageModel } from "../providers/antigravity-models";
import { activeAccountPricingProviders, activeConfiguredProviders, activeCreditPrices, activeUserCostOverlays, userCostOverlayVersion } from "./user-cost-overlays";
import { costTokensWithinBound, isValidCreditPriceBound, isRepresentableCreditCount, type CreditBilling } from "./credit-billing";
import {
  EXPECTED_PRICE_OVERLAYS,
  findExpectedPriceOverlay,
  findVerifiedPriceOverride,
  findPriorityPricingRule,
  cursorFastPriceMultiplier,
  cursorFastPriceSource,
  cursorFastPriceSupported,
  findContextTier,
  isLongContext,
  pricingFamilyProvider,
  type Cost4,
  type ExpectedPriceOverlay,
  type ExpectedPriceStatus,
} from "./expected-prices";

/** Published long-context pricing band (#908). */
export type ContextTierName = "long";

export interface PriceResolutionOptions {
  /** False for unresolved slash selectors; exact provider/user rates still apply. */
  allowModelLevelFallback?: boolean;
}

type AttemptCostInput = Pick<PersistedUsageAttempt, "ordinal" | "provider" | "model" | "usage" | "usageStatus" | "tierOutcome" | "cacheProvenance"> & PriceResolutionOptions;

/**
 * Service-tier provenance. `effectiveServiceTier()` collapses these with `??`,
 * but provider-specific long-context rules need to know WHICH source supplied Fast.
 * Current API rows stack Fast and long rates; legacy exclusive rows and unknown
 * vendor combinations still require response-confirmed provenance.
 */
export interface ServiceTierContext {
  responseServiceTier?: string;
  requestedServiceTier?: string;
  configuredServiceTier?: string;
  tierOutcome?: AttemptTierOutcome;
}

export interface CostTokens {
  input: number;
  output: number;
  cacheRead: number;
  cacheWrite: number;
  /** The 1-hour-TTL subset of `cacheWrite`, when the provider reports the split. */
  cacheWrite1h?: number;
}

export interface CostBreakdown {
  input: number;
  output: number;
  cacheRead: number;
  cacheWrite: number;
  total: number;
}

export interface MatchedPrice {
  provider: string;
  modelId: string;
  jawcodeProvider?: string;
  cost4: Cost4;
  promptLengthPricing?: PromptLengthPricing;
  source: "jawcode" | "expected" | "user";
  sourceRef?: string;
  verifiedAt?: string;
  status: "verified" | "verified-derived";
}

export interface AttemptCostEstimate {
  ordinal: number;
  provider: string;
  model: string;
  tokens: CostTokens | null;
  price: MatchedPrice;
  cost: CostBreakdown;
  estimated: boolean;
  /** Applied provider priority-tier multiplier (undefined or 1 = standard). */
  priorityMultiplier?: number;
  /** Set when the published long-context rate was applied (#908). */
  contextTier?: ContextTierName;
  /** User absolute rates selected for this attempt, separate from catalog tiers. */
  customThresholdApplied?: true;
  /** The numeric estimate is a known floor because the exact Priority price is unavailable. */
  priorityLowerBound?: boolean;
  /**
   * How this attempt was billed. Present only when provider credits priced it: `cost` is then
   * `providerCredits x creditPriceUsd` and its four token fields carry no allocation.
   */
  billing?: CreditBilling;
}

export interface CostEstimate {
  tokens: CostTokens | null;
  cost: CostBreakdown;
  estimated: boolean;
  attempts?: AttemptCostEstimate[];
  price?: MatchedPrice;
  /** Applied provider priority-tier multiplier (undefined or 1 = standard). */
  priorityMultiplier?: number;
  /** Set when any priced attempt used the published long-context rate (#908). */
  contextTier?: ContextTierName;
  /** At least one request/attempt selected the user threshold rates. */
  customThresholdApplied?: true;
  /** The aggregate satisfies the lower-bound rule for its billing basis. */
  priorityLowerBound?: boolean;
  /**
   * Billing basis for the aggregate. `provider-credits` means every priced attempt shared one
   * credit price and the credits are summed; `mixed` means the attempts were not all billed the
   * same way, so the total is real but the split is only available per attempt.
   */
  billing?: CreditBilling;
}

function finiteNonNegative(value: number): boolean {
  return Number.isFinite(value) && value >= 0;
}

function validCost4(cost: Cost4 | undefined): cost is Cost4 {
  return !!cost
    && finiteNonNegative(cost.input)
    && finiteNonNegative(cost.output)
    && finiteNonNegative(cost.cacheRead)
    && finiteNonNegative(cost.cacheWrite);
}

function hasNonZeroCost(cost: Cost4): boolean {
  return cost.input !== 0 || cost.output !== 0
    || cost.cacheRead !== 0 || cost.cacheWrite !== 0;
}

/**
 * Normalize inclusive OcxUsage (types.ts: inputTokens INCLUDES cache read/write)
 * into jawcode CostTokens (input = uncached prompt only) without double-charging.
 *
 * Canonical-first with a single legacy retry: the canonical contract says
 * `cachedInputTokens` is read-only tokens, but legacy claude-route rows stored
 * read+write combined there (devlog 070). The two shapes are indistinguishable
 * by fields alone, so we apply the canonical reading first and only when it
 * produces an impossible R+W>I do we retry the legacy recovery
 * (cached - creation). If both readings are contradictory, fail closed (null).
 */
export function normalizeCostTokens(usage: OcxUsage): CostTokens | null {
  const input = usage.inputTokens;
  const output = usage.outputTokens;
  const cacheWrite = usage.cacheCreationInputTokens ?? 0;
  const primaryRead = usage.cacheReadInputTokens ?? usage.cachedInputTokens ?? 0;
  const candidates: number[] = [primaryRead];
  if (typeof usage.cacheReadInputTokens !== "number"
    && typeof usage.cachedInputTokens === "number"
    && typeof usage.cacheCreationInputTokens === "number") {
    candidates.push(Math.max(0, usage.cachedInputTokens - usage.cacheCreationInputTokens));
  }
  for (const cacheRead of candidates) {
    if (![input, output, cacheRead, cacheWrite].every(finiteNonNegative)) return null;
    if (cacheRead + cacheWrite > input) continue;
    const cacheWrite1h = usage.cacheCreation1hInputTokens;
    return {
      input: Math.max(0, input - cacheRead - cacheWrite),
      output,
      cacheRead,
      cacheWrite,
      ...(typeof cacheWrite1h === "number" && finiteNonNegative(cacheWrite1h) && cacheWrite1h > 0
        ? { cacheWrite1h: Math.min(cacheWrite1h, cacheWrite) } : {}),
    };
  }
  return null;
}

/**
 * Price of a 1-hour cache write relative to the 5-minute rate that Cost4.cacheWrite records.
 * Anthropic bills 5m writes at 1.25x and 1h writes at 2x base input, so 2 / 1.25. Scaling the
 * 5m rate (rather than input) keeps every tier multiplier already applied to the Cost4 and keeps
 * a free-write row (cacheWrite 0) free.
 */
export const CACHE_WRITE_1H_OVER_5M = 2 / 1.25;

/** jawcode unit convention: USD per 1M tokens (jawcode stats/db.ts calculateCatalogCost). */
export function calculateCost(tokens: CostTokens, cost4: Cost4): CostBreakdown {
  const input = cost4.input * tokens.input / 1_000_000;
  const output = cost4.output * tokens.output / 1_000_000;
  const cacheRead = cost4.cacheRead * tokens.cacheRead / 1_000_000;
  const write1h = Math.min(tokens.cacheWrite1h ?? 0, tokens.cacheWrite);
  const cacheWrite = (cost4.cacheWrite * (tokens.cacheWrite - write1h)
    + cost4.cacheWrite * CACHE_WRITE_1H_OVER_5M * write1h) / 1_000_000;
  return { input, output, cacheRead, cacheWrite, total: input + output + cacheRead + cacheWrite };
}

/**
 * Fixed priority: user-configured provider overlay -> jawcode exact (provider
 * bundle) nonzero -> overlay verified -> overlay verified-derived -> jawcode
 * model-level vendor price (cross-provider fallback: a model follows its official
 * vendor price — WP5 policy, e.g. kiro/claude-opus-4-6 uses the anthropic price)
 * -> null. An explicit all-zero user override means free; all-zero catalog
 * rows remain overlay candidates rather than evidence of free pricing.
 */
export function resolveMatchedPrice(
  provider: string,
  modelId: string,
  overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
  userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
  options: PriceResolutionOptions = {},
): MatchedPrice | null {
  // Literal configured providers win over account identities. Only then use
  // config-owned Codex identities, followed by the existing historical suffix
  // grammar. Never infer an account by stripping an arbitrary suffix.
  const namespace = activeConfiguredProviders().has(provider)
    ? provider
    : activeAccountPricingProviders().get(provider) ?? baseProviderLabel(provider);
  if (namespace !== provider) {
    // An exact override (including caller-supplied rows) owns its namespace.
    // Unchanged names use the memoized inner lookup's existing user-first order.
    const exactUserOverlay = userOverlayMatch(provider, modelId, userOverlays);
    if (exactUserOverlay) return exactUserOverlay;
    provider = namespace;
  }
  // Memoize by (provider, model): usage summaries iterate hundreds of thousands of
  // rows that share a handful of provider/model keys, so resolving each time would
  // dominate /api/usage latency (WP6 audit). The compiled overlays are static;
  // user overlays get a NEW array identity + version bump on every config refresh,
  // so memoized rows never go stale.
  if (overlays === EXPECTED_PRICE_OVERLAYS && userOverlays === activeUserCostOverlays()) {
    const cacheKey = `${userCostOverlayVersion()} ${options.allowModelLevelFallback !== false} ${provider} ${modelId}`;
    if (!priceMemo.has(cacheKey)) {
      if (priceMemo.size >= 512) priceMemo.clear();
      priceMemo.set(cacheKey, resolveMatchedPriceInner(provider, modelId, overlays, userOverlays, options));
    }
    return priceMemo.get(cacheKey)!;
  }
  return resolveMatchedPriceInner(provider, modelId, overlays, userOverlays, options);
}

const priceMemo = new Map<string, MatchedPrice | null>();

/**
 * Resolution wrapper: exact provider/model lookup first, then the Antigravity
 * base-model fallback for collapsed wire ids. Never falls through to the
 * cross-provider vendor price at this level.
 */
function resolveMatchedPriceInner(
  provider: string,
  modelId: string,
  overlays: readonly ExpectedPriceOverlay[],
  userOverlays: readonly ExpectedPriceOverlay[],
  options: PriceResolutionOptions,
): MatchedPrice | null {
  const direct = resolveMatchedPriceExact(provider, modelId, overlays, userOverlays, options);
  if (direct) return direct;
  // Antigravity historical/wire ids often lack an exact overlay; fall back to the
  // picker/call base model so collapsed usage rows still get a price.
  if (provider === "google-antigravity" || provider.startsWith("google-antigravity")) {
    const base = canonicalAntigravityUsageModel(modelId);
    if (base !== modelId) return resolveMatchedPriceExact(provider, base, overlays, userOverlays, options);
  }
  return null;
}

/**
 * Exact provider/model price lookup: user-configured `modelCosts` first, then
 * an exact official correction, the jawcode provider bundle, the expected-price overlay, then the
 * model-level vendor fallback. All-zero catalog rows fall through; user zeros win.
 */
function resolveMatchedPriceExact(
  provider: string,
  modelId: string,
  overlays: readonly ExpectedPriceOverlay[],
  userOverlays: readonly ExpectedPriceOverlay[],
  options: PriceResolutionOptions,
): MatchedPrice | null {
  // User-configured provider overlay wins over every compiled catalog: the
  // operator's explicit price is authoritative for the ~$ estimate.
  const userOverlay = userOverlayMatch(provider, modelId, userOverlays);
  if (userOverlay) return userOverlay;
  if (!cursorFastPriceSupported(provider, modelId)) return null;
  const verifiedOverride = overlays === EXPECTED_PRICE_OVERLAYS
    ? findVerifiedPriceOverride(pricingFamilyProvider(provider), modelId)
    : undefined;
  if (verifiedOverride && verifiedOverride.status !== "unverified" && validCost4(verifiedOverride.cost4) && hasNonZeroCost(verifiedOverride.cost4)) {
    return {
      provider,
      modelId,
      cost4: multiplyCursorFastCost(verifiedOverride.cost4, provider, modelId),
      source: "expected",
      sourceRef: verifiedOverride.source,
      verifiedAt: verifiedOverride.verifiedAt,
      status: verifiedOverride.status,
      ...cursorFastPriceProvenance(provider, modelId),
    };
  }
  const metadataProvider = resolveMetadataProvider(provider);
  const bundled = metadataProvider
    ? getModelMetadata(metadataProvider, modelId)
    : undefined;
  if (bundled?.cost && validCost4(bundled.cost) && hasNonZeroCost(bundled.cost)) {
    return {
      provider,
      modelId,
      jawcodeProvider: metadataProvider,
      cost4: multiplyCursorFastCost(bundled.cost, provider, modelId),
      source: "jawcode",
      status: "verified",
      ...cursorFastPriceProvenance(provider, modelId),
    };
  }
  const overlay = findExpectedPriceOverlay(overlays === EXPECTED_PRICE_OVERLAYS ? pricingFamilyProvider(provider) : provider, modelId, overlays);
  if (!overlay || !validCost4(overlay.cost4) || !hasNonZeroCost(overlay.cost4)) {
    if (options.allowModelLevelFallback === false) return null;
    const fallback = resolveModelLevelPrice(provider, modelId);
    return fallback
      ? { ...fallback, cost4: multiplyCursorFastCost(fallback.cost4, provider, modelId), ...cursorFastPriceProvenance(provider, modelId) }
      : null;
  }
  if (overlay.status === "unverified") return null;
  return {
    provider,
    modelId,
    ...(metadataProvider ? { jawcodeProvider: metadataProvider } : {}),
    cost4: multiplyCursorFastCost(overlay.cost4, provider, modelId),
    source: "expected",
    sourceRef: overlay.source,
    verifiedAt: overlay.verifiedAt,
    status: overlay.status,
    ...cursorFastPriceProvenance(provider, modelId),
  };
}

function multiplyCursorFastCost(cost4: Cost4, provider: string, modelId: string): Cost4 {
  const multiplier = cursorFastPriceMultiplier(provider, modelId);
  if (multiplier === 1) return cost4;
  return {
    input: cost4.input * multiplier,
    output: cost4.output * multiplier,
    cacheRead: cost4.cacheRead * multiplier,
    cacheWrite: cost4.cacheWrite * multiplier,
  };
}

function cursorFastPriceProvenance(provider: string, modelId: string): Pick<MatchedPrice, "sourceRef" | "status"> | Record<never, never> {
  const sourceRef = cursorFastPriceSource(provider, modelId);
  return sourceRef ? { sourceRef, status: "verified" } : {};
}

/** User-configured overlay match; explicit zero rates are authoritative too. */
function userOverlayMatch(
  provider: string,
  modelId: string,
  userOverlays: readonly ExpectedPriceOverlay[],
): MatchedPrice | null {
  const overlay = findExpectedPriceOverlay(provider, modelId, userOverlays);
  if (!overlay || !validCost4(overlay.cost4)) return null;
  return {
    provider,
    modelId,
    cost4: overlay.cost4,
    source: "user",
    ...(overlay.promptLengthPricing ? { promptLengthPricing: overlay.promptLengthPricing } : {}),
    sourceRef: overlay.source,
    verifiedAt: overlay.verifiedAt,
    status: "verified",
  };
}

function resolveModelLevelPrice(provider: string, modelId: string): MatchedPrice | null {
  // Exact first; then dot->dash variant for providers that spell vendor ids with
  // dots where the catalog uses dashes (kiro "claude-opus-4.6" vs anthropic
  // "claude-opus-4-6"). No fuzzy matching beyond this one normalization.
  const found = findVendorCostByModelId(modelId)
    ?? (modelId.includes(".") ? findVendorCostByModelId(modelId.replaceAll(".", "-")) : undefined)
    ?? vendorPrefixedCost(modelId);
  if (!found) return null;
  return {
    provider,
    modelId,
    jawcodeProvider: found.provider,
    cost4: found.cost,
    source: "jawcode",
    status: "verified-derived",
  };
}

/**
 * Aggregators spell a model as `<vendor>/<model>` — CommandCode serves
 * `deepseek/deepseek-v4-flash`, and OpenRouter-shaped presets do the same. The cost
 * catalog stores the bare id, so the exact lookup above misses a price that is present and
 * every request through such a provider reports no cost at all (#3136).
 *
 * Retrying on the tail is only safe while the prefix AGREES with the vendor the matched row
 * belongs to. `findVendorCostByModelId` returns whichever vendor `COST_VENDOR_PRIORITY`
 * reaches first, so an unchecked strip would happily price `openai/claude-opus-4-6` from
 * Anthropic's row — a number that looks authoritative and is wrong. Requiring agreement
 * keeps the failure closed for a genuinely mismatched id.
 *
 * Comparison is normalized because the same vendor is spelled differently across catalogs:
 * `x-ai/grok-4.6` resolves to vendor `xai`. Dashes and case are the only variance seen;
 * anything beyond that stays a miss.
 */
function vendorPrefixedCost(modelId: string): ReturnType<typeof findVendorCostByModelId> {
  const slash = modelId.indexOf("/");
  if (slash <= 0 || slash === modelId.length - 1) return undefined;
  const claimedVendor = modelId.slice(0, slash);
  const tail = modelId.slice(slash + 1);
  // A tail that is itself slashed is not a vendor prefix we understand; leave it alone.
  if (tail.includes("/")) return undefined;
  const found = findVendorCostByModelId(tail)
    ?? (tail.includes(".") ? findVendorCostByModelId(tail.replaceAll(".", "-")) : undefined);
  if (!found) return undefined;
  const normalize = (value: string): string => value.toLowerCase().replaceAll("-", "");
  return normalize(found.provider) === normalize(claimedVendor) ? found : undefined;
}

/**
 * Only measured usage is priced. An `unreported` or `unsupported` row can still carry tokens — a
 * combo whose first leg failed without usage keeps the second leg's — and pricing them reports an
 * understated cost as if it were complete.
 */
export function isMeasuredStatus(usageStatus: UsageStatus): boolean {
  return usageStatus === "reported" || usageStatus === "estimated";
}

function isEstimated(usage: OcxUsage, usageStatus: UsageStatus, priceStatus: ExpectedPriceStatus | "verified"): boolean {
  return usage.estimated === true || usageStatus === "estimated" || priceStatus === "verified-derived";
}

/**
 * Resolve the effective service tier from persisted log fields.
 * Priority: responseServiceTier (server-confirmed) > requestedServiceTier
 * (client-sent, pre-rewrite) > configuredServiceTier (config.fastMode injection).
 */
export function effectiveServiceTier(entry: {
  responseServiceTier?: string;
  requestedServiceTier?: string;
  configuredServiceTier?: string;
}): string | undefined {
  return entry.responseServiceTier ?? entry.requestedServiceTier ?? entry.configuredServiceTier;
}

/**
 * Accepts either the collapsed tier scalar or the full provenance record.
 * A bare string carries no provenance, so it cannot confirm Fast: callers that
 * need long-context exclusivity to be correct must pass the record.
 */
export type ServiceTierInput = string | ServiceTierContext;

/**
 * Narrow a persisted log entry to just its tier provenance. Prefer this over
 * `effectiveServiceTier()` at estimator call sites: the collapsed scalar cannot
 * distinguish a response-confirmed Fast request from a merely requested one,
 * and long-context exclusivity depends on that distinction.
 */
export function serviceTierContext(entry: ServiceTierContext): ServiceTierContext {
  if (entry.tierOutcome) {
    return { ...serviceTierContextFromOutcome(entry.tierOutcome), tierOutcome: entry.tierOutcome };
  }
  return {
    responseServiceTier: entry.responseServiceTier,
    requestedServiceTier: entry.requestedServiceTier,
    configuredServiceTier: entry.configuredServiceTier,
  };
}

/** Convert one adapter-observed attempt outcome into the existing pricing provenance shape. */
export function serviceTierContextFromOutcome(outcome: AttemptTierOutcome): ServiceTierContext {
  const responseAuthoritative = outcome.responseTierAuthoritative !== false;
  if (responseAuthoritative && outcome.canonical === "priority" && outcome.confirmation === "confirmed") {
    return { responseServiceTier: "priority" };
  }
  // Non-authoritative echoes remain in the log, but cannot become pricing confirmation either.
  if (responseAuthoritative && outcome.responseServiceTier !== undefined) {
    return { responseServiceTier: outcome.responseServiceTier };
  }
  if (outcome.canonical === "priority"
    && (outcome.confirmation === "assumed" || (!responseAuthoritative && outcome.confirmation === "confirmed"))) {
    return { requestedServiceTier: "priority" };
  }
  // An unclassified route makes no canonical Fast claim, but its adapter can still prove that
  // it serialized a caller tier. Preserve that wire evidence instead of discarding the legacy
  // top-level pricing signal merely because B0 added an outcome row.
  if (
    outcome.fastOutcome === "unknown"
    && outcome.wireKind === "service-tier"
    && typeof outcome.wireValue === "string"
  ) {
    return { requestedServiceTier: outcome.wireValue };
  }
  return {};
}

function tierScalar(tier?: ServiceTierInput): string | undefined {
  return typeof tier === "string" ? tier : tier && effectiveServiceTier(tier);
}

/** True only when the UPSTREAM RESPONSE confirmed the Fast tier (see ServiceTierContext). */
function isConfirmedFast(tier?: ServiceTierInput): boolean {
  return typeof tier === "object" && canonicalFastTierMarker(tier.responseServiceTier) === "priority";
}

/**
 * Select user prompt-length rates, or apply the published context rule in automatic mode.
 * Returns [effectiveCost4, catalogTier, priorityLowerBound, customThresholdApplied].
 *
 * `rawInputTokens` MUST be `usage.inputTokens` (total prompt size), never the
 * normalized billable input — normalization subtracts cache read/write, so a
 * cache-heavy long prompt would fall below the boundary and under-bill.
 *
 * A provider's declaration decides how a response-confirmed priority tier relates to this band.
 * API rows can stack the bands. xAI publishes neither a combined rate nor an exclusion,
 * so its long-context rate remains the known lower bound instead of inventing a stacked multiplier.
 */
function applyPromptLengthPricing(
  cost4: Cost4,
  provider: string,
  modelId: string,
  rawInputTokens: number | undefined,
  tier?: ServiceTierInput,
  policy?: PromptLengthPricing,
): [Cost4, ContextTierName | undefined, boolean, true?] {
  // A user policy replaces the catalog rule on BOTH sides of its threshold.
  // Keep custom provenance separate while honoring the published Priority relation.
  if (policy?.mode === "flat") return [cost4, undefined, false];
  if (policy?.mode === "custom") {
    const crossed = rawInputTokens !== undefined && Number.isFinite(rawInputTokens)
      && (policy.comparison === "gte"
        ? rawInputTokens >= policy.thresholdTokens : rawInputTokens > policy.thresholdTokens);
    if (!crossed) return [cost4, undefined, false];
    const relation = findContextTier(provider, modelId)?.confirmedPriorityRelation;
    const confirmedFast = isConfirmedFast(tier);
    if (confirmedFast && relation === "exclusive") return [cost4, undefined, false];
    return [policy.rates, undefined, confirmedFast && relation === "lower-bound", true];
  }
  if (rawInputTokens === undefined) return [cost4, undefined, false];
  const rule = findContextTier(provider, modelId);
  if (!rule || !isLongContext(rule, rawInputTokens)) return [cost4, undefined, false];
  const confirmedFast = isConfirmedFast(tier);
  if (confirmedFast && rule.confirmedPriorityRelation === "exclusive") {
    return [cost4, undefined, false];
  }
  return [{
    input: cost4.input * rule.multiplier.input,
    output: cost4.output * rule.multiplier.output,
    cacheRead: cost4.cacheRead * rule.multiplier.cacheRead,
    cacheWrite: cost4.cacheWrite * rule.multiplier.cacheWrite,
  }, "long", confirmedFast && rule.confirmedPriorityRelation === "lower-bound"];
}

/**
 * Apply a declared provider/model priority-tier multiplier to a Cost4 when applicable.
 * Returns [effectiveCost4, multiplier]. Multiplier is 1 (no-op) when:
 * - serviceTier is not "priority"
 * - no exact provider/model rule exists
 */
function applyPriorityMultiplier(
  cost4: Cost4,
  provider: string,
  modelId: string,
  serviceTier?: ServiceTierInput,
  contextTier?: ContextTierName,
  customThresholdApplied?: true,
): [Cost4, number] {
  if (canonicalFastTierMarker(tierScalar(serviceTier)) !== "priority") return [cost4, 1];
  if (contextTier && findContextTier(provider, modelId)?.confirmedPriorityRelation !== "stack") return [cost4, 1];
  if (customThresholdApplied && isConfirmedFast(serviceTier)
    && findContextTier(provider, modelId)?.confirmedPriorityRelation === "lower-bound") return [cost4, 1];
  const rule = findPriorityPricingRule(provider, modelId);
  if (rule?.requiresResponseConfirmation && !isConfirmedFast(serviceTier)) return [cost4, 1];
  const multiplier = rule?.multiplier ?? 1;
  if (multiplier === 1) return [cost4, 1];
  return [{
    input: cost4.input * multiplier,
    output: cost4.output * multiplier,
    cacheRead: cost4.cacheRead * multiplier,
    cacheWrite: cost4.cacheWrite * multiplier,
  }, multiplier];
}

/**
 * OpenRouter confirms the actual endpoint tier and documents priority as higher cost, but this
 * branch does not bundle its provider-specific priority endpoint prices. A confirmed canonical
 * priority result can therefore use the standard price only as a provable lower bound. Do not
 * extend this to flex (cheaper) or to other providers without the same pricing contract.
 *
 * An ASSUMED priority attempt needs the same marker for a different reason. There the provider
 * never echoed a tier at all, so the standard price is not merely a lower bound on a known
 * premium — it is a floor under an outcome we did not observe. Returning it unmarked reports a
 * definite standard cost for a request that may well have been billed as priority, which is the
 * one thing a cost estimate must never do.
 */
function isOpenRouterPriorityLowerBound(
  provider: string,
  outcome: AttemptTierOutcome | undefined,
): boolean {
  return provider === "openrouter"
    && outcome?.canonical === "priority"
    && outcome.fastOutcome === "applied"
    && (outcome.confirmation === "confirmed" || outcome.confirmation === "assumed");
}

/**
 * Per-attempt cost estimate: tokens normalized, price resolved (user overlay →
 * catalogs), priority/long-context tiers applied. Null when usage or price is
 * missing so combos can fail closed.
 */
/**
 * Credit price for a logged provider label, with the same precedence as token prices: an exact
 * configured provider name first, then a config-owned account identity, then the base label of an
 * account-suffixed row (`kiro-<account>`).
 */
function creditPriceFor(provider: string, creditPrices: ReadonlyMap<string, number>): number | undefined {
  if (creditPrices.size === 0) return undefined;
  if (activeConfiguredProviders().has(provider)) return creditPrices.get(provider);
  // Keep a configured alias's own namespace before baseProviderLabel canonicalizes it.
  const cut = provider.lastIndexOf("-");
  const ownNamespace = provider.slice(0, cut);
  const suffix = provider.slice(cut + 1);
  if (cut > 0 && (suffix === "main" || CODEX_ACCOUNT_LOG_LABEL_RE.test(suffix))
    && activeConfiguredProviders().has(ownNamespace)
    && baseProviderLabel(provider) !== provider) return creditPrices.get(ownNamespace);
  const namespace = activeAccountPricingProviders().get(provider) ?? baseProviderLabel(provider);
  return creditPrices.get(provider) ?? creditPrices.get(namespace);
}

/**
 * Billed cost from provider credits, when the provider has a configured credit price.
 *
 * Three outcomes, because "not credit-priced" and "credit-priced but unrepresentable" are not the
 * same answer:
 * - `absent`: this row is not credit-priced, so the caller keeps its token estimate;
 * - `billed`: the charge, with the credits and price that produced it;
 * - `unrepresentable`: the row IS credit-priced but the numbers cannot be multiplied and
 *   serialized honestly. The caller must fail closed rather than fall back to a token estimate,
 *   which would report a different, invented amount for a row the operator asked to bill from
 *   credits.
 */
type CreditCostResult =
  | { kind: "absent" }
  | { kind: "billed"; cost: CostBreakdown; billing: CreditBilling }
  | { kind: "unrepresentable" };

function creditCost(provider: string, usage: OcxUsage, creditPrices: ReadonlyMap<string, number>): CreditCostResult {
  const price = creditPriceFor(provider, creditPrices);
  if (price === undefined) return { kind: "absent" };
  const credits = usage.providerCredits;
  if (typeof credits !== "number") {
    // No output is not proof of a free request: locally synthesized and legacy usage can
    // lack a credit observation even after a charge. Keep the legacy token fallback for
    // rows with output, but do not invent an observed zero when output is absent.
    if (usage.outputTokens === 0) return { kind: "unrepresentable" };
    return { kind: "absent" };
  }
  // A reading that exists but is corrupt (NaN, Infinity, negative) is not a missing reading: it is
  // evidence this row was supposed to be billed in credits and cannot be priced honestly. Falling
  // back to tokens here would report a different amount for the reason the operator configured.
  if (!isRepresentableCreditCount(credits)) return { kind: "unrepresentable" };
  // Both inputs are bounded independently AND the product is re-checked: a finite price and a
  // finite credit count can still multiply to Infinity, which JSON serializes as null.
  if (!isValidCreditPriceBound(price)) return { kind: "unrepresentable" };
  const total = credits * price;
  if (!Number.isFinite(total)) return { kind: "unrepresentable" };
  return {
    kind: "billed",
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total },
    billing: { source: "provider-credits", providerCredits: credits, creditPriceUsd: price },
  };
}

type CostInput = Pick<AttemptCostInput, "provider" | "model" | "usage" | "usageStatus" | "allowModelLevelFallback">;

function hasMeasuredUsage<T extends CostInput>(input: T): input is T & { usage: OcxUsage } {
  return isMeasuredStatus(input.usageStatus) && !!input.usage;
}

/**
 * True when this row WOULD have a credit price but its credits or price cannot produce a
 * representable charge. Exported so the management DTO can name that failure instead of reporting
 * the generic unmatched-price reason, which would imply a token estimate exists.
 */
export function creditChargeUnrepresentable(input: CostInput): boolean {
  return hasMeasuredUsage(input)
    && creditCost(input.provider, input.usage, activeCreditPrices()).kind === "unrepresentable"
    && !!resolveMatchedPrice(input.provider, input.model, undefined, undefined, input);
}

/**
 * One attempt's cost and the basis it used. Null means fail closed: either the credit charge is
 * unrepresentable, or the caller already decided the row is unpriced.
 */
function resolveAttemptCost(
  provider: string,
  usage: OcxUsage,
  creditPrices: ReadonlyMap<string, number>,
  tokens: CostTokens | null,
  cost4: Cost4,
): { cost: CostBreakdown; billing?: CreditBilling } | null {
  // The token bound is applied only on the token path. A credit charge is `credits x price`, so a
  // row whose token count is merely too large to price from tokens still has an honest credit
  // charge; refusing it would discard a number that never depended on those tokens.
  const credit = creditCost(provider, usage, creditPrices);
  if (credit.kind === "unrepresentable") return null;
  if (credit.kind === "billed") return { cost: credit.cost, billing: credit.billing };
  // A token estimate is `rate x tokens / 1e6`, and the rate bound alone leaves a corrupt token
  // count free to produce `Infinity`, which JSON serializes as `null`. Fail closed instead of
  // returning an invented number.
  if (!tokens || !costTokensWithinBound(tokens)) return null;
  return { cost: calculateCost(tokens, cost4) };
}

export function estimateAttemptCost(
  attempt: AttemptCostInput,
  overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
  serviceTier?: ServiceTierInput,
  userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
  creditPrices: ReadonlyMap<string, number> = activeCreditPrices(),
): AttemptCostEstimate | null {
  if (!hasMeasuredUsage(attempt)) return null;
  const tokens = normalizeCostTokens(attempt.usage);
  const price = resolveMatchedPrice(attempt.provider, attempt.model, overlays, userOverlays, attempt);
  if (!price) return null;
  const attemptServiceTier = attempt.tierOutcome
    ? serviceTierContextFromOutcome(attempt.tierOutcome)
    : serviceTier;
  const [tieredCost4, contextTier, contextPriorityLowerBound, customThresholdApplied] = applyPromptLengthPricing(
    price.cost4, price.provider, attempt.model, attempt.usage.inputTokens, attemptServiceTier, price.promptLengthPricing,
  );
  const [effectiveCost4, multiplier] = applyPriorityMultiplier(
    tieredCost4, price.provider, attempt.model, attemptServiceTier, contextTier, customThresholdApplied,
  );
  const billed = resolveAttemptCost(attempt.provider, attempt.usage, creditPrices, tokens, effectiveCost4);
  if (!billed) return null;
  // A credit charge is `providerCredits x creditPriceUsd`. The token rates were still resolved to
  // decide whether this row falls back to them, but they did not produce the amount, so the
  // `priorityLowerBound` they imply is a statement about a price nobody was charged. A lower bound
  // is only honest for the rate that actually priced the row.
  const priorityLowerBound = billed.billing === undefined
    && (contextPriorityLowerBound || isOpenRouterPriorityLowerBound(price.provider, attempt.tierOutcome));
  return {
    ordinal: attempt.ordinal,
    provider: attempt.provider,
    model: attempt.model,
    tokens,
    price,
    cost: billed.cost,
    estimated: isEstimated(attempt.usage, attempt.usageStatus, billed.billing ? "verified" : price.status),
    ...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
    ...(contextTier ? { contextTier } : {}),
    ...(customThresholdApplied ? { customThresholdApplied } : {}),
    ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
    ...(billed.billing ? { billing: billed.billing } : {}),
  };
}

/**
 * Aggregate billing basis for a combo.
 *
 * `provider-credits` is claimed only when EVERY attempt was credit-billed at the same price, so
 * summing their credits is a real total and the credit count is meaningful. One attempt at another
 * price, or one token-priced attempt, makes the aggregate honest only as a sum: the components are
 * visible per attempt, and the parent says `mixed` instead of presenting either split as the whole.
 */
function comboBilling(estimates: readonly AttemptCostEstimate[], total: number): CreditBilling | undefined {
  const creditAttempts = estimates.filter(est => est.billing?.source === "provider-credits");
  if (creditAttempts.length === 0) return undefined;
  const creditBilling = (est: AttemptCostEstimate) => est.billing as Extract<CreditBilling, { source: "provider-credits" }>;
  // `mixed` is a claim about HOW the attempts were billed, so it is only ever set for an actual
  // difference in basis. A same-price combo whose summed credit count happens to be large is not
  // mixed — the per-attempt charges were each bounded before they were computed, and the summed
  // total is re-checked here, so summing their credits is a real number too.
  if (creditAttempts.length !== estimates.length) return { source: "mixed" };
  const price = creditBilling(creditAttempts[0]!).creditPriceUsd;
  if (!creditAttempts.every(est => creditBilling(est).creditPriceUsd === price)) return { source: "mixed" };
  const providerCredits = creditAttempts.reduce((sum, est) => sum + creditBilling(est).providerCredits, 0);
  if (!Number.isFinite(providerCredits) || !Number.isFinite(providerCredits * price)) {
    // Unreachable while each attempt is bounded (and an overflowing sum would have failed the
    // combo total above), but the honest answer is still "no single split": claiming a credit
    // count would be an amount, and dropping the marker would let the four zero components be
    // read as a token allocation.
    return { source: "mixed" };
  }
  // The displayed split has to agree with the total it sits beside. Summed floats can differ in
  // the last bits; anything larger means the aggregate is not `sum(credits) x price`.
  if (Math.abs(providerCredits * price - total) > Math.max(1e-9, Math.abs(total) * 1e-9)) return { source: "mixed" };
  return { source: "provider-credits", providerCredits, creditPriceUsd: price };
}

/**
 * A token-only Combo requires every attempt to be a floor. Credit charges are exact at the
 * configured price. With credit billing, at least one token-priced attempt must be a floor,
 * and every other token-priced attempt must be a known floor or use non-estimated pricing
 * and usage with observed cache detail.
 */
function comboIsLowerBound(
  attempts: readonly AttemptCostInput[],
  estimates: readonly AttemptCostEstimate[],
  billing: CreditBilling | undefined,
): boolean {
  if (!billing) return estimates.length > 0 && estimates.every(est => est.priorityLowerBound === true);
  return estimates.some(est => est.billing === undefined && est.priorityLowerBound === true)
    && estimates.every((est, index) => {
      if (est.billing || est.priorityLowerBound) return true;
      const { usage, cacheProvenance } = attempts[index]!;
      return !est.estimated && cacheObservationFromUsage(usage, cacheProvenance).provenance === "observed";
    });
}

/**
 * Combo: price every attempt with its own rate and sum. Fail closed — if ANY
 * attempt is unpriced, return null rather than a partial sum.
 */
export function estimateComboCost(
  attempts: readonly AttemptCostInput[],
  overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
  serviceTier?: ServiceTierInput,
  userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
): CostEstimate | null {
  if (attempts.length === 0) return null;
  const estimates: AttemptCostEstimate[] = [];
  for (const attempt of attempts) {
    const estimate = estimateAttemptCost(attempt, overlays, serviceTier, userOverlays);
    if (!estimate) return null;
    estimates.push(estimate);
  }
  let tokens: CostTokens | null = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
  const cost: CostBreakdown = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
  for (const est of estimates) {
    if (!est.tokens) tokens = null;
    if (tokens && est.tokens) {
      tokens.input += est.tokens.input;
      tokens.output += est.tokens.output;
      tokens.cacheRead += est.tokens.cacheRead;
      tokens.cacheWrite += est.tokens.cacheWrite;
      if (est.tokens.cacheWrite1h) tokens.cacheWrite1h = (tokens.cacheWrite1h ?? 0) + est.tokens.cacheWrite1h;
    }
    cost.input += est.cost.input;
    cost.output += est.cost.output;
    cost.cacheRead += est.cost.cacheRead;
    cost.cacheWrite += est.cost.cacheWrite;
    cost.total += est.cost.total;
  }
  // A sum of individually representable charges can still leave the representable range. Fail
  // closed rather than serve a total that serializes as null.
  if (!Number.isFinite(cost.total) || (tokens && Object.values(tokens).some(value => !Number.isFinite(value)))) return null;
  const billing = comboBilling(estimates, cost.total);
  return {
    tokens,
    cost,
    estimated: estimates.some(est => est.estimated),
    attempts: estimates,
    ...(billing ? { billing } : {}),
    ...(estimates.some(est => est.priorityMultiplier && est.priorityMultiplier !== 1)
      ? { priorityMultiplier: estimates.find(est => est.priorityMultiplier)?.priorityMultiplier }
      : {}),
    ...(estimates.some(est => est.contextTier) ? { contextTier: "long" as const } : {}),
    ...(estimates.some(est => est.customThresholdApplied) ? { customThresholdApplied: true as const } : {}),
    ...(comboIsLowerBound(attempts, estimates, billing) ? { priorityLowerBound: true as const } : {}),
  };
}

/** Single-target request cost estimate (non-combo). */
export function estimateRequestCost(
  input: {
    provider: string;
    model: string;
    usage?: OcxUsage;
    usageStatus: UsageStatus;
    serviceTier?: ServiceTierInput;
    allowModelLevelFallback?: boolean;
  },
  overlays: readonly ExpectedPriceOverlay[] = EXPECTED_PRICE_OVERLAYS,
  userOverlays: readonly ExpectedPriceOverlay[] = activeUserCostOverlays(),
  creditPrices: ReadonlyMap<string, number> = activeCreditPrices(),
): CostEstimate | null {
  if (!hasMeasuredUsage(input)) return null;
  const tokens = normalizeCostTokens(input.usage);
  const price = resolveMatchedPrice(input.provider, input.model, overlays, userOverlays, input);
  if (!price) return null;
  const [tieredCost4, contextTier, contextPriorityLowerBound, customThresholdApplied] = applyPromptLengthPricing(
    price.cost4, price.provider, input.model, input.usage.inputTokens, input.serviceTier, price.promptLengthPricing,
  );
  const [effectiveCost4, multiplier] = applyPriorityMultiplier(
    tieredCost4, price.provider, input.model, input.serviceTier, contextTier, customThresholdApplied,
  );
  const billed = resolveAttemptCost(input.provider, input.usage, creditPrices, tokens, effectiveCost4);
  if (!billed) return null;
  // See `estimateAttemptCost`: a credit charge is exact for its configured price, so it must not
  // inherit the token-rate floor that the fallback path resolved on the way in.
  const priorityLowerBound = billed.billing === undefined && (contextPriorityLowerBound || isOpenRouterPriorityLowerBound(
    price.provider,
    typeof input.serviceTier === "object" ? input.serviceTier.tierOutcome : undefined,
  ));
  return {
    tokens,
    price,
    cost: billed.cost,
    estimated: isEstimated(input.usage, input.usageStatus, billed.billing ? "verified" : price.status),
    ...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
    ...(contextTier ? { contextTier } : {}),
    ...(customThresholdApplied ? { customThresholdApplied } : {}),
    ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
    ...(billed.billing ? { billing: billed.billing } : {}),
  };
}

/**
 * End-to-end output rate: outputTokens / wall-clock seconds (jawcode/OpenRouter
 * convention — TTFT is NOT subtracted; it is a separate metric, WP4).
 */
export function tokensPerSecond(outputTokens: number, durationMs: number): number | null {
  if (!finiteNonNegative(outputTokens) || !finiteNonNegative(durationMs)) return null;
  if (outputTokens <= 0 || durationMs <= 0) return null;
  return outputTokens / (durationMs / 1_000);
}
