@rebasepro/server-postgres 0.21.2-canary.g1ea48be → 0.23.0

package/dist/services/PersistService.d.ts

@@ -1,8 +1,37 @@
+import { Properties } from "@rebasepro/types";
 import { RelationService } from "./RelationService.js";
+import { type ReadCallContextProvider } from "./read-scope.js";
 import { RelationWriteService } from "./RelationWriteService.js";
 import { FetchService } from "./FetchService.js";
 import { DrizzleClient } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
+/**
+ * The top-level properties whose value is stamped once, when the row is
+ * created: `on_create` dates and `user_on_create` identities.
+ *
+ * What they hold is a fact about the row's creation, so a write to a row that
+ * already exists has nothing to say about them — an update, and the
+ * conflict-update of an upsert that met a stored row. Top level only: a stamp
+ * nested inside a `map` is part of that map's value, not a column a write can
+ * leave out.
+ */
+export declare function createStampKeys(properties: Properties | undefined): string[];
+/** How {@link PersistService.save} writes a row that may already be stored. */
+export interface PersistSaveOptions {
+    /** INSERT ... ON CONFLICT DO UPDATE. See `SaveProps.upsert`. */
+    upsert?: boolean;
+    /** The conflict target, instead of the primary key. See `SaveProps.onConflict`. */
+    onConflict?: readonly string[];
+    /**
+     * Keys of `values` that belong to the INSERT alone: what the create
+     * pipeline filled in rather than what the caller wrote — a declared
+     * `defaultValue`, a tenant stamp. When an upsert's INSERT meets a stored
+     * row, those columns keep the value they have. The create-time stamps
+     * (`on_create`, `user_on_create`) are left out of the conflict-update
+     * without being named here.
+     */
+    insertOnlyKeys?: readonly string[];
+}
 /**
  * Service for handling all row write operations.
  * Handles saving, deleting, and updating rows.
@@ -10,12 +39,26 @@ import { PostgresCollectionRegistry } from "../collections/PostgresCollectionReg
 export declare class PersistService {
     private db;
     private registry;
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    private callContext?;
     /** 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);
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry, 
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    callContext?: ReadCallContextProvider | undefined);
     /**
      * Set the columns of one many-to-many link, without touching the membership.
      *
@@ -67,6 +110,10 @@ export declare class PersistService {
      * the row already exists — which is what a re-runnable import needs. The
      * conflict is matched on the primary key unless `options.onConflict` names
      * other columns; see {@link SaveProps.onConflict} for why that matters.
+     * When the INSERT meets a stored row, the conflict-update sets what the
+     * caller wrote and nothing the create alone decides — see
+     * {@link PersistSaveOptions.insertOnlyKeys} — and only on a row the caller's
+     * `beforeQuery` scope reaches.
      *
      * `values` may carry field operations (`{ views: { $inc: 1 } }`). They are
      * split out here rather than at the REST boundary because every request
@@ -74,10 +121,14 @@ export declare class PersistService {
      * one method, and a rule applied at one door is a rule the other doors do
      * not have. What they compile to is `field-op-sql.ts`.
      */
-    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
-        upsert?: boolean;
-        onConflict?: readonly string[];
-    }): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: PersistSaveOptions): Promise<Record<string, unknown>>;
+    /**
+     * The caller's `beforeQuery` scope over this table, as one condition: what
+     * a stored row must satisfy for a write that meets it to change it. The
+     * same scope the update gate and the single get apply; `undefined` when the
+     * collection declares no hook.
+     */
+    private writeScope;
     /**
      * Get the RelationService instance for external use
      */

package/dist/services/RelationService.d.ts

@@ -4,6 +4,7 @@ import { DrizzleClient } from "../interfaces.js";
 import { CollectionConfig, FilterValues, OrderByTuple, ResolvedRelation, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import type { NestedPathHop } from "./nested-path.js";
+import { type ReadCallContextProvider } from "./read-scope.js";
 /**
  * Typed wrapper for Drizzle dynamic query innerJoin.
  * Drizzle's `$dynamic()` queries lose the `innerJoin` method from
@@ -44,7 +45,47 @@ export interface RelatedRow<M extends Record<string, unknown> = Record<string, u
 export declare class RelationService {
     private db;
     private registry;
-    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    private callContext?;
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry, 
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    callContext?: ReadCallContextProvider | undefined);
+    /**
+     * The **target** collection's `beforeQuery` narrowing, for rows reached
+     * through a relation.
+     *
+     * The target's, not the parent's, because these are the target's rows: a
+     * scope on `comments` has to hold whether they are listed at
+     * `/comments` or loaded as `post.comments`. Without this an `include` is a
+     * way around every row filter a collection declares — the exact hole
+     * `stripUnreadable` was once missing from the relation-ref branch.
+     *
+     * Folded into the `narrow` condition the loaders already thread through
+     * every relation kind, so a `via` join, a junction, a foreign key and the
+     * dynamic relation builder all apply it or none of them do.
+     */
+    private narrowTargetRead;
+    /**
+     * The target rows a caller may see through `relation`: the target's
+     * `beforeQuery` scope and its soft delete, as one condition on the target
+     * table, or `undefined` when neither applies.
+     *
+     * What every loader here narrows a read by, exposed for the membership
+     * writes. A write that diffs a new link set against "what is linked now"
+     * has to diff against what the caller could have read — otherwise saving
+     * back the list they were shown unlinks every row they were not.
+     */
+    visibleTargetCondition(parentCollection: CollectionConfig, relation: ResolvedRelation, parentId?: string | number): Promise<SQL | undefined>;
     /**
      * One target row, as the {@link RelatedRow} everything here returns.
      *

package/dist/services/RelationWriteService.d.ts

@@ -2,6 +2,7 @@ import { CollectionConfig, Properties, ResolvedManyToMany, ResolvedRelation, Res
 import { DrizzleClient } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import type { NestedPathHop } from "./nested-path.js";
+import type { ReadCallContextProvider } from "./read-scope.js";
 /**
  * A `_pivot` as the junction table's columns.
  *
@@ -28,8 +29,22 @@ export declare function serializePivot(pivot: Record<string, unknown>, payload:
 export declare class RelationWriteService {
     private db;
     private registry;
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    private callContext?;
     private reads;
-    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry, 
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    callContext?: ReadCallContextProvider | undefined);
     /**
      * Remove the junction row linking a parent to `targetId`, leaving the target
      * row itself alone.
@@ -49,6 +64,12 @@ export declare class RelationWriteService {
      * lost update the membership diff exists to avoid.
      */
     updateRelationPivot(tx: DrizzleClient, hop: NestedPathHop, targetId: string | number, pivot: Record<string, unknown>): Promise<void>;
+    /**
+     * The target rows of `relation` this caller can see, for a junction diff —
+     * or `undefined` when that is all of them. See
+     * {@link RelationService.visibleTargetCondition}.
+     */
+    private visibleTargets;
     /** A collection's id, parsed to the type its primary key column holds. */
     private parsedId;
     /** The same, for the membership list a to-many write names. */

package/dist/services/cdc/CdcListener.d.ts

@@ -31,7 +31,12 @@ export declare function parseCdcPayload(payload: string): CdcChangeEvent | null;
  */
 export declare class CdcListener {
     private readonly listener;
-    constructor(connectionString: string, onEvent: (event: CdcChangeEvent) => void | Promise<void>);
+    /**
+     * @param onReconnect Called when the connection is listening again after a
+     *        drop. Every change committed in the gap was notified to nobody, so
+     *        this is where subscribers are told to look again.
+     */
+    constructor(connectionString: string, onEvent: (event: CdcChangeEvent) => void | Promise<void>, onReconnect?: () => void);
     /**
      * Connect and begin listening. Idempotent.
      *

package/dist/services/collection-helpers.d.ts

@@ -1,4 +1,5 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
+import { SQL } from "drizzle-orm";
 import { CollectionConfig, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import { ApiError } from "@rebasepro/server";
@@ -34,6 +35,16 @@ export declare function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta;
  * statement into an unrelated-looking `25P02`.
  */
 export declare function idCanAddressTable(id: string | number, table: PgTable, idInfoArray: PrimaryKeyInfo[]): boolean;
+/**
+ * The condition that names one row: every key column equal to its part of the
+ * address.
+ *
+ * Every key column, not the first. A composite-key read that matched only the
+ * leading column answered `p1:::bob` with whichever `p1` row Postgres reached
+ * first, and a delete then judged that row's `beforeDelete` while deleting bob —
+ * the writes have always matched the whole key, so the reads must too.
+ */
+export declare function rowIdentityCondition(table: PgTable, idInfoArray: PrimaryKeyInfo[], id: string | number, collectionPath: string): SQL;
 export declare function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig;
 /**
  * Reject a write naming something that is not a column of the table.

package/dist/services/dataService.d.ts

@@ -1,8 +1,9 @@
 import { FilterValues, IncludeSpec, LogicalCondition, OrderByTuple } from "@rebasepro/types";
 import type { VectorSearchParams } from "@rebasepro/types";
 import { FetchService } from "./FetchService.js";
+import type { ReadCallContextProvider } from "./read-scope.js";
 import type { WithDeleted } from "./soft-delete.js";
-import { PersistService } from "./PersistService.js";
+import { PersistService, type PersistSaveOptions } from "./PersistService.js";
 import { RelationService } from "./RelationService.js";
 import { DataRepository, DrizzleClient } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
@@ -25,9 +26,23 @@ export * from "../interfaces.js";
 export declare class DataService implements DataRepository {
     private db;
     private registry;
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    private callContext?;
     private fetchService;
     private persistService;
-    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry, 
+    /**
+     * How this service's reads reach the identity their `beforeQuery` hooks
+     * run as. Passed by the driver that constructed it; absent only in a
+     * test, where a collection declaring the hook is refused rather than
+     * read unnarrowed. See `read-scope.ts`.
+     */
+    callContext?: ReadCallContextProvider | undefined);
     /**
      * Fetch a single row by ID
      */
@@ -37,21 +52,7 @@ export declare class DataService implements DataRepository {
     /**
      * Fetch a collection of rows with optional filtering, ordering, and pagination
      */
-    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 | OrderByTuple[];
-        order?: "desc" | "asc";
-        limit?: number;
-        offset?: number;
-        startAfter?: Record<string, unknown>;
-        searchString?: string;
-        databaseId?: string;
-        vectorSearch?: VectorSearchParams;
-        /** See `FetchCollectionProps.withDeleted`. */
-        withDeleted?: WithDeleted;
-    }): Promise<Record<string, unknown>[]>;
+    fetchCollection<M extends Record<string, unknown>>(collectionPath: string, options?: Parameters<FetchService["fetchCollection"]>[1]): Promise<Record<string, unknown>[]>;
     /**
      * The REST read pipeline: flat rows, with exactly the relations `include`
      * names — see {@link FetchService.fetchCollectionForRest}.
@@ -117,10 +118,7 @@ export declare class DataService implements DataRepository {
     /**
      * Save an row (create or update)
      */
-    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
-        upsert?: boolean;
-        onConflict?: readonly string[];
-    }): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: PersistSaveOptions): Promise<Record<string, unknown>>;
     /**
      * Delete an row by ID
      */

package/dist/services/field-op-sql.d.ts

@@ -1,6 +1,9 @@
 import { SQL } from "drizzle-orm";
 import { PgTable } from "drizzle-orm/pg-core";
+import { ApiError } from "@rebasepro/server";
 import type { ParsedFieldOp } from "@rebasepro/server";
+import type { Properties } from "@rebasepro/types";
+import type { DrizzleClient } from "../interfaces.js";
 /**
  * The expression one operation compiles to, or a 400 saying why it cannot.
  *
@@ -14,3 +17,71 @@ export declare function compileFieldOp(table: PgTable, field: string, op: Parsed
 export declare function compileFieldOps(table: PgTable, fieldOps: Record<string, ParsedFieldOp>, context: {
     collectionPath: string;
 }): Record<string, SQL>;
+/**
+ * One declared bound an operation's result has to stay inside.
+ *
+ * `code` and `message` are what a plain value breaking the same rule reports
+ * (see `write-validation.ts`), so `{ stock: { $inc: -1000 } }` and
+ * `{ stock: -5 }` are refused with one answer.
+ */
+export interface FieldOpBound {
+    /** The property key. */
+    field: string;
+    code: "min" | "max" | "more_than" | "less_than" | "positive" | "negative" | "min_items" | "max_items";
+    /**
+     * TRUE when the value the operation writes keeps to the rule, evaluated
+     * against the row the statement is changing. Never NULL: an unset column
+     * reads as `0` or empty wherever the operation itself reads it so, and an
+     * array the operation leaves unset has no size for a bound to judge.
+     */
+    holds: SQL;
+    message: string;
+}
+/**
+ * The declared bounds each operation's *result* must satisfy, as conditions
+ * for the UPDATE that applies it.
+ *
+ * `{ stock: -5 }` on `stock: { validation: { min: 0 } }` is refused before the
+ * statement is built, because the value is in the request. What
+ * `{ stock: { $inc: -1000 } }` produces depends on the stored row, which the
+ * request never sees, so it can only be judged where the row is: in the WHERE
+ * of the UPDATE that does the arithmetic, over the row that statement holds
+ * locked. Reading the row first and judging the sum would reopen the race the
+ * operation exists to close — two decrements of a stock of 1 would each read
+ * `1`, each find room for one more, and both go through. A condition on the
+ * UPDATE cannot be raced that way: under READ COMMITTED an UPDATE blocked on a
+ * concurrent writer re-evaluates its WHERE against the row that writer
+ * committed, so the second decrement sees `0 - 1` and matches nothing.
+ *
+ * The bound is the whole declared range, applied to the result the way it
+ * applies to a value: a number's `min`, `max`, `moreThan`, `lessThan`,
+ * `positive` and `negative`, an array's `min` and `max` items. `integer` is not
+ * here: a whole increment of a whole number stays whole, and the request
+ * already refuses a fractional one. `$merge` has no bounds to hold.
+ */
+export declare function compileFieldOpBounds(table: PgTable, fieldOps: Record<string, ParsedFieldOp>, properties: Properties, context: {
+    collectionPath: string;
+}): FieldOpBound[];
+/**
+ * Which bounds the row, as it now stands, would break — for an UPDATE that
+ * carried bounds and matched nothing.
+ *
+ * A guarded UPDATE matching zero rows means one of three things: the row is not
+ * there for this caller (404), a row-level security policy refused the write
+ * (403), or the operation's result broke a bound (400). The first two are
+ * `explainZeroRowWrite`'s; this answers the third, by evaluating each bound
+ * against the row over the same handle and the same key conditions. An empty
+ * answer — the row is not visible, or every bound holds — leaves the decision to
+ * `explainZeroRowWrite`.
+ *
+ * It is a second statement, so the row can change in between. A row deleted in
+ * between is a 404 here as it would have been anyway. A row changed so that the
+ * operation now fits reads as "every bound holds" and falls through to the
+ * row-level-security answer; the write was refused either way, and the
+ * refusal is never turned into a write.
+ *
+ * Only booleans come back — whether each bound holds — never the stored value.
+ */
+export declare function brokenFieldOpBounds(handle: DrizzleClient, table: PgTable, conditions: SQL[], bounds: FieldOpBound[]): Promise<FieldOpBound[]>;
+/** The 400 a write gets when an operation's result breaks a bound. */
+export declare function fieldOpBoundsError(collectionSlug: string, broken: FieldOpBound[]): ApiError;

package/dist/services/junction-writes.d.ts

@@ -1,3 +1,4 @@
+import { type SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import type { Properties, ResolvedVia } from "@rebasepro/types";
 import { DrizzleClient } from "../interfaces.js";
@@ -49,6 +50,19 @@ export interface JunctionLinkWrite {
     /** Payload values keyed by property key, already serialized for the driver. */
     pivot?: Record<string, unknown>;
 }
+/**
+ * The target rows a membership write can see, when that is not all of them —
+ * the target's `beforeQuery` scope and its soft delete.
+ *
+ * The diff reads "what is linked now" through it, so a link to a row the caller
+ * was never shown is in neither list and is left alone rather than unlinked.
+ */
+export interface VisibleTargets {
+    table: PgTable;
+    /** The target column the junction's `targetColumn` holds values of. */
+    idColumn: AnyPgColumn;
+    condition: SQL;
+}
 /** The junction a `manyToMany` names outright. */
 export declare function bindThroughJunction(registry: PostgresCollectionRegistry, through: {
     table: string;
@@ -91,8 +105,10 @@ export declare function removeJunctionLink(tx: DrizzleClient, binding: JunctionB
  *    the form runs under RLS, so a user who may edit the parent but cannot see
  *    some of the linked rows gets a shorter list — and writing it back deleted
  *    the links they were never shown. The select that drives the diff runs in
- *    this same transaction under the same policies, so a link the caller cannot
- *    read is in neither list and survives the save.
+ *    this same transaction under the same policies, and through
+ *    `visibleTargets` — the target's `beforeQuery` scope and soft delete, which
+ *    RLS knows nothing of — so a link the caller cannot read is in neither list
+ *    and survives the save.
  *  - **Junction payload columns.** A junction carrying its own columns
  *    (`position`, `role`, `created_at`) lost them on every save, because every
  *    row was re-inserted with only the two keys. Untouched links are left alone.
@@ -115,7 +131,7 @@ export declare function removeJunctionLink(tx: DrizzleClient, binding: JunctionB
  * that is what keeps a plain `[1, 2, 3]` membership write from wiping the
  * `role`s off the links it did not mention.
  */
-export declare function applyJunctionMembership(tx: DrizzleClient, binding: JunctionBinding, parentId: unknown, links: JunctionLinkWrite[]): Promise<void>;
+export declare function applyJunctionMembership(tx: DrizzleClient, binding: JunctionBinding, parentId: unknown, links: JunctionLinkWrite[], visibleTargets?: VisibleTargets): Promise<void>;
 /**
  * Set the columns of ONE existing link, without touching the membership.
  *

package/dist/services/pg-notify-listener.d.ts

@@ -23,6 +23,13 @@ export interface PgNotifyListenerOptions {
     logLabel: string;
     /** Delay before a reconnect attempt. */
     reconnectDelayMs?: number;
+    /**
+     * Called once the connection is listening again after a drop — never after
+     * the first connect. Postgres keeps no NOTIFY for a session that is not
+     * listening, so whatever was published while the connection was down is
+     * gone for good; a caller that mirrors state from the channel resyncs here.
+     */
+    onReconnect?: () => void;
 }
 export declare class PgNotifyListener {
     private readonly options;

package/dist/services/read-field-access.d.ts

@@ -0,0 +1,19 @@
+import type { CollectionConfig, FetchCollectionProps } from "@rebasepro/types";
+import type { FieldViewer } from "@rebasepro/common";
+/**
+ * Refuse a read that names a field its caller may not read, for the doors that
+ * take a driver-shaped request rather than a query string: the socket's
+ * `FETCH_COLLECTION`, `COUNT` and `CHECK_UNIQUE_FIELD`, and `subscribe_collection`.
+ * Callers hand it the request itself, not a re-listed copy of some of its keys.
+ *
+ * The row strip keeps a withheld value off the wire; this is the other half, and
+ * without it the value is still readable one predicate at a time — a `COUNT`
+ * filtered on `passwordHash like '$2b$10$A%'` answers 1 or 0. `GET /api/data`
+ * refuses the same request with `FIELD_NOT_READABLE`, and this is that rule, not
+ * a copy of it: only the request's shape is translated here.
+ *
+ * The shape arrives as whatever JSON the client sent, so it is read defensively.
+ * A malformed `orderBy` or `fields` is not this check's to reject; the entries
+ * that name a field are checked and the rest are left for the driver to refuse.
+ */
+export declare function assertReadRequestReadable(request: Pick<FetchCollectionProps, "filter" | "logical" | "orderBy" | "fields" | "include" | "vectorSearch">, collection: CollectionConfig, viewer: FieldViewer): void;

package/dist/services/read-scope.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `beforeQuery`: the one place a collection callback can change *which* rows a
+ * read asks for.
+ *
+ * `afterRead` runs over rows that have already been fetched, so until this
+ * existed an application developer who needed the read itself narrowed — a
+ * tenant scope, a visibility window, a per-role row filter — had two options:
+ * patch this driver, or `rebase eject`.
+ *
+ * Two properties are load-bearing, and both belong to the *shape* of the thing
+ * rather than to how carefully each call site was written.
+ *
+ * ## It can only narrow
+ *
+ * A hook returns a {@link QueryNarrowing} — a declarative filter, optionally a
+ * logical group — which is AND-ed into the query the caller sent. `AND(q, c)`
+ * is a subset of `q` for every `c`, so there is no `c` a hook can return that
+ * widens a read. The obvious alternative shape, `(query) => query`, can: a
+ * hook that drops a condition on the way through runs the query without it,
+ * and on an RLS data plane a dropped condition returns everything the policies
+ * happen to allow. That is the same reasoning behind
+ * `UnknownFilterFieldsMode` defaulting to `"error"`, and it is why that mode is
+ * **forced** to `"error"` for a hook's own filter here whatever the
+ * process-wide setting is: a scope condition naming a renamed column has to
+ * refuse the request, never be dropped from it.
+ *
+ * ## It cannot be skipped
+ *
+ * The hooks are resolved *by the read path itself*, out of the registry that
+ * read already holds — not handed to it by a caller who might forget. So a
+ * read that compiles a WHERE compiles this one too, or it throws.
+ *
+ * The one thing a read path cannot derive is the identity the hook runs as:
+ * `FetchService`, `RelationService` and `DataService` carry no user. That
+ * arrives as a {@link ReadCallContextProvider}, threaded from the driver that
+ * constructed them — the driver is the only object that knows both the caller
+ * and the connection, and it constructs a service per transaction anyway, so
+ * there is exactly one place per instance to pass it.
+ *
+ * Absence is the interesting case, and it fails closed: a service built with no
+ * provider refuses any read of a collection that declares `beforeQuery`, with
+ * a message naming the collection. So a future construction site that forgets
+ * the provider breaks loudly on the first scoped collection instead of quietly
+ * serving every row — which is the failure mode this whole module exists to
+ * rule out. A deployment with no `beforeQuery` anywhere never reaches any of
+ * this: the check is one map lookup and the compiled SQL is byte-identical.
+ *
+ * @module
+ */
+import { SQL } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import type { CollectionConfig, ReadOperation, ReadQuery, RebaseCallContext } from "@rebasepro/types";
+import type { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
+import { type FilterCompilationOptions } from "../utils/drizzle-conditions.js";
+/**
+ * How a read path reaches the context its `beforeQuery` hooks run with.
+ *
+ * A function rather than the context itself, because the driver's transaction
+ * handle and its `data` plane are established *after* it constructs the
+ * services that read through them — and because building a context costs an
+ * object that a collection with no hooks should never pay for.
+ */
+export type ReadCallContextProvider = () => RebaseCallContext;
+/** Whether anything at all would run for this collection. */
+export declare function hasBeforeQuery(registry: PostgresCollectionRegistry | undefined, collection: CollectionConfig | undefined): boolean;
+/**
+ * What a read path is about to compile, in the form a hook is shown it.
+ *
+ * Built by the caller rather than derived here, because only the caller knows
+ * which of its options are part of the query and which are transport — a
+ * `databaseId`, an `include` tree, a `withDeleted` flag are not "which rows".
+ */
+export interface ReadQueryDescription {
+    operation: ReadOperation;
+    query: ReadQuery;
+}
+/** Everything `beforeQueryConditions` needs that is not about this one read. */
+export interface BeforeQueryEnv {
+    registry: PostgresCollectionRegistry | undefined;
+    /**
+     * The context provider the driver handed down. `undefined` means no driver
+     * built this service, which is a refusal rather than a bypass — see the
+     * module comment.
+     */
+    callContext: ReadCallContextProvider | undefined;
+}
+/**
+ * The conditions every `beforeQuery` hook for this collection asks to add.
+ *
+ * Returned as a list rather than pre-combined so a caller pushes them onto the
+ * same `allConditions` array its own filter goes into. Every caller AND-es
+ * that array, which is what makes these additive — the hook is not trusted to
+ * narrow, it is only ever given a way to.
+ */
+export declare function beforeQueryConditions(env: BeforeQueryEnv, collection: CollectionConfig | undefined, path: string, table: PgTable<never>, description: ReadQueryDescription, filterContext: Omit<FilterCompilationOptions, "unknownFields">): Promise<SQL[]>;
+/**
+ * {@link beforeQueryConditions}, pre-combined, for the read paths that hold a
+ * single `SQL` rather than a list of them — a single get, a relation loader.
+ */
+export declare function beforeQueryCondition(env: BeforeQueryEnv, collection: CollectionConfig | undefined, path: string, table: PgTable<never>, description: ReadQueryDescription, filterContext: Omit<FilterCompilationOptions, "unknownFields">): Promise<SQL | undefined>;