@rebasepro/server-postgres 0.13.1-canary.gef9608c → 0.14.0

package/dist/schema/rls-bootstrap-sql.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Canonical SQL bootstrap for the RLS helper functions.
+ *
+ * Generated RLS policies reference `rebase.uid()` / `rebase.roles()` /
+ * `rebase.jwt()`, so any SQL stream that can contain policies must be
+ * self-contained: it has to (re)create these helpers first. This matters for
+ * the migration directory in particular — Atlas replays migrations against a
+ * clean dev database where no out-of-band bootstrap has ever run, so a
+ * migration carrying policies without this preamble fails with
+ * "function rebase.uid() does not exist".
+ *
+ * Idempotent (`IF NOT EXISTS` / `OR REPLACE`) so it can be prepended to every
+ * policies block and re-applied freely. The runtime boot path
+ * (`auth/ensure-tables.ts`) creates the same functions under an advisory lock
+ * for HMR-safety; keep the definitions in sync.
+ *
+ * ## Creating the `rebase` schema here is now safe, and required
+ *
+ * It deliberately did not, once. These functions lived in a schema called
+ * `auth`, and the note here read: creating `rebase` would leak it into Atlas's
+ * replayed migration state, and — absent from the desired `schema.sql` — Atlas
+ * would then plan `DROP SCHEMA "rebase" CASCADE`, taking the auth tables with
+ * it. That reasoning still holds; what changed is the second half of it. The
+ * DDL generator now emits `CREATE SCHEMA IF NOT EXISTS "rebase"`
+ * unconditionally, so the schema is always in the desired state and the diff is
+ * empty. (It used to appear only when some collection happened to declare
+ * `schema: "rebase"` — true for the scaffold's users collection, and not a
+ * property anything guaranteed.) `db push` additionally excludes the whole
+ * schema from the declarative apply.
+ *
+ * See `@rebasepro/types`' `rls-functions` for why the functions moved out of
+ * `auth` at all: the short version is that the name was Supabase's, and
+ * `CREATE OR REPLACE FUNCTION auth.uid() RETURNS text` cannot be applied over
+ * Supabase's `RETURNS uuid` — Postgres refuses, and the refusal used to be
+ * swallowed.
+ */
+/**
+ * The bootstrap as individual statements.
+ *
+ * Kept as an array because the two consumers need different shapes and only one
+ * of them can take a multi-command string: the migration preamble is written to
+ * a file and replayed by Atlas, but the boot path runs through drizzle, whose
+ * node-postgres handle speaks the extended query protocol and rejects more than
+ * one command per call. Splitting a joined string back apart on `$$;` would be
+ * a parser for a problem that does not need one.
+ */
+export declare const RLS_BOOTSTRAP_STATEMENTS: readonly string[];
+/** The same statements as one script, for migration files and raw clients. */
+export declare const RLS_BOOTSTRAP_SQL: string;
+/**
+ * Removes the pre-1.0 `auth` schema, but only when Rebase is what put it there.
+ *
+ * ## Why this is safe against a Supabase database
+ *
+ * Two independent guards, and both have to pass:
+ *
+ *  1. **Each function is identified before it is dropped.** Ours returns `text`
+ *     and reads the `app.uid` GUC; Supabase's returns `uuid` and reads
+ *     `request.jwt.claims`. Nothing is dropped on a signature we did not write,
+ *     so a Supabase database — where our `CREATE OR REPLACE` could never have
+ *     succeeded in the first place, Postgres refusing to change a return type —
+ *     matches nothing and this is a no-op.
+ *  2. **`DROP SCHEMA … RESTRICT`**, never CASCADE. If anything else at all still
+ *     lives in `auth` (Supabase's `users` table, its other helpers), the drop
+ *     fails and the schema stays. CASCADE here would be unrecoverable.
+ *
+ * ## Why it cannot run too early
+ *
+ * Postgres records a dependency from every RLS policy to the functions its body
+ * calls, so `DROP FUNCTION auth.uid()` fails for as long as a single policy
+ * still references it. That is the interlock, and it is load-bearing: the drop
+ * can only succeed once every policy has been recompiled to \`rebase.uid()\`.
+ * Callers therefore run this *after* applying policies, and treat a failure as
+ * "not yet — try again next boot" rather than as an error.
+ */
+export declare const DROP_LEGACY_AUTH_SCHEMA_SQL = "\nDO $rebase_drop_legacy$\nDECLARE\n    dropped_any boolean := false;\nBEGIN\n    -- Each function is matched on its own result type and body, so a schema\n    -- that merely shares the name keeps everything it has.\n    IF EXISTS (\n        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n        WHERE n.nspname = 'auth' AND p.proname = 'uid'\n          AND pg_get_function_result(p.oid) = 'text'\n          AND p.prosrc LIKE '%app.uid%'\n    ) THEN\n        DROP FUNCTION auth.uid();\n        dropped_any := true;\n    END IF;\n\n    IF EXISTS (\n        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n        WHERE n.nspname = 'auth' AND p.proname = 'jwt'\n          AND pg_get_function_result(p.oid) = 'jsonb'\n          AND p.prosrc LIKE '%app.jwt%'\n    ) THEN\n        DROP FUNCTION auth.jwt();\n        dropped_any := true;\n    END IF;\n\n    IF EXISTS (\n        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n        WHERE n.nspname = 'auth' AND p.proname = 'roles'\n          AND pg_get_function_result(p.oid) = 'text'\n          AND p.prosrc LIKE '%app.user_roles%'\n    ) THEN\n        DROP FUNCTION auth.roles();\n        dropped_any := true;\n    END IF;\n\n    -- RESTRICT: only an empty schema goes. Anything else in there \u2014 including a\n    -- Supabase installation left untouched above \u2014 keeps it.\n    IF dropped_any THEN\n        BEGIN\n            EXECUTE 'DROP SCHEMA auth RESTRICT';\n        EXCEPTION WHEN OTHERS THEN\n            NULL;\n        END;\n    END IF;\nEND\n$rebase_drop_legacy$;\n";
+/** Somebody's policy that still calls a pre-1.0 helper. */
+export interface LegacyRlsDependent {
+    schema: string;
+    table: string;
+    policy: string;
+}
+/**
+ * Policies whose body still calls `auth.uid()` / `auth.roles()` / `auth.jwt()`.
+ *
+ * Postgres will not drop a function a policy depends on, so this is exactly the
+ * set standing between a database and losing the legacy schema. Rebase's own
+ * policies leave the list on the next push or boot, when they are recompiled —
+ * anything still here afterwards is hand-written, will never be recompiled by
+ * anybody, and is the reason the drop keeps being skipped. Silence there would
+ * leave an operator staring at a schema the release notes said would go.
+ */
+export declare const LEGACY_RLS_DEPENDENTS_SQL = "\n    SELECT n.nspname AS schema, c.relname AS \"table\", p.polname AS policy\n    FROM pg_policy p\n    JOIN pg_class c ON c.oid = p.polrelid\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    WHERE pg_get_expr(p.polqual, p.polrelid) ~* '\\mauth\\.(uid|jwt|roles)\\s*\\('\n       OR pg_get_expr(p.polwithcheck, p.polrelid) ~* '\\mauth\\.(uid|jwt|roles)\\s*\\('\n    ORDER BY 1, 2, 3\n";
+/** Somebody's *function* that still calls a pre-1.0 helper from its own body. */
+export interface LegacyRlsFunctionDependent {
+    schema: string;
+    function: string;
+}
+/**
+ * Functions whose body calls `auth.uid()` / `auth.roles()` / `auth.jwt()`.
+ *
+ * This is the half `DROP FUNCTION ... RESTRICT` cannot see, and the reason it
+ * needs its own query. Postgres records a dependency for a *policy* that calls a
+ * function, which is why the drop is safe against the policies above — but a
+ * `LANGUAGE sql` function whose body is a **string literal** is not parsed when
+ * it is created, so nothing is recorded and `RESTRICT` has nothing to refuse on.
+ * The drop succeeds and the caller is left pointing at a function that no longer
+ * exists, which fails at *query* time rather than at boot.
+ *
+ * A downstream project building on these helpers is not hypothetical: the Rebase
+ * control plane defines `auth.is_org_member(uuid)` and `auth.is_org_admin(uuid)`
+ * in this very schema, each calling `auth.uid()` in a string body, and eleven of
+ * its row-level-security policies go through them. Every one of those would have
+ * started failing the first time a recompile left no policy referencing
+ * `auth.uid()` directly — the drop's own precondition.
+ *
+ * Matching on the body text is the only option available, and it is deliberately
+ * broad: a false positive costs a schema that stays one release longer and says
+ * why, while a false negative costs somebody their policies.
+ */
+export declare const LEGACY_RLS_FUNCTION_DEPENDENTS_SQL = "\n    SELECT n.nspname AS schema, p.proname AS function\n    FROM pg_proc p\n    JOIN pg_namespace n ON n.oid = p.pronamespace\n    WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')\n      AND NOT (n.nspname = 'auth' AND p.proname IN ('uid', 'jwt', 'roles'))\n      AND p.prosrc ~* '\\mauth\\.(uid|jwt|roles)\\s*\\('\n    ORDER BY 1, 2\n";
+/**
+ * Retire the pre-1.0 `auth` schema, reporting what is holding it back.
+ *
+ * The shared implementation behind the CLI's post-push step and the runtime's
+ * post-policy step. Both used to just fire {@link DROP_LEGACY_AUTH_SCHEMA_SQL}
+ * and swallow whatever came back, which is right for the ordinary case — a
+ * table not recompiled *yet* — and wrong for the one that never resolves: a
+ * hand-written policy nothing will ever rewrite. Then the schema stays forever
+ * and nothing ever says why.
+ */
+export declare function dropLegacyAuthSchema(run: (sql: string) => Promise<Record<string, unknown>[]>, report: {
+    info: (m: string) => void;
+    warn: (m: string) => void;
+}): Promise<void>;

package/dist/schema/search-column.d.ts

@@ -0,0 +1,248 @@
+/**
+ * The one place a collection's `search` block becomes SQL.
+ *
+ * Four things describe a Postgres table in this codebase — the DDL generator,
+ * the Drizzle schema generator, the runtime table builder for BaaS mode, and
+ * the boot-time schema ensure — and each of them has, at some point, described
+ * a column differently from the others. The `varchar(255)` note in
+ * `generate-postgres-ddl-logic` is one such scar: the same property produced a
+ * capped column down one path and an uncapped one down the other, and nothing
+ * failed until a user hit the cap.
+ *
+ * So the search column is not implemented four times. It is computed once,
+ * here, and every generator renders the same {@link SearchColumnSpec}. There is
+ * a test asserting exactly that (`search-column-contract.test.ts`); the point of
+ * this module is that the test has something to assert *about*.
+ *
+ * ## Why the expressions look the way they do
+ *
+ * A `GENERATED ALWAYS AS … STORED` expression must be strictly IMMUTABLE, and
+ * Postgres is stricter here than intuition. Verified against PostgreSQL 18:
+ *
+ * | expression                              | immutable |
+ * |-----------------------------------------|-----------|
+ * | `to_tsvector('spanish', col)`           | yes       |
+ * | `to_tsvector(col)` (1-arg)              | **no** — depends on `default_text_search_config` |
+ * | `array_to_string(col, ' ')`             | **no**    |
+ * | `col::text` on `text[]`                 | **no**    |
+ * | `to_jsonb(col)`                         | **no**    |
+ * | `unaccent(col)`                         | **no** — dictionary lookup is STABLE |
+ * | `jsonb_to_tsvector('spanish', j, '["string"]')` | yes |
+ * | `setweight(...) || setweight(...)`      | yes       |
+ *
+ * Three of the four things a real search column needs are therefore unavailable
+ * directly, which is why {@link searchHelperFunctions} exists: each wraps a
+ * stable built-in in an SQL function declared IMMUTABLE. That declaration is a
+ * promise, and it is a true one for these three — array joining, JSON string
+ * extraction and accent folding are all deterministic for a given input; the
+ * built-ins are marked stable only because they must account for element types
+ * and dictionaries in general.
+ *
+ * The alternative was to skip `unaccent` and text arrays entirely. That is not
+ * a real option in an accented language: Postgres stems `auditoría` to
+ * `auditor` and `auditoria` to `auditori` — *different lexemes* — so a query
+ * typed without accents misses every row that carries them.
+ */
+import { CollectionConfig, SearchConfig, SearchWeight } from "@rebasepro/types";
+/**
+ * Names of the helper functions. Frozen: they are recorded in the stored
+ * generation expression of every search column ever created, so renaming one
+ * orphans every table that already has a search column.
+ */
+export declare const SEARCH_TEXT_FN = "public.rebase_search_text";
+export declare const SEARCH_UNACCENT_FN = "public.rebase_search_unaccent";
+/** How a declared path reaches text, which decides the SQL that extracts it. */
+type FieldKind = "text" | "text_array" | "jsonb";
+/** One resolved field: where it lives, how to read it, what it is worth. */
+export interface ResolvedSearchField {
+    /** The path exactly as the author wrote it, for error messages. */
+    path: string;
+    /** The physical column the path starts at. */
+    column: string;
+    /** Dotted remainder addressed inside a JSONB column, if any. */
+    jsonPath: string[];
+    kind: FieldKind;
+    weight: SearchWeight;
+    /** The `setweight(to_tsvector(…), 'X')` term this field contributes. */
+    sql: string;
+    /** The plain-text term this field contributes, for the fuzzy column. */
+    textSql: string;
+}
+/** Everything the generators need to render one collection's search column. */
+export interface SearchColumnSpec {
+    schema: string;
+    table: string;
+    /** The generated `tsvector` column. */
+    column: string;
+    language: string;
+    unaccent: boolean;
+    fields: ResolvedSearchField[];
+    /** Body of `GENERATED ALWAYS AS ( … ) STORED` for the tsvector column. */
+    expression: string;
+    indexName: string;
+    /** Extensions that must exist before the column can be created. */
+    extensions: string[];
+    fuzzy?: {
+        column: string;
+        expression: string;
+        indexName: string;
+        threshold: number;
+    };
+}
+/** Raised when a `search` block names something that cannot be searched. */
+export declare class SearchConfigError extends Error {
+    constructor(message: string);
+}
+/** The `search` block of a collection, or undefined when it has none. */
+export declare const getSearchConfig: (collection: CollectionConfig) => SearchConfig | undefined;
+/**
+ * Refuse a `search` block on a collection this engine does not store.
+ *
+ * The type only permits one on a `PostgresCollectionConfig`, so TypeScript
+ * already stops the ordinary case. This catches the rest — a JS config, a cast,
+ * a collection whose `engine` was changed after the block was written — because
+ * the alternative is the exact failure the block exists to prevent: a developer
+ * who declared what to index, saw no error, and got the substring fallback.
+ *
+ * Called with *every* collection, before the Postgres ones are filtered out.
+ */
+export declare const assertSearchIsPostgresOnly: (collections: CollectionConfig[]) => void;
+/**
+ * Build the full spec for a collection, or undefined when it has not opted in.
+ *
+ * Throws {@link SearchConfigError} on a config that cannot be honoured. Callers
+ * at boot surface that as a startup failure — a search block that half-works is
+ * worse than one that refuses.
+ */
+export declare const buildSearchColumnSpec: (collection: CollectionConfig) => SearchColumnSpec | undefined;
+/**
+ * The IMMUTABLE wrappers the generated expressions call.
+ *
+ * `CREATE OR REPLACE` so a boot against an existing database is a no-op rather
+ * than an error, and idempotent for the same reason every other boot-time DDL
+ * statement here is.
+ *
+ * The bodies are stable built-ins wrapped in an immutable promise — see the
+ * module comment for why that promise is sound. `STRICT` matters: it makes NULL
+ * in mean NULL out without executing the body, which is what the `coalesce` at
+ * each call site then absorbs.
+ */
+export declare const searchHelperFunctions: (spec: SearchColumnSpec) => string[];
+/**
+ * `CREATE EXTENSION` statements the spec's expressions depend on.
+ *
+ * `WITH SCHEMA public` is load-bearing, not tidiness. An unqualified
+ * `CREATE EXTENSION` installs into the first schema on `search_path`, which
+ * defaults to `"$user", public` — and the scaffold's database role is named
+ * `rebase`, the same as the schema the generator creates one statement earlier.
+ * So the moment that schema exists, `CREATE EXTENSION unaccent` puts the
+ * dictionary in `rebase`, and every reference to `public.unaccent` below fails
+ * with "text search dictionary does not exist". Observed, not theorised.
+ */
+export declare const searchExtensionStatements: (spec: SearchColumnSpec) => string[];
+/** The column definition as it appears inside `CREATE TABLE`. */
+export declare const searchColumnDefinition: (spec: SearchColumnSpec) => string;
+/** The fuzzy column definition, when the spec asks for one. */
+export declare const fuzzyColumnDefinition: (spec: SearchColumnSpec) => string | undefined;
+/**
+ * Index statements for the spec.
+ *
+ * `CONCURRENTLY` is deliberately *not* used here. This form is emitted into a
+ * SQL file replayed as one unit — a migration, or `search.sql` — where a
+ * concurrent build is not allowed. The boot-time ensure path runs statement by
+ * statement against tables that are live and populated, and uses the
+ * concurrent form instead; see `ensureSearchColumns`.
+ */
+export declare const searchIndexStatements: (spec: SearchColumnSpec) => string[];
+/**
+ * Marker on the comment of every generated search column this module creates.
+ *
+ * Versioned because the fingerprint below is only comparable against itself: a
+ * future change to how it is computed has to read as "not stamped by this
+ * version" rather than as drift on every existing column.
+ */
+export declare const SEARCH_STAMP_PREFIX = "rebase:search:v1:";
+/**
+ * A stable fingerprint of one generated column's expression.
+ *
+ * Why a stamp rather than reading the expression back: Postgres stores a
+ * generated column's expression *parsed*, and hands it back deparsed — casts
+ * made explicit, identifiers requoted, schema qualifications added or dropped
+ * according to `search_path`. Comparing that text to the text we generated
+ * would report drift on wording, and this comparison decides whether a boot
+ * refuses, so a false positive is an outage. The stamp is written by the same
+ * code that writes the column, so equality means what it says.
+ */
+export declare const searchExpressionFingerprint: (expression: string) => string;
+/** One generated column, with the fingerprint that identifies its expression. */
+export interface SearchColumnStamp {
+    column: string;
+    /** The expression the column is generated from. */
+    expression: string;
+    fingerprint: string;
+    /** `COMMENT ON COLUMN …`, which is where the fingerprint is recorded. */
+    sql: string;
+}
+/**
+ * The stamps for a spec's generated columns — one per column, never shared.
+ *
+ * Per column on purpose: turning `fuzzy` on adds a second column and changes
+ * nothing about the first, and a spec-wide fingerprint would report the
+ * untouched `tsvector` column as drifted and refuse a boot over a change that
+ * is purely additive.
+ */
+export declare const searchColumnStamps: (spec: SearchColumnSpec) => SearchColumnStamp[];
+/**
+ * The same drift check as the boot ensure, for the SQL file.
+ *
+ * Needed because {@link searchColumnStamps} would otherwise *launder* drift on
+ * the migration path: `ADD COLUMN IF NOT EXISTS` does nothing to a column that
+ * exists, so a re-generated `search.sql` would stamp a stale column with the
+ * new block's fingerprint and the next boot would find them in agreement.
+ * Guarding first means the file refuses instead — `rebase db push` is attended,
+ * and the operator reading the failure is the person who changed the block.
+ */
+export declare const searchStampGuards: (spec: SearchColumnSpec) => string[];
+/**
+ * The index names the spec creates.
+ *
+ * Needed by name, not just by statement, so Atlas can be told to exclude them
+ * from its diff — see `searchExcludePatterns`.
+ */
+export declare const searchIndexNames: (spec: SearchColumnSpec) => string[];
+/**
+ * The generated column names a collection's search block adds, if any.
+ *
+ * These are physical columns on the table, so `SELECT *` returns them. They are
+ * an index in column form — a list of lexeme positions, or a concatenation of
+ * every searchable field on the row — and nothing outside the query planner has
+ * any use for them. Left in, every list response carries a second, larger copy
+ * of the row's text.
+ */
+export declare const searchColumnNames: (collection: CollectionConfig) => string[];
+/**
+ * True for a column whose type only ever holds a search index.
+ *
+ * Independent of any collection config on purpose: an introspected database
+ * (BaaS mode) can carry a `tsvector` column this framework never created —
+ * Pagila's `film.fulltext` is the canonical one — and it should not be returned
+ * to callers either. `isDerivedIndexColumn` already keeps such a column out of
+ * the *properties*; this keeps it out of the *rows*.
+ */
+export declare const isSearchIndexColumn: (column: {
+    getSQLType?: () => string;
+}) => boolean;
+/**
+ * A drizzle select projection over `table` with the search columns dropped.
+ *
+ * Returns undefined when nothing needs dropping, so the common case keeps using
+ * a plain `select()` and this stays invisible in the generated SQL.
+ */
+export declare const visibleColumnProjection: (tableColumns: Record<string, {
+    getSQLType?: () => string;
+}> | undefined, collection?: CollectionConfig) => Record<string, unknown> | undefined;
+/** The same exclusion as a drizzle `db.query` `columns` denylist. */
+export declare const hiddenColumnsOption: (tableColumns: Record<string, {
+    getSQLType?: () => string;
+}> | undefined, collection?: CollectionConfig) => Record<string, false> | undefined;
+export {};

package/dist/security/policy-drift.d.ts

@@ -26,6 +26,20 @@ export interface PolicyRef {
     hasUsing: boolean;
     /** Whether a WITH CHECK clause is present at all (not what it says). */
     hasWithCheck: boolean;
+    /**
+     * PERMISSIVE or RESTRICTIVE — the `AS` clause.
+     *
+     * An exact catalogue value on both sides, so it belongs with roles and
+     * command rather than with the expression text. It matters more than either:
+     * permissive policies are ORed together and restrictive ones ANDed, so a rule
+     * declared `mode: "restrictive"` whose live policy is PERMISSIVE has had its
+     * gate turned from a requirement into an alternative — the maximally
+     * permissive way for this to be wrong.
+     *
+     * The DDL regex captured this from the start and the destructuring threw it
+     * away; `pg_policies.permissive` was never selected.
+     */
+    mode?: "PERMISSIVE" | "RESTRICTIVE";
     /**
      * The live clause text, when read from `pg_policies`. Present only for live
      * policies (the expected side is parsed from DDL and does not carry it).
@@ -62,6 +76,26 @@ export interface PolicyDrift {
         policy: PolicyRef;
         reason: string;
     }[];
+    /**
+     * A table the collections describe whose RLS switch is off.
+     *
+     * `ALTER TABLE posts DISABLE ROW LEVEL SECURITY` leaves every row in
+     * `pg_policies` untouched, so before this category every expected policy
+     * still matched on name, roles, command and clause presence and the checker
+     * reported clean — on a table Postgres was applying no filter to at all.
+     * Requests run as `rebase_user`, which holds full DML, so the table is wide
+     * open while `doctor` certifies it.
+     *
+     * `forced` reports `relforcerowsecurity`, which is what also subjects the
+     * table's *owner* to its policies. Its absence is not drift on its own —
+     * Rebase does not connect as the owner in the request path — so it is
+     * reported for context rather than raised as a failure.
+     */
+    rlsDisabled: {
+        schema: string;
+        table: string;
+        forced: boolean;
+    }[];
 }
 export interface Queryable {
     query<R>(text: string, values?: unknown[]): Promise<{

package/dist/security/rls-enforcement.d.ts

@@ -1,5 +1,6 @@
 import { SQL } from "drizzle-orm";
 import { SecurityRule } from "@rebasepro/types";
+import { REBASE_USER_ROLE } from "@rebasepro/common";
 /**
  * Unified RLS enforcement — the "user context vs server context" model.
  *
@@ -13,9 +14,14 @@ import { SecurityRule } from "@rebasepro/types";
  *    are validation/side-effects, not a security boundary.
  *
  *  - **Server context** — the base (owner) connection: auth flows, migrations,
- *    background jobs, and the explicit `rebase.dataAsAdmin` accessor. As table
- *    owner it bypasses RLS. This is the trusted plane, equivalent to
- *    Supabase's `service_role`.
+ *    and raw `rebase.sql`. As table owner it bypasses RLS. This is the trusted
+ *    plane, equivalent to Supabase's `service_role`.
+ *
+ *    `rebase.dataAsAdmin` is **not** in it, despite the name. `init.ts` scopes
+ *    that driver with `withAuth(SERVICE_IDENTITY)`, so it arrives as user
+ *    context above — `rebase_user`, `app.uid = 'service'`, policies evaluated —
+ *    and clears the default policies through their admin arm rather than the
+ *    `auth.uid() IS NULL` one.
  *
  * This module provides the three pieces:
  *
@@ -32,8 +38,14 @@ import { SecurityRule } from "@rebasepro/types";
  * self-creates the `auth` schema and functions) — enforcement is default-on,
  * not an operator opt-in.
  */
-/** The restricted role every authenticated (user-context) request runs as. */
-export declare const REBASE_USER_ROLE = "rebase_user";
+/**
+ * The restricted role every authenticated (user-context) request runs as.
+ *
+ * Re-exported, not re-declared: the same name is needed by
+ * `@rebasepro/common`'s internal-table revokes, and two spellings of a role name
+ * fail as a silent no-op rather than an error.
+ */
+export { REBASE_USER_ROLE };
 /** Minimal SQL runner so callers can adapt drizzle or pg.Client. */
 export type RawSqlRunner = (sqlText: string) => Promise<Record<string, unknown>[]>;
 /** Minimal transaction surface needed by {@link applyAuthContext}. */
@@ -55,6 +67,34 @@ export interface AuthContext {
     /** Raw roles as carried on the user (strings or `{ id }` objects). */
     roles: unknown[];
 }
+/**
+ * Warn when the connection role shares its name with an existing schema.
+ *
+ * Postgres resolves unqualified names through `search_path`, which defaults to
+ * `"$user", public` — and `$user` is the connection ROLE. When a schema of that
+ * name exists it sits ahead of `public`, so every unqualified statement
+ * silently operates on it instead:
+ *
+ *     CREATE TABLE posts (...);   -- you meant public.posts; you got <role>.posts
+ *
+ * Nothing errors. You get a second table of the same name in the wrong schema,
+ * and reads that pin `public` cannot see it — which reads as "missing table" and
+ * sends people to re-run a push that creates a *third* copy. The bootstrapper
+ * has a whole branch dedicated to recognising the symptom after the fact.
+ *
+ * Rebase shipped straight into this: it creates a schema named `rebase` while
+ * every template named the database role `rebase` too. The scaffold uses
+ * `rebase_app` now, and every pool Rebase opens pins `search_path=public`
+ * (`pinSearchPath`), which covers the paths the framework controls. This covers
+ * the ones it does not — `psql`, `pg_dump`, drizzle-kit, a colleague's script,
+ * a hand-written migration — because the hazard is a property of the two NAMES,
+ * not of any one connection.
+ *
+ * A warning rather than a boot failure: the database works, the framework's own
+ * traffic is pinned, and refusing to start over a naming choice a user may have
+ * inherited would be worse than the risk.
+ */
+export declare function warnOnRoleSchemaCollision(run: RawSqlRunner): Promise<void>;
 export declare function detectConnectionPosture(run: RawSqlRunner): Promise<ConnectionPosture>;
 /**
  * Human-actionable instructions for when the connection cannot provision the
@@ -123,6 +163,22 @@ export declare function warnOnAnonymousGrants(collections: {
     slug?: string;
     securityRules?: readonly SecurityRule[];
 }[]): void;
+/**
+ * Name the collections whose raw policy SQL still calls the pre-1.0 helpers.
+ *
+ * The compiler rewrites `auth.uid()` to `rebase.uid()` on the way into the
+ * database, so nothing is broken and no policy is wrong — which is exactly why
+ * this has to be said out loud. A silent rewrite that works forever is not a
+ * migration, it is a second supported spelling nobody wrote down, and the next
+ * person to read those rules will copy the old one.
+ *
+ * Only `raw` expressions can carry it. Structured rules (`policy.authUid()`,
+ * `policy.rolesOverlap(...)`) compile from the model and were never affected.
+ */
+export declare function warnOnLegacyRlsFunctions(collections: {
+    slug?: string;
+    securityRules?: readonly SecurityRule[];
+}[]): void;
 /**
  * Reject `pgRoles` that this server can never satisfy.
  *

package/dist/services/FetchService.d.ts

@@ -64,6 +64,18 @@ export declare class FetchService {
      * and skips rows rather than erroring. The guesses stay, last, for a
      * caller that hands over no collection to resolve against.
      */
+    /**
+     * The ORDER BY target, which may be relevance rather than a column.
+     *
+     * `_score` is only meaningful for a collection that declared a `search`
+     * block *and* for a request that carried a search string — ranking rows
+     * against no query ranks them all at zero. Outside those two conditions it
+     * is an unknown field and gets the same 400 as any other typo, which is the
+     * behaviour that matters: a sort that is silently dropped returns 200 with
+     * rows in arbitrary order, and paging over that repeats and skips rows.
+     */
+    static readonly SCORE_FIELD = "_score";
+    private resolveOrderTarget;
     private resolveOrderByField;
     /**
      * Build the `with` config for Drizzle's relational query API.
@@ -132,6 +144,7 @@ export declare class FetchService {
         offset?: number;
         startAfter?: Record<string, unknown>;
         searchString?: string;
+        searchExplain?: boolean;
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
         logical?: LogicalCondition;
@@ -177,10 +190,21 @@ export declare class FetchService {
      */
     searchRows<M extends Record<string, unknown>>(collectionPath: string, searchString: string, options?: {
         filter?: FilterValues<Extract<keyof M, string>>;
+        /**
+         * An `or(...)`/`and(...)` group, applied alongside `filter`.
+         *
+         * `fetchRowsWithConditions` has always applied one; it was missing
+         * from this signature, so a realtime search subscription carrying a
+         * group could not pass it on and served every row matching the text
+         * that RLS allowed.
+         */
+        logical?: LogicalCondition;
         orderBy?: string;
         order?: "desc" | "asc";
         limit?: number;
         databaseId?: string;
+        /** Ask each row which declared search field matched. */
+        searchExplain?: boolean;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Count rows in a collection

package/dist/services/PersistService.d.ts

@@ -1,4 +1,5 @@
 import { RelationService } from "./RelationService";
+import { RelationWriteService } from "./RelationWriteService";
 import { FetchService } from "./FetchService";
 import { DrizzleClient } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
@@ -9,25 +10,15 @@ import { PostgresCollectionRegistry } from "../collections/PostgresCollectionReg
 export declare class PersistService {
     private db;
     private registry;
+    /** Reads: whether a row is under a parent, the key a link joins on. */
     private relationService;
+    /** Writes: junction membership, foreign-key stamping, links. */
+    private relationWrites;
     private fetchService;
     constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
     /**
-     * Explain a write that matched no rows.
-     *
-     * Row-level security filters UPDATE and DELETE through the policy's USING
-     * clause instead of raising: a denied write is reported by Postgres exactly
-     * like a successful one that happened to match nothing. Left unchecked, a
-     * caller cannot tell "denied" from "done" — the write returns 200/204 and
-     * the row is untouched.
-     *
-     * Re-reading the target over the *same* RLS-scoped handle separates the two
-     * cases. A visible row means the policy rejected the write (403); an
-     * invisible one means there is nothing there to write for this caller (404,
-     * matching what a GET would say). The re-read is bound by the caller's own
-     * policies, so it discloses nothing a plain read wouldn't.
-     *
-     * Only reached when zero rows matched, so the happy path pays nothing.
+     * Explain a row write that matched nothing — see {@link explainZeroRowWrite}
+     * for why a zero-row write cannot be reported as success.
      */
     private explainZeroRowWrite;
     /**
@@ -39,8 +30,14 @@ export declare class PersistService {
      */
     deleteAll(collectionPath: string, _databaseId?: string): Promise<void>;
     /**
-     * The column on the *target* table that records the parent, for a create
-     * under a nested one-to-many path.
+     * The field on the *target* row that records the parent, for a create under
+     * a nested one-to-many path.
+     *
+     * A **field**, not the column: the value is stamped into the caller's
+     * payload, which is keyed by wire names — `authorId`, never the `author_id`
+     * the relation names its link by. Stamping the column instead put a key on
+     * the payload that no property answers to, and `strictWrites` rejected the
+     * request the framework had just written to.
      *
      * Returns `undefined` when the link is not a column at all (a multi-hop
      * `joinPath`), so the caller writes the row without stamping anything.
@@ -66,6 +63,13 @@ export declare class PersistService {
      * Get the RelationService instance for external use
      */
     getRelationService(): RelationService;
+    /**
+     * The write half, for external use. Separate from
+     * {@link getRelationService} because they are separate objects now: reads
+     * answer questions, writes change rows, and the callers of one are not the
+     * callers of the other.
+     */
+    getRelationWriteService(): RelationWriteService;
     /**
      * Get the FetchService instance for external use
      */