Reference Knowledge Routing

Problems route to ranked reference entries or no match

It takes a plain-English problem and a small reference catalog and returns the ranked entries most likely to help, or no_match when nothing overlaps rather than a forced guess. annex_knowledge_routing takes a plain-English problem and a small catalog of reference entries and returns the entries most likely to help, ranked, with a breakdown of why each one matched. When nothing in the catalog overlaps the problem, it returns no_match rather than a forced best guess.

Public routing records expose scores without bodies

Each entry carries structured tags, description text, open-first summaries, and notes, and the router scores across those four kinds of evidence, weighting structured tags most, then ranks entries above zero. Each catalog entry carries structured routing tags (domains, clusters, problem-spaces, capabilities), some free description text, short open-first summaries, and curated notes. The router scores an entry against the problem across those four kinds of evidence, weighting the structured tags most, then ranks the entries that scored above zero. The result is a status, a ranked list of rows, and a per-row score breakdown.

Routing evidence does not become implementation authority

It is a plain keyword-overlap matcher, not BM25, TF-IDF, or embedding search, and it reads only the in-memory catalog handed to it. It is a keyword-overlap matcher. It is not BM25, TF-IDF, or embedding search, and it reads only the catalog handed to it in memory.

Purpose

The always-answer failure mode

A router that always returns its top entry hides the cases where it has nothing to offer, letting an off-topic problem still return a confident-looking row. A router that always returns its top-ranked entry hides the cases where it has nothing to offer. If every query gets an answer, a reader cannot tell a real match from noise, and an off-topic problem still returns a confident-looking row. That failure mode is the thing this component is built to avoid.

Explicit scores and an inspectable no_match

The router computes an explicit per-entry score, drops zero-score entries, returns no_match when all score zero or a filter empties the set, and exposes each row's tier scores. So the router computes an explicit score per entry and drops any entry that scores zero. If every entry scores zero, or a domain or cluster filter removes every candidate, the status is no_match. Each returned row also carries the tier-by-tier scores that produced its rank, so the ranking is inspectable instead of opaque.

How it works

route_catalog wraps the ranked rows

route_catalog calls route_annexes, wraps the rows into a record whose status is routed or no_match, and stamps the CLAIM_CEILING and ANTI_CLAIMS constants onto the output. The public entry point is route_catalog in src/microcosm_core/engine_room/annex_knowledge_router.py. It calls route_annexes and wraps the ranked rows into a result record whose status is routed when at least one row survived and no_match when the list is empty. It also stamps the fixed CLAIM_CEILING and ANTI_CLAIMS constants onto the record so the scope limit travels with the output.

route_annexes normalizes the problem text

route_annexes does the work, normalizing the problem with _normalized_query_text (lowercase, split, strip, collapse), returning nothing on an empty problem, then iterating each catalog entry. route_annexes does the work. It normalizes the problem text with _normalized_query_text, which lowercases, splits on underscores and slashes, strips punctuation, and collapses whitespace. An empty normalized problem returns nothing at all. Then, for each entry in the catalog:

Building the routing summary and filtering

It first builds a routing summary from the entry's structured tags and note tags, and skips the entry before scoring if a domain or cluster filter finds no matching value. First it builds a routing summary with _routing_summary_from_family, which collects the entry's structured domains, clusters, problem_spaces, and status and folds in the problem_spaces and capabilities declared on the entry's notes. If a domain or cluster filter is set and the entry does not list a matching value, the entry is skipped before any scoring.

Four weighted tiers score every surviving entry

Each surviving reference entry is scored across four weighted tiers by the same _route_match_score function. Then it scores the surviving entry across four tiers, each with its own weights passed to _route_match_score:

Exact, phrase, and token scoring

_route_match_score returns the exact weight on an identical string, the phrase weight when the query is contained, or token count times weight otherwise, keeping each tier's best field. _route_match_score normalizes both the query and the candidate string. If they are identical it returns the exact weight. If the whole query appears inside the candidate it returns the phrase weight. Otherwise it counts how many query tokens appear in the candidate token set and returns that count times the token weight. Stopwords in ROUTE_MATCH_STOPWORDS are dropped before token counting, so common words like "the" or "with" cannot inflate a match. Within each tier the router keeps the single best field score, not the sum, so one strong field sets the tier.

Notes ranked by relevance carry their ids

sort_notes_by_relevance reads notes by a clamped 0-100 relevance and note id, and up to eight matched note ids ride the row so a reader sees which note carried the match. Notes are read in relevance order by sort_notes_by_relevance, which sorts by a clamped 0-100 relevance value and then by note id. When a note contributes a positive score, its id is recorded, and up to eight matched note ids ride along on the row so a reader can see which note carried the match.

Summing tiers into ranked rows

The four tier scores sum to a total, zero-or-less entries are dropped, and the rest sort by descending score, ties broken by slug, each row carrying its match_breakdown. The four tier scores are summed into a total. Entries with a total of zero or less are dropped. The rest are sorted by descending score, ties broken by slug, and returned as rows carrying the slug, display name, total score, the match_breakdown of the four tier scores, and the matched note ids.

flowchart TD Problem["Problem text (+ optional domain/cluster filter)"] Summary["Build routing summary structured tags + note tags"] Filter["Domain / cluster filter skip non-matching entries"] Score["Score four tiers structured > family > open-first > notes"] Rank["Sum, drop zero-score entries, rank by score then slug"] Routed["status routed rows + match breakdown"] NoMatch["status no_match every entry scored zero or filter emptied the set"] Problem --> Summary --> Filter --> Score --> Rank Rank -->|at least one positive row| Routed Rank -->|no rows| NoMatch

The component wrapper checks fixture cases

The component wrapper drives the real route_catalog per fixture case, compares observed status, slug, score, and note ids to expectations, and passes only when every positive and negative case behaves. The component wrapper in src/microcosm_core/organs/annex_knowledge_routing.py runs this bundle against bounded public fixture cases. build_result reads the fixture directory and calls _evaluate_case per case, which drives the real route_catalog and compares the observed status, top slug, score, and matched note ids against the case's declared expectations. It separates positive from negative cases and reports pass only when every positive case routes as expected, every negative case is rejected, and both planted negatives named in EXPECTED_NEGATIVE_CASES are present. run writes the metadata-only result, board, validation, and sign-off records through write_json_atomic; result_card projects the compact board; run_annex_knowledge_routing_bundle is the bundle-caller alias for run.

Negative cases

Two positives, two planted negatives

The fixture set carries two positive cases and two planted negatives, and the component self-falsifies on the negatives by recomputation. The fixture set carries two positive cases and two planted negatives, and the component self-falsifies on the negatives by recomputation.

no_overlap_rejected: nothing scores

no_overlap_rejected sends an off-topic problem whose tokens overlap no entry, so every tier scores zero and the status recomputes to no_match. no_overlap_rejected sends the problem "subaquatic origami choreography for migrating waterfowl" against the catalog. No token overlaps any entry, every tier scores zero, and the status recomputes to no_match.

domain_filter_rejected: filter empties the set

domain_filter_rejected sends an otherwise-matchable problem under an agent-runtime domain filter that removes every non-declaring candidate, so the result is no_match. domain_filter_rejected sends "forecast error scoring for market outcomes" with a domain filter of agent-runtime. The problem could otherwise match, but the filter removes every candidate that does not declare that domain, so the result is no_match.

Two positives pin the structured and notes paths

The positives pin both paths: structured_route_ok routes through the structured tier above score 80, and note_route_ok routes through the notes tier above 40 with note_provider_backoff on the top row. The positive cases pin the two routing paths. structured_route_ok routes "rate limit backoff across multiple llm providers" to provider-rate-limit-patterns through the structured tier above a minimum score of 80. note_route_ok routes "provider rate limit retry result record" to the same slug through the notes tier above a minimum score of 40, and requires the matched note id note_provider_backoff to appear on the top row.

Prior Art Grounding

Lexical overlap, not a learned ranker

The mechanism is ordinary tiered weighted keyword overlap that stays lexical and shows its per-tier arithmetic, refactored source-faithfully from system/lib/annex_registry.py::route_annexes with no external citation claimed. The mechanism is ordinary weighted keyword overlap with tiered field weights, the kind of lexical scoring used in lightweight retrieval before ranked statistical models like BM25 or TF-IDF. This component deliberately stays at that lexical level and shows its per-tier arithmetic rather than reaching for a learned ranker. The local lineage is system/lib/annex_registry.py::route_annexes, of which this bundle is a source-faithful public refactor over a sanitized catalog. No external citation is claimed.

Validation Result record Path

Run the component against its public fixtures:

Coverage and corpus checks run from the root

The public coverage contract and paper-module parity check both rerun from the repository root. From the repository root, rerun the public coverage contract and the paper-module corpus parity check:

PYTHONPATH=src ./repo-pytest tests/test_plectis_paper_module_coverage_contract.py -q --tb=short
PYTHONPATH=src ./repo-python scripts/build_doctrine_projection.py --check-paper-module-corpus

What a pass certifies

A pass means the two positive cases routed to their expected slug above the minimum score, both negatives recomputed to no_match, and the reader page stays consistent with its source record. A pass means the two positive cases routed to their expected slug above the minimum score, both negatives recomputed to no_match, and the reader page stays consistent with its source record.