export function startTrace(requestId: string, now: Clock): Recorder {
  const spans: Span[] = [];
  const t0 = now();

  return {
    async span(type, name, fn, attrs) {
      const start = now();
      try {
        const result = await fn();
        const extra = attrs?.(result) ?? {};
        // Cost rides on the span, not on a separate meter.
        // If it is not here, no dashboard can ever attribute
        // spend to a step.
        const { costUsd, ...rest } = extra;
        spans.push({ type, name, ms: now() - start,
                    costUsd: costUsd ?? 0, attrs: rest });
        return result;
      } catch (err) {
        // The failing run is the one you most need to
        // replay. Record it, then rethrow.
        spans.push({ type, name, ms: now() - start, costUsd: 0,
                    attrs: { failed: true, error: String(err) } });
        throw err;
      }
    },

    end(outcome) {
      return { requestId, outcome, ms: now() - t0,
        // Summed, never reported separately. One source of truth.
        costUsd: spans.reduce((s, x) => s + x.costUsd, 0), spans };
    },
  };
}

export function replayGaps(trace: Trace): string[] {
  const gaps: string[] = [];

  for (const s of trace.spans) {
    if (s.type === "model" && s.attrs.promptVersion === undefined)
      gaps.push(`${s.name}: no promptVersion, so you cannot tell
                 which prompt produced this`);

    if (s.type === "model" && s.costUsd === 0)
      gaps.push(`${s.name}: costing 0, spend cannot be attributed`);

    if (s.type === "tool" && s.attrs.ok === undefined)
      gaps.push(`${s.name}: no ok flag, a silent tool failure
                 is invisible`);

    if (s.type === "retrieve" && s.attrs.chunkIds === undefined)
      gaps.push(`${s.name}: no chunkIds, you cannot re-read what
                 the model was given`);
  }
  return gaps;
}

// And the test that makes it mean something:
it("names every field a debugger would have to ask you for", () => {
  const gaps = replayGaps(untracedRun);
  expect(gaps).toHaveLength(3);
  expect(gaps.join(" ")).toContain("charge_card");
});

it("the mean of two shard p95s is not the p95 of the traffic", () => {
  const quiet = Array.from({ length: 100 }, () => 100);
  const busy  = [...Array.from({ length: 90 }, () => 200),
                 ...Array.from({ length: 10 }, () => 9_000)];

  // What the roll-up dashboard does
  const shardAverage =
    (percentile(quiet, 95) + percentile(busy, 95)) / 2;

  // What the traffic actually did
  const truth = percentile([...quiet, ...busy], 95);

  expect(shardAverage).toBe(4550);
  expect(truth).toBe(200);
  // Off by 22x, and it pages someone for a breach
  // that never happened.
});

it("refuses to fire on a thin window", () => {
  const thin = [trace(400), trace(30_000)];
  // p95 of 30s, on two requests, meaning nothing.
  // Alerts that fire on noise get muted, and a muted
  // alert is worse than no alert.
  const w = summarise(thin, { passed: 0, scored: 1 });
  expect(evaluateAlerts(w, rules)).toEqual([]);
});

// The id is derived, never typed by a human.
export function fingerprint(template: string): string {
  return createHash("sha256").update(template)
    .digest("hex").slice(0, 6);
}

export function definePrompt(name, template): Prompt {
  return { name, template, id: `${name}@${fingerprint(template)}` };
}

// The failure a hand-bumped "v13" gives you:
// edited text, unchanged label, and every trace from
// that day claiming a version that never ran.
it("cannot be edited without the id moving", () => {
  const shipped = definePrompt("answer",
    "Answer from the policy only.");
  const edited  = definePrompt("answer",
    "Answer from the policy only. Cite it.");
  expect(shipped.id).not.toBe(edited.id);
});

export function shouldPromote(candidate, incumbent, tolerance) {
  const reasons: string[] = [];

  if (candidate.passRate < incumbent.passRate + tolerance.minQualityGain)
    reasons.push("quality: inside the noise");

  if (candidate.costPerRequestUsd >
      incumbent.costPerRequestUsd * tolerance.maxCostIncrease)
    reasons.push("cost: the longer prompt costs more on every
                  request, forever");

  if (candidate.latencyP95 > incumbent.latencyP95 * tolerance.maxLatencyIncrease)
    reasons.push("latency: p95 got worse, and users feel the tail");

  return { promote: reasons.length === 0, reasons };
}

// 88% → 95% quality, and it still does not ship:
// { promote: false,
//   reasons: [ "cost: the longer prompt costs more on
//               every request, forever" ] }

export function routeForReview(trace, confidence, policy): Decision {
  const irreversible = trace.spans.find((s) =>
    s.type === "tool" && policy.irreversibleTools.includes(s.name));

  // Stakes beat confidence. Confidence is not authority.
  if (irreversible)
    return { route: "review", reason: `irreversible: ${irreversible.name}` };

  if (confidence < policy.minConfidence)
    return { route: "review", reason: `low confidence` };

  return { route: "auto", reason: "reversible and confident" };
}

// The line comes from capacity, not from a feeling.
export function calibrateThreshold(sample, reviewCapacity) {
  const sorted = [...sample].sort((a, b) => a - b);
  const budget = Math.floor(sample.length * reviewCapacity);
  return sorted[budget];
}

// And the loop that pays for the reviewers:
correctionToCase(trace, input, corrected)
  // → { name: "correction-req_8f2a", source: "human-correction",
  //     traceId: "req_8f2a" }  ← the run is still there to replay