cursedbelt-server 1.0.0

package/dist/server/search/pgSearchProvider.pg.test.js

@@ -0,0 +1,338 @@
+// 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 { 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 = () => {
+    const admin = new URL(ADMIN_URL);
+    admin.username = ROLE;
+    admin.password = PASSWORD;
+    admin.pathname = `/${DATABASE}`;
+    return admin.toString();
+};
+let sql;
+let pool;
+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'];
+const embed = async (text) => {
+    const lower = text.toLowerCase();
+    return Float32Array.from(VOCAB.map((word) => lower.split(word).length - 1));
+};
+const doc = (id, title, body, 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);
+        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 = {
+            async query(text, params = []) {
+                return (await sql.unsafe(text, [...params]));
+            },
+            async execute(text, params = []) {
+                const result = await sql.unsafe(text, [...params]);
+                return { rowCount: result.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'"));
+            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'"));
+            // 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('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'));
+            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)]).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 = [];
+            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 = [];
+            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();
+        });
+    });
+});

package/dist/server/search/pgSearchSchema.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The saas search schema (04 §3) — `search_docs` + `search_chunks` on Postgres.
+ *
+ * `domains/search.ts` refuses to compile its SQLite chain for Postgres
+ * (`PG_DDL_UNSUPPORTED`) and says why: `search_fts` is an FTS5 external-content
+ * virtual table maintained by SQLite triggers, which is not a dialect
+ * difference — it is a different search engine. So the saas keyword tier is
+ * authored here, natively, and the two providers share only the vector tier
+ * (`cwip`'s `searchVectorTier`, one implementation for both).
+ *
+ * ## Why a GENERATED column rather than a trigger
+ *
+ * The SQLite side keeps its FTS shadow in step with three triggers, and its own
+ * header explains the hazard: "application-maintained shadow tables drift the
+ * moment one code path forgets". Postgres offers something stronger than a
+ * trigger for this — a `GENERATED ALWAYS AS (…) STORED` column cannot drift at
+ * all, because there is no code path that writes it. A trigger can be dropped, a
+ * migration can forget to recreate it, and `INSERT ... ON CONFLICT DO UPDATE`
+ * can bypass one that was written for the wrong event. A generated column has
+ * none of those failure modes: the tsvector is a function of the row, enforced
+ * by the storage engine.
+ *
+ * ## `simple` rather than `english`
+ *
+ * The text config is `simple` — no stemming, no stopwords. Two reasons, and the
+ * second is the load-bearing one:
+ *
+ *   1. This platform's corpora are multi-lingual by construction (a customer's
+ *      notes, filenames, contact names). Stemming with the WRONG language is
+ *      worse than not stemming: `english` drops "die"/"das" as if they were
+ *      stopwords and stems "arbeiten" to nothing useful.
+ *   2. `english` discards stopwords, so a search for a title that IS a stopword
+ *      phrase ("The Who", "It") returns nothing at all — and the SQLite side's
+ *      `unicode61` tokenizer has no stopword list either. Two tiers that
+ *      disagree about whether a document is findable is a bug report a customer
+ *      files as "search works on my laptop".
+ *
+ * ## RLS
+ *
+ * `search_docs` is tenant-rooted (`SEARCH_TENANCY`), so it carries the same
+ * `tenant_isolation` policy every domain table does, and `search_chunks`
+ * inherits through its `doc_id` FK. That is defense in depth, not the primary
+ * control: the provider binds `tenant_id` into every statement it issues, the
+ * way the SQLite provider does. The policy is what makes a future statement that
+ * forgets return zero rows instead of everyone's.
+ *
+ * DDL is NEVER issued on a process start — {@link ensureSaasSearchSchema} is a
+ * named call a deployment makes once, for the same reason
+ * `ensureSaasControlPlaneSchema` is: a shared database has one schema owner, and
+ * a library that migrated on boot would be N of them racing.
+ */
+import type { SaasPool } from 'cwip/storage';
+/**
+ * Weights fed to `ts_rank`, in Postgres' `{D, C, B, A}` order. Title 4× body,
+ * matching the SQLite provider's `bm25(search_fts, 4.0, 1.0)` exactly — two
+ * profiles that ranked the same corpus differently would make "it ranks wrong in
+ * production" unreproducible on a laptop.
+ */
+export declare const PG_RANK_WEIGHTS = "{0.1, 0.1, 0.25, 1.0}";
+export declare const PG_SEARCH_DOCS_DDL = "CREATE TABLE IF NOT EXISTS search_docs (\n  id         BIGSERIAL PRIMARY KEY,\n  corpus     TEXT NOT NULL,\n  source_id  TEXT NOT NULL,\n  tenant_id  TEXT NOT NULL,\n  user_id    TEXT,\n  title      TEXT NOT NULL DEFAULT '',\n  body       TEXT NOT NULL DEFAULT '',\n  rev        INTEGER NOT NULL DEFAULT 0,\n  indexed_at TEXT NOT NULL,\n  tsv        tsvector GENERATED ALWAYS AS (setweight(to_tsvector('simple', coalesce(title, '')), 'A') || setweight(to_tsvector('simple', coalesce(body, '')), 'B')) STORED\n)";
+export declare const PG_SEARCH_CHUNKS_DDL = "CREATE TABLE IF NOT EXISTS search_chunks (\n  id         BIGSERIAL PRIMARY KEY,\n  doc_id     BIGINT NOT NULL REFERENCES search_docs(id) ON DELETE CASCADE,\n  seq        INTEGER NOT NULL,\n  text       TEXT NOT NULL,\n  embedding  BYTEA,\n  dims       INTEGER,\n  model      TEXT,\n  indexed_at TEXT NOT NULL\n)";
+/**
+ * Every statement that builds the saas search schema, in dependency order.
+ *
+ * The unique index on `(corpus, source_id, tenant_id)` is what makes the
+ * provider's upsert idempotent — it is the same natural key the SQLite schema
+ * declares, and 05 §A1's cross-tenant-uniqueness lesson is why `tenant_id` is
+ * in it rather than assumed.
+ */
+export declare const PG_SEARCH_DDL: readonly string[];
+/**
+ * Create the saas search schema. Idempotent, and called EXPLICITLY by a
+ * deployment — never on a process start. See the file header.
+ *
+ * `CREATE POLICY` has no `IF NOT EXISTS` in Postgres, so the policy statements
+ * are skipped when the policy is already there rather than being wrapped in a
+ * swallow-everything `DO` block: a block that ignores the duplicate-object error
+ * also ignores a typo in the predicate, which would leave the table enabled,
+ * forced, and isolated by a policy that never matches.
+ */
+export declare const ensureSaasSearchSchema: (pool: SaasPool) => Promise<void>;

package/dist/server/search/pgSearchSchema.js

@@ -0,0 +1,89 @@
+import { assertRowLevelSecurity, createPostgresControlExecutor, rlsStatements } from 'cwip/storage';
+/** The tsvector expression. Title weighted `A`, body `B` — `ts_rank` reads the weights. */
+const TSV_EXPRESSION = `setweight(to_tsvector('simple', coalesce(title, '')), 'A') || setweight(to_tsvector('simple', coalesce(body, '')), 'B')`;
+/**
+ * Weights fed to `ts_rank`, in Postgres' `{D, C, B, A}` order. Title 4× body,
+ * matching the SQLite provider's `bm25(search_fts, 4.0, 1.0)` exactly — two
+ * profiles that ranked the same corpus differently would make "it ranks wrong in
+ * production" unreproducible on a laptop.
+ */
+export const PG_RANK_WEIGHTS = '{0.1, 0.1, 0.25, 1.0}';
+export const PG_SEARCH_DOCS_DDL = `CREATE TABLE IF NOT EXISTS search_docs (
+  id         BIGSERIAL PRIMARY KEY,
+  corpus     TEXT NOT NULL,
+  source_id  TEXT NOT NULL,
+  tenant_id  TEXT NOT NULL,
+  user_id    TEXT,
+  title      TEXT NOT NULL DEFAULT '',
+  body       TEXT NOT NULL DEFAULT '',
+  rev        INTEGER NOT NULL DEFAULT 0,
+  indexed_at TEXT NOT NULL,
+  tsv        tsvector GENERATED ALWAYS AS (${TSV_EXPRESSION}) STORED
+)`;
+export const PG_SEARCH_CHUNKS_DDL = `CREATE TABLE IF NOT EXISTS search_chunks (
+  id         BIGSERIAL PRIMARY KEY,
+  doc_id     BIGINT NOT NULL REFERENCES search_docs(id) ON DELETE CASCADE,
+  seq        INTEGER NOT NULL,
+  text       TEXT NOT NULL,
+  embedding  BYTEA,
+  dims       INTEGER,
+  model      TEXT,
+  indexed_at TEXT NOT NULL
+)`;
+/**
+ * Every statement that builds the saas search schema, in dependency order.
+ *
+ * The unique index on `(corpus, source_id, tenant_id)` is what makes the
+ * provider's upsert idempotent — it is the same natural key the SQLite schema
+ * declares, and 05 §A1's cross-tenant-uniqueness lesson is why `tenant_id` is
+ * in it rather than assumed.
+ */
+export const PG_SEARCH_DDL = [
+    PG_SEARCH_DOCS_DDL,
+    'CREATE UNIQUE INDEX IF NOT EXISTS search_docs_source ON search_docs(corpus, source_id, tenant_id)',
+    'CREATE INDEX IF NOT EXISTS search_docs_tenant ON search_docs(tenant_id, corpus, indexed_at DESC)',
+    'CREATE INDEX IF NOT EXISTS search_docs_tsv ON search_docs USING GIN(tsv)',
+    PG_SEARCH_CHUNKS_DDL,
+    'CREATE UNIQUE INDEX IF NOT EXISTS search_chunks_seq ON search_chunks(doc_id, seq)',
+    // The vector tier's candidate scan filters on the join plus (dims, model);
+    // without this it is a sequential scan of every tenant's chunks per query.
+    'CREATE INDEX IF NOT EXISTS search_chunks_space ON search_chunks(doc_id, dims, model)',
+    // The platform's OWN policy text, not a hand-written copy. `rlsStatements`
+    // also emits `FORCE ROW LEVEL SECURITY`, which is the half a hand-written
+    // chain forgets and the half that matters here: a table's OWNER bypasses RLS
+    // unless it is FORCEd, and in this platform the application role owns its own
+    // schema. Without it the policy is decoration for exactly the connection that
+    // serves every request.
+    ...rlsStatements('search_docs'),
+];
+// Self-check at module load, the same one `toPostgresChain` performs on a
+// compiled chain. This chain is hand-authored (SQLite's FTS5 shadow has no
+// Postgres translation), so it does NOT go through the compiler that would
+// normally apply this gate — and a hand-authored chain is precisely the one that
+// can ship a tenant-rooted table with no policy.
+assertRowLevelSecurity(PG_SEARCH_DDL);
+/**
+ * Create the saas search schema. Idempotent, and called EXPLICITLY by a
+ * deployment — never on a process start. See the file header.
+ *
+ * `CREATE POLICY` has no `IF NOT EXISTS` in Postgres, so the policy statements
+ * are skipped when the policy is already there rather than being wrapped in a
+ * swallow-everything `DO` block: a block that ignores the duplicate-object error
+ * also ignores a typo in the predicate, which would leave the table enabled,
+ * forced, and isolated by a policy that never matches.
+ */
+export const ensureSaasSearchSchema = async (pool) => {
+    await pool.withConnection(async (connection) => {
+        const executor = createPostgresControlExecutor(connection);
+        const existing = await executor.all({
+            sql: "SELECT policyname FROM pg_policies WHERE tablename = 'search_docs'",
+        });
+        const present = new Set(existing.map((row) => row.policyname));
+        for (const statement of PG_SEARCH_DDL) {
+            const policy = /^CREATE\s+POLICY\s+([a-z_]+)\s+ON\b/i.exec(statement.trim());
+            if (policy?.[1] !== undefined && present.has(policy[1]))
+                continue;
+            await executor.write({ sql: statement });
+        }
+    });
+};

package/dist/server/sharing/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `cursedbelt-server/sharing` — the fleet's ONE per-record sharing/access model.
+ *
+ * The vocabulary is `cursedbelt-core/sharing` (pure), the panel is
+ * `cursedbelt/react/sharing`, and this is the storage + resolver half. Read
+ * `./store.ts`'s header for the five properties it guarantees and `./sql.ts` for
+ * why the row filter is a SQL fragment rather than a list of ids.
+ */
+export { SHARE_MIGRATIONS } from "./migrations";
+export { SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, } from "./migrations";
+export { GROUP_SUBJECT_PREFIX, mountShareRoutes, parseSubjectParam, subjectParam, } from "./router";
+export type { ShareRouterOptions, ShareRouterViewer, ShareRoutesPayload } from "./router";
+export { sharedResourceSql, sqlColumn, sqlLiteral } from "./sql";
+export type { SharedResourceSqlOptions } from "./sql";
+export { createShareStore, group, user } from "./store";
+export type { GrantInput, RevokeInput, ShareEventQuery, ShareStore, ShareStoreOptions, ShareTarget, } from "./store";
+export { accessMeets, describeAccess, describeShareEvent, isShareAccess, isShareLevel, isShareSubjectType, levelsMeeting, normalizeSubject, normalizeSubjectId, resolveAccess, resourceKey, sameResource, sameSubject, SHARE_ACTIONS, strongerAccess, } from "cursedbelt-core/sharing/model";
+export type { ShareAccess, ShareAction, ShareEvent, ShareGrant, ShareGroup, ShareGroupMember, ShareLevel, ShareResource, ShareSubject, ShareSubjectType, ShareViewer, } from "cursedbelt-core/sharing/model";

package/dist/server/sharing/index.js

@@ -0,0 +1,16 @@
+/**
+ * `cursedbelt-server/sharing` — the fleet's ONE per-record sharing/access model.
+ *
+ * The vocabulary is `cursedbelt-core/sharing` (pure), the panel is
+ * `cursedbelt/react/sharing`, and this is the storage + resolver half. Read
+ * `./store.ts`'s header for the five properties it guarantees and `./sql.ts` for
+ * why the row filter is a SQL fragment rather than a list of ids.
+ */
+export { SHARE_MIGRATIONS } from "./migrations";
+export { SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, } from "./migrations";
+export { GROUP_SUBJECT_PREFIX, mountShareRoutes, parseSubjectParam, subjectParam, } from "./router";
+export { sharedResourceSql, sqlColumn, sqlLiteral } from "./sql";
+export { createShareStore, group, user } from "./store";
+// Re-exported so a server consumer needs ONE import for the whole contract; the
+// pure entry (`cursedbelt-core/sharing`) stays available for a browser or a test.
+export { accessMeets, describeAccess, describeShareEvent, isShareAccess, isShareLevel, isShareSubjectType, levelsMeeting, normalizeSubject, normalizeSubjectId, resolveAccess, resourceKey, sameResource, sameSubject, SHARE_ACTIONS, strongerAccess, } from "cursedbelt-core/sharing/model";

package/dist/server/sharing/migrations.d.ts

@@ -0,0 +1,6 @@
+import type { Migration } from "../migration/types";
+export declare const SHARE_GRANTS_TABLE = "share_grants";
+export declare const SHARE_GROUPS_TABLE = "share_groups";
+export declare const SHARE_GROUP_MEMBERS_TABLE = "share_group_members";
+export declare const SHARE_EVENTS_TABLE = "share_events";
+export declare const SHARE_MIGRATIONS: readonly Migration[];

package/dist/server/sharing/migrations.js

@@ -0,0 +1,79 @@
+export const SHARE_GRANTS_TABLE = "share_grants";
+export const SHARE_GROUPS_TABLE = "share_groups";
+export const SHARE_GROUP_MEMBERS_TABLE = "share_group_members";
+export const SHARE_EVENTS_TABLE = "share_events";
+export const SHARE_MIGRATIONS = [
+    {
+        name: "0001_share_grants",
+        up(db) {
+            db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GRANTS_TABLE} (
+					grant_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+					app         TEXT NOT NULL,
+					kind        TEXT NOT NULL,
+					resource_id TEXT NOT NULL,
+					subject_type TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
+					subject_id  TEXT NOT NULL,
+					level       TEXT NOT NULL CHECK (level IN ('read', 'write')),
+					granted_by  TEXT NOT NULL,
+					granted_at  TEXT NOT NULL,
+					note        TEXT NOT NULL DEFAULT '',
+					-- One grant per subject per resource. This is what makes raising
+					-- read to write an UPDATE the audit trail can describe, instead of
+					-- two rows where revoking one leaves access in place.
+					UNIQUE (app, kind, resource_id, subject_type, subject_id)
+				)
+			`);
+            // The hot read is the resolver's: "does this subject hold a grant on this
+            // row" — correlated per row of a list query, so it must be an index hit.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_share_grants_subject
+				 ON ${SHARE_GRANTS_TABLE} (subject_type, subject_id, app, kind, resource_id)`);
+            // …and the panel's: "who can see this record".
+            db.run(`CREATE INDEX IF NOT EXISTS idx_share_grants_resource
+				 ON ${SHARE_GRANTS_TABLE} (app, kind, resource_id)`);
+            db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GROUPS_TABLE} (
+					group_id   TEXT PRIMARY KEY,
+					name       TEXT NOT NULL,
+					created_by TEXT NOT NULL,
+					created_at TEXT NOT NULL,
+					note       TEXT NOT NULL DEFAULT ''
+				)
+			`);
+            db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GROUP_MEMBERS_TABLE} (
+					group_id   TEXT NOT NULL REFERENCES ${SHARE_GROUPS_TABLE} (group_id) ON DELETE CASCADE,
+					subject_id TEXT NOT NULL,
+					added_by   TEXT NOT NULL,
+					added_at   TEXT NOT NULL,
+					PRIMARY KEY (group_id, subject_id)
+				)
+			`);
+            // "Which groups is this person in" — read by every shared-row query.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_share_group_members_subject
+				 ON ${SHARE_GROUP_MEMBERS_TABLE} (subject_id)`);
+            db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_EVENTS_TABLE} (
+					event_id      INTEGER PRIMARY KEY AUTOINCREMENT,
+					at            TEXT NOT NULL,
+					action        TEXT NOT NULL,
+					app           TEXT,
+					kind          TEXT,
+					resource_id   TEXT,
+					subject_type  TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
+					subject_id    TEXT NOT NULL,
+					level         TEXT,
+					previous_level TEXT,
+					actor         TEXT NOT NULL,
+					note          TEXT NOT NULL DEFAULT ''
+				)
+			`);
+            // "Everything that ever happened to this record", newest first.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_share_events_resource
+				 ON ${SHARE_EVENTS_TABLE} (app, kind, resource_id, event_id DESC)`);
+            // "Everything this person was ever given" — the offboarding question.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_share_events_subject
+				 ON ${SHARE_EVENTS_TABLE} (subject_id, event_id DESC)`);
+        },
+    },
+];