@kognai/tool-router 0.0.0-stage → 0.1.0

package/dist/retrieve/hash-embed.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashEmbeddingPort = exports.HASH_MODEL = void 0;
+exports.hashEmbed = hashEmbed;
+/**
+ * A deterministic stand in for an embedding model: hashed tokens and character trigrams into 256 dimensions. Used by
+ * tests (the fake EmbeddingPort) and as the labelled offline fallback of the benchmark when the gateway's real model
+ * is not reachable. It is not semantic: it is named 'ktr-hash-256' everywhere so it can never pass for bge-m3.
+ */
+const node_crypto_1 = require("node:crypto");
+const tokenise_1 = require("./tokenise");
+exports.HASH_MODEL = 'ktr-hash-256';
+const DIMS = 256;
+function bucket(s) {
+    const h = (0, node_crypto_1.createHash)('md5').update(s).digest();
+    return [h.readUInt16LE(0) % DIMS, h[2] & 1 ? 1 : -1];
+}
+function hashEmbed(text) {
+    const v = new Float32Array(DIMS);
+    for (const t of (0, tokenise_1.tokenise)(text)) {
+        const [i, s] = bucket(`w:${t}`);
+        v[i] += 2 * s;
+        const p = `#${t}#`;
+        for (let j = 0; j + 3 <= p.length; j++) {
+            const [k, sk] = bucket(`c:${p.slice(j, j + 3)}`);
+            v[k] += 0.5 * sk;
+        }
+    }
+    let n = 0;
+    for (const x of v)
+        n += x * x;
+    n = Math.sqrt(n) || 1;
+    for (let j = 0; j < DIMS; j++)
+        v[j] /= n;
+    return v;
+}
+exports.hashEmbeddingPort = {
+    model: exports.HASH_MODEL,
+    dims: DIMS,
+    async embed(texts) { return texts.map(hashEmbed); },
+};

package/dist/retrieve/hybrid.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Hybrid retrieval (plan.md S3). RouterIndex is built once per catalog snapshot: one document per operation of the
+ * newest version of each tool (name, sanitised description, summary, tags, capability words), a BM25 index, an
+ * inverted capability index and, when the catalog has vectors for the model, a normalised vector matrix.
+ *
+ * retrieve() takes the union of the top 50 by each signal plus every exact capability match (capped), then returns
+ * per candidate signals in 0..1: lexical, vector, capability, schema, health. History (success) is the ranker's.
+ */
+import type { CatalogStore } from '../types/ports';
+import type { PlanNode } from '../types/route';
+import type { ToolOperation, ToolRecord } from '../types/tool';
+import { Bm25Index } from './bm25';
+export interface IndexedOp {
+    key: string;
+    rec: ToolRecord;
+    op: ToolOperation;
+}
+export interface VectorCalibration {
+    lo: number;
+    hi: number;
+}
+/** Cosine to 0..1: below lo is no semantic match, above hi a full one. Per model, measured (bench report). */
+export declare const CALIBRATION: Record<string, VectorCalibration>;
+export declare class RouterIndex {
+    readonly ops: IndexedOp[];
+    readonly byKey: Map<string, number>;
+    readonly byCap: Map<string, number[]>;
+    readonly bm25: Bm25Index;
+    vectors: {
+        model: string;
+        dims: number;
+        data: Float32Array;
+        rowOf: Int32Array;
+    } | null;
+    readonly snapshot: string;
+    constructor(store: CatalogStore, opts?: {
+        vectorModel?: string;
+        records?: Iterable<ToolRecord>;
+    });
+    /** Cosine of the query against every operation (NaN where an operation has no vector). */
+    cosines(model: string, q: Float32Array): Float32Array | null;
+}
+export declare function docText(rec: ToolRecord, op: ToolOperation): string;
+/** The text embedded for an operation: provider facts only (sanitised), no KTR tags, so vectors survive a taxonomy change. */
+export declare function embedDocText(rec: ToolRecord, op: ToolOperation): string;
+/** Words for a node's lexical query: the request plus the capability's own label and first cues. */
+export declare function nodeQueryTokens(text: string, capability: string): string[];
+export interface Signals {
+    lexical: number;
+    vector: number;
+    capability: number;
+    schema: number;
+    health: number;
+    cosine: number | null;
+}
+export interface Retrieved {
+    index: number;
+    item: IndexedOp;
+    signals: Signals;
+}
+export interface RetrieveOpts {
+    topN?: number;
+    capCap?: number;
+    useLexical?: boolean;
+    useVector?: boolean;
+    useCapability?: boolean;
+    queryVector?: {
+        model: string;
+        vector: Float32Array;
+    } | null;
+    cosines?: Float32Array | null;
+    prevOutput?: (node: PlanNode) => Record<string, unknown> | null;
+}
+export declare function retrieve(ix: RouterIndex, node: PlanNode, text: string, o?: RetrieveOpts): Retrieved[];

package/dist/retrieve/hybrid.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouterIndex = exports.CALIBRATION = void 0;
+exports.docText = docText;
+exports.embedDocText = embedDocText;
+exports.nodeQueryTokens = nodeQueryTokens;
+exports.retrieve = retrieve;
+const taxonomy_1 = require("../classify/taxonomy");
+const bm25_1 = require("./bm25");
+const capability_1 = require("./capability");
+const schema_fit_1 = require("./schema-fit");
+const tokenise_1 = require("./tokenise");
+const vector_1 = require("./vector");
+/** Cosine to 0..1: below lo is no semantic match, above hi a full one. Per model, measured (bench report). */
+exports.CALIBRATION = {
+    'bge-m3': { lo: 0.35, hi: 0.7 },
+    'ktr-hash-256': { lo: 0.05, hi: 0.6 },
+};
+class RouterIndex {
+    ops = [];
+    byKey = new Map();
+    byCap = new Map();
+    bm25;
+    vectors = null;
+    snapshot;
+    constructor(store, opts = {}) {
+        this.snapshot = store.snapshotId();
+        const docs = [];
+        for (const rec of opts.records ?? store.latest()) {
+            for (const op of rec.operations) {
+                const key = `${rec.id}#${op.op}`;
+                const i = this.ops.length;
+                this.ops.push({ key, rec, op });
+                this.byKey.set(key, i);
+                for (const c of op.capabilities)
+                    (this.byCap.get(c) || this.byCap.set(c, []).get(c)).push(i);
+                docs.push({ key, text: docText(rec, op) });
+            }
+        }
+        this.bm25 = new bm25_1.Bm25Index(docs);
+        if (opts.vectorModel) {
+            const v = store.vectors(opts.vectorModel);
+            if (v) {
+                const data = (0, vector_1.normaliseRows)(v.data, v.dims);
+                const rowOf = new Int32Array(this.ops.length).fill(-1);
+                const pos = new Map(v.ids.map((id, r) => [id, r]));
+                for (let i = 0; i < this.ops.length; i++)
+                    rowOf[i] = pos.get(this.ops[i].key) ?? -1;
+                this.vectors = { model: opts.vectorModel, dims: v.dims, data, rowOf };
+            }
+        }
+    }
+    /** Cosine of the query against every operation (NaN where an operation has no vector). */
+    cosines(model, q) {
+        if (!this.vectors)
+            return null;
+        (0, vector_1.checkQuery)(this.vectors, model, q);
+        const rows = (0, vector_1.cosineAll)(q, this.vectors.data, this.vectors.dims);
+        const out = new Float32Array(this.ops.length).fill(NaN);
+        for (let i = 0; i < this.ops.length; i++) {
+            const r = this.vectors.rowOf[i];
+            if (r >= 0)
+                out[i] = rows[r];
+        }
+        return out;
+    }
+}
+exports.RouterIndex = RouterIndex;
+function docText(rec, op) {
+    const capWords = op.capabilities.map((c) => c.replace(/[._]/g, ' ')).join(' ');
+    return `${rec.name} ${rec.description_safe} ${op.op.replace(/[_.-]/g, ' ')} ${op.summary} ${rec.tags.join(' ')} ${capWords}`;
+}
+/** The text embedded for an operation: provider facts only (sanitised), no KTR tags, so vectors survive a taxonomy change. */
+function embedDocText(rec, op) {
+    return `${rec.name}. ${op.op.replace(/[_.-]/g, ' ')}: ${op.summary}. ${rec.description_safe}`.slice(0, 2000);
+}
+/** Words for a node's lexical query: the request plus the capability's own label and first cues. */
+function nodeQueryTokens(text, capability) {
+    const def = (0, taxonomy_1.capabilityById)(capability);
+    const label = capability.replace(/[._]/g, ' ');
+    const cueWords = def ? def.cues.en.slice(0, 3).map((c) => c.replace(/\\[a-z]|[()?|.*+\[\]{}^$\\]/g, ' ')).join(' ') : '';
+    return [...(0, tokenise_1.tokenise)(text), ...(0, tokenise_1.tokenise)(label), ...(0, tokenise_1.tokenise)(label), ...(0, tokenise_1.tokenise)(cueWords)];
+}
+const HEALTH = { up: 1, degraded: 0.5, unknown: 0.5, down: 0 };
+function retrieve(ix, node, text, o = {}) {
+    const topN = o.topN ?? 50;
+    const useLex = o.useLexical !== false;
+    const useVec = o.useVector !== false && !!o.cosines;
+    const useCap = o.useCapability !== false;
+    const pool = new Set();
+    let lexScores = new Map();
+    if (useLex) {
+        lexScores = ix.bm25.scoreAll(nodeQueryTokens(text, node.capability));
+        [...lexScores].sort((a, b) => b[1] - a[1] || a[0] - b[0]).slice(0, topN).forEach(([i]) => pool.add(i));
+    }
+    const cos = useVec ? o.cosines : null;
+    if (cos) {
+        const idx = [];
+        for (let i = 0; i < cos.length; i++)
+            if (!Number.isNaN(cos[i]))
+                idx.push(i);
+        idx.sort((a, b) => cos[b] - cos[a] || a - b).slice(0, topN).forEach((i) => pool.add(i));
+    }
+    if (useCap)
+        (ix.byCap.get(node.capability) || []).slice(0, o.capCap ?? 300).forEach((i) => pool.add(i));
+    const maxLex = Math.max(1e-9, ...[...pool].map((i) => lexScores.get(i) || 0));
+    const cal = exports.CALIBRATION[o.queryVector?.model || ''] || { lo: 0.3, hi: 0.8 };
+    const out = [];
+    for (const i of pool) {
+        const item = ix.ops[i];
+        const c = cos && !Number.isNaN(cos[i]) ? cos[i] : null;
+        out.push({
+            index: i, item,
+            signals: {
+                lexical: useLex ? (lexScores.get(i) || 0) / maxLex : 0,
+                vector: c === null ? 0 : Math.max(0, Math.min(1, (c - cal.lo) / (cal.hi - cal.lo))),
+                capability: useCap ? (0, capability_1.capabilityScore)(node.capability, item.op.capabilities) : 0,
+                schema: (0, schema_fit_1.schemaFit)(node, item.op.input_schema, o.prevOutput?.(node) ?? null),
+                health: HEALTH[item.rec.health.state] ?? 0.5,
+                cosine: c,
+            },
+        });
+    }
+    return out;
+}

package/dist/retrieve/schema-fit.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Schema fit: the share of an operation's required inputs the request can supply (the node's known arguments), or,
+ * for a chained node, whether the previous node's output can feed it. An unknown schema scores 0.3 and nothing that
+ * is unknown ever scores 1.
+ */
+import type { JSONSchema } from '../types/tool';
+import type { PlanNode } from '../types/route';
+export declare const UNKNOWN_SCHEMA = 0.3;
+export declare function schemaFit(node: Pick<PlanNode, 'args_known' | 'depends_on'>, input: JSONSchema | null | undefined, prevOutput?: JSONSchema | null): number;

package/dist/retrieve/schema-fit.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_SCHEMA = void 0;
+exports.schemaFit = schemaFit;
+/** Input property names each argument the classifier finds can fill. */
+const FILLS = {
+    query: /^(q|query|term|terms|search|text|prompt|brief|topic|keywords?|description|goal|task|idea|request|input|instruction|message|title|question|content|subject|from|name|shop|material|channel)$/i,
+    location: /^(city|location|place|lat|latitude|lon|lng|longitude|address|country|region|near|q|query)$/i,
+    url: /^(url|uri|link|href|page_url|website)$/i,
+    address: /^(address|token|mint|contract|contract_address|wallet|token_address|ca)$/i,
+    token: /^(token|mint|symbol|ticker|address|coin|chain|contract|token_address|ids|vs_currencies)$/i,
+    amount: /^(amount|value|quantity|qty|sum)$/i,
+    file_ref: /^(file|file_id|image|image_ref|image_url|audio|audio_ref|document|pdf|attachment|video|id)$/i,
+    recipient: /^(to|recipient|email|phone|number|chat_id|user)$/i,
+    date: /^(date|day|from|to|start|end|time|since|until|days)$/i,
+};
+exports.UNKNOWN_SCHEMA = 0.3;
+function schemaFit(node, input, prevOutput) {
+    const props = (input && typeof input === 'object' && input.properties && typeof input.properties === 'object') ? Object.keys(input.properties) : [];
+    const required = Array.isArray(input?.required) ? input.required.map(String) : [];
+    if (!props.length && !required.length)
+        return exports.UNKNOWN_SCHEMA;
+    if (node.depends_on.length) {
+        // chained: the previous node's output names, when known, should cover the required inputs
+        const outProps = prevOutput && prevOutput.properties ? Object.keys(prevOutput.properties) : [];
+        if (!required.length)
+            return 0.8;
+        if (!outProps.length)
+            return 0.6;
+        const covered = required.filter((r) => outProps.includes(r)).length;
+        return Math.min(0.95, 0.4 + 0.55 * covered / required.length);
+    }
+    if (!required.length)
+        return 0.8;
+    const fillable = (name) => node.args_known.some((a) => FILLS[a]?.test(name));
+    const ok = required.filter(fillable).length;
+    return Math.min(0.95, 0.15 + 0.8 * ok / required.length);
+}

package/dist/retrieve/tokenise.d.ts

@@ -0,0 +1,2 @@
+export declare const STOP: Set<string>;
+export declare function tokenise(text: string, keepStop?: boolean): string[];

package/dist/retrieve/tokenise.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP = void 0;
+exports.tokenise = tokenise;
+/**
+ * Multilingual tokeniser (FR, EN, Tunisian derja in Latin and Arabic script): normalised text (classify/text.ts),
+ * split on anything that is not a letter or a digit, stop words dropped per language, a light plural strip for Latin
+ * words and the article "al" stripped from Arabic words. Derja digits inside words are kept (a3mel, ta9s).
+ */
+const text_1 = require("../classify/text");
+exports.STOP = new Set([
+    // en
+    'the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'on', 'for', 'with', 'by', 'at', 'from', 'is', 'are', 'be', 'it', 'this',
+    'that', 'these', 'those', 'my', 'me', 'i', 'you', 'your', 'we', 'our', 'can', 'could', 'please', 'what', 'which', 'how',
+    'about', 'into', 'as', 'do', 'does', 'get', 'any', 'all', 'some', 'via', 'use', 'using', 'api', 'tool', 'tools', 'data',
+    'will', 'would', 'should', 'want', 'need', 'make', 'give', 'show', 'tell', 'just', 'also', 'one', 'more', 'than', 'then',
+    // fr
+    'le', 'la', 'les', 'l', 'de', 'des', 'du', 'd', 'un', 'une', 'et', 'ou', 'en', 'au', 'aux', 'pour', 'avec', 'dans', 'sur',
+    'par', 'mes', 'mon', 'ma', 'moi', 'je', 'tu', 'vous', 'nous', 'est', 'sont', 'ce', 'cette', 'ces', 'qui', 'que', 'qu',
+    'quel', 'quelle', 'fais', 'faire', 's', 'il', 'elle', 'pas', 'ne', 'plus', 'svp',
+    // derja (Latin) and Arabic function words
+    'el', 'w', 'fi', 'f', 'l', 'mte3', 'mta3', 'mte3i', 'mta3i', 'chnowa', 'chnoua', 'kifech', 'n7eb', 'nheb', '3la', '3al', 'ya',
+    'في', 'على', 'من', 'و', 'متاع', 'متاعي', 'شنوه', 'نحب', 'هذا', 'هذي', 'الي', 'ال',
+]);
+const LATIN = /^[a-z0-9]+$/;
+function stem(t) {
+    if (LATIN.test(t)) {
+        if (t.length > 4 && t.endsWith('ies'))
+            return t.slice(0, -3) + 'y';
+        if (t.length > 3 && (t.endsWith('s') || t.endsWith('x')) && !t.endsWith('ss'))
+            return t.slice(0, -1);
+        return t;
+    }
+    if (t.length > 3 && t.startsWith('ال'))
+        return t.slice(2);
+    return t;
+}
+function tokenise(text, keepStop = false) {
+    const out = [];
+    for (const raw of (0, text_1.normalise)(text).split(/[^\p{L}\p{N}]+/u)) {
+        if (!raw || raw.length < 2 && !/[؀-ۿ]/.test(raw))
+            continue;
+        if (!keepStop && exports.STOP.has(raw))
+            continue;
+        const s = stem(raw);
+        if (!keepStop && exports.STOP.has(s))
+            continue;
+        out.push(s);
+    }
+    return out;
+}

package/dist/retrieve/vector.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cosine over precomputed vectors (one per operation), stamped with model and dimension (ADR-003 rule 2): a query
+ * vector from another model or of another dimension is refused, never silently compared.
+ */
+export interface VectorSet {
+    model: string;
+    dims: number;
+    ids: string[];
+    data: Float32Array;
+}
+export declare function normaliseRows(data: Float32Array, dims: number): Float32Array;
+export declare function checkQuery(set: Pick<VectorSet, 'model' | 'dims'>, model: string, q: Float32Array): void;
+/** Cosine of a normalised query against every row (rows must be normalised). */
+export declare function cosineAll(q: Float32Array, data: Float32Array, dims: number): Float32Array;
+export declare function topK(q: Float32Array, data: Float32Array, dims: number, k: number): Array<{
+    row: number;
+    score: number;
+}>;

package/dist/retrieve/vector.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normaliseRows = normaliseRows;
+exports.checkQuery = checkQuery;
+exports.cosineAll = cosineAll;
+exports.topK = topK;
+function normaliseRows(data, dims) {
+    const out = new Float32Array(data.length);
+    for (let r = 0; r < data.length / dims; r++) {
+        let n = 0;
+        for (let j = 0; j < dims; j++)
+            n += data[r * dims + j] ** 2;
+        n = Math.sqrt(n) || 1;
+        for (let j = 0; j < dims; j++)
+            out[r * dims + j] = data[r * dims + j] / n;
+    }
+    return out;
+}
+function checkQuery(set, model, q) {
+    if (model !== set.model)
+        throw new Error(`query vector from ${model}, catalog vectors from ${set.model}: refused`);
+    if (q.length !== set.dims)
+        throw new Error(`query has ${q.length} dimensions, catalog vectors ${set.dims}: refused`);
+}
+/** Cosine of a normalised query against every row (rows must be normalised). */
+function cosineAll(q, data, dims) {
+    let n = 0;
+    for (let j = 0; j < dims; j++)
+        n += q[j] * q[j];
+    n = Math.sqrt(n) || 1;
+    const rows = data.length / dims;
+    const out = new Float32Array(rows);
+    for (let r = 0; r < rows; r++) {
+        let s = 0;
+        const o = r * dims;
+        for (let j = 0; j < dims; j++)
+            s += q[j] * data[o + j];
+        out[r] = s / n;
+    }
+    return out;
+}
+function topK(q, data, dims, k) {
+    const sims = cosineAll(q, data, dims);
+    const idx = Array.from(sims.keys());
+    idx.sort((a, b) => sims[b] - sims[a] || a - b);
+    return idx.slice(0, k).map((row) => ({ row, score: sims[row] }));
+}

package/dist/router.d.ts

@@ -0,0 +1,37 @@
+import type { KtrFlags } from './flags';
+import type { CatalogStore, ClassifierPort, Clock, EmbeddingPort, EvidenceStore, SkillIndex } from './types/ports';
+import type { RouteRequest, RouteResponse } from './types/route';
+import { RouterIndex } from './retrieve/hybrid';
+import { type FitWeights, type Weights } from './rank/weights';
+export interface RouterConfig {
+    weights?: Weights;
+    fitWeights?: FitWeights;
+    useLexical?: boolean;
+    useVector?: boolean;
+    useCapability?: boolean;
+    scoring?: 'full' | 'fit';
+    exploration?: boolean;
+    vectorModel?: string;
+    floor?: number;
+    /** The AIAX ready bonus (rank/weights.ts AIAX_READY_WEIGHT by default); 0 turns it off. */
+    aiaxWeight?: number;
+}
+export interface RouterDeps {
+    store: CatalogStore;
+    index?: RouterIndex;
+    flags: KtrFlags;
+    /** Offline CLIs and the benchmark (stage 0): the router answers with TOOL_ROUTER_ENABLED off; the stop file still wins. */
+    offline?: boolean;
+    classifier?: ClassifierPort | null;
+    embed?: EmbeddingPort | null;
+    queryVector?: {
+        model: string;
+        vector: Float32Array;
+    } | null;
+    evidence?: EvidenceStore | null;
+    skills?: SkillIndex | null;
+    clock?: Clock;
+    config?: RouterConfig;
+    log?: (entry: Record<string, unknown>) => void;
+}
+export declare function route(req: RouteRequest, deps: RouterDeps): Promise<RouteResponse>;

package/dist/router.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.route = route;
+/**
+ * route(): classify, decompose, then per node retrieve, filter (eligibility before any score), rank and shortlist
+ * (plan.md S4 of the spec, "router.ts"). Offline in milestone 1: it selects, it never executes (decision D2).
+ *
+ * The response names the catalog snapshot it read; every candidate is a row of that snapshot. Requirement:
+ *   no_tool / clarify     from the classifier (simple first: a shortlist is never forced, ADR-008)
+ *   tool                  at least one tool step has an eligible candidate
+ *   no_eligible_tool      tool steps exist but every candidate was excluded, or none exists
+ * Routes are logged through deps.log with ids, scores and exclusion counts; a citizen's request text is replaced by
+ * its hash (privacy).
+ */
+const node_crypto_1 = require("node:crypto");
+const classifier_1 = require("./classify/classifier");
+const decompose_1 = require("./classify/decompose");
+const hybrid_1 = require("./retrieve/hybrid");
+const engine_1 = require("./eligibility/engine");
+const rules_1 = require("./eligibility/rules");
+const ranker_1 = require("./rank/ranker");
+const weights_1 = require("./rank/weights");
+const generate_1 = require("./shortlist/generate");
+const sha = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
+async function route(req, deps) {
+    const now = (deps.clock?.now() || new Date()).toISOString();
+    const mode = req.mode || 'execute_plan';
+    const route_id = `route_${sha(`${now}|${req.request_id || ''}|${req.context.caller_id}|${req.text}`).slice(0, 24)}`;
+    const cfg = deps.config || {};
+    const notes = [];
+    const base = { route_id, created_at: now, catalog_snapshot: deps.store.snapshotId(), mode, request_step: req.request_step };
+    if (deps.flags.stopped || (!deps.flags.enabled && !deps.offline)) {
+        return { ...base, task_complexity: 'SIMPLE', risk_classes: [], requirement: 'no_eligible_tool', classifier: { method: 'rules', confidence: 0 }, plan: [], shortlists: [],
+            notes: [deps.flags.stopped ? 'KTR is stopped (.swarm-state/ktr-stop): the caller continues without it' : 'router disabled (TOOL_ROUTER_ENABLED off): the caller continues with request routing as before'] };
+    }
+    if (cfg.weights)
+        (0, weights_1.checkWeights)(cfg.weights, cfg.fitWeights);
+    const c = await (0, classifier_1.classify)(req.text, req.context, deps.flags, deps.classifier || null);
+    const plan = (0, decompose_1.decompose)(c, req.text);
+    const resp = { ...base, task_complexity: c.task_complexity, risk_classes: c.risk_classes, requirement: c.requirement,
+        classifier: { method: c.method, confidence: c.confidence }, plan, shortlists: [], notes };
+    if (c.requirement === 'no_tool') {
+        notes.push('no tool needed: the model can answer this itself (request routing step 1)');
+        return finish(resp, req, deps);
+    }
+    if (c.requirement === 'clarify') {
+        notes.push('the request is too vague to plan: ask the person what they want');
+        return finish(resp, req, deps);
+    }
+    const ix = deps.index && deps.index.snapshot === resp.catalog_snapshot ? deps.index : new hybrid_1.RouterIndex(deps.store, { vectorModel: cfg.vectorModel || deps.queryVector?.model || deps.embed?.model });
+    let qv = deps.queryVector || null;
+    if (!qv && deps.embed && ix.vectors && cfg.useVector !== false) {
+        try {
+            qv = { model: deps.embed.model, vector: (await deps.embed.embed([req.text]))[0] };
+        }
+        catch {
+            notes.push('query embedding unavailable: lexical and capability signals only');
+        }
+    }
+    const cosines = qv && cfg.useVector !== false ? ix.cosines(qv.model, qv.vector) : null;
+    const use = { capability: cfg.useCapability !== false, vector: !!cosines, lexical: cfg.useLexical !== false };
+    if (!cosines && cfg.useVector !== false)
+        notes.push(ix.vectors ? 'no query vector (not cached, gateway not asked): fit uses capability and lexical signals' : 'no vectors for this catalog: fit uses capability and lexical signals');
+    const floor = cfg.floor ?? weights_1.RELEVANCE_FLOOR;
+    const maxC = req.constraints?.max_candidates;
+    let anyEligible = false;
+    let anyToolNode = false;
+    const excludedTotal = {};
+    for (const node of plan) {
+        if (!node.needs_tool)
+            continue;
+        anyToolNode = true;
+        const found = (0, hybrid_1.retrieve)(ix, node, req.text, { useLexical: use.lexical, useVector: use.vector, useCapability: use.capability, queryVector: qv, cosines });
+        const relevant = (x) => (0, weights_1.fitOf)(x.signals, use, cfg.fitWeights) >= floor;
+        const { eligible, excluded } = (0, engine_1.filter)(found, { node, ctx: req.context, mode, flags: deps.flags, offline: !!deps.offline, constraints: req.constraints }, relevant);
+        const ranked = (0, ranker_1.rank)(eligible, { weights: cfg.weights || weights_1.DEFAULT_WEIGHTS, fitWeights: cfg.fitWeights, use, scoring: cfg.scoring, seed: route_id, exploration: !!cfg.exploration, evidence: deps.evidence, skills: deps.skills, aiaxWeight: cfg.aiaxWeight });
+        const { candidates, kognaiFirst } = (0, generate_1.generate)(ranked, node, req.context, { max: maxC, floor, mode });
+        for (const [k, v] of Object.entries(excluded))
+            excludedTotal[k] = (excludedTotal[k] || 0) + (v || 0);
+        const sl = { node_id: node.node_id, candidates, excluded: excluded };
+        resp.shortlists.push(sl);
+        if (candidates.length)
+            anyEligible = true;
+        if (kognaiFirst)
+            notes.push(`${node.node_id}: a Kognai product covers ${node.capability}; outside tools are fallbacks only (ADR-008)`);
+        if (!candidates.length)
+            notes.push(explainEmpty(node, excluded));
+    }
+    if (anyToolNode && !anyEligible)
+        resp.requirement = 'no_eligible_tool';
+    if (resp.risk_classes.includes('payment'))
+        notes.push('payment steps are never autonomous: a transfer is the Founder\'s own act (policy/security.txt rule 1); the Kognai Wallet is a spec only');
+    if (mode === 'discover' && resp.shortlists.some((s) => s.candidates.some((x) => !x.executable)))
+        notes.push('discover mode: quarantined tools are listed for review and are not executable');
+    return finish(resp, req, deps);
+}
+function explainEmpty(node, excluded) {
+    const parts = rules_1.RULE_IDS.filter((r) => excluded[r]).map((r) => `${excluded[r]} ${rules_1.RULE_LABEL[r]} (${r})`);
+    return parts.length ? `${node.node_id} ${node.capability}: no eligible tool; excluded: ${parts.join('; ')}` : `${node.node_id} ${node.capability}: no tool in the catalog covers this step`;
+}
+function finish(resp, req, deps) {
+    if (deps.log) {
+        try {
+            deps.log({
+                route_id: resp.route_id, at: resp.created_at, caller_kind: req.context.kind, caller_id: req.context.caller_id,
+                ...(req.context.kind === 'citizen' ? { text_sha256: sha(req.text) } : { text: req.text.slice(0, 500) }),
+                snapshot: resp.catalog_snapshot, mode: resp.mode, requirement: resp.requirement, task_complexity: resp.task_complexity, risk: resp.risk_classes,
+                nodes: resp.shortlists.map((s) => ({ node_id: s.node_id, top: s.candidates.slice(0, 10).map((c) => [c.tool_id, c.score]), excluded: s.excluded })),
+            });
+        }
+        catch { /* logging never breaks routing */ }
+    }
+    return resp;
+}