// Types for build-phases.js — written rather than `@ts-expect-error`'d, on the same criterion as
// handover-message.d.ts: this is OUR module and its output is customer-facing. phaseTrail's string
// goes verbatim into the error a site owner reads when their build dies, and it is computed from a
// `timing` object that crosses three processes (entrypoint.sh → server.mjs → the hosted Worker).
// Under `@ts-expect-error` that argument would be `any`, and a shape drift between the runner's
// report and this reader would typecheck cleanly all the way to a customer.

export interface BuildTiming {
  totalMs?: number;
  renderMs?: number;
  deployMs?: number;
  msPerPage?: number;
  /** Per-step durations in ms, keyed by PHASE_ORDER names. Absent on pre-2026-08-05 runner images. */
  phases?: Record<string, number>;
}

/** The order entrypoint.sh marks its phases in; pinned against it by tests/build-phases.test.js. */
export const PHASE_ORDER: readonly string[];

/** One line ending in `\n`, or `''` when there is nothing measured to report. */
export function phaseTrail(timing: BuildTiming | undefined): string;

export interface RenderSplit {
  /** clone + detect + mkpages — the cost no amount of narrowing the render can touch. */
  fixedMs: number;
  astroMs: number;
  /** fixedMs ÷ (fixedMs + astroMs), 2 dp. */
  fixedShare: number;
}

/**
 * `null` unless BOTH halves were measured — a ratio from half a measurement is the defect this
 * module exists to stop. Per-page cost is deliberately NOT here: server.mjs reports one
 * `msPerPage`, from this same astro phase.
 */
export function renderSplit(timing: BuildTiming | undefined): RenderSplit | null;

export interface BuildMemory {
  /** Peak container memory during ONE build — sampled, not the cgroup's since-boot counter. */
  peakBytes?: number;
  /** 'cgroup' (exact) or 'proc-rss-sum' (an upper bound: shared pages counted more than once). */
  source?: string;
  note?: string;
  limitBytes?: number;
  peakPercent?: number;
  /** Present INSTEAD of a reading when nothing could be measured — never a zero. */
  unavailable?: string;
}

/** One line ending in `\n`, or `''` when nothing was measured — absent must not read as small. */
export function memoryLine(memory: BuildMemory | undefined): string;