Catalogue Router

What it answers

"Here is what I am building — which of these listings actually matter, and which silent failures am I exposed to?"

```ts
const r = routeProject({
  deps: ["dotenv", "stripe", "zod"],
  stack: ["nextjs", "postgres", "row-level-security"],
  hosting: "vercel",
  description: "Multi-tenant SaaS billing app. I edited the .env file for config but the app still reads the old value.",
});
```

`r.free` takes nothing. `r.paid` costs money, and each item's `line` is copied verbatim from the catalogue and states the failure it prevents. `r.reference` is open source the catalogue points at but has not priced or assured — a third bucket rather than folding them into "free", because nobody has verified those are safe to run.

Why it stays quiet

A router that always finds something is an advertisement, not advice. Most calls come back with less than you fed in. An ordinary React app with local storage, a settings page, a coffee-shop landing page, a log-rotation script — all silent, and all pinned as tests.

`status: "NO_MATCH"` is a first-class outcome, not a fallback. Its finding names what was checked — how many deps, how many tags, how long the description, against how many snapshotted listings, dated — rather than claiming the thing you are building has no gap.

The correction it made on itself

It started at the threshold its neighbouring matcher uses: 2 distinct shared terms. Measured on its own 6-case negative set, that fired false positives 5 times out of 6 — a todo-list app matched a pricing listing, a settings page with a dark-mode toggle matched a money parser. A structured profile pools stack, deps, hosting and a paragraph into one bag, which is denser than a single sentence and throws off more coincidental overlap.

At 3 distinct terms, on the identical set: 0 of 6. The sweep that produced both numbers ships in `evidence/MEASURED.txt` and regenerates with one command.

What it refuses to guess

There is no alias table. Matching is against the literal token you pass.

• `deps: ["jsonwebtoken"]` will not find the JWT listing. Different literal string, however well-known the association.
• `deps: ["xlsx"]` will not find the SheetJS listing, even though xlsx is the package SheetJS publishes.
• `deps: ["dotenv"]` alone will not find the env-precedence listing — but describing the symptom does, and the suite pins both the miss and the recovery.

An alias table would fix the first two and guess wrong on a hundred nobody has checked. Inclusion is never a numeric cutoff you could tune: what separates a match from a coincidence is the STRUCTURE of the evidence — an exact package name, an exact title word, an exact capability tag, or several independent terms at once — never one word's rarity. 1,405 of the snapshot's 1,744 distinct stems occur in only 1-3 entries, so 80% of the vocabulary is "rare" and rarity alone means nothing.

Shortlist discipline

Capped at 8 across all buckets, because a list of twenty is not advice. When more qualify, a `TRUNCATED_TO_CAP` finding says so rather than letting you assume the shortlist was exhaustive. Anything unassured raises `UNVERIFIED_TIER_PRESENT` explaining what that tier does and does not mean.

Staleness, disclosed

The bundled snapshot is 255 listings dated 2026-08-07. `cataloguedCount` and `cataloguedAt` come back on every result, so a stale copy is detectable rather than silently assumed current. It carries no descriptions, offers, prices or trust scores — only what matching needs.

Proof

47 tests. Eight deliberate defects were applied to the real source and the suite caught 8 of 8 — including three that a previous round survived: an off-by-one on the signal threshold, a guard inversion that would let a first-party listing be reported as the package you depend on, and a dropped tie-break that reordered equally-scored results. Each survivor was applied, run, and observed changing real output before a test was written for it.

Delivery

Source delivered as a private repository invite within 24 hours. Use and modify in any number of products; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function routeProject(profile: ProjectProfile, index: BuiltIndex = DEFAULT_INDEX): RouterResult;
  export function stem(word: string): string;
  export function tokenize(text: string | null | undefined): string[];
  export function rawWords(text: string | null | undefined): string[];
  export function titleWords(text: string | null | undefined): string[];
  export function canonical(text: string): string;
  export function leafSegment(text: string): string;
  export function slugify(text: string): string;

  export type PriceBand = "free" | "under-50" | "50-99" | "100-plus" | "unknown";
  export type AssuranceTier = "verified" | "basic" | "unverified";
  export type MatchReason = | { kind: "namesake";
  export type RouterStatus = "MATCHED" | "NO_MATCH";