@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g249daa1

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,199 @@
+/**
+ * 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[];
+/**
+ * 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/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.
  *
@@ -32,8 +33,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 +62,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 +158,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;
@@ -153,6 +166,16 @@ export declare class FetchService {
      */
     fetchCollection<M extends Record<string, unknown>>(collectionPath: string, options?: {
         filter?: FilterValues<Extract<keyof M, string>>;
+        /**
+         * An `or(...)`/`and(...)` group, applied alongside `filter`.
+         *
+         * `fetchRowsWithConditions` below has always applied this; it was
+         * simply absent from this signature, so the only callers that could
+         * pass one were the ones that went around this method. Realtime
+         * came through here, which is why a subscription filtered by a
+         * logical group was pushed every row in the table.
+         */
+        logical?: LogicalCondition;
         orderBy?: string;
         order?: "desc" | "asc";
         limit?: number;
@@ -171,6 +194,8 @@ export declare class FetchService {
         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
@@ -226,13 +251,6 @@ export declare class FetchService {
      * Note: Primary path now uses inline `getQueryBuilder()` checks.
      */
     private hasDrizzleQueryAPI;
-    /**
-     * Attempt to use Drizzle's relational query API (db.query.<table>.findMany)
-     * for efficient JOIN-based relation loading.
-     * Returns null if the API is not available or the query fails.
-     * Note: Primary path now uses `buildWithConfig` + `buildDrizzleQueryOptions`.
-     */
-    private fetchWithDrizzleQuery;
     /**
      * Fallback path used when db.query is unavailable.
      * The primary path uses db.query.findMany with `with` config, which

package/dist/services/dataService.d.ts

@@ -36,6 +36,8 @@ export declare class DataService implements DataRepository {
      */
     fetchCollection<M extends Record<string, unknown>>(collectionPath: string, options?: {
         filter?: FilterValues<Extract<keyof M, string>>;
+        /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
+        logical?: LogicalCondition;
         orderBy?: string;
         order?: "desc" | "asc";
         limit?: number;
@@ -54,6 +56,7 @@ export declare class DataService implements DataRepository {
         order?: "desc" | "asc";
         limit?: number;
         databaseId?: string;
+        searchExplain?: boolean;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Count rows in a collection

package/dist/services/realtimeService.d.ts

@@ -1,6 +1,6 @@
 import { WebSocket } from "ws";
 import { EventEmitter } from "events";
-import { DataDriver, WebSocketMessage } from "@rebasepro/types";
+import { DataDriver, WebSocketMessage, LogicalCondition } from "@rebasepro/types";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
@@ -14,6 +14,29 @@ export interface SubscriptionAuthContext {
     uid: string;
     roles: string[];
 }
+/**
+ * The narrowing a collection subscription was created with, kept so that every
+ * refetch answers the same query the initial fetch did.
+ *
+ * Named once because it used to be written out inline in five places, and a
+ * field missing from one of them is accepted over the wire and then silently
+ * ignored: `offset` was declared on the incoming props and never stored, so a
+ * live list on page three served page one, and `logical` was never stored
+ * either, so an `or(...)` subscription was pushed every row in the table.
+ */
+type StoredCollectionRequest = {
+    filter?: Record<string, unknown>;
+    logical?: LogicalCondition;
+    orderBy?: string;
+    order?: "desc" | "asc";
+    limit?: number;
+    offset?: number;
+    startAfter?: Record<string, unknown>;
+    databaseId?: string;
+    searchString?: string;
+    /** Ask each row which declared search field matched — populates `_matches`. */
+    searchExplain?: boolean;
+};
 /**
  * PostgreSQL-specific realtime service.
  * Handles WebSocket connections and subscriptions for real-time row updates.
@@ -128,16 +151,7 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
         type: "collection" | "single";
         path: string;
         id?: string | number;
-        collectionRequest?: {
-            filter?: Record<string, unknown>;
-            orderBy?: string;
-            order?: "desc" | "asc";
-            limit?: number;
-            offset?: number;
-            startAfter?: Record<string, unknown>;
-            databaseId?: string;
-            searchString?: string;
-        };
+        collectionRequest?: StoredCollectionRequest;
         authContext?: SubscriptionAuthContext;
     }>;
     registerDataDriverSubscription(subscriptionId: string, subscription: {
@@ -145,16 +159,7 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
         type: "collection" | "single";
         path: string;
         id?: string | number;
-        collectionRequest?: {
-            filter?: Record<string, unknown>;
-            orderBy?: string;
-            order?: "desc" | "asc";
-            limit?: number;
-            offset?: number;
-            startAfter?: Record<string, unknown>;
-            databaseId?: string;
-            searchString?: string;
-        };
+        collectionRequest?: StoredCollectionRequest;
         authContext?: SubscriptionAuthContext;
     }): void;
     addSubscriptionCallback(subscriptionId: string, callback: (data: Record<string, unknown>[] | Record<string, unknown> | null) => void): void;
@@ -497,3 +502,4 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
  * This allows code to use PostgresRealtimeProvider alongside future MongoRealtimeProvider, etc.
  */
 export declare const PostgresRealtimeProvider: typeof RealtimeService;
+export {};