agent-nuvira 3.3.13 → 3.3.15

package/dist/learning/acceptance-model.d.ts

@@ -0,0 +1,247 @@
+/**
+ * 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 type { TurnReport } from './turn-report.js';
+/** The features a fit sees. Binary by construction — measured flags, not magnitudes. */
+export declare const ACCEPTANCE_FEATURES: readonly ["verified", "unverified", "flag", "delivered"];
+export type AcceptanceFeature = (typeof ACCEPTANCE_FEATURES)[number];
+export type AcceptanceFeatures = Record<AcceptanceFeature, number>;
+/** Below this many labelled turns a fit is noise. */
+export declare const MIN_LABELS_FOR_FIT = 20;
+/** …and below this many of EITHER class it can only learn the base rate. */
+export declare const MIN_PER_CLASS = 5;
+/** One labelled turn: what the harness saw, and whether the user accepted it. */
+export interface LabelledTurn {
+    traceId?: string;
+    provider?: string;
+    model?: string;
+    at: number;
+    accepted: boolean;
+    /** Where the label came from: `cli` / `dashboard` / `derived` (see `turn-feedback.ts`). */
+    source: string;
+    features: AcceptanceFeatures;
+}
+export interface AcceptanceModel {
+    weights: number[];
+    bias: number;
+    featureNames: AcceptanceFeature[];
+    n: number;
+    positives: number;
+    negatives: number;
+    trainedAt: number;
+}
+export type AcceptanceFit = {
+    ok: true;
+    model: AcceptanceModel;
+} | {
+    ok: false;
+    reason: string;
+    n: number;
+    positives: number;
+    negatives: number;
+};
+/** Imported labels kept on disk, oldest drop first — a dataset, not an unbounded log. */
+export declare const MAX_IMPORTED_LABELS = 5000;
+/**
+ * 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 declare function importedLabelsPath(): string;
+/** Best-effort format detection: by extension, else by the first non-space character. */
+export declare function detectCorpusFormat(path: string | undefined, text: string): CorpusFormat;
+/** Parse a shipped corpus in either format into labelled turns (malformed rows dropped). */
+export declare function parseCorpusText(text: string, format: CorpusFormat): LabelledTurn[];
+/** Read the imported labels store (best-effort; a corrupt line is skipped). */
+export declare function readImportedLabels(): LabelledTurn[];
+/**
+ * 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 declare function mergeImportedLabels(incoming: LabelledTurn[]): {
+    added: number;
+    updated: number;
+    total: number;
+};
+/** Names of the honesty flags a report set, for an audit view. */
+export declare function flagNames(report: TurnReport | undefined): string[];
+/**
+ * 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 declare function featuresFromTrace(trace: {
+    turnReport?: TurnReport;
+}, delivered: boolean): AcceptanceFeatures;
+/**
+ * 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 declare function featuresFromReport(report: TurnReport | undefined): AcceptanceFeatures;
+/** How long a fitted model is reused before the corpus is re-read. */
+export declare const FIT_CACHE_TTL_MS = 60000;
+/**
+ * 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 declare function cachedAcceptanceFit(now?: number): AcceptanceFit;
+/** Drop the memoized fit, so the next read refits (a CLI refresh, and tests). */
+export declare function invalidateAcceptanceFit(): void;
+/**
+ * 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 declare function collectLabelledTurns(): LabelledTurn[];
+/** One turn's evidence and label, for auditing a single rating. */
+export interface TraceLabelExplanation {
+    traceId: string;
+    goal: string;
+    provider?: string;
+    model?: string;
+    verification?: string;
+    flags: string[];
+    delivered: boolean;
+    features: AcceptanceFeatures;
+    /** The user's label, or null when the turn is unrated. */
+    label: boolean | null;
+    source: string | null;
+    /** The fitted `P(accepted | features)` for THIS turn, or null when no model exists. */
+    probability: number | null;
+    fitReady: boolean;
+}
+/**
+ * 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 declare function explainTraceLabel(traceId: string, now?: number): TraceLabelExplanation | null;
+/** The outcome of reconciling an imported corpus against the local labels. */
+export interface MergeResult {
+    /** Rows in the incoming file. */
+    incoming: number;
+    /** Rows written to the imported store (no local label for their trace). */
+    stored: number;
+    /** Rows whose trace already carries a DIFFERENT local label. */
+    conflicts: number;
+    /** Conflicts the incoming label won (`--replace`). */
+    replaced: number;
+    /** Conflicts the local label won (the default). */
+    keptLocal: number;
+    /** Rows whose trace already carries the SAME label — nothing to reconcile. */
+    matching: number;
+    /** The imported store size after the merge. */
+    total: number;
+}
+/**
+ * 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 declare function replaceLocalLabel(traceId: string, accepted: boolean, source: string, now?: number): boolean;
+/**
+ * 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 declare function mergeLabelledCorpus(incoming: LabelledTurn[], opts?: {
+    replace?: boolean;
+    now?: number;
+}): MergeResult;
+/**
+ * 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 declare function fitLabelledTurns(rows: LabelledTurn[], now?: number): AcceptanceFit;
+/** Fit to the LIVE corpus the harness has collected (local traces + imports). */
+export declare function trainAcceptanceModel(now?: number): AcceptanceFit;
+/** `P(accepted | features)` under a fitted model. */
+export declare function predictAcceptance(model: AcceptanceModel, features: AcceptanceFeatures): number;
+/** One review surface's worth of acceptance state, so CLI and dashboard agree. */
+export interface AcceptanceSummary {
+    labelled: number;
+    accepted: number;
+    rejected: number;
+    /** Labels by provenance: `cli` / `dashboard` / `derived`. */
+    bySource: Record<string, number>;
+    byPair: Record<string, {
+        accepted: number;
+        rejected: number;
+    }>;
+    fit: AcceptanceFit;
+}
+/** The whole acceptance picture in one call — the ONE source the surfaces render. */
+export declare function acceptanceSummary(now?: number): AcceptanceSummary;
+/**
+ * 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 declare function formatAcceptanceSummary(s: AcceptanceSummary, focusPair?: string): string[];
+/** Export formats for the labelled corpus. */
+export type CorpusFormat = 'json' | 'csv';
+/** CSV column order (stable, so an offline reader can rely on it). */
+export declare const CORPUS_CSV_COLUMNS: readonly ["traceId", "provider", "model", "at", "accepted", "source", "verified", "unverified", "flag", "delivered"];
+/**
+ * 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 declare function serializeLabelledTurns(rows: LabelledTurn[], format: CorpusFormat, now?: number): string;
+/** Rated turns per `provider/model`, for the per-pair acceptance line. */
+export declare function acceptanceByPair(): Record<string, {
+    accepted: number;
+    rejected: number;
+}>;
+//# sourceMappingURL=acceptance-model.d.ts.map

package/dist/learning/acceptance-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptance-model.d.ts","sourceRoot":"","sources":["../../src/learning/acceptance-model.ts"],"names":[],"mappings":"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"}