@claude-flow/cli 3.10.46 → 3.12.0

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

@@ -1,69 +1,161 @@
 /**
- * Router trajectory collection (#2334 Phase 1)
+ * router-trajectory.ts — Opt-in DRACO-shaped trajectory recorder for the
+ * cost-optimal model router (ADR-148, phase 5).
  *
- * Opt-in per-decision dataset collection for the model router. The persisted
- * bandit state (`.swarm/model-router-state.json`) keeps only aggregates —
- * 9 Beta(α,β) cells and a capped/truncated history — which is not trainable
- * material for the Phase 2 FastGRNN tier-classifier. This sidecar captures
- * the per-example rows that training needs:
+ * 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).
  *
- *   decision rows: { taskHash, task, embedding?, complexity, features,
- *                    model, confidence, uncertainty, routedBy, ts }
- *   outcome rows:  { taskHash, model, outcome, ts }
+ * 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.
  *
- * joined offline on `taskHash` (sha256-16 of the task text).
- *
- * OFF by default. Enable with CLAUDE_FLOW_ROUTER_TRAJECTORY=1. Rows append to
- * `.swarm/model-router-trajectories.jsonl` — local-only, same trust domain as
- * the existing state file, but unlike it the rows contain full task text (up
- * to 500 chars) and raw embeddings, which is why this is opt-in rather than
- * always-on.
- *
- * Writes are best-effort: any fs error is swallowed (collection must never
- * break routing), matching the state-file behavior in model-router.ts.
+ * Schema is versioned (`"v": 1`). New required fields bump the version;
+ * additive optional fields do not.
  *
  * @module router-trajectory
  */
-export declare const TRAJECTORY_FILE = ".swarm/model-router-trajectories.jsonl";
-export declare function trajectoryCollectionEnabled(): boolean;
-/** Join key: first 16 hex chars of sha256(task). */
-export declare function taskHash(task: string): string;
+import type { ClaudeModel } from './model-router.js';
+/** A single routing decision — written at `route()` time. */
 export interface TrajectoryDecisionRow {
-    v: number;
+    v: 1;
     type: 'decision';
     ts: string;
-    taskHash: string;
-    /** Task text, capped at 500 chars (cf. learningHistory's 100). */
+    task_hash: string;
     task: string;
-    /** Raw embedding when one was threaded through route(); else omitted. */
     embedding?: number[];
     complexity: number;
-    features: {
-        lexicalComplexity: number;
-        semanticDepth: number;
-        taskScope: number;
-        uncertaintyLevel: number;
-    };
-    model: string;
+    model: ClaudeModel;
     confidence: number;
     uncertainty: number;
-    routedBy: string;
+    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: number;
+    v: 1;
     type: 'outcome';
     ts: string;
-    taskHash: string;
-    model: string;
-    outcome: 'success' | 'failure' | 'escalated';
+    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 declare function recordTrajectoryDecision(task: string, embedding: number[] | undefined, complexity: TrajectoryDecisionRow['features'] & {
-    score: number;
-}, decision: {
-    model: 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: string;
+    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;
-export declare function recordTrajectoryOutcome(task: string, model: string, outcome: 'success' | 'failure' | 'escalated'): 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;
 //# sourceMappingURL=router-trajectory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"router-trajectory.d.ts","sourceRoot":"","sources":["../../../src/ruvector/router-trajectory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,eAAO,MAAM,eAAe,2CAA2C,CAAC;AAKxE,wBAAgB,2BAA2B,IAAI,OAAO,CAErD;AAED,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE;QACR,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;CAC9C;AAaD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,UAAU,EAAE,qBAAqB,CAAC,UAAU,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EACjE,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrF,IAAI,CAqBN;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAC3C,IAAI,CAUN"}
+{"version":3,"file":"router-trajectory.d.ts","sourceRoot":"","sources":["../../../src/ruvector/router-trajectory.ts"],"names":[],"mappings":"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"}

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

@@ -1,87 +1,250 @@
 /**
- * Router trajectory collection (#2334 Phase 1)
+ * router-trajectory.ts — Opt-in DRACO-shaped trajectory recorder for the
+ * cost-optimal model router (ADR-148, phase 5).
  *
- * Opt-in per-decision dataset collection for the model router. The persisted
- * bandit state (`.swarm/model-router-state.json`) keeps only aggregates —
- * 9 Beta(α,β) cells and a capped/truncated history — which is not trainable
- * material for the Phase 2 FastGRNN tier-classifier. This sidecar captures
- * the per-example rows that training needs:
+ * 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).
  *
- *   decision rows: { taskHash, task, embedding?, complexity, features,
- *                    model, confidence, uncertainty, routedBy, ts }
- *   outcome rows:  { taskHash, model, outcome, ts }
+ * 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.
  *
- * joined offline on `taskHash` (sha256-16 of the task text).
- *
- * OFF by default. Enable with CLAUDE_FLOW_ROUTER_TRAJECTORY=1. Rows append to
- * `.swarm/model-router-trajectories.jsonl` — local-only, same trust domain as
- * the existing state file, but unlike it the rows contain full task text (up
- * to 500 chars) and raw embeddings, which is why this is opt-in rather than
- * always-on.
- *
- * Writes are best-effort: any fs error is swallowed (collection must never
- * break routing), matching the state-file behavior in model-router.ts.
+ * Schema is versioned (`"v": 1`). New required fields bump the version;
+ * additive optional fields do not.
  *
  * @module router-trajectory
  */
-import { createHash } from 'crypto';
-import { appendFileSync, existsSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
-export const TRAJECTORY_FILE = '.swarm/model-router-trajectories.jsonl';
-/** Schema version stamped on every row so offline training can dispatch. */
-const ROW_VERSION = 1;
-export function trajectoryCollectionEnabled() {
-    return process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY === '1';
-}
-/** Join key: first 16 hex chars of sha256(task). */
+import { appendFileSync, mkdirSync, existsSync, statSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { costUsd } from './model-prices.js';
+// ============================================================================
+// FNV-1a-32 (matches scripts/gen-seed-corpus.mjs)
+// ============================================================================
 export function taskHash(task) {
-    return createHash('sha256').update(task).digest('hex').slice(0, 16);
+    let h = 0x811c9dc5 >>> 0;
+    for (let i = 0; i < task.length; i++) {
+        h ^= task.charCodeAt(i);
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+let _cfg = null;
+/** Cached size of the current file; updated incrementally on each append to
+ *  avoid a `statSync` per write. -1 means "unknown, probe on next append". */
+let _cachedSize = -1;
+function getConfig() {
+    if (_cfg !== null)
+        return _cfg;
+    const enabled = process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY === '1';
+    const swarmDir = process.env.CLAUDE_FLOW_SWARM_DIR
+        ?? resolvePath(process.cwd(), '.swarm');
+    _cfg = {
+        enabled,
+        path: process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_PATH
+            ?? join(swarmDir, 'model-router-trajectories.jsonl'),
+        taskCharLimit: parseInt(process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_TASKLEN ?? '500', 10) || 500,
+        maxSizeBytes: parseInt(process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_MAXSIZE ?? `${10 * 1024 * 1024}`, 10) | 0,
+        maxRotations: Math.max(0, parseInt(process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY_MAXROTATIONS ?? '3', 10) || 3),
+    };
+    return _cfg;
+}
+/** Rotate `path` → `path.1`, `path.1` → `path.2`, ..., dropping the oldest. */
+function rotate(cfg) {
+    if (!existsSync(cfg.path))
+        return;
+    try {
+        // Walk from oldest to newest so each rename has a free target.
+        if (cfg.maxRotations === 0) {
+            // No history kept — just truncate by deleting.
+            unlinkSync(cfg.path);
+            return;
+        }
+        const oldest = `${cfg.path}.${cfg.maxRotations}`;
+        if (existsSync(oldest))
+            unlinkSync(oldest);
+        for (let i = cfg.maxRotations - 1; i >= 1; i--) {
+            const src = `${cfg.path}.${i}`;
+            if (existsSync(src))
+                renameSync(src, `${cfg.path}.${i + 1}`);
+        }
+        renameSync(cfg.path, `${cfg.path}.1`);
+    }
+    catch {
+        // If rotation fails (permissions, race), drop back to overwriting the
+        // active file by truncating its handle. Worst case we lose history.
+        try {
+            unlinkSync(cfg.path);
+        }
+        catch { /* */ }
+    }
+    _cachedSize = 0;
 }
 function appendRow(row) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
+        return;
     try {
-        const fullPath = join(process.cwd(), TRAJECTORY_FILE);
-        const dir = dirname(fullPath);
+        const dir = dirname(cfg.path);
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
-        appendFileSync(fullPath, JSON.stringify(row) + '\n');
+        // Probe size lazily on first call this process, then track incrementally.
+        if (_cachedSize < 0) {
+            _cachedSize = existsSync(cfg.path) ? statSync(cfg.path).size : 0;
+        }
+        // One JSON object per line, newline-terminated. No leading whitespace —
+        // we want the file to be `jq -c`-friendly.
+        const line = JSON.stringify(row) + '\n';
+        const bytes = Buffer.byteLength(line, 'utf8');
+        // Rotate BEFORE writing if this row would push us past the cap.
+        if (cfg.maxSizeBytes > 0 && _cachedSize + bytes > cfg.maxSizeBytes) {
+            rotate(cfg);
+        }
+        appendFileSync(cfg.path, line);
+        _cachedSize += bytes;
     }
     catch {
-        // Best-effort: collection must never break routing.
+        // Silent: trajectory collection must never break routing.
     }
 }
-export function recordTrajectoryDecision(task, embedding, complexity, decision) {
-    if (!trajectoryCollectionEnabled())
+// ============================================================================
+// Public API
+// ============================================================================
+/** Record one decision. Cheap — a single appendFileSync of a JSONL row. */
+export function recordDecision(args) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
         return;
-    appendRow({
-        v: ROW_VERSION,
-        type: 'decision',
+    const row = {
+        v: 1, type: 'decision',
         ts: new Date().toISOString(),
-        taskHash: taskHash(task),
-        task: task.slice(0, 500),
-        ...(embedding && embedding.length > 0 ? { embedding } : {}),
-        complexity: complexity.score,
-        features: {
-            lexicalComplexity: complexity.lexicalComplexity,
-            semanticDepth: complexity.semanticDepth,
-            taskScope: complexity.taskScope,
-            uncertaintyLevel: complexity.uncertaintyLevel,
-        },
-        model: decision.model,
-        confidence: decision.confidence,
-        uncertainty: decision.uncertainty,
-        routedBy: decision.routedBy,
-    });
+        task_hash: taskHash(args.task),
+        task: args.task.length > cfg.taskCharLimit ? args.task.slice(0, cfg.taskCharLimit) : args.task,
+        embedding: args.embedding,
+        complexity: args.complexity,
+        model: args.model,
+        confidence: args.confidence,
+        uncertainty: args.uncertainty,
+        routed_by: args.routedBy,
+        ...(args.neuralBackend ? { neural_backend: args.neuralBackend } : {}),
+        ...(args.abPair ? { ab_pair: args.abPair } : {}),
+        ...(args.provider ? { provider: args.provider } : {}),
+        ...(args.openrouterModel ? { openrouter_model: args.openrouterModel } : {}),
+        ...(args.ensembleDisagreement !== undefined ? { ensemble_disagreement: args.ensembleDisagreement } : {}),
+    };
+    appendRow(row);
 }
-export function recordTrajectoryOutcome(task, model, outcome) {
-    if (!trajectoryCollectionEnabled())
+/** Record one outcome. Join to a decision by `task_hash`. */
+export function recordTrajectoryOutcome(args) {
+    const cfg = getConfig();
+    if (!cfg.enabled)
         return;
-    appendRow({
-        v: ROW_VERSION,
-        type: 'outcome',
+    // iter 31 — compute USD spend at write time using the canonical price
+    // table. Cost is a first-class field so consumers don't need to JOIN
+    // against the decision row (which may live in a rotated file).
+    const cost_usd = args.tokens && (args.tokens.input > 0 || args.tokens.output > 0)
+        ? costUsd(args.modelId, args.tokens.input, args.tokens.output)
+        : undefined;
+    const row = {
+        v: 1, type: 'outcome',
         ts: new Date().toISOString(),
-        taskHash: taskHash(task),
-        model,
-        outcome,
-    });
+        task_hash: taskHash(args.task),
+        quality: args.quality,
+        scores: args.scores,
+        source: args.source,
+        ...(args.tokens ? { tokens: args.tokens } : {}),
+        ...(cost_usd != null ? { cost_usd } : {}),
+        ...(args.modelId ? { model_id: args.modelId } : {}),
+    };
+    appendRow(row);
+}
+/** Diagnostic for status/CLI. */
+export function trajectoryRecorderStatus() {
+    return { ...getConfig() };
+}
+/** 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 function tierFromComplexity(complexity) {
+    if (complexity < 0.34)
+        return 'cheap';
+    if (complexity < 0.67)
+        return 'mid';
+    return '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 function pairTrajectoryRows(rows) {
+    const decisions = new Map();
+    const outcomes = new Map();
+    // Latest-wins per hash. Production may re-run the same task — using the most
+    // recent outcome avoids polluting the corpus with stale judgments.
+    let dCount = 0, oCount = 0;
+    for (const row of rows) {
+        if (row.type === 'decision') {
+            dCount++;
+            const prev = decisions.get(row.task_hash);
+            if (!prev || row.ts > prev.ts)
+                decisions.set(row.task_hash, row);
+        }
+        else if (row.type === 'outcome') {
+            oCount++;
+            const prev = outcomes.get(row.task_hash);
+            if (!prev || row.ts > prev.ts)
+                outcomes.set(row.task_hash, row);
+        }
+    }
+    const pairs = [];
+    const bySource = {};
+    const byTier = {};
+    let droppedNoEmbedding = 0;
+    let droppedNoMatch = 0;
+    for (const [hash, dec] of decisions) {
+        const out = outcomes.get(hash);
+        if (!out) {
+            droppedNoMatch++;
+            continue;
+        }
+        if (!dec.embedding || dec.embedding.length === 0) {
+            droppedNoEmbedding++;
+            continue;
+        }
+        // scores map: prefer the outcome's full per-model map (set by callers who
+        // ran multi-model comparisons); fall back to a single-model entry derived
+        // from the model the decision actually dispatched.
+        const scores = out.scores
+            ?? { [dec.openrouter_model ?? dec.model]: out.quality };
+        const tier = tierFromComplexity(dec.complexity);
+        const source = out.source ?? 'unknown';
+        pairs.push({
+            task: dec.task,
+            embedding: dec.embedding,
+            scores,
+            tier,
+            source,
+            ts: out.ts,
+        });
+        bySource[source] = (bySource[source] ?? 0) + 1;
+        byTier[tier] = (byTier[tier] ?? 0) + 1;
+    }
+    return {
+        pairs,
+        stats: {
+            totalRows: rows.length,
+            decisions: dCount,
+            outcomes: oCount,
+            paired: pairs.length,
+            droppedNoEmbedding,
+            droppedNoMatch,
+            bySource,
+            byTier,
+        },
+    };
+}
+/** Test seam — reset cached config so unit tests can change env vars between cases. */
+export function __resetTrajectoryRecorderForTests() {
+    _cfg = null;
+    _cachedSize = -1;
 }
 //# sourceMappingURL=router-trajectory.js.map

package/dist/src/ruvector/router-trajectory.js.map

@@ -1 +1 @@
-{"version":3,"file":"router-trajectory.js","sourceRoot":"","sources":["../../../src/ruvector/router-trajectory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAErC,MAAM,CAAC,MAAM,eAAe,GAAG,wCAAwC,CAAC;AAExE,4EAA4E;AAC5E,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,MAAM,UAAU,2BAA2B;IACzC,OAAO,OAAO,CAAC,GAAG,CAAC,6BAA6B,KAAK,GAAG,CAAC;AAC3D,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC;AAiCD,SAAS,SAAS,CAAC,GAAiD;IAClE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,eAAe,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;IACtD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,IAAY,EACZ,SAA+B,EAC/B,UAAiE,EACjE,QAAsF;IAEtF,IAAI,CAAC,2BAA2B,EAAE;QAAE,OAAO;IAC3C,SAAS,CAAC;QACR,CAAC,EAAE,WAAW;QACd,IAAI,EAAE,UAAU;QAChB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC;QACxB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACxB,GAAG,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,UAAU,EAAE,UAAU,CAAC,KAAK;QAC5B,QAAQ,EAAE;YACR,iBAAiB,EAAE,UAAU,CAAC,iBAAiB;YAC/C,aAAa,EAAE,UAAU,CAAC,aAAa;YACvC,SAAS,EAAE,UAAU,CAAC,SAAS;YAC/B,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;SAC9C;QACD,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;KAC5B,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,IAAY,EACZ,KAAa,EACb,OAA4C;IAE5C,IAAI,CAAC,2BAA2B,EAAE;QAAE,OAAO;IAC3C,SAAS,CAAC;QACR,CAAC,EAAE,WAAW;QACd,IAAI,EAAE,SAAS;QACf,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC;QACxB,KAAK;QACL,OAAO;KACR,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"router-trajectory.js","sourceRoot":"","sources":["../../../src/ruvector/router-trajectory.ts"],"names":[],"mappings":"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"}

package/dist/src/ruvector/task-embedder.d.ts

@@ -0,0 +1,56 @@
+/**
+ * task-embedder.ts — Shared lazy task embedder + LRU cache (ADR-149 iter 9).
+ *
+ * The cost-optimal neural router (ADR-149) fires only when `route(task, embedding)`
+ * is called with a real embedding. Two call sites in the dispatcher chain need
+ * embeddings: `agent-tools.ts` (initial routing) and `agent-execute-core.ts`
+ * (the fallback chain on 429/5xx). Before this module they each loaded their
+ * own @xenova/transformers MiniLM pipeline and recomputed embeddings on every
+ * call — including for repeated prompts.
+ *
+ * This module:
+ *   1. Loads the pipeline once per process (`loadTaskEmbedder`).
+ *   2. Caches embeddings per task text via an LRU of configurable size
+ *      (default 500 entries ≈ 1.5 MB at 384-dim).
+ *   3. Hashes by FNV-1a-32 + length to keep the key compact and collision-safe
+ *      for typical prompt sizes.
+ *   4. Returns `undefined` on any failure so callers gracefully fall back to
+ *      the heuristic+bandit path.
+ *
+ * @module task-embedder
+ */
+/**
+ * Compute (or fetch from cache) the 384-dim MiniLM embedding for `task`.
+ * Returns `undefined` on any failure (missing @xenova/transformers, ONNX
+ * runtime error, etc.) so callers can gracefully fall back to the
+ * heuristic+bandit path. Best-effort and never throws.
+ *
+ * Cache hit-rate accumulates across the process lifetime and is observable
+ * via `embedderStats()` for diagnostics.
+ */
+export declare function embedTaskWithCache(task: string): Promise<number[] | undefined>;
+/**
+ * Batch counterpart to `embedTaskWithCache`. For each task, returns the
+ * cached embedding when present, else schedules a fresh inference. The
+ * fresh-inference set is computed in a SINGLE ONNX pass via
+ * @xenova/transformers' array-input mode, amortizing tensor setup +
+ * model-load overhead across the batch. Order of the output array
+ * matches the input order.
+ *
+ * Returns `undefined` for any task that failed to embed (missing dep,
+ * runtime error). Cache state updates as if each task had been called
+ * separately through embedTaskWithCache (hits/misses counters update
+ * accordingly).
+ */
+export declare function embedTaskWithCacheBatch(tasks: string[]): Promise<Array<number[] | undefined>>;
+/** Diagnostic surface — hit/miss counters + cache state. */
+export declare function embedderStats(): {
+    size: number;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+};
+/** Test seam — clear LRU + counters so tests get a fresh baseline. */
+export declare function __resetTaskEmbedderForTests(): void;
+//# sourceMappingURL=task-embedder.d.ts.map

package/dist/src/ruvector/task-embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-embedder.d.ts","sourceRoot":"","sources":["../../../src/ruvector/task-embedder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAuHH;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAkBpF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CA2CnG;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAShH;AAED,sEAAsE;AACtE,wBAAgB,2BAA2B,IAAI,IAAI,CAKlD"}