@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/src/analytics/cache-health.js

@@ -0,0 +1,141 @@
+/**
+ * Cache health analytics: how well the prompt cache is working, and where it
+ * gets invalidated and rewritten at a premium.
+ *
+ * Two kinds of input, kept apart on purpose:
+ *
+ *  - `hitRateSeries` and `writeSplitSeries` read the pre-aggregated cube
+ *    (daily rows from `calculateDailyUsage`, e.g. `ctx.view.daily`). They work
+ *    offline, because the cube ships in every bundle and every snapshot.
+ *  - `detectChurn` and `summarize` read request-level records, one session at
+ *    a time. Records never ship in a snapshot, so churn detection is a live
+ *    dashboard feature only. See src/server/routes/cache-health.js.
+ *
+ * This module has no Node imports, so it runs the same in the browser, the
+ * CLI and a test.
+ */
+
+/** A churn event needs at least this many write tokens. */
+export const CHURN_MIN_WRITE_TOKENS = 10000;
+/** ...and at least this share of the previous turn's cache read. */
+export const CHURN_MIN_READ_SHARE = 0.5;
+
+/**
+ * Daily cache hit rate: cache_read / (cache_read + input).
+ * @param {{key?:string, date?:string, cr:number, in:number}[]} rows daily cube rows, e.g. ctx.view.daily
+ * @returns {{date:string, hitRate:number|null}[]} hitRate is null when neither field was measured that day
+ */
+export function hitRateSeries(rows) {
+  return (rows || []).map((d) => {
+    const date = d.key ?? d.date;
+    const cr = d.cr || 0;
+    const inTok = d.in || 0;
+    const denom = cr + inTok;
+    return { date, hitRate: denom > 0 ? cr / denom : null };
+  });
+}
+
+/**
+ * Daily cache write split: short-TTL writes (cache_write minus cache_refresh)
+ * versus long-TTL writes (cache_refresh). Both are real sums from the cube,
+ * so they are 0 (not null) on a day with no writes at all.
+ * @param {{key?:string, date?:string, cw:number, cf:number}[]} rows daily cube rows
+ * @returns {{date:string, shortTTL:number, longTTL:number}[]}
+ */
+export function writeSplitSeries(rows) {
+  return (rows || []).map((d) => {
+    const date = d.key ?? d.date;
+    const cw = d.cw || 0;
+    const cf = d.cf || 0;
+    return { date, shortTTL: Math.max(0, cw - cf), longTTL: cf };
+  });
+}
+
+/**
+ * Find churn events in one session's turns: a turn whose cache write is at
+ * least `CHURN_MIN_WRITE_TOKENS` and at least `CHURN_MIN_READ_SHARE` of the
+ * PREVIOUS turn's cache read, in the same session. That pattern means the
+ * cache was invalidated and rewritten, as happens when a system prompt
+ * changes mid-session.
+ *
+ * Records are sorted by timestamp internally, so callers do not have to
+ * guarantee order. A turn with a null write or a previous turn with a null
+ * read cannot be evaluated and is skipped, never treated as a zero.
+ *
+ * @param {{timestamp:string, session_id?:string|null, project?:string|null,
+ *          git_branch?:string|null, model?:string, provider?:string,
+ *          cache_read_tokens:number|null, cache_write_tokens:number|null}[]} sessionRecords
+ *   every record for one session
+ * @param {ReturnType<typeof import('../core/pricing.js').buildPriceBook>} book price book for the cost premium
+ * @returns {object[]} churn events, oldest first
+ */
+export function detectChurn(sessionRecords, book) {
+  const turns = [...(sessionRecords || [])].sort((a, b) => {
+    if (a.timestamp === b.timestamp) return 0;
+    return a.timestamp < b.timestamp ? -1 : 1;
+  });
+  const events = [];
+  for (let i = 1; i < turns.length; i++) {
+    const cur = turns[i];
+    const prev = turns[i - 1];
+    const write = cur.cache_write_tokens;
+    const prevRead = prev.cache_read_tokens;
+    if (write === null || write === undefined) continue;
+    if (prevRead === null || prevRead === undefined) continue;
+    if (write < CHURN_MIN_WRITE_TOKENS) continue;
+    if (write < CHURN_MIN_READ_SHARE * prevRead) continue;
+
+    const rates = book ? book.lookup(cur.model, cur.provider) : null;
+    const premiumUsd = rates && rates.cacheWrite !== null && rates.cacheWrite !== undefined
+      && rates.cacheRead !== null && rates.cacheRead !== undefined
+      ? (write / 1e6) * (rates.cacheWrite - rates.cacheRead)
+      : null;
+
+    events.push({
+      sessionId: cur.session_id ?? null,
+      project: cur.project ?? null,
+      branch: cur.git_branch ?? null,
+      turnIndex: i,
+      writeTokens: write,
+      previousReadTokens: prevRead,
+      model: cur.model ?? null,
+      provider: cur.provider ?? null,
+      premiumUsd,
+      timestamp: cur.timestamp ?? null,
+    });
+  }
+  return events;
+}
+
+/**
+ * Per-day event counts and the total estimated cost premium across every
+ * churn event. `totalPremiumUsd` is a real 0 when there are no events, but
+ * null (not available) when there are events and every one of them is priced
+ * with an unknown model, so the total is never a silent zero standing in for
+ * "unknown".
+ * @param {ReturnType<typeof detectChurn>} events
+ * @returns {{totalEvents:number, byDay:{date:string,count:number}[], totalPremiumUsd:number|null, premiumPartial:boolean}}
+ */
+export function summarize(events) {
+  const list = events || [];
+  const byDayMap = new Map();
+  let totalPremium = 0;
+  let premiumKnown = 0;
+  for (const e of list) {
+    const day = (e.timestamp || '').slice(0, 10);
+    if (day) byDayMap.set(day, (byDayMap.get(day) || 0) + 1);
+    if (e.premiumUsd !== null && e.premiumUsd !== undefined) {
+      totalPremium += e.premiumUsd;
+      premiumKnown++;
+    }
+  }
+  const byDay = [...byDayMap.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([date, count]) => ({ date, count }));
+  return {
+    totalEvents: list.length,
+    byDay,
+    totalPremiumUsd: list.length === 0 ? 0 : (premiumKnown > 0 ? totalPremium : null),
+    premiumPartial: list.length > 0 && premiumKnown < list.length,
+  };
+}

package/src/analytics/live-view.js

@@ -0,0 +1,266 @@
+/**
+ * Pure shaping for the Live tab's "right now" sections.
+ *
+ * `src/core/live-status.js` writes four sections into `data/status.json` every
+ * watcher cycle — `liveSessions`, `receiptsToday`, `guard`, `sparklines`. This
+ * module turns that JSON into the small display facts the view needs: a gauge
+ * ratio, a stable colour order for sparkline sources, the resolved context cap,
+ * and the labels that must not be assembled twice in two places.
+ *
+ * Nothing here touches the DOM, so it runs under `node --test` unchanged. Every
+ * label routes through `core/units.js`, the same formatters the CLI uses, with
+ * `n/a` passed for the missing case: a dash is not a number and neither is 0.
+ */
+import { compact, int, pct, relativeTime, usd } from '../core/units.js';
+
+/**
+ * Context window assumed when no `maxContextTokens` cap is declared.
+ *
+ * It is a drawing scale, not a claim about the model: the gauge needs a
+ * denominator, and 200K is the common frontier context length. `declared`
+ * comes back false so the view can say which one the reader is looking at.
+ */
+export const DEFAULT_CONTEXT_CAP = 200000;
+
+/** The five guard policy keys, in the order `live-status.js` writes them. */
+const CAP_FIELDS = [
+  { key: 'warnCostUsd', label: 'Warn at session spend', kind: 'usd' },
+  { key: 'maxCostUsd', label: 'Block at session spend', kind: 'usd' },
+  { key: 'warnContextTokens', label: 'Warn at context', kind: 'tokens' },
+  { key: 'maxContextTokens', label: 'Block at context', kind: 'tokens' },
+  { key: 'warnMarginalUsd', label: 'Warn at cost per turn', kind: 'usd' },
+];
+
+/** A positive finite number, or null. Mirrors the guard policy's own rule. */
+function positive(v) {
+  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null;
+}
+
+/** Deterministic id ordering: plain code-unit compare, never locale-dependent. */
+function compareIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * The denominator the context gauge draws against.
+ *
+ * A declared `maxContextTokens` wins, because that is the number the guard
+ * will actually block on. Otherwise the default scale, flagged as undeclared.
+ *
+ * @param {object|null|undefined} policy `status.guard.policy`
+ * @returns {{cap:number, label:string, declared:boolean}}
+ */
+export function resolveContextCap(policy) {
+  const declaredCap = positive(policy ? policy.maxContextTokens : null);
+  const cap = declaredCap ?? DEFAULT_CONTEXT_CAP;
+  return { cap, label: `of ${compact(cap, { na: 'n/a' })}`, declared: declaredCap !== null };
+}
+
+/**
+ * Fraction of `cap` that `value` fills, clamped to 0..1.
+ *
+ * Null when either side is unknown, so a gauge with no measurement draws
+ * empty and says "n/a" rather than sitting at zero as if it had measured one.
+ *
+ * @param {number|null|undefined} value
+ * @param {number|null|undefined} cap
+ * @returns {number|null}
+ */
+export function gaugeRatio(value, cap) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  const c = positive(cap);
+  if (c === null) return null;
+  return Math.max(0, Math.min(1, value / c));
+}
+
+/**
+ * Everything the context gauge shows for one session.
+ *
+ * @param {{contextTokens?:number|null, policy?:object|null}} opt
+ * @returns {{ratio:number|null, cap:number, declared:boolean, value:string,
+ *   capLabel:string, text:string, pctText:string}}
+ */
+export function contextGauge(opt) {
+  const o = opt || {};
+  const { cap, label, declared } = resolveContextCap(o.policy);
+  const tokens = typeof o.contextTokens === 'number' && Number.isFinite(o.contextTokens) ? o.contextTokens : null;
+  const ratio = gaugeRatio(tokens, cap);
+  const value = tokens === null ? 'n/a' : compact(tokens, { na: 'n/a' });
+  return {
+    ratio,
+    cap,
+    declared,
+    value,
+    capLabel: label,
+    text: tokens === null ? 'n/a' : `${value} ${label}`,
+    pctText: ratio === null ? 'n/a' : pct(ratio, 0, 'n/a'),
+  };
+}
+
+/**
+ * "3 min ago" for an `asOf` stamp, or "n/a" when there is none.
+ *
+ * `relativeTime` answers "never" for a missing timestamp, which reads as a
+ * claim about the watcher rather than about the field. An absent asOf is a
+ * missing value, so it says so the way every other missing value here does.
+ *
+ * @param {string|null|undefined} iso
+ * @param {number} [now] epoch ms, injectable for tests
+ */
+export function asOfLabel(iso, now = Date.now()) {
+  if (!iso || Number.isNaN(Date.parse(iso))) return 'n/a';
+  return relativeTime(iso, now);
+}
+
+/**
+ * Session spend, with its pricing coverage when some turns had no price.
+ *
+ * @param {{costUsd?:number|null, coverage?:number|null}} opt
+ * @returns {{text:string, coverageText:string|null, priced:boolean}}
+ */
+export function costLabel(opt) {
+  const o = opt || {};
+  const cost = typeof o.costUsd === 'number' && Number.isFinite(o.costUsd) ? o.costUsd : null;
+  const coverage = typeof o.coverage === 'number' && Number.isFinite(o.coverage) ? o.coverage : null;
+  return {
+    text: cost === null ? 'n/a' : usd(cost, 'n/a'),
+    coverageText: coverage !== null && coverage < 1 ? `priced ${pct(coverage, 0, 'n/a')} of turns` : null,
+    priced: cost !== null,
+  };
+}
+
+/**
+ * "179 turns", "1 turn", "n/a". A counted noun agrees with its count.
+ * @param {number|null|undefined} n
+ * @param {string} singular
+ */
+export function countLabel(n, singular) {
+  if (typeof n !== 'number' || !Number.isFinite(n)) return 'n/a';
+  return `${int(n, 'n/a')} ${singular}${n === 1 ? '' : 's'}`;
+}
+
+/**
+ * "260 turns, 4 by subagents". Subagents appear only when there are any.
+ * @param {{turns?:number|null, subagentTurns?:number|null}} session
+ */
+export function turnsLabel(session) {
+  const s = session || {};
+  const sub = typeof s.subagentTurns === 'number' && Number.isFinite(s.subagentTurns) ? s.subagentTurns : 0;
+  const base = countLabel(s.turns, 'turn');
+  return sub > 0 ? `${base}, ${int(sub, 'n/a')} by subagents` : base;
+}
+
+/**
+ * Where a session is working: project first, repository as the fallback.
+ * @param {object} session one entry of `status.liveSessions.sessions`
+ * @returns {{where:string, branch:string}}
+ */
+export function sessionPlace(session) {
+  const s = session || {};
+  return {
+    where: s.project || s.repository || 'n/a',
+    branch: s.branch || 'n/a',
+  };
+}
+
+/**
+ * The guard chip for one session or for the last verdict.
+ *
+ * `title` is the first reason, or null when there is none — an empty string
+ * would render an empty tooltip box on hover.
+ *
+ * @param {{level?:string, reasons?:string[]}|null|undefined} guard
+ * @returns {{level:string, text:string, title:string|null}}
+ */
+export function guardChip(guard) {
+  const g = guard || {};
+  const level = g.level === 'block' || g.level === 'warn' ? g.level : 'ok';
+  const reasons = Array.isArray(g.reasons) ? g.reasons : [];
+  return { level, text: `guard ${level}`, title: reasons.length ? reasons[0] : null };
+}
+
+/**
+ * The declared caps, in policy order. Empty when nothing is declared.
+ * @param {object|null|undefined} policy `status.guard.policy`
+ * @returns {{key:string, label:string, value:number, text:string}[]}
+ */
+export function capRows(policy) {
+  const p = policy || {};
+  const rows = [];
+  for (const f of CAP_FIELDS) {
+    const v = positive(p[f.key]);
+    if (v === null) continue;
+    rows.push({
+      key: f.key,
+      label: f.label,
+      value: v,
+      text: f.kind === 'usd' ? usd(v, 'n/a') : compact(v, { na: 'n/a' }),
+    });
+  }
+  return rows;
+}
+
+/** Sum of the finite entries of a bucket array. */
+function sumFinite(values) {
+  let t = 0;
+  for (const v of values) if (typeof v === 'number' && Number.isFinite(v)) t += v;
+  return t;
+}
+
+/**
+ * Which sparkline sources get their own chart, and which colour each keeps.
+ *
+ * Two orderings, deliberately different:
+ *
+ *  - **Selection** is by volume, because a chart per source is only worth its
+ *    space for the sources that moved tokens. Everything past `max` folds into
+ *    one summed "other" series rather than disappearing.
+ *  - **Colour** is by alphabetical position among *all* sources present, so a
+ *    source keeps its colour when a quiet day drops it out of the top five and
+ *    a busy one brings it back. `colorIndex` is null for "other", which the
+ *    view draws in the muted no-series colour.
+ *
+ * Series come back in alphabetical order with "other" last, so a series never
+ * jumps position as its numbers change.
+ *
+ * @param {{bySource?:object, max?:number}} [opt] `status.sparklines.bySource`
+ * @returns {{series:{id:string, values:number[], colorIndex:number|null,
+ *   total:number, folded?:string[]}[], folded:string[]}}
+ */
+export function orderSparkSources(opt) {
+  const o = opt || {};
+  const bySource = o.bySource && typeof o.bySource === 'object' ? o.bySource : {};
+  const max = typeof o.max === 'number' && Number.isFinite(o.max) && o.max > 0 ? Math.floor(o.max) : 5;
+
+  const keys = Object.keys(bySource).filter((k) => Array.isArray(bySource[k])).sort(compareIds);
+  const rank = new Map(keys.map((k, i) => [k, i]));
+  const totals = new Map(keys.map((k) => [k, sumFinite(bySource[k])]));
+
+  const kept = new Set(
+    keys.slice()
+      .sort((a, b) => (totals.get(b) - totals.get(a)) || compareIds(a, b))
+      .slice(0, max),
+  );
+
+  /** @type {{id:string, values:number[], colorIndex:number|null, total:number, folded?:string[]}[]} */
+  const series = keys.filter((k) => kept.has(k)).map((k) => ({
+    id: k,
+    values: bySource[k].slice(),
+    colorIndex: rank.get(k),
+    total: totals.get(k),
+  }));
+
+  const folded = keys.filter((k) => !kept.has(k));
+  if (folded.length) {
+    const width = Math.max(...folded.map((k) => bySource[k].length));
+    const values = new Array(width).fill(0);
+    for (const k of folded) {
+      bySource[k].forEach((v, i) => {
+        if (typeof v === 'number' && Number.isFinite(v)) values[i] += v;
+      });
+    }
+    series.push({ id: 'other', values, colorIndex: null, total: sumFinite(values), folded });
+  }
+
+  return { series, folded };
+}

package/src/analytics/receipt-schema.js

@@ -0,0 +1,214 @@
+/**
+ * Receipt schema v0 — a branch receipt shaped to travel with the code (as a
+ * git note) rather than live on a server. Three things live here:
+ *
+ *   toReceiptV0()            maps one buildReceipts() branch entry (the shape
+ *                             src/analytics/receipt.js produces) into the
+ *                             portable schema described by
+ *                             schemas/receipt.v0.json.
+ *   validateReceiptV0()      a small hand-written validator for that schema.
+ *                             No dependencies; kept in lockstep with the
+ *                             `required` list in schemas/receipt.v0.json —
+ *                             test/receipt-schema.test.js checks the two
+ *                             don't drift apart.
+ *   renderReceiptV0Markdown() the same PR-comment table shape as
+ *                             renderReceiptMarkdown() in receipt.js, plus an
+ *                             `<!-- tokenflow-receipt -->` marker on the first
+ *                             line so a CI comment can be found and updated.
+ *
+ * Every dollar figure here is an estimate from local token counts against a
+ * local price table — never measured billing, never a network round trip.
+ * See docs/receipt-schema.md.
+ */
+import { usd, compact, pct, shortDate } from '../core/units.js';
+
+/** The one receipt schema version this module speaks. */
+export const RECEIPT_SCHEMA_VERSION = 0;
+
+/** Fields schemas/receipt.v0.json marks `required`. Kept in sync by hand. */
+const REQUIRED_FIELDS = [
+  'schemaVersion', 'generatedAt', 'toolVersion', 'repo', 'branch', 'headSha',
+  'window', 'costUsd', 'contextShare', 'turns', 'sessions', 'subagentTurns',
+  'models', 'coverage', 'largestPromptTokens', 'changedLines', 'pr',
+  'longLived', 'costPer100Lines', 'notes',
+];
+
+/**
+ * Honesty caveats for one branch receipt, as plain sentences (no markdown).
+ * Mirrors the notes renderReceiptMarkdown() prints beside the table, minus
+ * the fields (like vsMedian and the raw prWindow) the v0 schema does not keep.
+ * @param {object} b one branch receipt from buildReceipts()
+ * @returns {string[]}
+ */
+function buildNotes(b) {
+  const notes = [];
+  const w = b.prWindow;
+  if (w && w.beforeOpened.turns > 0 && w.beforeOpened.days !== null && w.beforeOpened.days > 14) {
+    const preShare = b.cost ? (w.beforeOpened.cost ?? 0) / b.cost : null;
+    const pct100 = preShare !== null ? `${Math.round(preShare * 100)}%` : 'some';
+    notes.push(`${pct100} of the total predates the pull request by up to ${Math.round(w.beforeOpened.days)} days; on a long-lived branch that is earlier work, not this PR's.`);
+  }
+  if (b.longLived) notes.push(`"${b.key}" is a long-lived branch: this is a receipt for a period of work on it, not for one change.`);
+  if (w && w.priorPrs.count > 0) notes.push(`${w.priorPrs.count} earlier merged pull request(s) on this branch hold additional spend not counted here.`);
+  if (b.unpricedTurns > 0) notes.push(`${b.unpricedTurns} turn(s) used a model with no configured price and are excluded from costUsd.`);
+  notes.push('Estimated locally by TokenFlow from the session logs already on this machine, against a local price table — never measured billing, and no prompt or code content was read.');
+  return notes;
+}
+
+/**
+ * Map one buildReceipts()/createReceiptBuilder() branch entry into the
+ * portable receipt.v0 shape (schemas/receipt.v0.json).
+ * @param {object} b one branch receipt (an entry of `result.repos[i].branches`)
+ * @param {{repo:string, headSha:string, toolVersion:string, generatedAt?:string}} meta
+ * @returns {object} a receipt.v0 object
+ */
+export function toReceiptV0(b, meta) {
+  const hasWindow = (b.first !== null && b.first !== undefined) || (b.last !== null && b.last !== undefined);
+  return {
+    schemaVersion: RECEIPT_SCHEMA_VERSION,
+    generatedAt: meta.generatedAt || new Date().toISOString(),
+    toolVersion: meta.toolVersion,
+    repo: meta.repo,
+    branch: b.key,
+    headSha: meta.headSha,
+    window: hasWindow ? { first: b.first ?? null, last: b.last ?? null } : null,
+    costUsd: b.cost ?? null,
+    contextShare: b.contextShare ?? null,
+    turns: b.turns,
+    sessions: b.sessions,
+    subagentTurns: b.subagentTurns,
+    models: (b.models || []).map((m) => ({ model: m.model, costUsd: m.cost ?? null, share: m.share ?? null })),
+    coverage: b.coverage ?? null,
+    largestPromptTokens: b.maxPrompt ?? null,
+    changedLines: b.changedLines ?? null,
+    pr: b.pr ? { number: b.pr.number, mergedAt: b.pr.mergedAt ?? null } : null,
+    longLived: !!b.longLived,
+    costPer100Lines: b.costPer100Lines ?? null,
+    notes: buildNotes(b),
+  };
+}
+
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const isNullableNum = (v) => v === null || isNum(v);
+const isShare = (v) => v === null || (isNum(v) && v >= 0 && v <= 1);
+const isInt = (v) => Number.isInteger(v);
+const isNullableNonNegInt = (v) => v === null || (isInt(v) && v >= 0);
+const isStr = (v) => typeof v === 'string';
+
+/**
+ * Hand-written validator for the receipt.v0 shape — no dependencies, mirrors
+ * schemas/receipt.v0.json field-for-field.
+ * @param {*} obj
+ * @returns {{ok:boolean, errors:string[]}}
+ */
+export function validateReceiptV0(obj) {
+  const errors = [];
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, errors: ['receipt must be an object'] };
+  }
+  for (const key of REQUIRED_FIELDS) {
+    if (!(key in obj)) errors.push(`missing required field "${key}"`);
+  }
+
+  if ('schemaVersion' in obj && obj.schemaVersion !== RECEIPT_SCHEMA_VERSION) errors.push(`schemaVersion must be ${RECEIPT_SCHEMA_VERSION}`);
+  if ('generatedAt' in obj && !isStr(obj.generatedAt)) errors.push('generatedAt must be a string');
+  if ('toolVersion' in obj && !isStr(obj.toolVersion)) errors.push('toolVersion must be a string');
+  if ('repo' in obj && !(isStr(obj.repo) && obj.repo.length > 0)) errors.push('repo must be a non-empty string');
+  if ('branch' in obj && !(isStr(obj.branch) && obj.branch.length > 0)) errors.push('branch must be a non-empty string');
+  if ('headSha' in obj && !(isStr(obj.headSha) && /^[0-9a-f]{7,40}$/.test(obj.headSha))) errors.push('headSha must be a 7-40 char lowercase hex sha');
+
+  if ('window' in obj) {
+    const w = obj.window;
+    if (w !== null) {
+      if (typeof w !== 'object' || Array.isArray(w)) errors.push('window must be an object or null');
+      else {
+        if (!('first' in w) || !('last' in w)) errors.push('window must have "first" and "last"');
+        if ('first' in w && w.first !== null && !isStr(w.first)) errors.push('window.first must be a string or null');
+        if ('last' in w && w.last !== null && !isStr(w.last)) errors.push('window.last must be a string or null');
+      }
+    }
+  }
+
+  if ('costUsd' in obj && !isNullableNum(obj.costUsd)) errors.push('costUsd must be a number or null');
+  if ('contextShare' in obj && !isShare(obj.contextShare)) errors.push('contextShare must be null or a number between 0 and 1');
+  if ('turns' in obj && !isInt(obj.turns)) errors.push('turns must be an integer');
+  if ('sessions' in obj && !isInt(obj.sessions)) errors.push('sessions must be an integer');
+  if ('subagentTurns' in obj && !isInt(obj.subagentTurns)) errors.push('subagentTurns must be an integer');
+
+  if ('models' in obj) {
+    if (!Array.isArray(obj.models)) errors.push('models must be an array');
+    else obj.models.forEach((m, i) => {
+      if (typeof m !== 'object' || m === null || Array.isArray(m)) { errors.push(`models[${i}] must be an object`); return; }
+      if (!isStr(m.model)) errors.push(`models[${i}].model must be a string`);
+      if (!isNullableNum(m.costUsd)) errors.push(`models[${i}].costUsd must be a number or null`);
+      if (!isShare(m.share)) errors.push(`models[${i}].share must be null or a number between 0 and 1`);
+    });
+  }
+
+  if ('coverage' in obj && !isShare(obj.coverage)) errors.push('coverage must be null or a number between 0 and 1');
+  if ('largestPromptTokens' in obj && !isNullableNonNegInt(obj.largestPromptTokens)) errors.push('largestPromptTokens must be null or a non-negative integer');
+  if ('changedLines' in obj && !isNullableNonNegInt(obj.changedLines)) errors.push('changedLines must be null or a non-negative integer');
+
+  if ('pr' in obj) {
+    const pr = obj.pr;
+    if (pr !== null) {
+      if (typeof pr !== 'object' || Array.isArray(pr)) errors.push('pr must be an object or null');
+      else {
+        if (!isInt(pr.number)) errors.push('pr.number must be an integer');
+        if (!(pr.mergedAt === null || isStr(pr.mergedAt))) errors.push('pr.mergedAt must be a string or null');
+      }
+    }
+  }
+
+  if ('longLived' in obj && typeof obj.longLived !== 'boolean') errors.push('longLived must be a boolean');
+  if ('costPer100Lines' in obj && !isNullableNum(obj.costPer100Lines)) errors.push('costPer100Lines must be a number or null');
+
+  if ('notes' in obj) {
+    if (!Array.isArray(obj.notes)) errors.push('notes must be an array');
+    else obj.notes.forEach((n, i) => { if (!isStr(n)) errors.push(`notes[${i}] must be a string`); });
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+const money = (v) => (v === null || v === undefined ? '—' : usd(v));
+const share = (v) => (v === null || v === undefined ? '—' : pct(v, 0));
+
+/**
+ * A receipt.v0 object rendered for a PR comment — the same table shape as
+ * renderReceiptMarkdown() in src/analytics/receipt.js, plus a leading
+ * `<!-- tokenflow-receipt -->` marker so CI can find and update its own
+ * comment instead of piling up a new one per push.
+ * @param {object} receipt a receipt.v0 object (see toReceiptV0())
+ * @returns {string}
+ */
+export function renderReceiptV0Markdown(receipt) {
+  const L = [];
+  L.push('<!-- tokenflow-receipt -->');
+  const title = receipt.pr ? `\`${receipt.branch}\` · PR #${receipt.pr.number}` : `\`${receipt.branch}\``;
+  L.push(`### 🧾 AI cost receipt — ${title}`);
+  if (receipt.repo) L.push(`_${receipt.repo}_`);
+  L.push('');
+  L.push('| | |');
+  L.push('|---|---|');
+  const costLine = receipt.costUsd === null
+    ? '— (no priced turns)'
+    : `**${money(receipt.costUsd)}**${receipt.contextShare !== null ? ` · ${share(receipt.contextShare)} re-sent context, ${share(1 - receipt.contextShare)} fresh work` : ''}`;
+  L.push(`| Estimated spend | ${costLine} |`);
+  const subagentShare = receipt.turns > 0 ? receipt.subagentTurns / receipt.turns : null;
+  L.push(`| Sessions · turns | ${receipt.sessions} · ${receipt.turns}${subagentShare !== null && receipt.subagentTurns > 0 ? ` (${share(subagentShare)} subagent)` : ''} |`);
+  if (receipt.models.length) {
+    L.push(`| Models | ${receipt.models.slice(0, 3).map((m) => `${m.model} ${share(m.share)}`).join(', ')}${receipt.models.length > 3 ? ', …' : ''} |`);
+  }
+  if (receipt.pr && receipt.changedLines !== null) {
+    L.push(`| Changed lines | ${receipt.changedLines}${receipt.costPer100Lines !== null ? ` → ${money(receipt.costPer100Lines)} per 100 lines` : ''} |`);
+  }
+  if (receipt.largestPromptTokens !== null) L.push(`| Largest prompt | ${compact(receipt.largestPromptTokens)} tokens |`);
+  if (receipt.window && receipt.window.first && receipt.window.last) {
+    const merged = receipt.pr && receipt.pr.mergedAt ? ` (merged ${shortDate(receipt.pr.mergedAt.slice(0, 10))})` : receipt.pr ? ' (PR open)' : '';
+    L.push(`| Window | ${shortDate(receipt.window.first.slice(0, 10))} → ${shortDate(receipt.window.last.slice(0, 10))}${merged} |`);
+  }
+  L.push('');
+  L.push(`<sub>${receipt.notes.join(' ')}</sub>`);
+  return L.join('\n');
+}