@claude-flow/cli 3.32.3 → 3.32.5

package/dist/src/ruvector/router-calibrator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * router-calibrator.ts — Post-hoc isotonic calibration for the KRR router
+ * (ADR-149 iter 22).
+ *
+ * The bundled KRR systematically under-predicts at the low end (gap 0.45 at
+ * 0.0–0.1) and over-predicts at the high end (gap 0.15 at 0.9–1.0). Both
+ * deviations are monotone, so a piecewise-constant non-decreasing function
+ * fit via Pool-Adjacent-Violators (PAV) can correct them without retraining
+ * the KRR.
+ *
+ * USAGE
+ *
+ *   const cal = IsotonicCalibrator.fit([[0.07, 0.52], [0.55, 0.60], …]);
+ *   const corrected = cal.transform(rawKrrScore);
+ *
+ *   // Persist & reload:
+ *   writeFileSync(path, JSON.stringify(cal.toJSON()));
+ *   const loaded = IsotonicCalibrator.fromJSON(JSON.parse(readFileSync(path, 'utf8')));
+ *
+ * Pure TS — no native deps. ~25 lines of fitting logic, O(n log n) sort +
+ * O(n) PAV pass.
+ *
+ * @module router-calibrator
+ */
+export interface CalibratorBucket {
+    /** Inclusive lower bound of predicted-values pooled into this bucket. */
+    predMin: number;
+    /** Inclusive upper bound. */
+    predMax: number;
+    /** Calibrated output value (mean of observed values in the pool). */
+    calibrated: number;
+    /** Number of (pred,obs) pairs pooled. */
+    count: number;
+}
+export interface CalibratorJSON {
+    v: 1;
+    buckets: CalibratorBucket[];
+}
+export declare class IsotonicCalibrator {
+    private buckets;
+    private constructor();
+    /**
+     * Fit an isotonic regression to (predicted, observed) pairs via PAV.
+     *
+     * Result is a non-decreasing piecewise-constant function over the
+     * empirical predicted-value range, equivalent in spirit to sklearn's
+     * IsotonicRegression(increasing=True, out_of_bounds='clip').
+     */
+    static fit(pairs: Array<[number, number]>): IsotonicCalibrator;
+    /**
+     * Map a raw predicted value to its calibrated value. Uses piecewise-linear
+     * interpolation between adjacent bucket midpoints, clamped at the
+     * empirical edges (extrapolation outside the training range returns the
+     * nearest edge bucket's calibrated value).
+     */
+    transform(x: number): number;
+    /** Pure-JSON serialization — calibrator JSON is small (typically <2kB). */
+    toJSON(): CalibratorJSON;
+    static fromJSON(j: CalibratorJSON): IsotonicCalibrator;
+    /** Diagnostic — number of distinct calibration points after PAV. */
+    get bucketCount(): number;
+    /** Diagnostic — return a copy of the bucket array (read-only view). */
+    inspect(): CalibratorBucket[];
+}
+//# sourceMappingURL=router-calibrator.d.ts.map

package/dist/src/ruvector/router-calibrator.js

@@ -0,0 +1,120 @@
+/**
+ * router-calibrator.ts — Post-hoc isotonic calibration for the KRR router
+ * (ADR-149 iter 22).
+ *
+ * The bundled KRR systematically under-predicts at the low end (gap 0.45 at
+ * 0.0–0.1) and over-predicts at the high end (gap 0.15 at 0.9–1.0). Both
+ * deviations are monotone, so a piecewise-constant non-decreasing function
+ * fit via Pool-Adjacent-Violators (PAV) can correct them without retraining
+ * the KRR.
+ *
+ * USAGE
+ *
+ *   const cal = IsotonicCalibrator.fit([[0.07, 0.52], [0.55, 0.60], …]);
+ *   const corrected = cal.transform(rawKrrScore);
+ *
+ *   // Persist & reload:
+ *   writeFileSync(path, JSON.stringify(cal.toJSON()));
+ *   const loaded = IsotonicCalibrator.fromJSON(JSON.parse(readFileSync(path, 'utf8')));
+ *
+ * Pure TS — no native deps. ~25 lines of fitting logic, O(n log n) sort +
+ * O(n) PAV pass.
+ *
+ * @module router-calibrator
+ */
+export class IsotonicCalibrator {
+    buckets;
+    constructor(buckets) {
+        this.buckets = buckets;
+    }
+    /**
+     * Fit an isotonic regression to (predicted, observed) pairs via PAV.
+     *
+     * Result is a non-decreasing piecewise-constant function over the
+     * empirical predicted-value range, equivalent in spirit to sklearn's
+     * IsotonicRegression(increasing=True, out_of_bounds='clip').
+     */
+    static fit(pairs) {
+        if (pairs.length === 0)
+            return new IsotonicCalibrator([]);
+        // Sort by predicted value ascending; stable sort isn't required because
+        // ties only affect bucket boundaries (which PAV then pools anyway).
+        const sorted = [...pairs].sort((a, b) => a[0] - b[0]);
+        const pools = sorted.map(([p, o]) => ({ predMin: p, predMax: p, sumObs: o, count: 1 }));
+        // Pool-Adjacent-Violators: walk left-to-right, merge adjacent pools
+        // whose averages violate monotonicity. After merging, back up one step
+        // to check the new pool against its predecessor.
+        let i = 0;
+        while (i < pools.length - 1) {
+            const a = pools[i], b = pools[i + 1];
+            const avgA = a.sumObs / a.count;
+            const avgB = b.sumObs / b.count;
+            if (avgA > avgB) {
+                pools[i] = {
+                    predMin: a.predMin,
+                    predMax: b.predMax,
+                    sumObs: a.sumObs + b.sumObs,
+                    count: a.count + b.count,
+                };
+                pools.splice(i + 1, 1);
+                if (i > 0)
+                    i--;
+            }
+            else {
+                i++;
+            }
+        }
+        const buckets = pools.map(p => ({
+            predMin: p.predMin,
+            predMax: p.predMax,
+            calibrated: p.sumObs / p.count,
+            count: p.count,
+        }));
+        return new IsotonicCalibrator(buckets);
+    }
+    /**
+     * Map a raw predicted value to its calibrated value. Uses piecewise-linear
+     * interpolation between adjacent bucket midpoints, clamped at the
+     * empirical edges (extrapolation outside the training range returns the
+     * nearest edge bucket's calibrated value).
+     */
+    transform(x) {
+        const n = this.buckets.length;
+        if (n === 0)
+            return x; // No calibration data → pass-through.
+        if (n === 1)
+            return this.buckets[0].calibrated;
+        const mids = this.buckets.map(b => (b.predMin + b.predMax) / 2);
+        if (x <= mids[0])
+            return this.buckets[0].calibrated;
+        if (x >= mids[n - 1])
+            return this.buckets[n - 1].calibrated;
+        // Linear interpolation between two adjacent bucket midpoints. Could be
+        // binary-searched, but n is typically <30 after PAV so linear is fine.
+        for (let i = 0; i < n - 1; i++) {
+            if (x >= mids[i] && x <= mids[i + 1]) {
+                const t = (x - mids[i]) / (mids[i + 1] - mids[i]);
+                return this.buckets[i].calibrated * (1 - t) + this.buckets[i + 1].calibrated * t;
+            }
+        }
+        return x; // unreachable given the bounds above
+    }
+    /** Pure-JSON serialization — calibrator JSON is small (typically <2kB). */
+    toJSON() {
+        return { v: 1, buckets: this.buckets };
+    }
+    static fromJSON(j) {
+        if (!j || j.v !== 1)
+            throw new Error(`unsupported calibrator schema v=${j?.v}`);
+        return new IsotonicCalibrator(j.buckets);
+    }
+    /** Diagnostic — number of distinct calibration points after PAV. */
+    get bucketCount() {
+        return this.buckets.length;
+    }
+    /** Diagnostic — return a copy of the bucket array (read-only view). */
+    inspect() {
+        return this.buckets.map(b => ({ ...b }));
+    }
+}
+//# sourceMappingURL=router-calibrator.js.map

package/dist/src/ruvector/router-parallel-recorder.d.ts

@@ -0,0 +1,127 @@
+/**
+ * router-parallel-recorder.ts — Opt-in SelfEvolvingRouter parallel-logging
+ * recorder (ADR-150 Phase 2).
+ *
+ * Writes one JSON-line per PAIR of routing decisions (Thompson bandit pick
+ * + SelfEvolvingRouter pick + measured outcome) to a shared
+ * `.swarm/router-parallel.jsonl`. Designed to be matched by
+ * `plugins/ruflo-metaharness/scripts/router-parallel-analyze.mjs` which
+ * computes the 3-criteria AND-gate from ADR-150 review-round-1:
+ *
+ *   (a) qualityScore improvement > 2%
+ *   (b) usdPerDecision increase   < 1%
+ *   (c) p95 routing-decision latency increase < 5%
+ *
+ * ARCHITECTURAL CONSTRAINTS (ADR-150)
+ * -----------------------------------
+ * 1. REMOVABLE — `@metaharness/kernel` (which provides SelfEvolvingRouter)
+ *    is in optionalDependencies. This module's exports are pure-shape; the
+ *    `SerPick` carries pre-computed prediction fields. The caller is
+ *    responsible for dynamic-importing the kernel and computing the SER
+ *    pick — this module ONLY records the pair.
+ * 2. OPTIONAL — every write goes through the `CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1`
+ *    env gate. When unset (default), `recordPair()` is a no-op.
+ * 3. GRACEFUL DEGRADATION — every fs operation is try/caught at the
+ *    appendFileSync boundary. A failed write logs to stderr (gated by
+ *    DEBUG) but never throws — the routing decision continues.
+ * 4. CI GATE — the analyzer + recorder are both exercised by smoke
+ *    fixtures; no production data required for the contract to hold.
+ *
+ * SCHEMA (versioned, additive)
+ * ----------------------------
+ * One JSONL row per paired decision:
+ *   {
+ *     v: 1,
+ *     ts: ISO-8601,
+ *     task_hash: <FNV-1a-32 of task text>,
+ *     task?: <truncated to 500 chars when CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK=1>,
+ *     bandit: { pick, predictedQuality, predictedCostUsd, ... },
+ *     ser:    { pick, predictedQuality, predictedCostUsd, ... },
+ *     outcome?: { actualModel, actualQuality, actualUsd, actualLatencyMs }
+ *   }
+ *
+ * Outcomes can be filled in a separate `recordPairOutcome()` call (matched
+ * by task_hash) so the routing path doesn't have to wait for execution.
+ *
+ * @module router-parallel-recorder
+ */
+import type { ClaudeModel } from './model-router.js';
+/** Per-arm prediction for one routing decision. */
+export interface ArmPick {
+    pick: ClaudeModel;
+    predictedQuality: number;
+    predictedCostUsd: number;
+    /** Optional: backend identifier (bandit | metaharness-knn | metaharness-krr | self-evolving). */
+    backend?: string;
+}
+/** Optional outcome — filled in after execution via recordPairOutcome(). */
+export interface PairOutcome {
+    /** Whichever model actually executed (typically the bandit's pick). */
+    actualModel: ClaudeModel;
+    /** Measured quality score from the verdict ladder (0..1). */
+    actualQuality: number;
+    /** Measured spend at actualModel's prices. */
+    actualUsd: number;
+    /** Wall-clock latency from route() to response complete (ms). */
+    actualLatencyMs: number;
+}
+/** Discriminator for JSONL rows. */
+export type RowType = 'pair' | 'pair-outcome';
+/** One paired-decision row. */
+export interface PairRow {
+    v: 1;
+    type: RowType;
+    ts: string;
+    task_hash: string;
+    task?: string;
+    bandit: ArmPick;
+    ser: ArmPick;
+    outcome?: PairOutcome;
+}
+/**
+ * Record one paired routing decision. Cheap — single appendFileSync of a
+ * JSONL row. No-op when CLAUDE_FLOW_ROUTER_PARALLEL_LOG is unset (the
+ * default). Never throws.
+ *
+ * The caller dynamic-imports `@metaharness/kernel` (or any alternative
+ * predictor) and computes the SER pick BEFORE calling this. The recorder
+ * deliberately knows nothing about how either pick was computed — it just
+ * writes the pair.
+ */
+export declare function recordPair(args: {
+    task: string;
+    bandit: ArmPick;
+    ser: ArmPick;
+}): {
+    recorded: boolean;
+    taskHash: string;
+};
+/**
+ * Record the outcome of a previously-paired decision. Matched to its
+ * pair row by task_hash. Writes a separate JSONL row of type 'outcome'
+ * which the analyzer joins client-side (same pattern as the existing
+ * router-trajectory recorder).
+ *
+ * Returns the task_hash that was matched (caller can verify against
+ * what recordPair() returned).
+ */
+export declare function recordPairOutcome(args: {
+    task: string;
+    outcome: PairOutcome;
+}): {
+    recorded: boolean;
+    taskHash: string;
+};
+/**
+ * Status helper for diagnostics / smoke tests.
+ */
+export declare function parallelRecorderStatus(): {
+    enabled: boolean;
+    path: string;
+    includeTaskText: boolean;
+    taskCharLimit: number;
+    maxBytes: number;
+};
+/** @internal — test helper. */
+export declare function __resetParallelRecorderForTests(): void;
+//# sourceMappingURL=router-parallel-recorder.d.ts.map

package/dist/src/ruvector/router-parallel-recorder.js

@@ -0,0 +1,183 @@
+/**
+ * router-parallel-recorder.ts — Opt-in SelfEvolvingRouter parallel-logging
+ * recorder (ADR-150 Phase 2).
+ *
+ * Writes one JSON-line per PAIR of routing decisions (Thompson bandit pick
+ * + SelfEvolvingRouter pick + measured outcome) to a shared
+ * `.swarm/router-parallel.jsonl`. Designed to be matched by
+ * `plugins/ruflo-metaharness/scripts/router-parallel-analyze.mjs` which
+ * computes the 3-criteria AND-gate from ADR-150 review-round-1:
+ *
+ *   (a) qualityScore improvement > 2%
+ *   (b) usdPerDecision increase   < 1%
+ *   (c) p95 routing-decision latency increase < 5%
+ *
+ * ARCHITECTURAL CONSTRAINTS (ADR-150)
+ * -----------------------------------
+ * 1. REMOVABLE — `@metaharness/kernel` (which provides SelfEvolvingRouter)
+ *    is in optionalDependencies. This module's exports are pure-shape; the
+ *    `SerPick` carries pre-computed prediction fields. The caller is
+ *    responsible for dynamic-importing the kernel and computing the SER
+ *    pick — this module ONLY records the pair.
+ * 2. OPTIONAL — every write goes through the `CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1`
+ *    env gate. When unset (default), `recordPair()` is a no-op.
+ * 3. GRACEFUL DEGRADATION — every fs operation is try/caught at the
+ *    appendFileSync boundary. A failed write logs to stderr (gated by
+ *    DEBUG) but never throws — the routing decision continues.
+ * 4. CI GATE — the analyzer + recorder are both exercised by smoke
+ *    fixtures; no production data required for the contract to hold.
+ *
+ * SCHEMA (versioned, additive)
+ * ----------------------------
+ * One JSONL row per paired decision:
+ *   {
+ *     v: 1,
+ *     ts: ISO-8601,
+ *     task_hash: <FNV-1a-32 of task text>,
+ *     task?: <truncated to 500 chars when CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK=1>,
+ *     bandit: { pick, predictedQuality, predictedCostUsd, ... },
+ *     ser:    { pick, predictedQuality, predictedCostUsd, ... },
+ *     outcome?: { actualModel, actualQuality, actualUsd, actualLatencyMs }
+ *   }
+ *
+ * Outcomes can be filled in a separate `recordPairOutcome()` call (matched
+ * by task_hash) so the routing path doesn't have to wait for execution.
+ *
+ * @module router-parallel-recorder
+ */
+import { appendFileSync, mkdirSync, existsSync, statSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { taskHash } from './router-trajectory.js';
+let _cfg = null;
+function getConfig() {
+    if (_cfg !== null)
+        return _cfg;
+    _cfg = {
+        enabled: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG === '1',
+        path: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_PATH
+            ? resolvePath(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_PATH)
+            : resolvePath('.swarm', 'router-parallel.jsonl'),
+        includeTaskText: process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK === '1',
+        taskCharLimit: parseInt(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_TASK_LIMIT || '500', 10),
+        maxBytes: parseInt(process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG_MAX_BYTES || String(10 * 1024 * 1024), 10),
+    };
+    return _cfg;
+}
+function rotate(cfg) {
+    try {
+        const backup = `${cfg.path}.1`;
+        if (existsSync(backup))
+            unlinkSync(backup);
+        renameSync(cfg.path, backup);
+    }
+    catch (e) {
+        if (process.env.DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error('router-parallel: rotate failed:', e.message);
+        }
+    }
+}
+function appendRow(row) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
+        return;
+    try {
+        const dir = dirname(cfg.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        if (existsSync(cfg.path)) {
+            try {
+                const st = statSync(cfg.path);
+                if (st.size >= cfg.maxBytes)
+                    rotate(cfg);
+            }
+            catch { /* stat race is fine */ }
+        }
+        appendFileSync(cfg.path, JSON.stringify(row) + '\n');
+    }
+    catch (e) {
+        if (process.env.DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error('router-parallel: appendRow failed:', e.message);
+        }
+        // ADR-150 rule #3 — never throw, never block the routing path.
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Record one paired routing decision. Cheap — single appendFileSync of a
+ * JSONL row. No-op when CLAUDE_FLOW_ROUTER_PARALLEL_LOG is unset (the
+ * default). Never throws.
+ *
+ * The caller dynamic-imports `@metaharness/kernel` (or any alternative
+ * predictor) and computes the SER pick BEFORE calling this. The recorder
+ * deliberately knows nothing about how either pick was computed — it just
+ * writes the pair.
+ */
+export function recordPair(args) {
+    const cfg = getConfig();
+    const hash = taskHash(args.task);
+    if (!cfg.enabled)
+        return { recorded: false, taskHash: hash };
+    const row = {
+        v: 1,
+        type: 'pair',
+        ts: new Date().toISOString(),
+        task_hash: hash,
+        bandit: args.bandit,
+        ser: args.ser,
+    };
+    if (cfg.includeTaskText) {
+        row.task = args.task.length > cfg.taskCharLimit
+            ? args.task.slice(0, cfg.taskCharLimit) + '…'
+            : args.task;
+    }
+    appendRow(row);
+    return { recorded: true, taskHash: hash };
+}
+/**
+ * Record the outcome of a previously-paired decision. Matched to its
+ * pair row by task_hash. Writes a separate JSONL row of type 'outcome'
+ * which the analyzer joins client-side (same pattern as the existing
+ * router-trajectory recorder).
+ *
+ * Returns the task_hash that was matched (caller can verify against
+ * what recordPair() returned).
+ */
+export function recordPairOutcome(args) {
+    const cfg = getConfig();
+    const hash = taskHash(args.task);
+    if (!cfg.enabled)
+        return { recorded: false, taskHash: hash };
+    const row = {
+        v: 1,
+        type: 'pair-outcome',
+        ts: new Date().toISOString(),
+        task_hash: hash,
+        bandit: { pick: args.outcome.actualModel, predictedQuality: 0, predictedCostUsd: 0 },
+        ser: { pick: args.outcome.actualModel, predictedQuality: 0, predictedCostUsd: 0 },
+        outcome: args.outcome,
+    };
+    appendRow(row);
+    return { recorded: true, taskHash: hash };
+}
+/**
+ * Status helper for diagnostics / smoke tests.
+ */
+export function parallelRecorderStatus() {
+    const cfg = getConfig();
+    return {
+        enabled: cfg.enabled,
+        path: cfg.path,
+        includeTaskText: cfg.includeTaskText,
+        taskCharLimit: cfg.taskCharLimit,
+        maxBytes: cfg.maxBytes,
+    };
+}
+/** @internal — test helper. */
+export function __resetParallelRecorderForTests() {
+    _cfg = null;
+}
+//# sourceMappingURL=router-parallel-recorder.js.map

package/dist/src/ruvector/router-trajectory.d.ts

@@ -0,0 +1,194 @@
+/**
+ * router-trajectory.ts — Opt-in DRACO-shaped trajectory recorder for the
+ * cost-optimal model router (ADR-148, phase 5).
+ *
+ * Writes one JSON-line per routing decision and one per outcome to a
+ * shared `.swarm/model-router-trajectories.jsonl`. Outcome rows are
+ * matched to their decision via `task_hash` (FNV-1a-32 of the task text).
+ *
+ * Gated behind `CLAUDE_FLOW_ROUTER_TRAJECTORY=1`. Default: **off** — rows
+ * carry full task text + raw embeddings, which is a PII/retention surface
+ * we do not enable without explicit consent.
+ *
+ * Schema is versioned (`"v": 1`). New required fields bump the version;
+ * additive optional fields do not.
+ *
+ * COMPANION: run-transcript-recorder.ts (weight-eft capture path)
+ * --------------------------------------------------------------
+ * This recorder captures the routing DECISION only (task, embedding, scalar
+ * quality, tokens, cost) — enough to retrain the router. It deliberately does
+ * NOT carry the full message transcript, the produced patch, or a resolved
+ * boolean. `@metaharness/weight-eft` needs those to build SFT/DPO training
+ * rows, so a SEPARATE opt-in recorder — `run-transcript-recorder.ts` — captures
+ * the full run transcript to `.swarm/run-transcripts.jsonl`. Both share the
+ * `taskHash()` below as their join key, and both are off-by-default for the
+ * same PII/retention reason. Use `unifiedRecorderStatus()` (bottom of this
+ * file) to inspect both at once. Keeping them as two files keeps the routing
+ * hot path free of the heavier transcript payload.
+ *
+ * @module router-trajectory
+ */
+import type { ClaudeModel } from './model-router.js';
+/** A single routing decision — written at `route()` time. */
+export interface TrajectoryDecisionRow {
+    v: 1;
+    type: 'decision';
+    ts: string;
+    task_hash: string;
+    task: string;
+    embedding?: number[];
+    complexity: number;
+    model: ClaudeModel;
+    confidence: number;
+    uncertainty: number;
+    routed_by: 'hybrid' | 'bandit-fallback' | 'heuristic';
+    /** Underlying neural backend when routed_by='hybrid', else absent. */
+    neural_backend?: 'metaharness-knn' | 'metaharness-krr' | 'fastgrnn';
+    /**
+     * A/B mode (CLAUDE_FLOW_ROUTER_AB=1) attaches both the bandit-only pick
+     * and the hybrid pick so disagreement rate is measurable over time.
+     */
+    ab_pair?: {
+        bandit_pick: ClaudeModel;
+        hybrid_pick: ClaudeModel;
+        disagree: boolean;
+    };
+    /** Execution provider hint (phase 2): 'anthropic' or 'openrouter'. */
+    provider?: 'anthropic' | 'openrouter';
+    /** Concrete OpenRouter model slug when provider=openrouter. */
+    openrouter_model?: string;
+    /**
+     * iter 46 — ensemble-disagreement diagnostic from iter 45. Absolute
+     * difference between unified KRR and bucket specialist predictions for
+     * the picked model. Set when both backends were queried (bucket
+     * specialist available + bucket supplied). Persisting per-decision lets
+     * a future tuner analyze the distribution and recommend an iter 44
+     * threshold.
+     */
+    ensemble_disagreement?: number;
+}
+/** A routing outcome — written later by the caller via `recordOutcome()`. */
+export interface TrajectoryOutcomeRow {
+    v: 1;
+    type: 'outcome';
+    ts: string;
+    task_hash: string;
+    /** 0..1 measured quality the chosen model achieved. */
+    quality: number;
+    /** Optional per-model quality if the same query was evaluated against alternates. */
+    scores?: Record<string, number>;
+    /** Free-form provenance note (e.g. "manual rating", "benchmark suite"). */
+    source?: string;
+    /**
+     * iter 31 — token usage from the underlying API response. Optional and
+     * additive: pre-iter-31 readers see undefined; iter-31+ consumers can
+     * sum these for production cost accounting. `modelId` is repeated here
+     * (also in the paired decision row) so cost computation needs only the
+     * outcome row — no JOIN required for streaming aggregation.
+     */
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    /** USD spend for this call. Computed at write time from `tokens` + the
+     *  shared price table (model-prices.ts) so consumers get a canonical
+     *  number even if prices change between write and read. */
+    cost_usd?: number;
+    /** Concrete model id the call dispatched against (iter 13+ wired this
+     *  through agent.modelId). May differ from the bandit's tier label. */
+    model_id?: string;
+}
+export type TrajectoryRow = TrajectoryDecisionRow | TrajectoryOutcomeRow;
+export declare function taskHash(task: string): string;
+/** Record one decision. Cheap — a single appendFileSync of a JSONL row. */
+export declare function recordDecision(args: {
+    task: string;
+    embedding?: number[];
+    complexity: number;
+    model: ClaudeModel;
+    confidence: number;
+    uncertainty: number;
+    routedBy: TrajectoryDecisionRow['routed_by'];
+    neuralBackend?: TrajectoryDecisionRow['neural_backend'];
+    abPair?: TrajectoryDecisionRow['ab_pair'];
+    provider?: TrajectoryDecisionRow['provider'];
+    openrouterModel?: TrajectoryDecisionRow['openrouter_model'];
+    /** iter 46 — optional ensemble disagreement diagnostic (iter 45). */
+    ensembleDisagreement?: number;
+}): void;
+/** Record one outcome. Join to a decision by `task_hash`. */
+export declare function recordTrajectoryOutcome(args: {
+    task: string;
+    quality: number;
+    scores?: Record<string, number>;
+    source?: string;
+    /** iter 31 — optional token usage from the underlying API call. */
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    /** iter 31 — concrete model id for cost computation against MODEL_PRICES. */
+    modelId?: string;
+}): void;
+/** Diagnostic for status/CLI. */
+export declare function trajectoryRecorderStatus(): {
+    enabled: boolean;
+    path: string;
+    taskCharLimit: number;
+};
+/** A training row reconstructed from one decision+outcome pair. Shape matches
+ *  the bundled seed-corpus (`seed-rows.json`) so the same train-bundled-krr.mjs
+ *  pipeline can consume it. */
+export interface PairedTrainingRow {
+    task: string;
+    embedding: number[];
+    scores: Record<string, number>;
+    tier: 'cheap' | 'mid' | 'strong';
+    /** Provenance — useful for filtering low-signal sources at training time. */
+    source: string;
+    /** ISO timestamp of the outcome row (newer rows can be weighted higher). */
+    ts: string;
+}
+/** Map decision-side complexity ∈ [0,1] back to the corpus tier label. The
+ *  buckets are deliberately the same boundaries the bandit uses so a pair
+ *  drawn from production lands in the same KRR specialist that served it. */
+export declare function tierFromComplexity(complexity: number): 'cheap' | 'mid' | 'strong';
+/** Pair decision+outcome rows by task_hash. Returns the rebuilt training rows
+ *  + diagnostics so the caller (script or test) can report what was dropped
+ *  and why. */
+export declare function pairTrajectoryRows(rows: TrajectoryRow[]): {
+    pairs: PairedTrainingRow[];
+    stats: {
+        totalRows: number;
+        decisions: number;
+        outcomes: number;
+        paired: number;
+        droppedNoEmbedding: number;
+        droppedNoMatch: number;
+        bySource: Record<string, number>;
+        byTier: Record<string, number>;
+    };
+};
+/** Test seam — reset cached config so unit tests can change env vars between cases. */
+export declare function __resetTrajectoryRecorderForTests(): void;
+/**
+ * Unified status for BOTH the routing-decision recorder (this module) and the
+ * companion run-transcript recorder (the weight-eft capture path). The
+ * run-transcript recorder is loaded dynamically so this module has no static
+ * dependency on it (the reverse edge — run-transcript-recorder → taskHash —
+ * is the only static link, keeping the import acyclic).
+ */
+export declare function unifiedRecorderStatus(): Promise<{
+    routerTrajectory: {
+        enabled: boolean;
+        path: string;
+        taskCharLimit: number;
+    };
+    runTranscripts: {
+        enabled: boolean;
+        path: string;
+    } | {
+        unavailable: true;
+    };
+}>;
+//# sourceMappingURL=router-trajectory.d.ts.map