/**
 * Is the daily spend cap's own input still arriving? (#970)
 *
 * The cap compares `store.spendSince(project, startOfToday())` — a sum of the
 * per-run `spendUsd` column — against its ceiling. When the harness stops
 * reporting cost, that column reads 0.00 and the cap silently measures a
 * fraction of reality. #46 named this once already: **$0.00 spend is not proof
 * of no spend.**
 *
 * Measured on this fleet, counting only runs that actually did work:
 *
 * | day        | worked | reported $0.00 |
 * |------------|--------|----------------|
 * | 2026-08-15 |     53 |  3.8%          |
 * | …          |        |  0–2.5%        |
 * | 2026-08-20 |     15 |  0.0%          |
 * | 2026-08-21 |     22 | 31.8%          |
 * | 2026-08-22 |     12 | 75.0%          |
 *
 * Six days of ≤3.8% baseline, then 32%, then 75% — with #614 running 213 turns
 * for $0.00.
 *
 * Two properties are load-bearing, and both were wrong in the predicate this
 * replaces:
 *
 * - **Only runs that did work are judged.** A run killed before its first turn
 *   records $0.00 honestly; 26 of this project's 48 zero-spend rows are exactly
 *   that. Counting them inflates the ratio *and* lets a run of administrative
 *   kills fire a telemetry finding that says nothing about telemetry.
 * - **A ratio, not `every`.** The old check fired only when every sampled run
 *   reported zero. Replayed over all 410 windows in this fleet's history it
 *   would have fired 14 times while staying silent through 37 windows that had
 *   lost a majority of their telemetry — so the common case, partial loss, was
 *   the invisible one. On 2026-08-21, at 31.8% loss, every window that day
 *   contained one metered run and the probe was silent all day.
 *
 * One judgement, two consumers: `doctor`'s finding and the `status` row. The
 * cap's figure and the statement about whether that figure means anything must
 * never come from two implementations that can disagree.
 */

/** One sampled run, reduced to what the judgement needs. */
export interface SpendSample {
  /** Turns taken. Zero means the run never worked, so its $0.00 is honest. */
  turns: number;
  spendUsd: number;
}

/**
 * The share of *working* runs whose spend is missing at or above which this is
 * reported.
 *
 * A majority, deliberately — the observed healthy baseline is 0–3.8%, not zero.
 * A legitimately free or aborted-after-one-turn run happens, and a check that
 * fires on one of them is a check that gets ignored, which is the failure the
 * install-surface rows already name: a warning repeated every fifteen minutes
 * trains an operator to ignore the row that matters.
 */
export const SPEND_MISSING_SHARE = 0.5;

export type SpendTelemetryVerdict =
  /** Enough working runs, and most of them metered. */
  | { kind: "healthy"; worked: number; missing: number; totalUsd: number }
  /** Not enough working runs to say anything — never a pass by default. */
  | { kind: "insufficient"; worked: number; needed: number }
  /** A majority of working runs reported nothing. */
  | { kind: "partial"; worked: number; missing: number }
  /** Every working run reported nothing — the same fact, stated louder. */
  | { kind: "absent"; worked: number }
  /**
   * Every working run reported nothing **and this fleet does not bill in
   * dollars** (#984). Not a fault: a subscription request has no per-request
   * price, so the harness reports none and `spendUsd` is permanently 0.00 —
   * accurate rather than missing. The constraint that actually binds is the
   * provider's allowance window, named here.
   */
  | { kind: "subscription"; worked: number; window: string; evidence: "declared" | "observed" };

/**
 * What is known about how this project's runs are billed (#984).
 *
 * Two independent grounds, because on a real fleet the declaration is often
 * absent while the evidence is unambiguous:
 *
 * - `declaredSubscription` — the project requires its providers to bill to a
 *   subscription credential (`requireOauthProviders`, #852). A statement of
 *   intent, so it is believed on its own.
 * - `allowanceWindow` — the provider itself reports an allowance window
 *   (`omp usage --json`), which is what a subscription has instead of a price.
 *   Positive evidence only: a fleet whose provider reports no window has
 *   nothing here, and its zeros stay a fault.
 */
export interface SpendBilling {
  declaredSubscription?: boolean;
  allowanceWindow?: string;
}

/**
 * Judge a newest-first sample.
 *
 * `limit` is how many *working* runs are wanted, not how many rows to read: the
 * caller over-samples and this takes the first `limit` runs that did work, so a
 * burst of 0-turn kills cannot push the real evidence out of the window.
 */
export function judgeSpendTelemetry(
  samples: readonly SpendSample[],
  limit: number,
  billing: SpendBilling = {},
): SpendTelemetryVerdict {
  const working = samples.filter((row) => row.turns > 0).slice(0, limit);
  if (working.length < limit) {
    return { kind: "insufficient", worked: working.length, needed: limit };
  }
  const missing = working.filter((row) => row.spendUsd === 0).length;
  if (missing === working.length) {
    // Total absence is the only verdict a billing class can reclassify, and
    // that asymmetry is the whole safety property: a metered neighbour proves
    // dollars ARE being reported, so a zero beside one is real telemetry loss
    // no matter how the fleet is billed. `partial` therefore always warns.
    const window = subscriptionWindow(billing);
    if (window !== undefined) {
      return {
        kind: "subscription",
        worked: working.length,
        window: window.window,
        evidence: window.evidence,
      };
    }
    return { kind: "absent", worked: working.length };
  }
  if (missing / working.length >= SPEND_MISSING_SHARE) {
    return { kind: "partial", worked: working.length, missing };
  }
  return {
    kind: "healthy",
    worked: working.length,
    missing,
    totalUsd: working.reduce((sum, row) => sum + row.spendUsd, 0),
  };
}

/** The operator-facing sentence, or undefined when there is nothing to say.
 *  Shared so `doctor` and `status` cannot word the same fact differently. */
/**
 * The allowance window to name, or `undefined` when nothing establishes that
 * this fleet is subscription-billed.
 *
 * A declaration with no readable window still counts — the operator has said
 * how the fleet bills, and a provider that cannot be read is not evidence
 * against it — but it says so rather than inventing a window name.
 */
function subscriptionWindow(
  billing: SpendBilling,
): { window: string; evidence: "declared" | "observed" } | undefined {
  if (billing.allowanceWindow !== undefined && billing.allowanceWindow.trim() !== "") {
    return {
      window: billing.allowanceWindow.trim(),
      evidence: billing.declaredSubscription === true ? "declared" : "observed",
    };
  }
  if (billing.declaredSubscription === true) {
    return { window: "unreadable (omp usage --json reported no window)", evidence: "declared" };
  }
  return undefined;
}

export function spendTelemetryDetail(verdict: SpendTelemetryVerdict): string | undefined {
  switch (verdict.kind) {
    case "subscription":
      return (
        `the last ${verdict.worked} working runs recorded $0.00, which is correct: this fleet bills to a ` +
        `subscription (${verdict.evidence}), so requests carry no per-request price and no USD cap can fire` +
        ` — the constraint that binds is the ${verdict.window} allowance`
      );
    case "absent":
      return (
        `the last ${verdict.worked} completed runs that did any work all recorded $0.00 spend` +
        " — the USD cap cannot fire on zeros, and $0.00 is not proof of no spend"
      );
    case "partial":
      return (
        `${verdict.missing} of the last ${verdict.worked} completed runs that did any work recorded ` +
        "$0.00 spend — the USD cap is comparing a fraction of actual spend against its ceiling"
      );
    case "healthy":
    case "insufficient":
      return undefined;
  }
}