Engine Room Reference Knowledge Router

Is source-faithful public

This is a source-faithful public copy of the private routing decision, narrowed to run over a sanitized in-memory catalog with no private corpus attached. The private system keeps a catalog of reusable technique bundles, each tagged with the domains, clusters, and problem spaces it speaks to. When an agent has a problem in front of it, something has to decide which bundles are worth opening. This component is a source-faithful public copy of that decision, narrowed so it runs over a sanitized in-memory catalog with no private corpus attached.

Answers which catalog

It answers which catalog entries are relevant to a problem and why, giving every ranked entry a four-part score breakdown instead of one opaque relevance number. It answers one question: given a problem statement and a catalog, which entries are relevant, and why. The "why" is the point. Instead of one opaque relevance number, every ranked entry carries a four-part score breakdown, so a reader can see whether a row ranked because its structured routing fields matched, because its description happened to share words, or because a curated note carried the weight.

Runtime normalizes filters

The runtime normalizes, filters, scores, and emits a result record, without cloning repositories, reading private entry bodies, or running BM25, TF-IDF, or embedding search. The runtime is src/microcosm_core/engine_room/annex_knowledge_router.py. It normalizes, filters, scores, and emits a result record. It does not clone repositories, read private entry bodies, or run BM25, TF-IDF, or embedding search.

Purpose

Why a single relevance number fails

Ranking by one relevance number or bare substring presence cannot tell a deliberate metadata match from an incidental query word, yet only the former is trustworthy. Loose matching fails here for a specific reason. If you rank by a single relevance number, or by plain substring presence, you cannot tell whether a match came from metadata an author deliberately wrote or from a query word that happened to appear in some prose. Both look like "a match." Only one is trustworthy.

Tiered weights favor structured routing fields

Tiered weights encode that distinction: an exact problem_spaces match scores 120 points while the same word in a description scores 6, a deliberately simple weighted-token scorer. The component encodes that distinction as tiered weights. Structured routing fields score far higher than free text. An exact match on a problem_spaces field is worth 120 points. The same word appearing in a description is worth 6. This is a deliberately simple weighted-token scorer, not a learned retriever, and the page does not dress it as one.

How it works

Ranking runs in

The ranking runs in execution order inside route_annexes, wrapped by route_catalog. The ranking runs in execution order inside route_annexes, wrapped by route_catalog.

Normalize the problem into query tokens

First, _normalized_query_text lowercases and cleans the problem and _query_tokens drops stopwords, so if nothing survives, route_annexes returns no candidates and the result is no-match. First, normalize. _normalized_query_text lowercases the problem, turns slashes, underscores, and hyphens into spaces, and drops remaining punctuation. _query_tokens then splits it and removes a small stopword set, ROUTE_MATCH_STOPWORDS. If nothing survives normalization, route_annexes returns no candidates, which becomes a no-match result.

Filter on domain or cluster first

Second, a caller-supplied domain or cluster must exactly match the entry's normalized fields, or the entry is dropped before any scoring can rescue it. Second, filter. For each catalog entry, if the caller passed a domain or cluster, the entry's normalized domains or clusters must contain an exact match. Otherwise the entry is dropped before any scoring can rescue it.

Four-tier scoring in _route_match_score

Third, _route_match_score scores each field as exact, phrase-substring, or per-token overlap, and every tier keeps the maximum over its fields. Third, score in four tiers. _route_match_score returns the exact weight when the normalized query equals the field, the phrase weight when the query is a substring of the field, otherwise the per-token weight times the count of overlapping tokens. Each tier keeps the maximum over its fields:

• structured routing fields (problem spaces, capabilities, domains, clusters): 120 / 80 / 18
• family text (slug, display name, description, tags): 32 / 24 / 6
• open-first summaries: 20 / 16 / 4
• curated notes, ordered first by sort_notes_by_relevance: 18 / 12 / 3, and a matching note adds its id to matched_note_ids

Sum tiers, threshold, sort, and limit

Fourth, the four tiers sum to a total that drops any row at zero or below, and survivors sort by descending score then slug, with an optional limit trimming the list. Fourth, sum and threshold. The total is the four tiers added together. A total of zero or less drops the row. Each surviving row keeps its score, its match_breakdown, its matched note ids (capped at eight), and its routing_summary. route_annexes sorts by descending score then slug, and an optional limit trims the list.

route_catalog wraps the result record

Fifth, route_catalog returns a status record of routed or no_match carrying the row count, the echoed problem and filters, source refs, and the authority bounds. Fifth, wrap. route_catalog returns the result record: status of routed or no_match, row_count, the problem echoed back, the domain and cluster filters, source_refs, claim_ceiling, and anti_claims.

_routing_summary_from_family assembles routing fields

One helper, _routing_summary_from_family, builds each entry's routing summary from its own routing block plus routing pulled from its notes, deduping while preserving order. One helper does the assembly. _routing_summary_from_family builds each entry's routing_summary from its own routing block plus routing pulled from its notes, deduping while preserving order.

flowchart TD Problem["Problem statement normalize to tokens"] --> Empty{"Empty after normalization?"} Empty -->|yes| NoMatch["status: no_match"] Empty -->|no| Filter{"domain / cluster filter matches?"} Filter -->|no| Drop["excluded before scoring"] Filter -->|yes| Score["four-tier weighted-token score"] Score --> Threshold{"total score > 0?"} Threshold -->|no| Drop Threshold -->|yes| Ranked["ranked rows score + match_breakdown"]

Negative cases

The public fixtures hold two positive and two negative cases.

empty_problem_no_match: no tokens survive

empty_problem_no_match sends the empty string, so normalization leaves no tokens, route_annexes returns nothing, and the status is no_match. empty_problem_no_match sends the empty string as the problem. After normalization there are no tokens, route_annexes returns nothing, and the status is no_match.

domain_filter_no_match: filter vetoes a text match

domain_filter_no_match supplies a domain no entry lists, so every entry is excluded before scoring, showing a domain filter can veto a row that text alone would have ranked. domain_filter_no_match sends "forecast error scoring" with the domain filter "agent-runtime". No catalog entry lists that domain, so every entry is excluded before scoring and the result is no_match. This is the filter path: a domain filter can veto an entry that text alone would have ranked.

Two positive cases rank on fields and notes

The positive cases rank provider-rate-limit-patterns above 80 on structured fields and above 40 through a curated note, and evaluate_fixture_dir folds all four cases into a pass or fail. The positive cases anchor the other side. provider_backoff_route ("rate limit and back off across multiple LLM providers") ranks provider-rate-limit-patterns on structured fields with a score of at least

through the curated note note_provider_backoff with a score of at least 40. evaluate_fixture_dir turns the four cases into case_count, passed_case_count, and a pass or fail status.

1. note_match ("provider rate limit retry result record") ranks the same entry

Prior Art Grounding

Lineage in fielded and explainable sparse search

The design borrows information retrieval's inspectable, field-weighted scoring, whose closest lineage is fielded search and explainable sparse term scoring, named by two reference points. The component borrows the general information-retrieval pattern of scoring a candidate set with visible term evidence and returning ranked, inspectable matches. Its closest lineage is fielded search, where structured fields weigh more than body text, and explainable sparse term scoring. Two reference points in that lineage:

• Text REtrieval Conference (TREC) as the long-running benchmark line for retrieval tasks, relevance judgments, and scored runs.
• Apache Lucene `BM25Similarity` as a concrete example of explainable sparse term scoring.

Field-weighting borrowed, dense retrieval refused

The component takes only the inspectable, field-weighted idea and implements no BM25, no TF-IDF, and no embedding search. The component takes the inspectable, field-weighted idea and nothing more. It does not implement BM25, TF-IDF, or embeddings.

Validation Result record Path

Reader-verifiable checks are

The reader-verifiable checks are the focused test and the paper-module corpus readback. The reader-verifiable checks are the focused test and the paper-module corpus readback:

PYTHONPATH=src ./repo-pytest tests/test_engine_room_annex_knowledge_router.py -q
cd microcosm-substrate && PYTHONPATH=src ../repo-python scripts/build_doctrine_projection.py --check-paper-module-corpus

You can also replay the fixtures directly:

PYTHONPATH=src python3 -m microcosm_core.engine_room.annex_knowledge_router evaluate-fixtures \
  --input fixtures/first_wave/engine_room_annex_knowledge_router/input \
  --json

What a pass proves here

A pass means the public fixture behavior and JSON projection are still reproducible, and it means nothing more than that. A pass means the public fixture behavior and the JSON bundle projection are still reproducible. It does not mean anything more.