turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/powql.d.ts

@@ -0,0 +1,592 @@
+/**
+ * PowqlInterface — Turbine's PowQL query generator (the PowDB analogue of
+ * {@link QueryInterface}). It exposes the same public method surface as the SQL
+ * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL** — a
+ * pipeline language, not SQL — executed through {@link PowdbPool}.
+ *
+ * It is a *parallel* implementation rather than a `Dialect` of the SQL builder:
+ * PowQL's grammar (`T filter <e> order <k> { .col }`) shares no surface with
+ * `SELECT … FROM … WHERE`, so the SQL `Dialect` seam cannot express it. Keeping
+ * it separate also means the four SQL engines are untouched.
+ *
+ * Behavioural deltas from the SQL path, all driven by PowDB's wire reality (see
+ * `docs/internal/strategy/powdb-parity-matrix.md`, every row verified against a live
+ * server):
+ *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
+ *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
+ *     in one round-trip. `upsert` is the lone exception — its statement does not
+ *     accept `returning`, so it reselects the row by PK (a composite-PK upsert
+ *     reselects-or-writes inside one flat transaction).
+ *   - The PK is server-assigned when the column is `isGenerated` (PowDB's `auto`
+ *     int — read back via `returning`); otherwise a defaulted **string** PK is
+ *     generated client-side (UUID).
+ *   - `with` (nested relations) uses **batched N+1 loaders** — D round-trips for
+ *     depth D, not one query — including manyToMany (junction → targets).
+ *   - **Relation filters** (`some`/`none`/`every`, all cardinalities incl. m2m)
+ *     are resolved client-side to a literal `in (…)` list, never an IN-subquery:
+ *     PowDB's executor caches a subquery's result by plan shape and would return
+ *     a stale prior result for a later subquery of the same shape.
+ *   - **Nested writes** (relation ops in `create`/`update` data) run through the
+ *     shared nested-write engine as one flat top-level transaction (PowDB is
+ *     single-writer, no savepoints).
+ *   - pgvector / JSON / array filters and cursor streaming throw
+ *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
+ *
+ * @module
+ */
+import { type PowdbPool } from './powdb.js';
+import type { MiddlewareFn, QueryInterfaceOptions } from './query/index.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindUniqueArgs, GroupByArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './query/types.js';
+import { type SchemaMetadata } from './schema.js';
+/**
+ * The PowQL query interface. Constructed by `turbinePowDB` via the
+ * `queryInterfaceFactory` seam and cast to `QueryInterface<object>` so
+ * `TurbineClient.table()` can return it transparently.
+ */
+export declare class PowqlInterface<T extends object = Record<string, unknown>> {
+    private readonly pool;
+    private readonly table;
+    private readonly schema;
+    private readonly middlewares;
+    private readonly options;
+    private readonly meta;
+    private readonly defaultLimit?;
+    private readonly warnOnUnlimited;
+    private readonly onQuery?;
+    private warnedUnlimited;
+    constructor(pool: PowdbPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /** Resolve a camelCase field name (or raw snake) to its column metadata. */
+    private column;
+    /**
+     * PowQL column reference for a field. Unqualified it is a dotted field
+     * reference (`.snake_name`), which bypasses keyword lookup. When an `alias`
+     * is supplied (the F2 join path) it is qualified (`alias.snake_name`) and the
+     * column name is backtick-quoted if it is a reserved word (a qualified
+     * `p.order` does NOT bypass keyword lookup, unlike the dotted `.order`).
+     */
+    private ref;
+    /** Render a raw column name as a PowQL reference, qualified with `alias` when given. */
+    private colRefName;
+    /**
+     * Push a value into the param array and return its `$N` placeholder. When the
+     * value targets a `float` column it is wrapped in {@link PowdbFloatParam} so
+     * the *embedded* literal encoder emits a float-form literal even for an
+     * integer value (PowQL's `42` is an int literal, `42.0` a float). The
+     * networked driver unwraps the marker back to the plain number in
+     * {@link toPowdbParam}, so the wire param is unchanged.
+     */
+    private param;
+    /**
+     * Render a value for a write *assignment* (`col := …`). Every value — float
+     * columns included — is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
+     * the int→float UPDATE coercion bug (`score := $n` with an integer param now
+     * reads back the integer value, not the raw i64 bits), so the float-literal
+     * inlining workaround Turbine carried for ≤ 0.6.2 is gone. Marks the column as
+     * float-typed for the *embedded* literal encoder (which materializes params
+     * into PowQL text) so an integer-valued float still encodes as a float literal
+     * and coercion stays unambiguous. Non-finite floats are still rejected.
+     */
+    private writeRef;
+    private isFloatCol;
+    /**
+     * The bound pool's {@link PowdbCapabilities}. Falls back to the trusted-caller
+     * default (all feature gates on, `nativeRaw` off) when a directly-constructed
+     * pool did not carry them, matching {@link PowdbPool}'s own constructor
+     * default so a hand-built test pool never crashes the version gates.
+     */
+    private get capabilities();
+    /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
+    private alwaysFalse;
+    /**
+     * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
+     * value as a positional `$N` param. Returns `''` when there are no conditions.
+     *
+     * When `alias` is supplied (the F2 native-join path) every field reference is
+     * qualified with it (`.col` → `alias.col`, JSON path bases too); params bind
+     * exactly as in the unqualified path. The caller only ever passes an alias for
+     * an already-RESOLVED where (relation filters pre-resolved to literal in-lists
+     * by {@link resolveRelationFilters}): the relation-key branch below still
+     * throws, so an unresolved relation filter can never leak into a join.
+     */
+    private buildWhere;
+    /** Build a single `field: value | operator` condition. */
+    private buildFieldCondition;
+    /**
+     * PowQL JSON path expression `.col->$a->$b…`, binding EVERY path segment as a
+     * positional param (a string segment as a `str` token, an integer index as an
+     * `int` token). `->` binds tighter than every operator, so no parens are
+     * needed around the path in a comparison. Segments are bound (never inlined)
+     * to keep {@link materializePowql}'s `$N`-scan invariant intact: a segment
+     * that literally contained `$1` would otherwise be rewritten. Shared by the
+     * F1 where-filter path and the F2 orderBy / groupBy path emitters.
+     *
+     * A digit-only STRING segment (`'0'`) binds as an `int` array index, matching
+     * the SQL engines: `JsonFilter.path` is typed `string[]`, so an array index
+     * can only be expressed as a digit string, and the SQL builder converts it the
+     * same way (`/^\d+$/ → [n]`, query/builder.ts). Without this, PowDB's typed
+     * `->` treats `'0'` as a string KEY and silently matches nothing on an array
+     * (a wrong result, not an error). Same object-key-`'0'` caveat SQL accepts: a
+     * json object whose key is literally `"0"` is addressed as an array index.
+     */
+    private jsonPathExpr;
+    /**
+     * Compile a {@link JsonFilter} on a json document column into a PowQL filter
+     * (≥ 0.12). Operators PowQL cannot express EXACTLY throw a per-operator E017
+     * (never a wrong result): containment (`contains`, and `equals` without a
+     * `path`) has no PowQL operator. The mapped shapes:
+     *   - `{ path, equals: v }`  → `P = $n` (typed: string→str, bool→bool,
+     *      integral number→int, fractional→float; NOT stringified)
+     *   - `{ path, equals: null }` → `P is null` (matches JSON null AND a missing
+     *      key, a deliberate divergence from the PG driver, documented on
+     *      {@link JsonFilter})
+     *   - `{ path, gt|gte|lt|lte: v }` → `P > $n` … (range ops require `path`; the
+     *      engine coerces int/float numerically)
+     *   - `{ hasKey: k }` → `json_type(.col->$n) is not null` (top-level key test,
+     *      ignoring `path`, mirroring PG `col ? key`; includes keys holding JSON
+     *      null)
+     * A bare `{ path }` with no operators compiles to zero clauses (byte-parity
+     * with SQL), so a mutation whose only `where` is a bare `{ path }` is refused
+     * by the empty-where guard.
+     */
+    private buildJsonPathCondition;
+    /** Bind a value, lowercasing for case-insensitive comparisons. */
+    private bind;
+    /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
+    private bindLike;
+    /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
+    private buildInList;
+    /**
+     * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause
+     * into a plain scalar `in`/`notIn` condition on the **local key**, by running
+     * the inner predicate as its own query and materializing the matching keys as
+     * a literal list. The compiled where is then relation-free and `buildWhere`
+     * emits only `in (<literal list>)`.
+     *
+     * Why not an IN-subquery (`.k in (Target filter <e> { .fk })`)? PowDB's
+     * executor caches a subquery's result by **plan shape, ignoring the literal**,
+     * so a second subquery of the same shape with a different value returns the
+     * first one's stale rows (reproduced live on the embedded engine; the
+     * single-statement literal `in (list)` form is always correct). Resolving
+     * client-side trades extra round-trips for correctness, and recurses — nested
+     * relation filters in the inner predicate resolve when the target query runs.
+     */
+    private resolveRelationFilters;
+    /** Resolve one hasMany/hasOne/belongsTo filter to `{ localField: { in|notIn: [...] } }`. */
+    private resolveRelationCondition;
+    /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
+    private resolveManyToManyCondition;
+    /**
+     * Resolve the set of columns to project, honouring `select` / `omit` and the
+     * query-level `includePii` opt-in. PII-tagged (`defineSchema` `pii: true`)
+     * columns are EXCLUDED from a default (or omit-only) projection unless
+     * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
+     * and returns it regardless. Untagged tables project exactly as before.
+     */
+    private projectedColumns;
+    /**
+     * The snake_case names of this table's PII-tagged columns. Empty for a table
+     * with no `pii: true` column, so untagged tables keep their prior projection.
+     */
+    private piiColumnNames;
+    /**
+     * The camelCase field names of this table's PII-tagged columns: the read
+     * policy applied to a write's returned row (create/update/upsert/delete accept
+     * no `includePii`/`select`, so their result always drops PII; you may still
+     * write PII fields freely).
+     *
+     * SPEC LIMITATION (PowQL): the driver contract
+     * (`docs/integrations/powql-for-drivers.md`) exposes `returning` only as a
+     * bare keyword that hands back every column; it accepts NO column list, so
+     * (unlike the SQL engines, which emit an explicit non-PII `RETURNING`/`OUTPUT`
+     * projection) the create/update/delete `returning` paths cannot exclude PII at
+     * the query-language level and must strip it here after the fact. This is the
+     * client-side strip of last resort, not defense-in-depth, for those paths; we
+     * do NOT reverse-engineer an undocumented projection form. The upsert path is
+     * different: it has no `returning` and reselects by PK through the read
+     * projection ({@link projectedColumns}), which already omits PII, so PII never
+     * crosses the wire there. If a future spec revision lets `returning` take a
+     * projection, switch the write paths to emit the non-PII list and this strip
+     * becomes a no-op like {@link parseWriteRow} on the SQL engines.
+     */
+    private stripWritePii;
+    /** `{ .c1, .c2, … }` projection clause. */
+    private projection;
+    /**
+     * `order .c1 asc, .c2 desc` clause (empty string when no orderBy). Supports,
+     * besides a plain direction:
+     *   - {@link JsonPathOrderBy} on a json column (≥ 0.12): `{ data: { path: […],
+     *     type?, direction? } }` → `order .data->$n asc` (or
+     *     `cast(.data->$n, "float")` for `type: 'numeric'`);
+     *   - {@link OrderBySpec} `{ sort, nulls }`: `nulls: 'last'` is accepted as a
+     *     no-op (PowDB is always nulls-last), `nulls: 'first'` throws E017.
+     *
+     * PowDB orders missing / JSON-null keys LAST in BOTH directions (an engine
+     * contract): for identical cross-engine results pass `nulls: 'last'`
+     * explicitly on Postgres, which defaults nulls-first for `desc`.
+     */
+    private buildOrder;
+    /** Compile one {@link JsonPathOrderBy} entry to `order .col->$n asc` (+ optional numeric cast). */
+    private buildJsonPathOrder;
+    /**
+     * Run PowQL with optional timeout, emitting a query event either way. The
+     * `action` is passed PER CALL (never read from shared instance state) so the
+     * retry-eligibility and the emitted event action stay correct even when a
+     * concurrent operation runs on the same cached interface: a WRITE statement
+     * carries a write action and can therefore never be mistaken for a replayable
+     * read. Read statements pass a read-shaped action from {@link POWQL_READ_ACTIONS}.
+     */
+    private exec;
+    /** Build the E018 refusal for a write / `begin` on a read-only pool. */
+    private readOnlyError;
+    /**
+     * Execute one statement, with the opt-in single stale-frame READ replay. When
+     * `retryStaleReads` is on and a first-statement READ fails with the stale-wire
+     * {@link isStaleFramePowdbError} ConnectionError (a socket idle-gap "received
+     * unexpected frame" that the client cannot recover), the statement is retried
+     * exactly once on a fresh pooled connection (the broken one was destroyed).
+     * The replay is refused for writes (an ambiguous mutation reply is unsafe to
+     * replay) and inside a transaction (a mid-tx statement cannot move connection),
+     * so only the read-shaped actions in {@link POWQL_READ_ACTIONS}, outside a
+     * `_txScoped` interface, are eligible. `action` is a per-call argument (never
+     * `this`-state), so a concurrent op flipping instance fields cannot turn a
+     * write into a retryable read.
+     */
+    private execOnce;
+    /** Is `err` a replayable stale-frame failure for THIS (per-call) read-shaped, non-tx action? */
+    private shouldRetryStaleRead;
+    private emit;
+    /** Run a method body through the middleware chain (mirrors QueryInterface). */
+    private withMiddleware;
+    /** Map raw rows to typed entities. `native` is the wire that ACTUALLY served
+     * this result (threaded from {@link execOnce}, not the pool-level capability),
+     * so cells that arrived pre-typed over `queryNativeRaw` (F3) skip the legacy
+     * string coercion (a genuine str `"null"` stays `"null"` instead of collapsing
+     * to null) while a per-call legacy fallback on a native-capable pool still
+     * coerces its string cells correctly. Defaults to the pool capability for the
+     * rare caller with no per-result flag (hand-built test pools). */
+    private shape;
+    findMany(args?: FindManyArgs<T>): Promise<T[]>;
+    /**
+     * Compile the findMany select into PowQL (no execution), pushing values into
+     * `params`. Returns the query plus the RESOLVED where (relation filters
+     * already collapsed to literal in-lists) so the F2 join path can re-emit the
+     * exact parent predicate alias-qualified, and so {@link explain} can wrap it.
+     *
+     * When the engine supports nested projections (>= 0.18) and the strategy
+     * does not opt out, eligible `with` relations compile INTO this statement as
+     * nested-projection blocks (`nestedPlans`) — one round-trip for the whole
+     * shape — and only the ineligible remainder (`residualWith`) goes to the
+     * post-execution loaders. Without nesting the emitted PowQL is byte-identical
+     * to the pre-0.18 output (no alias, `.col` refs).
+     */
+    private buildFind;
+    /** Build + run the findMany select; returns raw rows, the serving wire, the resolved where, and the `with` partition. */
+    private runFind;
+    /**
+     * Diagnostic surface: compile the same PowQL {@link findMany} would run for
+     * `args` (no cache) and return the engine's plan as one string per line.
+     *
+     * Runs as a READ (`explain <query>`), so it is safe on a read-only pool and
+     * eligible for the stale-read replay. The line content is engine-owned and is
+     * NOT covered by semver (match plan node names / tree shape, never exact
+     * bytes; mirrors PowDB's own `explain` contract).
+     *
+     * Does NOT run through the middleware chain: plan text is a diagnostic, not
+     * entity rows, and `QueryInterface.explain` deliberately bypasses middleware
+     * too, so both engines agree.
+     */
+    explain(args?: FindManyArgs<T>): Promise<string[]>;
+    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
+    findFirst(args?: FindManyArgs<T>): Promise<T | null>;
+    findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
+    findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
+    /**
+     * Load each requested relation for `parents` and attach it onto each row.
+     *
+     * `parent` is supplied ONLY by the top-level {@link findMany} (its args +
+     * resolved where). When the effective `relationLoadStrategy` resolves to an
+     * explicit `'join'` and the pool advertises `serverJoins`, an eligible
+     * top-level relation is loaded with a native PowQL join instead of the keyed
+     * loaders (F2); everything else (nested `with` levels, ineligible shapes, and
+     * the default `'batched'` strategy) keeps the loaders. Output is byte-equal
+     * either way (the join reuses the same stitch / shape helpers).
+     */
+    private loadRelations;
+    /**
+     * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
+     * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
+     * chunks, (2) read the target rows for the collected `targetKey`s, (3) stitch
+     * each parent → its junction rows → its targets in memory. Mirrors the
+     * single-key N+1 loaders; the junction's source/target columns must be single
+     * (composite junction keys would need PowQL tuple-`in`, which it lacks).
+     */
+    private loadManyToMany;
+    /**
+     * Resolve the effective relation-load strategy: the per-query arg wins, then
+     * the client config, then the PowDB default of `'batched'` (the keyed
+     * loaders). PowDB deliberately does NOT inherit the SQL-side implicit `'join'`
+     * default (that would silently flip every existing PowDB user onto brand-new
+     * join generation). Only a value the user actually set to `'join'` activates it.
+     */
+    private resolveStrategy;
+    /**
+     * Per-relation eligibility for the join path (checked before the serverJoins
+     * capability). Any `false` here is a SILENT fallback to the keyed loaders (it
+     * is never an error), so an off-page or nested-`with` shape still returns
+     * correct rows:
+     *   - the parent query must not be paged (`limit`/`offset`/`take`, including the
+     *     configured `defaultLimit`): a parent-filter join under a page would scan
+     *     children of off-page parents, where the loaders are strictly better;
+     *   - the relation must not request a nested `with` (its subtree stays on the
+     *     loaders this round) or a `distinct`;
+     *   - single-column relation keys only (a composite key falls to the loader,
+     *     which throws the same E017 as today);
+     *   - the PARENT-SIDE correlation column must be a single-column PK or unique
+     *     column, or the INNER join would re-emit one child copy per matching
+     *     parent row (a non-unique correlation key produces duplicate children the
+     *     loader never would). For hasMany/hasOne/m2m that column is the relation's
+     *     `referenceKey` on THIS (fetched) table; for belongsTo it is the
+     *     `referenceKey` on the TARGET table (the join's non-fetched side);
+     *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
+     *     stitch can't be reproduced by the 3-table join deterministically);
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
+     *     does a to-many relation `limit`/`offset` when the parent set spills past
+     *     one loader chunk (the loader limits per chunk, the join once globally).
+     */
+    private joinEligible;
+    /**
+     * True when `col` is a single-column unique key of `tableMeta`: the sole
+     * primary-key column, a single-column entry in `uniqueColumns` (where a
+     * per-column `unique: true` and an introspected single-column unique constraint
+     * both land), or a single-column unique index. Used by {@link joinEligible} to
+     * keep the INNER-join path off relations whose parent-side correlation column
+     * can repeat (which would duplicate children).
+     */
+    private isSingleColumnUnique;
+    /** Dispatch one eligible relation to the correct native-join loader. */
+    private loadRelationViaJoin;
+    /**
+     * manyToMany via chained joins: the target (alias `t`) → junction (alias `j`)
+     * → the already-fetched side (alias `p`), correlating `__tpk` from the
+     * junction's source key. Always a list, stitched exactly like the loader.
+     */
+    private loadManyToManyViaJoin;
+    /**
+     * The target column list to project through the join (honouring select/omit),
+     * with a loud guard: a real column named `__tpk` would collide with the
+     * reserved correlation alias, so refuse rather than silently mis-stitch.
+     */
+    private joinChildCols;
+    /**
+     * `{ __tpk: <tpkExpr>, <col>: <childAlias>.<col>, … }`. Each child column is
+     * ALIASED to its bare name (a bare qualified ref `c.col` would come back named
+     * `c.col`, not `col`) so the stitched rows shape identically to a flat select.
+     */
+    private joinProjection;
+    /**
+     * `filter <parentWhere qualified p> [and <relationWhere qualified childAlias>]`.
+     * The parent where is the ALREADY-RESOLVED predicate (relation filters collapsed
+     * to literal in-lists before the base query ran); the relation where is resolved
+     * on the target the same way before qualifying, so a nested relation filter in
+     * the relation `where` never reaches the join unresolved. Params bind in order.
+     */
+    private joinFilter;
+    /** Group join rows by their (normalized) `__tpk`, stripping it and shaping each child. */
+    private bucketByTpk;
+    /**
+     * Normalize a correlation key to a stable string map key so a parent's key
+     * value (a shaped entity field) and a child row's `__tpk` cell match across
+     * wires and column types. A `Date` maps to microseconds
+     * (`getTime()` ms times 1000), because a datetime correlation cell arrives as
+     * raw micros (bigint on the native wire, a micros string on the legacy wire),
+     * never as ms. bigint / number / string all stringify to the same digits, so
+     * an int key matches whether it came back typed or as text.
+     */
+    private joinKey;
+    /**
+     * Should this query's `with` compile to nested-projection blocks? Requires
+     * the engine capability (>= 0.18), and an EXPLICIT `relationLoadStrategy:
+     * 'batched'` (per-query or client-level) opts back out to the keyed loaders.
+     * The default and `'join'` both prefer nesting: unlike the F2 INNER join it
+     * has no fan-out, keeps childless parents, works under parent paging, and
+     * applies per-parent `order`/`limit`/`offset` natively, so it is the
+     * strictly-better single-statement path wherever it is eligible. Ineligible
+     * relations fall through to the existing strategy resolution untouched.
+     */
+    private nestedProjectionsPreferred;
+    /**
+     * Plan one `with` relation as a nested-projection block, or return `null`
+     * when the shape must stay on the loaders (ALWAYS a silent fallback with
+     * identical output, never an error):
+     *   - m2m (the block takes exactly one child table; the junction-order
+     *     stitch has no nested equivalent), and composite relation keys;
+     *   - a to-one relation carrying `limit`/`offset` (the loaders' semantics);
+     *   - `distinct` inside the relation options (no nested grammar for it);
+     *   - a projected child column whose tsType is `bigint` or `Uint8Array`
+     *     (values ride a JSON array, which cannot carry them losslessly);
+     *   - a projection key collision (a child column named like a sub-relation);
+     *   - depth >= 10 (the loader path enforces the same cap by throwing, so the
+     *     fallback surfaces the identical E003 today's users get);
+     *   - any ineligible descendant (the WHOLE relation falls back, so one
+     *     statement never mixes nested and loader semantics mid-subtree).
+     */
+    private planNestedRelation;
+    /**
+     * Compile one {@link NestedRelationPlan} into its projection-field block:
+     * `name: Target as tN filter <correlation> [and (<child where>)] [order …]
+     * [limit …] [offset …] { col: tN.col, …, <sub-blocks> }`. Params bind in
+     * emission order (the projection is the statement's final clause, so nested
+     * params always follow the parent's filter/order/limit/offset params).
+     * Aliases share the parent statement's counter, so arbitrarily deep and
+     * self-referential trees stay collision-free (the same discipline as the SQL
+     * engine's json_agg subqueries).
+     */
+    private buildNestedBlock;
+    /**
+     * Shape the nested JSON children back into typed entities on every parent
+     * row. The nested field arrives as a decoded JSON array on the native wire
+     * (or JSON text on the legacy wire — parsed here); its values are real JSON
+     * types, so each child object goes through the NATIVE coercion policy
+     * (`rowToEntity(…, true)`: a date column's micros number becomes a `Date`, a
+     * json column's document passes through, a str `"null"` stays a string).
+     * to-one relations unwrap to `[0] ?? null`, matching the loaders exactly.
+     */
+    private attachNestedRows;
+    private attachOneNested;
+    /**
+     * The `schema links` snapshot for this pool, fetched at most once and cached on
+     * the pool identity. A fetch failure resolves to `[]` (a missing listing is a
+     * silent fallback to loaders, never an error). Only called when the `linkPaths`
+     * capability is on, so the listing statement is guaranteed to exist.
+     */
+    private linksSnapshot;
+    private fetchLinksSnapshot;
+    /** True when `name` is a bare PowQL identifier (quoting leaves it unchanged). */
+    private isBareIdent;
+    /**
+     * Find the declared to-one link on THIS table that matches `rel` exactly: same
+     * target, same correlation columns (owner localKey = the FK on this table, target
+     * targetKey = the referenced key on target), cardinality `"to-one"`. Returns the
+     * declared link (whose NAME drives the path spelling, which may differ from the
+     * relation's own name) or `null` for no verifiable match (→ silent loader
+     * fallback, never an error).
+     */
+    private findMatchingLink;
+    /**
+     * Plan one belongsTo `with` as a scalar link-path relation, or `null` when it
+     * must stay on the loaders (ALWAYS a silent fallback with identical output).
+     *
+     * SCOPED TIGHT: this fires ONLY for a to-one relation whose child projection
+     * includes a bigint/bytes column — exactly the case a JSON nested block cannot
+     * carry, so nested projections have already fallen back to a per-relation loader
+     * (`planNestedRelation` returned `null` for the same shape). Cases nested
+     * projections DO serve keep nested projections: link-bearing statements are
+     * NEVER plan-cached upstream, so replacing a cacheable nested projection with a
+     * link path would regress a hot path for no gain. Requires: single-column
+     * belongsTo; no relation `with` / `where` / `distinct` / `orderBy` /
+     * `limit` / `offset` (a scalar path has no per-hop filter/order and cannot
+     * reproduce those — such inputs stay on the loader for exact parity); a link
+     * name and all projected columns that are bare identifiers (a quoted segment in
+     * a dotted link path is outside the verified spelling — fall back); and a
+     * DECLARED link that verifiably matches (`findMatchingLink`).
+     */
+    private planLinkPathRelation;
+    /** The flat `l<i>_<col>: t0.<linkName>.<col>` projection fields for one link plan. */
+    private linkPathFields;
+    /**
+     * Reconstruct each link-path relation's child entity from its flat hop fields
+     * and attach it under the relation name — output indistinguishable from the
+     * loader (same keys, same coercions). Presence: the target PK cell arriving
+     * Empty (a null/dangling FK at the hop) means no linked row → `null`, matching
+     * the loader's `matches[0] ?? null`. Otherwise the gathered snake cells go
+     * through the SAME `rowToEntity` policy the loader uses (native micros → Date,
+     * bigint per the int8 policy), and the PK is stripped back off if the user did
+     * not project it. `native` is the wire that actually served the parent row.
+     */
+    private attachLinkRows;
+    /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
+    private scalarData;
+    /**
+     * Fill in a client-generated UUID for a defaulted **string** PK that wasn't
+     * supplied. A server-generated PK ({@link ColumnMetadata.isGenerated}, e.g. an
+     * `int` column with PowDB's `auto` modifier) is left untouched — PowDB assigns
+     * it and the trailing `returning` reads it back — as is any non-string PK.
+     */
+    private applyPkDefault;
+    /**
+     * The table name as a PowQL type reference — backtick-quoted when it is a
+     * reserved word (e.g. a table named `order`). Used in every emitted
+     * statement; plain `this.table` stays in error messages.
+     */
+    private get qt();
+    create(args: CreateArgs<T>): Promise<T>;
+    createMany(args: CreateManyArgs<T>): Promise<T[]>;
+    update(args: UpdateArgs<T>): Promise<T>;
+    updateMany(args: UpdateManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    /** Compile `data` into PowQL update assignments, including atomic operators. */
+    private buildUpdateAssignments;
+    private isTxScoped;
+    private nestedCreate;
+    private nestedUpdate;
+    /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
+    private runInImplicitTx;
+    /** Already inside a transaction: build a context whose table accessors reuse the pinned pool. */
+    private buildNestedCtx;
+    delete(args: DeleteArgs<T>): Promise<T>;
+    deleteMany(args: DeleteManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    upsert(args: UpsertArgs<T>): Promise<T>;
+    /**
+     * Composite-key upsert: PowQL's `upsert … on .col` only takes one conflict
+     * column, so reselect by the full composite PK and update-or-create inside one
+     * flat transaction (PowDB single-writer makes the read-then-write safe from
+     * concurrent writers; the transaction makes it atomic with the write).
+     */
+    private upsertComposite;
+    count(args?: CountArgs<T>): Promise<number>;
+    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
+    groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
+    /** Validate a JSON-path target (group key / aggregate target): non-empty array of keys/indexes. */
+    private assertJsonPath;
+    /**
+     * `having <expr>` over group aggregates. `_count` compares `count(*)` (parity
+     * with the projection); a per-field aggregate re-emits its inner expression
+     * (from `aggInner` when the field is a requested aggregate, so a JSON-path
+     * aggregate reuses its bound placeholders, else `.field` for a plain column).
+     *
+     * Every token that reaches the PowQL text is builder-controlled: the field is
+     * validated by `ref()`, the aggregate function comes from
+     * {@link POWQL_HAVING_AGG_FNS} (unknown keys throw E003), the operator from a
+     * fixed map, and every compared value is bound as a `$N` param.
+     */
+    private buildHaving;
+    /**
+     * Compile a groupBy `orderBy` into a PowQL `order` body over the group RESULT
+     * columns (by-fields, JSON group-key aliases, and requested aggregates). PowQL
+     * cannot re-emit an aggregate EXPRESSION in `order` (engine error), but CAN
+     * order by a projection alias on a grouped query (probed), so each key maps to
+     * its projected alias (`.agg_N` / `.gk_N` / `.col`). Semantics and error
+     * surface mirror the SQL `buildGroupByOrderBy` (0.32.2 R3-1): an aggregate not
+     * requested in this call, or an unknown by-key, throws E003 listing the valid
+     * keys. `nulls: 'first'` stays E017 (PowDB has no NULLS placement grammar).
+     */
+    private buildGroupOrder;
+    /** Resolve a groupBy order direction, refusing `nulls: 'first'` (E017); `nulls: 'last'` is a no-op. */
+    private groupOrderDir;
+    findManyStream(): AsyncGenerator<T>;
+    /** Reselect a single row by its single-column primary key value. */
+    private reselectByPk;
+    /**
+     * Empty-where guard — blocks accidental whole-table writes. Mirrors the SQL
+     * path's `assertMutationHasPredicate` (query/builder.ts): it gates on the
+     * *compiled* PowQL filter fragment, NOT the shape of the `where` object. A
+     * `where` whose conditions all evaporate during compilation — `{}`,
+     * `{ id: undefined }`, `{ OR: [] }`, `{ AND: [] }`, `{ NOT: {} }`,
+     * `{ OR: [{ f: undefined }] }` — compiles to the empty string and is refused,
+     * because emitting a filter-less write would hit every row.
+     */
+    private assertCompiledWhere;
+}