#!/usr/bin/env node
/**
 * funnel-velocity.mjs — Funnel calibration vs market benchmarks + stage velocity
 *
 * Three payloads, decreasing availability:
 *   1. calibration — own funnel rates (canonical ever* definition imported from
 *      stats.mjs) vs candidate-side market benchmark ranges. Works day one;
 *      folds status-log history when the ledger is present so a row rejected
 *      after an interview still counts as having reached Interview (#3493).
 *   2. waiting — in-flight Applied rows and elapsed days vs the typical
 *      first-response window. Per-row factual reporting, not an aggregate claim.
 *   3. velocity — median/p75 days per stage hop, folded from the append-only
 *      transition ledger data/status-log.tsv. Accrues value as the log grows.
 *
 * Transition ledger (written by set-status.mjs, never edited in place):
 *   {tracker#}\t{YYYY-MM-DD}\t{from}\t{to}\t{source}\t{note}
 *   - from may be "-" (unknown prior state)
 *   - to "-" retracts the row's latest observation
 *   - source "correction" replaces an earlier same-(num,to) observation
 *   - log path = sibling of the active tracker file (sandbox-safe for tests)
 *
 * Statistical honesty rules (council-reviewed, non-negotiable):
 *   - medians report right-censoring ("n still waiting, excluded") — with 61%
 *     ghosting, completed-only medians are survivorship-biased otherwise
 *   - 0-day hops (same-day catch-up entries) are excluded from medians, counted
 *   - no comparative multiplier claims below n=20 applied
 *   - above-range calibration always carries the selection-bias note
 *   - every benchmark mention carries its year and "directional"
 *
 * Benchmarks lookup order: --benchmarks <path> > config/benchmarks.yml (user
 * layer, survives updates) > templates/benchmarks.yml (shipped default).
 *
 * Run: node funnel-velocity.mjs             (JSON)
 *      node funnel-velocity.mjs --summary   (human-readable)
 *      node funnel-velocity.mjs --self-test
 *      node funnel-velocity.mjs --benchmarks path/to/benchmarks.yml
 */

import { readFileSync, existsSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { loadYaml } from './lib/yaml-document.mjs';
import { computeFunnel, computeFunnelWithHistory, parseStatusLogStages, trackerStatusByNum, computeTrackerStats } from './stats.mjs';
import { resolveColumns, parseTrackerRow } from './tracker-parse.mjs';
import { resolveTrackerPath, loadCanonicalStates, resolveCanonicalState } from './tracker-utils.mjs';
import { getCareerOpsRoot } from './path-resolver.mjs';
import { parseAppliedDate, normalizeStatus, loadFollowupsEnabled } from './followup-cadence.mjs';
import { flagValue, validateFlags } from './lib/cli-flags.mjs';
import { localToday } from './lib/local-today.mjs';
import { isMainModule } from './lib/is-main-module.mjs';

// Two roots, because this file reads both layers and they are not the same
// directory. CODE_ROOT is where the shipped templates live; DATA_ROOT is where
// the USER's tracker and overrides live, and getCareerOpsRoot() is what honours
// CAREER_OPS_ROOT / CAREER_OPS_DATA_DIR / the .career-ops-data marker.
//
// One name for both is how this went wrong: the constant was called CAREER_OPS
// and held __dirname, so it read correctly for templates and silently pointed
// the tracker lookup at the checkout. A user with a data root configured got
// "No tracker found ... nothing to calibrate yet" — indistinguishable from
// having no data.
const CODE_ROOT = dirname(fileURLToPath(import.meta.url));
const DATA_ROOT = getCareerOpsRoot();
const STATES_FILE = join(CODE_ROOT, 'templates/states.yml');

const KNOWN_FLAGS = ['--summary', '--self-test', '--benchmarks', '--help', '-h'];
const VALUE_FLAGS = ['--benchmarks'];

const USAGE = `Usage:
  node funnel-velocity.mjs                       # JSON report
  node funnel-velocity.mjs --summary             # human-readable report
  node funnel-velocity.mjs --benchmarks <path>   # override the benchmark YAML file
  node funnel-velocity.mjs --self-test           # run the built-in fixtures
  node funnel-velocity.mjs --help|-h              # show this message`;

const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
// `web` sits alongside `set-status` because it is the same class of event: a
// status change made in the web app is recorded as the user makes it, not
// reconstructed afterwards. Only the door differs.
// `reply-watch` is the same class: the user confirms the update interactively;
// the transition is observed at that moment, not reconstructed later.
// `dedup-tracker` is the opposite class: the kept row of a duplicate pair takes
// over the removed row's more advanced status, and that transition was found
// at dedup time, not observed then (#5536).
// `close-stale` is the same class: close-stale.mjs moves a long-silent Applied
// row to Discarded in bulk, dated the day it ran. That is when the silence was
// declared, not when anything happened, so it must not read as a hop (#5794).
const VALID_SOURCES = new Set(['set-status', 'web', 'correction', 'backfill', 'manual', 'reply-watch', 'dedup-tracker', 'close-stale']);
// Sources whose dates are trusted for day-math. backfill/manual/dedup-tracker/close-stale
// are parsed and counted but excluded: they are reconstructed after the fact,
// not observed.
const DAY_MATH_SOURCES = new Set(['set-status', 'web', 'correction', 'reply-watch']);

// The hops a candidate can measure from their own tracker. Applied→Rejected is
// tracked separately from the forward hops — a "days to terminal" number that
// mixes offers and rejections reads grim and means nothing.
const HOPS = [
  { key: 'appliedToResponded', from: 'Applied', to: 'Responded' },
  { key: 'respondedToAssessment', from: 'Responded', to: 'Assessment' },
  { key: 'assessmentToInterview', from: 'Assessment', to: 'Interview' },
  // Keep the direct hop for legacy rows that moved from Responded straight to
  // Interview before Assessment became a first-class lifecycle stage.
  { key: 'respondedToInterview', from: 'Responded', to: 'Interview', excludeIntermediate: 'Assessment' },
  { key: 'interviewToOffer', from: 'Interview', to: 'Offer' },
  { key: 'appliedToRejected', from: 'Applied', to: 'Rejected' },
];

// Verbatim strings the tone contract pins (also asserted by mode-doc checks).
const SELECTION_BIAS_NOTE = 'targeted applications are expected to beat mass-platform averages — this confirms your filtering works';
const BELOW_RANGE_ACTION = '→ check follow-up compliance (followup mode) or review your score threshold (patterns mode)';
const BELOW_RANGE_ACTION_NO_FOLLOWUPS = '→ review your score threshold (patterns mode)';
const CLAIM_MIN_N = 20;
const HOP_MIN_N = 3;

// --- Date helpers ---
export function parseISODate(s) {
  if (!DATE_RE.test(String(s ?? '').trim())) return null;
  const d = new Date(`${String(s).trim()}T00:00:00Z`);
  return Number.isNaN(d.getTime()) ? null : d;
}

export function daysBetween(fromStr, toStr) {
  const a = parseISODate(fromStr), b = parseISODate(toStr);
  if (!a || !b) return null;
  return Math.round((b - a) / 86400000);
}

// --- Ledger parsing ---
// line: {tracker#}\t{YYYY-MM-DD}\t{from}\t{to}\t{source}\t{note}
export function parseStatusLog(content, states) {
  const observations = [];
  const unparseable = [];
  const unknownSources = [];
  const lines = String(content || '').replace(/\r/g, '').split('\n');
  for (let i = 0; i < lines.length; i++) {
    const t = lines[i].trim();
    if (!t || t.startsWith('#')) continue;
    const cells = t.split('\t').map(c => c.trim());
    if (cells.length < 5) { unparseable.push({ line: i + 1, raw: t, reason: 'expected 5+ tab-separated columns' }); continue; }
    const [numRaw, date, fromRaw, toRaw, source, note = ''] = cells;
    const num = parseInt(numRaw, 10);
    if (!Number.isInteger(num) || String(num) !== numRaw) { unparseable.push({ line: i + 1, raw: t, reason: `bad tracker# "${numRaw}"` }); continue; }
    if (!parseISODate(date)) { unparseable.push({ line: i + 1, raw: t, reason: `bad date "${date}"` }); continue; }
    const from = fromRaw === '-' ? null : resolveCanonicalState(fromRaw, states);
    if (fromRaw !== '-' && !from) { unparseable.push({ line: i + 1, raw: t, reason: `unknown from-state "${fromRaw}"` }); continue; }
    const to = toRaw === '-' ? '-' : resolveCanonicalState(toRaw, states);
    if (toRaw !== '-' && !to) { unparseable.push({ line: i + 1, raw: t, reason: `unknown to-state "${toRaw}"` }); continue; }
    if (!VALID_SOURCES.has(source)) {
      unknownSources.push({ line: i + 1, num, source });
      // Parsed but never fed to day-math; still visible in dataQuality.
      observations.push({ num, date, from, to, source, note, dayMath: false });
      continue;
    }
    observations.push({ num, date, from, to, source, note, dayMath: DAY_MATH_SOURCES.has(source) });
  }
  return { observations, unparseable, unknownSources };
}

/**
 * Replay observations in file order, one timeline per tracker#, applying the
 * ledger's edit rules:
 *   - later `correction` with same (num, to) replaces the earlier observation's
 *     date (the fix for "agent logged the wrong day")
 *   - `to: "-"` retracts the row's latest surviving observation (the fix for
 *     "that transition never happened")
 *   - otherwise observations accumulate in file order
 *
 * File order is what a retraction pops, so the last entry is the change a new
 * retraction line would remove (set-status.mjs --undo reads it).
 *
 * @returns Map num -> [{from, to, date, source, dayMath}]
 */
export function replayObservations(observations) {
  const byNum = new Map();
  for (const obs of observations) {
    if (!byNum.has(obs.num)) byNum.set(obs.num, []);
    const timeline = byNum.get(obs.num);
    if (obs.to === '-') { timeline.pop(); continue; }
    if (obs.source === 'correction') {
      const idx = timeline.map(o => o.to).lastIndexOf(obs.to);
      if (idx !== -1) { timeline[idx] = { from: timeline[idx].from, to: obs.to, date: obs.date, source: obs.source, dayMath: obs.dayMath }; continue; }
    }
    timeline.push({ from: obs.from, to: obs.to, date: obs.date, source: obs.source, dayMath: obs.dayMath });
  }
  return byNum;
}

/**
 * Fold observations into one timeline per tracker#: replayObservations(), then
 * sorted by date so hop math sees event order, not entry order (--on
 * backdating makes file order unreliable, so dates may be non-monotonic in the
 * log). Stable sort keeps same-day catch-up entries in entry order.
 *
 * @returns Map num -> [{from, to, date, source, dayMath}]
 */
export function foldObservations(observations) {
  const byNum = replayObservations(observations);
  for (const timeline of byNum.values()) {
    timeline.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
  }
  return byNum;
}

// --- Percentiles ---
export function median(nums) {
  if (!nums.length) return null;
  const s = [...nums].sort((a, b) => a - b);
  const m = Math.floor(s.length / 2);
  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
}

// p75 by linear interpolation between closest ranks (R-7, the numpy default).
// Pinned by self-test fixture: [3,6,20] -> 13.
export function p75(nums) {
  if (!nums.length) return null;
  const s = [...nums].sort((a, b) => a - b);
  if (s.length === 1) return s[0];
  const rank = 0.75 * (s.length - 1);
  const lo = Math.floor(rank), hi = Math.ceil(rank);
  return s[lo] + (s[hi] - s[lo]) * (rank - lo);
}

// --- Velocity ---
/**
 * Per-hop day stats from folded timelines.
 *
 * A hop measurement = days between a row's dated `from` observation and its
 * next dated `to` observation (both day-math-trusted). Honesty rules:
 *   - 0-day hops excluded from the math, counted (same-day catch-up entries)
 *   - right-censoring: a row sitting in `from` with no later observation
 *     counts as censored for that hop (still waiting — median excludes it and
 *     must say so)
 *   - < HOP_MIN_N completed measurements -> insufficientData, no median
 */
export function computeVelocity(timelines, todayStr) {
  const result = {};
  for (const hop of HOPS) {
    const days = [];
    let sameDayExcluded = 0;
    let censored = 0;
    for (const timeline of timelines.values()) {
      // A row can re-enter the from-state (re-applied after a rejection), so
      // each entry starts its own measurement instead of the row's first one.
      let start = null;
      let left = false;
      let viaIntermediate = false;
      for (const o of timeline) {
        if (o.to === hop.from) {
          if (!start || left) { start = o.dayMath ? o : null; left = false; viaIntermediate = false; }
          continue;
        }
        if (!start) continue;
        if (o.to === hop.to && o.dayMath) {
          const d = daysBetween(start.date, o.date);
          start = null;
          if (viaIntermediate || d === null || d < 0) continue;
          if (d === 0) { sameDayExcluded++; continue; }
          days.push(d);
          continue;
        }
        left = true;
        if (o.to === hop.excludeIntermediate) viaIntermediate = true;
      }
      // Row's latest state is the hop's from-state: still waiting = censored.
      // Only forward hops censor; Applied→Rejected shares Applied rows with
      // Applied→Responded, so count censoring once (on the forward hop).
      if (start && timeline.at(-1).to === hop.from && hop.to !== 'Rejected') censored++;
    }
    result[hop.key] = {
      from: hop.from,
      to: hop.to,
      n: days.length,
      median: days.length >= HOP_MIN_N ? median(days) : null,
      p75: days.length >= HOP_MIN_N ? p75(days) : null,
      insufficientData: days.length < HOP_MIN_N,
      sameDayExcluded,
      censored,
    };
  }
  return result;
}

// --- Benchmarks ---
export function loadBenchmarks(explicitPath) {
  const path = explicitPath
    || (existsSync(join(DATA_ROOT, 'config/benchmarks.yml')) ? join(DATA_ROOT, 'config/benchmarks.yml') : join(CODE_ROOT, 'templates/benchmarks.yml'));
  let doc;
  try {
    doc = loadYaml(readFileSync(path, 'utf-8'));
  } catch (err) {
    throw new Error(`Cannot read benchmarks at ${path}: ${err.message}`);
  }
  if (!doc || typeof doc.benchmarks !== 'object' || doc.benchmarks === null) {
    throw new Error(`Malformed benchmarks file at ${path}: expected a top-level "benchmarks" map`);
  }
  return { benchmarks: doc.benchmarks, path };
}

/** Classify an own-rate percentage against a benchmark's range (inclusive). */
export function classify(ownPct, metric) {
  if (ownPct === null || ownPct === undefined || !metric || !Array.isArray(metric.range_pct)) return null;
  const [lo, hi] = metric.range_pct;
  const band = ownPct < lo ? 'below-range' : ownPct > hi ? 'above-range' : 'within-range';
  const typical = metric.typical_pct;
  return {
    band,
    ownPct,
    rangePct: [lo, hi],
    typicalPct: typical ?? null,
    vsTypical: typical ? Math.round((ownPct / typical) * 10) / 10 : null,
    source: metric.source ?? null,
    year: metric.year ?? null,
    caveat: metric.caveat ?? null,
  };
}

// --- Calibration (flagship: works day one, no ledger needed) ---
export function computeCalibration(funnel, benchmarks) {
  const smallSample = funnel.everApplied < CLAIM_MIN_N;
  return {
    everApplied: funnel.everApplied,
    smallSample,
    claimMinN: CLAIM_MIN_N,
    // 'ledger' when the ever* counts fold status-log history (rejected-after-
    // interview rows counted at the stage they reached), 'snapshot' otherwise.
    basis: funnel.basis === 'ledger' ? 'ledger' : 'snapshot',
    responseRate: classify(funnel.everApplied > 0 ? funnel.responseRate : null, benchmarks.response_rate),
    interviewRate: classify(funnel.everApplied > 0 ? funnel.interviewRate : null, benchmarks.application_to_interview),
  };
}

// --- Waiting (flagship #2: in-flight Applied rows vs first-response window) ---
/**
 * Applied-date priority per row:
 *   1. ledger Applied observation (event-dated via --on, or logged same day)
 *   2. "Applied YYYY-MM-DD" in the tracker notes (followup-cadence convention;
 *      followup-seed/apply modes write it — same helper, same regex)
 *   3. unknown (listed, never guessed — the tracker date column is the
 *      EVALUATION date and must not stand in for the submission date)
 */
export function computeWaiting(rows, timelines, benchmarks, todayStr) {
  const windowDays = benchmarks.days_first_response?.range_days ?? [5, 14];
  const items = [];
  let unknownDates = 0;
  for (const row of rows) {
    // Canonicalize before comparing — the funnel counts everApplied through
    // normalizeStatus, so non-canonical Applied rows (lowercase "applied", a
    // status carrying a date, localized "Aplicado", markdown-bold "**Applied**")
    // must surface here too, or the follow-up backlog is under-reported.
    if (normalizeStatus(row.status) !== 'applied') continue;
    const timeline = timelines.get(row.num) || [];
    const ledgerApplied = timeline.filter(o => o.to === 'Applied' && o.dayMath).pop();
    const appliedDate = ledgerApplied?.date ?? parseAppliedDate(row.notes) ?? null;
    if (!appliedDate) { unknownDates++; items.push({ num: row.num, company: row.company, appliedDate: null, elapsedDays: null, beyondTypicalWindow: false, dateSource: 'unknown' }); continue; }
    const elapsed = daysBetween(appliedDate, todayStr);
    items.push({
      num: row.num,
      company: row.company,
      appliedDate,
      elapsedDays: elapsed,
      beyondTypicalWindow: elapsed !== null && elapsed > windowDays[1],
      dateSource: ledgerApplied ? 'status-log' : 'tracker-notes',
    });
  }
  return {
    windowDays,
    windowSource: benchmarks.days_first_response ? { source: benchmarks.days_first_response.source, year: benchmarks.days_first_response.year } : null,
    inFlight: items.length,
    unknownDates,
    items: items.sort((a, b) => (b.elapsedDays ?? -1) - (a.elapsedDays ?? -1)),
  };
}

// --- Tracker rows ---
export function parseTrackerRows(content) {
  const lines = String(content ?? '').replace(/\r/g, '').split('\n');
  const colmap = resolveColumns(lines);
  const rows = [];
  for (const line of lines) {
    const row = parseTrackerRow(line, colmap);
    if (row) rows.push(row);
  }
  return rows;
}

// --- Assembly ---
export function analyze({ trackerContent, logContent, benchmarks, states, todayStr }) {
  const rows = parseTrackerRows(trackerContent);
  const stats = computeTrackerStats(trackerContent);
  // Ledger-aware funnel when the transition log carries usable history: a row now
  // sitting in a terminal snapshot (Rejected/Discarded) still counts for the
  // middle stages it passed through, so interviewRate/responseRate stop
  // undercounting rejected-after-interview rows (#3493). Same canonical
  // definition `node stats.mjs` uses. Branch on the parsed stages, not the raw
  // file: a header-only, comment-only, or all-malformed log has no history to
  // fold, and taking the ledger path anyway would stamp basis:'ledger' on a
  // funnel identical to the snapshot and print the "rates fold history" note.
  const ledgerStages = parseStatusLogStages(logContent);
  const funnel = ledgerStages.length > 0
    ? computeFunnelWithHistory(trackerStatusByNum(trackerContent), ledgerStages)
    : computeFunnel(stats.byStatus);
  const { observations, unparseable, unknownSources } = parseStatusLog(logContent, states);
  const timelines = foldObservations(observations);

  const trackerNums = new Set(rows.map(r => r.num));
  const orphans = [...timelines.keys()].filter(n => !trackerNums.has(n));
  const coveredRows = [...timelines.keys()].filter(n => trackerNums.has(n)).length;
  const newestObs = observations.reduce((max, o) => (o.date > max ? o.date : max), '');

  const velocity = computeVelocity(timelines, todayStr);
  // The one hop with a candidate-side day benchmark gets it attached, so the
  // renderer can show market context next to the own-median (same denominator:
  // per-successful-process). Gated on an existing median: with insufficientData
  // the JSON output would otherwise leak a benchmark next to a null median.
  const io = benchmarks.days_interview_to_offer;
  if (io && Array.isArray(io.range_days) && velocity.interviewToOffer.median !== null) {
    velocity.interviewToOffer.benchmark = {
      rangeDays: io.range_days,
      typicalDays: io.typical_days ?? null,
      source: io.source ?? null,
      year: io.year ?? null,
    };
  }

  return {
    calibration: computeCalibration(funnel, benchmarks),
    waiting: computeWaiting(rows, timelines, benchmarks, todayStr),
    velocity,
    dataQuality: {
      trackerRows: rows.length,
      coveredRows,
      observations: observations.length,
      orphans,
      unparseable,
      unknownSources,
      newestObservation: newestObs || null,
    },
  };
}

// --- Summary rendering (tone contract lives here — see header) ---
function fmtCalibrationLine(label, c, smallSample, n, belowRangeAction) {
  if (!c || c.ownPct === null) return `  ${label}: no data yet`;
  const range = `${c.rangePct[0]}–${c.rangePct[1]}% typical band (${c.year ?? 'n/a'}, directional)`;
  let line = `  ${label}: ${c.ownPct}% vs ${range}`;
  if (smallSample) {
    line += ` — small sample (n=${n}) — directional only`;
    return line;
  }
  if (c.band === 'above-range') {
    line += ` — above the typical band${c.vsTypical ? `, ${c.vsTypical}× typical` : ''} (${SELECTION_BIAS_NOTE})`;
  } else if (c.band === 'below-range') {
    line += ` — below the typical band ${belowRangeAction}`;
  } else {
    line += ' — within the typical band';
  }
  return line;
}

export function renderSummary(result, todayStr, { followupsEnabled = true } = {}) {
  const out = [];
  const belowRangeAction = followupsEnabled ? BELOW_RANGE_ACTION : BELOW_RANGE_ACTION_NO_FOLLOWUPS;
  const { calibration: cal, waiting, velocity, dataQuality: dq } = result;
  out.push('━'.repeat(46));
  out.push(`Funnel Calibration — ${todayStr}`);
  out.push('━'.repeat(46));

  out.push('\nCalibration (your funnel vs market):');
  if (cal.everApplied === 0) {
    out.push('  no applications sent yet — calibration starts at your first Applied row');
  } else {
    out.push(fmtCalibrationLine('Response rate', cal.responseRate, cal.smallSample, cal.everApplied, belowRangeAction));
    out.push(fmtCalibrationLine('Interview rate', cal.interviewRate, cal.smallSample, cal.everApplied, belowRangeAction));
    if (cal.basis === 'ledger') out.push('  (rates fold status-log history — a row rejected after an interview still counts as reaching Interview)');
    if (cal.smallSample) out.push(`  (comparative claims need n≥${cal.claimMinN} applied; you have ${cal.everApplied})`);
  }

  out.push('\nWaiting (in-flight applications):');
  if (!waiting.inFlight) {
    out.push('  none in Applied right now');
  } else {
    out.push(`  ${waiting.inFlight} in flight. Typical first-response window: ${waiting.windowDays[0]}–${waiting.windowDays[1]} days (${waiting.windowSource?.year ?? 'n/a'}, directional; many applications never get a response — silence is common, not a verdict).`);
    for (const item of waiting.items) {
      if (item.appliedDate === null) { out.push(`  #${item.num} ${item.company} — applied date unknown (no dated Applied observation; add "Applied YYYY-MM-DD" to its notes or use set-status)`); continue; }
      const flag = item.beyondTypicalWindow ? `, beyond typical ${waiting.windowDays[0]}–${waiting.windowDays[1]}d window${followupsEnabled ? ' → consider followup mode' : ''}` : '';
      out.push(`  #${item.num} ${item.company} — applied ${item.appliedDate} (${item.elapsedDays}d${flag})`);
    }
  }

  out.push('\nVelocity (days per stage, from the transition ledger):');
  const hopsWithData = Object.values(velocity).filter(h => !h.insufficientData);
  for (const h of Object.values(velocity)) {
    const extras = [];
    if (h.censored) extras.push(`${h.censored} still waiting, excluded`);
    if (h.sameDayExcluded) extras.push(`${h.sameDayExcluded} same-day catch-up entr${h.sameDayExcluded === 1 ? 'y' : 'ies'} excluded`);
    const extraStr = extras.length ? `; ${extras.join('; ')}` : '';
    if (h.insufficientData) {
      out.push(`  ${h.from}→${h.to}: insufficient data (n=${h.n}${extraStr})`);
    } else {
      const bm = h.benchmark ? ` vs ${h.benchmark.rangeDays[0]}–${h.benchmark.rangeDays[1]}d typical (${h.benchmark.year ?? 'n/a'}, directional)` : '';
      out.push(`  ${h.from}→${h.to}: median ${h.median}d, p75 ${h.p75}d${bm} (n=${h.n} completed${extraStr} — median reflects answered applications only)`);
    }
  }
  if (!hopsWithData.length && dq.observations === 0) {
    out.push('  ledger is empty — velocity accrues as statuses change through set-status.mjs');
  }

  out.push('\nData quality:');
  out.push(`  velocity data for ${dq.coveredRows} of ${dq.trackerRows} tracker rows (rows predating the log or edited outside set-status have no dated transitions)`);
  if (dq.unparseable.length) {
    out.push(`  ⚠ ${dq.unparseable.length} unparseable ledger line${dq.unparseable.length === 1 ? '' : 's'}:`);
    for (const u of dq.unparseable) out.push(`      line ${u.line}: ${u.reason}`);
  } else out.push('  unparseable ledger lines: none');
  if (dq.unknownSources.length) {
    out.push(`  ⚠ ${dq.unknownSources.length} observation${dq.unknownSources.length === 1 ? '' : 's'} with unrecognized source (excluded from day-math):`);
    for (const s of dq.unknownSources) out.push(`      line ${s.line}: #${s.num} source "${s.source}"`);
  } else out.push('  unrecognized sources: none');
  if (dq.orphans.length) {
    out.push(`  ⚠ ${dq.orphans.length} orphaned tracker#${dq.orphans.length === 1 ? '' : 's'} in the ledger (renumbering/dedup can strand them): ${dq.orphans.map(n => `#${n}`).join(', ')}`);
  } else out.push('  orphaned ledger entries: none');
  if (dq.newestObservation) out.push(`  newest observation: ${dq.newestObservation}`);
  out.push('');
  return out.join('\n');
}

// --- Self-test ---
function selfTest() {
  let failures = 0;
  const check = (cond, msg) => {
    if (!cond) { console.error(`SELF-TEST FAIL: ${msg}`); failures++; }
  };
  const states = loadCanonicalStates(STATES_FILE);
  const TODAY = '2026-07-08';

  // -- parser --
  const LOG_FIXTURE = [
    '1\t2026-06-01\tEvaluated\tApplied\tset-status\t',
    '1\t2026-06-08\tApplied\tResponded\tset-status\t',
    '1\t2026-06-15\tResponded\tInterview\tset-status\t',
    '1\t2026-06-30\tInterview\tOffer\tset-status\t',
    '2\t2026-06-01\t-\tApplied\tset-status\tunknown prior state',
    '2\t2026-06-11\tApplied\tResponded\tset-status\t',
    '2\t2026-06-09\tApplied\tResponded\tcorrection\tthey actually replied on the 9th',
    '3\t2026-06-05\tEvaluated\tApplied\tset-status\t',
    '3\t2026-06-05\tApplied\tResponded\tset-status\tsame-day catch-up',
    '4\t2026-06-20\tEvaluated\tApplied\tset-status\t',
    '5\t2026-06-01\tEvaluated\tApplied\tset-status\t',
    '5\t2026-06-02\tApplied\tInterview\tset-status\tmis-click',
    '5\t2026-06-02\t-\t-\tset-status\tretract the mis-click',
    '6\t2026-06-03\tEvaluated\tApplied\tfuture-import\tunknown source on purpose',
    '99\t2026-06-01\tEvaluated\tApplied\tset-status\torphan - not in tracker',
    'x\t2026-06-01\tEvaluated\tApplied\tset-status\tbad num',
    '7\t06/01/2026\tEvaluated\tApplied\tset-status\tbad date',
    '8\t2026-06-01\tEvaluated\tShortlisted\tset-status\tnon-canonical state',
    '',
    '# comment line',
  ].join('\n');

  const { observations, unparseable, unknownSources } = parseStatusLog(LOG_FIXTURE, states);
  check(unparseable.length === 3, `parser: expected 3 unparseable, got ${unparseable.length}`);
  check(unparseable.some(u => u.reason.includes('bad tracker#')), 'parser: bad num reported');
  check(unparseable.some(u => u.reason.includes('bad date')), 'parser: bad date reported');
  check(unparseable.some(u => u.reason.includes('unknown to-state')), 'parser: non-canonical state reported');
  check(unknownSources.length === 1 && unknownSources[0].source === 'future-import', 'parser: unknown source counted');
  check(observations.find(o => o.source === 'future-import')?.dayMath === false, 'parser: unknown source excluded from day-math');
  check(observations.find(o => o.num === 2 && o.from === null), 'parser: "-" from-state parses as null');

  // A status change made from the web app is observed live, at the moment the
  // user makes it — the same event as a set-status transition entering through
  // a different door. Excluding it does not drop the rows, which is what makes
  // the failure quiet: they are parsed, counted, flagged under unknownSources,
  // and contribute nothing to the hop figures, so a web-driven install reads as
  // an empty funnel rather than a broken one. Its own fixture so the counts
  // pinned above stay pinned.
  const WEB_FIXTURE = [
    '1\t2026-06-01\tEvaluated\tApplied\tweb\t',
    '1\t2026-06-08\tApplied\tResponded\tweb\t',
  ].join('\n');
  const web = parseStatusLog(WEB_FIXTURE, states);
  check(web.unknownSources.length === 0, `parser: web is a recognized source (got ${web.unknownSources.length} unknown)`);
  check(web.observations.length === 2 && web.observations.every(o => o.dayMath === true),
    'parser: web observations are trusted for day-math');

  // The rows above are a clean 7-day Applied→Responded hop. Asserting the
  // parse alone would not have caught this: the defect was never that the rows
  // failed to parse, it was that a parsed row reached no figure.
  const webVelocity = computeVelocity(foldObservations(web.observations), TODAY);
  check(webVelocity.appliedToResponded.n === 1,
    `velocity: a web transition reaches the hop figures (expected n=1, got ${webVelocity.appliedToResponded.n})`);

  // reply-watch is the same event class as set-status/web: the user confirms the
  // update interactively and it is recorded at that moment (not reconstructed
  // after the fact the way backfill/manual are). A reply-watch transition that is
  // excluded from day-math silently empties the velocity figures for users who
  // manage their inbox through reply-watch. Its own fixture so the counts above
  // stay pinned and this source is covered independently.
  const REPLY_WATCH_FIXTURE = [
    '1\t2026-06-01\tEvaluated\tApplied\treply-watch\t',
    '1\t2026-06-09\tApplied\tResponded\treply-watch\t',
  ].join('\n');
  const rw = parseStatusLog(REPLY_WATCH_FIXTURE, states);
  check(rw.unknownSources.length === 0, `parser: reply-watch is a recognized source (got ${rw.unknownSources.length} unknown)`);
  check(rw.observations.length === 2 && rw.observations.every(o => o.dayMath === true),
    'parser: reply-watch observations are trusted for day-math');
  const rwVelocity = computeVelocity(foldObservations(rw.observations), TODAY);
  check(rwVelocity.appliedToResponded.n === 1,
    `velocity: a reply-watch transition reaches the hop figures (expected n=1, got ${rwVelocity.appliedToResponded.n})`);

  // -- fold --
  const timelines = foldObservations(observations);
  const t2 = timelines.get(2);
  check(t2.length === 2, `fold: row 2 expected 2 observations, got ${t2.length}`);
  check(t2[1].date === '2026-06-09' && t2[1].source === 'correction', 'fold: correction replaces same-(num,to) date');
  const t5 = timelines.get(5);
  check(t5.length === 1 && t5[0].to === 'Applied', `fold: retraction removes latest observation (got ${t5.map(o => o.to).join(',')})`);

  // -- percentiles --
  check(median([3, 6, 20]) === 6, 'median odd');
  check(median([3, 6]) === 4.5, 'median even');
  check(p75([3, 6, 20]) === 13, `p75 interpolation: expected 13, got ${p75([3, 6, 20])}`);
  check(p75([5]) === 5, 'p75 single value');

  // -- velocity --
  const velocity = computeVelocity(timelines, TODAY);
  check(velocity.appliedToResponded.n === 2, `velocity: A→R expected n=2 (rows 1,2), got ${velocity.appliedToResponded.n}`);
  check(velocity.appliedToResponded.insufficientData === true, 'velocity: n=2 < 3 → insufficient');
  check(velocity.appliedToResponded.median === null, 'velocity: insufficient → no median');
  check(velocity.appliedToResponded.sameDayExcluded === 1, `velocity: row 3 same-day hop excluded+counted, got ${velocity.appliedToResponded.sameDayExcluded}`);
  // rows 4, 5, 99 sit in Applied with no later observation → censored (still waiting)
  check(velocity.appliedToResponded.censored === 3, `velocity: expected 3 censored, got ${velocity.appliedToResponded.censored}`);
  check(velocity.appliedToRejected.censored === 0, 'velocity: rejection hop does not double-count censoring');
  check(velocity.interviewToOffer.n === 1 && velocity.interviewToOffer.insufficientData, 'velocity: I→O n=1 insufficient');

  const ASSESSMENT_FIXTURE = [
    '10\t2026-06-01\tApplied\tResponded\tset-status\t',
    '10\t2026-06-04\tResponded\tAssessment\tset-status\t',
    '10\t2026-06-09\tAssessment\tInterview\tset-status\t',
  ].join('\n');
  const assessmentVelocity = computeVelocity(
    foldObservations(parseStatusLog(ASSESSMENT_FIXTURE, states).observations),
    TODAY,
  );
  check(assessmentVelocity.respondedToAssessment.n === 1,
    `velocity: Responded→Assessment expected n=1, got ${assessmentVelocity.respondedToAssessment.n}`);
  check(assessmentVelocity.assessmentToInterview.n === 1,
    `velocity: Assessment→Interview expected n=1, got ${assessmentVelocity.assessmentToInterview.n}`);
  check(assessmentVelocity.respondedToInterview.n === 0,
    `velocity: Assessment path must not count as legacy Responded→Interview, got n=${assessmentVelocity.respondedToInterview.n}`);

  // three completed A→R measurements → median renders
  const logWithThird = LOG_FIXTURE + '\n4\t2026-06-27\tApplied\tResponded\tset-status\t';
  const v3 = computeVelocity(foldObservations(parseStatusLog(logWithThird, states).observations), TODAY);
  check(v3.appliedToResponded.n === 3 && v3.appliedToResponded.median === 7, `velocity: [7,8,7] → median 7, got n=${v3.appliedToResponded.n} median=${v3.appliedToResponded.median}`);
  check(v3.appliedToResponded.censored === 2, 'velocity: censored drops to 2 after row 4 completes');

  // -- benchmarks + classification --
  const bm = loadBenchmarks(join(CODE_ROOT, 'templates/benchmarks.yml')).benchmarks;
  check(bm.response_rate && Array.isArray(bm.response_rate.range_pct), 'benchmarks: shipped file loads');
  check(bm.days_first_response.range_days[1] === 14, 'benchmarks: first-response window upper bound');
  check(!('time_to_fill' in bm), 'benchmarks: employer-side time_to_fill must not exist');
  check(classify(1.5, bm.response_rate).band === 'below-range', 'classify: below');
  check(classify(6, bm.response_rate).band === 'within-range', 'classify: within');
  check(classify(14, bm.response_rate).band === 'above-range', 'classify: above');
  check(classify(2, bm.response_rate).band === 'within-range', 'classify: lower bound inclusive');
  check(classify(13, bm.response_rate).band === 'within-range', 'classify: upper bound inclusive');
  check(classify(6, bm.response_rate).vsTypical === 2, 'classify: vsTypical multiplier');

  // -- calibration gating --
  const mkTracker = (applied, responded) => {
    const header = '| # | Date | Company | Role | Score | Status | PDF | Report | Notes |\n|---|------|---------|------|-------|--------|-----|--------|-------|';
    const rows = [];
    let n = 1;
    for (let i = 0; i < applied; i++) rows.push(`| ${n++} | 2026-06-01 | Co${n} | Role | 4.0/5 | Applied | ❌ | - | |`);
    for (let i = 0; i < responded; i++) rows.push(`| ${n++} | 2026-06-01 | Co${n} | Role | 4.0/5 | Responded | ❌ | - | Applied 2026-06-01 |`);
    return `${header}\n${rows.join('\n')}`;
  };
  const small = analyze({ trackerContent: mkTracker(16, 1), logContent: '', benchmarks: bm, states, todayStr: TODAY });
  check(small.calibration.smallSample === true, 'calibration: n=17 < 20 → smallSample');
  const smallSummary = renderSummary(small, TODAY);
  check(!/[\d.]+× typical/.test(smallSummary), 'tone: no multiplier claim under n=20');
  check(smallSummary.includes('directional only'), 'tone: small-sample label present');

  const big = analyze({ trackerContent: mkTracker(38, 2), logContent: '', benchmarks: bm, states, todayStr: TODAY });
  check(big.calibration.smallSample === false, 'calibration: n=40 → claims allowed');
  check(big.calibration.responseRate.ownPct === 5, `calibration: 2/40 = 5%, got ${big.calibration.responseRate.ownPct}`);
  const bigSummary = renderSummary(big, TODAY);
  check(bigSummary.includes('within the typical band'), 'tone: within-band phrasing');

  // above-range → selection-bias note; below-range → single action pointer
  const above = renderSummary(analyze({ trackerContent: mkTracker(25, 15), logContent: '', benchmarks: bm, states, todayStr: TODAY }), TODAY);
  check(above.includes(SELECTION_BIAS_NOTE), 'tone: above-range carries selection-bias note');
  const below = renderSummary(analyze({ trackerContent: mkTracker(40, 0), logContent: '', benchmarks: bm, states, todayStr: TODAY }), TODAY);
  check(below.includes(BELOW_RANGE_ACTION), 'tone: below-range carries the single action pointer');
  check(below.includes('(2025, directional)'), 'tone: benchmark year + directional attached');

  // -- ledger-aware calibration (#3493): a terminal Rejected snapshot must not
  // erase the middle stages the row actually reached. Same shape stats.mjs uses. --
  const ledgerHeader = '| # | Date | Company | Role | Score | Status | PDF | Report | Notes |\n|---|------|---------|------|-------|--------|-----|--------|-------|';
  const ledgerRows = [];
  for (let i = 1; i <= 21; i++) ledgerRows.push(`| ${i} | 2026-06-01 | Co${i} | Role | 4.0/5 | Applied | ❌ | - | |`);
  for (let i = 22; i <= 25; i++) ledgerRows.push(`| ${i} | 2026-06-01 | Co${i} | Role | 4.0/5 | Rejected | ❌ | - | |`);
  const ledgerTracker = `${ledgerHeader}\n${ledgerRows.join('\n')}`;
  const ledgerLog = [
    '22\t2026-06-02\tApplied\tResponded\tset-status\t',
    '22\t2026-06-09\tResponded\tInterview\tset-status\t',
    '22\t2026-06-20\tInterview\tRejected\tset-status\t',
    '23\t2026-06-02\tApplied\tResponded\tset-status\t',
    '23\t2026-06-09\tResponded\tInterview\tset-status\t',
    '23\t2026-06-20\tInterview\tRejected\tset-status\t',
    '24\t2026-06-03\tApplied\tResponded\tset-status\t',
    '24\t2026-06-18\tResponded\tRejected\tset-status\t',
  ].join('\n');
  const snap = analyze({ trackerContent: ledgerTracker, logContent: '', benchmarks: bm, states, todayStr: TODAY });
  check(snap.calibration.basis === 'snapshot', 'ledger-funnel: no log → snapshot basis');
  check(snap.calibration.interviewRate.ownPct === 0, `ledger-funnel: snapshot erases interviews reached, got ${snap.calibration.interviewRate.ownPct}`);
  const led = analyze({ trackerContent: ledgerTracker, logContent: ledgerLog, benchmarks: bm, states, todayStr: TODAY });
  check(led.calibration.basis === 'ledger', 'ledger-funnel: log present → ledger basis');
  check(led.calibration.everApplied === 25, `ledger-funnel: everApplied still 25, got ${led.calibration.everApplied}`);
  check(led.calibration.interviewRate.ownPct === 8, `ledger-funnel: 2/25 reached Interview → 8%, got ${led.calibration.interviewRate.ownPct}`);
  check(led.calibration.responseRate.ownPct === 16, `ledger-funnel: 4/25 received a reply including rejection → 16%, got ${led.calibration.responseRate.ownPct}`);
  check(renderSummary(led, TODAY).includes('rates fold status-log history'), 'ledger-funnel: summary flags the folded basis');
  check(!renderSummary(snap, TODAY).includes('rates fold status-log history'), 'ledger-funnel: snapshot summary carries no fold note');

  // A log with no *parsed* history — header row, comments, torn rows — must stay
  // on the snapshot basis: taking the ledger path would stamp basis:'ledger' on
  // a funnel identical to the snapshot and wrongly print the fold note.
  for (const [label, emptyLog] of [
    ['header only', '#\tdate\tfrom\tto\tsource\tnote'],
    ['comment only', '# migrated 2026-06-01 — no transitions yet'],
    ['torn rows only', 'x\t2026-06-02\tApplied\tResponded\nx\t2026-06-09\tResponded\tInterview'],
    ['whitespace', '   \n\t\n'],
  ]) {
    const r = analyze({ trackerContent: ledgerTracker, logContent: emptyLog, benchmarks: bm, states, todayStr: TODAY });
    check(r.calibration.basis === 'snapshot', `ledger-funnel: ${label} log → snapshot basis`);
    check(r.calibration.interviewRate.ownPct === snap.calibration.interviewRate.ownPct, `ledger-funnel: ${label} log leaves rates on the snapshot value`);
    check(!renderSummary(r, TODAY).includes('rates fold status-log history'), `ledger-funnel: ${label} log carries no fold note`);
  }

  // everX counts distinct tracker rows, so a transition the ledger records more
  // than once (a re-applied set-status, a torn-then-rewritten append) must not
  // inflate the funnel — the ledger result is identical with each line doubled.
  const dupLog = ledgerLog.split('\n').flatMap(l => [l, l]).join('\n');
  const dup = analyze({ trackerContent: ledgerTracker, logContent: dupLog, benchmarks: bm, states, todayStr: TODAY });
  check(dup.calibration.everApplied === led.calibration.everApplied, `ledger-funnel: duplicated transitions leave everApplied at ${led.calibration.everApplied}, got ${dup.calibration.everApplied}`);
  check(dup.calibration.interviewRate.ownPct === led.calibration.interviewRate.ownPct, `ledger-funnel: duplicated transitions leave interviewRate at ${led.calibration.interviewRate.ownPct}%, got ${dup.calibration.interviewRate.ownPct}%`);
  check(dup.calibration.responseRate.ownPct === led.calibration.responseRate.ownPct, `ledger-funnel: duplicated transitions leave responseRate at ${led.calibration.responseRate.ownPct}%, got ${dup.calibration.responseRate.ownPct}%`);
  // A row that genuinely bounces back and forth is still one row at its deepest
  // stage — Responded→Interview→Responded→Interview counts once into everInterview.
  const bounceLog = [
    '2\t2026-06-02\tApplied\tResponded\tset-status\t',
    '2\t2026-06-09\tResponded\tInterview\tset-status\t',
    '2\t2026-06-12\tInterview\tResponded\tset-status\t',
    '2\t2026-06-15\tResponded\tInterview\tset-status\t',
  ].join('\n');
  const bounce = analyze({ trackerContent: ledgerTracker, logContent: bounceLog, benchmarks: bm, states, todayStr: TODAY });
  check(bounce.calibration.interviewRate.ownPct === 4, `ledger-funnel: a bouncing row counts once → 1/25 = 4%, got ${bounce.calibration.interviewRate.ownPct}`);

  // A current Discarded row with no ledger history stays out of everApplied in
  // both funnels — Discarded (unlike Rejected) does not by itself prove a
  // submission, and the ledger path must not silently diverge from the snapshot.
  const discardTracker = `${ledgerHeader}\n${[
    ...Array.from({ length: 10 }, (_, i) => `| ${i + 1} | 2026-06-01 | Co${i + 1} | Role | 4.0/5 | Applied | ❌ | - | |`),
    '| 11 | 2026-06-01 | Co11 | Role | 4.0/5 | Discarded | ❌ | - | |',
  ].join('\n')}`;
  const discardSnap = analyze({ trackerContent: discardTracker, logContent: '', benchmarks: bm, states, todayStr: TODAY });
  const discardLed = analyze({ trackerContent: discardTracker, logContent: '1\t2026-06-05\tApplied\tResponded\tset-status\t', benchmarks: bm, states, todayStr: TODAY });
  check(discardSnap.calibration.everApplied === 10, `ledger-funnel: snapshot leaves a no-history Discarded row out of everApplied, got ${discardSnap.calibration.everApplied}`);
  check(discardLed.calibration.everApplied === discardSnap.calibration.everApplied, `ledger-funnel: ledger path agrees with snapshot on a no-history Discarded row, got ${discardLed.calibration.everApplied} vs ${discardSnap.calibration.everApplied}`);

  // -- waiting --
  const waitTracker = [
    '| # | Date | Company | Role | Score | Status | PDF | Report | Notes |',
    '|---|------|---------|------|-------|--------|-----|--------|-------|',
    '| 1 | 2026-06-01 | LogCo | Role | 4.0/5 | Applied | ❌ | - | |',
    '| 2 | 2026-06-01 | NotesCo | Role | 4.0/5 | Applied | ❌ | - | Applied 2026-07-01 |',
    '| 3 | 2026-06-01 | UnknownCo | Role | 4.0/5 | Applied | ❌ | - | evaluated only |',
    '| 4 | 2026-06-01 | DoneCo | Role | 4.0/5 | Responded | ❌ | - | Applied 2026-06-01 |',
  ].join('\n');
  const waitLog = '1\t2026-06-10\tEvaluated\tApplied\tset-status\t';
  const wait = analyze({ trackerContent: waitTracker, logContent: waitLog, benchmarks: bm, states, todayStr: TODAY }).waiting;
  check(wait.inFlight === 3, `waiting: 3 Applied rows in flight, got ${wait.inFlight}`);
  const w1 = wait.items.find(i => i.num === 1);
  check(w1.dateSource === 'status-log' && w1.appliedDate === '2026-06-10', 'waiting: ledger date wins');
  check(w1.elapsedDays === 28 && w1.beyondTypicalWindow === true, `waiting: 28d beyond 14d window, got ${w1.elapsedDays}`);
  const w2 = wait.items.find(i => i.num === 2);
  check(w2.dateSource === 'tracker-notes' && w2.elapsedDays === 7 && w2.beyondTypicalWindow === false, 'waiting: notes date fallback, within window');
  const w3 = wait.items.find(i => i.num === 3);
  check(w3.dateSource === 'unknown' && w3.appliedDate === null, 'waiting: unknown date listed, never guessed');
  check(!wait.items.some(i => i.num === 4), 'waiting: non-Applied rows excluded');

  // Non-canonical Applied rows must still count as in-flight. The funnel counts
  // everApplied through normalizeStatus, so lowercase "applied", a status
  // carrying a date, a localized "Aplicado", and markdown-bold "**Applied**"
  // belong in the waiting backlog too (regression: a raw row.status !== 'Applied'
  // filter dropped all four and under-reported follow-ups).
  const noncanonTracker = [
    '| # | Date | Company | Role | Score | Status | PDF | Report | Notes |',
    '|---|------|---------|------|-------|--------|-----|--------|-------|',
    '| 1 | 2026-06-01 | CanonCo | Role | 4.0/5 | Applied | ❌ | - | Applied 2026-07-01 |',
    '| 2 | 2026-06-01 | LowerCo | Role | 4.0/5 | applied | ❌ | - | Applied 2026-07-01 |',
    '| 3 | 2026-06-01 | DatedCo | Role | 4.0/5 | Applied 2026-06-01 | ❌ | - | Applied 2026-07-01 |',
    '| 4 | 2026-06-01 | LocaleCo | Role | 4.0/5 | Aplicado | ❌ | - | Applied 2026-07-01 |',
    '| 5 | 2026-06-01 | BoldCo | Role | 4.0/5 | **Applied** | ❌ | - | Applied 2026-07-01 |',
  ].join('\n');
  const noncanon = analyze({ trackerContent: noncanonTracker, logContent: '', benchmarks: bm, states, todayStr: TODAY });
  check(noncanon.waiting.inFlight === 5, `waiting: non-canonical Applied variants all count in-flight, got ${noncanon.waiting.inFlight}`);
  // The waiting count must agree with the funnel's everApplied for the same rows —
  // both canonicalize status the same way, so neither may silently drop a variant.
  check(noncanon.calibration.everApplied === 5, `waiting: in-flight agrees with everApplied on non-canonical rows, got ${noncanon.calibration.everApplied}`);

  // -- data quality --
  const dq = analyze({ trackerContent: waitTracker, logContent: LOG_FIXTURE, benchmarks: bm, states, todayStr: TODAY }).dataQuality;
  check(dq.orphans.length >= 1 && dq.orphans.includes(99), 'dataQuality: orphan #99 surfaced');
  check(dq.unparseable.length === 3, 'dataQuality: unparseable lines surfaced');
  check(dq.newestObservation === '2026-06-30', `dataQuality: newest observation, got ${dq.newestObservation}`);
  const dqSummary = renderSummary(analyze({ trackerContent: waitTracker, logContent: LOG_FIXTURE, benchmarks: bm, states, todayStr: TODAY }), TODAY);
  check(dqSummary.includes('velocity data for'), 'summary: coverage line present');
  check(dqSummary.includes('still waiting, excluded'), 'summary: censoring surfaced next to velocity');

  // -- interview→offer day benchmark wiring --
  const ioLog = [
    '1\t2026-05-01\tResponded\tInterview\tset-status\t',
    '1\t2026-05-22\tInterview\tOffer\tset-status\t',
    '2\t2026-05-01\tResponded\tInterview\tset-status\t',
    '2\t2026-05-26\tInterview\tOffer\tset-status\t',
    '3\t2026-05-01\tResponded\tInterview\tset-status\t',
    '3\t2026-05-31\tInterview\tOffer\tset-status\t',
  ].join('\n');
  const ioResult = analyze({ trackerContent: waitTracker, logContent: ioLog, benchmarks: bm, states, todayStr: TODAY });
  check(ioResult.velocity.interviewToOffer.benchmark?.rangeDays?.[0] === 20, 'io-benchmark: days_interview_to_offer attached to the hop');
  check(ioResult.velocity.interviewToOffer.n === 3 && ioResult.velocity.interviewToOffer.median === 25, `io-benchmark: [21,25,30] → median 25, got ${ioResult.velocity.interviewToOffer.median}`);
  const ioSummary = renderSummary(ioResult, TODAY);
  check(ioSummary.includes('vs 20–28d typical (2019, directional)'), 'io-benchmark: summary carries the benchmark with year + directional');
  check(!renderSummary(analyze({ trackerContent: waitTracker, logContent: '', benchmarks: bm, states, todayStr: TODAY }), TODAY).includes('20–28d typical'), 'io-benchmark: no benchmark context without a median (claims stay gated)');
  // n=1 I→O hop → insufficientData, median null → benchmark must not leak into JSON output
  const ioInsufficient = analyze({ trackerContent: waitTracker, logContent: LOG_FIXTURE, benchmarks: bm, states, todayStr: TODAY });
  check(ioInsufficient.velocity.interviewToOffer.insufficientData === true && !('benchmark' in ioInsufficient.velocity.interviewToOffer), 'io-benchmark: not attached when median is null (JSON output stays gated)');

  // -- missing year in a user-override benchmark file must render n/a, not null --
  const bmNoYear = JSON.parse(JSON.stringify(bm));
  delete bmNoYear.response_rate.year;
  delete bmNoYear.application_to_interview.year;
  delete bmNoYear.days_interview_to_offer.year;
  const noYearSummary = renderSummary(analyze({ trackerContent: mkTracker(40, 0), logContent: ioLog, benchmarks: bmNoYear, states, todayStr: TODAY }), TODAY);
  check(noYearSummary.includes('(n/a, directional)'), 'no-year: renders n/a fallback');
  check(!noYearSummary.includes('null, directional'), 'no-year: never prints (null, directional)');

  // -- empty state --
  const empty = analyze({ trackerContent: '', logContent: '', benchmarks: bm, states, todayStr: TODAY });
  check(empty.calibration.everApplied === 0, 'empty: zero applied');
  const emptySummary = renderSummary(empty, TODAY);
  check(emptySummary.includes('calibration starts at your first Applied row'), 'empty: friendly zero state');
  check(emptySummary.includes('ledger is empty'), 'empty: ledger explainer');

  if (failures) { console.error(`\n${failures} self-test failure(s)`); process.exit(1); }
  console.log('funnel-velocity self-test OK (parser + fold + percentiles + velocity/censoring + benchmarks + calibration gating + waiting + tone contract)');
}

// --- Main ---
function main() {
  const args = process.argv.slice(2);
  validateFlags(args, KNOWN_FLAGS, USAGE, { valueFlags: VALUE_FLAGS, requireOperand: true });

  const summaryMode = args.includes('--summary');
  const selfTestMode = args.includes('--self-test');
  if (selfTestMode) { selfTest(); return; }

  let benchmarks;
  try {
    benchmarks = loadBenchmarks(flagValue(args, '--benchmarks')).benchmarks;
  } catch (err) {
    console.error(`Error: ${err.message}`);
    process.exit(1);
  }
  const states = loadCanonicalStates(STATES_FILE);
  const trackerPath = resolveTrackerPath(DATA_ROOT);
  const logPath = join(dirname(trackerPath), 'status-log.tsv');
  const trackerContent = existsSync(trackerPath) ? readFileSync(trackerPath, 'utf-8') : '';
  const logContent = existsSync(logPath) ? readFileSync(logPath, 'utf-8') : '';
  // LOCAL day: the UTC day is tomorrow for a west-of-Greenwich evening run, so
  // every "waiting" figure read one day high (#3070).
  const todayStr = localToday();

  if (!trackerContent) {
    if (summaryMode) console.log(`No tracker found at ${trackerPath} — nothing to calibrate yet.`);
    else console.log(JSON.stringify({ calibration: null, waiting: null, velocity: null, dataQuality: { trackerRows: 0, note: `no tracker at ${trackerPath}` } }, null, 2));
    return;
  }

  const result = analyze({ trackerContent, logContent, benchmarks, states, todayStr });
  if (summaryMode) console.log(renderSummary(result, todayStr, { followupsEnabled: loadFollowupsEnabled() }));
  else console.log(JSON.stringify({ ...result, generatedAt: todayStr }, null, 2));
}

if (isMainModule(import.meta.url)) {
  main();
}