agent-nuvira 3.3.13 → 3.3.14

package/dist/learning/acceptance-model.js

@@ -0,0 +1,708 @@
+/**
+ * Acceptance model — fit `P(accepted | features)` to the labels the harness now
+ * collects, and report it READ-ONLY.
+ *
+ * THE POINT OF THE WHOLE `userVerdict` WORK. Bundles 27–30 made it possible for a
+ * turn to carry a LABEL: the user accepted it, rejected it, or said nothing. This
+ * module is the first consumer — it fits a probability of acceptance to the
+ * harness's OWN features (did the turn verify, was it flagged, did it deliver),
+ * which is the thing a "quality score" was always supposed to be and could never
+ * be built from derived signals alone.
+ *
+ * WHAT IT REFUSES TO DO.
+ *  - It never routes on an UNMEASURED or too-thin sample. `cachedAcceptanceFit`
+ *    returns the same named refusal below the floor as `trainAcceptanceModel`, and
+ *    the one routing consumer (`outcome-observation.ts` → the bandit's
+ *    `qualityScore`) omits the field entirely unless the fit is `ok`. So a router
+ *    cannot be moved by a probability fitted to three rows — the exact defect the
+ *    programme removes. (NOTE: this file previously READ-ONLY; the user's decision
+ *    of 2026-10-08 wired the fitted probability into the bandit's measured
+ *    `qualityScore`, which is why the router now reads it. Below the floor, nothing
+ *    changes.)
+ *  - It never fits below the sample floor. With too few labelled turns, or with
+ *    only one class, it returns a NAMED reason and no model — an underfit
+ *    probability printed as if it were evidence is worse than printing nothing.
+ *  - It never invents an acceptance. Only rows with a real verdict are used;
+ *    `verdict: null` rows are excluded, because silence is not a positive.
+ *
+ * THE FEATURES are the ones the harness already records per turn, each of them
+ * evidence the run produced rather than the model's account of itself:
+ *   verified    — the turn's own check passed (`verified` / `delivered-and-read-back`)
+ *   unverified  — the turn ran but nothing verified it
+ *   flag        — an honesty flag fired (a defect the turn disclosed)
+ *   delivered   — the turn produced an authored artifact
+ *
+ * Training is deterministic (zero initial weights, fixed iterations), so the same
+ * corpus always yields the same coefficients and a report cannot drift run to run.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listTraces, recordTraceVerdict, getTrace } from './reasoning-trace.js';
+import { readDeliverableCandidates, labelDeliverableByTrace } from './deliverable-corpus.js';
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+/** The features a fit sees. Binary by construction — measured flags, not magnitudes. */
+export const ACCEPTANCE_FEATURES = ['verified', 'unverified', 'flag', 'delivered'];
+/** Below this many labelled turns a fit is noise. */
+export const MIN_LABELS_FOR_FIT = 20;
+/** …and below this many of EITHER class it can only learn the base rate. */
+export const MIN_PER_CLASS = 5;
+const LEARNING_RATE = 0.3;
+const ITERATIONS = 500;
+const L2 = 0.01;
+const emptyFeatures = () => ({ verified: 0, unverified: 0, flag: 0, delivered: 0 });
+function anyFlag(report) {
+    const f = report?.flags;
+    if (!f)
+        return false;
+    return Boolean(f.unverifiedActionClaim ||
+        f.unverifiedEdit ||
+        f.unverifiedEditClaim ||
+        f.unverifiedBuildClaim ||
+        f.undeliveredArtifact ||
+        f.unfulfilledPromise ||
+        f.noActionTaken ||
+        f.incompleteArtifactClaim ||
+        f.unverifiedFileClaim ||
+        f.artifactShortfall);
+}
+/** Imported labels kept on disk, oldest drop first — a dataset, not an unbounded log. */
+export const MAX_IMPORTED_LABELS = 5000;
+function memoryDir() {
+    return envBuff('MEMORY_DIR') || join(resolveNuviraHome(), 'memory');
+}
+/**
+ * Where an imported corpus's labels live. Kept separate from the traces because an
+ * imported row has no local trace to attach a `userVerdict` to — a fit simply READS
+ * these alongside the local labels, so a corpus collected elsewhere joins without
+ * the harness inventing a trace or rewriting one it does not own.
+ */
+export function importedLabelsPath() {
+    return join(memoryDir(), 'acceptance-labels.jsonl');
+}
+function isTruthy(v) {
+    return v === true || v === 1 || v === '1' || v === 'true';
+}
+/** One row from a shipped corpus → a `LabelledTurn`, or null when it is malformed. */
+function coerceTurn(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (!('accepted' in r) || !('at' in r))
+        return null;
+    const at = Number(r.at);
+    if (!Number.isFinite(at))
+        return null;
+    const features = emptyFeatures();
+    const featSrc = r.features && typeof r.features === 'object'
+        ? r.features
+        : r;
+    for (const f of ACCEPTANCE_FEATURES)
+        features[f] = isTruthy(featSrc[f]) ? 1 : 0;
+    return {
+        ...(typeof r.traceId === 'string' && r.traceId ? { traceId: r.traceId } : {}),
+        ...(typeof r.provider === 'string' && r.provider ? { provider: r.provider } : {}),
+        ...(typeof r.model === 'string' && r.model ? { model: r.model } : {}),
+        at,
+        accepted: isTruthy(r.accepted),
+        source: typeof r.source === 'string' && r.source ? r.source : 'imported',
+        features,
+    };
+}
+/** Quote-aware split of one CSV line (RFC-4180: doubled quotes, embedded commas). */
+function splitCsvLine(line) {
+    const out = [];
+    let cur = '';
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (line[i + 1] === '"') {
+                    cur += '"';
+                    i++;
+                }
+                else
+                    inQuotes = false;
+            }
+            else
+                cur += ch;
+        }
+        else if (ch === '"')
+            inQuotes = true;
+        else if (ch === ',') {
+            out.push(cur);
+            cur = '';
+        }
+        else
+            cur += ch;
+    }
+    out.push(cur);
+    return out;
+}
+function parseCorpusCsv(text) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    if (lines.length < 2)
+        return [];
+    const header = splitCsvLine(lines[0]).map((h) => h.trim());
+    const out = [];
+    for (let i = 1; i < lines.length; i++) {
+        const cells = splitCsvLine(lines[i]);
+        const obj = {};
+        header.forEach((h, j) => { obj[h] = cells[j]; });
+        const t = coerceTurn(obj);
+        if (t)
+            out.push(t);
+    }
+    return out;
+}
+function parseCorpusJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : parsed && typeof parsed === 'object' && Array.isArray(parsed.turns)
+            ? parsed.turns
+            : [];
+    const out = [];
+    for (const raw of rows) {
+        const t = coerceTurn(raw);
+        if (t)
+            out.push(t);
+    }
+    return out;
+}
+/** Best-effort format detection: by extension, else by the first non-space character. */
+export function detectCorpusFormat(path, text) {
+    if (path && path.toLowerCase().endsWith('.csv'))
+        return 'csv';
+    if (path && path.toLowerCase().endsWith('.json'))
+        return 'json';
+    const first = text.trimStart()[0];
+    return first === '{' || first === '[' ? 'json' : 'csv';
+}
+/** Parse a shipped corpus in either format into labelled turns (malformed rows dropped). */
+export function parseCorpusText(text, format) {
+    return format === 'csv' ? parseCorpusCsv(text) : parseCorpusJson(text);
+}
+/** Read the imported labels store (best-effort; a corrupt line is skipped). */
+export function readImportedLabels() {
+    try {
+        if (!existsSync(importedLabelsPath()))
+            return [];
+        const out = [];
+        for (const line of readFileSync(importedLabelsPath(), 'utf-8').split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const row = coerceTurn(JSON.parse(trimmed));
+                if (row)
+                    out.push(row);
+            }
+            catch {
+                // A corrupt line is skipped — a dataset store must not be a landmine.
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** Dedupe key for an imported row: its trace when it has one, else its identity. */
+function labelKey(t) {
+    return t.traceId ?? `p:${t.provider ?? ''}|m:${t.model ?? ''}|at:${t.at}|a:${t.accepted ? 1 : 0}`;
+}
+/**
+ * Merge an imported corpus into the local store, deduped by trace (or identity).
+ * Re-importing the same file is idempotent: rows already present are updated, not
+ * duplicated. Returns the counts a caller reports, and never throws.
+ */
+export function mergeImportedLabels(incoming) {
+    const byKey = new Map();
+    for (const t of readImportedLabels())
+        byKey.set(labelKey(t), t);
+    let added = 0;
+    let updated = 0;
+    for (const t of incoming) {
+        const k = labelKey(t);
+        if (byKey.has(k))
+            updated++;
+        else
+            added++;
+        byKey.set(k, t);
+    }
+    const merged = [...byKey.values()].sort((a, b) => a.at - b.at).slice(-MAX_IMPORTED_LABELS);
+    try {
+        if (!existsSync(memoryDir()))
+            mkdirSync(memoryDir(), { recursive: true });
+        writeFileSync(importedLabelsPath(), merged.map((r) => JSON.stringify(r)).join('\n') + '\n', 'utf-8');
+    }
+    catch {
+        // Best-effort — an import must never break the caller.
+    }
+    return { added, updated, total: merged.length };
+}
+/** Names of the honesty flags a report set, for an audit view. */
+export function flagNames(report) {
+    const f = report?.flags;
+    if (!f)
+        return [];
+    return Object.entries(f)
+        .filter(([, v]) => Boolean(v))
+        .map(([k]) => k);
+}
+/**
+ * The features a fit sees for ONE trace — the SAME derivation `collectLocalTurns`
+ * uses, extracted so an audit (`nuvira rate --explain`) cannot disagree with the fit.
+ */
+export function featuresFromTrace(trace, delivered) {
+    const features = emptyFeatures();
+    const verification = trace.turnReport?.verification;
+    if (verification === 'verified' || verification === 'delivered-and-read-back')
+        features.verified = 1;
+    else if (verification === 'unverified')
+        features.unverified = 1;
+    if (anyFlag(trace.turnReport))
+        features.flag = 1;
+    if (delivered)
+        features.delivered = 1;
+    return features;
+}
+/**
+ * Features for a LIVE turn, derived from its `TurnReport` the SAME way
+ * {@link featuresFromTrace} derives them for a stored one — so the score a turn
+ * gets while it runs cannot disagree with the rows the fit trained on.
+ */
+export function featuresFromReport(report) {
+    const features = emptyFeatures();
+    const verification = report?.verification;
+    if (verification === 'verified' || verification === 'delivered-and-read-back')
+        features.verified = 1;
+    else if (verification === 'unverified')
+        features.unverified = 1;
+    if (anyFlag(report))
+        features.flag = 1;
+    if (verification === 'delivered-and-read-back' || (report?.changedPaths?.length ?? 0) > 0)
+        features.delivered = 1;
+    return features;
+}
+/** How long a fitted model is reused before the corpus is re-read. */
+export const FIT_CACHE_TTL_MS = 60_000;
+let _fitCache = null;
+/**
+ * A MEMOIZED {@link trainAcceptanceModel}.
+ *
+ * WHY IT MUST BE CACHED: this is read on the live turn-outcome path, and fitting
+ * re-reads up to 1000 traces plus the corpus and runs 500 iterations. Doing that
+ * once per turn would put a synchronous fs read on every answer. The corpus only
+ * grows when a turn is rated, so a short TTL costs at most one refit per minute and
+ * cannot hide a label for longer than that.
+ */
+export function cachedAcceptanceFit(now = Date.now()) {
+    if (_fitCache && now - _fitCache.at < FIT_CACHE_TTL_MS)
+        return _fitCache.fit;
+    const fit = trainAcceptanceModel(now);
+    _fitCache = { at: now, fit };
+    return fit;
+}
+/** Drop the memoized fit, so the next read refits (a CLI refresh, and tests). */
+export function invalidateAcceptanceFit() {
+    _fitCache = null;
+}
+/**
+ * The LOCAL labels: the trace verdicts (the reliable source, carrying the
+ * features) plus any corpus rows whose verdict has no trace counterpart. Excludes
+ * imported rows — a conflict merge must compare against what THIS machine recorded.
+ */
+function collectLocalTurns() {
+    const out = [];
+    const seen = new Set();
+    let traces = [];
+    try {
+        traces = listTraces(1000);
+    }
+    catch {
+        traces = [];
+    }
+    const corpus = (() => {
+        try {
+            return readDeliverableCandidates();
+        }
+        catch {
+            return [];
+        }
+    })();
+    for (const t of traces) {
+        const v = t.userVerdict;
+        if (!v)
+            continue;
+        const verification = t.turnReport?.verification;
+        const row = corpus.find((r) => r.traceId === t.id);
+        const features = featuresFromTrace(t, Boolean(row) || verification === 'delivered-and-read-back');
+        out.push({
+            traceId: t.id,
+            ...(t.provider ? { provider: t.provider } : {}),
+            ...(t.model ? { model: t.model } : {}),
+            at: v.at,
+            accepted: v.verdict === 'accepted',
+            source: v.source,
+            features,
+        });
+        seen.add(t.id);
+    }
+    for (const row of corpus) {
+        if (row.verdict === null)
+            continue;
+        if (row.traceId && seen.has(row.traceId))
+            continue;
+        const features = emptyFeatures();
+        if (row.verification === 'verified' || row.verification === 'delivered-and-read-back')
+            features.verified = 1;
+        else if (row.verification === 'unverified')
+            features.unverified = 1;
+        features.delivered = 1;
+        out.push({
+            ...(row.traceId ? { traceId: row.traceId } : {}),
+            at: row.verdictAt ?? row.ts,
+            accepted: row.verdict === 'accepted',
+            source: 'derived',
+            features,
+        });
+    }
+    return out.sort((a, b) => a.at - b.at);
+}
+/**
+ * Collect every LABELLED turn the harness has: the local labels plus the rows
+ * imported from another corpus. A LOCAL label for the same trace wins — the local
+ * record carries the features we measured ourselves.
+ */
+export function collectLabelledTurns() {
+    const out = collectLocalTurns();
+    const seen = new Set(out.map((t) => t.traceId).filter((id) => Boolean(id)));
+    for (const imp of readImportedLabels()) {
+        if (imp.traceId && seen.has(imp.traceId))
+            continue;
+        out.push(imp);
+        if (imp.traceId)
+            seen.add(imp.traceId);
+    }
+    return out.sort((a, b) => a.at - b.at);
+}
+/**
+ * Explain ONE trace: its features, its label and — when the fit has trained — the
+ * probability the model assigns to it. The features come from the SAME
+ * `featuresFromTrace` the fit uses, so an audit cannot disagree with the model.
+ */
+export function explainTraceLabel(traceId, now = Date.now()) {
+    let trace;
+    try {
+        trace = getTrace(traceId);
+    }
+    catch {
+        trace = null;
+    }
+    if (!trace)
+        return null;
+    const row = (() => {
+        try {
+            return readDeliverableCandidates().find((r) => r.traceId === traceId);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const verification = trace.turnReport?.verification;
+    const delivered = Boolean(row) || verification === 'delivered-and-read-back';
+    const features = featuresFromTrace(trace, delivered);
+    const fit = trainAcceptanceModel(now);
+    return {
+        traceId,
+        goal: trace.goal,
+        ...(trace.provider ? { provider: trace.provider } : {}),
+        ...(trace.model ? { model: trace.model } : {}),
+        ...(verification ? { verification } : {}),
+        flags: flagNames(trace.turnReport),
+        delivered,
+        features,
+        label: trace.userVerdict ? trace.userVerdict.verdict === 'accepted' : null,
+        source: trace.userVerdict?.source ?? null,
+        probability: fit.ok ? predictAcceptance(fit.model, features) : null,
+        fitReady: fit.ok,
+    };
+}
+/**
+ * Overwrite one LOCAL label with an imported verdict (corpus row and trace). Used
+ * only by an EXPLICIT `--replace` — the default keeps the local label, because a
+ * label this machine recorded is one a person or the behaviour here produced.
+ */
+export function replaceLocalLabel(traceId, accepted, source, now = Date.now()) {
+    const verdict = accepted ? 'accepted' : 'rejected';
+    const src = source === 'cli' || source === 'dashboard' || source === 'derived' ? source : 'derived';
+    let did = false;
+    try {
+        did = recordTraceVerdict(traceId, verdict, src, now) || did;
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        did = labelDeliverableByTrace(traceId, verdict, now) || did;
+    }
+    catch {
+        // best-effort
+    }
+    return did;
+}
+/**
+ * Reconcile an incoming corpus against the LOCAL labels, explicitly.
+ *
+ * A conflict is a trace the local record already labels differently. The default
+ * KEEPS the local label (it is this machine's own measurement) and reports the
+ * count; `replace: true` lets the incoming label win. Rows with no local label are
+ * simply stored. Deduped and idempotent like {@link mergeImportedLabels}.
+ */
+export function mergeLabelledCorpus(incoming, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const localByTrace = new Map();
+    for (const t of collectLocalTurns()) {
+        if (t.traceId)
+            localByTrace.set(t.traceId, t.accepted);
+    }
+    const toStore = [];
+    let conflicts = 0;
+    let replaced = 0;
+    let keptLocal = 0;
+    let matching = 0;
+    for (const t of incoming) {
+        if (!t.traceId || !localByTrace.has(t.traceId)) {
+            toStore.push(t);
+            continue;
+        }
+        if (localByTrace.get(t.traceId) === t.accepted) {
+            matching++;
+            continue;
+        }
+        conflicts++;
+        if (opts.replace) {
+            replaceLocalLabel(t.traceId, t.accepted, t.source, now);
+            replaced++;
+        }
+        else {
+            keptLocal++;
+        }
+    }
+    const merged = mergeImportedLabels(toStore);
+    return {
+        incoming: incoming.length,
+        stored: toStore.length,
+        conflicts,
+        replaced,
+        keptLocal,
+        matching,
+        total: merged.total,
+    };
+}
+/**
+ * Fit the logistic model. Deterministic; returns a NAMED reason rather than a
+ * model whenever the sample is too thin to mean anything. Trains on an arbitrary
+ * set of rows, so the offline fitter can reuse the identical maths on an EXPORTED
+ * corpus — a shipped corpus and this machine cannot disagree.
+ */
+export function fitLabelledTurns(rows, now = Date.now()) {
+    const positives = rows.filter((r) => r.accepted).length;
+    const negatives = rows.length - positives;
+    if (rows.length < MIN_LABELS_FOR_FIT) {
+        return {
+            ok: false,
+            reason: `only ${rows.length} labelled turn(s) — need ${MIN_LABELS_FOR_FIT}`,
+            n: rows.length,
+            positives,
+            negatives,
+        };
+    }
+    if (positives < MIN_PER_CLASS || negatives < MIN_PER_CLASS) {
+        return {
+            ok: false,
+            reason: `needs ≥${MIN_PER_CLASS} of each class (have ${positives}👍/${negatives}👎)`,
+            n: rows.length,
+            positives,
+            negatives,
+        };
+    }
+    const X = rows.map((r) => ACCEPTANCE_FEATURES.map((f) => r.features[f]));
+    const y = rows.map((r) => (r.accepted ? 1 : 0));
+    const dim = ACCEPTANCE_FEATURES.length;
+    const weights = new Array(dim).fill(0);
+    let bias = 0;
+    for (let iter = 0; iter < ITERATIONS; iter++) {
+        const gradW = new Array(dim).fill(0);
+        let gradB = 0;
+        for (let i = 0; i < X.length; i++) {
+            const z = bias + X[i].reduce((s, xi, j) => s + xi * weights[j], 0);
+            const p = 1 / (1 + Math.exp(-z));
+            const err = p - y[i];
+            for (let j = 0; j < dim; j++)
+                gradW[j] += err * X[i][j];
+            gradB += err;
+        }
+        for (let j = 0; j < dim; j++) {
+            weights[j] -= LEARNING_RATE * (gradW[j] / X.length + L2 * weights[j]);
+        }
+        bias -= LEARNING_RATE * (gradB / X.length);
+    }
+    return {
+        ok: true,
+        model: {
+            weights,
+            bias,
+            featureNames: [...ACCEPTANCE_FEATURES],
+            n: rows.length,
+            positives,
+            negatives,
+            trainedAt: now,
+        },
+    };
+}
+/** Fit to the LIVE corpus the harness has collected (local traces + imports). */
+export function trainAcceptanceModel(now = Date.now()) {
+    return fitLabelledTurns(collectLabelledTurns(), now);
+}
+/** `P(accepted | features)` under a fitted model. */
+export function predictAcceptance(model, features) {
+    const z = model.bias + model.featureNames.reduce((s, f, j) => s + (features[f] ?? 0) * model.weights[j], 0);
+    return 1 / (1 + Math.exp(-z));
+}
+/** The whole acceptance picture in one call — the ONE source the surfaces render. */
+export function acceptanceSummary(now = Date.now()) {
+    const turns = collectLabelledTurns();
+    const bySource = {};
+    for (const t of turns)
+        bySource[t.source] = (bySource[t.source] ?? 0) + 1;
+    const accepted = turns.filter((t) => t.accepted).length;
+    return {
+        labelled: turns.length,
+        accepted,
+        rejected: turns.length - accepted,
+        bySource,
+        byPair: acceptanceByPair(),
+        fit: trainAcceptanceModel(now),
+    };
+}
+/**
+ * Render a summary as human lines — the SINGLE renderer every surface uses.
+ *
+ * `nuvira rate --stats`, `model explain` and any future surface call THIS, so they
+ * cannot describe the same corpus two different ways. `focusPair` (optional) lists
+ * that `provider/model` first, which is how `model explain` keeps the decision's own
+ * pair at the top without a second formatter.
+ */
+export function formatAcceptanceSummary(s, focusPair) {
+    const lines = [];
+    lines.push(`labelled turns: ${s.labelled} (👍 ${s.accepted} / 👎 ${s.rejected})`);
+    const sources = Object.entries(s.bySource);
+    lines.push(sources.length > 0
+        ? `by source: ${sources.map(([k, v]) => `${k} ${v}`).join(', ')}`
+        : 'by source: (none yet)');
+    const pairLine = (key, v) => {
+        const n = v.accepted + v.rejected;
+        return `${key}: 👍 ${v.accepted} / 👎 ${v.rejected} (${Math.round((100 * v.accepted) / n)}%, n=${n})`;
+    };
+    const pairs = Object.entries(s.byPair);
+    if (pairs.length === 0 && !focusPair) {
+        lines.push('by pair: (no rated turns yet)');
+    }
+    else {
+        lines.push('by pair:');
+        if (focusPair) {
+            const v = s.byPair[focusPair];
+            lines.push(v ? `   ${pairLine(focusPair, v)}  ←` : `   ${focusPair}: n/a (no rated turns yet)  ←`);
+        }
+        for (const [key, v] of pairs) {
+            if (key === focusPair)
+                continue;
+            lines.push(`   ${pairLine(key, v)}`);
+        }
+    }
+    if (s.fit.ok) {
+        lines.push(`fit: TRAINED — P(accepted | features) n=${s.fit.model.n} (${s.fit.model.positives}👍/${s.fit.model.negatives}👎)`);
+        for (let j = 0; j < s.fit.model.featureNames.length; j++) {
+            const w = s.fit.model.weights[j];
+            lines.push(`     ${s.fit.model.featureNames[j].padEnd(10)} ${w >= 0 ? '+' : ''}${w.toFixed(2)}`);
+        }
+        lines.push(`     ${'bias'.padEnd(10)} ${s.fit.model.bias >= 0 ? '+' : ''}${s.fit.model.bias.toFixed(2)}`);
+    }
+    else {
+        lines.push(`fit: NOT trained — ${s.fit.reason}`);
+        lines.push(`     (needs ${MIN_LABELS_FOR_FIT} labelled turns with ≥${MIN_PER_CLASS} of each class)`);
+    }
+    lines.push(s.fit.ok
+        ? 'this fit feeds the router bandit\'s qualityScore on live turns (never below the sample floor)'
+        : 'nothing routes on this until the fit clears the sample floor above');
+    return lines;
+}
+/** CSV column order (stable, so an offline reader can rely on it). */
+export const CORPUS_CSV_COLUMNS = [
+    'traceId',
+    'provider',
+    'model',
+    'at',
+    'accepted',
+    'source',
+    ...ACCEPTANCE_FEATURES,
+];
+function csvCell(v) {
+    const s = v === undefined || v === null ? '' : String(v);
+    // Quote only when needed, so a plain id stays readable and RFC-4180 holds.
+    return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+/**
+ * Serialize the labelled corpus for shipping and offline fitting — the SAME rows
+ * a fit here would read, so nothing is lost in the hand-off.
+ *
+ * JSON carries the full structure (features nested, plus provenance); CSV is the
+ * flat form for a spreadsheet, with one column per feature and `accepted` as 0/1.
+ */
+export function serializeLabelledTurns(rows, format, now = Date.now()) {
+    if (format === 'csv') {
+        const header = CORPUS_CSV_COLUMNS.join(',');
+        const lines = rows.map((r) => CORPUS_CSV_COLUMNS.map((c) => {
+            if (c === 'accepted')
+                return r.accepted ? '1' : '0';
+            if (c === 'traceId')
+                return csvCell(r.traceId);
+            if (c === 'provider')
+                return csvCell(r.provider);
+            if (c === 'model')
+                return csvCell(r.model);
+            if (c === 'at')
+                return csvCell(r.at);
+            if (c === 'source')
+                return csvCell(r.source);
+            return csvCell(r.features[c]);
+        }).join(','));
+        return `${header}\n${lines.join('\n')}${lines.length > 0 ? '\n' : ''}`;
+    }
+    return `${JSON.stringify({ version: 1, exportedAt: now, count: rows.length, turns: rows }, null, 2)}\n`;
+}
+/** Rated turns per `provider/model`, for the per-pair acceptance line. */
+export function acceptanceByPair() {
+    const out = {};
+    for (const t of collectLabelledTurns()) {
+        if (!t.provider)
+            continue;
+        const key = `${t.provider}/${t.model ?? ''}`;
+        out[key] = out[key] ?? { accepted: 0, rejected: 0 };
+        if (t.accepted)
+            out[key].accepted++;
+        else
+            out[key].rejected++;
+    }
+    return out;
+}
+//# sourceMappingURL=acceptance-model.js.map