@rebasepro/common 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/data/paginate.ts

@@ -1,4 +1,5 @@
 import {
+    DEFAULT_LIST_LIMIT,
     FilterValues,
     FieldPath,
     FindAllParams,
@@ -70,6 +71,35 @@ export class RebasePaginationError extends Error {
 export type PageFinder<M extends Record<string, unknown> = Record<string, unknown>> =
     (params: FindParams<M>) => Promise<FindResult<M>>;
 
+/**
+ * Resolve `limit`/`offset`/`page` into the window a read will actually use.
+ *
+ * Lives here, next to the walk, for the reason at the top of this file: every
+ * transport has to mean the same thing by "page two". Four of them did not —
+ * the REST layer strode by {@link DEFAULT_LIST_LIMIT}, the local-first
+ * evaluator by {@link DEFAULT_PAGE_SIZE}, the in-process accessor by 20, and
+ * the published type documented a fourth number. Pages that overlap or skip
+ * rows are the mildest of those outcomes.
+ *
+ * `page` wins over `offset`, as {@link FindParams} documents. `driverOffset`
+ * is the value to hand a driver: it stays `undefined` when the caller named no
+ * offset, because keyset pagination seeks with a `where` clause and must not
+ * look like it is paging by offset.
+ */
+export function resolveFindWindow(
+    params?: Pick<FindParams, "limit" | "offset" | "page">
+): { limit: number; offset: number; driverOffset: number | undefined } {
+    const limit = params?.limit ?? DEFAULT_LIST_LIMIT;
+    const offset = params?.page != null
+        ? Math.max(0, (params.page - 1) * limit)
+        : (params?.offset ?? 0);
+    return {
+        limit,
+        offset,
+        driverOffset: params?.page != null ? offset : params?.offset
+    };
+}
+
 function normalizePageSize(raw: number | undefined): number {
     if (raw === undefined || !Number.isFinite(raw)) return DEFAULT_PAGE_SIZE;
     return Math.max(1, Math.floor(raw));

package/src/data/query_builder.ts

@@ -6,7 +6,8 @@ import {
     LogicalCondition,
     QueryBuilderInterface,
     WhereFilterOp,
-    WhereValue
+    WhereValueFor,
+    type ComputedSortField
 } from "@rebasepro/types";
 
 export function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition {
@@ -40,7 +41,7 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
      * @example
      * client.collection('users').where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
         // Handle LogicalCondition signature
@@ -80,7 +81,7 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
      * @example
      * client.collection('users').orderBy('createdAt', 'desc').find()
      */
-    orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
+    orderBy(column: (keyof M & string) | ComputedSortField, direction: "asc" | "desc" = "asc"): this {
         this.params.orderBy = [column, direction];
         return this;
     }
@@ -104,8 +105,29 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
     /**
      * Set a free-text search string if supported by the backend.
      */
-    search(searchString: string): this {
+    search(searchString: string, options?: { explain?: boolean }): this {
         this.params.searchString = searchString;
+        if (options?.explain !== undefined) this.params.searchExplain = options.explain;
+        return this;
+    }
+
+    /**
+     * Order rows by nearest-neighbour distance to `vector`, closest first.
+     *
+     * Postgres only, over a property declared as `type: "vector"`. Rows come
+     * back with a `_distance`; `where` filters before the ordering.
+     */
+    vectorSearch(
+        property: string,
+        vector: number[],
+        options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+    ): this {
+        this.params.vectorSearch = {
+            property,
+            vector,
+            ...(options?.distance !== undefined && { distance: options.distance }),
+            ...(options?.threshold !== undefined && { threshold: options.threshold })
+        };
         return this;
     }
 

package/src/data/resolveDataSource.ts

@@ -77,3 +77,59 @@ export function resolveDataSource(
         capabilities: getDataSourceCapabilities(engine)
     };
 }
+
+/**
+ * Does a SQL toolchain own this collection's storage?
+ *
+ * "Owns the storage" means: something generates a table for it, pushes that
+ * table to a database, plans its RLS policies, and reports it as drifted when
+ * the two disagree. That is true of a Postgres collection and false of a
+ * Firestore or MongoDB one, whose documents live in a store Rebase never
+ * migrates — and the two were never told apart. Every stage of the SQL
+ * toolchain took "the collections" to mean *all* of them, so a Firestore
+ * collection declared next to the Postgres ones got a `pgTable` in the
+ * generated schema, a `CREATE TABLE` at boot, RLS policies, and a place in the
+ * `db push` include list — where its name shielding a same-named real table
+ * from Atlas's exclude list is the one that can lose data.
+ *
+ * The answer is the resolved engine's {@link DataSourceCapabilities}, not a
+ * name check: an engine registered through `registerDataSourceCapabilities`
+ * gets the same treatment as the built-in ones.
+ *
+ * Deliberately answers **true** for an engine nobody has heard of. Build-time
+ * tooling (the CLI, the schema generator) has no data-source registry to
+ * resolve a `dataSource` key against, so an unknown key resolves to an unknown
+ * engine — and the cost of the two mistakes is not symmetric. Wrongly
+ * including a collection generates a table nothing writes to; wrongly excluding
+ * one silently stops generating a table the app is serving from. Declare
+ * `engine` on a collection that is not SQL-backed and this is exact.
+ */
+export function isRelationalCollection(
+    collection: DataSourceResolvable | undefined,
+    registry?: DataSourceRegistry
+): boolean {
+    // The collection's own `engine` wins over a registered definition's. That
+    // is the opposite of {@link resolveDataSource}'s precedence, deliberately:
+    // there a definition describes where the data *goes*, so it should override;
+    // here the question is what the author said this collection is, and a
+    // collection declaring `engine: "firestore"` with no `dataSource` must not
+    // come back as the default source's engine and be handed a table.
+    const engine = collection?.engine
+        ?? (collection?.dataSource ? resolveDataSource(collection, registry).engine : undefined);
+    return getDataSourceCapabilities(engine).supportsRelations;
+}
+
+/**
+ * The subset of `collections` a SQL toolchain owns — see
+ * {@link isRelationalCollection}.
+ *
+ * Every stage that generates SQL from collections starts by calling this, so
+ * the rule lives in one place rather than being re-decided per generator. It
+ * keeps the input order.
+ */
+export function relationalCollections<C extends DataSourceResolvable>(
+    collections: readonly C[],
+    registry?: DataSourceRegistry
+): C[] {
+    return collections.filter(collection => isRelationalCollection(collection, registry));
+}

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./data/buildRoutedRebaseData";
 export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
 export * from "./data/paginate";
+export * from "./data/filter-conditions";
 export * from "./data/filter-dialect";
 export * from "./data/sort-dialect";
 export * from "./table-classification";

package/src/util/auth-default-policies.ts

@@ -8,8 +8,14 @@ import { getPolicyNamesForRules } from "@rebasepro/utils";
  * Rebase's enforcement model is unified: authenticated (user-context) requests
  * run under the restricted `rebase_user` role, so Postgres RLS binds *every*
  * statement — reads and writes. A collection's `securityRules` are the whole
- * authorization model. The server context (auth flows, migrations,
- * `dataAsAdmin`) runs as the owner and bypasses RLS.
+ * authorization model. The server context (auth flows, migrations, raw
+ * `rebase.sql`) runs as the owner and bypasses RLS.
+ *
+ * `rebase.dataAsAdmin` is **not** in that set, despite the name: it is scoped as
+ * `{ uid: "service", roles: ["admin"] }`, so it runs as `rebase_user` like any
+ * other caller and clears the baseline below through the *admin* arm, not the
+ * server arm. Which is why `disableDefaultPolicies` plus a lone
+ * `policy.serverContext()` rule locks it out too.
  *
  * Because RLS default-denies, every collection is **locked by default**: with
  * no rules, only the server context and admins can touch it. The generator

package/src/util/builders.ts

@@ -14,14 +14,14 @@ import {
 // ── defineCollection ─────────────────────────────────────────────────────
 // A smarter builder that uses `const` type-parameter inference (TS 5.0+)
 // to capture literal property types automatically. This gives you
-// autocomplete on `titleProperty`, `sort`, `propertiesOrder`, `fixedFilter`,
+// autocomplete on `display.title`, `sort`, `propertiesOrder`, `fixedFilter`,
 // callbacks, etc. — without writing `as const` or passing manual generics.
 
 /**
  * Define a PostgreSQL-backed collection with full type inference.
  *
  * The `const P` generic captures literal property types from your
- * `properties` object, which enables autocomplete on `titleProperty`,
+ * `properties` object, which enables autocomplete on `display.title`,
  * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
  *
  * @example
@@ -34,7 +34,7 @@ import {
  *         name: { name: "Name", type: "string", validation: { required: true } },
  *         price: { name: "Price", type: "number" },
  *     },
- *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     display: { title: "name" },  // ✅ autocomplete: "name" | "price"
  *     sort: ["price", "asc"], // ✅ autocomplete on first element
  * });
  * ```

package/src/util/collections.ts

@@ -83,7 +83,23 @@ export function sortProperties<M extends Record<string, unknown>>(properties: Pr
     }
 }
 
-
+/**
+ * A copy of `collections` ordered by slug.
+ *
+ * Every generator that turns collections into a file is order-dependent, and
+ * every one of them is compared against its own output — `rebase doctor`
+ * regenerates in memory and diffs, `generate-sdk && git diff --exit-code` gates
+ * CI. While only the *writers* sorted, a project whose `readdirSync` order
+ * differed from its slug order was reported permanently out of date, and the
+ * fix the message printed rewrote the file in the order it was already in. The
+ * generators sort themselves now, so no caller can get this wrong.
+ *
+ * A slug-less collection is left to the generator's own validation, which names
+ * the offending collection; sorting must not throw first.
+ */
+export function sortCollectionsBySlug<C extends { slug?: string }>(collections: readonly C[]): C[] {
+    return [...collections].sort((a, b) => (a.slug ?? "").localeCompare(b.slug ?? ""));
+}
 
 export function getPrimaryKeys<M extends Record<string, unknown>>(collection: CollectionConfig<M>): Extract<keyof M, string>[] {
     const properties = collection.properties;

package/src/util/conditions.ts

@@ -3,8 +3,8 @@ import {
     ArrayProperty,
     AuthState,
     ConditionContext,
+    ConditionRule,
     EnumValueConfig,
-    JsonLogicRule,
     NumberProperty,
     PropertyConditions,
     Property,
@@ -66,9 +66,14 @@ export function registerConditionOperations(): void {
 }
 
 /**
- * Evaluate a JSON Logic rule against the given context.
+ * Evaluate a condition against the given context.
+ *
+ * A condition may be stated as a literal instead of a rule — `hidden: true`
+ * rather than `hidden: { "==": [1, 1] }` — and a literal is already its own
+ * answer, so it is returned rather than handed to the evaluator.
  */
-export function evaluateCondition(rule: JsonLogicRule, context: ConditionContext): unknown {
+export function evaluateCondition(rule: ConditionRule, context: ConditionContext): unknown {
+    if (typeof rule === "boolean") return rule;
     // Ensure operations are registered
     registerConditionOperations();
     return jsonLogic.apply(rule, context);

package/src/util/entities.ts

@@ -143,10 +143,24 @@ export function getRelationFrom<M extends Record<string, unknown>>(entity: Entit
  * have `id` and `path` fields — these are relation-shaped objects from
  * edge cases in the data pipeline (REST fallback, stale cache, custom data source).
  *
+ * When `targetPath` is given, also accepts a bare id. A relation column is a
+ * foreign key, and the REST layer returns it as the scalar it is; only some
+ * fetch paths hydrate it into an object. Which form a caller sees therefore
+ * depends on how the row was loaded, and a caller that only accepted objects
+ * reported half of its own data as a type error. The declared target is the
+ * missing half: with it, an id is a relation that has not been fetched yet.
+ *
  * Returns null if the value cannot be coerced.
  */
-export function normalizeToEntityRelation(value: unknown, propertyType?: string): EntityRelation | null {
+export function normalizeToEntityRelation(value: unknown, propertyType?: string, targetPath?: string): EntityRelation | null {
     if (value instanceof EntityRelation) return value;
+
+    if (targetPath && (typeof value === "string" || typeof value === "number")) {
+        // An empty string is an unset foreign key, not row "".
+        if (value === "") return null;
+        return new EntityRelation(value, targetPath);
+    }
+
     if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 
     const obj = value as Record<string, unknown>;

package/src/util/index.ts

@@ -18,3 +18,4 @@ export * from "./junction-policies";
 export * from "./conditions";
 export * from "./pg-column-to-property";
 export * from "./string-column-length";
+export * from "./internal-tables";

package/src/util/internal-tables.ts

@@ -0,0 +1,154 @@
+/**
+ * The tables Rebase creates for its own bookkeeping, and the SQL that keeps the
+ * end-user role away from them.
+ *
+ * ## Why this exists
+ *
+ * Authenticated requests run as {@link REBASE_USER_ROLE}, and the boot-time role
+ * provisioning grants that role `SELECT, INSERT, UPDATE, DELETE` on every table
+ * in the schemas a project uses — including `rebase`, because a project's own
+ * collections are allowed to live there (the scaffold puts `users` there). It
+ * also sets `ALTER DEFAULT PRIVILEGES`, so a table created *later* by the
+ * migrating role inherits the same grant.
+ *
+ * Every framework-internal table is created later: auth's tables come up during
+ * `initializeAuth`, `api_keys` during route mounting, `cron_logs` when the first
+ * job registers, `idempotency_keys` on the first request that carries a key. So
+ * they all inherited full DML for the end-user role — and none of them enables
+ * row-level security, because none of them is a collection with
+ * `securityRules`. Measured on a freshly provisioned database, `SET ROLE
+ * rebase_user` could read `rebase.refresh_tokens` (session token hashes),
+ * `rebase.mfa_factors` (`secret_encrypted`), `rebase.recovery_codes`, and
+ * `rebase.api_keys` (including its `admin` flag), and insert into
+ * `rebase.app_config`.
+ *
+ * Nothing routes a user-context query at those tables today, so this was not
+ * reachable over the API. That is the wrong thing to depend on: the documented
+ * model is that RLS is the authorization boundary, and these tables sat outside
+ * it. The boundary is now a privilege boundary instead — the role simply cannot
+ * address them.
+ *
+ * ## Why REVOKE rather than ENABLE ROW LEVEL SECURITY
+ *
+ * RLS with no policy denies every row, which is the same outcome, but it is the
+ * *weaker* statement: it leaves the grant in place, so a later policy — or a
+ * `FORCE` flag cleared by some future migration — reopens the table. There is no
+ * row of `refresh_tokens` any end user should ever reach, so the honest encoding
+ * is "this role has no privilege here at all". It also keeps the owner
+ * connection (which auth actually runs on) completely unaffected.
+ *
+ * ## Keeping it true
+ *
+ * `packages/rls-check` scans the `rebase` schema — it used to skip it as a
+ * "platform" schema — and its `rls-disabled` check fires on exactly the
+ * condition this module removes: RLS off *and* a DML grant to a reachable role.
+ * So a table added here without a revoke is caught by `pnpm rls:check`, not by
+ * someone re-reading this file.
+ */
+
+/**
+ * The Postgres role authenticated requests run as.
+ *
+ * Defined here rather than in the Postgres driver because both the driver (which
+ * provisions the role) and this module (which revokes on its behalf) need it,
+ * and a second spelling of a role name is a silent no-op waiting to happen.
+ */
+export const REBASE_USER_ROLE = "rebase_user";
+
+/**
+ * Framework-internal table names, unqualified.
+ *
+ * Deliberately NOT including `users`: the auth user table is also a collection,
+ * with `securityRules`, RLS enabled and policies applied. Users read their own
+ * row through it — revoking there would break sign-in.
+ *
+ * `atlas_schema_revisions` is Atlas's migration ledger, which lands in `rebase`
+ * because `db migrate apply` passes `--revisions-schema rebase`.
+ */
+export const REBASE_INTERNAL_TABLES: readonly string[] = [
+    // auth
+    "user_identities",
+    "refresh_tokens",
+    "password_reset_tokens",
+    "magic_link_tokens",
+    "mfa_factors",
+    "mfa_challenges",
+    "recovery_codes",
+    "app_config",
+    "schema_meta",
+    // platform services
+    "api_keys",
+    "cron_logs",
+    "cron_claims",
+    "idempotency_keys",
+    "entity_history",
+    "branches",
+    // realtime channels — authorization for these lives in the channel rules the
+    // server evaluates before it reads or writes, never in a row policy
+    "channel_messages",
+    "channel_cursors",
+    "channel_presence",
+    // migration bookkeeping
+    "atlas_schema_revisions"
+];
+
+/** Postgres identifiers this module is willing to interpolate. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * A single statement that takes every privilege on `schema.table` away from the
+ * end-user role.
+ *
+ * Wrapped in a `DO` block guarded on `pg_roles` for two reasons, both of which
+ * happen in practice:
+ *
+ *  - the role does not exist when the connection is unprivileged (Rebase then
+ *    relies on native RLS rather than a role switch), and a bare `REVOKE` on a
+ *    missing role is an error, not a no-op;
+ *  - the table may not exist yet — `cron_logs` never appears in a project with
+ *    no cron jobs — and `to_regclass` returning NULL has to be tolerated too.
+ *
+ * One command, so it is safe on handles that speak the extended query protocol
+ * and reject multi-statement strings.
+ */
+export function revokeInternalTableSql(schema: string, table: string): string {
+    if (!SAFE_IDENTIFIER.test(schema)) {
+        throw new Error(`Refusing to build SQL with an unsafe schema name: ${JSON.stringify(schema)}`);
+    }
+    if (!SAFE_IDENTIFIER.test(table)) {
+        throw new Error(`Refusing to build SQL with an unsafe table name: ${JSON.stringify(table)}`);
+    }
+    const qualified = `"${schema}"."${table}"`;
+    return `
+        DO $rebase_revoke$
+        BEGIN
+            IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}')
+               AND to_regclass('${qualified}') IS NOT NULL THEN
+                EXECUTE 'REVOKE ALL ON ${qualified} FROM ${REBASE_USER_ROLE}';
+            END IF;
+        END
+        $rebase_revoke$;
+    `.trim();
+}
+
+/**
+ * Revoke on every internal table in `schema`, one statement at a time.
+ *
+ * Best-effort per table: a connection that does not own one of them (a
+ * pre-provisioned database, a platform-managed ledger) cannot revoke on it, and
+ * that must not take down a boot. The caller decides how loud to be — `onError`
+ * exists so the driver can warn without this module importing a logger.
+ */
+export async function revokeInternalTableAccess(
+    execute: (sql: string) => Promise<unknown>,
+    schema: string,
+    options?: { tables?: readonly string[]; onError?: (table: string, error: unknown) => void }
+): Promise<void> {
+    for (const table of options?.tables ?? REBASE_INTERNAL_TABLES) {
+        try {
+            await execute(revokeInternalTableSql(schema, table));
+        } catch (error) {
+            options?.onError?.(table, error);
+        }
+    }
+}

package/src/util/permissions.test.ts

@@ -1,4 +1,4 @@
-import { canCreateEntity, canEditEntity, canDeleteEntity, canReadCollection } from "./permissions";
+import { canCreateEntity, canEditEntity, canDeleteEntity, canReadCollection, checkOperation } from "./permissions";
 import { AuthState, CollectionConfig, Entity, User, SecurityRule } from "@rebasepro/types";
 
 describe("Permissions Evaluator", () => {
@@ -823,7 +823,28 @@ roles: ["author"],
 using: "status = 'draft'" }
             ]);
             expect(canEditEntity(collection, unauthenticatedController, "test", draftOwned)).toBe(true);
-            expect(canEditEntity(restrictedCollection, unauthenticatedController, "test", draftOwned)).toBe(false);
+
+            // `true`, not `false`, and the change is in `evaluatePolicy` rather
+            // than here. The ownerField rule compares `user_id` (null on this
+            // row) against the uid, and a comparison against NULL is now
+            // "unknown" — SQL's answer — where it used to be a flat `false`.
+            // `canEditEntity` gates optimistically (`onUnknown: "allow"`), so
+            // an undecided rule shows the button.
+            //
+            // The old `false` matched Postgres here by accident and diverged
+            // from it under negation; see the note on the null branch in
+            // `evaluatePolicy`. What this now exposes is a separate, real gap:
+            // "the client cannot evaluate this" (raw SQL, a membership
+            // subquery) and "SQL would answer NULL, so the row is definitively
+            // not granted" are both spelled "unknown", and only the first
+            // deserves optimism. Recorded in docs/verification.md.
+            expect(canEditEntity(restrictedCollection, unauthenticatedController, "test", draftOwned)).toBe(true);
+
+            // Fail-closed callers — every enforcement path — are unaffected:
+            // an undecided rule denies.
+            expect(checkOperation(
+                restrictedCollection, unauthenticatedController, draftOwned, "update", { onUnknown: "deny" }
+            )).toBe(false);
         });
 
         test("58. Missing authController ('blankAuth') handled gracefully", () => {

package/src/util/permissions.ts

@@ -1,4 +1,4 @@
-import { AuthState, Entity, CollectionConfig, getDataSourceCapabilities, SecurityOperation, SecurityRule, User } from "@rebasepro/types";
+import { AuthState, Entity, CollectionConfig, SecurityOperation, SecurityRule, User } from "@rebasepro/types";
 import { securityRuleToConditions } from "./policy/securityRuleToConditions";
 import { evaluatePolicy, PolicyEvalContext, TriState } from "./policy/evaluatePolicy";
 
@@ -26,8 +26,28 @@ export type AuthContext<USER extends User = User> = AuthState<USER>;
  */
 export type UnknownResolution = "allow" | "deny";
 
+/**
+ * Which half of a rule to evaluate.
+ *
+ * Postgres evaluates `USING` against the row as it is *now* and `WITH CHECK`
+ * against the row as it *will be*, both inside the transaction. A driver
+ * enforcing an update in-process has two different rows in hand and therefore
+ * needs to ask the two questions separately — asking one question about one row
+ * either checks the new values against the old row's ownership or the reverse.
+ *
+ * - `"both"` (default): what a single-row decision means (`USING ∧ WITH CHECK`).
+ * - `"using"`: the read/target clause only — ask it about the stored row.
+ * - `"withCheck"`: the write clause only — ask it about the row being written.
+ *
+ * Rule *selection* is unaffected: the target operation still decides which rules
+ * apply, so `"using"` on an `update` evaluates the update rules' USING clause,
+ * not the delete rules'.
+ */
+export type PolicyClauses = "both" | "using" | "withCheck";
+
 export interface CheckOperationOptions {
     onUnknown?: UnknownResolution;
+    clauses?: PolicyClauses;
 }
 
 /** Combine clause results with AND under three-valued (Kleene) logic. */
@@ -57,12 +77,17 @@ function ruleApplies(rule: SecurityRule, targetOperation: SecurityOperation): bo
  * in that case. USING applies to SELECT/UPDATE/DELETE; WITH CHECK to
  * INSERT/UPDATE; both must pass for UPDATE.
  */
-function evaluateRuleForOperation(rule: SecurityRule, ctx: PolicyEvalContext, targetOperation: SecurityOperation): TriState {
+function evaluateRuleForOperation(
+    rule: SecurityRule,
+    ctx: PolicyEvalContext,
+    targetOperation: SecurityOperation,
+    clauses: PolicyClauses = "both"
+): TriState {
     const { usingExpr, withCheckExpr } = securityRuleToConditions(rule);
     const clause = (expr: typeof usingExpr): TriState => expr === null ? false : evaluatePolicy(expr, ctx);
 
-    const needsUsing = targetOperation !== "insert";
-    const needsWithCheck = targetOperation === "insert" || targetOperation === "update";
+    const needsUsing = targetOperation !== "insert" && clauses !== "withCheck";
+    const needsWithCheck = (targetOperation === "insert" || targetOperation === "update") && clauses !== "using";
 
     const results: TriState[] = [];
     if (needsUsing) results.push(clause(usingExpr));
@@ -81,9 +106,20 @@ function resolveTriState(value: TriState, onUnknown: UnknownResolution): boolean
  * the same model compiled to Postgres RLS DDL, so the decision matches database
  * enforcement for every non-raw rule.
  *
+ * Engine-independent by design. `securityRules` are a declaration about the
+ * data, not about Postgres: the engine decides *who* enforces them (Postgres
+ * compiles them to RLS DDL, a document driver applies them in-process), never
+ * *whether* they hold. Gating this function on the engine's `supportsRLS`
+ * capability is what made every `{ onUnknown: "deny" }` call site in the Mongo
+ * driver return `true` before it evaluated anything — and it did so only for
+ * collections that spelled their engine out, so declaring `engine: "mongodb"`
+ * was what switched authorization off.
+ *
  * @param options.onUnknown how to treat rules that cannot be decided
  *   client-side (raw SQL, or row predicates with no row). Defaults to `"allow"`
  *   for optimistic UI gating; enforcement callers should pass `"deny"`.
+ * @param options.clauses which half of each rule to evaluate. See
+ *   {@link PolicyClauses}; defaults to `"both"`.
  */
 export function checkOperation<M extends Record<string, unknown>, USER extends User>(
     collection: CollectionConfig<M>,
@@ -93,7 +129,8 @@ export function checkOperation<M extends Record<string, unknown>, USER extends U
     options?: CheckOperationOptions
 ): boolean {
     const onUnknown = options?.onUnknown ?? "allow";
-    const securityRules = getDataSourceCapabilities(collection.engine).supportsRLS ? collection.securityRules : undefined;
+    const clauses = options?.clauses ?? "both";
+    const securityRules = collection.securityRules;
     if (!securityRules || securityRules.length === 0) {
         return true;
     }
@@ -113,7 +150,7 @@ export function checkOperation<M extends Record<string, unknown>, USER extends U
 
     for (const rule of applicableRules) {
         const mode = rule.mode || "permissive";
-        const passed = resolveTriState(evaluateRuleForOperation(rule, ctx, targetOperation), onUnknown);
+        const passed = resolveTriState(evaluateRuleForOperation(rule, ctx, targetOperation, clauses), onUnknown);
 
         if (mode === "restrictive") {
             if (!passed) {

package/src/util/policy/evaluatePolicy.ts

@@ -139,8 +139,30 @@ function evaluateCompare(
     const b = r.value;
 
     if (a === null || b === null) {
-        if (op === "eq") return false;
-        if (op === "neq") return true;
+        // SQL answers NULL for *every* comparison against NULL, and a policy
+        // that answers NULL does not grant the row. So the only question here
+        // is which JavaScript answer reproduces that outcome.
+        //
+        // This used to answer `false` for `eq` and `true` for `neq`, which is
+        // JavaScript's two-valued reading of a three-valued question.
+        //
+        // `neq` was a grant the database does not give:
+        // `owner_id != rebase.uid()` on a row whose `owner_id` is NULL read as
+        // *permitted* in the admin panel and was refused by Postgres — on every
+        // row where the column is null, which for a nullable column is usually
+        // most of them.
+        //
+        // `false` for `eq` looked safe, because false denies and NULL denies.
+        // It is not, because it does not survive negation: `not(a = NULL)`
+        // became `true` while `NOT NULL` stays NULL, so the same grant reappears
+        // one operator up. A local answer that is only right in a positive
+        // position is not right — it just moves.
+        //
+        // "unknown" is what SQL actually says, it composes correctly through
+        // Kleene negation, and enforcement callers already resolve it
+        // fail-closed. Both were found by the exhaustive Postgres differential
+        // in `policy-agreement-exhaustive.test.ts`, the second only after the
+        // first was fixed.
         return "unknown";
     }