@knolo/core 3.1.2

package/dist/query.js

@@ -0,0 +1,463 @@
+/*
+ * query.ts
+ *
+ * Deterministic, embedding-free retrieval with:
+ *  - REQUIRED phrase enforcement (quoted and requirePhrases)
+ *  - Proximity bonus based on min cover span
+ *  - Optional heading overlap boost
+ *  - KNS numeric-signature tie-breaker (tiny)
+ *  - Near-duplicate suppression + MMR diversity
+ */
+import { tokenize, parsePhrases, normalize } from "./tokenize.js";
+import { rankBM25L } from "./rank.js";
+import { minCoverSpan, proximityMultiplier } from "./quality/proximity.js";
+import { diversifyAndDedupe } from "./quality/diversify.js";
+import { knsSignature, knsDistance } from "./quality/signature.js";
+import { decodeScaleF16, quantizeEmbeddingInt8L2Norm } from "./semantic.js";
+export function validateQueryOptions(opts) {
+    if (!opts)
+        return;
+    if (opts.topK !== undefined && (!Number.isInteger(opts.topK) || opts.topK < 1)) {
+        throw new Error("query(...): topK must be a positive integer.");
+    }
+    if (opts.minScore !== undefined && (!Number.isFinite(opts.minScore) || opts.minScore < 0)) {
+        throw new Error("query(...): minScore must be a finite number >= 0.");
+    }
+    if (opts.requirePhrases !== undefined && (!Array.isArray(opts.requirePhrases) || opts.requirePhrases.some((p) => typeof p !== "string"))) {
+        throw new Error("query(...): requirePhrases must be an array of strings when provided.");
+    }
+    validateStringOrStringArrayOption("namespace", opts.namespace);
+    validateStringOrStringArrayOption("source", opts.source);
+    if (opts.queryExpansion) {
+        const qe = opts.queryExpansion;
+        if (qe.enabled !== undefined && typeof qe.enabled !== "boolean") {
+            throw new Error("query(...): queryExpansion.enabled must be a boolean when provided.");
+        }
+        if (qe.docs !== undefined && (!Number.isInteger(qe.docs) || qe.docs < 1)) {
+            throw new Error("query(...): queryExpansion.docs must be a positive integer.");
+        }
+        if (qe.terms !== undefined && (!Number.isInteger(qe.terms) || qe.terms < 1)) {
+            throw new Error("query(...): queryExpansion.terms must be a positive integer.");
+        }
+        if (qe.weight !== undefined && (!Number.isFinite(qe.weight) || qe.weight < 0)) {
+            throw new Error("query(...): queryExpansion.weight must be a finite number >= 0.");
+        }
+        if (qe.minTermLength !== undefined && (!Number.isInteger(qe.minTermLength) || qe.minTermLength < 1)) {
+            throw new Error("query(...): queryExpansion.minTermLength must be a positive integer.");
+        }
+    }
+    validateSemanticQueryOptions(opts.semantic);
+}
+export function validateSemanticQueryOptions(options) {
+    if (!options)
+        return;
+    if (options.enabled !== undefined && typeof options.enabled !== "boolean") {
+        throw new Error("query(...): semantic.enabled must be a boolean when provided.");
+    }
+    if (options.mode !== undefined && options.mode !== "rerank") {
+        throw new Error('query(...): semantic.mode currently only supports "rerank".');
+    }
+    if (options.topN !== undefined && (!Number.isInteger(options.topN) || options.topN < 1)) {
+        throw new Error("query(...): semantic.topN must be a positive integer.");
+    }
+    if (options.minLexConfidence !== undefined && (!Number.isFinite(options.minLexConfidence) || options.minLexConfidence < 0 || options.minLexConfidence > 1)) {
+        throw new Error("query(...): semantic.minLexConfidence must be a finite number between 0 and 1.");
+    }
+    if (options.queryEmbedding !== undefined && !(options.queryEmbedding instanceof Float32Array)) {
+        throw new Error("query(...): semantic.queryEmbedding must be a Float32Array.");
+    }
+    if (options.blend) {
+        if (options.blend.enabled !== undefined && typeof options.blend.enabled !== "boolean") {
+            throw new Error("query(...): semantic.blend.enabled must be a boolean when provided.");
+        }
+        if (options.blend.wLex !== undefined && (!Number.isFinite(options.blend.wLex) || options.blend.wLex < 0)) {
+            throw new Error("query(...): semantic.blend.wLex must be a finite number >= 0.");
+        }
+        if (options.blend.wSem !== undefined && (!Number.isFinite(options.blend.wSem) || options.blend.wSem < 0)) {
+            throw new Error("query(...): semantic.blend.wSem must be a finite number >= 0.");
+        }
+    }
+    if (options.force !== undefined && typeof options.force !== "boolean") {
+        throw new Error("query(...): semantic.force must be a boolean when provided.");
+    }
+}
+export function query(pack, q, opts = {}) {
+    validateQueryOptions(opts);
+    const topK = opts.topK ?? 10;
+    const minScore = Number.isFinite(opts.minScore) ? Math.max(0, opts.minScore) : 0;
+    const expansionOpts = {
+        enabled: opts.queryExpansion?.enabled ?? true,
+        docs: Math.max(1, opts.queryExpansion?.docs ?? 3),
+        terms: Math.max(1, opts.queryExpansion?.terms ?? 4),
+        weight: Math.max(0, opts.queryExpansion?.weight ?? 0.35),
+        minTermLength: Math.max(2, opts.queryExpansion?.minTermLength ?? 3),
+    };
+    const semanticOpts = {
+        enabled: opts.semantic?.enabled ?? false,
+        mode: opts.semantic?.mode ?? "rerank",
+        topN: Math.max(1, opts.semantic?.topN ?? 50),
+        minLexConfidence: clamp01(opts.semantic?.minLexConfidence ?? 0.35),
+        blend: {
+            enabled: opts.semantic?.blend?.enabled ?? true,
+            wLex: Math.max(0, opts.semantic?.blend?.wLex ?? 0.75),
+            wSem: Math.max(0, opts.semantic?.blend?.wSem ?? 0.25),
+        },
+        queryEmbedding: opts.semantic?.queryEmbedding,
+        force: opts.semantic?.force ?? false,
+    };
+    // --- Query parsing
+    const normTokens = tokenize(q).map((t) => t.term);
+    // Normalize quoted phrases from q
+    const quotedRaw = parsePhrases(q);
+    const quoted = quotedRaw.map((seq) => seq.map((t) => normalize(t)).flatMap((s) => s.split(/\s+/)).filter(Boolean));
+    // Normalize requirePhrases the same way
+    const extraReq = (opts.requirePhrases ?? [])
+        .map((s) => tokenize(s).map((t) => t.term))
+        .filter((arr) => arr.length > 0);
+    const requiredPhrases = [...quoted, ...extraReq];
+    const namespaceFilter = normalizeNamespaceFilter(opts.namespace);
+    const sourceFilter = normalizeSourceFilter(opts.source);
+    // --- Term ids for the free (unquoted) tokens in q
+    const termIds = normTokens
+        .map((t) => pack.lexicon.get(t))
+        .filter((id) => id !== undefined);
+    // If there are no free tokens but there ARE required phrases, we'll fill candidates from phrases later.
+    const termSet = new Set(termIds);
+    // --- Candidate map
+    const candidates = new Map();
+    // Query-time document frequency collection for BM25 IDF.
+    const dfs = new Map();
+    const usesOffsetBlockIds = (pack.meta?.version ?? 1) >= 3;
+    // Helper to harvest postings for a given set of termIds into candidates
+    function scanForTermIds(idWeights, cfg = { collectPositions: true, createCandidates: true }) {
+        const p = pack.postings;
+        let i = 0;
+        while (i < p.length) {
+            const tid = p[i++];
+            if (tid === 0)
+                continue;
+            const weight = idWeights.get(tid) ?? 0;
+            const relevant = weight > 0;
+            let termDf = 0;
+            let encodedBid = p[i++];
+            while (encodedBid !== 0) {
+                const bid = usesOffsetBlockIds ? encodedBid - 1 : encodedBid;
+                let pos = p[i++];
+                const positions = [];
+                while (pos !== 0) {
+                    positions.push(pos);
+                    pos = p[i++];
+                }
+                termDf++;
+                if (relevant && bid >= 0) {
+                    let entry = candidates.get(bid);
+                    if (!entry && cfg.createCandidates !== false) {
+                        entry = { tf: new Map(), pos: new Map() };
+                        candidates.set(bid, entry);
+                    }
+                    if (entry) {
+                        const prevTf = entry.tf.get(tid) ?? 0;
+                        entry.tf.set(tid, prevTf + positions.length * weight);
+                        if (cfg.collectPositions !== false) {
+                            entry.pos.set(tid, positions);
+                        }
+                    }
+                }
+                encodedBid = p[i++];
+            }
+            if (relevant)
+                dfs.set(tid, termDf);
+        }
+    }
+    // 1) Scan using tokens from q (if any)
+    if (termSet.size > 0) {
+        scanForTermIds(new Map(Array.from(termSet.values(), (tid) => [tid, 1])));
+    }
+    // 2) Phrase-first rescue:
+    // If nothing matched the free tokens, but we do have required phrases,
+    // build a fallback term set from ALL tokens that appear in those phrases and scan again.
+    if (candidates.size === 0 && requiredPhrases.length > 0) {
+        const phraseTokenIds = new Set();
+        for (const seq of requiredPhrases) {
+            for (const t of seq) {
+                const id = pack.lexicon.get(t);
+                if (id !== undefined)
+                    phraseTokenIds.add(id);
+            }
+        }
+        if (phraseTokenIds.size > 0) {
+            scanForTermIds(new Map(Array.from(phraseTokenIds.values(), (tid) => [tid, 1])));
+        }
+    }
+    // --- Namespace filtering
+    if (namespaceFilter.size > 0) {
+        for (const bid of [...candidates.keys()]) {
+            const ns = pack.namespaces?.[bid];
+            const normalizedNs = typeof ns === "string" ? normalize(ns) : "";
+            if (!normalizedNs || !namespaceFilter.has(normalizedNs)) {
+                candidates.delete(bid);
+            }
+        }
+    }
+    // --- Source/docId filtering
+    if (sourceFilter.size > 0) {
+        for (const bid of [...candidates.keys()]) {
+            const source = pack.docIds?.[bid];
+            const normalizedSource = typeof source === "string" ? normalize(source) : "";
+            if (!normalizedSource || !sourceFilter.has(normalizedSource)) {
+                candidates.delete(bid);
+            }
+        }
+    }
+    // --- Phrase enforcement (now that we have some candidates)
+    if (requiredPhrases.length > 0) {
+        for (const [bid, data] of [...candidates]) {
+            const text = pack.blocks[bid] || "";
+            const ok = requiredPhrases.every((seq) => containsPhrase(text, seq));
+            if (!ok)
+                candidates.delete(bid);
+            else
+                data.hasPhrase = true;
+        }
+    }
+    else if (quoted.length > 0) {
+        for (const [bid, data] of candidates) {
+            const text = pack.blocks[bid] || "";
+            data.hasPhrase = quoted.some((seq) => containsPhrase(text, seq));
+        }
+    }
+    // If still nothing, bail early
+    if (candidates.size === 0)
+        return [];
+    // --- Heading overlap
+    if (pack.headings?.length) {
+        const qset = new Set(normTokens);
+        const qUniqueCount = new Set(normTokens).size || 1;
+        for (const [bid, data] of candidates) {
+            const h = pack.headings[bid] ?? "";
+            const hTerms = tokenize(h || "").map((t) => t.term);
+            const overlap = new Set(hTerms.filter((t) => qset.has(t))).size;
+            data.headingScore = overlap / qUniqueCount;
+        }
+    }
+    // --- Rank with proximity bonus
+    const avgLen = pack.meta?.stats?.avgBlockLen ??
+        (pack.blocks.length
+            ? pack.blocks.reduce((s, b) => s + tokenize(b).length, 0) / pack.blocks.length
+            : 1);
+    const docCount = pack.meta?.stats?.blocks ?? pack.blocks.length;
+    let prelim = rankBM25L(candidates, avgLen, docCount, dfs, pack.blockTokenLens, {
+        proximityBonus: (cand) => proximityMultiplier(minCoverSpan(cand.pos)),
+    });
+    if (expansionOpts.enabled && prelim.length > 0) {
+        const expansionWeights = deriveExpansionTerms(pack, prelim, termSet, requiredPhrases, expansionOpts);
+        if (expansionWeights.size > 0) {
+            scanForTermIds(expansionWeights, { collectPositions: false, createCandidates: true });
+            prelim = rankBM25L(candidates, avgLen, docCount, dfs, pack.blockTokenLens, {
+                proximityBonus: (cand) => proximityMultiplier(minCoverSpan(cand.pos)),
+            });
+        }
+    }
+    if (prelim.length === 0)
+        return [];
+    if (minScore > 0) {
+        prelim = prelim.filter((item) => item.score >= minScore);
+        if (prelim.length === 0)
+            return [];
+    }
+    const confidence = lexConfidence(prelim);
+    if (shouldRerankWithSemantic(pack, semanticOpts, confidence)) {
+        prelim = rerankLexicalHitsWithSemantic(pack, prelim, semanticOpts);
+    }
+    // --- KNS tie-breaker + de-dup/MMR
+    const qSig = knsSignature(normalize(q));
+    const pool = prelim.slice(0, topK * 5).map((r) => {
+        const text = pack.blocks[r.blockId] || "";
+        const boost = 1 + 0.02 * (1 - knsDistance(qSig, knsSignature(text)));
+        return {
+            blockId: r.blockId,
+            score: r.score * boost,
+            text,
+            source: pack.docIds?.[r.blockId] ?? undefined,
+            namespace: pack.namespaces?.[r.blockId] ?? undefined,
+        };
+    });
+    const finalHits = diversifyAndDedupe(pool, { k: topK });
+    return finalHits;
+}
+export function lexConfidence(hits) {
+    if (hits.length === 0)
+        return 0;
+    const top1 = Math.max(0, hits[0]?.score ?? 0);
+    const top2 = Math.max(0, hits[1]?.score ?? 0);
+    const gapRatio = top1 > 0 ? clamp01((top1 - top2) / top1) : 0;
+    const strength = top1 > 0 ? top1 / (top1 + 1) : 0;
+    return clamp01(0.65 * gapRatio + 0.35 * strength);
+}
+function shouldRerankWithSemantic(pack, opts, confidence) {
+    if (!opts.enabled || opts.mode !== "rerank")
+        return false;
+    if (!pack.semantic)
+        return false;
+    if (!opts.queryEmbedding) {
+        throw new Error("query(...): semantic.queryEmbedding (Float32Array) is required when semantic.enabled=true.");
+    }
+    return opts.force || confidence < opts.minLexConfidence;
+}
+function rerankLexicalHitsWithSemantic(pack, prelim, opts) {
+    const sem = pack.semantic;
+    if (!sem || !opts.queryEmbedding)
+        return prelim;
+    if (sem.dims <= 0 || sem.vecs.length === 0 || sem.dims !== opts.queryEmbedding.length)
+        return prelim;
+    const topN = Math.min(opts.topN, prelim.length);
+    const rerankSlice = prelim.slice(0, topN);
+    const tail = prelim.slice(topN);
+    const lexScores = new Float64Array(topN);
+    for (let i = 0; i < topN; i++)
+        lexScores[i] = rerankSlice[i].score;
+    const normLex = minMaxNormalizeTyped(lexScores);
+    const quantizedQuery = quantizeEmbeddingInt8L2Norm(opts.queryEmbedding);
+    const semScores = scoreSemanticInt8(quantizedQuery.q, quantizedQuery.scale, sem, rerankSlice);
+    const normSem = minMaxNormalizeTyped(semScores);
+    const denom = opts.blend.wLex + opts.blend.wSem;
+    const wLex = denom > 0 ? opts.blend.wLex / denom : 0.5;
+    const wSem = denom > 0 ? opts.blend.wSem / denom : 0.5;
+    const reranked = new Array(topN);
+    for (let i = 0; i < topN; i++) {
+        const hit = rerankSlice[i];
+        reranked[i] = {
+            blockId: hit.blockId,
+            score: opts.blend.enabled ? wLex * normLex[i] + wSem * normSem[i] : semScores[i],
+        };
+    }
+    reranked.sort((a, b) => b.score - a.score || a.blockId - b.blockId);
+    return [...reranked, ...tail];
+}
+function scoreSemanticInt8(queryQ, queryScale, semantic, hits) {
+    const scores = new Float64Array(hits.length);
+    const dims = semantic.dims;
+    if (queryQ.length !== dims || queryScale === 0)
+        return scores;
+    const vecs = semantic.vecs;
+    const scales = semantic.scales;
+    for (let h = 0; h < hits.length; h++) {
+        const blockId = hits[h].blockId;
+        if (blockId < 0)
+            continue;
+        const base = blockId * dims;
+        if (base + dims > vecs.length)
+            continue;
+        let dot = 0;
+        for (let i = 0; i < dims; i++) {
+            dot += queryQ[i] * vecs[base + i];
+        }
+        const blockScale = scales?.[blockId] !== undefined ? decodeScaleF16(scales[blockId]) : (1 / 127);
+        scores[h] = dot * queryScale * blockScale;
+    }
+    return scores;
+}
+function minMaxNormalizeTyped(values) {
+    if (values.length === 0)
+        return values;
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < values.length; i++) {
+        const v = values[i];
+        if (v < min)
+            min = v;
+        if (v > max)
+            max = v;
+    }
+    if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+        const out = new Float64Array(values.length);
+        out.fill(1);
+        return out;
+    }
+    const out = new Float64Array(values.length);
+    const span = max - min;
+    for (let i = 0; i < values.length; i++) {
+        out[i] = clamp01((values[i] - min) / span);
+    }
+    return out;
+}
+function clamp01(v) {
+    if (!Number.isFinite(v))
+        return 0;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+function deriveExpansionTerms(pack, prelim, baseTermSet, requiredPhrases, opts) {
+    if (prelim.length === 0 || opts.weight <= 0)
+        return new Map();
+    const forbidden = new Set(baseTermSet);
+    for (const seq of requiredPhrases) {
+        for (const term of seq) {
+            const tid = pack.lexicon.get(term);
+            if (tid !== undefined)
+                forbidden.add(tid);
+        }
+    }
+    const cap = Math.min(opts.docs, prelim.length);
+    const bestScore = Math.max(prelim[0]?.score ?? 0, 1e-6);
+    const termScores = new Map();
+    for (let i = 0; i < cap; i++) {
+        const item = prelim[i];
+        const text = pack.blocks[item.blockId] ?? "";
+        const docWeight = Math.max(item.score / bestScore, 0.2);
+        const localTfs = new Map();
+        for (const tok of tokenize(text)) {
+            if (tok.term.length < opts.minTermLength)
+                continue;
+            const tid = pack.lexicon.get(tok.term);
+            if (tid === undefined || forbidden.has(tid))
+                continue;
+            localTfs.set(tid, (localTfs.get(tid) ?? 0) + 1);
+        }
+        for (const [tid, tf] of localTfs) {
+            termScores.set(tid, (termScores.get(tid) ?? 0) + tf * docWeight);
+        }
+    }
+    const selected = [...termScores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, opts.terms);
+    return new Map(selected.map(([tid, score]) => [tid, opts.weight * Math.max(0.5, Math.min(1.5, score))]));
+}
+/** Ordered phrase check using the SAME tokenizer/normalizer path as the index. */
+function containsPhrase(text, seq) {
+    if (seq.length === 0)
+        return false;
+    const seqNorm = tokenize(seq.join(" ")).map((t) => t.term);
+    const toks = tokenize(text).map((t) => t.term);
+    outer: for (let i = 0; i <= toks.length - seqNorm.length; i++) {
+        for (let j = 0; j < seqNorm.length; j++) {
+            if (toks[i + j] !== seqNorm[j])
+                continue outer;
+        }
+        return true;
+    }
+    return false;
+}
+function normalizeNamespaceFilter(input) {
+    if (input === undefined)
+        return new Set();
+    const values = Array.isArray(input) ? input : [input];
+    return new Set(values.map((v) => normalize(v)).filter(Boolean));
+}
+function normalizeSourceFilter(input) {
+    if (input === undefined)
+        return new Set();
+    const values = Array.isArray(input) ? input : [input];
+    return new Set(values.map((v) => normalize(v)).filter(Boolean));
+}
+function validateStringOrStringArrayOption(name, value) {
+    if (value === undefined)
+        return;
+    const valid = typeof value === "string" || (Array.isArray(value) && value.every((entry) => typeof entry === "string"));
+    if (!valid) {
+        throw new Error(`query(...): ${name} must be a string or an array of strings when provided.`);
+    }
+}

package/dist/rank.d.ts

@@ -0,0 +1,21 @@
+export type RankOptions = {
+    k1?: number;
+    b?: number;
+    headingBoost?: number;
+    phraseBoost?: number;
+    proximityBonus?: (cand: {
+        tf: Map<number, number>;
+        pos?: Map<number, number[]>;
+        hasPhrase?: boolean;
+        headingScore?: number;
+    }) => number;
+};
+export declare function rankBM25L(candidates: Map<number, {
+    tf: Map<number, number>;
+    pos?: Map<number, number[]>;
+    hasPhrase?: boolean;
+    headingScore?: number;
+}>, avgLen: number, docCount: number, dfs: Map<number, number>, blockTokenLens?: number[], opts?: RankOptions): Array<{
+    blockId: number;
+    score: number;
+}>;

package/dist/rank.js

@@ -0,0 +1,31 @@
+/*
+ * rank.ts
+ * BM25L ranker with optional heading/phrase boosts and a proximity bonus hook.
+ */
+export function rankBM25L(candidates, avgLen, docCount, dfs, blockTokenLens, opts = {}) {
+    const k1 = opts.k1 ?? 1.5;
+    const b = opts.b ?? 0.75;
+    const headingBoost = opts.headingBoost ?? 0.3;
+    const phraseBoost = opts.phraseBoost ?? 0.6;
+    const results = [];
+    for (const [bid, data] of candidates) {
+        const len = blockTokenLens?.[bid] ?? (Array.from(data.tf.values()).reduce((sum, tf) => sum + tf, 0) || 1);
+        let score = 0;
+        for (const [tid, tf] of data.tf) {
+            const df = dfs.get(tid) ?? 0;
+            const idf = Math.log(1 + (docCount - df + 0.5) / (df + 0.5));
+            const numer = tf * (k1 + 1);
+            const denom = tf + k1 * (1 - b + b * (len / avgLen));
+            score += idf * (numer / denom);
+        }
+        if (opts.proximityBonus)
+            score *= opts.proximityBonus(data) ?? 1;
+        if (data.hasPhrase)
+            score *= 1 + phraseBoost;
+        if (data.headingScore)
+            score *= 1 + headingBoost * data.headingScore;
+        results.push({ blockId: bid, score });
+    }
+    results.sort((a, b2) => b2.score - a.score);
+    return results;
+}

package/dist/router.d.ts

@@ -0,0 +1,28 @@
+import type { AgentDefinitionV1 } from './agent.js';
+export interface RouteCandidateV1 {
+    agentId: string;
+    score: number;
+    why?: string;
+}
+export interface RouteDecisionV1 {
+    type: 'route_decision';
+    intent?: string;
+    entities?: Record<string, unknown>;
+    candidates: RouteCandidateV1[];
+    selected: string;
+    needsTools?: string[];
+    risk?: 'low' | 'med' | 'high';
+}
+export declare function isRouteDecisionV1(x: unknown): x is RouteDecisionV1;
+export declare function validateRouteDecisionV1(decision: RouteDecisionV1, agentRegistry: Record<string, AgentDefinitionV1>): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function selectAgentIdFromRouteDecisionV1(decision: RouteDecisionV1, agentRegistry: Record<string, AgentDefinitionV1>, opts?: {
+    fallbackAgentId?: string;
+}): {
+    agentId: string;
+    reason: 'selected' | 'top_candidate' | 'fallback';
+};

package/dist/router.js

@@ -0,0 +1,74 @@
+export function isRouteDecisionV1(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const v = x;
+    if (v.type !== 'route_decision')
+        return false;
+    if (typeof v.selected !== 'string' || !v.selected.trim())
+        return false;
+    if (!Array.isArray(v.candidates) || v.candidates.length < 1)
+        return false;
+    if (v.needsTools !== undefined &&
+        (!Array.isArray(v.needsTools) ||
+            v.needsTools.some((toolId) => typeof toolId !== 'string'))) {
+        return false;
+    }
+    for (const candidate of v.candidates) {
+        if (!candidate || typeof candidate !== 'object')
+            return false;
+        const c = candidate;
+        if (typeof c.agentId !== 'string' || !c.agentId.trim())
+            return false;
+        if (typeof c.score !== 'number' || !Number.isFinite(c.score))
+            return false;
+        if (c.score < 0 || c.score > 1)
+            return false;
+        if (c.why !== undefined && typeof c.why !== 'string')
+            return false;
+    }
+    return true;
+}
+export function validateRouteDecisionV1(decision, agentRegistry) {
+    if (!agentRegistry[decision.selected]) {
+        return {
+            ok: false,
+            error: `selected agent is not registered: ${decision.selected}`,
+        };
+    }
+    const seen = new Set();
+    for (const candidate of decision.candidates) {
+        if (seen.has(candidate.agentId)) {
+            return {
+                ok: false,
+                error: `duplicate candidate agentId: ${candidate.agentId}`,
+            };
+        }
+        seen.add(candidate.agentId);
+        if (!agentRegistry[candidate.agentId]) {
+            return {
+                ok: false,
+                error: `candidate agent is not registered: ${candidate.agentId}`,
+            };
+        }
+    }
+    return { ok: true };
+}
+export function selectAgentIdFromRouteDecisionV1(decision, agentRegistry, opts = {}) {
+    if (agentRegistry[decision.selected]) {
+        return { agentId: decision.selected, reason: 'selected' };
+    }
+    const sortedCandidates = [...decision.candidates].sort((a, b) => b.score - a.score || a.agentId.localeCompare(b.agentId));
+    for (const candidate of sortedCandidates) {
+        if (agentRegistry[candidate.agentId]) {
+            return { agentId: candidate.agentId, reason: 'top_candidate' };
+        }
+    }
+    if (opts.fallbackAgentId && agentRegistry[opts.fallbackAgentId]) {
+        return { agentId: opts.fallbackAgentId, reason: 'fallback' };
+    }
+    const defaultAgentId = Object.keys(agentRegistry).sort()[0];
+    if (defaultAgentId) {
+        return { agentId: defaultAgentId, reason: 'fallback' };
+    }
+    return { agentId: '', reason: 'fallback' };
+}

package/dist/routing_profile.d.ts

@@ -0,0 +1,19 @@
+import type { AgentDefinitionV1 } from './agent.js';
+import type { Pack } from './pack.js';
+export interface AgentRoutingProfileV1 {
+    agentId: string;
+    namespace?: string;
+    heading?: string;
+    description?: string;
+    tags: string[];
+    examples: string[];
+    capabilities: string[];
+    toolPolicy?: unknown;
+    toolPolicySummary?: {
+        mode: 'allow_all' | 'deny_all' | 'mixed' | 'unknown';
+        allowed?: string[];
+        denied?: string[];
+    };
+}
+export declare function getAgentRoutingProfileV1(agent: AgentDefinitionV1): AgentRoutingProfileV1;
+export declare function getPackRoutingProfilesV1(pack: Pack): AgentRoutingProfileV1[];