@runbooks/search 0.1.0

package/dist/log.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Zero-result queries, logged without PII (§17, M-03).
+ *
+ * An empty result is a request for content: somebody arrived with a real problem and the
+ * catalog did not have it, which is worth more than a search that matched. So the fact
+ * that it happened is kept — and nothing else is.
+ *
+ * The rule is structural rather than a redaction step. A log line is built from a fixed
+ * set of fields, none of which can carry a query string or anything about the client, so
+ * there is no path by which one arrives and later has to be scrubbed. "We redact before
+ * storing" is a promise made by whoever already has the data.
+ */
+import { type SearchQuery } from "./search.js";
+export interface ZeroResultLine {
+    /** The day. Not the moment: a timestamp series is a movement log of one organization. */
+    readonly date: string;
+    /** Which facets were used, not what they were set to for free-text ones. */
+    readonly facets: readonly string[];
+    /** How many words the symptom had. A length is not a query. */
+    readonly symptom_words: number;
+    /** The controlled values, which are drawn from a published vocabulary and identify nobody. */
+    readonly target?: string;
+    readonly risk_max?: string;
+    readonly profile?: string;
+    readonly trust_min: string;
+}
+/**
+ * What may be recorded about a query that found nothing.
+ *
+ * The symptom text never appears — not hashed, not truncated. A hashed query is a query
+ * for anybody holding a candidate list, and an ops search reads like an incident report:
+ * a hostname, a customer name, a table nobody else has.
+ */
+export declare function zeroResultLine(query: SearchQuery, today: string): ZeroResultLine;
+/**
+ * The aggregate a backlog is built from: which facet combinations keep coming back empty.
+ *
+ * Counts only, and only above a floor — a combination seen once is one organization's
+ * afternoon, and publishing it would be publishing them.
+ */
+export declare const REPORTABLE_FLOOR = 5;
+export declare function gaps(lines: readonly ZeroResultLine[], floor?: number): {
+    readonly facets: string;
+    readonly count: number;
+}[];

package/dist/log.js

@@ -0,0 +1,58 @@
+/**
+ * Zero-result queries, logged without PII (§17, M-03).
+ *
+ * An empty result is a request for content: somebody arrived with a real problem and the
+ * catalog did not have it, which is worth more than a search that matched. So the fact
+ * that it happened is kept — and nothing else is.
+ *
+ * The rule is structural rather than a redaction step. A log line is built from a fixed
+ * set of fields, none of which can carry a query string or anything about the client, so
+ * there is no path by which one arrives and later has to be scrubbed. "We redact before
+ * storing" is a promise made by whoever already has the data.
+ */
+import { DEFAULT_TRUST_MIN } from "./search.js";
+/**
+ * What may be recorded about a query that found nothing.
+ *
+ * The symptom text never appears — not hashed, not truncated. A hashed query is a query
+ * for anybody holding a candidate list, and an ops search reads like an incident report:
+ * a hostname, a customer name, a table nobody else has.
+ */
+export function zeroResultLine(query, today) {
+    const facets = [
+        query.symptom ? "symptom" : undefined,
+        query.target ? "target" : undefined,
+        query.risk_max ? "risk_max" : undefined,
+        query.execution ? "execution" : undefined,
+        query.profile ? "profile" : undefined,
+        query.available ? "available" : undefined,
+        query.trust_min ? "trust_min" : undefined,
+    ].filter((facet) => facet !== undefined);
+    return {
+        date: today,
+        facets,
+        symptom_words: query.symptom ? query.symptom.trim().split(/\s+/).filter(Boolean).length : 0,
+        ...(query.target ? { target: query.target } : {}),
+        ...(query.risk_max ? { risk_max: query.risk_max } : {}),
+        ...(query.profile ? { profile: query.profile } : {}),
+        trust_min: query.trust_min ?? DEFAULT_TRUST_MIN,
+    };
+}
+/**
+ * The aggregate a backlog is built from: which facet combinations keep coming back empty.
+ *
+ * Counts only, and only above a floor — a combination seen once is one organization's
+ * afternoon, and publishing it would be publishing them.
+ */
+export const REPORTABLE_FLOOR = 5;
+export function gaps(lines, floor = REPORTABLE_FLOOR) {
+    const tally = new Map();
+    for (const line of lines) {
+        const key = [...line.facets].sort().join("+") || "none";
+        tally.set(key, (tally.get(key) ?? 0) + 1);
+    }
+    return [...tally.entries()]
+        .filter(([, count]) => count >= floor)
+        .map(([facets, count]) => ({ facets, count }))
+        .sort((a, b) => b.count - a.count);
+}

package/dist/search.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `/v1/search` (M-03, §12, §17).
+ *
+ * §17 defines three intents, and the third — "given the MCP servers I have connected,
+ * what can I actually execute" — is the agent's primary path. It is a first-class query
+ * here rather than a filter bolted onto text search, because the two questions have
+ * different right answers: a text search wants the best match, and an agent wants the
+ * set it can run without stopping halfway.
+ */
+import { type Bm25Index, type Synonyms } from "./bm25.js";
+export type Trust = "T0" | "T1" | "T2" | "T3" | "T4";
+export type Risk = "read-only" | "reversible-write" | "destructive" | "irreversible";
+export interface IndexedRecord {
+    readonly ref: string;
+    readonly title: string;
+    readonly description: string;
+    readonly targets: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly trust: Trust;
+    readonly risk: Risk;
+    readonly profile: string;
+    readonly execution?: string;
+    /** The topic this record answers, when one has been authored (I-05). */
+    readonly topic?: string;
+}
+export interface SearchQuery {
+    readonly symptom?: string;
+    readonly target?: string;
+    readonly risk_max?: Risk;
+    readonly execution?: string;
+    /** Defaults to T2 (§8, §17). Below it is an explicit act, never an omission. */
+    readonly trust_min?: Trust;
+    readonly profile?: string;
+    /**
+     * What the caller can actually run. A record is returned only if **every** capability
+     * it declares is in this set — see `executableWith`.
+     */
+    readonly available?: readonly string[];
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+export interface Hit {
+    readonly ref: string;
+    readonly score: number;
+    /** Set when this hit stands for a topic rather than a record (§17, G5). */
+    readonly topic?: string;
+}
+export interface SearchResult {
+    readonly hits: readonly Hit[];
+    readonly total: number;
+    /**
+     * Where to continue: an opaque cursor naming the last hit on this page and the query
+     * it came from (./cursor.ts). Not an offset — the result set is rebuilt per request,
+     * and an offset taken against one build skips whatever moved across the boundary in
+     * the next.
+     */
+    readonly next_cursor?: string;
+    /** What the query was resolved as, including the defaults it did not state. */
+    readonly applied: {
+        readonly trust_min: Trust;
+        readonly capability_semantics: "all-required-available";
+    };
+}
+export declare const DEFAULT_TRUST_MIN: Trust;
+export declare const DEFAULT_LIMIT = 25;
+/**
+ * Whether a caller can run this record, given what they have.
+ *
+ * **Every capability the record declares must be available.** The other reading — return
+ * anything that shares one capability — is a security footgun: it hands an agent a
+ * procedure it can start and cannot finish, and a procedure abandoned halfway has already
+ * done part of the work. Part of a destructive procedure is a state nobody designed.
+ *
+ * This is why the semantics are in the response as well as in the contract: a caller who
+ * assumed the other reading finds out from the answer rather than from an incident.
+ */
+export declare function executableWith(record: Pick<IndexedRecord, "capabilities">, available: readonly string[]): boolean;
+export interface SearchOptions {
+    /** Prebuilt, so the same ranking runs in a browser and in a Lambda. */
+    readonly index?: Bm25Index;
+    /**
+     * Words this catalog treats as one, from S-09's vocabulary.
+     *
+     * Data rather than a dependency, because this library is what the browser runs. Without
+     * it a reader who typed `kubernetes` found nothing while the record was indexed under
+     * `k8s` — and the clustering that groups records into topics had folded the two
+     * together all along, through the same vocabulary this table is built from.
+     */
+    readonly synonyms?: Synonyms;
+    /**
+     * The vector half of §17's hybrid. Absent offline, and absent is not a failure: BM25
+     * alone finds fewer things, and finding fewer things is recoverable in a way that
+     * inventing a ranking is not.
+     */
+    readonly semantic?: (query: string, refs: readonly string[]) => readonly {
+        ref: string;
+        score: number;
+    }[];
+}
+/**
+ * Run a query.
+ *
+ * Filters first, then ranking, then grouping, then the page. Filters first because
+ * `trust_min` is a safety default rather than a preference: a record that should not be
+ * in the answer must not be ranked into it and then trimmed, or the trimming becomes the
+ * thing that has to be right.
+ */
+export declare function runSearch(records: readonly IndexedRecord[], query: SearchQuery, options?: SearchOptions): SearchResult;

package/dist/search.js

@@ -0,0 +1,111 @@
+/**
+ * `/v1/search` (M-03, §12, §17).
+ *
+ * §17 defines three intents, and the third — "given the MCP servers I have connected,
+ * what can I actually execute" — is the agent's primary path. It is a first-class query
+ * here rather than a filter bolted onto text search, because the two questions have
+ * different right answers: a text search wants the best match, and an agent wants the
+ * set it can run without stopping halfway.
+ */
+import { buildIndex, search as bm25 } from "./bm25.js";
+import { encodeCursor, readCursor } from "./cursor.js";
+const TRUST_ORDER = ["T0", "T1", "T2", "T3", "T4"];
+const RISK_ORDER = ["read-only", "reversible-write", "destructive", "irreversible"];
+export const DEFAULT_TRUST_MIN = "T2";
+export const DEFAULT_LIMIT = 25;
+/**
+ * Whether a caller can run this record, given what they have.
+ *
+ * **Every capability the record declares must be available.** The other reading — return
+ * anything that shares one capability — is a security footgun: it hands an agent a
+ * procedure it can start and cannot finish, and a procedure abandoned halfway has already
+ * done part of the work. Part of a destructive procedure is a state nobody designed.
+ *
+ * This is why the semantics are in the response as well as in the contract: a caller who
+ * assumed the other reading finds out from the answer rather than from an incident.
+ */
+export function executableWith(record, available) {
+    const have = new Set(available);
+    return record.capabilities.every((capability) => have.has(capability));
+}
+function atLeast(level, minimum) {
+    return TRUST_ORDER.indexOf(level) >= TRUST_ORDER.indexOf(minimum);
+}
+function atMost(risk, maximum) {
+    return RISK_ORDER.indexOf(risk) <= RISK_ORDER.indexOf(maximum);
+}
+/**
+ * Run a query.
+ *
+ * Filters first, then ranking, then grouping, then the page. Filters first because
+ * `trust_min` is a safety default rather than a preference: a record that should not be
+ * in the answer must not be ranked into it and then trimmed, or the trimming becomes the
+ * thing that has to be right.
+ */
+export function runSearch(records, query, options = {}) {
+    const trustMin = query.trust_min ?? DEFAULT_TRUST_MIN;
+    const eligible = records.filter((record) => {
+        if (!atLeast(record.trust, trustMin))
+            return false;
+        if (query.target && !record.targets.includes(query.target))
+            return false;
+        if (query.risk_max && !atMost(record.risk, query.risk_max))
+            return false;
+        if (query.execution && record.execution !== query.execution)
+            return false;
+        if (query.profile && record.profile !== query.profile)
+            return false;
+        if (query.available && !executableWith(record, query.available))
+            return false;
+        return true;
+    });
+    let ranked;
+    if (query.symptom) {
+        const index = options.index ??
+            buildIndex(eligible.map((r) => ({ ref: r.ref, text: `${r.title} ${r.description} ${r.targets.join(" ")}` })), options.synonyms ?? {});
+        const allowed = new Set(eligible.map((r) => r.ref));
+        const lexical = bm25(index, query.symptom).filter((hit) => allowed.has(hit.ref));
+        const semantic = options.semantic?.(query.symptom, [...allowed]) ?? [];
+        const merged = new Map(lexical.map((hit) => [hit.ref, hit.score]));
+        for (const hit of semantic)
+            merged.set(hit.ref, (merged.get(hit.ref) ?? 0) + hit.score);
+        ranked = [...merged.entries()]
+            .map(([ref, score]) => ({ ref, score }))
+            .sort((a, b) => (b.score === a.score ? (a.ref < b.ref ? -1 : 1) : b.score - a.score));
+    }
+    else {
+        // No symptom: the facets are the query, and the order is stable rather than clever.
+        ranked = [...eligible].sort((a, b) => (a.ref < b.ref ? -1 : 1)).map((r) => ({ ref: r.ref, score: 0 }));
+    }
+    // §17 and G5: one line per topic where a topic exists, so variants do not compete.
+    const byRef = new Map(records.map((r) => [r.ref, r]));
+    const seenTopics = new Set();
+    const grouped = [];
+    for (const hit of ranked) {
+        const topic = byRef.get(hit.ref)?.topic;
+        if (!topic) {
+            grouped.push(hit);
+            continue;
+        }
+        if (seenTopics.has(topic))
+            continue;
+        seenTopics.add(topic);
+        grouped.push({ ...hit, topic });
+    }
+    const limit = query.limit ?? DEFAULT_LIMIT;
+    // A cursor resumes after a ref. An unreadable one starts from the beginning here; the
+    // endpoint refuses it outright, because a caller who sent one deserves to be told
+    // rather than handed page 1 believing it is page 3.
+    const read = query.cursor ? readCursor(query.cursor, query) : undefined;
+    const start = read?.ok === true ? grouped.findIndex((hit) => hit.ref === read.cursor.after) + 1 : 0;
+    const page = grouped.slice(start, start + limit);
+    const last = page[page.length - 1];
+    return {
+        hits: page,
+        total: grouped.length,
+        ...(start + page.length < grouped.length && last
+            ? { next_cursor: encodeCursor(last.ref, query) }
+            : {}),
+        applied: { trust_min: trustMin, capability_semantics: "all-required-available" },
+    };
+}

package/dist/search.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/search.test.js

@@ -0,0 +1,253 @@
+import { describe, it, expect } from "vitest";
+import { buildIndex, search as bm25, terms } from "./bm25.js";
+import { runSearch, executableWith, DEFAULT_TRUST_MIN, DEFAULT_LIMIT, } from "./search.js";
+import { zeroResultLine, gaps, REPORTABLE_FLOOR } from "./log.js";
+import { matchStack, excluded } from "./stack.js";
+const records = [
+    {
+        ref: "std/kafka-lag", title: "Kafka consumer group stuck", targets: ["kafka"],
+        description: "Offsets stop advancing and lag grows on a consumer group.",
+        capabilities: ["cli:kafka-consumer-groups", "cli:kubectl"], trust: "T2",
+        risk: "reversible-write", profile: "P1", execution: "human-with-agent",
+    },
+    {
+        ref: "std/drain-node", title: "Drain a NotReady node", targets: ["k8s"],
+        description: "A node is stuck NotReady and its pods are not rescheduled.",
+        capabilities: ["cli:kubectl"], trust: "T2", risk: "destructive", profile: "P1",
+        execution: "human-with-agent",
+    },
+    {
+        ref: "std/disk-pressure", title: "Disk pressure triage", targets: ["linux"],
+        description: "A filesystem is filling up and something has to be reclaimed.",
+        capabilities: ["cli:df", "cli:du"], trust: "T2", risk: "read-only", profile: "P1",
+        execution: "human-only",
+    },
+    {
+        ref: "acme/unreviewed", title: "Kafka lag, unreviewed", targets: ["kafka"],
+        description: "An unreviewed procedure about consumer lag.",
+        capabilities: ["cli:kafka-consumer-groups"], trust: "T1", risk: "read-only", profile: "P0",
+    },
+];
+/** §8 and §17: the default answer holds nothing below T2, and that is not an omission. */
+describe("the default response is T2 and above", () => {
+    it("leaves an unreviewed record out without being asked", () => {
+        const result = runSearch(records, { symptom: "kafka lag" });
+        expect(result.hits.map((h) => h.ref)).not.toContain("acme/unreviewed");
+    });
+    it("says which default it applied, so a caller is not guessing", () => {
+        expect(runSearch(records, {}).applied.trust_min).toBe(DEFAULT_TRUST_MIN);
+    });
+    it("includes it only when the caller asks for it explicitly", () => {
+        const result = runSearch(records, { symptom: "kafka lag", trust_min: "T1" });
+        expect(result.hits.map((h) => h.ref)).toContain("acme/unreviewed");
+    });
+    it("filters before ranking, so nothing below the floor is ranked and then trimmed", () => {
+        // With a limit of one, an unreviewed record that outranked the rest would still be
+        // absent — because it was never a candidate.
+        const result = runSearch(records, { symptom: "unreviewed procedure lag", limit: 1 });
+        expect(result.hits.map((h) => h.ref)).not.toContain("acme/unreviewed");
+    });
+});
+/**
+ * The footgun the criterion names: "anything sharing one capability" hands an agent a
+ * procedure it can start and cannot finish, and part of a destructive procedure is a
+ * state nobody designed.
+ */
+describe("capability search returns what the caller can actually run", () => {
+    it("requires every declared capability, not any of them", () => {
+        const result = runSearch(records, { available: ["cli:kubectl"] });
+        expect(result.hits.map((h) => h.ref)).toEqual(["std/drain-node"]);
+    });
+    it("returns a record once its whole set is available", () => {
+        const result = runSearch(records, { available: ["cli:kubectl", "cli:kafka-consumer-groups"] });
+        expect(result.hits.map((h) => h.ref)).toContain("std/kafka-lag");
+    });
+    it("says the semantics in the response, not only in the contract", () => {
+        expect(runSearch(records, { available: [] }).applied.capability_semantics)
+            .toBe("all-required-available");
+    });
+    it("returns nothing rather than something partial when nothing is offered", () => {
+        expect(runSearch(records, { available: [] }).hits).toEqual([]);
+    });
+    it.each([
+        [["cli:df"], []],
+        [["cli:df", "cli:du"], ["std/disk-pressure"]],
+    ])("with %o returns %o", (available, expected) => {
+        expect(runSearch(records, { available }).hits.map((h) => h.ref)).toEqual(expected);
+    });
+    it("is the same predicate a caller can apply themselves", () => {
+        expect(executableWith({ capabilities: ["a", "b"] }, ["a"])).toBe(false);
+        expect(executableWith({ capabilities: ["a", "b"] }, ["a", "b", "c"])).toBe(true);
+        expect(executableWith({ capabilities: [] }, [])).toBe(true);
+    });
+});
+describe("facets narrow without ranking", () => {
+    it.each([
+        [{ target: "kafka" }, ["std/kafka-lag"]],
+        [{ risk_max: "read-only" }, ["std/disk-pressure"]],
+        [{ execution: "human-only" }, ["std/disk-pressure"]],
+        [{ profile: "P0" }, []],
+    ])("%o", (query, expected) => {
+        expect(runSearch(records, query).hits.map((h) => h.ref)).toEqual(expected);
+    });
+    it("orders a facet-only answer stably rather than cleverly", () => {
+        const once = runSearch(records, {}).hits.map((h) => h.ref);
+        expect(runSearch(records, {}).hits.map((h) => h.ref)).toEqual(once);
+        expect([...once].sort()).toEqual(once);
+    });
+});
+/** A ranking somebody cannot reproduce is one they have to trust (§19). */
+describe("symptom search is ordinary BM25", () => {
+    it("puts the record about the symptom first", () => {
+        const result = runSearch(records, { symptom: "consumer group offsets" });
+        expect(result.hits[0].ref).toBe("std/kafka-lag");
+    });
+    it("finds nothing for a symptom nothing is about", () => {
+        expect(runSearch(records, { symptom: "quantum tunnelling" }).hits).toEqual([]);
+    });
+    it("is deterministic, including its tie-breaks", () => {
+        const index = buildIndex([
+            { ref: "b", text: "kafka lag" },
+            { ref: "a", text: "kafka lag" },
+        ]);
+        expect(bm25(index, "kafka").map((h) => h.ref)).toEqual(["a", "b"]);
+    });
+    it("tokenizes the way a reader would expect", () => {
+        expect(terms("Kafka consumer-group, stuck!")).toEqual(["kafka", "consumer", "group", "stuck"]);
+    });
+});
+/** §17, G5: variants of one procedure are one answer, not three competing ones. */
+describe("results are topics where topics exist", () => {
+    const withTopic = [
+        { ...records[0], ref: "std/kafka-a", topic: "consumer-stuck" },
+        { ...records[0], ref: "std/kafka-b", topic: "consumer-stuck" },
+        records[2],
+    ];
+    it("collapses variants into one hit", () => {
+        const result = runSearch(withTopic, { symptom: "consumer group" });
+        expect(result.hits.filter((h) => h.topic === "consumer-stuck")).toHaveLength(1);
+    });
+    it("marks the hit as standing for a topic", () => {
+        const hit = runSearch(withTopic, { symptom: "consumer group" }).hits[0];
+        expect(hit.topic).toBe("consumer-stuck");
+    });
+    it("leaves a record with no topic as itself", () => {
+        const result = runSearch(withTopic, { symptom: "filesystem filling" });
+        expect(result.hits[0].topic).toBeUndefined();
+    });
+});
+describe("pagination is consistent with the rest of /v1", () => {
+    const many = Array.from({ length: 60 }, (_, i) => ({ ...records[2], ref: `std/r${String(i).padStart(2, "0")}` }));
+    it("pages at a size nobody has to think about", () => {
+        expect(runSearch(many, {}).hits).toHaveLength(DEFAULT_LIMIT);
+    });
+    it("names where to continue rather than an offset to trust", () => {
+        const first = runSearch(many, {});
+        expect(first.next_cursor).toBeDefined();
+        const second = runSearch(many, { cursor: first.next_cursor });
+        expect(second.hits[0].ref).not.toBe(first.hits[0].ref);
+    });
+    it("stops naming one at the end", () => {
+        expect(runSearch(many, { limit: 100 }).next_cursor).toBeUndefined();
+    });
+    it("reports the total behind the page", () => {
+        expect(runSearch(many, {}).total).toBe(60);
+    });
+});
+/**
+ * An ops search reads like an incident report: a hostname, a customer name, a table
+ * nobody else has. The query text never enters the log — not hashed, not truncated.
+ */
+describe("a zero-result query is logged without the query", () => {
+    const query = { symptom: "postgres on db-3.acme.internal is out of wal space", target: "postgres" };
+    const line = zeroResultLine(query, "2026-09-21");
+    it("keeps no trace of the text", () => {
+        const serialized = JSON.stringify(line);
+        for (const fragment of ["db-3", "acme", "wal", "postgres on"]) {
+            expect(serialized).not.toContain(fragment);
+        }
+    });
+    it("records that a symptom was searched, and how long it was", () => {
+        expect(line.facets).toContain("symptom");
+        expect(line.symptom_words).toBe(8);
+    });
+    it("keeps the controlled values, which come from a published vocabulary", () => {
+        expect(line.target).toBe("postgres");
+    });
+    it("records the day, not the moment", () => {
+        expect(line.date).toBe("2026-09-21");
+        expect(JSON.stringify(line)).not.toMatch(/T\d{2}:\d{2}/);
+    });
+    it("carries nothing about who asked", () => {
+        expect(Object.keys(line).sort()).toEqual(["date", "facets", "symptom_words", "target", "trust_min"].sort());
+    });
+    it("publishes a gap only once several people have hit it", () => {
+        const once = Array.from({ length: REPORTABLE_FLOOR - 1 }, () => line);
+        expect(gaps(once)).toEqual([]);
+        expect(gaps([...once, line])[0].count).toBe(REPORTABLE_FLOOR);
+    });
+});
+/**
+ * §10.1: killing the Lambda degrades to the client-side index. It is the same function
+ * over the same artifact, which is what makes that true rather than hoped for.
+ */
+describe("the endpoint and the browser run the same search", () => {
+    it("gives the same answer with a prebuilt index as without one", () => {
+        const index = buildIndex(records.map((r) => ({ ref: r.ref, text: `${r.title} ${r.description} ${r.targets.join(" ")}` })));
+        const inBrowser = runSearch(records, { symptom: "node pods rescheduled" });
+        const inLambda = runSearch(records, { symptom: "node pods rescheduled" }, { index });
+        expect(inLambda.hits.map((h) => h.ref)).toEqual(inBrowser.hits.map((h) => h.ref));
+    });
+    it("works with no semantic half at all, finding fewer things rather than inventing an order", () => {
+        const withoutVectors = runSearch(records, { symptom: "offsets" });
+        expect(withoutVectors.hits.length).toBeGreaterThan(0);
+    });
+    it("merges the semantic half when there is one", () => {
+        const semantic = (_q, refs) => refs.includes("std/disk-pressure") ? [{ ref: "std/disk-pressure", score: 99 }] : [];
+        const result = runSearch(records, { symptom: "offsets" }, { semantic });
+        expect(result.hits[0].ref).toBe("std/disk-pressure");
+    });
+});
+/**
+ * The floor the matcher applies when nobody set one (§8, §17).
+ *
+ * `trust_min` "defaults to T2 … below it is an explicit act, never an omission" — true of
+ * `runSearch` and, until 2026-09-05, false of `matchStack`, which applied no floor at all
+ * unless a caller asked for one. Nothing here asserted it in the direction that mattered,
+ * so the two halves of one rule were free to disagree, and did.
+ *
+ * Found by building a record that lands at T1 and running the matcher over the real index:
+ * a reader saying "linux, cli:df" was shown two procedures, one of them below the level
+ * `/v1/index.json` excludes, `/catalog` does not ship and no hub counts.
+ */
+describe("what a stack is shown when nobody set a trust floor", () => {
+    const matchable = (ref, trust) => ({
+        ref,
+        title: ref,
+        description: "",
+        targets: ["linux"],
+        capabilities: ["cli:df"],
+        risk: "read-only",
+        trust,
+        profile: "P1",
+        execution: "agent-autonomous",
+    });
+    const records = [matchable("std/audited", "T2"), matchable("std/not-audited", "T1")];
+    const stack = { targets: { linux: undefined }, capabilities: ["cli:df"] };
+    it("shows the audited one and not the other", () => {
+        expect(matchStack(records, stack).map((m) => m.record.ref)).toEqual(["std/audited"]);
+    });
+    it("says why the other is missing rather than dropping it silently", () => {
+        const why = excluded(records, stack).find((e) => e.ref === "std/not-audited")?.why ?? "";
+        expect(why).toContain("T1");
+        expect(why, "a reader cannot tell it exists, or how to see it").toMatch(/default|floor/i);
+    });
+    it("shows it when the reader lowers the floor, which is the explicit act", () => {
+        const opened = matchStack(records, { ...stack, trustMin: "T0" });
+        expect(opened.map((m) => m.record.ref)).toEqual(["std/audited", "std/not-audited"]);
+    });
+    it("is the same default the search contract applies", () => {
+        expect(runSearch(records, {}).applied.trust_min).toBe(DEFAULT_TRUST_MIN);
+        expect(matchStack(records, stack).every((m) => m.record.trust === DEFAULT_TRUST_MIN)).toBe(true);
+    });
+});

package/dist/stack.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Stack matching (W-20, §17, §13.3).
+ *
+ * §17's third entry point taken to its conclusion: a reader says what they have — targets
+ * and versions, the capabilities their client offers, how much risk they will accept, what
+ * supervision they enforce — and the catalog answers what applies to *them*.
+ *
+ * The privacy shape is the constraint that decides the design. **A declared stack is an
+ * infrastructure fingerprint**: postgres 14.3 and kubernetes 1.29 and a private MCP server
+ * names an organization more precisely than most of what §14 refuses to collect in a run
+ * report. So the declaration never travels. This module is a pure function over the
+ * published index, run in the reader's browser, and there is nothing here that could send
+ * one anywhere — no client, no logger, no callback.
+ *
+ * The matching itself is deliberately unclever. A range that cannot be parsed does not
+ * match rather than matching hopefully: telling somebody a procedure applies to their
+ * cluster when nobody checked is worse than telling them nothing.
+ */
+import { type IndexedRecord, type Risk, type Trust } from "./search.js";
+export type RuntimeProfile = "R0" | "R1" | "R2";
+export interface Stack {
+    /** `{ postgres: "14.3", kubernetes: "1.29" }` — versions optional per target. */
+    readonly targets: Readonly<Record<string, string | undefined>>;
+    /** What this client can actually invoke. A record needing more is not applicable. */
+    readonly capabilities: readonly string[];
+    /** The most dangerous thing this reader will be shown. */
+    readonly riskCeiling?: Risk;
+    /** What the client enforces (§13.3). A record demanding more is refused, not ranked low. */
+    readonly runtimeProfile?: RuntimeProfile;
+    readonly execution?: string;
+    /**
+     * The trust floor. **Omitting it means T2**, the same default `runSearch` applies.
+     *
+     * It was optional in the sense of absent: unset meant no floor at all, so a stack page
+     * offered a T1 record beside a T2 one and the contract's own sentence about it — *below
+     * it is an explicit act, never an omission* — was true of the endpoint and false of the
+     * matcher. Measured with a record built for it: a reader saying "linux, cli:df" was
+     * shown two procedures and one of them was T1, a record `/v1/index.json` excludes,
+     * `/catalog` does not even ship, and no hub counts.
+     *
+     * Pass `"T0"` to mean no floor. That is the explicit act.
+     */
+    readonly trustMin?: Trust;
+}
+/** What the index must carry for a record to be matchable against a stack. */
+export interface Matchable extends IndexedRecord {
+    readonly applies_to?: Readonly<Record<string, string>>;
+    readonly min_runtime_profile?: RuntimeProfile;
+}
+export type Applicability = {
+    readonly applies: true;
+    readonly matchedTargets: readonly string[];
+} | {
+    readonly applies: false;
+    readonly why: string;
+};
+/**
+ * Does this version satisfy this range?
+ *
+ * A deliberately small subset of what a version range can be: comparators over dotted
+ * numbers, joined by spaces meaning "and". Anything else is **unparseable, and unparseable
+ * does not match** — a range this cannot read is a question nobody answered, and answering
+ * it optimistically puts a procedure in front of somebody whose cluster it was never
+ * checked against.
+ */
+export declare function satisfies(version: string, range: string): boolean | undefined;
+/**
+ * Whether a record applies to a stack, and when it does not, why.
+ *
+ * The refusals are named because "no results" is the least useful thing a catalog can say
+ * to somebody who has just described their environment: a reader who is told *their client
+ * only enforces R0* knows what to change, and a reader shown an empty list concludes the
+ * catalog is empty.
+ */
+export declare function applicability(record: Matchable, stack: Stack): Applicability;
+export interface Match {
+    readonly record: Matchable;
+    readonly matchedTargets: readonly string[];
+}
+/**
+ * What applies, ranked by applicability and then by trust.
+ *
+ * Applicability first because relevance is what was asked for; trust second because
+ * between two procedures that both fit, the one somebody has verified is the better
+ * answer. Ties break on the ref, so two builds of the same catalog agree.
+ */
+export declare function matchStack(records: readonly Matchable[], stack: Stack): Match[];
+/** Everything that did not apply, with the reason: an empty list explains nothing. */
+export declare function excluded(records: readonly Matchable[], stack: Stack): {
+    ref: string;
+    why: string;
+}[];