agentlinkops 0.5.0

package/src/citations/adapter.js

@@ -0,0 +1,141 @@
+// Engine adapters: one run of one prompt against one engine identity.
+//
+// An adapter returns answer text, a normalized provider citation list, any search
+// fan-out the API exposes, token usage, and a cost estimate for the budget cap. It
+// never interprets the answer (matching does that) and never decides outcomes. The
+// Perplexity field map follows LiteLLM's normalization (MIT; used as a spec, not
+// vendored): citations live on the response object as URLs, sometimes objects.
+import { ENGINE_RATE_CARD, CITATION_LIMITS } from './contract.js';
+
+export class EngineError extends Error {
+  constructor(message, { retriable = false, cause } = {}) {
+    super(message);
+    this.name = 'EngineError';
+    this.retriable = retriable;
+    if (cause) this.cause = cause;
+  }
+}
+
+// Deterministic per (seed, prompt, runIndex): tests and dry-runs must cost $0 AND
+// reproduce exactly, or the statistics tests would be testing the RNG, not the tool.
+function mulberry32(a) {
+  return function next() {
+    a |= 0; a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const hashString = (text) => {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i += 1) { h ^= text.charCodeAt(i); h = Math.imul(h, 16777619); }
+  return h >>> 0;
+};
+
+/**
+ * The mock engine. Fixtures map prompt text to candidate citations with inclusion
+ * weights, so a panel can simulate any citation behavior — including a collapse
+ * between epochs — without a network call or a cent.
+ */
+export function createMockEngine({ seed = 'mock', fixtures = {}, costEstimateUsd = 0.002 } = {}) {
+  return {
+    identity: { engine: 'mock', provider: 'builtin', model: 'mock-1' },
+    // The nominal per-run estimate the budget cap is enforced against, checked
+    // BEFORE a call so the cap can be approached but never exceeded.
+    estimateCostUsd: () => costEstimateUsd,
+    async run({ prompt, runIndex = 0 }) {
+      const fixture = fixtures[prompt] ?? {};
+      const rng = mulberry32(hashString(`${seed}|${prompt}|${runIndex}`));
+      const candidates = fixture.citations ?? [];
+      const citations = candidates
+        .filter((c) => typeof c.weight !== 'number' || rng() < c.weight)
+        .map((c) => ({ url: c.url, title: c.title }));
+      let answer = fixture.answerText ?? `Mock answer for: ${prompt}`;
+      for (const c of citations) answer += `\nSource: ${c.url}`;
+      if (fixture.mentionText) answer += `\n${fixture.mentionText}`;
+      return {
+        engine: 'mock', provider: 'builtin', model: 'mock-1', providerModelVersion: 'mock-1.0',
+        answer, citations, fanOut: fixture.fanOut ?? [],
+        usage: { input_tokens: 40, output_tokens: 400 },
+        // The run reports its actual estimate; the engine-level value is the nominal
+        // one the budget pre-check uses, so both must come from the same dial.
+        costEstimateUsd: fixture.costEstimateUsd ?? costEstimateUsd,
+      };
+    },
+  };
+}
+
+function estimatePerplexityCost(usage) {
+  const rates = ENGINE_RATE_CARD.perplexity;
+  const input = ((usage.input_tokens ?? 0) / 1e6) * rates.inputPerMTokens;
+  const output = ((usage.output_tokens ?? 0) / 1e6) * rates.outputPerMTokens;
+  return Number((input + output + rates.perRequest).toFixed(6));
+}
+
+/**
+ * The Perplexity adapter. First live engine because Sonar's citations are native and
+ * its base tier is the cheapest per-answer surface (~$0.005-0.01). The key is read
+ * by the caller (env or fleet) and never stored or printed here.
+ */
+export function createPerplexityEngine({
+  apiKey, model = 'sonar', baseUrl = 'https://api.perplexity.ai', fetchImpl,
+} = {}) {
+  if (!apiKey || typeof apiKey !== 'string') throw new EngineError('a Perplexity API key is required');
+  const doFetch = fetchImpl ?? globalThis.fetch?.bind(globalThis);
+  if (typeof doFetch !== 'function') throw new EngineError('no fetch implementation available');
+  return {
+    identity: { engine: 'perplexity', provider: 'api', model },
+    // Nominal per-run estimate for the pre-call cap check (search fee plus a
+    // conservative token assumption); the post-run estimate uses actual usage.
+    estimateCostUsd: () => Number((ENGINE_RATE_CARD.perplexity.perRequest
+      + (800 / 1e6) * ENGINE_RATE_CARD.perplexity.inputPerMTokens
+      + (600 / 1e6) * ENGINE_RATE_CARD.perplexity.outputPerMTokens).toFixed(6)),
+    async run({ prompt }) {
+      let response;
+      try {
+        response = await doFetch(`${baseUrl}/chat/completions`, {
+          method: 'POST',
+          headers: { 'authorization': `Bearer ${apiKey}`, 'content-type': 'application/json' },
+          body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
+          signal: AbortSignal.timeout(CITATION_LIMITS.timeoutMs),
+        });
+      } catch (cause) {
+        throw new EngineError(`perplexity request failed: ${cause.message}`, { retriable: true, cause });
+      }
+      if (!response.ok) {
+        const retriable = response.status === 429 || response.status >= 500;
+        throw new EngineError(`perplexity responded ${response.status}`, { retriable });
+      }
+      let body;
+      try { body = await response.json(); }
+      catch (cause) { throw new EngineError('perplexity response was not JSON', { cause }); }
+      const message = body?.choices?.[0]?.message;
+      const answer = typeof message?.content === 'string' ? message.content : '';
+      if (answer.length === 0) throw new EngineError('perplexity returned an empty answer');
+      if (answer.length > CITATION_LIMITS.answerBytes) {
+        throw new EngineError('perplexity answer exceeded the size limit');
+      }
+      // LiteLLM's map: citations are URL strings, or objects carrying a url/link.
+      const citations = (body?.citations ?? message?.citations ?? [])
+        .map((c) => (typeof c === 'string' ? { url: c } : { url: c?.url ?? c?.link, title: c?.title }))
+        .filter((c) => typeof c.url === 'string' && c.url.length > 0);
+      const usage = {
+        input_tokens: body?.usage?.prompt_tokens ?? 0,
+        output_tokens: body?.usage?.completion_tokens ?? 0,
+      };
+      return {
+        engine: 'perplexity', provider: 'api', model,
+        providerModelVersion: body?.model ?? model,
+        answer, citations, fanOut: [],
+        usage,
+        costEstimateUsd: estimatePerplexityCost(usage),
+      };
+    },
+  };
+}
+
+export function createEngine(spec, options = {}) {
+  if (spec.engine === 'mock') return createMockEngine(options.mock ?? {});
+  if (spec.engine === 'perplexity') return createPerplexityEngine({ model: spec.model ?? 'sonar', ...(options.perplexity ?? {}) });
+  throw new EngineError(`unknown engine: ${spec.engine}`);
+}

package/src/citations/contract.js

@@ -0,0 +1,171 @@
+// The citation contract: one AI citation treated as one placement.
+//
+// A link is placed by an editor and stays until an editor removes it. A citation is
+// re-decided by a model on every ask, so the observable is a rate, not a presence —
+// and the 2026 measurement research (IQRush, arXiv 2603.08924) says single readings
+// are mostly noise (run-to-run citation-set Jaccard 0.29-0.50). Every rule in this
+// file exists to keep that fact structural: fixed-n epochs, honest denominators,
+// intervals instead of scores, and an explicit refusal to interpret thin data.
+//
+// Internal v1 contract only. No route, queue or hosted surface is activated by this
+// module; the hosted port (DP-0033) must not weaken anything stated here.
+import { z } from 'zod';
+import { validatePublicUrl } from '../verifier/url.js';
+
+export const CITATIONS_VERSION = 1;
+
+// Outcome tiers, weakest to strongest. `unknown` is NOT the bottom of a scale: it is
+// excluded from every denominator, exactly as a blocked fetch is never a lost link.
+// `verified` means we re-fetched the cited URL ourselves; we never take the engine's
+// word for its citations (potato's rule, adopted 2026-09-16).
+export const CITATION_OUTCOMES = Object.freeze(['verified', 'cited', 'mentioned', 'not_cited', 'unknown']);
+const OUTCOME_RANK = Object.freeze({ verified: 4, cited: 3, mentioned: 2, not_cited: 1, unknown: 0 });
+export const outcomeRank = (outcome) => OUTCOME_RANK[outcome] ?? 0;
+
+// Domain scope is the default because URL-level matching is strictly more volatile
+// (IQRush). URL scope is an explicit precision mode and its intervals are read with
+// that caveat attached.
+export const CITATION_TARGET_SCOPES = Object.freeze(['domain', 'url']);
+
+// Engines this version knows. `mock` costs nothing, is deterministic per seed, and
+// exists so every test and every dry-run proves the pipeline without spending money.
+export const CITATION_ENGINES = Object.freeze(['mock', 'perplexity']);
+
+// Token rates used ONLY for the pre-call budget estimate. These are not bills; they
+// are the numbers the hard maxUsd cap is enforced against, so they are deliberately
+// conservative (rounded up where uncertain). Update with a version bump when prices
+// move.
+export const ENGINE_RATE_CARD = Object.freeze({
+  mock: Object.freeze({ inputPerMTokens: 0, outputPerMTokens: 0, perRequest: 0, currency: 'USD' }),
+  perplexity: Object.freeze({ inputPerMTokens: 1.0, outputPerMTokens: 1.0, perRequest: 0.005, currency: 'USD' }),
+});
+
+export const CITATION_LIMITS = Object.freeze({
+  answerBytes: 256 * 1024,
+  timeoutMs: 45_000,
+  // Below this the tool refuses to interpret, whatever the numbers look like.
+  minSamplesForInterpretation: 10,
+  maxCiWidth: 0.5,
+  defaultSamples: 30,
+  shareGradeSamples: 100,
+  defaultMaxUsd: 5.0,
+  // Courtesy pacing between runs against the same engine identity. The hosted port
+  // owns real fairness; locally this only keeps one panel from hammering an API key.
+  delayMs: 250,
+});
+
+const httpsUrl = z.string().refine((value) => {
+  try { return validatePublicUrl(value); } catch { return false; }
+}, { message: 'a public https URL is required' });
+
+export const citationTargetSchema = z.object({
+  domain: z.string().min(3).optional(),
+  url: httpsUrl.optional(),
+  scope: z.enum(CITATION_TARGET_SCOPES).default('domain'),
+  brand: z.string().min(1),
+  aliases: z.array(z.string().min(1)).max(12).default([]),
+}).refine((t) => (t.scope === 'domain' ? typeof t.domain === 'string' : typeof t.url === 'string'), {
+  message: 'domain scope needs a domain; url scope needs a url',
+});
+
+export const citationPromptSchema = z.object({
+  id: z.string().min(1).max(80).optional(),
+  text: z.string().min(1).max(2000),
+});
+
+export const citationEngineSpecSchema = z.object({
+  engine: z.enum(CITATION_ENGINES),
+  model: z.string().min(1).max(80).optional(),
+});
+
+export const citationPanelSchema = z.object({
+  schema_version: z.literal(CITATIONS_VERSION),
+  targets: z.array(citationTargetSchema).min(1).max(50),
+  prompts: z.array(citationPromptSchema).min(1).max(500),
+  engines: z.array(citationEngineSpecSchema).min(1).max(4),
+  samples: z.number().int().min(1).max(500).optional(),
+  maxUsd: z.number().positive().max(500).optional(),
+  // Mock-engine behavior keyed by prompt text: candidate citations with inclusion
+  // weights, mentionText, fanOut, costEstimateUsd. This is how a dry run simulates a
+  // real panel (and how a test simulates a collapse) without spending anything.
+  mockFixtures: z.record(z.string(), z.any()).optional(),
+  note: z.string().max(500).optional(),
+});
+
+// The engine identity names HOW a surface was reached, because the same engine two
+// ways is two different measurements and is never averaged (limelitgeo/open's rule).
+export function engineIdentity(spec) {
+  const parts = [spec.engine, spec.engine === 'mock' ? 'builtin' : 'api'];
+  if (spec.model) parts.push(spec.model);
+  return parts.join(':');
+}
+
+export function cellId(identity, promptId, targetKey) {
+  return `${identity}|${promptId}|${targetKey}`;
+}
+
+export function targetKey(target) {
+  return target.scope === 'domain' ? `d:${target.domain.toLowerCase()}` : `u:${target.url}`;
+}
+
+// What one run leaves behind, immutably, before anyone interprets it.
+export const evidenceEnvelopeSchema = z.object({
+  schema_version: z.literal(CITATIONS_VERSION),
+  epoch_id: z.string().min(1),
+  cell_id: z.string().min(1),
+  // Two runs can land in the same millisecond; the run index is what makes their
+  // evidence snapshots distinct content-addressed objects rather than silent
+  // duplicates of each other.
+  run_index: z.number().int().nonnegative(),
+  prompt: z.string().min(1),
+  engine_identity: z.string().min(1),
+  provider_model_version: z.string().min(1),
+  answer: z.string(),
+  citations: z.array(z.object({ url: httpsUrl, title: z.string().max(500).optional() })).max(200),
+  fan_out: z.array(z.string().max(500)).max(100).default([]),
+  usage: z.object({
+    input_tokens: z.number().int().nonnegative().default(0),
+    output_tokens: z.number().int().nonnegative().default(0),
+  }),
+  cost_estimate_usd: z.number().nonnegative(),
+  at: z.string().min(1),
+});
+
+export const observationRowSchema = z.object({
+  schema_version: z.literal(CITATIONS_VERSION),
+  epoch_id: z.string().min(1),
+  cell_id: z.string().min(1),
+  run_index: z.number().int().nonnegative(),
+  outcome: z.enum(CITATION_OUTCOMES),
+  cited_urls: z.array(z.string().max(2048)).max(50).default([]),
+  verify: z.enum(['unverified', 'reachable', 'unreachable', 'unknown']).default('unverified'),
+  evidence_sha256: z.string().length(64),
+  cost_estimate_usd: z.number().nonnegative(),
+  at: z.string().min(1),
+});
+
+export const EPOCH_CLASSIFICATIONS = Object.freeze([
+  'first_epoch', 'insufficient_data', 'declined', 'grown', 'not_distinguishable',
+]);
+
+export const epochRowSchema = z.object({
+  schema_version: z.literal(CITATIONS_VERSION),
+  epoch_id: z.string().min(1),
+  cell_id: z.string().min(1),
+  k: z.number().int().nonnegative(),
+  n: z.number().int().nonnegative(),
+  unknowns: z.number().int().nonnegative(),
+  mentioned: z.number().int().nonnegative(),
+  rate: z.number().min(0).max(1),
+  ci_low: z.number().min(0).max(1),
+  ci_high: z.number().min(0).max(1),
+  classification: z.enum(EPOCH_CLASSIFICATIONS),
+  baseline: z.object({
+    epoch_id: z.string().min(1),
+    rate: z.number().min(0).max(1),
+    ci_low: z.number().min(0).max(1),
+    ci_high: z.number().min(0).max(1),
+  }).optional(),
+  spent_estimate_usd: z.number().nonnegative(),
+  at: z.string().min(1),
+});

package/src/citations/match.js

@@ -0,0 +1,120 @@
+// Target matching: did THIS run's answer reference THIS target?
+//
+// Two doors, in cost order: a citation match against the provider's citation list
+// (cheap, exact), then a word-boundary mention match against the answer text (for the
+// mentioned tier). URL normalization is deliberately conservative — the pilot's own
+// domains are simple — and carries a documented limitation: the registrable-domain
+// table below is a common-case subset of the public suffix list, not the PSL. It is
+// sufficient for owned-site panels and wrong for exotic ccTLD composites, which is
+// why hardening it (tldts or a vendored PSL) is a named task before general release.
+import { CITATION_OUTCOMES, outcomeRank } from './contract.js';
+
+const MULTI_LABEL_SUFFIXES = new Set([
+  'co.uk', 'org.uk', 'ac.uk', 'gov.uk', 'me.uk', 'net.uk',
+  'com.au', 'net.au', 'org.au', 'edu.au', 'gov.au',
+  'co.nz', 'net.nz', 'org.nz', 'govt.nz',
+  'com.br', 'com.mx', 'com.ar', 'com.co', 'com.pe', 'com.uy',
+  'co.jp', 'or.jp', 'ne.jp', 'ac.jp',
+  'co.in', 'net.in', 'org.in', 'co.za', 'com.sg', 'com.my', 'com.tr',
+  'com.cn', 'com.hk', 'com.tw', 'co.kr',
+]);
+
+export function normalizeHost(rawHost) {
+  if (typeof rawHost !== 'string') return null;
+  let host = rawHost.trim().toLowerCase().replace(/\.$/, '');
+  if (host.startsWith('www.')) host = host.slice(4);
+  return host || null;
+}
+
+/** Best-effort registrable domain. See the module comment for the PSL caveat. */
+export function registrableDomain(rawHost) {
+  const host = normalizeHost(rawHost);
+  if (!host || !host.includes('.')) return host ?? null;
+  const labels = host.split('.');
+  if (labels.length < 2) return host;
+  const lastTwo = labels.slice(-2).join('.');
+  if (MULTI_LABEL_SUFFIXES.has(lastTwo) && labels.length >= 3) return labels.slice(-3).join('.');
+  return lastTwo;
+}
+
+/** URL-scope comparison key: scheme- and query-agnostic, trailing-slash-insensitive. */
+export function urlMatchKey(rawUrl) {
+  try {
+    const url = new URL(rawUrl);
+    const host = normalizeHost(url.hostname);
+    if (!host) return null;
+    let path = url.pathname.replace(/\/+$/, '');
+    if (path === '') path = '/';
+    return `${host}${path}`;
+  } catch {
+    return null;
+  }
+}
+
+function hostOf(rawUrl) {
+  try { return normalizeHost(new URL(rawUrl).hostname); } catch { return null; }
+}
+
+/**
+ * Citation matching against a provider citation list.
+ * domain scope: registrable domains equal. url scope: normalized URL keys equal.
+ * Returns the matched citation URLs (possibly several).
+ */
+export function matchCitations(target, citations) {
+  if (!Array.isArray(citations)) return [];
+  if (target.scope === 'url') {
+    const want = urlMatchKey(target.url);
+    if (!want) return [];
+    return citations.filter((c) => urlMatchKey(c.url) === want).map((c) => c.url);
+  }
+  const wantDomain = registrableDomain(target.domain);
+  if (!wantDomain) return [];
+  const hits = [];
+  for (const c of citations) {
+    const host = hostOf(c.url);
+    if (host && registrableDomain(host) === wantDomain) hits.push(c.url);
+  }
+  return hits;
+}
+
+const escapeRe = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Word-boundary mention match. "acme" must not match "acmeshop" (mcp-geo's false
+ * positive). Unicode lookarounds instead of \b, because \b is ASCII-only and brand
+ * names are not.
+ */
+export function matchMention(target, answerText) {
+  if (typeof answerText !== 'string' || answerText.length === 0) return false;
+  const names = [target.brand, ...(target.aliases ?? [])].filter((n) => typeof n === 'string' && n.trim().length > 0);
+  for (const name of names) {
+    const re = new RegExp(`(?<![\\p{L}\\p{N}])${escapeRe(name.trim())}(?![\\p{L}\\p{N}])`, 'iu');
+    if (re.test(answerText)) return true;
+  }
+  return false;
+}
+
+/**
+ * Tier one observation for one target. Citations outrank mentions; a successful
+ * re-fetch of the cited URL upgrades cited to verified. A failed re-fetch NEVER
+ * downgrades the citation: the engine cited it, and our fetch problems are ours
+ * (verify: 'unknown'), which is the link verifier's blocked-fetch rule transplanted.
+ */
+export function classifyOutcome(target, run, verifyFetch) {
+  const citedUrls = matchCitations(target, run.citations ?? []);
+  if (citedUrls.length > 0) {
+    let outcome = 'cited';
+    let verify = 'unverified';
+    if (typeof verifyFetch === 'function') {
+      const reachable = verifyFetch(citedUrls[0]);
+      if (reachable === true) { outcome = 'verified'; verify = 'reachable'; }
+      else if (reachable === false) { verify = 'unreachable'; }
+      else { verify = 'unknown'; }
+    }
+    return { outcome, citedUrls, verify };
+  }
+  if (matchMention(target, run.answer ?? '')) return { outcome: 'mentioned', citedUrls: [], verify: 'unverified' };
+  return { outcome: 'not_cited', citedUrls: [], verify: 'unverified' };
+}
+
+export { CITATION_OUTCOMES, outcomeRank };

package/src/citations/runner.js

@@ -0,0 +1,151 @@
+// The epoch runner: a fixed-n batch over a panel, budgeted, evidenced, summarized.
+//
+// Execution order per run: check the budget, run the engine, write the immutable
+// evidence snapshot, tier the outcome, tally. The epoch size is committed before the
+// first call and never extended mid-epoch. A budget abort leaves a partial-epoch
+// receipt — never a silent overspend, never a silent shortfall — and partial tallies
+// below the interpretation minimum classify as insufficient_data, which is the point.
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { citationPanelSchema, engineIdentity, cellId, targetKey,
+  CITATIONS_VERSION, CITATION_LIMITS,
+  evidenceEnvelopeSchema, observationRowSchema, epochRowSchema } from './contract.js';
+import { classifyOutcome } from './match.js';
+import { wilsonInterval, smoothedRate, classifyEpoch, tallyOutcomes } from './stats.js';
+import { EngineError } from './adapter.js';
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+const nowIso = () => new Date().toISOString();
+
+export const CITATION_FILES = Object.freeze({
+  observations: 'citations-observations.jsonl',
+  epochs: 'citations-epochs.jsonl',
+  evidenceDir: 'citations/evidence',
+});
+
+export async function loadPanel(path) {
+  const raw = JSON.parse(await readFile(path, 'utf8'));
+  return citationPanelSchema.parse(raw);
+}
+
+async function readPriorEpochs(dir) {
+  let text = '';
+  try { text = await readFile(join(dir, CITATION_FILES.epochs), 'utf8'); } catch { return []; }
+  const rows = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try { rows.push(JSON.parse(trimmed)); } catch { /* reported by the reader, not the runner */ }
+  }
+  return rows;
+}
+
+/**
+ * Run one epoch. Options:
+ *  - engines: Map from engine identity to an adapter instance (tests pass mocks)
+ *  - dir: the ledger directory (default `.agentlinkops`)
+ *  - verifyFetch: async (url) => true | false | null — upgrades cited to verified
+ *  - now: injectable clock, for tests
+ * The runner never retries: a failed run is one unknown observation, and retry
+ * policy is a hosted concern (DP-0033) where leases exist.
+ */
+export async function runEpoch(panelInput, options = {}) {
+  const panel = citationPanelSchema.parse(panelInput);
+  const dir = options.dir ?? '.agentlinkops';
+  const now = options.now ?? new Date();
+  const samples = panel.samples ?? CITATION_LIMITS.defaultSamples;
+  const maxUsd = panel.maxUsd ?? CITATION_LIMITS.defaultMaxUsd;
+  const delayMs = options.delayMs ?? 0; // mock/tests: 0; live callers pass pacing
+
+  const epochId = `${now.toISOString().slice(0, 10)}-${sha256(JSON.stringify({ panel, at: now.toISOString() })).slice(0, 10)}`;
+  const evidenceRoot = join(dir, CITATION_FILES.evidenceDir, epochId);
+  await mkdir(evidenceRoot, { recursive: true });
+
+  const cells = [];
+  for (const engineSpec of panel.engines) {
+    const identity = engineIdentity(engineSpec);
+    const engine = options.engines?.get(identity);
+    if (!engine) throw new EngineError(`no engine instance provided for ${identity}`);
+    for (const prompt of panel.prompts) {
+      for (const target of panel.targets) {
+        cells.push({ identity, prompt, target, engine, id: cellId(identity, prompt.id ?? sha256(prompt.text).slice(0, 10), targetKey(target)) });
+      }
+    }
+  }
+
+  let spent = 0;
+  let aborted = null;
+  const observationRows = [];
+  const outcomesByCell = new Map(cells.map((c) => [c.id, []]));
+
+  outer:
+  for (const cell of cells) {
+    for (let runIndex = 0; runIndex < samples; runIndex += 1) {
+      // Budget first: the estimate is checked BEFORE the call, so the cap cannot be
+      // exceeded, only approached. The mock engine's estimate makes this testable.
+      const estimate = cell.engine.estimateCostUsd?.() ?? null;
+      if (estimate !== null && spent + estimate > maxUsd) {
+        aborted = { reason: 'budget', spent, nextEstimate: estimate, maxUsd };
+        break outer;
+      }
+      let run;
+      try {
+        run = await cell.engine.run({ prompt: cell.prompt.text, runIndex });
+      } catch (cause) {
+        if (cause instanceof EngineError && cause.retriable) {
+          outcomesByCell.get(cell.id).push('unknown');
+          continue;
+        }
+        throw cause;
+      }
+      spent += run.costEstimateUsd ?? 0;
+
+      const envelope = evidenceEnvelopeSchema.parse({
+        schema_version: CITATIONS_VERSION,
+        epoch_id: epochId, cell_id: cell.id, run_index: runIndex, prompt: cell.prompt.text,
+        engine_identity: cell.identity,
+        provider_model_version: run.providerModelVersion ?? `${run.engine}:${run.model}`,
+        answer: run.answer, citations: run.citations, fan_out: run.fanOut ?? [],
+        usage: run.usage ?? { input_tokens: 0, output_tokens: 0 },
+        cost_estimate_usd: run.costEstimateUsd ?? 0,
+        at: nowIso(),
+      });
+      const evidenceJson = JSON.stringify(envelope);
+      const digest = sha256(evidenceJson);
+      await writeFile(join(evidenceRoot, `${digest}.json`), evidenceJson, 'utf8');
+
+      const tiered = classifyOutcome(cell.target, run, options.verifyFetch ?? null);
+      outcomesByCell.get(cell.id).push(tiered.outcome);
+      observationRows.push(observationRowSchema.parse({
+        schema_version: CITATIONS_VERSION, epoch_id: epochId, cell_id: cell.id, run_index: runIndex,
+        outcome: tiered.outcome, cited_urls: tiered.citedUrls, verify: tiered.verify,
+        evidence_sha256: digest, cost_estimate_usd: run.costEstimateUsd ?? 0, at: nowIso(),
+      }));
+      if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+    }
+  }
+
+  const prior = await readPriorEpochs(dir);
+  const epochRows = [];
+  for (const cell of cells) {
+    const outcomes = outcomesByCell.get(cell.id);
+    const { k, n, unknowns, mentioned } = tallyOutcomes(outcomes);
+    const ci = wilsonInterval(k, n) ?? [0, 1];
+    const baselineRow = prior.filter((r) => r.cell_id === cell.id && r.n >= CITATION_LIMITS.minSamplesForInterpretation).at(-1);
+    const baseline = baselineRow ? { k: baselineRow.k, n: baselineRow.n } : null;
+    epochRows.push(epochRowSchema.parse({
+      schema_version: CITATIONS_VERSION, epoch_id: epochId, cell_id: cell.id,
+      k, n, unknowns, mentioned,
+      rate: smoothedRate(k, n) ?? 0, ci_low: ci[0], ci_high: ci[1],
+      classification: classifyEpoch({ k, n }, baseline, CITATION_LIMITS),
+      baseline: baselineRow ? { epoch_id: baselineRow.epoch_id, rate: baselineRow.rate, ci_low: baselineRow.ci_low, ci_high: baselineRow.ci_high } : undefined,
+      spent_estimate_usd: Number(spent.toFixed(6)), at: nowIso(),
+    }));
+  }
+
+  await writeFile(join(dir, CITATION_FILES.observations), observationRows.map((r) => JSON.stringify(r)).join('\n') + (observationRows.length ? '\n' : ''), { flag: 'a' });
+  await writeFile(join(dir, CITATION_FILES.epochs), epochRows.map((r) => JSON.stringify(r)).join('\n') + (epochRows.length ? '\n' : ''), { flag: 'a' });
+
+  return { epochId, cells: epochRows, spentEstimateUsd: Number(spent.toFixed(6)), aborted, samples, maxUsd };
+}

package/src/citations/stats.js

@@ -0,0 +1,74 @@
+// The statistics: closed-form and boring on purpose.
+//
+// Wilson intervals over fixed-n epochs. No bootstrap, no resampling, no early
+// stopping — the IQRush finding that bootstrap CIs can be non-monotone in n is why
+// the epoch size is committed before the epoch starts. Anything cleverer (confidence
+// sequences, SPRT, changepoint dating) is a v2 design decision with its own gate,
+// recorded in DP-0031's contract, and does not ship until it is validated against
+// published data.
+export const WILSON_Z = 1.959963985; // two-sided 95%
+
+/** Wilson score interval for k successes in n rendered runs. null when n is 0. */
+export function wilsonInterval(k, n, z = WILSON_Z) {
+  if (!Number.isFinite(k) || !Number.isFinite(n) || n <= 0 || k < 0 || k > n) return null;
+  const p = k / n;
+  const z2 = z * z;
+  const denom = 1 + z2 / n;
+  const center = (p + z2 / (2 * n)) / denom;
+  const half = (z * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n))) / denom;
+  return [Math.max(0, center - half), Math.min(1, center + half)];
+}
+
+/** Laplace-smoothed rate. (k+1)/(n+2) never reports 0 or 1 from finite data. */
+export function smoothedRate(k, n) {
+  if (n <= 0) return null;
+  return (k + 1) / (n + 2);
+}
+
+/**
+ * Classify one epoch against the previous epoch's baseline.
+ *
+ * declined/grown require the intervals to separate entirely; overlap is reported as
+ * not_distinguishable — the honest label, because claiming "stable" would assert
+ * knowledge the noise forbids. Thin data is refused, not interpreted.
+ */
+export function classifyEpoch(current, baseline, limits) {
+  const minN = limits?.minSamplesForInterpretation ?? 10;
+  const maxWidth = limits?.maxCiWidth ?? 0.5;
+  if (current.n < minN) return 'insufficient_data';
+  const ci = wilsonInterval(current.k, current.n);
+  if (!ci) return 'insufficient_data';
+  if (ci[1] - ci[0] > maxWidth) return 'insufficient_data';
+  if (!baseline || baseline.n < minN) return 'first_epoch';
+  const baseCi = wilsonInterval(baseline.k, baseline.n);
+  if (!baseCi) return 'first_epoch';
+  if (ci[1] < baseCi[0]) return 'declined';
+  if (ci[0] > baseCi[1]) return 'grown';
+  return 'not_distinguishable';
+}
+
+/**
+ * Tally rendered runs. Unknowns are excluded from the denominator and carried
+ * alongside, because an errored run is a missing observation, not a miss — the same
+ * honest-denominator rule the link verifier applies to blocked fetches.
+ */
+export function tallyOutcomes(outcomes) {
+  let k = 0, n = 0, unknowns = 0, mentioned = 0;
+  for (const outcome of outcomes) {
+    if (outcome === 'unknown') { unknowns += 1; continue; }
+    n += 1;
+    if (outcome === 'cited' || outcome === 'verified') k += 1;
+    if (outcome === 'mentioned') mentioned += 1;
+  }
+  return { k, n, unknowns, mentioned };
+}
+
+/**
+ * The glossary, as a function. The tool never says a citation was "removed" or
+ * "lost"; it states both rates with their intervals and sample sizes.
+ */
+export function describeChange(current, baseline) {
+  const fmt = (e) => `${e.rate.toFixed(2)} (${e.ci_low.toFixed(2)}–${e.ci_high.toFixed(2)}, n=${e.n})`;
+  if (!baseline) return `first epoch: citation rate ${fmt(current)}`;
+  return `citation rate moved from ${fmt(baseline)} to ${fmt(current)} between epochs`;
+}