driftproof 0.3.0

package/lib/provider.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+const { spawn } = require('child_process');
+const { withRetry, withTimeout } = require('./json');
+const { stubComplete, stubEnabled } = require('./stub');
+
+// Provider abstraction: one `complete()` call, two surfaces.
+//
+//   CLAUDE_PROVIDER=api   → Anthropic Messages API (needs ANTHROPIC_API_KEY).
+//   CLAUDE_PROVIDER=cli   → spawn `claude -p` with ANTHROPIC_API_KEY STRIPPED
+//                           from the child env, so dev runs draw on the local
+//                           subscription session credit rather than metered API
+//                           billing. This is the DEFAULT for dev.
+//
+// The surface actually used is returned so the runner can stamp it into the
+// receipt (run.surface = "api" | "claude-cli").
+
+// Short model aliases → canonical ids. Kept tiny and explicit; unknown values
+// are passed through verbatim so a full model id always works.
+const MODEL_ALIASES = {
+  haiku: 'claude-haiku-4-5-20251001',
+  sonnet: 'claude-sonnet-5',          // current Sonnet
+  'sonnet-5': 'claude-sonnet-5',
+  'sonnet-4-6': 'claude-sonnet-4-6',  // previous Sonnet point release
+  opus: 'claude-opus-4-8',
+};
+
+function resolveModel(m) {
+  return MODEL_ALIASES[m] || m;
+}
+
+function providerName() {
+  return (process.env.CLAUDE_PROVIDER || 'cli').toLowerCase();
+}
+
+// The receipt-facing label for the surface in use.
+function surfaceLabel() {
+  return providerName() === 'api' ? 'api' : 'claude-cli';
+}
+
+// Send a single-turn prompt and return { text, usage, surface }.
+// usage is { input_tokens, output_tokens } when the surface reports it (api),
+// else null (cli does not expose token counts to us).
+// `temperature` is honoured ONLY on the api surface (the Messages API exposes
+// it). On the cli surface sampling params are surface-controlled — we cannot set
+// them, so temperature is ignored there and the receipt records that fact.
+async function complete({ system, prompt, model, maxTokens = 1024, timeoutMs = 120000, temperature = undefined }) {
+  const surface = surfaceLabel();
+  // Offline stub surface: return a canned completion with zero model calls. The
+  // receipt still records the real surface label so a stub run is not mistaken
+  // for a genuine one at read time — only run.judge/generation TEXT is canned.
+  if (stubEnabled()) return { ...stubComplete({ system, prompt }), surface };
+  const runner = () => (surface === 'api'
+    ? completeApi({ system, prompt, model, maxTokens, temperature })
+    : completeCli({ system, prompt, model, timeoutMs }));
+  // A published run makes ~1000s of calls; be patient with transient
+  // throttling/cold-starts so one blip doesn't abort a multi-hour grind.
+  const out = await withRetry(() => withTimeout(runner, timeoutMs, `provider(${surface})`), { tries: 4, baseDelayMs: 3000 });
+  return { ...out, surface };
+}
+
+async function completeApi({ system, prompt, model, maxTokens, temperature }) {
+  let Anthropic;
+  try { Anthropic = require('@anthropic-ai/sdk'); }
+  catch (_e) { throw new Error('CLAUDE_PROVIDER=api requires the @anthropic-ai/sdk package (npm i @anthropic-ai/sdk)'); }
+  if (!process.env.ANTHROPIC_API_KEY) throw new Error('CLAUDE_PROVIDER=api requires ANTHROPIC_API_KEY');
+  const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+  const params = {
+    model: resolveModel(model),
+    max_tokens: maxTokens,
+    messages: [{ role: 'user', content: prompt }],
+  };
+  if (system) params.system = system;
+  if (temperature !== undefined) params.temperature = temperature;
+  const resp = await client.messages.create(params);
+  const text = (resp.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('');
+  return {
+    text,
+    usage: {
+      input_tokens: (resp.usage && resp.usage.input_tokens) || 0,
+      output_tokens: (resp.usage && resp.usage.output_tokens) || 0,
+    },
+  };
+}
+
+function completeCli({ system, prompt, model, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    // Strip ANTHROPIC_API_KEY so the CLI uses the subscription session, not the
+    // metered API key. Everything else in the env is preserved.
+    const env = { ...process.env };
+    delete env.ANTHROPIC_API_KEY;
+
+    const args = ['-p', '--model', resolveModel(model)];
+    if (system) args.push('--append-system-prompt', system);
+
+    const child = spawn('claude', args, { env, stdio: ['pipe', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    const killer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs + 5000);
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { err += d; });
+    child.on('error', (e) => {
+      clearTimeout(killer);
+      if (e.code === 'ENOENT') reject(new Error("CLAUDE_PROVIDER=cli requires the `claude` CLI on PATH. Install it or set CLAUDE_PROVIDER=api."));
+      else reject(e);
+    });
+    child.on('close', (code) => {
+      clearTimeout(killer);
+      if (code !== 0) return reject(new Error(`claude CLI exited ${code}: ${err.slice(0, 400)}`));
+      resolve({ text: out.trim(), usage: null });
+    });
+    child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}
+
+module.exports = { complete, resolveModel, surfaceLabel, providerName, MODEL_ALIASES };

package/lib/receipt.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { canonicalize, sha256 } = require('./canonical');
+const { RECEIPT_SCHEMA_VERSION } = require('../config');
+const { aggregateBands, combineUncertainty, round } = require('./stats');
+
+// Schema file per receipt version. The current schema is receipt.schema.json;
+// older versions live alongside it so v0.1 receipts still validate. The
+// validator picks the schema by the receipt's own schema_version field.
+const SCHEMA_FILES = {
+  '0.1': 'receipt.v0.1.schema.json',
+  '0.2': 'receipt.v0.2.schema.json',
+  '0.3': 'receipt.schema.json',
+};
+
+const _validators = {};
+// Lazily compile the JSON Schema validator (ajv) for a given version. Kept lazy
+// so the library can be required without ajv present (pure hashing utilities).
+function getValidator(version) {
+  const v = SCHEMA_FILES[version] ? version : RECEIPT_SCHEMA_VERSION;
+  if (_validators[v]) return _validators[v];
+  let Ajv;
+  // The schema is JSON Schema draft 2020-12, so use ajv's 2020 build.
+  try { Ajv = require('ajv/dist/2020'); }
+  catch (_e) { throw new Error('receipt validation requires the `ajv` package (npm install)'); }
+  const schema = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'spec', SCHEMA_FILES[v]), 'utf8'));
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  _validators[v] = ajv.compile(schema);
+  return _validators[v];
+}
+
+// Compute the receipt_hash: sha256 over the canonical receipt JSON with the
+// receipt_hash field itself removed. Deterministic and reproducible.
+function computeReceiptHash(receipt) {
+  const { receipt_hash, ...rest } = receipt; // eslint-disable-line no-unused-vars
+  return sha256(canonicalize(rest));
+}
+
+// Stamp (or re-stamp) the receipt_hash in place and return the receipt.
+function sealReceipt(receipt) {
+  receipt.receipt_hash = computeReceiptHash(receipt);
+  return receipt;
+}
+
+// Verify a receipt's self-hash matches its contents (tamper-evidence lite).
+function verifyReceiptHash(receipt) {
+  return receipt.receipt_hash === computeReceiptHash(receipt);
+}
+
+// Validate against the schema matching the receipt's own schema_version (so both
+// v0.1 and v0.2 receipts validate). Returns { valid, errors, version }.
+function validateReceipt(receipt) {
+  const version = (receipt && receipt.schema_version) || RECEIPT_SCHEMA_VERSION;
+  const validate = getValidator(version);
+  const valid = validate(receipt);
+  return { valid, errors: valid ? [] : (validate.errors || []), version };
+}
+
+function mean(nums) {
+  if (!nums.length) return 0;
+  return round(nums.reduce((a, b) => a + b, 0) / nums.length);
+}
+
+// Aggregate one mode's cases: mean of case means, band (suite dispersion — the
+// stddev of the per-case means; see lib/stats.aggregateBands), and pass count.
+function aggregate(caseResults) {
+  const band = aggregateBands(caseResults.map((r) => ({ mean: r.mean != null ? r.mean : r.score, stddev: r.stddev || 0, n: Array.isArray(r.samples) ? r.samples.length : 1 })));
+  const passes = caseResults.filter((r) => r.outcome === 'pass').length;
+  const borderline = caseResults.filter((r) => r.outcome === 'borderline').length;
+  return { case_count: caseResults.length, pass_count: passes, borderline_count: borderline, mean_score: band.mean, stddev: band.stddev };
+}
+
+// Assemble a full receipt from the runner's raw pieces, seal it, and return it.
+//   skill:   { name, version, contentHash }
+//   suite:   { format, suiteHash, caseCount }
+//   run:     { model_id, model_release_date, surface, runner_version, date_utc, judge, registry, transcripts }
+//   cases:   [ { id, mode, outcome, score, mean, stddev, samples, generation_hash, judge_sample_hashes, threshold, reason, judge } ]
+//   editorialReviews: optional [ { url, source, date } ]
+function buildReceipt({ skill, suite, run, cases, verificationLevel = 'TESTED', editorialReviews = null }) {
+  const withSkill = cases.filter((c) => c.mode === 'with_skill');
+  const baseline = cases.filter((c) => c.mode === 'baseline');
+  const aggWith = aggregate(withSkill);
+  const aggBase = aggregate(baseline);
+
+  const receipt = {
+    schema_version: RECEIPT_SCHEMA_VERSION,
+    skill: {
+      name: skill.name,
+      version: skill.version,
+      content_hash: skill.contentHash,
+    },
+    suite: {
+      format: suite.format,
+      suite_hash: suite.suiteHash,
+      case_count: suite.caseCount,
+    },
+    run: {
+      model_id: run.model_id,
+      model_release_date: run.model_release_date == null ? null : run.model_release_date,
+      surface: run.surface,
+      runner_version: run.runner_version,
+      date_utc: run.date_utc,
+      // v0.3: registry provenance + transcript-retention mode. Defaults keep the
+      // honest, cheapest interpretation when a caller omits them.
+      registry: run.registry || 'unregistered',
+      transcripts: run.transcripts || 'hashes-only',
+      judge: run.judge || { samples: 1, temperature: null, sampling: 'single', surface: run.surface },
+    },
+    results: {
+      cases,
+      aggregates: { with_skill: aggWith, baseline: aggBase },
+    },
+    comparison: {
+      with_skill_score: aggWith.mean_score,
+      baseline_score: aggBase.mean_score,
+      delta: round(aggWith.mean_score - aggBase.mean_score),
+      // Combined uncertainty of the delta: quadrature sum of the two aggregate
+      // bands. Diff uses this for the headline "within noise" vs real-move rule.
+      delta_uncertainty: combineUncertainty(aggWith.stddev, aggBase.stddev),
+    },
+    verification_level: verificationLevel,
+    receipt_hash: '',
+  };
+  if (editorialReviews && editorialReviews.length) receipt.editorial_reviews = editorialReviews;
+  return sealReceipt(receipt);
+}
+
+module.exports = {
+  buildReceipt, sealReceipt, computeReceiptHash, verifyReceiptHash, validateReceipt,
+};

package/lib/run.js

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+const { complete, resolveModel, surfaceLabel } = require('./provider');
+const { gradeSamples, judgeSettings } = require('./judge');
+const { buildReceipt } = require('./receipt');
+const { sha256 } = require('./canonical');
+const { registryStatus } = require('./models');
+const { perCallCostUSD } = require('./cost');
+const { RUNNER_VERSION, DEFAULT_JUDGE_SAMPLES } = require('../config');
+
+// Known model release dates (best-effort; null when unknown). Recorded into the
+// receipt so drift reports can order runs by model age. Dateless model ids
+// (the 4.6 generation onward) carry no date, so the announcement date is
+// recorded explicitly here from Anthropic's public launch posts (provenance
+// noted in the report; consistent with spec open question #4 — dates are
+// best-effort, not verified against the Models API in this run).
+const MODEL_RELEASE_DATES = {
+  'claude-haiku-4-5-20251001': '2025-10-01',
+  'claude-haiku-4-5': '2025-10-01',
+  'claude-sonnet-5': '2026-06-30',     // anthropic.com/news/claude-sonnet-5
+  'claude-sonnet-4-6': '2026-02-17',   // anthropic.com/news/claude-sonnet-4-6
+};
+
+function releaseDateFor(modelId) {
+  if (MODEL_RELEASE_DATES[modelId]) return MODEL_RELEASE_DATES[modelId];
+  // Derive from a trailing YYYYMMDD in the id if present.
+  const m = String(modelId).match(/(\d{4})(\d{2})(\d{2})$/);
+  return m ? `${m[1]}-${m[2]}-${m[3]}` : null;
+}
+
+// Calls for one model run: each case does 2 generations (with_skill + baseline)
+// and 2×samples judge calls (each generation judged `samples` times).
+function projectCalls(caseCount, samples) {
+  return caseCount * (2 + 2 * samples);
+}
+
+// Ask the target model to perform one eval case. `withSkill` decides whether the
+// SKILL.md is prepended as a system prompt (the whole point: measure the skill's
+// marginal effect vs a bare baseline).
+async function runCase({ skillMd, caseObj, model, withSkill, timeoutMs }) {
+  const system = withSkill ? skillMd : undefined;
+  const { text, usage } = await complete({ system, prompt: caseObj.prompt, model, maxTokens: 1024, timeoutMs });
+  return { text, usage };
+}
+
+// Determine a case outcome from its sampled band and threshold.
+//   borderline : threshold lies within [mean - stddev, mean + stddev]
+//   pass/fail  : mean clears / misses the threshold with the band clear of it
+//   score      : un-thresholded case (report the number, no pass/fail)
+function outcomeFor(mean, stddev, threshold) {
+  if (typeof threshold !== 'number') return 'score';
+  if (mean - stddev <= threshold && threshold <= mean + stddev) return 'borderline';
+  return mean >= threshold ? 'pass' : 'fail';
+}
+
+// Judge one generated response `samples` times → sampled case result.
+// `generationHash` binds the graded case to the exact generation text (v0.3).
+// Returns { caseResult, sampleTexts } — sampleTexts is transient (retained only
+// under --keep-transcripts; never part of the receipt).
+async function judgeCase({ caseObj, response, generationHash, judgeModel, mode, timeoutMs, samples }) {
+  const g = await gradeSamples({ task: caseObj.prompt, response, rubric: caseObj.rubric, model: judgeModel, samples, timeoutMs });
+  const outcome = outcomeFor(g.mean, g.stddev, caseObj.pass_threshold);
+  const caseResult = {
+    id: caseObj.id,
+    mode,
+    outcome,
+    score: g.mean,        // `score` == sampled mean (v0.1 readers still work)
+    mean: g.mean,
+    stddev: g.stddev,
+    samples: g.samples,
+    // v0.3 transcript auditability: hash of the graded generation + one hash per
+    // judge sample. These make a receipt checkable against retained transcripts.
+    generation_hash: generationHash,
+    judge_sample_hashes: g.sample_hashes,
+    threshold: typeof caseObj.pass_threshold === 'number' ? caseObj.pass_threshold : null,
+    reason: g.reason,
+    judge: { model_id: g.model_id, rubric_hash: g.rubric_hash },
+  };
+  return { caseResult, sampleTexts: g.sample_texts };
+}
+
+// Run up to `concurrency` async tasks at a time, preserving input order in the
+// results. Keeps the CLI grind tractable (each `claude -p` cold-start dominates
+// wall-clock, so a handful of concurrent spawns is a large speedup) without
+// unbounded fan-out.
+async function mapPool(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = new Array(Math.max(1, Math.min(concurrency, items.length))).fill(0).map(async () => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+// Run the full suite for ONE model, both modes, sampled judge-grading, and build
+// a sealed receipt. Enforces a hard call cap; every model+judge call counts.
+//
+// opts: { maxCases, maxCalls, samples, judgeModel, timeoutMs, concurrency,
+//         onProgress, budget, keepTranscripts, nowIso }
+//   budget          — optional BudgetTracker; accumulates estimated per-call
+//                     USD as the run proceeds and hard-stops at 1.25× the cap.
+//   keepTranscripts — when true, the run records transcripts:"retained-local"
+//                     and returns the raw generations + judge outputs so the
+//                     caller can write them to transcripts/<receipt-id>/.
+async function runSkillOnModel({ skill, model, opts = {} }) {
+  const modelId = resolveModel(model);
+  const judgeModel = opts.judgeModel ? resolveModel(opts.judgeModel) : modelId;
+  const timeoutMs = opts.timeoutMs || 120000;
+  const maxCalls = opts.maxCalls || 200;
+  const samples = opts.samples || DEFAULT_JUDGE_SAMPLES;
+  const concurrency = Math.max(1, opts.concurrency || 1);
+  const onProgress = opts.onProgress || (() => {});
+  const budget = opts.budget || null;
+  const keepTranscripts = !!opts.keepTranscripts;
+
+  let cases = skill.suite.cases;
+  if (opts.maxCases && cases.length > opts.maxCases) cases = cases.slice(0, opts.maxCases);
+
+  // Cost guard: project the whole run up front and refuse before spending a
+  // single call if it would blow the cap.
+  const projected = projectCalls(cases.length, samples);
+  if (projected > maxCalls) {
+    const e = new Error(`cost guard: projected ${projected} calls exceeds cap ${maxCalls} (${cases.length} cases × (2 + 2×${samples} samples)). Raise --max-calls or lower --max-cases/--samples.`);
+    e.code = 'CALL_CAP';
+    throw e;
+  }
+
+  // One task per (case, mode). Order is preserved in the receipt regardless of
+  // completion order, so receipts are deterministic under concurrency.
+  const tasks = [];
+  for (const c of cases) for (const withSkill of [true, false]) tasks.push({ c, withSkill });
+
+  let calls = 0;
+  const pairs = await mapPool(tasks, concurrency, async ({ c, withSkill }) => {
+    const mode = withSkill ? 'with_skill' : 'baseline';
+    onProgress({ case: c.id, mode, phase: 'generate' });
+    const { text } = await runCase({ skillMd: skill.skillMd, caseObj: c, model: modelId, withSkill, timeoutMs });
+    calls += 1;
+    // Live budget: count the generation call, then hard-stop if over 1.25× cap.
+    if (budget) budget.add(perCallCostUSD(modelId, withSkill ? 'gen_with_skill' : 'gen_baseline'));
+    const generationHash = sha256(String(text || ''));
+    onProgress({ case: c.id, mode, phase: 'judge', samples });
+    const { caseResult, sampleTexts } = await judgeCase({ caseObj: c, response: text, generationHash, judgeModel, mode, timeoutMs, samples });
+    calls += samples;
+    // Live budget: count all `samples` judge calls for this (case, mode).
+    if (budget) budget.add(samples * perCallCostUSD(judgeModel, 'judge'));
+    onProgress({ case: c.id, mode, phase: 'done', outcome: caseResult.outcome, score: caseResult.mean, stddev: caseResult.stddev });
+    const transcript = keepTranscripts
+      ? { id: c.id, mode, generation: String(text || ''), judge_outputs: sampleTexts }
+      : null;
+    return { caseResult, transcript };
+  });
+  const caseResults = pairs.map((p) => p.caseResult);
+  const transcripts = keepTranscripts ? pairs.map((p) => p.transcript) : null;
+
+  const receipt = buildReceipt({
+    skill: { name: skill.name, version: skill.version, contentHash: skill.contentHash },
+    suite: { format: skill.suite.format, suiteHash: skill.suite.suiteHash, caseCount: skill.suite.caseCount },
+    run: {
+      model_id: modelId,
+      model_release_date: releaseDateFor(modelId),
+      surface: surfaceLabel(),
+      runner_version: RUNNER_VERSION,
+      date_utc: opts.nowIso || new Date().toISOString(),
+      registry: registryStatus(modelId),
+      transcripts: keepTranscripts ? 'retained-local' : 'hashes-only',
+      judge: judgeSettings(samples),
+    },
+    cases: caseResults,
+    verificationLevel: 'TESTED',
+  });
+
+  return { receipt, calls, transcripts };
+}
+
+function band(mean, sd) { return `${mean.toFixed(3)} ± ${sd.toFixed(3)}`; }
+
+// Render a short human-readable markdown summary of a receipt.
+function summarizeReceipt(receipt) {
+  const L = [];
+  L.push(`# ${receipt.skill.name} — receipt summary`);
+  L.push('');
+  L.push(`- **model:** \`${receipt.run.model_id}\`${receipt.run.model_release_date ? ` (released ${receipt.run.model_release_date})` : ''}`);
+  L.push(`- **surface:** ${receipt.run.surface}`);
+  L.push(`- **run (UTC):** ${receipt.run.date_utc}`);
+  L.push(`- **runner:** v${receipt.run.runner_version}`);
+  const j = receipt.run.judge || {};
+  L.push(`- **judge:** ${j.samples || 1} samples/case, temperature ${j.temperature == null ? 'n/a (surface-controlled)' : j.temperature} (${j.sampling || 'single'})`);
+  if (receipt.run.registry) L.push(`- **registry:** ${receipt.run.registry}   **transcripts:** ${receipt.run.transcripts || 'hashes-only'}`);
+  L.push(`- **skill content_hash:** \`${receipt.skill.content_hash.slice(0, 16)}…\``);
+  L.push(`- **suite:** ${receipt.suite.case_count} cases (${receipt.suite.format})`);
+  L.push(`- **verification:** ${receipt.verification_level}`);
+  L.push(`- **receipt_hash:** \`${receipt.receipt_hash.slice(0, 16)}…\``);
+  L.push('');
+  L.push(`## Headline`);
+  L.push('');
+  const cmp = receipt.comparison;
+  const aggs = receipt.results.aggregates;
+  const sign = cmp.delta >= 0 ? '+' : '';
+  L.push(`with_skill **${band(aggs.with_skill.mean_score, aggs.with_skill.stddev)}** vs baseline **${band(aggs.baseline.mean_score, aggs.baseline.stddev)}**`);
+  L.push('');
+  L.push(`skill lift **${sign}${cmp.delta.toFixed(3)}** (combined uncertainty ± ${cmp.delta_uncertainty.toFixed(3)})`);
+  L.push('');
+  L.push(`## Per-case (mean ± stddev over ${(receipt.run.judge || {}).samples || 1} judge samples)`);
+  L.push('');
+  L.push(`| case | mode | outcome | mean ± stddev | judge reason |`);
+  L.push(`|---|---|---|---|---|`);
+  for (const c of receipt.results.cases) {
+    const flag = c.outcome === 'borderline' ? ' ⚠' : '';
+    L.push(`| \`${c.id}\` | ${c.mode} | ${c.outcome}${flag} | ${band(c.mean, c.stddev || 0)} | ${c.reason || ''} |`);
+  }
+  L.push('');
+  return L.join('\n');
+}
+
+module.exports = { runSkillOnModel, summarizeReceipt, releaseDateFor, projectCalls, outcomeFor };

package/lib/runner.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+// The run / compare / report-delta / exit-nonzero engine.
+//
+// PORTED (then fully genericized) from a private behavioral-gate spec. The
+// original drove a browser against a product and asserted product-specific
+// journeys; ALL of that (endpoints, tenant probes, chrome tokens, journeys) was
+// stripped. What remains is the reusable core:
+//   - a Gate collects named checks grouped by "section"
+//   - each check records { section, name, pass, detail }
+//   - summarize() prints a PASS/FAIL line per check and a headline count
+//   - toExitCode() gives 0 on all-pass, 1 on any failure
+// Scanned clean against the confidentiality deny-list.
+
+// A single collector for one gate run.
+class Gate {
+  constructor(title = 'gate') {
+    this.title = title;
+    this.results = [];
+    this._section = '?';
+  }
+
+  // Start a new named section; subsequent checks are grouped under it.
+  section(name) {
+    this._section = name;
+    return this;
+  }
+
+  // Record an assertion. `pass` is coerced to boolean; `detail` is any JSON-able
+  // context printed only when the check fails.
+  check(name, pass, detail = null) {
+    const rec = { section: this._section, name, pass: !!pass, detail: pass ? null : detail };
+    this.results.push(rec);
+    const tag = rec.pass ? 'PASS' : 'FAIL';
+    const suffix = rec.pass ? '' : `  -- ${safeJson(detail)}`;
+    // eslint-disable-next-line no-console
+    console.log(`  [${tag}] ${name}${suffix}`);
+    return rec.pass;
+  }
+
+  // Convenience: assert deep equality of two JSON-able values.
+  checkEqual(name, actual, expected) {
+    const pass = safeJson(actual) === safeJson(expected);
+    return this.check(name, pass, { actual, expected });
+  }
+
+  get passed() { return this.results.filter((r) => r.pass).length; }
+  get failed() { return this.results.filter((r) => !r.pass); }
+  get total() { return this.results.length; }
+
+  // Print the headline and per-failure detail. Returns the summary object.
+  summarize() {
+    const failed = this.failed;
+    // eslint-disable-next-line no-console
+    console.log(`\n=== ${this.title.toUpperCase()} RESULT: ${this.passed}/${this.total} passed, ${failed.length} failed ===`);
+    for (const f of failed) {
+      // eslint-disable-next-line no-console
+      console.log(`  FAIL [${f.section}] ${f.name}: ${safeJson(f.detail)}`);
+    }
+    return { title: this.title, total: this.total, passed: this.passed, failed: failed.length, results: this.results };
+  }
+
+  toExitCode() {
+    return this.failed.length === 0 ? 0 : 1;
+  }
+}
+
+// Compute the per-item delta between a "before" and "after" map of numeric
+// scores, keyed by id. Returns entries with { id, before, after, delta,
+// regressed } sorted worst-regression-first. This is the generic report-delta
+// primitive the drift report builds on.
+function reportDelta(beforeById, afterById, { regressionEpsilon = 0.0 } = {}) {
+  const ids = new Set([...Object.keys(beforeById || {}), ...Object.keys(afterById || {})]);
+  const rows = [];
+  for (const id of ids) {
+    const before = num(beforeById && beforeById[id]);
+    const after = num(afterById && afterById[id]);
+    const delta = (after == null || before == null) ? null : round(after - before);
+    const regressed = delta != null && delta < -regressionEpsilon;
+    rows.push({ id, before, after, delta, regressed });
+  }
+  rows.sort((a, b) => {
+    // Regressions first, then by magnitude of drop.
+    const da = a.delta == null ? 0 : a.delta;
+    const db = b.delta == null ? 0 : b.delta;
+    return da - db;
+  });
+  return rows;
+}
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : (v == null ? null : Number(v));
+}
+function round(n) { return Math.round(n * 1e6) / 1e6; }
+function safeJson(v) {
+  try { return JSON.stringify(v); } catch (_e) { return String(v); }
+}
+
+module.exports = { Gate, reportDelta };