@claude-flow/cli 3.10.46 → 3.12.0

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

@@ -22,17 +22,96 @@
  *
  * Note (#2329): An earlier design (ADR-026 + this file's previous header)
  * described a Tiny-Dancer / FastGRNN neural router with embedding-based
- * complexity scoring. That path was never wired in — `@ruvector/tiny-dancer`
- * is not imported here and the `embedding`-consuming branch in
- * `computeSemanticDepth` is only reachable via the externally-callable
- * `routeToModelFull(task, embedding)` wrapper (no internal callers). The
- * shipped router is the heuristic + bandit described above; the neural
- * path remains a future direction tracked in #2329.
+ * complexity scoring. That path was never wired in directly.
+ *
+ * Note (ADR-148, #2334): The cost-optimal neural router is now wired as an
+ * optional, gated addition via `./neural-router.ts` (which uses
+ * `@metaharness/router`, optionally accelerated by `@ruvector/tiny-dancer`).
+ * It is double-gated on `CLAUDE_FLOW_ROUTER_NEURAL=1` + an embedding being
+ * supplied + a corpus/artifact being loadable. When any gate is closed the
+ * shipped heuristic + bandit path runs unchanged and the result carries
+ * `routedBy: 'heuristic'` (default) or `'bandit-fallback'` (neural enabled
+ * but declined). When all gates are open and a backend resolves, the result
+ * carries `routedBy: 'metaharness-knn' | 'metaharness-krr' | 'fastgrnn'`.
  *
  * @module model-router
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
+// ----------------------------------------------------------------------------
+// Lazy module loaders — initialised once per process. The dynamic-import calls
+// keep these modules off the critical-path-cold-start, but we want subsequent
+// route() calls to pay only a Map lookup, not a new Promise per call.
+// ----------------------------------------------------------------------------
+let _neuralRouterMod = null;
+function loadNeuralRouter() {
+    if (_neuralRouterMod === null)
+        _neuralRouterMod = import('./neural-router.js');
+    return _neuralRouterMod;
+}
+let _trajectoryMod = null;
+function loadTrajectoryRecorder() {
+    if (_trajectoryMod === null)
+        _trajectoryMod = import('./router-trajectory.js');
+    return _trajectoryMod;
+}
+// ADR-150 iter 11–12 — parallel-decision recorder for the SelfEvolvingRouter
+// promotion gate. Dynamic-imported lazily so the routing hot path never
+// pays the load cost when CLAUDE_FLOW_ROUTER_PARALLEL_LOG is unset.
+let _parallelRecorderMod = null;
+function loadParallelRecorder() {
+    if (_parallelRecorderMod === null)
+        _parallelRecorderMod = import('./router-parallel-recorder.js');
+    return _parallelRecorderMod;
+}
+let _altsCache = null;
+let _altsProbeDone = false;
+function loadOpenRouterAlts() {
+    if (_altsProbeDone)
+        return _altsCache;
+    _altsProbeDone = true;
+    try {
+        // Probe candidate paths: explicit env override, then asset locations
+        // relative to this file (src dev) and the dist build.
+        const explicit = process.env.CLAUDE_FLOW_ROUTER_OPENROUTER_ALTS;
+        const candidates = [];
+        if (explicit)
+            candidates.push(explicit);
+        // Probe asset dirs without using import.meta.url so this stays compatible
+        // with both CJS and ESM consumers of the compiled .js.
+        candidates.push(join(process.cwd(), 'v3', '@claude-flow', 'cli', 'assets', 'model-router', 'openrouter-alts.json'));
+        candidates.push(join(process.cwd(), 'assets', 'model-router', 'openrouter-alts.json'));
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                _altsCache = JSON.parse(readFileSync(p, 'utf8'));
+                return _altsCache;
+            }
+        }
+    }
+    catch {
+        // Silent — alts are optional.
+    }
+    return null;
+}
+/** Return the resolved provider + OpenRouter model for the picked tier. */
+function resolveExecutionProvider(model) {
+    const explicit = process.env.CLAUDE_FLOW_ROUTER_PROVIDER?.toLowerCase();
+    // Default: anthropic unless explicitly set to openrouter, or OPENROUTER_API_KEY
+    // is the only credential present (matches agent-execute-core's selection).
+    const hasOpenRouter = !!process.env.OPENROUTER_API_KEY;
+    const hasAnthropic = !!process.env.ANTHROPIC_API_KEY;
+    const wantOR = explicit === 'openrouter' ||
+        (!hasAnthropic && hasOpenRouter && explicit !== 'anthropic');
+    if (!wantOR)
+        return { provider: 'anthropic' };
+    const alts = loadOpenRouterAlts();
+    if (!alts)
+        return { provider: 'openrouter' }; // OR provider but no alt slug
+    const entry = alts.tiers[model];
+    if (!entry?.openrouter_alt)
+        return { provider: 'openrouter' };
+    return { provider: 'openrouter', openrouterModel: entry.openrouter_alt };
+}
 /**
  * Model capabilities and characteristics
  */
@@ -145,7 +224,7 @@ function sampleGamma(alpha) {
  * X ~ Gamma(α), Y ~ Gamma(β). Returns the mean for degenerate α+β=0
  * (shouldn't happen in practice but defensive).
  */
-function sampleBeta(alpha, beta) {
+export function sampleBeta(alpha, beta) {
     if (alpha <= 0 || beta <= 0)
         return 0.5;
     const x = sampleGamma(alpha);
@@ -169,6 +248,11 @@ function defaultBanditPriors() {
 function defaultBucketedPriors() {
     return { low: defaultBanditPriors(), med: defaultBanditPriors(), high: defaultBanditPriors() };
 }
+/** ADR-149 — empty per-modelId shadow priors. Each bucket starts as `{}`; entries
+ *  populate on first `recordOutcomeByModelId(task, modelId, outcome)` call. */
+function defaultBucketedPriorsById() {
+    return { low: {}, med: {}, high: {} };
+}
 function clonePriors(p) {
     return { haiku: { ...p.haiku }, sonnet: { ...p.sonnet }, opus: { ...p.opus }, inherit: { ...p.inherit } };
 }
@@ -243,24 +327,219 @@ export class ModelRouter {
         opus: 0,
         inherit: 0,
     };
+    /**
+     * ADR-148 — in-memory counters surfaced via `getStats()` and read by the
+     * `hooks_intelligence_stats` MCP tool. Process-local, not persisted (these
+     * are operational metrics, not authoritative state — see ADR-074/086).
+     */
+    routedByCounts = {
+        heuristic: 0,
+        'bandit-fallback': 0,
+        hybrid: 0,
+    };
+    neuralBackendCounts = {
+        'metaharness-knn': 0,
+        'metaharness-krr': 0,
+        fastgrnn: 0,
+    };
+    abDisagreements = 0;
+    abComparisons = 0;
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.state = this.loadState();
     }
     /**
-     * Route a task to the optimal model
+     * Route a task to the optimal model.
+     *
+     * When `embedding` is supplied and `CLAUDE_FLOW_ROUTER_NEURAL=1` is set,
+     * the cost-optimal neural backend (ADR-148) is consulted first; its
+     * decision is used when its `metBar` clears the configured quality bar
+     * and `routedBy` reflects which backend produced the decision. Otherwise
+     * the shipped heuristic + Thompson bandit path runs (byte-identical to
+     * the pre-ADR-148 behavior) and the result carries `routedBy:
+     * 'bandit-fallback'` (neural was enabled but declined) or
+     * `'heuristic'` (neural was disabled).
      */
     async route(task, embedding) {
         const startTime = performance.now();
         // Analyze task complexity
         const complexity = this.analyzeComplexity(task, embedding);
-        // Compute base model scores
+        // ADR-148 — optional neural cost-optimal path (gated, opt-in).
+        //
+        // Hybrid math: we use the neural's per-candidate predicted quality as a
+        // weighted prior on the bandit's Beta(α,β) posterior, rather than
+        // overriding the bandit's pick. With weight=w (env-tunable, default 5)
+        // each candidate's Beta becomes Beta(α + q*w, β + (1-q)*w). Cold start
+        // → neural dominates (α+β ≈ 2 + w); many real outcomes → bandit
+        // dominates (α+β >> w). The persistent bandit state is unchanged.
+        //
+        // `bandit-fallback` is reserved for the case where neural was enabled
+        // but the backend returned no decision at all (artifact load failed,
+        // dim mismatch, etc.). In that case we route via pure bandit.
+        let neuralPrior = null;
+        let neuralBackend = undefined;
+        let neuralModelId = undefined;
+        let neuralDeclined = false;
+        // iter 46 — capture iter 45's ensemble-disagreement diagnostic so we can
+        // persist it to the trajectory below; downstream tuners (future) can
+        // analyze the distribution to recommend an iter 44 threshold.
+        let neuralEnsembleDisagreement = undefined;
+        if (embedding && embedding.length > 0 && process.env.CLAUDE_FLOW_ROUTER_NEURAL === '1') {
+            try {
+                const { tryCostOptimalRoute } = await loadNeuralRouter();
+                // ADR-149 iter 15 — pass the task's complexity bucket through so
+                // the neural-router's per-modelId Thompson (when gated on) can
+                // use the bucket-specific prior instead of marginalising.
+                const nr = await tryCostOptimalRoute(embedding, { complexityBucket: complexityBucket(complexity.score) });
+                if (nr) {
+                    // ADR-149: capture the concrete picked model id (the cost-optimal
+                    // pick across all candidates, not just within a tier).
+                    neuralModelId = nr.modelId;
+                    neuralEnsembleDisagreement = nr.ensembleDisagreement;
+                    // Build per-tier quality map for the bandit prior. The neural
+                    // backend returns per-model alternatives (e.g. 7 distinct slugs);
+                    // for the Beta-prior bump we collapse to tier by taking the MAX
+                    // predicted quality within each tier — the tier whose best
+                    // candidate is best overall is the tier the bandit should favor.
+                    // Then we apply rank-based scaling [1.0, 0.5, 0.2] across the
+                    // three tiers so the Beta bumps are well-separated (raw KRR
+                    // outputs are typically in a narrow band — see ADR-148 phase 1).
+                    const sorted = [...nr.alternatives].sort((a, b) => b.predictedQuality - a.predictedQuality);
+                    if (!sorted.find(s => s.model === nr.model)) {
+                        sorted.unshift({ model: nr.model, modelId: nr.modelId, predictedQuality: nr.predictedQuality, costPerMTok: 0 });
+                    }
+                    // Collapse per-model alternatives → per-tier MAX quality, preserving
+                    // first-occurrence order (which is best-quality first thanks to the sort).
+                    const tierMaxQ = {};
+                    const tierOrder = [];
+                    for (const a of sorted) {
+                        if (tierMaxQ[a.model] === undefined) {
+                            tierMaxQ[a.model] = a.predictedQuality;
+                            tierOrder.push(a.model);
+                        }
+                        else if (a.predictedQuality > (tierMaxQ[a.model] ?? 0)) {
+                            tierMaxQ[a.model] = a.predictedQuality;
+                        }
+                    }
+                    const rankQ = [1.0, 0.5, 0.2];
+                    const qualities = {};
+                    for (let i = 0; i < tierOrder.length && i < rankQ.length; i++) {
+                        qualities[tierOrder[i]] = rankQ[i];
+                    }
+                    const weight = parseFloat(process.env.CLAUDE_FLOW_ROUTER_NEURAL_WEIGHT ?? '5') || 5;
+                    neuralPrior = { qualities, weight };
+                    neuralBackend = nr.routedBy;
+                }
+                else {
+                    neuralDeclined = true;
+                }
+            }
+            catch {
+                // Silent — neural path is best-effort.
+            }
+        }
         const scores = this.computeModelScores(complexity);
-        // Apply circuit breaker adjustments
         const adjustedScores = this.applyCircuitBreaker(scores);
-        // Select best model
-        const { model, confidence, uncertainty } = this.selectModel(adjustedScores, complexity.score);
+        // A/B mode: compute the pure-bandit pick alongside the hybrid pick so
+        // we can log disagreement. Both samples are drawn from the same Beta
+        // posteriors but with/without the neural prior bump — useful for
+        // measuring real lift before flipping defaults.
+        //
+        // iter 37 — TWO knobs:
+        //   CLAUDE_FLOW_ROUTER_AB=1                    → A/B on every call (orig)
+        //   CLAUDE_FLOW_ROUTER_AB_SAMPLE_RATE=<0..1>   → A/B on a sampled subset,
+        //     keyed deterministically by task_hash so the same task always falls
+        //     in or out of the sample. Lets production accumulate ab_pair data
+        //     passively at low overhead (e.g. 0.05 = 5% of decisions).
+        //   Both set → SAMPLE_RATE wins (more specific).
+        const rateRaw = process.env.CLAUDE_FLOW_ROUTER_AB_SAMPLE_RATE;
+        const rate = rateRaw ? Math.max(0, Math.min(1, parseFloat(rateRaw) || 0)) : 0;
+        const allOn = process.env.CLAUDE_FLOW_ROUTER_AB === '1';
+        let inSample = false;
+        if (rate > 0) {
+            // Deterministic sample by FNV-1a-32 of the task text. Same task always
+            // gets the same A/B decision across re-runs (reproducible tests, stable
+            // population over time). Inlined to avoid the async router-trajectory
+            // import on the hot path.
+            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;
+            }
+            inSample = (h % 10000) / 10000 < rate;
+        }
+        const abEnabled = (rate > 0 ? inSample : allOn) && neuralPrior !== null;
+        let abPair;
+        if (abEnabled) {
+            // Pre-compute the bandit-only pick. Single extra Thompson sample per
+            // call — independent draws are noisy but cheap (~3 Beta samples ≈
+            // <10 μs). For a per-call disagreement signal one draw is fine; over
+            // N decisions the rate stabilises.
+            const banditOnly = this.selectModel(adjustedScores, complexity.score, undefined);
+            const picked = this.selectModel(adjustedScores, complexity.score, neuralPrior ?? undefined);
+            abPair = {
+                bandit_pick: banditOnly.model,
+                hybrid_pick: picked.model,
+                disagree: banditOnly.model !== picked.model,
+            };
+            this.abComparisons++;
+            if (abPair.disagree)
+                this.abDisagreements++;
+            // ADR-150 iter 12 — opt-in parallel-decision recorder. No-op when
+            // CLAUDE_FLOW_ROUTER_PARALLEL_LOG is unset (the default), so this
+            // adds zero overhead to the default routing path. Fire-and-forget
+            // dynamic-import + recordPair; never blocks the route() return.
+            if (process.env.CLAUDE_FLOW_ROUTER_PARALLEL_LOG === '1') {
+                loadParallelRecorder().then((mod) => {
+                    try {
+                        mod.recordPair({
+                            task,
+                            bandit: {
+                                pick: banditOnly.model,
+                                predictedQuality: banditOnly.confidence,
+                                predictedCostUsd: 0, // bandit doesn't price; analyzer uses outcome
+                                backend: 'thompson-bandit',
+                            },
+                            ser: {
+                                pick: picked.model,
+                                predictedQuality: picked.confidence,
+                                predictedCostUsd: 0,
+                                backend: neuralPrior ? 'metaharness-router-hybrid' : 'bandit-only',
+                            },
+                        });
+                    }
+                    catch {
+                        // ADR-150 rule #3 — never throw from the routing path.
+                    }
+                }).catch(() => { });
+            }
+            var pickedForResult = picked; // eslint-disable-line no-var
+        }
+        else {
+            var pickedForResult = this.selectModel(adjustedScores, complexity.score, neuralPrior ?? undefined); // eslint-disable-line no-var
+        }
+        const model = pickedForResult.model;
+        const confidence = pickedForResult.confidence;
+        const uncertainty = pickedForResult.uncertainty;
+        const routedBy = neuralPrior
+            ? 'hybrid'
+            : neuralDeclined ? 'bandit-fallback' : 'heuristic';
         const inferenceTimeUs = (performance.now() - startTime) * 1000;
+        // ADR-148 phase 2 — resolve OpenRouter alt for the picked tier when the
+        // execution provider is OpenRouter. Free of side effects on the bandit;
+        // purely advisory metadata for downstream agent-execute-core.
+        //
+        // ADR-149 — when the neural backend returned a concrete `modelId` that
+        // is NOT an Anthropic slug, we override the provider to 'openrouter'
+        // and use the modelId as the openrouterModel. Otherwise consumers
+        // dispatching on `model` would call the Anthropic SDK for a model id
+        // the SDK can't reach (e.g. 'inclusionai/ling-2.6-flash'), losing the
+        // cost-optimal pick. When the neural picked an Anthropic id we keep
+        // the standard provider resolution since the Anthropic SDK can serve it.
+        let exec = resolveExecutionProvider(model);
+        if (neuralModelId && !neuralModelId.startsWith('anthropic/')) {
+            exec = { provider: 'openrouter', openrouterModel: neuralModelId };
+        }
         // Build result
         const result = {
             model,
@@ -274,9 +553,35 @@ export class ModelRouter {
                 .sort((a, b) => b.score - a.score),
             inferenceTimeUs,
             costMultiplier: MODEL_CAPABILITIES[model].costMultiplier,
+            routedBy,
+            ...(neuralBackend ? { neuralBackend } : {}),
+            provider: exec.provider,
+            ...(exec.openrouterModel ? { openrouterModel: exec.openrouterModel } : {}),
+            // ADR-149: surface the concrete neural pick when present. Prefer the
+            // explicit OpenRouter alt (resolveExecutionProvider) for execution,
+            // but expose the model id the neural backend chose so observers and
+            // consumers can see the cost-optimal decision.
+            ...(neuralModelId ? { modelId: neuralModelId } : {}),
         };
-        // Track decision
+        // Track decision (in-memory bandit state)
         this.trackDecision(task, result);
+        // ADR-148 — opt-in DRACO-shaped trajectory collection
+        if (process.env.CLAUDE_FLOW_ROUTER_TRAJECTORY === '1') {
+            try {
+                const { recordDecision } = await loadTrajectoryRecorder();
+                recordDecision({
+                    task, embedding, complexity: complexity.score,
+                    model, confidence, uncertainty, routedBy,
+                    neuralBackend, abPair,
+                    provider: exec.provider,
+                    openrouterModel: exec.openrouterModel,
+                    ensembleDisagreement: neuralEnsembleDisagreement,
+                });
+            }
+            catch {
+                // Silent — trajectory recording must never break routing.
+            }
+        }
         return result;
     }
     /**
@@ -418,15 +723,36 @@ export class ModelRouter {
      * threshold tuning. Beta(1,1) = uniform on cold start so behavior matches
      * the prior deterministic router until outcomes accumulate.
      */
-    selectModel(scores, complexityScore) {
+    selectModel(scores, complexityScore, 
+    /**
+     * Optional neural prior (ADR-148 hybrid math). When supplied, each
+     * candidate's Beta(α, β) prior is perturbed by `weight` pseudo-counts of
+     * the neural's predicted quality before sampling. Cold start → neural
+     * dominates; many real outcomes → bandit dominates. The persistent
+     * bandit state is NOT modified — this is a per-call posterior bump only.
+     */
+    neuralPrior) {
         // Thompson sampling: combine deterministic score with bandit posterior,
         // keyed by complexity bucket (ADR-142) so learning is task-type-local.
         const bucketed = this.state.priors ?? defaultBucketedPriors();
         const priors = bucketed[complexityBucket(complexityScore)] ?? defaultBanditPriors();
+        // Apply the optional neural prior: Beta(α + q*w, β + (1-q)*w). Per-call,
+        // does not persist. Clamp `q` into [0, 1] so a bogus backend reading
+        // cannot push the prior into invalid territory.
+        const bump = (a, b, q, w) => {
+            if (q === undefined || w <= 0)
+                return { alpha: a, beta: b };
+            const clamped = Math.min(1, Math.max(0, q));
+            return { alpha: a + clamped * w, beta: b + (1 - clamped) * w };
+        };
+        const w = neuralPrior?.weight ?? 0;
+        const ph = bump(priors.haiku.alpha, priors.haiku.beta, neuralPrior?.qualities.haiku, w);
+        const ps = bump(priors.sonnet.alpha, priors.sonnet.beta, neuralPrior?.qualities.sonnet, w);
+        const po = bump(priors.opus.alpha, priors.opus.beta, neuralPrior?.qualities.opus, w);
         const sampledScores = {
-            haiku: scores.haiku * sampleBeta(priors.haiku.alpha, priors.haiku.beta),
-            sonnet: scores.sonnet * sampleBeta(priors.sonnet.alpha, priors.sonnet.beta),
-            opus: scores.opus * sampleBeta(priors.opus.alpha, priors.opus.beta),
+            haiku: scores.haiku * sampleBeta(ph.alpha, ph.beta),
+            sonnet: scores.sonnet * sampleBeta(ps.alpha, ps.beta),
+            opus: scores.opus * sampleBeta(po.alpha, po.beta),
             inherit: scores.inherit, // not bandit-controlled
         };
         // Get sorted models by sampled score (drops 'inherit' from selection)
@@ -469,7 +795,28 @@ export class ModelRouter {
             // while honoring any non-trivial learning.
             const selectedSamples = priors[bestModel].alpha + priors[bestModel].beta;
             const selectedTrusted = selectedSamples >= 5 && selectedMean >= 0.45;
-            if (!targetWorse && !selectedTrusted) {
+            // ADR-148 — additional trust path: when the neural prior agrees with
+            // the bandit's pick (i.e. neuralPrior.qualities[bestModel] is the
+            // highest), the neural backend's signal is treated as a vote of
+            // confidence that lets us skip escalation. Without this, cold-start
+            // installations stay stuck in the structurally-high-uncertainty
+            // regime (#2250) and the neural's clear preference never reaches
+            // the final pick. The neural prior's top is computed as the max
+            // quality over the supplied candidates.
+            let neuralEndorsesPick = false;
+            if (neuralPrior) {
+                let bestNeuralQ = -1;
+                let neuralTop = null;
+                for (const [m, q] of Object.entries(neuralPrior.qualities)) {
+                    if (q > bestNeuralQ) {
+                        bestNeuralQ = q;
+                        neuralTop = m;
+                    }
+                }
+                if (neuralTop === bestModel)
+                    neuralEndorsesPick = true;
+            }
+            if (!targetWorse && !selectedTrusted && !neuralEndorsesPick) {
                 model = escalateTo;
             }
         }
@@ -499,6 +846,10 @@ export class ModelRouter {
         this.state.totalDecisions++;
         this.state.modelDistribution[result.model] =
             (this.state.modelDistribution[result.model] || 0) + 1;
+        // ADR-148 — operational counters for hooks_intelligence_stats.
+        this.routedByCounts[result.routedBy]++;
+        if (result.neuralBackend)
+            this.neuralBackendCounts[result.neuralBackend]++;
         // Update running averages
         const n = this.state.totalDecisions;
         this.state.avgComplexity =
@@ -552,6 +903,52 @@ export class ModelRouter {
         bp[model].beta += 1 - reward;
         this.saveState();
     }
+    /**
+     * ADR-149 — record an outcome keyed by the CONCRETE model id (e.g.
+     * 'inclusionai/ling-2.6-flash') rather than the tier label. Updates the
+     * shadow `priorsById` state without affecting `priors` (tier priors).
+     *
+     * This is the per-model learning signal the bandit needs to eventually
+     * distinguish GPT-4.1 from Sonnet within the 'sonnet' tier. Selection
+     * currently still uses tier priors; this state accumulates so a future
+     * refactor can switch the selector over once there's enough data.
+     *
+     * Cost-adjusted reward semantics: cheap models get the highest reward on
+     * success (their successes are most cost-efficient). We map modelId to
+     * its closest tier for the reward table — the routing math doesn't have
+     * a per-modelId reward configuration yet.
+     */
+    recordOutcomeByModelId(task, modelId, outcome) {
+        if (!modelId || typeof modelId !== 'string')
+            return;
+        const taskScore = this.analyzeComplexity(task).score;
+        const bucket = complexityBucket(taskScore);
+        if (!this.state.priorsById)
+            this.state.priorsById = defaultBucketedPriorsById();
+        let perBucket = this.state.priorsById[bucket];
+        if (!perBucket) {
+            perBucket = {};
+            this.state.priorsById[bucket] = perBucket;
+        }
+        if (!perBucket[modelId])
+            perBucket[modelId] = { alpha: 1, beta: 1 };
+        // Reward proxy: derive a tier-equivalent for cost weighting. Substring
+        // match keeps it cheap and accurate for the candidates in the registry.
+        const id = modelId.toLowerCase();
+        const tierProxy = id.includes('haiku') || id.includes('ling-') || id.includes('flash-lite')
+            || id.includes('nemotron-nano') || id.includes('ministral')
+            || id.includes('llama-3.2-3b') || id.includes('llama-3.1-8b')
+            ? 'haiku'
+            : id.includes('opus') ? 'opus' : 'sonnet';
+        const reward = BANDIT_REWARDS[tierProxy]?.[outcome] ?? 0.5;
+        perBucket[modelId].alpha += reward;
+        perBucket[modelId].beta += 1 - reward;
+        // Bump the schema version on first per-modelId write so downstream
+        // tooling can see v3 was reached (the version field stays at 3 once set).
+        if ((this.state.version ?? 0) < 3)
+            this.state.version = 3;
+        this.saveState();
+    }
     /**
      * Get router statistics
      */
@@ -563,6 +960,15 @@ export class ModelRouter {
             avgConfidence: this.state.avgConfidence,
             circuitBreakerTrips: this.state.circuitBreakerTrips,
             consecutiveFailures: { ...this.consecutiveFailures },
+            routedByCounts: { ...this.routedByCounts },
+            neuralBackendCounts: { ...this.neuralBackendCounts },
+            ab: {
+                comparisons: this.abComparisons,
+                disagreements: this.abDisagreements,
+                disagreementRate: this.abComparisons > 0 ? this.abDisagreements / this.abComparisons : 0,
+            },
+            stateVersion: this.state.version ?? 2,
+            ...(this.state.priorsById ? { priorsById: this.state.priorsById } : {}),
         };
     }
     /**
@@ -722,4 +1128,35 @@ export function recordModelOutcome(task, model, outcome) {
     const router = getModelRouter();
     router.recordOutcome(task, model, outcome);
 }
+/**
+ * ADR-149 — record an outcome keyed by the concrete model id rather than
+ * the tier label. Updates the shadow `priorsById` state. Selection logic
+ * still uses tier priors; this data accumulates for a future per-modelId
+ * selector refactor.
+ *
+ * Safe to call alongside `recordModelOutcome` — they update independent
+ * state slices so double-counting is impossible.
+ */
+export function recordModelOutcomeByModelId(task, modelId, outcome) {
+    const router = getModelRouter();
+    router.recordOutcomeByModelId(task, modelId, outcome);
+}
+/**
+ * ADR-149 iter 14 — read-only access to the per-modelId Beta priors. The
+ * neural-router consumes this to apply per-model Thompson sampling on top
+ * of its predicted-quality vector when CLAUDE_FLOW_ROUTER_BANDIT_PER_MODEL=1.
+ * Returns the legacy bucketed priors (`priorsById[bucket][modelId]`) when
+ * present, else null.
+ */
+export function getModelRouterPriorsById() {
+    const router = getModelRouter();
+    const stats = router.getStats();
+    return stats.priorsById ?? null;
+}
+/**
+ * Re-export the complexity-bucket helper so the neural-router (which gets
+ * the task text via the route() call) can map a complexity score to the
+ * matching bandit bucket.
+ */
+export { complexityBucket };
 //# sourceMappingURL=model-router.js.map