@claude-flow/cli 3.42.5 → 3.43.0

package/dist/src/memory/memory-bridge.js

@@ -801,6 +801,52 @@ async function rescueAgentdbEmbedder(agentdb) {
     emb.__ruvectorRescued = true;
     _embedderPatched = true;
 }
+/**
+ * #3325: embed text for a bridge row or query.
+ *
+ * AgentDB's embedder is tried first. If it is absent or throws, fall back to
+ * the LOCAL chain — `generateLocalEmbedding`, never the bridge-first
+ * `generateEmbedding`, which would re-enter this bridge (#2312). Only a real
+ * ONNX vector is accepted from the local chain; a hash vector would make the
+ * row look embedded while carrying no meaning. Previously both failure modes
+ * were a bare `catch {}` that stored embedding=NULL and reported nothing.
+ */
+async function embedForBridge(agentdb, text) {
+    let agentdbProblem;
+    const embedder = agentdb?.embedder;
+    // Same mock signal bridgeGenerateEmbedding honours (AUDIT #3): the rescue
+    // tags a degraded embedder backend='mock' when it cannot replace it.
+    const agentdbIsMock = embedder?.isMock === true || embedder?.backend === 'mock';
+    if (agentdbIsMock) {
+        agentdbProblem = 'agentdb embedder is serving mock vectors';
+    }
+    else if (embedder && typeof embedder.embed === 'function') {
+        try {
+            const emb = await embedder.embed(text);
+            if (emb && emb.length > 0) {
+                return { vector: Array.from(emb), model: 'Xenova/all-MiniLM-L6-v2' };
+            }
+            agentdbProblem = 'agentdb embedder returned no vector';
+        }
+        catch (err) {
+            agentdbProblem = `agentdb embedder threw: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    else {
+        agentdbProblem = 'agentdb embedder unavailable';
+    }
+    try {
+        const { generateLocalEmbedding } = await import('./memory-initializer.js');
+        const local = await generateLocalEmbedding(text);
+        if (local.backend === 'onnx' && local.embedding.length > 0) {
+            return { vector: Array.from(local.embedding), model: local.model };
+        }
+        return { vector: null, reason: `${agentdbProblem}; local embedding chain has no real model (backend=${local.backend})` };
+    }
+    catch (err) {
+        return { vector: null, reason: `${agentdbProblem}; local embedding chain failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 // ===== Bridge functions — match memory-initializer.ts signatures =====
 /**
  * Store an entry via AgentDB v3.
@@ -851,26 +897,24 @@ export async function bridgeStoreEntry(options) {
         if (!guardResult.allowed) {
             return { success: false, id, error: `MutationGuard rejected: ${guardResult.reason}` };
         }
-        // Generate embedding via AgentDB's embedder
+        // Generate embedding via AgentDB's embedder, falling back to the local
+        // chain (#3325). If neither can produce one, the row is still written but
+        // the result says why instead of silently storing embedding=NULL.
         let embeddingJson = null;
         let embeddingArr = null;
         let dimensions = 0;
         let model = 'local';
+        let embeddingError;
         if (options.generateEmbeddingFlag !== false && value.length > 0) {
-            try {
-                const embedder = ctx.agentdb.embedder;
-                if (embedder) {
-                    const emb = await embedder.embed(value);
-                    if (emb) {
-                        embeddingArr = Array.from(emb);
-                        embeddingJson = JSON.stringify(embeddingArr);
-                        dimensions = emb.length;
-                        model = 'Xenova/all-MiniLM-L6-v2';
-                    }
-                }
+            const emb = await embedForBridge(ctx.agentdb, value);
+            if (emb.vector) {
+                embeddingArr = emb.vector;
+                embeddingJson = JSON.stringify(embeddingArr);
+                dimensions = embeddingArr.length;
+                model = emb.model;
             }
-            catch {
-                // Embedding failed — store without
+            else {
+                embeddingError = emb.reason;
             }
         }
         // #2775: strict-insert path now auto-resurrects soft-deleted tombstones
@@ -1011,6 +1055,7 @@ export async function bridgeStoreEntry(options) {
             cached: true,
             attested: true,
             ...(persistWarning ? { persistWarning } : {}),
+            ...(embeddingError ? { embeddingError } : {}),
         };
     }
     catch (err) {
@@ -1061,18 +1106,10 @@ export async function bridgeSearchEntries(options) {
         const { query: queryStr, namespace, limit = 10, threshold = 0.3, provenanceFilter } = options;
         const effectiveNamespace = namespace || 'all';
         const startTime = Date.now();
-        // Generate query embedding
-        let queryEmbedding = null;
-        try {
-            const embedder = ctx.agentdb.embedder;
-            if (embedder) {
-                const emb = await embedder.embed(queryStr);
-                queryEmbedding = Array.from(emb);
-            }
-        }
-        catch {
-            // Fall back to keyword search
-        }
+        // Generate query embedding — same agentdb-then-local chain as the write
+        // path (#3325), so rows embedded by the local fallback are searchable.
+        // No vector → keyword (BM25) search only.
+        const queryEmbedding = (await embedForBridge(ctx.agentdb, queryStr)).vector;
         // better-sqlite3: .prepare().all() returns array of objects
         // ADR-323: compose namespace + provenance filters into one WHERE clause.
         const filters = [];
@@ -1300,7 +1337,10 @@ export async function bridgeGetEntry(options) {
                     accessCount: cached.accessCount ?? 0,
                     createdAt: cached.createdAt || new Date().toISOString(),
                     updatedAt: cached.updatedAt || new Date().toISOString(),
-                    hasEmbedding: !!cached.embedding,
+                    // #3325: the cache holds the `entry` object built below, which has
+                    // `hasEmbedding` but no `embedding` field — so `!!cached.embedding`
+                    // reported false on every cache hit, even for embedded rows.
+                    hasEmbedding: typeof cached.hasEmbedding === 'boolean' ? cached.hasEmbedding : !!cached.embedding,
                     tags: cached.tags || [],
                 },
             };
@@ -1888,7 +1928,15 @@ export async function bridgeStorePattern(options) {
         // was actually stored under. getEntry/memory_retrieve look up by `key`,
         // so returning result.id here handed the caller a handle that can never
         // be read back — return `patternId` (the real key) instead.
-        return { success: true, patternId, controller: 'bridge-fallback' };
+        // #3325: say whether the row got a vector. Without one, Tier-1 (semantic)
+        // pattern search cannot find it — report that here, at write time.
+        return {
+            success: true,
+            patternId,
+            controller: 'bridge-fallback',
+            hasEmbedding: !!result.embedding,
+            ...(result.embeddingError ? { embeddingError: result.embeddingError } : {}),
+        };
     }
     catch (err) {
         // #3327 Finding A — this catch is what hid the defect for months. When

package/dist/src/memory/memory-initializer.d.ts

@@ -452,6 +452,9 @@ export declare function storeEntry(options: {
     /** #2968: set when the bridge's checkpoint failed in a way indicating
      *  this write may not be durably persisted (sql.js fallback driver). */
     persistWarning?: string;
+    /** #3325: set by the bridge when an embedding was requested but none could
+     *  be produced — the row is stored without a vector. */
+    embeddingError?: string;
 }>;
 /**
  * Search entries using sql.js with vector similarity

package/dist/src/memory/memory-initializer.js

@@ -81,6 +81,23 @@ function hasNativeWalSidecars(dbPath) {
         return true;
     }
 }
+/**
+ * #3397 — this process's own graph-edge-writer handle keeps -wal/-shm on disk
+ * between its idle-release ticks. Release (checkpoint + close) it before the
+ * #2735 guard runs, so the guard only sees sidecars some OTHER native
+ * connection is holding. The guard itself is unchanged: even a same-process
+ * open WAL connection makes a whole-image sql.js write unsafe until its WAL
+ * has been checkpointed, which is exactly what releasing does.
+ */
+async function releaseOwnNativeHandle(dbPath) {
+    try {
+        const { releaseBridgeDb } = await import('./graph-edge-writer.js');
+        releaseBridgeDb(dbPath);
+    }
+    catch {
+        // Writer module unavailable — nothing of ours to release; the guard decides.
+    }
+}
 /**
  * #1854: previously every site that needed the memory directory hardcoded
  * `getMemoryRoot()`, so the documented config entry
@@ -1957,7 +1974,17 @@ export async function applyTemporalDecay(dbPath) {
         };
     }
 }
+/**
+ * State of the LOCAL embedding chain only (transformers.js / agentic-flow /
+ * ruvector ONNX / hash). #3375: the AgentDB bridge's result is cached
+ * separately in `bridgeEmbeddingInfo` and must never be written here — it used
+ * to be recorded as `{ loaded: true, model: null }`, which made
+ * generateLocalEmbedding() skip loading any local model and always return the
+ * hash fallback, so rescueAgentdbEmbedder()'s `backend === 'onnx'` probe could
+ * never pass.
+ */
 let embeddingModelState = null;
+let bridgeEmbeddingInfo = null;
 /**
  * Lazy load ONNX embedding model
  * Only loads when first embedding is requested
@@ -1966,10 +1993,11 @@ export async function loadEmbeddingModel(options) {
     const { verbose = false } = options || {};
     const startTime = Date.now();
     // Already loaded
-    if (embeddingModelState?.loaded) {
+    const cached = bridgeEmbeddingInfo ?? (embeddingModelState?.loaded ? embeddingModelState : null);
+    if (cached) {
         return {
             success: true,
-            dimensions: embeddingModelState.dimensions,
+            dimensions: cached.dimensions,
             modelName: 'cached',
             loadTime: 0
         };
@@ -1979,16 +2007,24 @@ export async function loadEmbeddingModel(options) {
     if (bridge) {
         const bridgeResult = await bridge.bridgeLoadEmbeddingModel();
         if (bridgeResult && bridgeResult.success) {
-            // Mark local state as loaded too so subsequent calls use cache
-            embeddingModelState = {
-                loaded: true,
-                model: null, // Bridge handles embedding
-                tokenizer: null,
-                dimensions: bridgeResult.dimensions
-            };
+            // #3375: cache the bridge result on its own. Do NOT mark the local
+            // chain as loaded — the bridge's model is not callable from here.
+            bridgeEmbeddingInfo = { dimensions: bridgeResult.dimensions };
             return bridgeResult;
         }
     }
+    return loadLocalEmbeddingChain(verbose, startTime);
+}
+/**
+ * Load the LOCAL embedding chain into `embeddingModelState`, never consulting
+ * the AgentDB bridge. Used by loadEmbeddingModel() after the bridge declines,
+ * and directly by generateLocalEmbedding() so the "bridge-free" contract the
+ * #2312 comment on that function describes actually holds (#3375).
+ */
+async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now()) {
+    if (embeddingModelState?.loaded) {
+        return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+    }
     try {
         // ADR-094: prefer @huggingface/transformers (clears protobufjs <7.5.5
         // critical RCE chain), fall back to legacy @xenova/transformers.
@@ -2195,9 +2231,12 @@ export async function generateEmbedding(text) {
  * Keeping the local chain as its own export breaks that cycle structurally.
  */
 export async function generateLocalEmbedding(text) {
-    // Ensure model is loaded
+    // Ensure the LOCAL model is loaded. #3375: this must not go through
+    // loadEmbeddingModel(), which is bridge-first — when the bridge answered
+    // there, no local model was ever loaded and this function always returned
+    // the hash fallback.
     if (!embeddingModelState?.loaded) {
-        await loadEmbeddingModel();
+        await loadLocalEmbeddingChain();
     }
     // #2461: loadEmbeddingModel() can leave embeddingModelState null when an
     // earlier loader (transformers fetch, ruvector init) throws and we never
@@ -2535,6 +2574,7 @@ export async function storeEntry(options) {
         // this closes and its known residual (the narrow assess-then-write
         // race). This check gates ensureSchemaColumns()'s own whole-image
         // write below too, not just this function's.
+        await releaseOwnNativeHandle(dbPath);
         if (hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,
@@ -3043,6 +3083,7 @@ export async function getEntry(options) {
         // this closes. Applies here too because the fallback's access_count
         // bump is itself a whole-image write, not a lightweight read, even
         // though this function's contract reads as a "get".
+        await releaseOwnNativeHandle(dbPath);
         if (hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,
@@ -3162,6 +3203,7 @@ export async function deleteEntry(options) {
         }
         // #2735 — see storeEntry's identical gate for the corruption mechanism
         // this closes.
+        await releaseOwnNativeHandle(dbPath);
         if (hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,

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

@@ -0,0 +1,119 @@
+/**
+ * typesafe-router.ts — opt-in `@ruvector/typesafe` augmentation for `hooks_route`.
+ *
+ * Mirrors ADR-150's MetaHarness rules for optional integrations:
+ *   1. Removable — the package is loaded with a dynamic import only; any load,
+ *      construction or decide error falls back to the existing router.
+ *   2. Opt-in    — does nothing unless `CLAUDE_FLOW_ROUTER_TYPESAFE=1`. With the
+ *      flag unset the package is never imported and the legacy result is
+ *      returned unchanged (same object, no added fields).
+ *   3. Optional  — declared as an optional peer of `@claude-flow/cli`.
+ *   4. Honest    — the result carries `routedBy`, typesafe's confidence, abstain
+ *      mass and `calibrated` flag verbatim. The default `hash` embedder is
+ *      uncalibrated, so its confidence is reported as `confidenceCalibrated:
+ *      false` and is never copied into `estimatedMetrics.successProbability`.
+ *
+ * Gate: typesafe's answer is used only when all hold —
+ *   - `abstain <= maxAbstain` (default 0.30)
+ *   - lift = top-1 probability × option count >= `minLift` (default 1.2, i.e.
+ *     20% above chance). Lift, not raw confidence, because confidence scales
+ *     with the option count (~0.1 for ten agents) and differs per embedder.
+ *   - top-1 beats the runner-up by >= `minMargin` (default 0.005); a uniform
+ *     distribution — text that matches nothing — has margin 0.
+ * Otherwise the legacy route is kept and `typesafe.reason` says which gate failed.
+ *
+ * @module typesafe-router
+ */
+/** Keyword/agent table shape shared with hooks-tools' TASK_PATTERNS. */
+export interface RoutingPatternLike {
+    keywords: string[];
+    agents: string[];
+}
+/** One `choice` option in typesafe's `{ what, not_for, examples }` form. */
+export interface TypesafeCriterion {
+    what: string;
+    not_for?: string;
+    examples?: string[];
+}
+/** The subset of a typesafe choice answer this adapter reads. */
+export interface TypesafeChoiceAnswer {
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+    abstain: number;
+    calibrated: boolean;
+    head?: string;
+    model?: string;
+}
+/** The subset of `@ruvector/typesafe`'s module surface this adapter uses. */
+export interface TypesafeModuleLike {
+    createTypesafe(opts?: Record<string, unknown>): {
+        readonly backend?: string;
+        decide(state: string, questions: Record<string, unknown>): Promise<Record<string, unknown>>;
+    };
+    choice?(criteria: Record<string, TypesafeCriterion>): unknown;
+}
+export interface TypesafeRouterConfig {
+    enabled: boolean;
+    minLift: number;
+    maxAbstain: number;
+    minMargin: number;
+    /** `'hash'` (default, uncalibrated) or an ONNX model dir + manifest. */
+    embedder: 'hash' | {
+        kind: 'onnx';
+        modelDir: string;
+        manifest: string;
+    };
+}
+export interface TypesafeRouteOutcome {
+    used: boolean;
+    reason: string;
+    answer?: TypesafeChoiceAnswer;
+    backend?: string;
+    embedder?: string;
+    /** top-1 probability × option count (1.0 = chance). */
+    lift?: number;
+    thresholds: Pick<TypesafeRouterConfig, 'minLift' | 'maxAbstain' | 'minMargin'>;
+}
+/** Injectable deps (tests). `loadModule` defaults to a dynamic import of the package. */
+export interface TypesafeRouterDeps {
+    env?: NodeJS.ProcessEnv;
+    loadModule?: () => Promise<unknown>;
+    debug?: (msg: string) => void;
+}
+/**
+ * Build choice options from the router's pattern table: every primary agent of
+ * a pattern, plus the profiled roles (researcher/reviewer) the table only lists
+ * as alternates. Each pattern's keywords are appended to its primary agent's
+ * `what`, so the options track TASK_PATTERNS rather than a parallel list.
+ */
+export declare function buildAgentCriteria(patterns: Record<string, RoutingPatternLike>): Record<string, TypesafeCriterion>;
+/** Read config from env. Invalid numeric values fall back to the defaults. */
+export declare function readTypesafeConfig(env?: NodeJS.ProcessEnv): TypesafeRouterConfig;
+/**
+ * Stateful router: loads the module and builds one engine on first use, caches
+ * a load failure so a missing package costs one import attempt per process.
+ */
+export declare class TypesafeRouter {
+    private engine;
+    private mod;
+    private loadError;
+    private readonly env;
+    private readonly loadModule;
+    private readonly debug;
+    constructor(deps?: TypesafeRouterDeps);
+    isEnabled(): boolean;
+    private ensureEngine;
+    /** Ask typesafe for an agent. Never throws; `used: false` means keep the legacy route. */
+    route(task: string, patterns: Record<string, RoutingPatternLike>): Promise<TypesafeRouteOutcome>;
+}
+type RouteResult = Record<string, unknown>;
+/**
+ * Merge a typesafe outcome into a legacy `hooks_route` result. Disabled or
+ * error results (`success: false`) pass through untouched.
+ */
+export declare function applyTypesafeRouting(params: Record<string, unknown>, legacy: RouteResult, patterns: Record<string, RoutingPatternLike>, router: TypesafeRouter): Promise<RouteResult>;
+/** Process-wide router used by hooks_route. */
+export declare function getTypesafeRouter(): TypesafeRouter;
+export {};
+//# sourceMappingURL=typesafe-router.d.ts.map

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

@@ -0,0 +1,245 @@
+/**
+ * typesafe-router.ts — opt-in `@ruvector/typesafe` augmentation for `hooks_route`.
+ *
+ * Mirrors ADR-150's MetaHarness rules for optional integrations:
+ *   1. Removable — the package is loaded with a dynamic import only; any load,
+ *      construction or decide error falls back to the existing router.
+ *   2. Opt-in    — does nothing unless `CLAUDE_FLOW_ROUTER_TYPESAFE=1`. With the
+ *      flag unset the package is never imported and the legacy result is
+ *      returned unchanged (same object, no added fields).
+ *   3. Optional  — declared as an optional peer of `@claude-flow/cli`.
+ *   4. Honest    — the result carries `routedBy`, typesafe's confidence, abstain
+ *      mass and `calibrated` flag verbatim. The default `hash` embedder is
+ *      uncalibrated, so its confidence is reported as `confidenceCalibrated:
+ *      false` and is never copied into `estimatedMetrics.successProbability`.
+ *
+ * Gate: typesafe's answer is used only when all hold —
+ *   - `abstain <= maxAbstain` (default 0.30)
+ *   - lift = top-1 probability × option count >= `minLift` (default 1.2, i.e.
+ *     20% above chance). Lift, not raw confidence, because confidence scales
+ *     with the option count (~0.1 for ten agents) and differs per embedder.
+ *   - top-1 beats the runner-up by >= `minMargin` (default 0.005); a uniform
+ *     distribution — text that matches nothing — has margin 0.
+ * Otherwise the legacy route is kept and `typesafe.reason` says which gate failed.
+ *
+ * @module typesafe-router
+ */
+const MODULE_ID = '@ruvector/typesafe';
+/**
+ * Default loader. The variable specifier keeps tsc/bundlers off the optional peer;
+ * `require` (the package is CJS) covers hosts that rewrite dynamic import (vite-node).
+ * An absent package still surfaces as MODULE_NOT_FOUND → "not installed".
+ */
+async function loadTypesafeModule() {
+    try {
+        return await import(/* @vite-ignore */ MODULE_ID);
+    }
+    catch (importErr) {
+        try {
+            const { createRequire } = await import('node:module');
+            return createRequire(import.meta.url)(MODULE_ID);
+        }
+        catch (requireErr) {
+            throw requireErr?.code === 'MODULE_NOT_FOUND' ? requireErr : importErr;
+        }
+    }
+}
+/** Agent descriptions + `not_for` hints that separate neighbouring roles. */
+const AGENT_PROFILES = {
+    tester: { what: 'write and run unit tests, integration tests, e2e tests, test coverage and specs', not_for: 'reviewing code, researching issues or reading the latest news' },
+    reviewer: { what: 'review code quality, pull requests, diffs and best practices', not_for: 'writing tests, implementing features or researching background information' },
+    researcher: { what: 'research, investigate, explore, read and summarize issues, docs, discussions and prior art', not_for: 'writing code, writing tests or reviewing a diff' },
+    coder: { what: 'implement features, write code, fix bugs and build functionality', not_for: 'research, review or test-only work' },
+    architect: { what: 'design system architecture, module boundaries, APIs, schemas and refactoring plans', not_for: 'running tests or small bug fixes' },
+    'security-architect': { what: 'security, authentication, authorization, encryption, vulnerabilities, CVEs and audits', not_for: 'general feature work or performance tuning' },
+    'performance-engineer': { what: 'performance optimization, profiling, benchmarks, latency and bottlenecks', not_for: 'security review or writing documentation' },
+    devops: { what: 'deployment, CI/CD pipelines, docker, kubernetes and infrastructure', not_for: 'application feature code or unit tests' },
+    'memory-specialist': { what: 'memory systems, caches, vector stores, embeddings and persistence', not_for: 'UI work or deployment pipelines' },
+    'swarm-specialist': { what: 'multi-agent swarms, coordinators, hive-mind, mesh topology and agent orchestration', not_for: 'single-file code edits' },
+};
+/**
+ * Build choice options from the router's pattern table: every primary agent of
+ * a pattern, plus the profiled roles (researcher/reviewer) the table only lists
+ * as alternates. Each pattern's keywords are appended to its primary agent's
+ * `what`, so the options track TASK_PATTERNS rather than a parallel list.
+ */
+export function buildAgentCriteria(patterns) {
+    const keywordsByAgent = new Map();
+    for (const { agents, keywords } of Object.values(patterns)) {
+        const primary = agents[0];
+        if (!primary)
+            continue;
+        const set = keywordsByAgent.get(primary) ?? new Set();
+        keywords.forEach(k => set.add(k));
+        keywordsByAgent.set(primary, set);
+    }
+    for (const agent of ['researcher', 'reviewer', 'tester', 'coder']) {
+        if (!keywordsByAgent.has(agent))
+            keywordsByAgent.set(agent, new Set());
+    }
+    const criteria = {};
+    for (const [agent, kws] of keywordsByAgent) {
+        const profile = AGENT_PROFILES[agent] ?? { what: `${agent.replace(/-/g, ' ')} tasks` };
+        const kw = [...kws].join(', ');
+        criteria[agent] = {
+            what: kw ? `${profile.what}; keywords: ${kw}` : profile.what,
+            ...(profile.not_for ? { not_for: profile.not_for } : {}),
+        };
+    }
+    return criteria;
+}
+function num(raw, dflt, max = 1) {
+    const n = raw === undefined || raw === '' ? NaN : Number(raw);
+    return Number.isFinite(n) && n >= 0 && n <= max ? n : dflt;
+}
+/** Read config from env. Invalid numeric values fall back to the defaults. */
+export function readTypesafeConfig(env = process.env) {
+    const modelDir = env.CLAUDE_FLOW_ROUTER_TYPESAFE_MODEL_DIR;
+    const manifest = env.CLAUDE_FLOW_ROUTER_TYPESAFE_MANIFEST;
+    return {
+        enabled: env.CLAUDE_FLOW_ROUTER_TYPESAFE === '1',
+        minLift: num(env.CLAUDE_FLOW_ROUTER_TYPESAFE_MIN_LIFT, 1.2, 255),
+        maxAbstain: num(env.CLAUDE_FLOW_ROUTER_TYPESAFE_MAX_ABSTAIN, 0.3),
+        minMargin: num(env.CLAUDE_FLOW_ROUTER_TYPESAFE_MIN_MARGIN, 0.005),
+        embedder: modelDir && manifest ? { kind: 'onnx', modelDir, manifest } : 'hash',
+    };
+}
+/**
+ * Stateful router: loads the module and builds one engine on first use, caches
+ * a load failure so a missing package costs one import attempt per process.
+ */
+export class TypesafeRouter {
+    engine = null;
+    mod = null;
+    loadError = null;
+    env;
+    loadModule;
+    debug;
+    constructor(deps = {}) {
+        this.env = deps.env ?? process.env;
+        this.loadModule = deps.loadModule ?? loadTypesafeModule;
+        this.debug = deps.debug ?? ((m) => { if (this.env.CLAUDE_FLOW_LOG_LEVEL === 'debug')
+            console.error(`[typesafe-router] ${m}`); });
+    }
+    isEnabled() { return readTypesafeConfig(this.env).enabled; }
+    async ensureEngine(cfg) {
+        if (this.engine || this.loadError)
+            return this.engine;
+        try {
+            const raw = (await this.loadModule());
+            const mod = (typeof raw.createTypesafe === 'function' ? raw : raw.default);
+            if (!mod || typeof mod.createTypesafe !== 'function')
+                throw new Error('module has no createTypesafe export');
+            this.mod = mod;
+            this.engine = mod.createTypesafe({ embedder: cfg.embedder });
+        }
+        catch (err) {
+            const e = err;
+            this.loadError = e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND'
+                ? `${MODULE_ID} not installed`
+                : `${MODULE_ID} failed to load: ${e?.message ?? String(err)}`;
+            this.debug(this.loadError);
+        }
+        return this.engine;
+    }
+    /** Ask typesafe for an agent. Never throws; `used: false` means keep the legacy route. */
+    async route(task, patterns) {
+        const cfg = readTypesafeConfig(this.env);
+        const thresholds = { minLift: cfg.minLift, maxAbstain: cfg.maxAbstain, minMargin: cfg.minMargin };
+        const embedder = cfg.embedder === 'hash' ? 'hash' : 'onnx';
+        if (!cfg.enabled)
+            return { used: false, reason: 'CLAUDE_FLOW_ROUTER_TYPESAFE is not 1', thresholds };
+        const engine = await this.ensureEngine(cfg);
+        if (!engine)
+            return { used: false, reason: this.loadError ?? 'typesafe unavailable', thresholds, embedder };
+        let answer;
+        try {
+            const criteria = buildAgentCriteria(patterns);
+            const question = this.mod?.choice ? this.mod.choice(criteria) : { type: 'choice', criteria };
+            const res = await engine.decide(task, { agent: question });
+            answer = res.agent;
+            if (!answer || typeof answer.choice !== 'string')
+                throw new Error('no choice in answer');
+        }
+        catch (err) {
+            const reason = `typesafe decide failed: ${err?.message ?? String(err)}`;
+            this.debug(reason);
+            return { used: false, reason, thresholds, embedder, backend: engine.backend };
+        }
+        const probs = Object.values(answer.probabilities ?? {}).sort((a, b) => b - a);
+        const margin = (probs[0] ?? 0) - (probs[1] ?? 0);
+        const lift = (probs[0] ?? 0) * probs.length;
+        const base = { answer, lift, thresholds, embedder, backend: engine.backend };
+        const f = (n) => n.toFixed(2);
+        if (answer.abstain > cfg.maxAbstain) {
+            return { ...base, used: false, reason: `typesafe abstain ${f(answer.abstain)} > max ${f(cfg.maxAbstain)}; kept existing router` };
+        }
+        if (lift < cfg.minLift) {
+            return { ...base, used: false, reason: `typesafe lift ${f(lift)} (top-1 × ${probs.length} options) < min ${f(cfg.minLift)}; kept existing router` };
+        }
+        if (margin < cfg.minMargin) {
+            return { ...base, used: false, reason: `typesafe top-1 margin ${margin.toFixed(3)} < min ${cfg.minMargin.toFixed(3)} (no clear winner); kept existing router` };
+        }
+        return { ...base, used: true, reason: `typesafe choice "${answer.choice}" (confidence ${f(answer.confidence)}, lift ${f(lift)}, abstain ${f(answer.abstain)}, ${answer.calibrated ? 'calibrated' : 'UNCALIBRATED'} ${embedder} embedder)` };
+    }
+}
+const round2 = (n) => Math.round(n * 100) / 100;
+/**
+ * Merge a typesafe outcome into a legacy `hooks_route` result. Disabled or
+ * error results (`success: false`) pass through untouched.
+ */
+export async function applyTypesafeRouting(params, legacy, patterns, router) {
+    if (!router.isEnabled() || !legacy || legacy.success === false || typeof params.task !== 'string')
+        return legacy;
+    const text = typeof params.context === 'string' && params.context ? `${params.task} ${params.context}` : params.task;
+    const outcome = await router.route(text, patterns);
+    const legacyRouting = (legacy.routing ?? {});
+    const legacyPrimary = (legacy.primaryAgent ?? {});
+    const a = outcome.answer;
+    const typesafe = {
+        used: outcome.used,
+        reason: outcome.reason,
+        ...(a ? {
+            choice: a.choice,
+            confidence: round2(a.confidence),
+            abstain: round2(a.abstain),
+            lift: outcome.lift === undefined ? undefined : round2(outcome.lift),
+            calibrated: a.calibrated,
+            head: a.head,
+            model: a.model,
+            probabilities: Object.fromEntries(Object.entries(a.probabilities).map(([k, v]) => [k, round2(v)])),
+        } : {}),
+        backend: outcome.backend,
+        embedder: outcome.embedder,
+        thresholds: outcome.thresholds,
+    };
+    if (!outcome.used || !a) {
+        return { ...legacy, routedBy: String(legacyRouting.method ?? 'legacy'), typesafe };
+    }
+    const alternatives = Object.entries(a.probabilities)
+        .filter(([k]) => k !== a.choice)
+        .sort((x, y) => y[1] - x[1])
+        .slice(0, 2)
+        .map(([type, p]) => ({ type, confidence: round2(p), reason: 'typesafe runner-up (probability share)' }));
+    return {
+        ...legacy,
+        routing: { ...legacyRouting, method: 'typesafe', backend: `@ruvector/typesafe (${outcome.backend ?? 'unknown'}, ${outcome.embedder} embedder)` },
+        routedBy: 'typesafe',
+        matchedPattern: `typesafe:${a.choice}`,
+        primaryAgent: {
+            type: a.choice,
+            confidence: round2(a.confidence),
+            confidenceCalibrated: a.calibrated,
+            reason: outcome.reason,
+        },
+        alternativeAgents: alternatives,
+        fallbackRoute: { agent: legacyPrimary.type, confidence: legacyPrimary.confidence, method: legacyRouting.method },
+        typesafe,
+    };
+}
+let sharedRouter = null;
+/** Process-wide router used by hooks_route. */
+export function getTypesafeRouter() {
+    return (sharedRouter ??= new TypesafeRouter());
+}
+//# sourceMappingURL=typesafe-router.js.map