@polderlabs/bizar 9.0.0 → 10.0.7

package/packages/sdk/dist/router/memory-distillation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * router/memory-distillation.ts — RETRIEVE → JUDGE → DISTILL →
+ * CONSOLIDATE (ADR-174) as a pure TypeScript module.
+ *
+ * v6.4.0 — ported from ruflo `@claude-flow/neural/src/reasoning-bank.ts`
+ * (the 4-step pipeline) + ADR-174 (provenance-tiered promote gate).
+ *
+ * This is the $0 default path — deterministic, no LLM, no I/O.
+ * Living inside the SDK (rather than the dashboard .mjs files) so
+ * the `memory_distill` MCP tool can call it via a static TypeScript
+ * import without crossing the ESM/CJS boundary at runtime.
+ *
+ * The dashboard's `bizar-dash/src/server/memory-{distillation,
+ * consolidator}.mjs` re-export the same semantics and add the
+ * vault I/O (read notes, write promoted patterns back). Both paths
+ * agree on the `Pattern` shape so the schema is one-of.
+ */
+export declare const PROVENANCE_TIERS: readonly ["oracle:test-exec", "proxy:structural", "judge:fable"];
+export type ProvenanceTier = (typeof PROVENANCE_TIERS)[number];
+export interface MemoryEntryLike {
+    memory_id?: string;
+    id?: string;
+    path?: string;
+    relPath?: string;
+    frontmatter?: Record<string, unknown>;
+    body?: string;
+    kind?: string;
+    type?: string;
+    created?: string;
+    createdAt?: string;
+    tags?: unknown;
+}
+export interface Retrieval {
+    complexity: "simple" | "moderate" | "complex";
+    testExec: boolean;
+    hasCodeBlock: boolean;
+    length: number;
+}
+export interface Pattern {
+    id: string;
+    kind: "pattern";
+    summary: string;
+    uses: string[];
+    evidence: string[];
+    provenance_tier: ProvenanceTier;
+    promoted: boolean;
+    score: number;
+}
+export interface DistillationResult {
+    patterns: Pattern[];
+    promoted: Pattern[];
+    byTier: Record<ProvenanceTier, number>;
+}
+export declare function retrieve(entry: MemoryEntryLike): Retrieval;
+export declare function judge(_entry: MemoryEntryLike, retrieval: Retrieval): ProvenanceTier;
+export declare function distill(entry: MemoryEntryLike): Omit<Pattern, "provenance_tier" | "promoted" | "score"> | null;
+export declare function runDistillation(entries: MemoryEntryLike[]): DistillationResult;
+//# sourceMappingURL=memory-distillation.d.ts.map

package/packages/sdk/dist/router/memory-distillation.js

@@ -0,0 +1,195 @@
+/**
+ * router/memory-distillation.ts — RETRIEVE → JUDGE → DISTILL →
+ * CONSOLIDATE (ADR-174) as a pure TypeScript module.
+ *
+ * v6.4.0 — ported from ruflo `@claude-flow/neural/src/reasoning-bank.ts`
+ * (the 4-step pipeline) + ADR-174 (provenance-tiered promote gate).
+ *
+ * This is the $0 default path — deterministic, no LLM, no I/O.
+ * Living inside the SDK (rather than the dashboard .mjs files) so
+ * the `memory_distill` MCP tool can call it via a static TypeScript
+ * import without crossing the ESM/CJS boundary at runtime.
+ *
+ * The dashboard's `bizar-dash/src/server/memory-{distillation,
+ * consolidator}.mjs` re-export the same semantics and add the
+ * vault I/O (read notes, write promoted patterns back). Both paths
+ * agree on the `Pattern` shape so the schema is one-of.
+ */
+export const PROVENANCE_TIERS = [
+    "oracle:test-exec",
+    "proxy:structural",
+    "judge:fable",
+];
+const COMPLEXITY_SIMPLE_MAX = 600;
+const COMPLEXITY_MODERATE_MAX = 2400;
+function firstLine(s) {
+    if (!s)
+        return "";
+    const i = s.indexOf("\n");
+    return (i < 0 ? s : s.slice(0, i)).trim();
+}
+function snippet(body) {
+    const cleaned = body.replace(/\s+/g, " ").trim();
+    return cleaned.length <= 200 ? cleaned : cleaned.slice(0, 200) + "…";
+}
+function shorten(s) {
+    let h = 5381 >>> 0;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(36).slice(0, 10);
+}
+function wordSet(s) {
+    const out = new Set();
+    const norm = (s || "").toLowerCase().replace(/[^a-z0-9\s]+/g, " ");
+    for (const w of norm.split(/\s+/)) {
+        if (w.length > 2)
+            out.add(w);
+    }
+    return out;
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter += 1;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+function dedupe(arr) {
+    const seen = new Set();
+    const out = [];
+    for (const x of arr)
+        if (!seen.has(x)) {
+            seen.add(x);
+            out.push(x);
+        }
+    return out;
+}
+export function retrieve(entry) {
+    const body = String(entry?.body ?? "");
+    const fm = entry?.frontmatter ?? {};
+    const hasCodeBlock = /```/.test(body);
+    const tagsArr = Array.isArray(fm.tags) ? fm.tags : [];
+    const testExec = Boolean(fm.test_exec) ||
+        Boolean(fm.testExec) ||
+        tagsArr.some((t) => String(t).includes("test-exec")) ||
+        String(fm.kind ?? "") === "feedback";
+    const len = body.length;
+    let complexity;
+    if (hasCodeBlock || len > COMPLEXITY_MODERATE_MAX)
+        complexity = "complex";
+    else if (len > COMPLEXITY_SIMPLE_MAX)
+        complexity = "moderate";
+    else
+        complexity = "simple";
+    return { complexity, testExec, hasCodeBlock, length: len };
+}
+export function judge(_entry, retrieval) {
+    if (retrieval.testExec)
+        return "oracle:test-exec";
+    return "proxy:structural";
+}
+export function distill(entry) {
+    const fm = entry?.frontmatter ?? {};
+    const body = String(entry?.body ?? "").trim();
+    const id = String(entry?.memory_id ?? entry?.id ?? entry?.path ?? entry?.relPath ?? "");
+    const kindRaw = String(fm.kind ?? entry?.kind ?? entry?.type ?? "").toLowerCase();
+    if (kindRaw === "coding_convention" || kindRaw === "bug_pattern") {
+        return {
+            id: `pat_${shorten(id || body.slice(0, 24))}`,
+            kind: "pattern",
+            summary: firstLine(body) || "(empty)",
+            uses: id ? [id] : [],
+            evidence: [snippet(body)],
+        };
+    }
+    const head = firstLine(body).toLowerCase();
+    if (kindRaw === "task_summary" ||
+        kindRaw === "session_summary" ||
+        /\bpattern\s*:/.test(head) ||
+        /^\s*(use|avoid|do|don't)\s*:/.test(head)) {
+        return {
+            id: `pat_${shorten(id || head.replace(/\W+/g, " ").slice(0, 24))}`,
+            kind: "pattern",
+            summary: firstLine(body) || "(empty)",
+            uses: id ? [id] : [],
+            evidence: [snippet(body)],
+        };
+    }
+    return null;
+}
+export function runDistillation(entries) {
+    const empty = {
+        patterns: [],
+        promoted: [],
+        byTier: { "oracle:test-exec": 0, "proxy:structural": 0, "judge:fable": 0 },
+    };
+    if (!Array.isArray(entries) || entries.length === 0)
+        return empty;
+    const candidates = [];
+    for (const entry of entries) {
+        const retrieval = retrieve(entry);
+        const tier = judge(entry, retrieval);
+        const pattern = distill(entry);
+        if (!pattern)
+            continue;
+        candidates.push({ ...pattern, _tier: tier });
+    }
+    // Cluster by Jaccard similarity ≥ 0.5 over (summary + evidence).
+    const groups = [];
+    for (const c of candidates) {
+        const ws = wordSet(c.summary + " " + c.evidence.join(" "));
+        let placed = false;
+        for (const g of groups) {
+            const gs = wordSet(g.rep.summary + " " + g.rep.evidence.join(" "));
+            if (jaccard(ws, gs) >= 0.5) {
+                g.members.push(c);
+                placed = true;
+                break;
+            }
+        }
+        if (!placed)
+            groups.push({ rep: c, members: [c] });
+    }
+    const byTier = {
+        "oracle:test-exec": 0,
+        "proxy:structural": 0,
+        "judge:fable": 0,
+    };
+    const patterns = [];
+    for (const g of groups) {
+        const usesSet = new Set();
+        const evidence = [];
+        for (const m of g.members) {
+            for (const u of m.uses ?? [])
+                usesSet.add(u);
+            for (const e of m.evidence ?? [])
+                evidence.push(e);
+        }
+        const tiers = g.members.map((m) => m._tier);
+        let tier = "proxy:structural";
+        if (tiers.includes("oracle:test-exec"))
+            tier = "oracle:test-exec";
+        else if (tiers.includes("judge:fable"))
+            tier = "judge:fable";
+        const promoted = usesSet.size >= 1 && (tier === "oracle:test-exec" || tier === "judge:fable");
+        const pattern = {
+            id: g.rep.id,
+            kind: "pattern",
+            summary: g.rep.summary,
+            uses: Array.from(usesSet),
+            evidence: dedupe(evidence).slice(0, 5),
+            provenance_tier: tier,
+            promoted,
+            score: 0.5 + usesSet.size * 0.1,
+        };
+        patterns.push(pattern);
+        byTier[tier] += 1;
+    }
+    const promoted = patterns.filter((p) => p.promoted);
+    return { patterns, promoted, byTier };
+}
+//# sourceMappingURL=memory-distillation.js.map

package/packages/sdk/dist/router/model-router.d.ts

@@ -0,0 +1,83 @@
+/**
+ * router/model-router.ts — Adaptive model-tier router.
+ *
+ * v6.4.0 — ported from ruflo `model-router.ts` (Thompson-sampling bandit,
+ * ADR-026 + ADR-143). Trims the surface to what Bizar needs:
+ *
+ *   - 3 tiers:  `flash` (cheap),  `mid` (default),  `expensive`
+ *   - Per-tier Beta(α, β) priors, updated by `recordOutcome()`.
+ *   - Marsaglia-Tsang Gamma sampler + Box-Muller normal → sample from Beta
+ *     by drawing two Gamma(shape, 1) variates and dividing.
+ *   - Tier-1 codemod short-circuit: if `detectCodemodIntent()` says the
+ *     prompt is codemod-eligible, we return `{tier: 'flash'}` with
+ *     confidence 1.0 and tag `codemodIntent` on the result. This is the
+ *     $0 path — no model call required.
+ *
+ * The tier names match Bizar's actual model lineup
+ * (`m2.7-flash`, `m2.7`, `m3`). The ruflo vocabulary uses
+ * `haiku / sonnet / opus`; we rename to `flash / mid / expensive`
+ * so future call-site code reads naturally.
+ */
+export type ModelTier = "flash" | "mid" | "expensive";
+export interface RouteDecision {
+    tier: ModelTier;
+    confidence: number;
+    codemodIntent?: "var-to-const" | "remove-console" | "add-logging";
+}
+export interface BetaPrior {
+    alpha: number;
+    beta: number;
+}
+export declare class ModelRouter {
+    private priors;
+    private rngState;
+    constructor(opts?: {
+        priors?: Partial<Record<ModelTier, BetaPrior>>;
+        seed?: number;
+    });
+    /** Read-only access for telemetry / tests. */
+    getPriors(): Record<ModelTier, BetaPrior>;
+    /**
+     * Pick a tier for `prompt`. Codemod-eligible prompts short-circuit
+     * to `flash` (the Tier-1 $0 path). Otherwise we Thompson-sample each
+     * tier and return the highest sample, with confidence = max_sample
+     * (the posterior mean is `α/(α+β)`, and the max-sampled value is a
+     * lower bound on the probability that this tier beats the others).
+     */
+    route(prompt: string): RouteDecision;
+    /**
+     * Update the per-tier prior after observing the outcome of a call.
+     * `success === true` increments α; `success === false` increments β.
+     * Cost-adjusted (ruflo ADR-026 §BANDIT_REWARDS):
+     * - flash-success:    +1.0 → α++           (cheap wins are gold)
+     * - mid-success:      +0.7 → α += 0.7      (still good)
+     * - expensive-success:+0.4 → α += 0.4      (expensive wins are wasteful)
+     * - any failure:      β ++
+     *
+     * The fractional updates work fine with the Beta sampler.
+     */
+    recordOutcome(tier: ModelTier, success: boolean): void;
+    /** Seeded or Math.random()-backed uniform in [0,1). */
+    private random;
+    /** Box-Muller standard normal sample. */
+    private sampleStandardNormal;
+    /** Marsaglia-Tsang Gamma sample for shape α≥1 (with boost for α<1). */
+    private sampleGamma;
+    /** Sample from Beta(α, β) via two Gamma draws. */
+    private sampleBeta;
+    /** JSON snapshot of the current per-tier priors + RNG seed. */
+    snapshot(): RouterStateSnapshot;
+    /** Restore from a snapshot; defaults applied where fields are missing. */
+    static fromSnapshot(snap: Partial<RouterStateSnapshot>): ModelRouter;
+    /** Persist state to `path`. Creates parent dirs as needed. */
+    saveTo(path: string): void;
+    /** Load state from `path`. Returns a default router if file is
+     *  missing or unparseable. Does NOT throw. */
+    static loadFrom(path: string): ModelRouter;
+}
+export interface RouterStateSnapshot {
+    version: number;
+    priors: Record<ModelTier, BetaPrior>;
+    rngSeed: number;
+}
+//# sourceMappingURL=model-router.d.ts.map

package/packages/sdk/dist/router/model-router.js

@@ -0,0 +1,207 @@
+/**
+ * router/model-router.ts — Adaptive model-tier router.
+ *
+ * v6.4.0 — ported from ruflo `model-router.ts` (Thompson-sampling bandit,
+ * ADR-026 + ADR-143). Trims the surface to what Bizar needs:
+ *
+ *   - 3 tiers:  `flash` (cheap),  `mid` (default),  `expensive`
+ *   - Per-tier Beta(α, β) priors, updated by `recordOutcome()`.
+ *   - Marsaglia-Tsang Gamma sampler + Box-Muller normal → sample from Beta
+ *     by drawing two Gamma(shape, 1) variates and dividing.
+ *   - Tier-1 codemod short-circuit: if `detectCodemodIntent()` says the
+ *     prompt is codemod-eligible, we return `{tier: 'flash'}` with
+ *     confidence 1.0 and tag `codemodIntent` on the result. This is the
+ *     $0 path — no model call required.
+ *
+ * The tier names match Bizar's actual model lineup
+ * (`m2.7-flash`, `m2.7`, `m3`). The ruflo vocabulary uses
+ * `haiku / sonnet / opus`; we rename to `flash / mid / expensive`
+ * so future call-site code reads naturally.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { detectCodemodIntent } from "./codemod-intent.js";
+const TIERS = ["flash", "mid", "expensive"];
+/**
+ * Default priors — slight optimism for `flash` (so it gets tried for
+ * cheap prompts), uniform for `mid`, slight pessimism for `expensive`
+ * (it should have to earn its keep). Adjust here, not at the call site.
+ */
+const DEFAULT_PRIORS = {
+    flash: { alpha: 2, beta: 1 }, // mean 2/3 ≈ 0.67
+    mid: { alpha: 1, beta: 1 }, // mean 0.5
+    expensive: { alpha: 1, beta: 2 }, // mean 1/3 ≈ 0.33
+};
+export class ModelRouter {
+    priors;
+    rngState;
+    constructor(opts) {
+        this.priors = {
+            flash: { ...DEFAULT_PRIORS.flash, ...(opts?.priors?.flash ?? {}) },
+            mid: { ...DEFAULT_PRIORS.mid, ...(opts?.priors?.mid ?? {}) },
+            expensive: { ...DEFAULT_PRIORS.expensive, ...(opts?.priors?.expensive ?? {}) },
+        };
+        // LCG seed for reproducible sampling in tests. Default uses
+        // Math.random() when seed is not provided.
+        this.rngState = (opts?.seed ?? 0) | 0;
+    }
+    /** Read-only access for telemetry / tests. */
+    getPriors() {
+        return {
+            flash: { ...this.priors.flash },
+            mid: { ...this.priors.mid },
+            expensive: { ...this.priors.expensive },
+        };
+    }
+    /**
+     * Pick a tier for `prompt`. Codemod-eligible prompts short-circuit
+     * to `flash` (the Tier-1 $0 path). Otherwise we Thompson-sample each
+     * tier and return the highest sample, with confidence = max_sample
+     * (the posterior mean is `α/(α+β)`, and the max-sampled value is a
+     * lower bound on the probability that this tier beats the others).
+     */
+    route(prompt) {
+        // Tier-1 codemod short-circuit ($0).
+        const cm = detectCodemodIntent(prompt);
+        if (cm !== null) {
+            return { tier: "flash", confidence: 1.0, codemodIntent: cm.intent };
+        }
+        let best = null;
+        for (const tier of TIERS) {
+            const prior = this.priors[tier];
+            const sample = this.sampleBeta(prior.alpha, prior.beta);
+            if (best === null || sample > best.sample) {
+                best = { tier, sample };
+            }
+        }
+        const confidence = clamp01(best ? best.sample : 0.5);
+        return { tier: best ? best.tier : "mid", confidence };
+    }
+    /**
+     * Update the per-tier prior after observing the outcome of a call.
+     * `success === true` increments α; `success === false` increments β.
+     * Cost-adjusted (ruflo ADR-026 §BANDIT_REWARDS):
+     * - flash-success:    +1.0 → α++           (cheap wins are gold)
+     * - mid-success:      +0.7 → α += 0.7      (still good)
+     * - expensive-success:+0.4 → α += 0.4      (expensive wins are wasteful)
+     * - any failure:      β ++
+     *
+     * The fractional updates work fine with the Beta sampler.
+     */
+    recordOutcome(tier, success) {
+        const prior = this.priors[tier];
+        if (!prior)
+            return;
+        if (success) {
+            const reward = tier === "flash" ? 1.0 : tier === "mid" ? 0.7 : 0.4;
+            prior.alpha += reward;
+        }
+        else {
+            prior.beta += 1;
+        }
+    }
+    // -----------------------------------------------------------------
+    // Sampling primitives (lifted from ruflo model-router.ts).
+    // Marsaglia-Tsang Gamma + Box-Muller normal. Module-local so we
+    // don't pull a stats library for one sampler.
+    // -----------------------------------------------------------------
+    /** Seeded or Math.random()-backed uniform in [0,1). */
+    random() {
+        if (this.rngState !== 0) {
+            // LCG (Numerical Recipes). Period ~2^32.
+            this.rngState = (this.rngState * 1664525 + 1013904223) | 0;
+            const u = (this.rngState >>> 0) / 0xffffffff;
+            return u || 1e-12;
+        }
+        return Math.random() || 1e-12;
+    }
+    /** Box-Muller standard normal sample. */
+    sampleStandardNormal() {
+        const u1 = this.random();
+        const u2 = this.random();
+        return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+    }
+    /** Marsaglia-Tsang Gamma sample for shape α≥1 (with boost for α<1). */
+    sampleGamma(alpha) {
+        if (alpha < 1) {
+            const u = this.random();
+            return this.sampleGamma(alpha + 1) * Math.pow(u, 1 / alpha);
+        }
+        const d = alpha - 1 / 3;
+        const c = 1 / Math.sqrt(9 * d);
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            let x = this.sampleStandardNormal();
+            let v = 1 + c * x;
+            if (v <= 0)
+                continue;
+            v = v * v * v;
+            const u = this.random();
+            const xx = x * x;
+            if (u < 1 - 0.0331 * xx * xx)
+                return d * v;
+            if (Math.log(u) < 0.5 * xx + d * (1 - v + Math.log(v)))
+                return d * v;
+        }
+    }
+    /** Sample from Beta(α, β) via two Gamma draws. */
+    sampleBeta(alpha, beta) {
+        const x = this.sampleGamma(alpha);
+        const y = this.sampleGamma(beta);
+        const denom = x + y;
+        if (denom <= 0)
+            return alpha / (alpha + beta);
+        return x / denom;
+    }
+    // -----------------------------------------------------------------
+    // Persistence (ADR-174 invariant: router state survives restarts).
+    // We avoid native deps — `.harness/router-state.json` is the
+    // canonical store; loading is best-effort and falls back to
+    // defaults if the file is missing or corrupt.
+    // -----------------------------------------------------------------
+    /** JSON snapshot of the current per-tier priors + RNG seed. */
+    snapshot() {
+        return {
+            version: 1,
+            priors: this.getPriors(),
+            rngSeed: this.rngState,
+        };
+    }
+    /** Restore from a snapshot; defaults applied where fields are missing. */
+    static fromSnapshot(snap) {
+        return new ModelRouter({
+            priors: snap.priors,
+            seed: snap.rngSeed,
+        });
+    }
+    /** Persist state to `path`. Creates parent dirs as needed. */
+    saveTo(path) {
+        const fp = isAbsolute(path) ? path : resolve(path);
+        mkdirSync(dirname(fp), { recursive: true });
+        writeFileSync(fp, JSON.stringify(this.snapshot(), null, 2), "utf-8");
+    }
+    /** Load state from `path`. Returns a default router if file is
+     *  missing or unparseable. Does NOT throw. */
+    static loadFrom(path) {
+        try {
+            if (!existsSync(path))
+                return new ModelRouter();
+            const raw = readFileSync(path, "utf-8");
+            const snap = JSON.parse(raw);
+            return ModelRouter.fromSnapshot(snap);
+        }
+        catch {
+            return new ModelRouter();
+        }
+    }
+}
+function clamp01(n) {
+    if (Number.isNaN(n))
+        return 0;
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+//# sourceMappingURL=model-router.js.map

package/packages/sdk/dist/router/q-learning-router.d.ts

@@ -0,0 +1,85 @@
+/**
+ * router/q-learning-router.ts — Q-learning agent router.
+ *
+ * v6.4.0 — ported from ruflo `q-learning-router.ts` (8-action softmax
+ * agent-route over coder / tester / reviewer / …).
+ *
+ * Bizar has more than 8 named agents, so the action set is the 8 most
+ * commonly delegated targets from `Agent` tool calls (matches
+ * `.claude/agents/*.md` to first 8 names). Adding the full
+ * 12-agent space could be done in a follow-up but each new agent
+ * increases state-action coverage cost; 8 keeps the bandit honest.
+ *
+ *   - State: a 64-dim bag-of-words hash of the task string (FNV-1a
+ *     folded into 64 buckets). LRU-cached so repeated task patterns
+ *     are O(1).
+ *   - Action: one of `odin|frigg|vor|mimir|heimdall|thor|tyr|forseti`.
+ *   - Reward: `+1` on `recordOutcome(agent, true)`, `0` on false.
+ *   - Exploration: ε-greedy with ε = 0.1 (configurable).
+ *
+ * `selectAgent()` returns `{agent, confidence}`. `confidence` is the
+ * posterior mean of the picked action's Q-value clamped to [0,1].
+ *
+ * Tiny surface area by design — the
+ * `AgentRouteDecision` shape is what `model_route` /
+ * `agent_route` MCP tools expose.
+ */
+export declare const AGENT_ACTIONS: readonly string[];
+export type AgentName = (typeof AGENT_ACTIONS)[number];
+export interface AgentRouteDecision {
+    agent: string;
+    confidence: number;
+}
+export interface QLearningRouterOpts {
+    stateDim?: number;
+    epsilon?: number;
+    lruSize?: number;
+    seed?: number;
+}
+export declare class QLearningRouter {
+    private readonly stateDim;
+    private readonly epsilon;
+    private readonly lruSize;
+    private readonly q;
+    private readonly counts;
+    private readonly lru;
+    private rngState;
+    constructor(opts?: QLearningRouterOpts);
+    /**
+     * Greedy ε-soft policy. Returns a cached decision when the same
+     * (task) hash has been seen recently (LRU bounded by `lruSize`).
+     * Codemod-eligible prompts short-circuit to `heimdall` (the
+     * routine-implementation agent) so they still get a "best" agent
+     * without paying the bandit lookup cost twice.
+     */
+    selectAgent(task: string): AgentRouteDecision;
+    /**
+     * EMA update of Q[agentIdx][bucket]. Uses the standard
+     *   Q ← Q + α (reward − Q)
+     * where α = 1 / (1 + count) — decreasing step size over time.
+     */
+    recordOutcome(agent: string, success: boolean): void;
+    /** Read-only access for tests / telemetry. */
+    snapshot(): Array<{
+        agent: string;
+        qMean: number;
+        n: number;
+    }>;
+    /** Stable on-disk serialisation: Q-table per agent, counts, seed. */
+    fullSnapshot(): QLearningSnapshot;
+    static fromSnapshot(snap: Partial<QLearningSnapshot>): QLearningRouter;
+    saveTo(path: string): void;
+    static loadFrom(path: string): QLearningRouter;
+    /** FNV-1a 32-bit hash, folded into [0, stateDim). Bag-of-words. */
+    private bucketize;
+    private random;
+}
+export interface QLearningSnapshot {
+    version: number;
+    stateDim: number;
+    epsilon: number;
+    q: number[][];
+    counts: number[][];
+    rngSeed: number;
+}
+//# sourceMappingURL=q-learning-router.d.ts.map