@kognai/tool-router 0.0.0-stage → 0.1.0

package/dist/ids.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tool ids (ADR-004): tool:<origin>:<namespace>/<name>[#<operation>]. Lower case, version free, URL and file safe.
+ */
+import type { Origin } from './types/tool';
+export declare const TOOL_ID_RE: RegExp;
+export interface ParsedToolId {
+    origin: Origin;
+    path: string;
+    op?: string;
+}
+export declare function parseToolId(s: string): ParsedToolId | null;
+/** Normalises any string to one id segment: lower case, [a-z0-9._-], no leading or trailing separators. */
+export declare function slugSegment(s: string): string;
+export declare function formatToolId(origin: Origin, path: string, op?: string): string;
+/** The id without '#operation'. */
+export declare const baseId: (id: string) => string;
+export declare const withOp: (id: string, op: string) => string;

package/dist/ids.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withOp = exports.baseId = exports.TOOL_ID_RE = void 0;
+exports.parseToolId = parseToolId;
+exports.slugSegment = slugSegment;
+exports.formatToolId = formatToolId;
+exports.TOOL_ID_RE = /^tool:(kognai|mcp|openapi|x402|community|composio):[a-z0-9._-]+(\/[a-z0-9._-]+)+(#[a-z0-9_.-]+)?$/;
+const SEG_RE = /^[a-z0-9._-]+$/;
+const MAX_PATH = 128;
+function parseToolId(s) {
+    if (typeof s !== 'string' || !exports.TOOL_ID_RE.test(s))
+        return null;
+    const rest = s.slice(5);
+    const colon = rest.indexOf(':');
+    const origin = rest.slice(0, colon);
+    let path = rest.slice(colon + 1);
+    let op;
+    const hash = path.indexOf('#');
+    if (hash >= 0) {
+        op = path.slice(hash + 1);
+        path = path.slice(0, hash);
+    }
+    if (path.length > MAX_PATH)
+        return null;
+    if (path.split('/').some((seg) => seg === '' || seg === '.' || seg === '..'))
+        return null;
+    return op === undefined ? { origin, path } : { origin, path, op };
+}
+/** Normalises any string to one id segment: lower case, [a-z0-9._-], no leading or trailing separators. */
+function slugSegment(s) {
+    const out = String(s ?? '')
+        .normalize('NFKD').replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
+    return out.slice(0, 60) || 'x';
+}
+function formatToolId(origin, path, op) {
+    const segs = path.split('/').map(slugSegment);
+    if (segs.length < 2)
+        throw new Error(`tool id path needs namespace/name, got "${path}"`);
+    if (!segs.every((x) => SEG_RE.test(x)))
+        throw new Error(`bad tool id path "${path}"`);
+    const id = `tool:${origin}:${segs.join('/')}${op ? `#${slugSegment(op).replace(/-/g, '_')}` : ''}`;
+    if (!parseToolId(id))
+        throw new Error(`could not form a valid tool id from "${path}"`);
+    return id;
+}
+/** The id without '#operation'. */
+const baseId = (id) => id.split('#')[0];
+exports.baseId = baseId;
+const withOp = (id, op) => `${(0, exports.baseId)(id)}#${op}`;
+exports.withOp = withOp;

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/** @kognai/tool-router public exports (published under MIT, Founder 2026-11-12; was private, decision D1). */
+export * from './types/tool';
+export * from './types/route';
+export * from './types/ports';
+export * from './ids';
+export * from './hash';
+export * from './money';
+export * from './flags';
+export * from './schema/validate';
+export * from './catalog/sanitise';
+export * from './catalog/lifecycle';
+export * from './catalog/risk';
+export * from './catalog/ingest';
+export * from './catalog/memory-store';
+export * from './catalog/file-store';
+export * from './adapters/raw';
+export { fromServerJson } from './adapters/mcp-registry';
+export { fromMcpToolsList, listToolsLive, type ApprovedServer } from './adapters/mcp-tools';
+export { fromOpenApi } from './adapters/openapi';
+export { fromPaySkills } from './adapters/pay-skills';
+export { fromX402Resources } from './adapters/x402-discovery';
+export { fromAwesomeMarkdown } from './adapters/awesome-list';
+export * from './classify/taxonomy';
+export { classifyRules } from './classify/rules';
+export { classify } from './classify/classifier';
+export { decompose, topoOrder } from './classify/decompose';
+export { tagCapabilities } from './classify/tagger';
+export { tokenise } from './retrieve/tokenise';
+export { Bm25Index } from './retrieve/bm25';
+export { topK, cosineAll } from './retrieve/vector';
+export { hashEmbed, hashEmbeddingPort, HASH_MODEL } from './retrieve/hash-embed';
+export { RouterIndex, retrieve, docText, CALIBRATION } from './retrieve/hybrid';
+export { firstFailure, authNeeded, RULE_IDS, RULE_LABEL } from './eligibility/rules';
+export { filter } from './eligibility/engine';
+export { wilsonLower, successScore } from './rank/confidence';
+export { DEFAULT_WEIGHTS, DEFAULT_FIT, RELEVANCE_FLOOR, AIAX_READY_WEIGHT, checkWeights } from './rank/weights';
+export { rank } from './rank/ranker';
+export { generate, MAX_CANDIDATES } from './shortlist/generate';
+export { route, type RouterDeps, type RouterConfig } from './router';

package/dist/index.js

@@ -0,0 +1,95 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.route = exports.MAX_CANDIDATES = exports.generate = exports.rank = exports.checkWeights = exports.AIAX_READY_WEIGHT = exports.RELEVANCE_FLOOR = exports.DEFAULT_FIT = exports.DEFAULT_WEIGHTS = exports.successScore = exports.wilsonLower = exports.filter = exports.RULE_LABEL = exports.RULE_IDS = exports.authNeeded = exports.firstFailure = exports.CALIBRATION = exports.docText = exports.retrieve = exports.RouterIndex = exports.HASH_MODEL = exports.hashEmbeddingPort = exports.hashEmbed = exports.cosineAll = exports.topK = exports.Bm25Index = exports.tokenise = exports.tagCapabilities = exports.topoOrder = exports.decompose = exports.classify = exports.classifyRules = exports.fromAwesomeMarkdown = exports.fromX402Resources = exports.fromPaySkills = exports.fromOpenApi = exports.listToolsLive = exports.fromMcpToolsList = exports.fromServerJson = void 0;
+/** @kognai/tool-router public exports (published under MIT, Founder 2026-11-12; was private, decision D1). */
+__exportStar(require("./types/tool"), exports);
+__exportStar(require("./types/route"), exports);
+__exportStar(require("./types/ports"), exports);
+__exportStar(require("./ids"), exports);
+__exportStar(require("./hash"), exports);
+__exportStar(require("./money"), exports);
+__exportStar(require("./flags"), exports);
+__exportStar(require("./schema/validate"), exports);
+__exportStar(require("./catalog/sanitise"), exports);
+__exportStar(require("./catalog/lifecycle"), exports);
+__exportStar(require("./catalog/risk"), exports);
+__exportStar(require("./catalog/ingest"), exports);
+__exportStar(require("./catalog/memory-store"), exports);
+__exportStar(require("./catalog/file-store"), exports);
+__exportStar(require("./adapters/raw"), exports);
+var mcp_registry_1 = require("./adapters/mcp-registry");
+Object.defineProperty(exports, "fromServerJson", { enumerable: true, get: function () { return mcp_registry_1.fromServerJson; } });
+var mcp_tools_1 = require("./adapters/mcp-tools");
+Object.defineProperty(exports, "fromMcpToolsList", { enumerable: true, get: function () { return mcp_tools_1.fromMcpToolsList; } });
+Object.defineProperty(exports, "listToolsLive", { enumerable: true, get: function () { return mcp_tools_1.listToolsLive; } });
+var openapi_1 = require("./adapters/openapi");
+Object.defineProperty(exports, "fromOpenApi", { enumerable: true, get: function () { return openapi_1.fromOpenApi; } });
+var pay_skills_1 = require("./adapters/pay-skills");
+Object.defineProperty(exports, "fromPaySkills", { enumerable: true, get: function () { return pay_skills_1.fromPaySkills; } });
+var x402_discovery_1 = require("./adapters/x402-discovery");
+Object.defineProperty(exports, "fromX402Resources", { enumerable: true, get: function () { return x402_discovery_1.fromX402Resources; } });
+var awesome_list_1 = require("./adapters/awesome-list");
+Object.defineProperty(exports, "fromAwesomeMarkdown", { enumerable: true, get: function () { return awesome_list_1.fromAwesomeMarkdown; } });
+__exportStar(require("./classify/taxonomy"), exports);
+var rules_1 = require("./classify/rules");
+Object.defineProperty(exports, "classifyRules", { enumerable: true, get: function () { return rules_1.classifyRules; } });
+var classifier_1 = require("./classify/classifier");
+Object.defineProperty(exports, "classify", { enumerable: true, get: function () { return classifier_1.classify; } });
+var decompose_1 = require("./classify/decompose");
+Object.defineProperty(exports, "decompose", { enumerable: true, get: function () { return decompose_1.decompose; } });
+Object.defineProperty(exports, "topoOrder", { enumerable: true, get: function () { return decompose_1.topoOrder; } });
+var tagger_1 = require("./classify/tagger");
+Object.defineProperty(exports, "tagCapabilities", { enumerable: true, get: function () { return tagger_1.tagCapabilities; } });
+var tokenise_1 = require("./retrieve/tokenise");
+Object.defineProperty(exports, "tokenise", { enumerable: true, get: function () { return tokenise_1.tokenise; } });
+var bm25_1 = require("./retrieve/bm25");
+Object.defineProperty(exports, "Bm25Index", { enumerable: true, get: function () { return bm25_1.Bm25Index; } });
+var vector_1 = require("./retrieve/vector");
+Object.defineProperty(exports, "topK", { enumerable: true, get: function () { return vector_1.topK; } });
+Object.defineProperty(exports, "cosineAll", { enumerable: true, get: function () { return vector_1.cosineAll; } });
+var hash_embed_1 = require("./retrieve/hash-embed");
+Object.defineProperty(exports, "hashEmbed", { enumerable: true, get: function () { return hash_embed_1.hashEmbed; } });
+Object.defineProperty(exports, "hashEmbeddingPort", { enumerable: true, get: function () { return hash_embed_1.hashEmbeddingPort; } });
+Object.defineProperty(exports, "HASH_MODEL", { enumerable: true, get: function () { return hash_embed_1.HASH_MODEL; } });
+var hybrid_1 = require("./retrieve/hybrid");
+Object.defineProperty(exports, "RouterIndex", { enumerable: true, get: function () { return hybrid_1.RouterIndex; } });
+Object.defineProperty(exports, "retrieve", { enumerable: true, get: function () { return hybrid_1.retrieve; } });
+Object.defineProperty(exports, "docText", { enumerable: true, get: function () { return hybrid_1.docText; } });
+Object.defineProperty(exports, "CALIBRATION", { enumerable: true, get: function () { return hybrid_1.CALIBRATION; } });
+var rules_2 = require("./eligibility/rules");
+Object.defineProperty(exports, "firstFailure", { enumerable: true, get: function () { return rules_2.firstFailure; } });
+Object.defineProperty(exports, "authNeeded", { enumerable: true, get: function () { return rules_2.authNeeded; } });
+Object.defineProperty(exports, "RULE_IDS", { enumerable: true, get: function () { return rules_2.RULE_IDS; } });
+Object.defineProperty(exports, "RULE_LABEL", { enumerable: true, get: function () { return rules_2.RULE_LABEL; } });
+var engine_1 = require("./eligibility/engine");
+Object.defineProperty(exports, "filter", { enumerable: true, get: function () { return engine_1.filter; } });
+var confidence_1 = require("./rank/confidence");
+Object.defineProperty(exports, "wilsonLower", { enumerable: true, get: function () { return confidence_1.wilsonLower; } });
+Object.defineProperty(exports, "successScore", { enumerable: true, get: function () { return confidence_1.successScore; } });
+var weights_1 = require("./rank/weights");
+Object.defineProperty(exports, "DEFAULT_WEIGHTS", { enumerable: true, get: function () { return weights_1.DEFAULT_WEIGHTS; } });
+Object.defineProperty(exports, "DEFAULT_FIT", { enumerable: true, get: function () { return weights_1.DEFAULT_FIT; } });
+Object.defineProperty(exports, "RELEVANCE_FLOOR", { enumerable: true, get: function () { return weights_1.RELEVANCE_FLOOR; } });
+Object.defineProperty(exports, "AIAX_READY_WEIGHT", { enumerable: true, get: function () { return weights_1.AIAX_READY_WEIGHT; } });
+Object.defineProperty(exports, "checkWeights", { enumerable: true, get: function () { return weights_1.checkWeights; } });
+var ranker_1 = require("./rank/ranker");
+Object.defineProperty(exports, "rank", { enumerable: true, get: function () { return ranker_1.rank; } });
+var generate_1 = require("./shortlist/generate");
+Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return generate_1.generate; } });
+Object.defineProperty(exports, "MAX_CANDIDATES", { enumerable: true, get: function () { return generate_1.MAX_CANDIDATES; } });
+var router_1 = require("./router");
+Object.defineProperty(exports, "route", { enumerable: true, get: function () { return router_1.route; } });

package/dist/money.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Integer micro units (1 USDC = 1_000_000). Decimal strings in, bigint inside, decimal strings on disk. There is no
+ * floating point path: "0.17" is parsed digit by digit.
+ */
+import type { Money } from './types/tool';
+export declare function toMicro(decimal: string, decimals?: number): bigint;
+export declare function fromMicro(b: bigint, decimals?: number): string;
+/** Parses a micro unit string from disk. */
+export declare function microOf(s: string | undefined | null): bigint | null;
+export declare function fmt(m: Money): string;

package/dist/money.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMicro = toMicro;
+exports.fromMicro = fromMicro;
+exports.microOf = microOf;
+exports.fmt = fmt;
+const DEC_RE = /^(\d+)(?:\.(\d+))?$/;
+function toMicro(decimal, decimals = 6) {
+    const s = String(decimal).trim();
+    if (s.startsWith('-'))
+        throw new Error('negative amounts are refused');
+    const m = DEC_RE.exec(s);
+    if (!m)
+        throw new Error(`not a decimal amount: "${decimal}"`);
+    const frac = m[2] || '';
+    if (frac.length > decimals && /[1-9]/.test(frac.slice(decimals)))
+        throw new Error(`more than ${decimals} decimals: "${decimal}"`);
+    const padded = (frac + '0'.repeat(decimals)).slice(0, decimals);
+    return BigInt(m[1]) * 10n ** BigInt(decimals) + BigInt(padded || '0');
+}
+function fromMicro(b, decimals = 6) {
+    if (b < 0n)
+        throw new Error('negative amounts are refused');
+    const base = 10n ** BigInt(decimals);
+    const whole = b / base;
+    const frac = (b % base).toString().padStart(decimals, '0').replace(/0+$/, '');
+    return frac ? `${whole}.${frac}` : whole.toString();
+}
+/** Parses a micro unit string from disk. */
+function microOf(s) {
+    if (s === undefined || s === null || !/^\d{1,30}$/.test(String(s)))
+        return null;
+    return BigInt(s);
+}
+function fmt(m) {
+    const b = microOf(m.amount_micro);
+    if (b === null)
+        return `? ${m.currency}`;
+    const dec = m.currency === 'KGC' ? 0 : 6;
+    return `${dec ? fromMicro(b) : b.toString()} ${m.currency}${m.network ? ` on ${m.network}` : ''}`;
+}

package/dist/rank/confidence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Success scores that know how sure they are (plan.md S3, threat T10). The Wilson lower bound (z 1.64) of verified
+ * successes, with a Beta prior by origin and trust: Kognai verified (4, 1), reviewed outside (2, 2), anything else
+ * (1, 1). Execution success (the call returned) counts only when nothing was verified, at half weight, with its sample
+ * capped and shrunk by the number of distinct principals, so a tool cannot buy a score with self reports.
+ */
+import type { SuccessStats, ToolRecord } from '../types/tool';
+export declare const Z = 1.64;
+export declare function wilsonLower(ok: number, n: number, z?: number): number;
+export declare function priorOf(rec: Pick<ToolRecord, 'origin' | 'trust_state'>): [number, number];
+export declare const EXEC_CAP = 20;
+export declare const PRINCIPALS_FULL = 10;
+export declare function successScore(rec: Pick<ToolRecord, 'origin' | 'trust_state'>, s: SuccessStats): number;
+/** How much the evidence says about the tool, 0..1: trust plus sample size. */
+export declare function evidenceConfidence(rec: Pick<ToolRecord, 'trust_state' | 'origin'>, s: SuccessStats): number;

package/dist/rank/confidence.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRINCIPALS_FULL = exports.EXEC_CAP = exports.Z = void 0;
+exports.wilsonLower = wilsonLower;
+exports.priorOf = priorOf;
+exports.successScore = successScore;
+exports.evidenceConfidence = evidenceConfidence;
+exports.Z = 1.64;
+function wilsonLower(ok, n, z = exports.Z) {
+    if (n <= 0)
+        return 0;
+    const p = Math.min(1, Math.max(0, ok / n));
+    const z2 = z * z;
+    const den = 1 + z2 / n;
+    const centre = p + z2 / (2 * n);
+    const margin = z * Math.sqrt((p * (1 - p) + z2 / (4 * n)) / n);
+    return Math.max(0, (centre - margin) / den);
+}
+function priorOf(rec) {
+    if (rec.origin === 'kognai' && rec.trust_state === 'verified')
+        return [4, 1];
+    if (rec.trust_state === 'reviewed' || rec.trust_state === 'verified')
+        return [2, 2];
+    return [1, 1];
+}
+exports.EXEC_CAP = 20;
+exports.PRINCIPALS_FULL = 10;
+function successScore(rec, s) {
+    const [a, b] = priorOf(rec);
+    if (s.verified_n > 0) {
+        const shrink = Math.min(1, Math.max(1, s.distinct_principals) / exports.PRINCIPALS_FULL);
+        const n = s.verified_n * shrink;
+        const ok = s.verified_ok * shrink;
+        return wilsonLower(ok + a, n + a + b);
+    }
+    if (s.exec_n > 0) {
+        const shrink = Math.min(1, Math.max(1, s.distinct_principals) / exports.PRINCIPALS_FULL);
+        const n = Math.min(exports.EXEC_CAP, s.exec_n) * shrink;
+        const ok = n * (s.exec_ok / s.exec_n);
+        return 0.5 * wilsonLower(ok + a, n + a + b);
+    }
+    return wilsonLower(a, a + b);
+}
+/** How much the evidence says about the tool, 0..1: trust plus sample size. */
+function evidenceConfidence(rec, s) {
+    const base = rec.trust_state === 'verified' ? 0.7 : rec.trust_state === 'reviewed' ? 0.55 : 0.3;
+    return Math.min(1, base + 0.3 * (1 - 1 / (1 + s.verified_n / 10)));
+}

package/dist/rank/ranker.d.ts

@@ -0,0 +1,34 @@
+import type { Retrieved } from '../retrieve/hybrid';
+import type { ScorePart } from '../types/route';
+import type { EvidenceStore, SkillIndex, SkillRef } from '../types/ports';
+import type { SuccessStats } from '../types/tool';
+import { type FitWeights, type Weights } from './weights';
+export interface RankOpts {
+    weights?: Weights;
+    fitWeights?: FitWeights;
+    use?: {
+        capability: boolean;
+        vector: boolean;
+        lexical: boolean;
+    };
+    /** 'full' = every part; 'fit' = fit only (the hybrid retrieval baseline of the benchmark). */
+    scoring?: 'full' | 'fit';
+    seed?: string;
+    exploration?: boolean;
+    evidence?: EvidenceStore | null;
+    skills?: SkillIndex | null;
+    /** The AIAX ready bonus (weights.ts AIAX_READY_WEIGHT by default); 0 turns it off. */
+    aiaxWeight?: number;
+}
+export interface Ranked {
+    r: Retrieved;
+    fit: number;
+    score: number;
+    parts: Record<ScorePart, number>;
+    reasons: string[];
+    confidence: number;
+    skills: SkillRef[];
+    stats: SuccessStats;
+    cold: boolean;
+}
+export declare function rank(cands: Retrieved[], o?: RankOpts): Ranked[];

package/dist/rank/ranker.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rank = rank;
+/**
+ * The ranker (plan.md S3): score = weighted parts + exploration. Reasons are written from the parts by this code,
+ * never copied from provider text (T1). Deterministic for a given seed: exploration is a hash of the route id and the
+ * tool id, off unless asked for.
+ */
+const node_crypto_1 = require("node:crypto");
+const rules_1 = require("../eligibility/rules");
+const confidence_1 = require("./confidence");
+const weights_1 = require("./weights");
+const unitHash = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest().readUInt32BE(0) / 0xffffffff;
+function rank(cands, o = {}) {
+    const w = o.weights || weights_1.DEFAULT_WEIGHTS;
+    const aiaxW = typeof o.aiaxWeight === 'number' && Number.isFinite(o.aiaxWeight) && o.aiaxWeight >= 0 ? o.aiaxWeight : weights_1.AIAX_READY_WEIGHT;
+    const use = o.use || { capability: true, vector: true, lexical: true };
+    // cost and latency are normalised inside the node's candidate set
+    const prices = cands.map((c) => (0, rules_1.priceMicroUsd)(c.item.rec));
+    const known = prices.filter((p) => p !== null && p > 0n).map((p) => Math.log10(Number(p) + 1));
+    const pMin = known.length ? Math.min(...known) : 0;
+    const pMax = known.length ? Math.max(...known) : 0;
+    const lats = cands.map((c) => c.item.rec.latency.p50_ms).filter((x) => typeof x === 'number');
+    const lMin = lats.length ? Math.min(...lats) : 0;
+    const lMax = lats.length ? Math.max(...lats) : 0;
+    const out = cands.map((c, i) => {
+        const rec = c.item.rec;
+        const fit = (0, weights_1.fitOf)(c.signals, use, o.fitWeights || weights_1.DEFAULT_FIT);
+        const stats = o.evidence?.stats(rec.id) || rec.success;
+        const success = (0, confidence_1.successScore)(rec, stats);
+        const p = prices[i];
+        const cost = p === null ? 0.5 : p === 0n ? 1 : (pMax > pMin ? 1 - (Math.log10(Number(p) + 1) - pMin) / (pMax - pMin) : 0.8);
+        const l = rec.latency.p50_ms;
+        const latency = typeof l !== 'number' ? 0.5 : lMax > lMin ? 1 - (l - lMin) / (lMax - lMin) : 0.8;
+        const skills = (o.skills?.forTool(rec.id, c.item.op.op) || []).filter((s) => s.uplift > 0).sort((a, b) => b.uplift - a.uplift);
+        const skillPart = skills.length ? Math.min(1, skills[0].uplift) : 0;
+        const cold = stats.verified_n < 5;
+        const exploration = o.exploration && cold && fit >= 0.7 ? weights_1.EXPLORATION_MAX * unitHash(`${o.seed || ''}|${rec.id}`) : 0;
+        const aiax = rec.aiax_ready === true ? aiaxW : 0;
+        const parts = { fit, schema: c.signals.schema, success, cost, latency, skills: skillPart, exploration, aiax };
+        const score = o.scoring === 'fit' ? fit
+            : w.fit * fit + w.schema * c.signals.schema + w.success * success + w.cost * cost + w.latency * latency + w.skills * skillPart + exploration + aiax;
+        return { r: c, fit, score, parts, reasons: reasonsOf(c, parts, rec.trust_state, rec.origin, p, cold, skills), confidence: Math.min(fit, (0, confidence_1.evidenceConfidence)(rec, stats)), skills, stats, cold };
+    });
+    return out.sort((a, b) => b.score - a.score || (a.r.item.key < b.r.item.key ? -1 : 1));
+}
+function reasonsOf(c, parts, trust, origin, price, cold, skills) {
+    const r = [];
+    if (c.signals.capability === 1)
+        r.push('capability matches the step');
+    else if (c.signals.capability === 0.5)
+        r.push('related capability (same family)');
+    if (c.signals.lexical >= 0.5)
+        r.push('strong match on the request words');
+    else if (c.signals.lexical > 0)
+        r.push('partial match on the request words');
+    if (c.signals.cosine !== null)
+        r.push(`semantic similarity ${c.signals.cosine.toFixed(2)}`);
+    if (c.signals.schema === 0.3)
+        r.push('input schema unknown');
+    else if (c.signals.schema >= 0.8)
+        r.push('the request supplies the required inputs');
+    else
+        r.push('some required inputs are missing');
+    if (trust === 'verified' && origin === 'kognai')
+        r.push('Kognai tool, verified in the repository');
+    else if (trust === 'verified' || trust === 'reviewed')
+        r.push(`outside tool, ${trust} by the CTO desk`);
+    else if (trust === 'quarantined')
+        r.push('quarantined: listed for discovery, not executable');
+    r.push(price === null ? 'price unknown' : price === 0n ? 'free' : 'priced per call');
+    if (cold)
+        r.push('no verified runs yet (cold start)');
+    if (skills.length)
+        r.push(`a skill applies (${skills[0].evaluated ? 'evaluated' : 'unevaluated'} uplift ${skills[0].uplift.toFixed(2)})`);
+    if (parts.exploration > 0)
+        r.push('exploration bonus for a new tool');
+    if (parts.aiax > 0)
+        r.push('provider publishes a valid AIAX manifest');
+    return r;
+}

package/dist/rank/weights.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Ranking weights (plan.md S3, the directive's split): fit 30, schema 20, success 20, cost 10, latency 10, skills 10,
+ * plus up to 0.03 exploration. fit = 0.45 capability + 0.35 vector + 0.20 lexical. Configurable; validated to sum to 1.
+ */
+export interface Weights {
+    fit: number;
+    schema: number;
+    success: number;
+    cost: number;
+    latency: number;
+    skills: number;
+}
+export interface FitWeights {
+    capability: number;
+    vector: number;
+    lexical: number;
+}
+export declare const DEFAULT_WEIGHTS: Weights;
+export declare const DEFAULT_FIT: FitWeights;
+export declare const EXPLORATION_MAX = 0.03;
+/**
+ * AIAX ready (2026-10-12, AIAX rollout): a tool whose provider serves a valid AIAX manifest (/aiax/manifest.json,
+ * spec github.com/Godman-s/aiax) gets this flat bonus on top of the weighted parts, like exploration. A tie breaker
+ * only: at 0.02 it is smaller than a 0.07 gap in fit (0.30 x 0.07), so it never beats a clearly better match.
+ * Configurable per call (RankOpts.aiaxWeight, RouterConfig.aiaxWeight); 0 turns it off.
+ */
+export declare const AIAX_READY_WEIGHT = 0.02;
+/** A candidate whose fit is under this is not shown (fewer than 10 is normal). */
+export declare const RELEVANCE_FLOOR = 0.35;
+export declare function checkWeights(w: Weights, f?: FitWeights): void;
+/** Fit from the signals in use: weights of signals that are off are spread over the others. */
+export declare function fitOf(s: {
+    capability: number;
+    vector: number;
+    lexical: number;
+}, use: {
+    capability: boolean;
+    vector: boolean;
+    lexical: boolean;
+}, f?: FitWeights): number;

package/dist/rank/weights.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELEVANCE_FLOOR = exports.AIAX_READY_WEIGHT = exports.EXPLORATION_MAX = exports.DEFAULT_FIT = exports.DEFAULT_WEIGHTS = void 0;
+exports.checkWeights = checkWeights;
+exports.fitOf = fitOf;
+exports.DEFAULT_WEIGHTS = { fit: 0.30, schema: 0.20, success: 0.20, cost: 0.10, latency: 0.10, skills: 0.10 };
+exports.DEFAULT_FIT = { capability: 0.45, vector: 0.35, lexical: 0.20 };
+exports.EXPLORATION_MAX = 0.03;
+/**
+ * AIAX ready (2026-10-12, AIAX rollout): a tool whose provider serves a valid AIAX manifest (/aiax/manifest.json,
+ * spec github.com/Godman-s/aiax) gets this flat bonus on top of the weighted parts, like exploration. A tie breaker
+ * only: at 0.02 it is smaller than a 0.07 gap in fit (0.30 x 0.07), so it never beats a clearly better match.
+ * Configurable per call (RankOpts.aiaxWeight, RouterConfig.aiaxWeight); 0 turns it off.
+ */
+exports.AIAX_READY_WEIGHT = 0.02;
+/** A candidate whose fit is under this is not shown (fewer than 10 is normal). */
+exports.RELEVANCE_FLOOR = 0.35;
+function checkWeights(w, f = exports.DEFAULT_FIT) {
+    const s = w.fit + w.schema + w.success + w.cost + w.latency + w.skills;
+    if (Math.abs(s - 1) > 1e-9)
+        throw new Error(`ranking weights sum to ${s}, not 1`);
+    const t = f.capability + f.vector + f.lexical;
+    if (Math.abs(t - 1) > 1e-9)
+        throw new Error(`fit weights sum to ${t}, not 1`);
+    for (const v of [...Object.values(w), ...Object.values(f)])
+        if (v < 0)
+            throw new Error('negative weight');
+}
+/** Fit from the signals in use: weights of signals that are off are spread over the others. */
+function fitOf(s, use, f = exports.DEFAULT_FIT) {
+    let num = 0;
+    let den = 0;
+    if (use.capability) {
+        num += f.capability * s.capability;
+        den += f.capability;
+    }
+    if (use.vector) {
+        num += f.vector * s.vector;
+        den += f.vector;
+    }
+    if (use.lexical) {
+        num += f.lexical * s.lexical;
+        den += f.lexical;
+    }
+    return den ? num / den : 0;
+}

package/dist/retrieve/bm25.d.ts

@@ -0,0 +1,21 @@
+export declare class Bm25Index {
+    readonly k1: number;
+    readonly b: number;
+    private postings;
+    private lengths;
+    private avgdl;
+    readonly keys: string[];
+    constructor(docs: Array<{
+        key: string;
+        text: string;
+    }>, k1?: number, b?: number);
+    get size(): number;
+    idf(term: string): number;
+    /** Scores by document index, for the given query tokens (repeats weigh more). */
+    scoreAll(queryTokens: string[]): Map<number, number>;
+    search(q: string | string[], k: number): Array<{
+        key: string;
+        index: number;
+        score: number;
+    }>;
+}

package/dist/retrieve/bm25.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bm25Index = void 0;
+/** BM25 lexical index (k1 1.2, b 0.75) over tokenised documents, built in memory at load time (ADR-003 rule 4). */
+const tokenise_1 = require("./tokenise");
+class Bm25Index {
+    k1;
+    b;
+    postings = new Map();
+    lengths;
+    avgdl;
+    keys;
+    constructor(docs, k1 = 1.2, b = 0.75) {
+        this.k1 = k1;
+        this.b = b;
+        this.keys = docs.map((d) => d.key);
+        this.lengths = new Float64Array(docs.length);
+        let total = 0;
+        docs.forEach((d, i) => {
+            const toks = (0, tokenise_1.tokenise)(d.text);
+            this.lengths[i] = toks.length;
+            total += toks.length;
+            const tf = new Map();
+            for (const t of toks)
+                tf.set(t, (tf.get(t) || 0) + 1);
+            for (const [t, n] of tf)
+                (this.postings.get(t) || this.postings.set(t, []).get(t)).push([i, n]);
+        });
+        this.avgdl = docs.length ? total / docs.length : 1;
+    }
+    get size() { return this.keys.length; }
+    idf(term) {
+        const df = this.postings.get(term)?.length || 0;
+        return Math.log(1 + (this.keys.length - df + 0.5) / (df + 0.5));
+    }
+    /** Scores by document index, for the given query tokens (repeats weigh more). */
+    scoreAll(queryTokens) {
+        const scores = new Map();
+        const qtf = new Map();
+        for (const t of queryTokens)
+            qtf.set(t, (qtf.get(t) || 0) + 1);
+        for (const [t, qn] of qtf) {
+            const post = this.postings.get(t);
+            if (!post)
+                continue;
+            const idf = this.idf(t);
+            for (const [i, tf] of post) {
+                const s = idf * (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * this.lengths[i] / this.avgdl));
+                scores.set(i, (scores.get(i) || 0) + s * qn);
+            }
+        }
+        return scores;
+    }
+    search(q, k) {
+        const toks = Array.isArray(q) ? q : (0, tokenise_1.tokenise)(q);
+        return [...this.scoreAll(toks)].sort((a, b) => b[1] - a[1] || a[0] - b[0]).slice(0, k).map(([i, s]) => ({ key: this.keys[i], index: i, score: s }));
+    }
+}
+exports.Bm25Index = Bm25Index;

package/dist/retrieve/capability.d.ts

@@ -0,0 +1 @@
+export declare function capabilityScore(nodeCap: string, opCaps: string[]): number;

package/dist/retrieve/capability.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilityScore = capabilityScore;
+/** Capability match: the classifier's capability on the operation = 1, a sibling in the same family = 0.5, else 0. */
+const taxonomy_1 = require("../classify/taxonomy");
+function capabilityScore(nodeCap, opCaps) {
+    if (opCaps.includes(nodeCap))
+        return 1;
+    const fam = (0, taxonomy_1.familyOf)(nodeCap);
+    if (fam && opCaps.some((c) => (0, taxonomy_1.familyOf)(c) === fam))
+        return 0.5;
+    return 0;
+}

package/dist/retrieve/hash-embed.d.ts

@@ -0,0 +1,4 @@
+import type { EmbeddingPort } from '../types/ports';
+export declare const HASH_MODEL = "ktr-hash-256";
+export declare function hashEmbed(text: string): Float32Array;
+export declare const hashEmbeddingPort: EmbeddingPort;