cursedbelt-server 1.0.0

package/src/server/search/pgSearchProvider.pg.test.ts

@@ -0,0 +1,392 @@
+// search-writer-allow-file: schema-lifecycle suite — it DROPs and rebuilds the saas
+// search schema per run and TRUNCATEs between tests, because the schema and its RLS
+// policy ARE the subject here. No statement below writes an index row outside the
+// provider.
+/**
+ * The saas search tier against a REAL Postgres (04 §3).
+ *
+ * Everything this provider claims is a claim about Postgres, not about
+ * TypeScript: that a `GENERATED ALWAYS AS … STORED` tsvector stays in step
+ * through an `ON CONFLICT DO UPDATE`, that `websearch_to_tsquery` cannot be made
+ * to raise on user input, that `ts_rank` with the 4× title weighting orders a
+ * corpus the way the SQLite side does, that `FORCE ROW LEVEL SECURITY` binds the
+ * owning role, and that `bytea` round-trips an embedding bit-for-bit. A fake
+ * pool can prove the plumbing and nothing else — it would be answering those
+ * questions with our own assumptions, which is how the previous arc shipped a
+ * search tier that had never run.
+ *
+ *   bun run test:pg          (starts a disposable container, runs, tears down)
+ *   CC_PG_URL=postgres://…   (or point it at any throwaway database)
+ *
+ * SKIPPED, loudly, when `CC_PG_URL` is absent — the skip is a missing proof,
+ * never a passing one. It runs nightly (`.github/workflows/nightly.yml`).
+ */
+import { SQL } from 'bun';
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'bun:test';
+import type { SaasConnection, SaasPool } from 'cwip/storage';
+import { createPgSearchProvider } from './pgSearchProvider';
+import { ensureSaasSearchSchema } from './pgSearchSchema';
+
+const ADMIN_URL = process.env.CC_PG_URL;
+
+/**
+ * A dedicated NON-SUPERUSER owner, and the reason is the finding this suite
+ * produced.
+ *
+ * Connecting as the container's default `postgres` role, the RLS test passed
+ * with BOTH tenants' rows: a **superuser bypasses row-level security
+ * unconditionally**, and `FORCE ROW LEVEL SECURITY` does not change that — FORCE
+ * subjects the table's OWNER to its policy, not a superuser. So the whole
+ * isolation guarantee is invisible to a suite that connects as one, and it would
+ * be equally invisible in a deployment whose application connects as one. This
+ * suite therefore runs as the shape a deployment should have (a non-superuser
+ * role that owns its own schema), which makes the policy load-bearing here
+ * rather than decorative.
+ */
+const ROLE = 'cc_search_rls';
+const PASSWORD = 'cc_search_rls_pw';
+const DATABASE = 'cc_search_rls_db';
+
+const appUrl = (): string => {
+  const admin = new URL(ADMIN_URL as string);
+  admin.username = ROLE;
+  admin.password = PASSWORD;
+  admin.pathname = `/${DATABASE}`;
+  return admin.toString();
+};
+
+let sql: SQL;
+let pool: SaasPool;
+
+const TENANT = 't_saas';
+const OTHER = 't_other';
+const CORPUS = 'knowledge';
+const MODEL = 'vocab-v1';
+
+/** Deterministic token-count embedder — see the local provider's suite for why. */
+const VOCAB = ['canine', 'puppy', 'feline', 'kitten', 'ledger', 'invoice'] as const;
+const embed = async (text: string): Promise<Float32Array> => {
+  const lower = text.toLowerCase();
+  return Float32Array.from(VOCAB.map((word) => lower.split(word).length - 1));
+};
+
+const doc = (id: string, title: string, body: string, tenantId = TENANT) => ({
+  corpus: CORPUS,
+  id,
+  tenantId,
+  title,
+  body,
+});
+
+// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
+describe.skipIf(!ADMIN_URL)('createPgSearchProvider against a real Postgres (04 §3)', () => {
+  // 120s for the same reason the control-plane suite gives: this hook drops and
+  // rebuilds a whole role, database and schema, and on a shared CI runner a 5s
+  // default times out mid-migration and reports the failure as though the SQL
+  // were wrong.
+  beforeAll(async () => {
+    const admin = new SQL(ADMIN_URL as string);
+    await admin.unsafe(`DROP DATABASE IF EXISTS ${DATABASE}`);
+    await admin.unsafe(`DROP ROLE IF EXISTS ${ROLE}`);
+    await admin.unsafe(`CREATE ROLE ${ROLE} LOGIN PASSWORD '${PASSWORD}' NOSUPERUSER NOBYPASSRLS`);
+    await admin.unsafe(`CREATE DATABASE ${DATABASE} OWNER ${ROLE}`);
+    await admin.close();
+
+    // `max: 1` is load-bearing, not tuning. The provider issues
+    // BEGIN / set_config / … / COMMIT, and a driver free to move the next
+    // statement onto a different physical connection would scope one connection
+    // and query another — which is the exact bug the transaction-local setting
+    // exists to prevent, arriving from the test harness instead of the code.
+    sql = new SQL(appUrl(), { max: 1 });
+    const connection: SaasConnection = {
+      async query<R>(text: string, params: readonly unknown[] = []): Promise<R[]> {
+        return (await sql.unsafe(text, [...params])) as R[];
+      },
+      async execute(text: string, params: readonly unknown[] = []) {
+        const result = await sql.unsafe(text, [...params]);
+        return { rowCount: (result as { count?: number }).count ?? 0 };
+      },
+    };
+    pool = {
+      async withConnection(fn) {
+        return await fn(connection);
+      },
+    };
+
+    await sql.unsafe('DROP TABLE IF EXISTS search_chunks');
+    await sql.unsafe('DROP TABLE IF EXISTS search_docs');
+    await ensureSaasSearchSchema(pool);
+  }, 120_000);
+
+  afterAll(async () => {
+    await sql?.end();
+  });
+
+  beforeEach(async () => {
+    // TRUNCATE, not DELETE — and the difference is the whole point of running as
+    // a non-superuser. A `DELETE` issued outside a tenant scope is checked
+    // against the policy, matches nothing, and SILENTLY LEAVES EVERY ROW, so
+    // state leaks from test to test and the failures read as ranking bugs.
+    // TRUNCATE requires ownership rather than a policy match, so it is the one
+    // cleanup that is honest under FORCE RLS.
+    await sql.unsafe('TRUNCATE search_chunks, search_docs RESTART IDENTITY');
+  });
+
+  const keywordOnly = () => createPgSearchProvider({ pool });
+  const hybrid = () => createPgSearchProvider({ pool, embed, embedModel: MODEL });
+
+  describe('schema', () => {
+    it('creates itself idempotently — a second deployment run is not a hard failure', async () => {
+      // `CREATE POLICY` has no `IF NOT EXISTS`, so this is the assertion that the
+      // skip-if-present path works rather than throwing 42710.
+      await ensureSaasSearchSchema(pool);
+      const policies = (await sql.unsafe(
+        "SELECT policyname FROM pg_policies WHERE tablename = 'search_docs'",
+      )) as { policyname: string }[];
+      expect(policies.map((row) => row.policyname)).toEqual(['tenant_isolation']);
+    });
+
+    it('FORCES row level security, so the owning role is subject to it too', async () => {
+      const [row] = (await sql.unsafe(
+        "SELECT relrowsecurity, relforcerowsecurity FROM pg_class WHERE relname = 'search_docs'",
+      )) as { relrowsecurity: boolean; relforcerowsecurity: boolean }[];
+      // ENABLE alone is decoration for the role that owns the schema — which, in
+      // this platform, is the role that serves every request.
+      expect(row?.relrowsecurity).toBe(true);
+      expect(row?.relforcerowsecurity).toBe(true);
+    });
+
+    it('keeps the tsvector in step through an ON CONFLICT DO UPDATE', async () => {
+      const search = keywordOnly();
+      await search.index(doc('d1', 'First title', 'canine body'));
+      await search.index(doc('d1', 'Second title', 'feline body'));
+
+      // A trigger written for INSERT only would leave the old postings here. A
+      // generated column cannot, because no code path writes it — which is the
+      // reason the schema uses one.
+      await expect(search.query('feline', { tenantId: TENANT })).resolves.toHaveLength(1);
+      await expect(search.query('canine', { tenantId: TENANT })).resolves.toEqual([]);
+    });
+  });
+
+  describe('the keyword tier', () => {
+    it('finds a document and reports a higher-is-better score', async () => {
+      const search = keywordOnly();
+      await search.index(doc('d1', 'Dogs', 'canine puppy notes'));
+      const hits = await search.query('canine', { tenantId: TENANT });
+      expect(hits).toHaveLength(1);
+      expect(hits[0]?.id).toBe('d1');
+      // `ts_rank` is already higher-is-better. The available mistake is copying
+      // the SQLite provider's sign flip, which would invert every ranking.
+      expect(hits[0]?.score).toBeGreaterThan(0);
+      expect(hits[0]?.snippet.length).toBeGreaterThan(0);
+    });
+
+    it('weights a title hit above a body hit, exactly as the SQLite profile does', async () => {
+      const search = keywordOnly();
+      await search.index(doc('body', 'Notes', 'ledger ledger ledger canine'));
+      await search.index(doc('title', 'Canine', 'ledger ledger ledger ledger'));
+      const hits = await search.query('canine', { tenantId: TENANT });
+      // Two profiles that ranked one corpus differently would make "search ranks
+      // wrong in production" unreproducible on a laptop.
+      expect(hits.map((hit) => hit.id)).toEqual(['title', 'body']);
+    });
+
+    it('survives every punctuation a real person types into a search box', async () => {
+      const search = keywordOnly();
+      await search.index(doc('d1', 'Quotes', 'canine puppy'));
+      // The SQLite side needs a phrase-literal retry for these because FTS5
+      // raises. `websearch_to_tsquery` is total, so a 500 on a hyphen — a product
+      // defect, not user error — is not reachable here at all.
+      for (const query of ['"canine', 'canine -', 'AND OR NEAR', 'canine)("', '""""', '-canine']) {
+        await expect(search.query(query, { tenantId: TENANT })).resolves.toBeArray();
+      }
+    });
+
+    it('returns nothing for an empty box rather than the whole corpus', async () => {
+      const search = keywordOnly();
+      await search.index(doc('d1', 'Any', 'canine'));
+      await expect(search.query('   ', { tenantId: TENANT })).resolves.toEqual([]);
+    });
+  });
+
+  describe('tenancy', () => {
+    it('never returns another tenant’s document', async () => {
+      const search = keywordOnly();
+      await search.index(doc('mine', 'Mine', 'canine puppy'));
+      await search.index(doc('theirs', 'Theirs', 'canine puppy', OTHER));
+
+      await expect(search.count(CORPUS, TENANT)).resolves.toBe(1);
+      const hits = await search.query('canine', { tenantId: TENANT });
+      expect(hits.map((hit) => hit.id)).toEqual(['mine']);
+    });
+
+    it('is protected by the DATABASE, not only by the predicate', async () => {
+      const search = keywordOnly();
+      await search.index(doc('mine', 'Mine', 'canine'));
+      await search.index(doc('theirs', 'Theirs', 'canine', OTHER));
+
+      // The same statement the provider runs, minus its tenant predicate, inside
+      // the same tenant scope. If the policy were merely ENABLEd (not FORCEd) or
+      // the predicate were the only control, this would return both rows.
+      const rows = await pool.withConnection(async (connection) => {
+        await connection.execute('BEGIN');
+        await connection.execute('SELECT set_config($1, $2, true)', ['app.tenant_id', TENANT]);
+        const all = await connection.query<{ source_id: string }>('SELECT source_id FROM search_docs');
+        await connection.execute('COMMIT');
+        return all;
+      });
+      expect(rows.map((row) => row.source_id)).toEqual(['mine']);
+    });
+
+    it('refuses an operation with no tenant', async () => {
+      const search = keywordOnly();
+      await expect(search.query('canine', { tenantId: '' })).rejects.toThrow(/tenantId/);
+    });
+  });
+
+  describe('the vector tier', () => {
+    it('writes chunks only when an embedder is wired', async () => {
+      await keywordOnly().index(doc('kw', 'Keyword', 'canine puppy'));
+      await expect(keywordOnly().countChunks(CORPUS, TENANT)).resolves.toBe(0);
+
+      const search = hybrid();
+      await search.index(doc('vec', 'Vector', 'canine puppy'));
+      await expect(search.countChunks(CORPUS, TENANT)).resolves.toBe(1);
+    });
+
+    it('round-trips an embedding through bytea bit-for-bit', async () => {
+      const search = hybrid();
+      await search.index(doc('d1', 'Dogs', 'canine puppy'));
+      const [row] = (await sql.unsafe('SELECT embedding, dims, model FROM search_chunks')) as {
+        embedding: Uint8Array;
+        dims: number;
+        model: string;
+      }[];
+      const expected = await embed('Dogs\n\ncanine puppy');
+      // Decoded through the same little-endian codec the reader uses. A driver
+      // that handed back a hex string or a differently-offset view would fail
+      // here rather than silently ranking by noise.
+      const { decodeEmbedding } = await import('cwip/search');
+      expect([...decodeEmbedding(row?.embedding as Uint8Array)]).toEqual([...expected]);
+      expect(row?.dims).toBe(VOCAB.length);
+      expect(row?.model).toBe(MODEL);
+    });
+
+    it('ranks the semantically nearest document above a keyword-only match', async () => {
+      const search = hybrid();
+      // Same fixture shape as the SQLite suite, and for the same reason — read
+      // that suite's comment before simplifying this to two documents.
+      await search.index(
+        doc('decoy', 'Canine Puppy Ledger', 'ledger invoice ledger invoice ledger invoice ledger invoice canine puppy'),
+      );
+      await search.index(doc('near', 'Notes', 'canine puppy canine puppy canine puppy'));
+      await search.index(doc('canines', 'Canines', 'canine canine canine'));
+      await search.index(doc('pups', 'Pups', 'puppy puppy puppy'));
+
+      const keyword = await keywordOnly().query('canine puppy', { tenantId: TENANT });
+      const fused = await search.query('canine puppy', { tenantId: TENANT });
+
+      // The negative control first: BM25/ts_rank alone puts `decoy` on top.
+      expect(keyword[0]?.id).toBe('decoy');
+      expect(fused[0]?.id).toBe('near');
+      expect(fused.map((hit) => hit.id)).toContain('decoy');
+    });
+
+    it('surfaces a document the keyword tier cannot find, with a hydrated title', async () => {
+      const search = hybrid();
+      await search.index(doc('semantic', 'Puppy notes', 'canine puppy'));
+
+      await expect(keywordOnly().query('kitten feline', { tenantId: TENANT })).resolves.toEqual([]);
+      const fused = await search.query('canine kitten', { tenantId: TENANT });
+      expect(fused.map((hit) => hit.id)).toContain('semantic');
+      expect(fused.find((hit) => hit.id === 'semantic')?.title).toBe('Puppy notes');
+    });
+
+    it('never ranks another tenant’s chunks', async () => {
+      const search = hybrid();
+      await search.index(doc('mine', 'Mine', 'canine puppy'));
+      await search.index(doc('theirs', 'Theirs', 'canine puppy', OTHER));
+      const hits = await search.query('canine puppy', { tenantId: TENANT });
+      expect(hits.map((hit) => hit.id)).toEqual(['mine']);
+    });
+
+    it('replaces a document’s chunks on re-index rather than accumulating them', async () => {
+      const search = hybrid();
+      await search.index(doc('r1', 'First', 'canine puppy'));
+      await search.index(doc('r1', 'Second', 'feline kitten'));
+      await expect(search.countChunks(CORPUS, TENANT)).resolves.toBe(1);
+      await expect(search.count(CORPUS, TENANT)).resolves.toBe(1);
+    });
+
+    it('degrades to the keyword tier when the embedder is down', async () => {
+      const phases: string[] = [];
+      const flaky = createPgSearchProvider({
+        pool,
+        embed: async () => {
+          throw new Error('embedding provider is down');
+        },
+        onVectorError: (_error, phase) => phases.push(phase),
+      });
+      await flaky.index(doc('d1', 'Dogs', 'canine puppy'));
+      // The document still landed — a failing embedder must not look like a
+      // write failure to the CDC tap, which would retry into an outage.
+      await expect(flaky.count(CORPUS, TENANT)).resolves.toBe(1);
+      await expect(flaky.query('canine', { tenantId: TENANT })).resolves.toHaveLength(1);
+      expect(phases).toEqual(['index', 'query']);
+    });
+
+    it('reports a truncated candidate scan', async () => {
+      const truncations: unknown[] = [];
+      const search = createPgSearchProvider({
+        pool,
+        embed,
+        embedModel: MODEL,
+        vectorCandidateLimit: 1,
+        onVectorTruncated: (detail) => truncations.push(detail),
+      });
+      await search.index(doc('t1', 'One', 'canine puppy'));
+      await search.index(doc('t2', 'Two', 'canine kitten'));
+      await search.query('canine', { tenantId: TENANT });
+      expect(truncations).toHaveLength(1);
+    });
+  });
+
+  describe('rebuild operations', () => {
+    it('reads its epoch from the DATABASE clock, in the index’s own format', async () => {
+      const epoch = await keywordOnly().now();
+      // Same format the SQLite provider's `strftime` produces — the reindexer
+      // compares this string against `indexed_at`, and two formats would make
+      // that comparison quietly wrong rather than loudly broken.
+      expect(epoch).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    });
+
+    it('sweeps documents older than the epoch, and their chunks with them', async () => {
+      const search = hybrid();
+      await search.index(doc('old', 'Old', 'canine puppy'));
+      await Bun.sleep(5);
+      const epoch = await search.now();
+      await search.index(doc('new', 'New', 'canine puppy'));
+
+      // Counted as DOCUMENTS. Reading the delete's row count would report the
+      // cascaded chunks too, and the reindex job's log would lie about how much
+      // it removed.
+      await expect(search.sweepStale(CORPUS, TENANT, epoch)).resolves.toBe(1);
+      await expect(search.count(CORPUS, TENANT)).resolves.toBe(1);
+      await expect(search.countChunks(CORPUS, TENANT)).resolves.toBe(1);
+      await expect(search.query('canine', { tenantId: TENANT })).resolves.toHaveLength(1);
+    });
+
+    it('removes a document and its chunks together', async () => {
+      const search = hybrid();
+      await search.index(doc('gone', 'Gone', 'canine puppy'));
+      await search.remove(CORPUS, 'gone', TENANT);
+      await expect(search.count(CORPUS, TENANT)).resolves.toBe(0);
+      await expect(search.countChunks(CORPUS, TENANT)).resolves.toBe(0);
+    });
+
+    it('does not treat removing an unindexed document as an error', async () => {
+      await expect(keywordOnly().remove(CORPUS, 'never-indexed', TENANT)).resolves.toBeUndefined();
+    });
+  });
+});