@voltro/database 0.27.0 → 0.29.0

package/dist/sql.d.ts

@@ -9,6 +9,49 @@ import { Statement } from '@effect/sql';
 
 export declare const acquireMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
 
+declare interface AggregateColumn<TResult = number | Date | null> {
+    readonly op: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count-distinct' | 'window-row-number' | 'window-rank' | 'window-dense-rank' | 'window-lag' | 'window-lead' | 'window-sum-over' | 'window-avg-over' | 'column';
+    readonly column?: string;
+    readonly alias: string;
+    readonly window?: WindowSpec;
+    /** Used by lag/lead — offset rows (default 1). */
+    readonly offset?: number;
+    /** Phantom — carries the projected/aggregated result type so
+     *  `aggregate<Spec>()` can infer a precise result row. Never set at
+     *  runtime; exists purely for `AggregateColumn<infer T>` inference. */
+    readonly _result?: TResult;
+}
+
+declare interface AndPredicate {
+    readonly and: ReadonlyArray<Predicate>;
+}
+
+/**
+ * Approximate-nearest-neighbour search clause carried on a
+ * {@link QueryDescriptor}. See {@link QueryDescriptor.annClause}.
+ */
+declare interface AnnClause {
+    /** Vector column to search. */
+    readonly column: string;
+    /** Literal query vector (array overload). Mutually exclusive with `queryText`. */
+    readonly queryVector?: ReadonlyArray<number>;
+    /** Raw query string (string overload) — embedded by the runtime before
+     *  compile. Mutually exclusive with `queryVector`. */
+    readonly queryText?: string;
+    /** Distance metric — MUST match the index opclass to accelerate. Default 'cosine'. */
+    readonly distance: VectorDistance;
+    /** Per-query HNSW search effort (pgvector `hnsw.ef_search`). Set by `.efSearch(n)`. */
+    readonly ef?: number;
+    /**
+     * Hybrid-search fusion weight in `[0, 1]`. Set by `hybridSearch(...)`
+     * when both an ANN ranking and an FTS filter are present: `0` = pure
+     * FTS, `1` = pure vector, `0.5` = balanced. The runtime fuses the two
+     * rank signals (Reciprocal-Rank-Fusion) weighted by this. Absent for a
+     * plain `nearestNeighbours(...)` query.
+     */
+    readonly alpha?: number;
+}
+
 declare type AnyMixin = MixinDefinition<Record<string, ColumnDefinition<unknown>>>;
 
 declare type AnyTable = Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>;
@@ -399,6 +442,45 @@ declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType,
      * COSTS is per command — see `serverOnly()` below for the matrix.
      */
     readonly serverOnly?: boolean;
+    /**
+     * Field-level read scopes, set by `.readableBy(...scopes)`. A NON-EMPTY list
+     * of scope strings; the column is stripped from wire OUTPUT for any subject
+     * that holds NONE of them, and present for a subject holding at least ONE.
+     * This is the graded middle of the exposure axis: `.serverOnly()` hides a
+     * column from EVERYONE on the wire, a plain column is visible to everyone,
+     * and `.readableBy('billing:read')` is visible only to callers scoped for it.
+     *
+     * The scope strings are the SAME vocabulary as `guards:` / `ctx.access` — they
+     * are checked against the subject's EFFECTIVE scope set (raw subject scopes ∪
+     * any rbac role-derived scopes), and the `admin:full` bypass sees every
+     * `.readableBy()` column, exactly as it satisfies every guard. Empty here is a
+     * declaration error (`.readableBy()` with no scope would mean "nobody" — use
+     * `.serverOnly()` for that), so the field is never present as `[]`.
+     *
+     * Orthogonal to `.encrypted()` (storage-at-rest) and to `.sensitive()` /
+     * `.safe()` (export-time masking): this is purely the WIRE-exposure axis.
+     */
+    readonly readableBy?: ReadonlyArray<string>;
+    /**
+     * CRDT-managed marker, set by the `crdtText()` column constructor. When `true`
+     * the column holds an ENCODED CRDT state (opaque bytes — a Yjs update blob
+     * behind `@voltro/local-first`'s swappable backend) rather than a plain value.
+     *
+     * It changes NOTHING about the column's DDL or how the declarative differ
+     * treats it: the storage type is `bytes` (BYTEA / BLOB / LONGBLOB /
+     * VARBINARY), a normal storable type, and the planner compares it structurally
+     * like any other `bytes` column — introspection never reports this flag, and
+     * `sameColumnShape` never reads it, so a `crdtText()` column round-trips
+     * through a plan with zero churn (no phantom re-plan).
+     *
+     * What it DOES drive lives above the DDL, in the runtime write path: the
+     * MutationStore reads it (via the SchemaRegistry) to run the AUTHORITATIVE
+     * server-side merge on write — an incoming encoded update is folded into the
+     * stored state with `mergeCrdtStates` before the row is written, so two
+     * concurrent clients converge. Orthogonal to every other flag here; a CRDT
+     * column is just `bytes` with server-merge semantics.
+     */
+    readonly crdtManaged?: boolean;
     /**
      * Optimistic-concurrency marker, set by `.version()`.
      *
@@ -851,6 +933,75 @@ export declare interface DriftReport {
     }>;
 }
 
+/**
+ * Per-branch refinement passed to `.with({ relation: { ... } })`.
+ *
+ * `true` is the zero-config shorthand — equivalent to `{}`. Otherwise
+ * each branch can carry its own `where` / `orderBy` / `limit` /
+ * `offset` / nested `with`, so `users.with({ posts: { limit: 10,
+ * orderBy: 'createdAt' } })` works without dropping into a sub-query
+ * builder.
+ *
+ * Untyped at runtime: the QueryDescriptor is the boundary between the
+ * typed builder API and the dialect-agnostic JoinCompiler. End-user
+ * types live one layer up in the typed `.with()` method on `Query`.
+ */
+declare interface EagerLoadSpec {
+    readonly where?: Predicate;
+    readonly orderBy?: ReadonlyArray<OrderClause>;
+    /**
+     * Per-parent cap on the relation. `{ limit: 10 }` returns up to 10
+     * rows FOR EACH parent — same semantics as Drizzle / Prisma /
+     * Hibernate. This matches what users actually mean when they write
+     * "the 10 latest posts" inside `users.with({ posts: { limit: 10 } })`.
+     *
+     * The SQL stores express this natively as a `LIMIT` clause in a
+     * correlated subquery (postgres / sqlite / mysql / mariadb) or
+     * via `TOP N` inside `FOR JSON PATH` (mssql) when the JSON-agg path
+     * is active. The walker fallback post-buckets the batch fetch and
+     * slices each bucket.
+     */
+    readonly limit?: number;
+    /** Per-parent offset. Only meaningful with `limit`. */
+    readonly offset?: number;
+    readonly with?: WithSpec;
+    /**
+     * Project the JUNCTION row's own columns into a `manyToMany` eager result.
+     *
+     * `true` takes every junction column; an array takes only those named. The
+     * values land under `_junction` on each target row:
+     *
+     *     projects.with({ teams: { junction: ['role', 'addedAt'] } })
+     *     // → team._junction.addedAt
+     *
+     * Nested rather than merged onto the target row, deliberately: a junction and
+     * its target routinely share column names (`createdAt` is the obvious one),
+     * and merging would silently overwrite real target data with membership data.
+     * A name collision that corrupts a row is worse than one extra level.
+     *
+     * Why this exists: junction tables carrying meaningful columns — a role, a
+     * joined-at stamp, a permission tier — are the rule rather than the
+     * exception, and without this an eager load could FILTER on them
+     * (`onJunction`) but never return them, so any relation with real membership
+     * data had to stay a hand-written join. The junction rows were already being
+     * fetched in full to resolve the target ids; this stops throwing them away.
+     */
+    readonly junction?: true | ReadonlyArray<string>;
+    /**
+     * Filter a `manyToMany` eager branch on the THROUGH-table's columns.
+     * The predicate is evaluated against the junction row, not the target
+     * row — e.g. for `users.with({ organizations: { onJunction: eq('role',
+     * 'admin') } })` it keeps only the memberships where `role = 'admin'`,
+     * so the loaded `organizations` are exactly the orgs the user is an
+     * admin of.
+     *
+     * Compiles into the correlated subquery's WHERE alongside the
+     * source-key correlation, qualified to the junction-table alias.
+     * Ignored on `one` / `many` branches (no junction table exists).
+     */
+    readonly onJunction?: Predicate;
+}
+
 export declare const emitDropColumnDdl: (op: Extract<MigrationOperation, {
     kind: "drop-column";
 }>, q: typeof quote) => string;
@@ -936,6 +1087,18 @@ cdcChannel?: string) => string;
 
 declare type EmptyMerge = unknown;
 
+/**
+ * `EXISTS (SELECT 1 FROM ... WHERE ...)` / `NOT EXISTS (...)`.
+ * Mirrors `SubqueryInPredicate` but doesn't bind to a specific
+ * outer column — the predicate is "the sub-query produces at least
+ * one row" (or doesn't). Non-correlated in v1; the sub-query's
+ * WHERE clause references only its own table.
+ */
+declare interface ExistsPredicate {
+    readonly op: 'exists' | 'not-exists';
+    readonly subquery: QueryDescriptor;
+}
+
 /**
  * Filename pattern the discovery walker matches: timestamp-prefixed
  * `.ts` files in any depth under the project's `migrations/` dir.
@@ -1215,6 +1378,8 @@ declare interface JsonIndexPath {
     readonly numeric: boolean;
 }
 
+declare type LeafOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'arrayContains' | 'arrayOverlaps' | 'arrayHas' | 'isNull' | 'isNotNull' | 'spatial';
+
 export declare const mapPgType: (dataType: string, udtName?: string) => ColumnType;
 
 declare type MergeMixinFields<Mixins extends ReadonlyArray<AnyMixin>> = Mixins extends readonly [] ? EmptyMerge : Mixins extends readonly [infer Head, ...infer Rest] ? (Head extends MixinDefinition<infer F> ? F : EmptyMerge) & (Rest extends ReadonlyArray<AnyMixin> ? MergeMixinFields<Rest> : EmptyMerge) : EmptyMerge;
@@ -1453,6 +1618,13 @@ declare interface NarrowedFromSpec {
     readonly using?: string;
 }
 
+/** Negation of an arbitrary sub-predicate → `NOT (...)`. Wraps any
+ *  leaf/and/or/subquery subtree (distinct from the per-column `neq` and
+ *  the narrow `notInSubquery`/`notExists`). */
+declare interface NotPredicate {
+    readonly not: Predicate;
+}
+
 /**
  * DDL fragment for a numeric primary key column. Each dialect has its
  * own auto-increment idiom — there's no portable shorthand, so we
@@ -1509,6 +1681,15 @@ export declare type OperationClass =
  */
 export declare type OperationKind = 'create-table' | 'drop-table' | 'add-column' | 'drop-column' | 'rename-column' | 'alter-column-nullability' | 'alter-column-type' | 'alter-column-default' | 'add-index' | 'drop-index' | 'add-unique' | 'drop-unique' | 'add-unique-composite' | 'drop-unique-composite' | 'add-foreign-key' | 'drop-foreign-key' | 'add-check' | 'drop-check';
 
+declare interface OrderClause {
+    readonly column: string;
+    readonly direction: 'asc' | 'desc';
+}
+
+declare interface OrPredicate {
+    readonly or: ReadonlyArray<Predicate>;
+}
+
 export declare const parseEnumCheck: (clause: string) => {
     readonly column: string;
     readonly values: ReadonlyArray<string>;
@@ -1622,6 +1803,23 @@ declare type PluginRefOrphanPolicy =
 *  omitting the option, which is the same behaviour arrived at by accident. */
 | 'keep';
 
+declare type Predicate = PredicateLeaf | AndPredicate | OrPredicate | NotPredicate | SubqueryInPredicate | ExistsPredicate;
+
+declare interface PredicateLeaf {
+    readonly column: string;
+    readonly op: LeafOperator;
+    readonly value?: unknown;
+    /**
+     * JSON-path segments INTO a `json()` column (object keys / array indices).
+     * When set, the leaf filters on the extracted value, not the whole column —
+     * built via {@link jsonField}. The sql compiler lowers it to the dialect's
+     * json-extract expression; the reactive matcher treats it as non-indexable
+     * (rides the unindexed bucket → re-checked on any change to the table, like
+     * `contains`). Absent for a normal column leaf.
+     */
+    readonly path?: ReadonlyArray<string | number>;
+}
+
 /**
  * Imperative `applyNamespacedSchema` against a fresh SqlClient — the
  * entry point the CLI / runtime use to provision a tenant's namespace
@@ -1629,6 +1827,275 @@ declare type PluginRefOrphanPolicy =
  */
 export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
 
+/**
+ * The runtime-facing materialized query — a plain bag of strings the store and
+ * the matcher consume.
+ *
+ * `R` is a PHANTOM row type. It exists so the row shape the typed builder
+ * already knows survives the trip through `.descriptor` into `store.query()`,
+ * which is where it used to be thrown away: `store.query(database.notes...)`
+ * returned `Row` (`Record<string, unknown>`), so every field read needed a
+ * hand-written cast. One downstream app wrote 2,032 of them. The type was
+ * always available — it was just dropped at this boundary.
+ *
+ * It is an OPTIONAL field, never set at runtime. That matters for two reasons:
+ * a plain object literal still satisfies `QueryDescriptor` (dispatcher, matcher
+ * and store code build and forward these structurally), and `R` stays
+ * covariant, so a `QueryDescriptor<Note>` is still assignable to the bare
+ * `QueryDescriptor` that generic infrastructure passes around. Defaulting to
+ * `Row` keeps every existing annotation meaning exactly what it meant before.
+ */
+declare interface QueryDescriptor<R = Row> {
+    readonly table: string;
+    readonly predicate: Predicate | undefined;
+    /** Phantom — carries the row type through to `store.query()`. Never set at
+     *  runtime; erased entirely by the compiler. */
+    readonly __row?: R;
+    /**
+     * Opt OUT of the runtime's automatic `deletedAt IS NULL` scope on
+     * `softDelete()` tables. Set by `.withDeleted()`. The query builder is
+     * browser-safe and mixin-unaware, so this is just a flag the RUNTIME
+     * (storeMiddleware read path + reactive-query finalize) honors.
+     */
+    readonly includeDeleted?: boolean;
+    /** Opt OUT of the `expires()` read filter — a deliberate read of expired
+     *  rows (an admin view, a grace-period check). Same shape and same posture as
+     *  `includeDeleted`. */
+    readonly includeExpired?: boolean;
+    /**
+     * Opt OUT of the runtime's automatic tenant scope on `tenant()` tables.
+     * Set by `.unscoped()`. Honored by the runtime, same as `includeDeleted`.
+     */
+    readonly crossTenant?: boolean;
+    readonly order: ReadonlyArray<OrderClause>;
+    readonly take: number | undefined;
+    readonly skip: number | undefined;
+    readonly projection: ReadonlyArray<string> | undefined;
+    /**
+     * Aggregate projection. When set, `SELECT` emits the aggregates
+     * instead of row columns; the result is always exactly ONE row
+     * (per group when combined with `groupBy`, ONE row total when not).
+     *
+     * Cannot coexist with `projection` (the two are mutually exclusive
+     * select clauses). The builder enforces this at chain time.
+     */
+    readonly aggregations?: ReadonlyArray<AggregateColumn<unknown>>;
+    /**
+     * `GROUP BY` columns. When set, the query returns ONE row per
+     * distinct combination of these columns + the aggregations.
+     * Requires `aggregations` to be set; ungrouped aggregates always
+     * produce exactly one row.
+     */
+    readonly groupBy?: ReadonlyArray<string>;
+    /**
+     * `HAVING` clause — predicate evaluated AFTER GROUP BY. Distinct
+     * from `predicate` (which becomes `WHERE` and runs BEFORE grouping).
+     * Use HAVING to filter groups based on their aggregate values
+     * (e.g. "users with more than 10 posts").
+     *
+     * Stored as a `Predicate` so the same predicate compiler that
+     * handles WHERE handles HAVING — but the column names on the LHS
+     * of HAVING refer to aggregate aliases, not raw rows.
+     */
+    readonly having?: Predicate;
+    /**
+     * Full-text-search predicate (S7). Set by `.matching('indexName',
+     * 'query')`. `.matching()` resolves the index back to its declared
+     * columns + config + weights from the table registry at call time and
+     * stores them here, so the SQL compiler can emit the right per-dialect
+     * predicate (and an optional relevance-ranking expression) without
+     * re-consulting the registry.
+     *
+     * Per-dialect emission:
+     *   - postgres        → `<tsvCol> @@ plainto_tsquery('<cfg>', ?)`
+     *   - mysql / mariadb → `MATCH(col1, col2) AGAINST (? IN NATURAL LANGUAGE MODE)`
+     *   - sqlite          → `<table>_<idx>_fts MATCH ?` against the FTS5 table
+     *   - mssql           → ranked LOWER(...) LIKE fallback (no server FTS catalog)
+     *
+     * `rank` carries an optional relevance-ranking request. When set, the
+     * compiler also surfaces a synthetic relevance column aliased `rank.alias`
+     * and (when `rank.order` is set) orders by it DESC. The score expression
+     * is per-dialect: postgres `ts_rank`, mysql/mariadb `MATCH ... AGAINST`
+     * score, sqlite FTS5 `bm25`, mssql a LIKE-hit count.
+     */
+    /**
+     * Full-text indexes declared on the FROM table — captured by
+     * `queryFor()` so `.matching()` can resolve an index's columns/config
+     * without a global table-registry lookup. Pure builder metadata; the
+     * SQL compiler never reads it (it reads the resolved `fullTextSearch`).
+     */
+    readonly fullTextIndexes?: ReadonlyArray<{
+        readonly name: string;
+        readonly columns: ReadonlyArray<string>;
+        readonly config?: string;
+        readonly weights?: Readonly<Record<string, 'A' | 'B' | 'C' | 'D'>>;
+    }>;
+    /**
+     * The SOURCE table object this query was built from (`queryFor(t)` / a
+     * `databaseHandle` entry sets it). The eager-load resolver (`.with(...)`)
+     * needs the source table's shape + relations; it used to re-resolve it
+     * BY NAME via `requireTable(descriptor.table)`, which forces every queried
+     * table to be pre-registered (`databaseHandle(...)` / discovery). A direct
+     * query needs no such registration — it carries the object — so an eager
+     * query that threw "table 'X' is not registered" for a table you can query
+     * directly was an asymmetry. Carrying the object here (same precedent as
+     * `fullTextIndexes`) lets the store use it directly, with `requireTable` as
+     * the fallback for reconstructed descriptors (e.g. `paginateById`). NOT
+     * serialized/fingerprinted — the reactive engine keys on table+predicate.
+     */
+    readonly sourceTable?: TableLike;
+    readonly fullTextSearch?: {
+        readonly indexName: string;
+        readonly query: string;
+        /** Columns the index covers — resolved from the table registry. */
+        readonly columns: ReadonlyArray<string>;
+        /** Postgres tsvector config (default 'english'). */
+        readonly config?: string;
+        /** Per-column weight letters (postgres ts_rank). */
+        readonly weights?: Readonly<Record<string, 'A' | 'B' | 'C' | 'D'>>;
+        /** Relevance-ranking request — set by `.rankBy(alias?)`. */
+        readonly rank?: {
+            readonly alias: string;
+            readonly order: boolean;
+        };
+    };
+    /**
+     * Common-Table-Expression definitions (Q4) — `WITH <name> AS (...)`.
+     * Each entry binds a `name` to a sub-query descriptor; the outer
+     * SELECT can reference the CTE by name in `from`, `inSubquery`,
+     * `exists`, etc.
+     *
+     * `.withCte()` adds a non-recursive CTE. For tree-walks use
+     * `.recursiveCte()`, which sets `recursive: true` and emits
+     * `WITH RECURSIVE` (the inner descriptor self-references the CTE
+     * name). Both are reactive — see `runtime/dependencyGraph.ts`.
+     */
+    readonly ctes?: ReadonlyArray<{
+        readonly name: string;
+        readonly descriptor: QueryDescriptor;
+        /**
+         * Recursive CTE marker (Q4 v2). When true, the compiler emits
+         * `WITH RECURSIVE name AS (...)`. The inner descriptor must be a
+         * UNION (via the `union` / `unionAll` helpers) whose first arm is
+         * the anchor and subsequent arms reference the CTE by name (the
+         * recursion). Cycle-detection per-dialect: postgres uses
+         * `UNION` semantics (implicit dedup); other dialects mirror.
+         */
+        readonly recursive?: boolean;
+    }>;
+    /**
+     * SELECT DISTINCT (Q7). When true, dedup rows by the full result
+     * shape. Cross-dialect.
+     */
+    readonly distinct?: boolean;
+    /**
+     * SELECT DISTINCT ON (cols) — postgres-only (Q7). Picks ONE row
+     * per distinct combination of `distinctOn` columns; the row picked
+     * is the FIRST per the descriptor's `order`. The compiler emits a
+     * windowed-rownumber fallback on other dialects.
+     *
+     * Common use: "latest message per channel".
+     */
+    readonly distinctOn?: ReadonlyArray<string>;
+    /**
+     * Alias for the FROM table — `FROM <table> AS <alias>` (Q8).
+     * Needed for self-joins where the same table appears multiple
+     * times with different aliases. When unset, the FROM clause is
+     * the bare table name.
+     */
+    readonly alias?: string;
+    /**
+     * Joined tables (Q8). Each entry adds an INNER JOIN or LEFT JOIN
+     * with an explicit ON predicate. Self-joins re-use the same
+     * source table with a different alias.
+     *
+     * `on` is a regular `Predicate` — the leaf columns may carry
+     * `alias.column` style qualifiers since the compiler emits the
+     * column string verbatim.
+     */
+    readonly joins?: ReadonlyArray<{
+        readonly kind: 'inner' | 'left';
+        readonly table: string;
+        readonly alias: string;
+        readonly on: Predicate;
+    }>;
+    /**
+     * Aliased projection for joined queries (Q8 v2). When set, the
+     * SELECT emits `alias.col AS outputKey` for each entry, producing
+     * a flat row with the user's chosen keys.
+     *
+     * Mutually exclusive with `projection` (regular select-cols).
+     * Bypassed by `aggregations`.
+     */
+    readonly joinedProjection?: ReadonlyArray<{
+        readonly outputKey: string;
+        readonly source: string;
+    }>;
+    /**
+     * Set-operation composition (Q6). When set, the SELECT shape is
+     * replaced by `(SELECT ...) <OP> (SELECT ...) ...`.
+     *
+     * - `'union'`           → dedup-merge (`UNION`)
+     * - `'union-all'`       → no dedup (`UNION ALL`)
+     * - `'intersect'`       → rows in BOTH (`INTERSECT`)
+     * - `'except'`          → rows in LHS not in RHS (`EXCEPT`)
+     *
+     * All four are standard SQL + supported on every dialect we ship.
+     */
+    readonly setOp?: {
+        readonly kind: 'union' | 'union-all' | 'intersect' | 'except';
+        readonly queries: ReadonlyArray<QueryDescriptor>;
+    };
+    /**
+     * Optional index hint. Set by `.using('indexName')` on the query
+     * builder. The framework stores it on the descriptor for two reasons:
+     *
+     *   1. Suppresses the dev-mode "non-indexed query" warning for this
+     *      descriptor (the user explicitly signalled they thought about
+     *      the access pattern).
+     *   2. The matcher's tuple-routing path keys subscriptions on the
+     *      declared index's column set — see `IndexedMatcher` in
+     *      `@voltro/runtime/matcher.ts`. Subscriptions that declare a
+     *      covering index get O(1) candidate lookup per event instead
+     *      of column-union routing.
+     */
+    readonly usingIndex?: string;
+    /**
+     * Eager-load tree declared via `.with({ ... })`. Consumed by the
+     * JoinCompiler (`./joinCompiler.ts`) when present — the SQL stores
+     * dispatch nested-JSON-aggregation queries; the in-memory store
+     * walks it via post-hoc lookups.
+     */
+    readonly eager?: WithSpec;
+    /**
+     * Approximate-nearest-neighbour clause (plan 01). Set by
+     * `.nearestNeighbours(...)`. Drives a synthetic `distance` projection
+     * + `ORDER BY <col> <op> <query>` in the SQL compiler:
+     *
+     *   - postgres (pgvector): `<col> <=> $q` (cosine) / `<->` (l2) /
+     *     `<#>` (inner).
+     *   - mariadb / mysql: `VEC_DISTANCE_COSINE/EUCLIDEAN(<col>, $q)`.
+     *   - mssql / sqlite: no portable ANN operator → the compiler warns +
+     *     skips the distance ordering (sequential scan; rows still return).
+     *
+     * `queryVector` is the literal float array; `queryText` is the
+     * raw string the runtime embeds to a vector *before* compiling
+     * (only valid when the table carries `vectorEmbedding()`). Exactly
+     * one of the two is set.
+     */
+    readonly annClause?: AnnClause;
+    /**
+     * PostGIS spatial distance clause (`@voltro/plugin-postgis`). Set by the
+     * `withDistance(...)` / `nearestBy(...)` transforms applied via `.use(...)`.
+     * Postgres-only — the SQL compiler lowers it to a `ST_Distance(...)`
+     * projected column and/or a `<->` KNN `ORDER BY`; on any non-postgres
+     * dialect the compiler THROWS (mirrors the spatial predicate + column
+     * guards). Never evaluated in-memory (no PostGIS in JS). Composes with
+     * `.where(...)`, `.limit(k)`, spatial predicates, etc.
+     */
+    readonly spatialClause?: SpatialClause;
+}
+
 declare const quote: (name: string) => string;
 
 /**
@@ -1750,6 +2217,52 @@ export declare const rollingDeployUnsafeOps: (operations: ReadonlyArray<PlannedO
     readonly remedy: string;
 }>;
 
+declare type Row = Readonly<Record<string, unknown>>;
+
+/** The context a rule predicate is evaluated with. */
+declare interface RuleContext {
+    /** Transactional store — read other tables in the mutation's snapshot. */
+    readonly store: RuleReadStore;
+    /** The calling subject (tenant / user), for tenant-aware rules. */
+    readonly subject: unknown;
+}
+
+/**
+ * What a rule predicate may return. `true` / `void` / `undefined` = the rule
+ * HOLDS. `false` = violated with the rule's default detail. A
+ * `RuleViolationDetail` object = violated, carrying per-row i18n params / a
+ * field pointer for THIS specific row.
+ */
+declare type RuleOutcome = boolean | void | RuleViolationDetail;
+
+/**
+ * A rule predicate over the POST-WRITE row. Runs inside the mutation
+ * transaction. Return `true`/nothing when the invariant holds; return `false`
+ * or a `RuleViolationDetail` to signal a violation. May be async (cross-table
+ * reads).
+ */
+declare type RulePredicate = (row: Record<string, unknown>, context: RuleContext) => RuleOutcome | Promise<RuleOutcome>;
+
+/** Minimal READ surface (a subset of `DataStore`) handed to a rule predicate —
+ *  the SAME transactional store the mutation writes through, so cross-table
+ *  reads share its MVCC snapshot and cannot race the write the rule guards. */
+declare interface RuleReadStore {
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Record<string, unknown>>>;
+}
+
+/** Severity of a business rule. `error` rolls the mutation back; `warning`
+ *  logs + audits but lets the write commit (useful during data migrations). */
+declare type RuleSeverity = 'error' | 'warning';
+
+declare interface RuleViolationDetail {
+    /** i18n params for the violation message (per this row). */
+    readonly params?: Record<string, unknown>;
+    /** Field path the violation pinpoints, if any. */
+    readonly field?: string;
+    /** Human-readable message (fallback / dev aid). */
+    readonly message?: string;
+}
+
 export declare const runFileBasedMigrations: (sql: SqlClient.SqlClient, ctx: RunFileBasedMigrationsCtx) => Effect.Effect<FileMigrationRunResult, unknown>;
 
 export declare interface RunFileBasedMigrationsCtx {
@@ -1819,6 +2332,41 @@ export declare const shortFingerprint: (fp: string) => string;
  */
 export declare const snapshotColumn: (name: string, def: ColumnDefinition<unknown>) => ColumnSnapshot;
 
+/**
+ * PostGIS spatial-distance clause carried on a {@link QueryDescriptor}.
+ * Drives a `ST_Distance` projected column (distance-as-a-value) and/or a
+ * `<->` nearest-neighbour `ORDER BY` (KNN). Built by `@voltro/plugin-postgis`;
+ * postgres-only (the compiler throws on other dialects).
+ */
+declare interface SpatialClause {
+    /** The spatial column to measure from. */
+    readonly column: string;
+    /** The comparison geometry as WKT/EWKT (e.g. `SRID=4326;POINT(8 50)`). Bound as a parameter. */
+    readonly geom: string;
+    /**
+     * Measure metric metres via a `::geography` cast on both operands
+     * (great-circle distance). When false, distance is in the SRID's own
+     * planar units (`::geometry`). Default true — the "distance in metres"
+     * users expect for lat/lon data.
+     */
+    readonly useGeography: boolean;
+    /**
+     * When set, surface the distance as a projected column aliased this name
+     * (`ST_Distance(col, geom) AS "<projectAs>"`). The row type gains a
+     * `number` field. Absent → no distance projection (KNN-order-only).
+     */
+    readonly projectAs?: string;
+    /**
+     * When set, add a KNN `ORDER BY col <-> geom <dir>` clause (indexed
+     * nearest-neighbour when a GiST index covers the column). Leads any
+     * explicit `.orderBy(...)`. Absent → no spatial ordering. `<->` is always
+     * a planar operator (postgres has no geography `<->`), so KNN ordering
+     * ranks by planar distance even when `useGeography` is true for the
+     * projected metric distance.
+     */
+    readonly order?: 'asc' | 'desc';
+}
+
 /**
  * The `sql` template tag — captures a tagged-template literal into a
  * {@link RawSqlFragment} descriptor without binding it to any client.
@@ -1888,6 +2436,25 @@ export declare interface SquashResult {
     readonly snapshotId: string;
 }
 
+/**
+ * `col IN (SELECT col FROM ...)` / `col NOT IN (SELECT ...)` — the
+ * RHS is a sub-query descriptor. The sub-query MUST project a
+ * single column (via `.select('col')`); the SQL compiler emits the
+ * full inner SELECT inline, and the in-memory store evaluates the
+ * sub-query first + then runs the IN check against the materialized
+ * set.
+ *
+ * The sub-query is non-correlated in v1 — it can't reference outer
+ * row columns. Correlated sub-queries (`WHERE EXISTS (... WHERE
+ * inner.userId = outer.id)`) would require a table-alias mechanism;
+ * tracked separately.
+ */
+declare interface SubqueryInPredicate {
+    readonly column: string;
+    readonly op: 'subquery-in' | 'subquery-not-in';
+    readonly subquery: QueryDescriptor;
+}
+
 declare interface Table<Name extends string, Fields extends Record<string, ColumnDefinition<unknown>>, Reactive extends boolean = true, IxNames extends string = never> extends TableLike {
     readonly tableName: Name;
     readonly fields: Fields;
@@ -1911,6 +2478,12 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
     readonly appliedUniques: ReadonlyArray<TableUnique>;
     readonly appliedFullText: ReadonlyArray<TableFullTextIndex>;
     readonly appliedChecks: ReadonlyArray<TableCheck>;
+    /**
+     * The cross-table business rules DECLARED on this table, set by
+     * `.rule(name, predicate)`. Evaluated by the runtime inside the mutation
+     * transaction (see `TableRule`); they emit no DDL.
+     */
+    readonly appliedRules: ReadonlyArray<TableRule>;
     /**
      * The name this table used to have, set by `.renamedFrom('old_name')`.
      * Named apart from the METHOD that sets it — one interface cannot carry both.
@@ -2172,6 +2745,38 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      * For a single-column check, `column.check(expr)` is the terser form.
      */
     check: <const CkName extends string>(name: CkName, expr: string) => Table<Name, Fields, Reactive, IxNames>;
+    /**
+     * Declare a CROSS-TABLE business rule (S3). Unlike `.check(name, expr)` — a
+     * single-row SQL `CHECK` the database enforces — a rule is a PREDICATE the
+     * runtime evaluates INSIDE the mutation's transaction, after the write and
+     * before commit. It can read OTHER tables in the same snapshot and rolls the
+     * mutation back with a typed `BusinessRuleViolation` on failure.
+     *
+     * The predicate receives the POST-WRITE row and a `context` whose `store` is
+     * the SAME transactional store the mutation wrote through. Return `true`
+     * (or nothing) when the invariant holds; return `false` or a
+     * `RuleViolationDetail` (i18n `params` / a `field` pointer) to signal a
+     * violation.
+     *
+     * ```ts
+     * table('invoices', { id: id(), total: integer() }).rule(
+     *   'totalMatchesLineItems',
+     *   async (row, { store }) => {
+     *     const items = await store.query(
+     *       lineItems.where(eq('invoiceId', row.id)).descriptor,
+     *     )
+     *     const sum = items.reduce((a, l) => a + (l.amount as number), 0)
+     *     return sum === row.total || { params: { computed: sum, declared: row.total } }
+     *   },
+     * )
+     * ```
+     *
+     * `severity: 'warning'` logs + audits the violation but lets the write
+     * commit (useful during data migration); the default `'error'` rolls back.
+     */
+    rule: <const RuleName extends string>(name: RuleName, predicate: RulePredicate, options?: {
+        readonly severity?: RuleSeverity;
+    }) => Table<Name, Fields, Reactive, IxNames>;
     /**
      * Declare a full-text-search index (S7). One method, three back-
      * ends:
@@ -2383,6 +2988,21 @@ declare interface TableLike {
     readonly fields: Record<string, ColumnDefinition<unknown>>;
 }
 
+/**
+ * A named cross-table business rule, attached by `.rule(name, predicate)`.
+ *
+ * UNLIKE `.check(name, expr)` — a single-row SQL `CHECK` emitted as DDL and
+ * enforced by the database — a rule is a PREDICATE the runtime evaluates INSIDE
+ * the mutation's transaction, AFTER the write and BEFORE commit. It can read
+ * OTHER tables in the same MVCC snapshot and rolls the whole mutation back
+ * (typed `BusinessRuleViolation`) on violation. It emits no DDL.
+ */
+declare interface TableRule {
+    readonly name: string;
+    readonly predicate: RulePredicate;
+    readonly severity: RuleSeverity;
+}
+
 export declare interface TableSnapshot {
     readonly name: string;
     readonly columns: ReadonlyArray<ColumnSnapshot>;
@@ -2477,6 +3097,32 @@ declare interface View<Name extends string, Fields extends Record<string, Column
  */
 export declare const VOLTRO_MIGRATION_LOCK_KEY = 6322741009312437n;
 
+/**
+ * One aggregate column in a `SELECT` projection — `COUNT(*)`,
+ * `SUM(amount) AS total`, etc. Built via the `count() / sum() /
+ * avg() / min() / max() / countDistinct()` helpers exported from
+ * `@voltro/database`.
+ *
+ * `column` is undefined for `count()` (which compiles to `COUNT(*)`)
+ * and required for every other op. `alias` is the column name on the
+ * result row.
+ */
+/**
+ * Window-function spec (Q3). When set on an AggregateColumn, the
+ * compiler emits `<OP>(...) OVER (PARTITION BY ... ORDER BY ...)`
+ * instead of a plain aggregate. The query is reactive coarsely — the
+ * matcher can't bucket on a window-function result, so the engine
+ * widens the dependency to the whole source table and re-queries on
+ * any write to it (see `runtime/relevantFields.ts`).
+ */
+declare interface WindowSpec {
+    readonly partitionBy?: ReadonlyArray<string>;
+    readonly orderBy?: ReadonlyArray<{
+        column: string;
+        direction: 'asc' | 'desc';
+    }>;
+}
+
 /**
  * Convenience wrapper: acquire → run `work` → release. Releases even
  * on failure via `Effect.ensuring`, but a process crash mid-work
@@ -2485,4 +3131,7 @@ export declare const VOLTRO_MIGRATION_LOCK_KEY = 6322741009312437n;
  */
 export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>) => Effect.Effect<A, E | SqlError_2, R>;
 
+/** Tree of relations to eager-load. */
+declare type WithSpec = Readonly<Record<string, true | EagerLoadSpec>>;
+
 export { }