@runbooks/search 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Dorokhovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# `@runbooks/search`
+
+BM25, the query semantics, and `/v1/search` as a function.
+
+**Tasks:** [M-03](../../tasks/v1/M-03-search-api.md) · **Normative:** RUNBOOK.md §12, §17, §10.1
+
+Search runs client-side over the prebuilt index until size forces an endpoint, and
+`handleSearch` **is** that endpoint: a URL and the published artifact in, a response out,
+with no framework and no state. That is what makes §10.1's degradation claim literal —
+there is nothing in the endpoint the file does not already contain.
+
+Two rules the API cannot bend. `available` means **every** capability, not any: a client
+reading it the other way is handed procedures it can start and cannot finish. And
+`trust_min` defaults to T2, so reaching below it is something a caller did on purpose.
+
+The vector half of §17's hybrid is an injected function with no default
+([why](../../docs/decisions/M03-vector-half.md)): BM25 finds fewer things, and finding
+fewer things is recoverable in a way that inventing a ranking is not.

package/dist/bm25.d.ts

@@ -0,0 +1,67 @@
+/**
+ * BM25 over the prebuilt index (M-03, §10.1).
+ *
+ * Pure, and running in the reader's browser over an artifact the build produced. §10.1's
+ * rule is that search is client-side until size forces a Lambda, and that the Lambda is
+ * a pure transform over the same artifacts — never a source of truth. Keeping the ranking
+ * here rather than behind an endpoint is what makes that literally true: the same code
+ * ranks in both places, so switching costs nothing and changes nothing.
+ */
+export interface Document {
+    readonly ref: string;
+    readonly text: string;
+}
+export interface Bm25Index {
+    readonly documents: readonly {
+        readonly ref: string;
+        readonly length: number;
+        readonly terms: Readonly<Record<string, number>>;
+    }[];
+    readonly documentFrequency: Readonly<Record<string, number>>;
+    readonly averageLength: number;
+    /**
+     * The table this index was built through.
+     *
+     * Carried rather than passed again at query time: an index folded one way and a query
+     * folded another is the disagreement this whole change is about, one layer down.
+     */
+    readonly synonyms: Synonyms;
+}
+/**
+ * A synonym mapped to the word this catalog uses for it.
+ *
+ * Data rather than a dependency: `packages/search` has none on purpose — it is the
+ * library the browser runs — and the vocabulary lives in `@runbooks/lint`, which pulls in
+ * the schema and the graph. So the map travels: the build resolves it once from S-09's
+ * targets vocabulary and publishes it in `/v1/search-index.json`, and both the index and
+ * the query are folded through the same table.
+ */
+export type Synonyms = Readonly<Record<string, string>>;
+/**
+ * The words a document or a query is made of.
+ *
+ * This used to say it was "the same tokenizer the clustering uses in spirit", and *in
+ * spirit* was the tell: clustering folds `kubernetes` onto `k8s` through S-09's
+ * vocabulary and this did not, so a reader who typed the word Kubernetes calls itself
+ * found nothing while the clustering that groups records into topics treated the two as
+ * one word. `postgresql` and `postgres` were the same story.
+ *
+ * What is shared is now shared literally — the same table, applied at both ends. What
+ * still differs is stated rather than implied: clustering drops stop words and keeps
+ * single characters, because it is comparing whole documents for sameness; this keeps
+ * stop words, because BM25 already discounts them by their document frequency, and drops
+ * single characters, because a one-letter term matches everything and ranks nothing.
+ */
+export declare function terms(text: string, synonyms?: Synonyms): string[];
+export declare function buildIndex(documents: readonly Document[], synonyms?: Synonyms): Bm25Index;
+/**
+ * Score a query. Standard BM25, no tuning of our own.
+ *
+ * A ranking somebody cannot reproduce is a ranking they have to trust, which is the
+ * thing §19 refuses about scores generally. The parameters are the textbook ones and the
+ * formula is the textbook formula, so a result order can be argued with.
+ */
+export declare function search(index: Bm25Index, query: string, synonyms?: Synonyms): {
+    ref: string;
+    score: number;
+}[];

package/dist/bm25.js

@@ -0,0 +1,73 @@
+/**
+ * The words a document or a query is made of.
+ *
+ * This used to say it was "the same tokenizer the clustering uses in spirit", and *in
+ * spirit* was the tell: clustering folds `kubernetes` onto `k8s` through S-09's
+ * vocabulary and this did not, so a reader who typed the word Kubernetes calls itself
+ * found nothing while the clustering that groups records into topics treated the two as
+ * one word. `postgresql` and `postgres` were the same story.
+ *
+ * What is shared is now shared literally — the same table, applied at both ends. What
+ * still differs is stated rather than implied: clustering drops stop words and keeps
+ * single characters, because it is comparing whole documents for sameness; this keeps
+ * stop words, because BM25 already discounts them by their document frequency, and drops
+ * single characters, because a one-letter term matches everything and ranks nothing.
+ */
+export function terms(text, synonyms = {}) {
+    return text
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "")
+        .split(/[^a-z0-9]+/u)
+        .filter((word) => word.length > 1)
+        .map((word) => synonyms[word] ?? word);
+}
+export function buildIndex(documents, synonyms = {}) {
+    const df = {};
+    const built = documents.map((document) => {
+        const counted = {};
+        const words = terms(document.text, synonyms);
+        for (const word of words)
+            counted[word] = (counted[word] ?? 0) + 1;
+        for (const word of Object.keys(counted))
+            df[word] = (df[word] ?? 0) + 1;
+        return { ref: document.ref, length: words.length, terms: counted };
+    });
+    return {
+        documents: built,
+        documentFrequency: df,
+        averageLength: built.length === 0 ? 0 : built.reduce((sum, d) => sum + d.length, 0) / built.length,
+        synonyms,
+    };
+}
+const K1 = 1.2;
+const B = 0.75;
+/**
+ * Score a query. Standard BM25, no tuning of our own.
+ *
+ * A ranking somebody cannot reproduce is a ranking they have to trust, which is the
+ * thing §19 refuses about scores generally. The parameters are the textbook ones and the
+ * formula is the textbook formula, so a result order can be argued with.
+ */
+export function search(index, query, synonyms = index.synonyms) {
+    const queryTerms = terms(query, synonyms);
+    if (queryTerms.length === 0 || index.documents.length === 0)
+        return [];
+    const total = index.documents.length;
+    return index.documents
+        .map((document) => {
+        let score = 0;
+        for (const term of queryTerms) {
+            const frequency = document.terms[term];
+            if (!frequency)
+                continue;
+            const df = index.documentFrequency[term] ?? 0;
+            const idf = Math.log(1 + (total - df + 0.5) / (df + 0.5));
+            const norm = 1 - B + (B * document.length) / (index.averageLength || 1);
+            score += idf * ((frequency * (K1 + 1)) / (frequency + K1 * norm));
+        }
+        return { ref: document.ref, score };
+    })
+        .filter((hit) => hit.score > 0)
+        .sort((a, b) => (b.score === a.score ? (a.ref < b.ref ? -1 : 1) : b.score - a.score));
+}

package/dist/cursor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Search pagination (M-03, §12).
+ *
+ * `search.ts` said its cursor "names where to continue, not an offset to trust", two
+ * lines above a `parseInt` of exactly that offset. The claim was the right one and the
+ * code was not, and an offset is wrong for a reason that shows up only in use: the set is
+ * rebuilt for every request, so a page-2 offset taken against yesterday's catalog skips
+ * or repeats whatever moved across the boundary — silently, and in the direction of
+ * showing a caller fewer records than exist.
+ *
+ * So a cursor names the last hit the caller saw and the query it belonged to. Continuing
+ * means resuming after that ref, and a cursor from a different query is refused rather
+ * than reinterpreted: it names a position in a set that was never returned.
+ */
+import type { SearchQuery } from "./search.js";
+export interface Cursor {
+    /** The ref the previous page ended on. The next page starts after it. */
+    readonly after: string;
+    /** Which query this position belongs to. */
+    readonly query: string;
+}
+/**
+ * What makes two queries the same question.
+ *
+ * Everything that changes the result set, and nothing that changes only its size: a
+ * caller paging through with a different `limit` is still asking the same thing.
+ */
+export declare function fingerprint(query: SearchQuery): string;
+export declare function encodeCursor(after: string, query: SearchQuery): string;
+export type CursorRead = {
+    readonly ok: true;
+    readonly cursor: Cursor;
+} | {
+    readonly ok: false;
+    readonly why: string;
+};
+/**
+ * Read a cursor, or say why not.
+ *
+ * Refusing beats guessing in both directions here: an unreadable cursor silently treated
+ * as "start from the beginning" hands a caller page 1 while they believe they are on
+ * page 3, and a cursor from another query silently honoured hands them a slice of a set
+ * they never asked for.
+ */
+export declare function readCursor(raw: string, query: SearchQuery): CursorRead;

package/dist/cursor.js

@@ -0,0 +1,49 @@
+/**
+ * What makes two queries the same question.
+ *
+ * Everything that changes the result set, and nothing that changes only its size: a
+ * caller paging through with a different `limit` is still asking the same thing.
+ */
+export function fingerprint(query) {
+    return JSON.stringify([
+        query.symptom ?? "",
+        query.target ?? "",
+        query.risk_max ?? "",
+        query.execution ?? "",
+        query.profile ?? "",
+        query.trust_min ?? "",
+        [...(query.available ?? [])].sort(),
+    ]);
+}
+const encode = (value) => Buffer.from(value, "utf8").toString("base64url");
+const decode = (value) => Buffer.from(value, "base64url").toString("utf8");
+export function encodeCursor(after, query) {
+    return encode(JSON.stringify({ after, query: fingerprint(query) }));
+}
+/**
+ * Read a cursor, or say why not.
+ *
+ * Refusing beats guessing in both directions here: an unreadable cursor silently treated
+ * as "start from the beginning" hands a caller page 1 while they believe they are on
+ * page 3, and a cursor from another query silently honoured hands them a slice of a set
+ * they never asked for.
+ */
+export function readCursor(raw, query) {
+    let parsed;
+    try {
+        parsed = JSON.parse(decode(raw));
+    }
+    catch {
+        return { ok: false, why: "This cursor is not one of ours. Cursors come from next_cursor in a previous response; they are not constructed." };
+    }
+    if (typeof parsed.after !== "string" || typeof parsed.query !== "string") {
+        return { ok: false, why: "This cursor is missing the position or the query it belongs to." };
+    }
+    if (parsed.query !== fingerprint(query)) {
+        return {
+            ok: false,
+            why: "This cursor belongs to a different query. A position in one result set does not name a position in another, and continuing anyway would return a page of something the caller never asked for.",
+        };
+    }
+    return { ok: true, cursor: { after: parsed.after, query: parsed.query } };
+}

package/dist/endpoint.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `GET /v1/search` (M-03, §12, §17, §10.1).
+ *
+ * A function of a URL and an artifact, and nothing else. There is no request object here,
+ * no framework and no I/O: whatever deploys this — a Lambda behind CloudFront, a route
+ * handler, a script on somebody's laptop — hands it the query string and the index it
+ * already has. That is what makes §10.1's claim literally true rather than aspirational:
+ * killing the endpoint degrades `/catalog` to the same search over the same file, because
+ * there is nothing in the endpoint that the file does not already contain.
+ *
+ * Three things the HTTP surface owes a caller that the library does not:
+ *
+ *  - **Refusing a query it cannot answer**, by name. A misspelled `risk_max` silently
+ *    ignored returns destructive records to somebody who asked for read-only ones.
+ *  - **Saying what it applied.** Defaults that are invisible are defaults nobody chose.
+ *  - **An ETag that changes when the answer would.** The index is content-addressed and
+ *    the query is part of the answer, so both are in it.
+ */
+import { type IndexedRecord, type SearchQuery, type SearchOptions } from "./search.js";
+import { type ZeroResultLine } from "./log.js";
+export interface EndpointRequest {
+    /** The full URL, or anything `URL` accepts with a base. */
+    readonly url: string;
+    /** Header names lowercased, as every runtime hands them over eventually. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface EndpointResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Absent on 304, which is the point of a 304. */
+    readonly body?: string;
+}
+export interface EndpointOptions extends SearchOptions {
+    /** The artifact's own hash, so the ETag changes exactly when the catalog does. */
+    readonly indexHash: string;
+    readonly today: string;
+    /**
+     * Where a query that found nothing is recorded (§17). Injected: an endpoint that
+     * decided on its own where to write would be a supervisor of somebody's disk, and a
+     * deployment that wants no log passes nothing.
+     */
+    readonly log?: (line: ZeroResultLine) => void;
+}
+export declare function parseQuery(url: string): {
+    ok: true;
+    query: SearchQuery;
+} | {
+    ok: false;
+    why: string;
+};
+/** The ETag: this catalog, this query. Both, because either changes the answer. */
+export declare function etagFor(indexHash: string, query: SearchQuery): string;
+export declare function handleSearch(request: EndpointRequest, index: readonly IndexedRecord[], options: EndpointOptions): EndpointResponse;

package/dist/endpoint.js

@@ -0,0 +1,103 @@
+/**
+ * `GET /v1/search` (M-03, §12, §17, §10.1).
+ *
+ * A function of a URL and an artifact, and nothing else. There is no request object here,
+ * no framework and no I/O: whatever deploys this — a Lambda behind CloudFront, a route
+ * handler, a script on somebody's laptop — hands it the query string and the index it
+ * already has. That is what makes §10.1's claim literally true rather than aspirational:
+ * killing the endpoint degrades `/catalog` to the same search over the same file, because
+ * there is nothing in the endpoint that the file does not already contain.
+ *
+ * Three things the HTTP surface owes a caller that the library does not:
+ *
+ *  - **Refusing a query it cannot answer**, by name. A misspelled `risk_max` silently
+ *    ignored returns destructive records to somebody who asked for read-only ones.
+ *  - **Saying what it applied.** Defaults that are invisible are defaults nobody chose.
+ *  - **An ETag that changes when the answer would.** The index is content-addressed and
+ *    the query is part of the answer, so both are in it.
+ */
+import { runSearch, DEFAULT_LIMIT } from "./search.js";
+import { readCursor } from "./cursor.js";
+import { zeroResultLine } from "./log.js";
+const RISKS = ["read-only", "reversible-write", "destructive", "irreversible"];
+const TRUSTS = ["T0", "T1", "T2", "T3", "T4"];
+const MAX_LIMIT = 100;
+/** A refusal that names the parameter, because "bad request" is not actionable. */
+function refuse(status, why) {
+    return {
+        status,
+        headers: { "content-type": "application/json", "cache-control": "no-store" },
+        body: `${JSON.stringify({ error: why }, null, 2)}\n`,
+    };
+}
+export function parseQuery(url) {
+    const params = new URL(url, "https://runbooks.directory").searchParams;
+    const value = (name) => params.get(name) ?? undefined;
+    const risk = value("risk_max");
+    if (risk !== undefined && !RISKS.includes(risk)) {
+        return { ok: false, why: `risk_max must be one of ${RISKS.join(", ")}. An unrecognised value is refused rather than ignored: a filter that silently does not apply returns exactly what the caller asked not to see.` };
+    }
+    const trust = value("trust_min");
+    if (trust !== undefined && !TRUSTS.includes(trust)) {
+        return { ok: false, why: `trust_min must be one of ${TRUSTS.join(", ")}.` };
+    }
+    const rawLimit = value("limit");
+    let limit;
+    if (rawLimit !== undefined) {
+        limit = Number.parseInt(rawLimit, 10);
+        if (!Number.isFinite(limit) || limit < 1 || limit > MAX_LIMIT) {
+            return { ok: false, why: `limit must be between 1 and ${MAX_LIMIT}. The default is ${DEFAULT_LIMIT}.` };
+        }
+    }
+    // `available` repeats or comma-separates: both shapes arrive from real clients, and
+    // refusing one of them teaches nothing.
+    const available = params.getAll("available").flatMap((entry) => entry.split(",")).map((entry) => entry.trim()).filter(Boolean);
+    return {
+        ok: true,
+        query: {
+            ...(value("symptom") ? { symptom: value("symptom") } : {}),
+            ...(value("target") ? { target: value("target") } : {}),
+            ...(risk ? { risk_max: risk } : {}),
+            ...(value("execution") ? { execution: value("execution") } : {}),
+            ...(trust ? { trust_min: trust } : {}),
+            ...(value("profile") ? { profile: value("profile") } : {}),
+            ...(available.length > 0 ? { available } : {}),
+            ...(limit !== undefined ? { limit } : {}),
+            ...(value("cursor") ? { cursor: value("cursor") } : {}),
+        },
+    };
+}
+/** The ETag: this catalog, this query. Both, because either changes the answer. */
+export function etagFor(indexHash, query) {
+    const hash = indexHash.replace(/^sha256:/, "");
+    const shape = Buffer.from(JSON.stringify(query), "utf8").toString("base64url");
+    return `"${hash}.${shape}"`;
+}
+export function handleSearch(request, index, options) {
+    const parsed = parseQuery(request.url);
+    if (!parsed.ok)
+        return refuse(400, parsed.why);
+    if (parsed.query.cursor) {
+        const read = readCursor(parsed.query.cursor, parsed.query);
+        if (!read.ok)
+            return refuse(400, read.why);
+    }
+    const etag = etagFor(options.indexHash, parsed.query);
+    const headers = {
+        "content-type": "application/json",
+        etag,
+        // A published catalog changes when it is rebuilt and not between: an hour is a
+        // compromise between a stale answer and a request per keystroke.
+        "cache-control": "public, max-age=3600",
+    };
+    if (request.headers?.["if-none-match"] === etag) {
+        return { status: 304, headers };
+    }
+    const { indexHash: _hash, today, log, ...searchOptions } = options;
+    const result = runSearch(index, parsed.query, searchOptions);
+    // §17: an empty result is a request for content, and the fact that it happened is the
+    // only part worth keeping. `zeroResultLine` cannot carry the query text at all.
+    if (result.hits.length === 0 && log)
+        log(zeroResultLine(parsed.query, today));
+    return { status: 200, headers, body: `${JSON.stringify(result, null, 2)}\n` };
+}

package/dist/endpoint.test.d.ts

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

package/dist/endpoint.test.js

@@ -0,0 +1,182 @@
+import { describe, it, expect } from "vitest";
+import { handleSearch, parseQuery, etagFor } from "./endpoint.js";
+import { readCursor, encodeCursor } from "./cursor.js";
+import { runSearch } from "./search.js";
+const HASH = "sha256:" + "a".repeat(64);
+const record = (over) => ({
+    title: over.ref,
+    description: "",
+    targets: [],
+    capabilities: [],
+    trust: "T2",
+    risk: "read-only",
+    profile: "P1",
+    ...over,
+});
+const INDEX = [
+    record({ ref: "std/a", title: "disk pressure", capabilities: ["cli:df"], targets: ["linux"] }),
+    record({ ref: "std/b", title: "kafka lag", capabilities: ["cli:kafka", "cli:kubectl"], risk: "destructive" }),
+    record({ ref: "std/c", title: "untrusted thing", trust: "T1" }),
+    record({ ref: "std/d", title: "draft thing", trust: "T0" }),
+];
+const get = (query, headers, log) => handleSearch({ url: `/v1/search${query}`, ...(headers ? { headers } : {}) }, INDEX, {
+    indexHash: HASH,
+    today: "2026-09-03",
+    ...(log ? { log } : {}),
+});
+const hits = (response) => JSON.parse(response.body).hits.map((h) => h.ref);
+/** "The default response contains no record below T2." */
+describe("the floor is a default, not an option nobody set", () => {
+    it("returns nothing below T2 when nobody asked", () => {
+        expect(hits(get(""))).toEqual(["std/a", "std/b"]);
+    });
+    it("says which floor it applied", () => {
+        const body = JSON.parse(get("").body);
+        expect(body.applied.trust_min).toBe("T2");
+    });
+    it("reaches below only when asked in as many words", () => {
+        expect(hits(get("?trust_min=T0"))).toContain("std/c");
+    });
+    it("refuses a trust level it does not know rather than ignoring it", () => {
+        const response = get("?trust_min=T9");
+        expect(response.status).toBe(400);
+        expect(response.body).toMatch(/trust_min must be one of/);
+    });
+});
+/**
+ * "Capability search returns exactly the records whose declared capabilities are a subset
+ * of those offered — and the semantics are documented, because the alternative reading is
+ * a security footgun."
+ */
+describe("available means every capability, not any", () => {
+    it("returns a record only when all of its capabilities are offered", () => {
+        expect(hits(get("?available=cli:df"))).toEqual(["std/a"]);
+        expect(hits(get("?available=cli:kafka"))).toEqual([]);
+        expect(hits(get("?available=cli:kafka,cli:kubectl,cli:df")).sort()).toEqual(["std/a", "std/b"]);
+    });
+    it("accepts the repeated and the comma-separated form", () => {
+        expect(hits(get("?available=cli:kafka&available=cli:kubectl"))).toEqual(["std/b"]);
+    });
+    it("repeats the rule in the answer, so a caller who assumed otherwise finds out here", () => {
+        const body = JSON.parse(get("?available=cli:df").body);
+        expect(body.applied.capability_semantics).toBe("all-required-available");
+    });
+});
+/** A filter that silently does not apply returns what the caller asked not to see. */
+describe("an unreadable query is refused by name", () => {
+    it("refuses an unknown risk ceiling", () => {
+        const response = get("?risk_max=scary");
+        expect(response.status).toBe(400);
+        expect(response.body).toMatch(/risk_max must be one of/);
+        expect(response.body).toMatch(/asked not to see/);
+    });
+    it("refuses a limit outside what it will serve", () => {
+        expect(get("?limit=0").status).toBe(400);
+        expect(get("?limit=1000").status).toBe(400);
+        expect(get("?limit=2").status).toBe(200);
+    });
+    it("refuses a cursor from another query rather than answering a different question", () => {
+        const cursor = encodeCursor("std/a", { symptom: "disk" });
+        const response = get(`?symptom=kafka&cursor=${cursor}`);
+        expect(response.status).toBe(400);
+        expect(response.body).toMatch(/belongs to a different query/);
+    });
+    it("refuses a cursor nobody issued", () => {
+        expect(get("?cursor=not-a-cursor").status).toBe(400);
+    });
+});
+/** A cursor names a position in a set, and the set is rebuilt on every request. */
+describe("pagination survives the catalog changing underneath it", () => {
+    const many = Array.from({ length: 6 }, (_, i) => record({ ref: `std/r${i}` }));
+    it("continues after the last hit rather than at an offset", () => {
+        const first = runSearch(many, { limit: 2 });
+        expect(first.next_cursor).toBeDefined();
+        const read = readCursor(first.next_cursor, { limit: 2 });
+        expect(read.ok && read.cursor.after).toBe(first.hits[1].ref);
+    });
+    it("does not skip a record inserted before the page boundary", () => {
+        const first = runSearch(many, { limit: 2 });
+        const grown = [record({ ref: "std/r-new" }), ...many];
+        const second = runSearch(grown, { limit: 2, cursor: first.next_cursor });
+        // An offset cursor would have started at index 2 of the grown list and skipped r1.
+        expect(second.hits.map((h) => h.ref)).toEqual(["std/r2", "std/r3"]);
+    });
+    it("stops when the page is the last one", () => {
+        expect(runSearch(many, { limit: 100 }).next_cursor).toBeUndefined();
+    });
+    it("pages to the end without repeating or losing a record", () => {
+        const seen = [];
+        let cursor;
+        for (let guard = 0; guard < 10; guard++) {
+            const page = runSearch(many, { limit: 2, ...(cursor ? { cursor } : {}) });
+            seen.push(...page.hits.map((h) => h.ref));
+            cursor = page.next_cursor;
+            if (!cursor)
+                break;
+        }
+        expect(seen).toEqual(many.map((r) => r.ref));
+    });
+});
+/** M-01's convention: an ETag that changes exactly when the answer would. */
+describe("the answer is cacheable and says when it did not change", () => {
+    it("answers 304 to the same query with the same catalog", () => {
+        const first = get("?symptom=disk");
+        const again = get("?symptom=disk", { "if-none-match": first.headers["etag"] });
+        expect(again.status).toBe(304);
+        expect(again.body).toBeUndefined();
+    });
+    it("changes when the catalog does", () => {
+        const other = "sha256:" + "b".repeat(64);
+        expect(etagFor(HASH, { symptom: "disk" })).not.toBe(etagFor(other, { symptom: "disk" }));
+    });
+    it("changes when the query does", () => {
+        expect(etagFor(HASH, { symptom: "disk" })).not.toBe(etagFor(HASH, { symptom: "kafka" }));
+    });
+    it("does not cache a refusal", () => {
+        expect(get("?limit=0").headers["cache-control"]).toBe("no-store");
+    });
+});
+/** "Query logs cannot be tied to an identifiable client." */
+describe("what an empty result records", () => {
+    it("records that it happened, and the facets, and nothing else", () => {
+        const lines = [];
+        const response = get("?symptom=a+hostname+nobody+else+has&target=linux", undefined, (line) => lines.push(line));
+        expect(hits(response)).toEqual([]);
+        expect(lines.length).toBe(1);
+        expect(JSON.stringify(lines[0])).not.toMatch(/hostname/);
+        expect(lines[0].symptom_words).toBe(5);
+        expect([...lines[0].facets].sort()).toEqual(["symptom", "target"]);
+    });
+    it("records nothing for a query that found something", () => {
+        const lines = [];
+        get("?symptom=disk", undefined, (line) => lines.push(line));
+        expect(lines).toEqual([]);
+    });
+    it("logs nowhere when no log was given", () => {
+        expect(() => get("?symptom=nothing-matches-this")).not.toThrow();
+    });
+    it("keeps no time of day, since a timestamp series is a movement log", () => {
+        const lines = [];
+        get("?symptom=nothing-matches-this", undefined, (line) => lines.push(line));
+        expect(lines[0].date).toBe("2026-09-03");
+        expect(JSON.stringify(lines[0])).not.toMatch(/\d{2}:\d{2}/);
+    });
+});
+/**
+ * "Killing the search Lambda degrades to the client-side index rather than breaking
+ * /catalog." The endpoint is a function of the artifact: there is nothing in it that the
+ * file does not already contain, which is what makes that true rather than hoped.
+ */
+describe("the endpoint is the same function over the same file", () => {
+    it("returns what the library returns for the same query", () => {
+        const direct = runSearch(INDEX, { symptom: "disk" });
+        expect(JSON.parse(get("?symptom=disk").body)).toEqual(JSON.parse(JSON.stringify(direct)));
+    });
+    it("holds no state of its own between requests", () => {
+        expect(get("?symptom=disk").body).toBe(get("?symptom=disk").body);
+    });
+    it("parses a query without needing a host", () => {
+        const parsed = parseQuery("/v1/search?symptom=disk&target=linux");
+        expect(parsed.ok && parsed.query).toEqual({ symptom: "disk", target: "linux" });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Search over the prebuilt index (M-03, §12, §17, §10.1).
+ *
+ * Client-side until size forces a Lambda, and the Lambda is the same code over the same
+ * artifacts — never a source of truth. That is what makes killing it a degradation rather
+ * than an outage.
+ */
+export * from "./bm25.js";
+export * from "./search.js";
+export * from "./log.js";
+export * from "./cursor.js";
+export * from "./endpoint.js";
+export * from "./stack.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Search over the prebuilt index (M-03, §12, §17, §10.1).
+ *
+ * Client-side until size forces a Lambda, and the Lambda is the same code over the same
+ * artifacts — never a source of truth. That is what makes killing it a degradation rather
+ * than an outage.
+ */
+export * from "./bm25.js";
+export * from "./search.js";
+export * from "./log.js";
+export * from "./cursor.js";
+export * from "./endpoint.js";
+export * from "./stack.js";