@retinue/agentkit 0.1.0 → 0.3.0

package/dist/testing/conformance/knowledge.js

@@ -0,0 +1,592 @@
+/**
+ * `KnowledgeStore` and `VectorIndex` conformance (#135) — AC-6.
+ *
+ * Two harnesses over one fixture, because on pgvector both ports are one table and a suite that opened them
+ * separately would never exercise the case that matters: a search seeing what a write just wrote.
+ *
+ * Both harnesses are gated on the `vector-search` capability. An adapter that cannot hold vectors — Postgres
+ * without pgvector installed, which includes the PGlite the suite runs on by default — declares nothing and
+ * every case registers as a *named* skip rather than vanishing from the report. `gatedIt` exists for exactly
+ * this: an invisible skip is indistinguishable from coverage.
+ *
+ * The search cases assert the **contract**, not recall. pgvector's HNSW index is *approximate*, so
+ * "the nearest chunk comes first" is something the production adapter is permitted to miss on a large corpus —
+ * asserting it here would make the harness fail for a reason that is not a bug. What is asserted is what must
+ * hold exactly at any size: tenant isolation, permission filtering, the limit, score ordering among returned
+ * hits, and that no vector ever comes back. Recall is measured separately against a fixed query set.
+ */
+import { describe, expect } from "vitest";
+import { gatedIt } from "./capability.js";
+import { asId } from "../../core/ids.js";
+const T1 = asId("conf-knowledge-tenant-1");
+const T2 = asId("conf-knowledge-tenant-2");
+const AT = "2026-08-23T12:00:00.000Z";
+/** 1536, because that is what the pgvector schema declares and a vector of another length is rejected. */
+export const CONFORMANCE_DIMENSIONS = 1536;
+export const MODEL = {
+    modelId: "conf-embed",
+    version: "1",
+    dimensions: CONFORMANCE_DIMENSIONS,
+};
+/**
+ * A deterministic vector pointing mostly along one axis.
+ *
+ * Deterministic because a recall figure that moves between runs is a figure nobody can act on, and axis-aligned
+ * because it makes "closer" obvious: a query along axis 3 must rank the chunk built on axis 3 first, with no
+ * dependence on floating-point luck.
+ */
+export const axisVector = (axis, magnitude = 1) => {
+    const v = new Array(CONFORMANCE_DIMENSIONS).fill(0.0001);
+    v[axis % CONFORMANCE_DIMENSIONS] = magnitude;
+    return v;
+};
+const chunk = (overrides) => ({
+    id: overrides.id ?? `c${overrides.index}`,
+    sourceType: overrides.sourceType ?? "file",
+    sourceId: overrides.sourceId ?? "file-1",
+    chunkIndex: overrides.chunkIndex ?? overrides.index,
+    content: overrides.content ?? `chunk ${overrides.index}`,
+    tokenCount: overrides.tokenCount ?? 10,
+    authSubject: overrides.authSubject ?? "convo-1",
+    embeddingModel: overrides.embeddingModel ?? MODEL,
+    ...(overrides.locator === undefined ? {} : { locator: overrides.locator }),
+    createdAt: overrides.createdAt ?? AT,
+    embedding: overrides.embedding ?? axisVector(overrides.index),
+});
+export function knowledgeStoreConformance(make, declaration) {
+    describe("KnowledgeStore conformance", () => {
+        const it = (name, fn) => gatedIt(declaration, "vector-search", name, fn);
+        it("writes a source's chunks and reads them back in order", async () => {
+            const { store } = await make();
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [chunk({ index: 2 }), chunk({ index: 0 }), chunk({ index: 1 })],
+            });
+            const page = await store.listBySource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                limit: 10,
+            });
+            // Document order, not insertion order: reading around a hit depends on it being the document's order.
+            expect(page.items.map((c) => c.chunkIndex)).toEqual([0, 1, 2]);
+        });
+        it("never returns the embedding", async () => {
+            // Nothing above this layer needs it, and it is by far the largest field -- returning it would make every
+            // listing an order of magnitude more expensive for a value nobody reads.
+            const { store } = await make();
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "file-1", chunks: [chunk({ index: 0 })] });
+            const found = await store.get({ tenantId: T1, id: "c0" });
+            expect(found).not.toBeNull();
+            expect(Object.keys(found ?? {})).not.toContain("embedding");
+        });
+        it("records the model that produced each chunk", async () => {
+            // AC-1. Per chunk, not per deployment: a global setting cannot tell you which rows are stale, which
+            // makes incremental re-indexing impossible.
+            const { store } = await make();
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "file-1", chunks: [chunk({ index: 0 })] });
+            expect((await store.get({ tenantId: T1, id: "c0" }))?.embeddingModel).toEqual(MODEL);
+        });
+        it("replaces rather than appends", async () => {
+            // A changed document's old chunks must stop being searchable: a stale chunk is a citation pointing at
+            // text that is no longer there.
+            const { store } = await make();
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [chunk({ index: 0 }), chunk({ index: 1 }), chunk({ index: 2 })],
+            });
+            const result = await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [chunk({ index: 0, content: "rewritten" })],
+            });
+            expect(result).toEqual({ written: 1, removed: 3 });
+            const page = await store.listBySource({ tenantId: T1, sourceType: "file", sourceId: "file-1", limit: 10 });
+            expect(page.items.map((c) => c.content)).toEqual(["rewritten"]);
+        });
+        it("does not touch another source when replacing one", async () => {
+            const { store } = await make();
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "a", chunks: [chunk({ index: 0, id: "a0", sourceId: "a" })] });
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "b", chunks: [chunk({ index: 0, id: "b0", sourceId: "b" })] });
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "a", chunks: [] });
+            expect((await store.listBySource({ tenantId: T1, sourceType: "file", sourceId: "b", limit: 10 })).items).toHaveLength(1);
+        });
+        it("treats the same id under a different source type as a different source", async () => {
+            // A file and an artifact can share an id. Keying on the id alone would have one delete the other's chunks.
+            const { store } = await make();
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "x", chunks: [chunk({ index: 0, id: "f0", sourceId: "x" })] });
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "artifact",
+                sourceId: "x",
+                chunks: [chunk({ index: 0, id: "a0", sourceType: "artifact", sourceId: "x" })],
+            });
+            expect((await store.listBySource({ tenantId: T1, sourceType: "file", sourceId: "x", limit: 10 })).items).toHaveLength(1);
+            expect((await store.listBySource({ tenantId: T1, sourceType: "artifact", sourceId: "x", limit: 10 })).items).toHaveLength(1);
+        });
+        it("returns null for another tenant's chunk", async () => {
+            const { store } = await make();
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "file-1", chunks: [chunk({ index: 0 })] });
+            expect(await store.get({ tenantId: T2, id: "c0" })).toBeNull();
+            expect((await store.listBySource({ tenantId: T2, sourceType: "file", sourceId: "file-1", limit: 10 })).items).toEqual([]);
+        });
+        it("refuses a vector whose length contradicts its declared dimensions", async () => {
+            // A wrong-length vector would score against whatever prefix overlapped, which looks like bad relevance
+            // rather than a bug.
+            const { store } = await make();
+            await expect(store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [chunk({ index: 0, embedding: [0.1, 0.2, 0.3] })],
+            })).rejects.toThrow();
+        });
+        it("removes a source's chunks on delete", async () => {
+            // A deleted document's content must stop being searchable.
+            const { store } = await make();
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [chunk({ index: 0 }), chunk({ index: 1 })],
+            });
+            expect(await store.deleteSource({ tenantId: T1, sourceType: "file", sourceId: "file-1" })).toEqual({ removed: 2 });
+            expect((await store.listBySource({ tenantId: T1, sourceType: "file", sourceId: "file-1", limit: 10 })).items).toEqual([]);
+        });
+        it("does not delete another tenant's source", async () => {
+            const { store } = await make();
+            await store.replaceSource({ tenantId: T1, sourceType: "file", sourceId: "file-1", chunks: [chunk({ index: 0 })] });
+            expect(await store.deleteSource({ tenantId: T2, sourceType: "file", sourceId: "file-1" })).toEqual({ removed: 0 });
+            expect(await store.get({ tenantId: T1, id: "c0" })).not.toBeNull();
+        });
+        it("pages a source's chunks without repeating or skipping one", async () => {
+            const { store } = await make();
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [0, 1, 2, 3, 4].map((i) => chunk({ index: i })),
+            });
+            const seen = [];
+            let cursor;
+            do {
+                const page = await store.listBySource({
+                    tenantId: T1,
+                    sourceType: "file",
+                    sourceId: "file-1",
+                    limit: 2,
+                    ...(cursor === undefined ? {} : { cursor }),
+                });
+                seen.push(...page.items.map((c) => c.chunkIndex));
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            expect(seen).toEqual([0, 1, 2, 3, 4]);
+        });
+        it("lists exactly the sources a model change made stale", async () => {
+            // AC-5's basis: the work list is derived from what is stored, so an interrupted re-index resumes by
+            // asking again rather than by remembering where it was.
+            const { store } = await make();
+            const older = { ...MODEL, version: "0" };
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "stale-1",
+                chunks: [chunk({ index: 0, id: "s0", sourceId: "stale-1", embeddingModel: older })],
+            });
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "fresh-1",
+                chunks: [chunk({ index: 0, id: "f0", sourceId: "fresh-1" })],
+            });
+            const page = await store.listStaleSources({ tenantId: T1, current: MODEL, limit: 10 });
+            expect(page.items).toEqual([{ sourceType: "file", sourceId: "stale-1", chunkCount: 1 }]);
+        });
+        it("refuses a vector of a different size rather than storing two sizes at once", async () => {
+            // A provider that keeps its model id and changes its *output size* is a different case from one that
+            // changes its version, and it is not a re-index: a vector column has one width and an index cannot span
+            // widths, so a size change is a **migration**. Asserted as a refusal rather than as staleness, because
+            // the store genuinely cannot hold both — found by running this harness against real pgvector, which
+            // rejected the 768-dimension write the earlier version of this case tried to make.
+            const { store } = await make();
+            await expect(store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "resized",
+                chunks: [
+                    chunk({
+                        index: 0,
+                        id: "r0",
+                        sourceId: "resized",
+                        embeddingModel: { ...MODEL, dimensions: 768 },
+                        embedding: new Array(768).fill(0.1),
+                    }),
+                ],
+            })).rejects.toThrow();
+        });
+        it("lists no stale source for another tenant", async () => {
+            const { store } = await make();
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "stale-1",
+                chunks: [chunk({ index: 0, embeddingModel: { ...MODEL, version: "0" } })],
+            });
+            expect((await store.listStaleSources({ tenantId: T2, current: MODEL, limit: 10 })).items).toEqual([]);
+        });
+    });
+}
+export function vectorIndexConformance(make, declaration) {
+    describe("VectorIndex conformance", () => {
+        const it = (name, fn) => gatedIt(declaration, "vector-search", name, fn);
+        const seeded = async () => {
+            const fixture = await make();
+            await fixture.store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [
+                    chunk({ index: 0, id: "own-0", authSubject: "convo-1", embedding: axisVector(0) }),
+                    chunk({ index: 1, id: "own-1", authSubject: "convo-1", embedding: axisVector(1) }),
+                    chunk({ index: 2, id: "other-2", authSubject: "convo-2", embedding: axisVector(0) }),
+                ],
+            });
+            await fixture.store.replaceSource({
+                tenantId: T2,
+                sourceType: "file",
+                sourceId: "file-1",
+                chunks: [chunk({ index: 0, id: "foreign-0", authSubject: "convo-1", embedding: axisVector(0) })],
+            });
+            return fixture;
+        };
+        it("returns the chunk nearest the query", async () => {
+            const { index } = await seeded();
+            const hits = await index.search({
+                tenantId: T1,
+                embedding: axisVector(1),
+                authSubjects: ["convo-1"],
+                limit: 1,
+            });
+            expect(hits.map((h) => h.chunk.id)).toEqual(["own-1"]);
+            expect(hits[0]?.score).toBeGreaterThan(0.5);
+        });
+        it("excludes a chunk whose subject was not asked for", async () => {
+            // AC-3. `other-2` sits on the same axis as `own-0`, so it *would* be a top hit if the filter were
+            // applied after retrieval -- which is exactly the leak this asserts against.
+            const { index } = await seeded();
+            const hits = await index.search({
+                tenantId: T1,
+                embedding: axisVector(0),
+                authSubjects: ["convo-1"],
+                limit: 10,
+            });
+            expect(hits.map((h) => h.chunk.id)).not.toContain("other-2");
+        });
+        it("returns nothing for an empty subject list", async () => {
+            // "No subjects" must mean nothing, not everything. The opposite reading is the worst possible default.
+            const { index } = await seeded();
+            expect(await index.search({ tenantId: T1, embedding: axisVector(0), authSubjects: [], limit: 10 })).toEqual([]);
+        });
+        it("does not return another tenant's chunk however close it is", async () => {
+            const { index } = await seeded();
+            const hits = await index.search({
+                tenantId: T1,
+                embedding: axisVector(0),
+                authSubjects: ["convo-1"],
+                limit: 10,
+            });
+            expect(hits.map((h) => h.chunk.id)).not.toContain("foreign-0");
+        });
+        it("honours the limit", async () => {
+            const { index } = await seeded();
+            expect(await index.search({ tenantId: T1, embedding: axisVector(0), authSubjects: ["convo-1", "convo-2"], limit: 1 })).toHaveLength(1);
+        });
+        it("returns hits in descending score order", async () => {
+            const { index } = await seeded();
+            const hits = await index.search({
+                tenantId: T1,
+                embedding: axisVector(0),
+                authSubjects: ["convo-1", "convo-2"],
+                limit: 10,
+            });
+            const scores = hits.map((h) => h.score);
+            expect([...scores].sort((a, b) => b - a)).toEqual(scores);
+        });
+        it("drops hits below the minimum score", async () => {
+            // Prevents a query with no good answer returning noise, which a model then cites.
+            const { index } = await seeded();
+            const hits = await index.search({
+                tenantId: T1,
+                embedding: axisVector(1),
+                authSubjects: ["convo-1"],
+                limit: 10,
+                minScore: 0.9,
+            });
+            expect(hits.map((h) => h.chunk.id)).toEqual(["own-1"]);
+        });
+        it("filters by source type when asked", async () => {
+            const { index } = await seeded();
+            expect(await index.search({
+                tenantId: T1,
+                embedding: axisVector(0),
+                authSubjects: ["convo-1"],
+                limit: 10,
+                sourceTypes: ["artifact"],
+            })).toEqual([]);
+        });
+        it("never returns a vector with a hit", async () => {
+            const { index } = await seeded();
+            const hits = await index.search({
+                tenantId: T1,
+                embedding: axisVector(0),
+                authSubjects: ["convo-1"],
+                limit: 10,
+            });
+            for (const hit of hits)
+                expect(Object.keys(hit.chunk)).not.toContain("embedding");
+        });
+        it("finds a chunk written a moment ago", async () => {
+            // AC-4's mechanism at the store level: an index that needed a refresh step would fail here, and the
+            // freshness target would be unmeetable however fast the pipeline ran.
+            const { store, index } = await seeded();
+            await store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "brand-new",
+                chunks: [chunk({ index: 7, id: "new-7", sourceId: "brand-new", authSubject: "convo-1", embedding: axisVector(7) })],
+            });
+            const hits = await index.search({
+                tenantId: T1,
+                embedding: axisVector(7),
+                authSubjects: ["convo-1"],
+                limit: 1,
+            });
+            expect(hits.map((h) => h.chunk.id)).toEqual(["new-7"]);
+        });
+    });
+}
+export function keywordIndexConformance(make, declaration) {
+    describe("KeywordIndex conformance", () => {
+        const it = (name, fn) => gatedIt(declaration, "vector-search", name, fn);
+        /**
+         * A corpus with an exact identifier, a near-miss, and a distractor.
+         *
+         * The identifier is the whole reason this port exists: `ERR-4021` embeds as a string that looks like other
+         * strings, so no vector index reliably finds it. The near-miss (`ERR-4022`) is what a substring matcher or
+         * a stemmed configuration would return alongside it.
+         */
+        const seeded = async () => {
+            const fixture = await make();
+            await fixture.store.replaceSource({
+                tenantId: T1,
+                sourceType: "file",
+                sourceId: "runbook",
+                chunks: [
+                    chunk({
+                        index: 0,
+                        id: "exact",
+                        content: "Error ERR-4021 means the upstream billing service refused the request.",
+                        authSubject: "convo-1",
+                    }),
+                    chunk({
+                        index: 1,
+                        id: "near",
+                        content: "Error ERR-4022 means the upstream billing service timed out.",
+                        authSubject: "convo-1",
+                    }),
+                    chunk({
+                        index: 2,
+                        id: "noise",
+                        content: "The billing service runs in three regions and is monitored continuously.",
+                        authSubject: "convo-1",
+                    }),
+                    chunk({
+                        index: 3,
+                        id: "restricted",
+                        content: "Error ERR-4021 also appears in the confidential incident report.",
+                        authSubject: "convo-restricted",
+                    }),
+                ],
+            });
+            await fixture.store.replaceSource({
+                tenantId: T2,
+                sourceType: "file",
+                sourceId: "runbook",
+                chunks: [
+                    chunk({
+                        index: 0,
+                        id: "foreign",
+                        content: "Error ERR-4021 in another tenant's runbook entirely.",
+                        authSubject: "convo-1",
+                    }),
+                ],
+            });
+            return fixture;
+        };
+        const search = async (fixture, input) => (fixture.keyword === undefined ? [] : fixture.keyword.search(input));
+        it("finds an exact identifier and ranks it above its near neighbour", async () => {
+            // AC-1's exact-term half, and the case that justifies the whole port.
+            const fixture = await seeded();
+            const hits = await search(fixture, {
+                tenantId: T1,
+                query: "ERR-4021",
+                authSubjects: ["convo-1"],
+                limit: 5,
+            });
+            expect(hits[0]?.chunk.id).toBe("exact");
+            // The near-miss must not outrank it, and ideally must not match at all: `ERR-4022` is a different token.
+            expect(hits.map((h) => h.chunk.id)).not.toContain("near");
+        });
+        it("excludes a chunk whose subject was not asked for", async () => {
+            // AC-3, for the keyword signal. `restricted` contains the query term verbatim, so it would be a top hit
+            // if the filter were applied after the match.
+            const fixture = await seeded();
+            const hits = await search(fixture, {
+                tenantId: T1,
+                query: "ERR-4021",
+                authSubjects: ["convo-1"],
+                limit: 10,
+            });
+            expect(hits.map((h) => h.chunk.id)).not.toContain("restricted");
+        });
+        it("returns nothing for an empty subject list", async () => {
+            const fixture = await seeded();
+            expect(await search(fixture, { tenantId: T1, query: "ERR-4021", authSubjects: [], limit: 10 })).toEqual([]);
+        });
+        it("does not return another tenant's chunk", async () => {
+            const fixture = await seeded();
+            const hits = await search(fixture, {
+                tenantId: T1,
+                query: "ERR-4021",
+                authSubjects: ["convo-1"],
+                limit: 10,
+            });
+            expect(hits.map((h) => h.chunk.id)).not.toContain("foreign");
+        });
+        it("returns nothing when no chunk contains the terms", async () => {
+            // AC-4 at the port level: an empty result rather than the least-bad match. A keyword index that returned
+            // its closest row would hand a model something to cite about a subject the corpus never mentions.
+            const fixture = await seeded();
+            expect(await search(fixture, {
+                tenantId: T1,
+                query: "kubernetes helm chart",
+                authSubjects: ["convo-1"],
+                limit: 10,
+            })).toEqual([]);
+        });
+        it("returns nothing for an empty query rather than everything", async () => {
+            const fixture = await seeded();
+            expect(await search(fixture, { tenantId: T1, query: "   ", authSubjects: ["convo-1"], limit: 10 })).toEqual([]);
+        });
+        it("returns nothing for a query made only of stopwords", async () => {
+            // `simple` text search keeps stopwords — that is the price of not stemming, which is what preserves
+            // `ERR-4021`. So they come off the *query*, and a search for "the" is a search for nothing rather than a
+            // ranking of whichever document says "the" most often. Pinned in the shared harness because both
+            // adapters must agree: found by measuring hybrid retrieval, where a decoy sharing only "was" and "the"
+            // outranked the document that answered the question.
+            const fixture = await seeded();
+            for (const query of ["the", "was the", "what is the", "and or the"]) {
+                expect(await search(fixture, { tenantId: T1, query, authSubjects: ["convo-1"], limit: 10 })).toEqual([]);
+            }
+        });
+        it("does not let stopwords in a query decide the ranking", async () => {
+            // The same defect from the other side: with stopwords retained, "was the billing service down" ranks by
+            // how often a document says "the". The `noise` chunk mentions the billing service and nothing about an
+            // error; the `exact` chunk answers the question.
+            const fixture = await seeded();
+            const hits = await search(fixture, {
+                tenantId: T1,
+                query: "what was the ERR-4021 error about",
+                authSubjects: ["convo-1"],
+                limit: 5,
+            });
+            expect(hits[0]?.chunk.id).toBe("exact");
+        });
+        it("survives punctuation a user would actually type", async () => {
+            // A search box that errors on a stray quote is a search box that errors. Postgres's `to_tsquery` throws
+            // on all of these; `websearch_to_tsquery` does not, and that is why the adapter uses it.
+            const fixture = await seeded();
+            for (const query of ['billing "unclosed', "billing & ", "&&&", "billing |", "-", "billing OR"]) {
+                await expect(search(fixture, { tenantId: T1, query, authSubjects: ["convo-1"], limit: 5 })).resolves.toBeInstanceOf(Array);
+            }
+        });
+        it("scores between zero and one, best first", async () => {
+            // Normalised so a caller fusing this with a cosine similarity does not have to know that one scale is
+            // bounded and the other is not.
+            const fixture = await seeded();
+            const hits = await search(fixture, {
+                tenantId: T1,
+                query: "billing service",
+                authSubjects: ["convo-1"],
+                limit: 10,
+            });
+            expect(hits.length).toBeGreaterThan(0);
+            for (const hit of hits) {
+                expect(hit.score).toBeGreaterThanOrEqual(0);
+                expect(hit.score).toBeLessThanOrEqual(1);
+            }
+            const scores = hits.map((h) => h.score);
+            expect([...scores].sort((a, b) => b - a)).toEqual(scores);
+        });
+        it("honours the limit and the minimum score", async () => {
+            const fixture = await seeded();
+            expect(await search(fixture, {
+                tenantId: T1,
+                query: "billing service",
+                authSubjects: ["convo-1"],
+                limit: 1,
+            })).toHaveLength(1);
+            const strict = await search(fixture, {
+                tenantId: T1,
+                query: "billing service",
+                authSubjects: ["convo-1"],
+                limit: 10,
+                minScore: 0.99,
+            });
+            // Every returned hit clears the floor — the actual contract. An earlier version asserted *at most one*
+            // hit, which is not the contract: two chunks matching identically tie at the top score, and Postgres's
+            // `ts_rank_cd` does exactly that for the two `ERR-40xx` lines. A harness must not encode one adapter's
+            // tie-breaking as a guarantee.
+            for (const hit of strict)
+                expect(hit.score).toBeGreaterThanOrEqual(0.99);
+            // And the floor is genuinely applied rather than the loop above being vacuous. Asserted with a floor
+            // *above* any normalised score, because "the floor excludes something" depends on the corpus: all three
+            // chunks here contain both terms, and Postgres's cover density ranks them identically — which is correct,
+            // and which an earlier version of this assertion mistook for the floor not working.
+            expect(await search(fixture, {
+                tenantId: T1,
+                query: "billing service",
+                authSubjects: ["convo-1"],
+                limit: 10,
+                minScore: 1.01,
+            })).toEqual([]);
+        });
+        it("filters by source type when asked", async () => {
+            const fixture = await seeded();
+            expect(await search(fixture, {
+                tenantId: T1,
+                query: "billing",
+                authSubjects: ["convo-1"],
+                limit: 10,
+                sourceTypes: ["artifact"],
+            })).toEqual([]);
+        });
+        it("never returns a vector with a hit", async () => {
+            const fixture = await seeded();
+            const hits = await search(fixture, {
+                tenantId: T1,
+                query: "billing",
+                authSubjects: ["convo-1"],
+                limit: 10,
+            });
+            for (const hit of hits)
+                expect(Object.keys(hit.chunk)).not.toContain("embedding");
+        });
+    });
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/testing/conformance/parents.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Parent seeding for the conformance suite.
+ *
+ * An adapter is entitled to enforce referential integrity, and the Postgres schema does: a checkpoint
+ * belongs to a run, a message and a binding belong to a conversation. The in-memory reference adapter
+ * holds no such constraint, so the shared harnesses never created those parent rows — and every
+ * foreign key added to the schema broke them.
+ *
+ * #95 solved that for `CheckpointStore` with a bespoke fixture type. #96 needed the same thing for
+ * `ConversationBindingStore`, which is the point at which a one-off becomes a pattern. This is the
+ * shared mechanism: a harness accepts either a bare store (adapters with no constraints, unchanged)
+ * or a fixture pairing the store with the seeders its constraints require.
+ *
+ * The alternative was to drop the foreign keys so the harness would pass, which would have traded a
+ * real guarantee — orphan rows are impossible — for a green suite. That is the wrong direction.
+ */
+import type { ConversationId, RunId, TenantId } from "../../core/ids.js";
+/** Creates whatever parent row an adapter's constraints require. Omitted when there are none. */
+export type ParentSeeders = {
+    readonly seedRun?: (input: {
+        readonly tenantId: TenantId;
+        readonly runId: RunId;
+    }) => Promise<void>;
+    readonly seedConversation?: (input: {
+        readonly tenantId: TenantId;
+        readonly conversationId: ConversationId;
+    }) => Promise<void>;
+};
+/** A store plus the seeders its adapter needs. Harnesses accept this or a bare store. */
+export type Fixture<TStore> = ParentSeeders & {
+    readonly store: TStore;
+};
+/** What a harness is handed: either shape. */
+export type FixtureOrStore<TStore> = TStore | Fixture<TStore>;
+/**
+ * Normalise whichever shape the adapter supplied. Returns the store and the seeders, so a harness can
+ * seed unconditionally without caring which form it was given.
+ */
+export declare const openFixture: <TStore>(made: FixtureOrStore<TStore>) => Fixture<TStore>;
+/** Seed a run if the adapter needs one, then hand back the store. */
+export declare const withRun: <TStore>(made: FixtureOrStore<TStore>, runs: readonly {
+    tenantId: TenantId;
+    runId: RunId;
+}[]) => Promise<TStore>;
+/** Seed a conversation if the adapter needs one, then hand back the store. */
+export declare const withConversation: <TStore>(made: FixtureOrStore<TStore>, conversations: readonly {
+    tenantId: TenantId;
+    conversationId: ConversationId;
+}[]) => Promise<TStore>;
+//# sourceMappingURL=parents.d.ts.map