turbine-orm 0.79.1 → 0.80.0

package/dist/errors.js

@@ -1200,6 +1200,84 @@ const CONNECTION_ERROR_CODES = new Set([
     'CERT_HAS_EXPIRED',
     'ERR_TLS_CERT_ALTNAME_INVALID',
 ]);
+/**
+ * The driver's own words for "this connection is gone", which carry NO code.
+ *
+ * node-postgres raises these as plain `Error`s with no SQLSTATE and no socket
+ * code: the first when the socket closes under a live client, the next two for
+ * any query sent to a client after that, the last two when a connect or an
+ * orderly `end()` cuts a query off. Keyed on `.code` alone, wrapPgError handed
+ * every one of them back untyped, so the commonest symptom of a database
+ * restart was the one connection failure a `catch (e) { if (e instanceof
+ * ConnectionError) ... }` did not see. Exact matches on the full message, and
+ * only on code-less errors: these strings are pg's and have not changed across
+ * the 8.x line, and nothing else produces them.
+ */
+const PG_CONNECTION_LOSS_MESSAGES = new Set([
+    'Connection terminated unexpectedly',
+    'Client has encountered a connection error and is not queryable',
+    'Client was closed and is not queryable',
+    'Connection terminated',
+    'Connection terminated due to connection timeout',
+]);
+/** The follow-on errors pg raises for a query sent to a client already known to be dead. */
+const PG_NOT_QUERYABLE_MESSAGES = new Set([
+    'Client has encountered a connection error and is not queryable',
+    'Client was closed and is not queryable',
+]);
+/**
+ * Report the error that KILLED a held connection instead of its follow-on.
+ *
+ * When a connection dies while a transaction callback is between queries, the
+ * next query fails with "Client has encountered a connection error and is not
+ * queryable", which says nothing about why. The connection guard recorded the
+ * real cause (`lostWith`, e.g. 57P01 `terminating connection due to
+ * administrator command`), so a not-queryable ConnectionError is swapped for
+ * that one. Anything else passes through: an error the caller threw, or a
+ * query that was IN FLIGHT when the connection died, which already carries the
+ * server's own message.
+ */
+export function explainConnectionLoss(err, lostWith) {
+    if (!lostWith || !(err instanceof ConnectionError))
+        return err;
+    const cause = err.cause;
+    if (!(cause instanceof Error) || !PG_NOT_QUERYABLE_MESSAGES.has(cause.message))
+        return err;
+    const original = wrapPgError(lostWith);
+    return original instanceof ConnectionError ? original : err;
+}
+/**
+ * Codes that mean an ESTABLISHED connection went away: the server ended the
+ * backend (57P01, which is also what a dead idle connection hands the next
+ * query, since pg attributes the FATAL it buffered to whatever is sent next),
+ * or the peer reset the socket.
+ */
+const STALE_CONNECTION_CODES = new Set(['57P01', 'ECONNRESET', 'EPIPE']);
+/** pg's code-less messages for the same thing. */
+const STALE_CONNECTION_MESSAGES = new Set(['Connection terminated unexpectedly', ...PG_NOT_QUERYABLE_MESSAGES]);
+/**
+ * Whether `err` says a connection that was already open is gone, so the same
+ * statement on a fresh connection can succeed. Accepts the raw driver error or
+ * the {@link ConnectionError} wrapPgError made of it.
+ *
+ * Narrower than "is a ConnectionError" on purpose. A connection that could not
+ * be OPENED (refused, DNS, auth, a connect timeout, 57P03 while the server
+ * starts) will not open on an immediate second try either, and retrying it
+ * only doubles the wait before the caller hears about it. Nor does it cover
+ * `Connection terminated` without "unexpectedly", which is the pool itself
+ * shutting down.
+ */
+export function isStaleConnectionError(err) {
+    const raw = err instanceof ConnectionError && err.cause instanceof Error ? err.cause : err;
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const code = raw.code;
+    if (code)
+        return STALE_CONNECTION_CODES.has(code);
+    return raw instanceof Error && STALE_CONNECTION_MESSAGES.has(raw.message);
+}
+const CONNECTION_LOSS_HINT = 'The server or the network closed it (a restart, failover, idle timeout, compute suspend, or ' +
+    'pg_terminate_backend). The pool discards the connection, so retrying the operation opens a fresh one.';
 /**
  * Actionable next step per connection-class code, appended to the driver's own
  * message. The driver message states WHAT happened ("password authentication
@@ -1472,8 +1550,12 @@ export function wrapPgError(err) {
     if (!err || typeof err !== 'object')
         return err;
     const e = err;
-    if (!e.code)
+    if (!e.code) {
+        if (err instanceof Error && PG_CONNECTION_LOSS_MESSAGES.has(err.message)) {
+            return new ConnectionError(`Database connection lost: ${err.message}. ${CONNECTION_LOSS_HINT}`, { cause: err });
+        }
         return err;
+    }
     switch (e.code) {
         case '23505': {
             const cols = e.detail ? parseColumnsFromDetail(e.detail) : undefined;

package/dist/index.d.ts

@@ -46,7 +46,7 @@ export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSu
 export { fingerprintPrismaSchema } from './prisma-schema-fingerprint.js';
 export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonEncoding, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderBySpec, type OrderDirection, type PrivilegeOption, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationOrderBy, type RelationOrderByChain, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, UNSAFE, type Unsafe, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
 export { MAX_QUERY_TAG_LENGTH, RAW_QUERY_MODEL } from './query-events.js';
-export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
+export { type ActiveSubscription, type ListenOptions, type ListenReconnectOptions, type NotificationHandler, type Subscription, validateChannel, } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, PrismaSchemaSource, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, withDbFieldNames, } from './schema.js';
 export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnIndexDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, type DocFieldIndexDef, defineSchema, isDocFieldIndexDef, type ManyToManyDef, type ReferenceDef, type SchemaDef, type SchemaIndexDef, type TableDef, table, } from './schema-builder.js';

package/dist/index.js

@@ -58,7 +58,7 @@ export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN
 // $on('query') event metadata: raw-statement model name, $tag() label limit
 export { MAX_QUERY_TAG_LENGTH, RAW_QUERY_MODEL } from './query-events.js';
 // Realtime, LISTEN/NOTIFY pub/sub
-export { validateChannel } from './realtime.js';
+export { validateChannel, } from './realtime.js';
 // Schema utilities
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, withDbFieldNames, } from './schema.js';
 // Schema builder, define schemas in TypeScript

package/dist/nested-write.d.ts

@@ -137,10 +137,20 @@ export declare function createManyShapeRuns<T extends Record<string, unknown>>(r
  * operation (create, connect, connectOrCreate), and finally reads back the
  * full tree using `findUnique` with an auto-built `with` clause.
  */
-export declare function executeNestedCreate(ctx: NestedWriteContext, tableName: string, data: Record<string, unknown>, depth?: number, path?: string[]): Promise<Record<string, unknown>>;
+/**
+ * The caller's `select` / `omit` for the TOP-LEVEL row of a nested write. Only
+ * the final read-back applies it (see executeNestedCreate), so it narrows the
+ * returned scalars exactly as it does on a read, while every intermediate
+ * statement keeps the full row it needs for keys.
+ */
+export interface NestedReturnShape {
+    select?: Record<string, boolean>;
+    omit?: Record<string, boolean>;
+}
+export declare function executeNestedCreate(ctx: NestedWriteContext, tableName: string, data: Record<string, unknown>, depth?: number, path?: string[], returnShape?: NestedReturnShape): Promise<Record<string, unknown>>;
 /**
  * Tree-walking update: updates the parent row with scalar data, then
  * processes each relation operation (create, connect, connectOrCreate,
  * disconnect, set, delete), and reads back the full tree.
  */
-export declare function executeNestedUpdate(ctx: NestedWriteContext, tableName: string, where: Record<string, unknown>, data: Record<string, unknown>, depth?: number, path?: string[]): Promise<Record<string, unknown>>;
+export declare function executeNestedUpdate(ctx: NestedWriteContext, tableName: string, where: Record<string, unknown>, data: Record<string, unknown>, depth?: number, path?: string[], returnShape?: NestedReturnShape): Promise<Record<string, unknown>>;

package/dist/nested-write.js

@@ -828,15 +828,7 @@ function rethrowAsNotRelated(err, op, relName, rel, target) {
     }
     throw err;
 }
-// ---------------------------------------------------------------------------
-// executeNestedCreate
-// ---------------------------------------------------------------------------
-/**
- * Tree-walking create: inserts the parent row, then processes each relation
- * operation (create, connect, connectOrCreate), and finally reads back the
- * full tree using `findUnique` with an auto-built `with` clause.
- */
-export async function executeNestedCreate(ctx, tableName, data, depth = 0, path = []) {
+export async function executeNestedCreate(ctx, tableName, data, depth = 0, path = [], returnShape) {
     if (depth > MAX_DEPTH) {
         throw new CircularRelationError(path);
     }
@@ -902,6 +894,7 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
     const fullRow = await ctx.tx.table(tableName).findUnique({
         where: pkWhere(tableMeta, parentRow),
         with: withClause,
+        ...returnShape,
     });
     return (fullRow ?? parentRow);
 }
@@ -913,7 +906,7 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
  * processes each relation operation (create, connect, connectOrCreate,
  * disconnect, set, delete), and reads back the full tree.
  */
-export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0, path = []) {
+export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0, path = [], returnShape) {
     if (depth > MAX_DEPTH) {
         throw new CircularRelationError(path);
     }
@@ -1008,6 +1001,7 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
     const fullRow = await ctx.tx.table(tableName).findUnique({
         where: pkWhere(tableMeta, parentRow),
         with: readBackWith(ctx.schema, tableName, relations),
+        ...returnShape,
     });
     return (fullRow ?? parentRow);
 }

package/dist/pipeline.js

@@ -18,8 +18,9 @@
  * Sequential fallback covers HTTP-based drivers (Neon HTTP, Vercel Postgres, Cloudflare
  * Hyperdrive), mock pools in tests, and any pool that doesn't expose pg internals.
  */
+import { guardCheckout } from './connection-guard.js';
 import { postgresDialect } from './dialect.js';
-import { PipelineError, TurbineError, wrapPgError } from './errors.js';
+import { explainConnectionLoss, PipelineError, TurbineError, wrapPgError } from './errors.js';
 import { pipelineClientNeedsDiscard, runPipelined, supportsExtendedPipeline, } from './pipeline-submittable.js';
 /**
  * Execute queries sequentially on an already-acquired connection.
@@ -202,6 +203,9 @@ export async function executePipeline(pool, queries, options) {
     catch (err) {
         throw wrapPgError(err);
     }
+    // Guarded for the checkout window, see connection-guard.ts: a connection that
+    // dies mid-batch emits 'error', which with no listener exits the process.
+    const checkout = guardCheckout(client);
     try {
         if (supportsExtendedPipeline(client)) {
             // Real pipeline path, uses extended-query protocol wire methods
@@ -223,8 +227,8 @@ export async function executePipeline(pool, queries, options) {
         // driver error that must not escape with a SQLSTATE sitting in the same
         // `.code` slot Turbine puts TURBINE_E0NN in.
         if (err instanceof TurbineError)
-            throw err;
-        throw wrapPgError(err);
+            throw explainConnectionLoss(err, checkout.lostWith);
+        throw explainConnectionLoss(wrapPgError(err), checkout.lostWith);
     }
     finally {
         // A client the pipeline could not return to a clean state is released WITH
@@ -235,10 +239,10 @@ export async function executePipeline(pool, queries, options) {
         // normally is what turned one failed batch into `25P02` on somebody else's
         // query.
         if (pipelineClientNeedsDiscard(client)) {
-            client.release(new Error('turbine: pipeline connection left an open transaction and was discarded'));
+            checkout.release(new Error('turbine: pipeline connection left an open transaction and was discarded'));
         }
         else {
-            client.release();
+            checkout.release();
         }
     }
 }
@@ -250,15 +254,16 @@ export async function executePipeline(pool, queries, options) {
  * Note: This acquires and immediately releases a connection to inspect it.
  */
 export async function pipelineSupported(pool) {
-    let client;
+    let checkout;
     try {
-        client = await pool.connect();
+        const client = await pool.connect();
+        checkout = guardCheckout(client);
         return supportsExtendedPipeline(client);
     }
     catch {
         return false;
     }
     finally {
-        client?.release();
+        checkout?.release();
     }
 }

package/dist/plan-flip-probe.js

@@ -76,6 +76,7 @@
  *
  * @module
  */
+import { guardConnection } from './connection-guard.js';
 import { quoteIdent } from './query/utils.js';
 /** An empty result, which keeps every finding. Used when probing is off. */
 export function emptyFlipProbeResult() {
@@ -220,6 +221,9 @@ export async function probePlanFlips(options) {
     }
     const { Client } = (await import('pg')).default;
     const client = new Client({ connectionString: options.connectionString });
+    // A dropped connection must fail the probe (which then reports 'unknown'),
+    // not exit the process through an unheard 'error' event.
+    guardConnection(client);
     try {
         await client.connect();
         // READ ONLY is belt-and-braces: EXPLAIN without ANALYZE cannot write, and the

package/dist/powdb-shared.d.ts

@@ -19,8 +19,9 @@
  *
  * Everything here is re-exported by powdb.ts under its original name, so the
  * public `turbine-orm/powdb` surface is byte-identical to before the split.
- * The few helpers powdb.ts consumes but never published (`isDateColumn`) are
- * exported from this module and NOT re-exported from powdb.ts.
+ * The few helpers powdb.ts consumes but never published (`isDateColumn`,
+ * `parsePowdbSemver`, `atLeastVersion`) are exported from this module and NOT
+ * re-exported from powdb.ts.
  *
  * @module
  */
@@ -140,6 +141,25 @@ export interface PowdbCapabilities {
 }
 /** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
 type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections' | 'entityLinks' | 'linkIntrospection' | 'linkPaths' | 'datetimeCompare' | 'projectedCountNonNull';
+/** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
+export declare function parsePowdbSemver(version: string | undefined | null): {
+    major: number;
+    minor: number;
+    patch: number;
+} | null;
+/**
+ * Is `sem` at least `major.minor.patch`? PATCH-AWARE: `patch` defaults to `0`,
+ * so a two-component floor (`atLeastVersion(sem, 0, 19)`) behaves exactly as the
+ * old major/minor comparison did (matches every patch of 0.19), while a
+ * three-component floor (`atLeastVersion(sem, 0, 19, 1)`) additionally requires
+ * the patch, the distinction the link lanes need (0.19.1, never 0.19.0). Every
+ * existing two-argument call keeps its prior semantics unchanged.
+ */
+export declare function atLeastVersion(sem: {
+    major: number;
+    minor: number;
+    patch: number;
+}, major: number, minor: number, patch?: number): boolean;
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
  * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that

package/dist/powdb-shared.js

@@ -19,8 +19,9 @@
  *
  * Everything here is re-exported by powdb.ts under its original name, so the
  * public `turbine-orm/powdb` surface is byte-identical to before the split.
- * The few helpers powdb.ts consumes but never published (`isDateColumn`) are
- * exported from this module and NOT re-exported from powdb.ts.
+ * The few helpers powdb.ts consumes but never published (`isDateColumn`,
+ * `parsePowdbSemver`, `atLeastVersion`) are exported from this module and NOT
+ * re-exported from powdb.ts.
  *
  * @module
  */
@@ -60,6 +61,28 @@ export class PowdbJsonParam {
         this.column = column;
     }
 }
+/** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
+export function parsePowdbSemver(version) {
+    const m = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(version ?? '').trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0) };
+}
+/**
+ * Is `sem` at least `major.minor.patch`? PATCH-AWARE: `patch` defaults to `0`,
+ * so a two-component floor (`atLeastVersion(sem, 0, 19)`) behaves exactly as the
+ * old major/minor comparison did (matches every patch of 0.19), while a
+ * three-component floor (`atLeastVersion(sem, 0, 19, 1)`) additionally requires
+ * the patch, the distinction the link lanes need (0.19.1, never 0.19.0). Every
+ * existing two-argument call keeps its prior semantics unchanged.
+ */
+export function atLeastVersion(sem, major, minor, patch = 0) {
+    if (sem.major !== major)
+        return sem.major > major;
+    if (sem.minor !== minor)
+        return sem.minor > minor;
+    return sem.patch >= patch;
+}
 /**
  * Minimum engine version each gated feature needs, for the E017 hint text.
  * Most gates carry a `major.minor` floor (patch-insensitive); the two link

package/dist/powdb.js

@@ -57,7 +57,7 @@ import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
 import { ConnectionError, malformedConnectionStringMessage, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import importOptionalPeer from './optional-peer-import.cjs';
-import { ALL_POWDB_CAPABILITIES, isDateColumn, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlIdent, requireCapability, } from './powdb-shared.js';
+import { ALL_POWDB_CAPABILITIES, atLeastVersion, isDateColumn, PowdbFloatParam, PowdbJsonParam, parsePowdbSemver, powqlColumnType, quotePowqlIdent, requireCapability, } from './powdb-shared.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { normalizeKeyColumns } from './schema.js';
 // The shared PowDB primitives live in a leaf module (see powdb-shared.ts): this
@@ -206,28 +206,6 @@ export function assertSupportedPowdbVersion(version) {
  * powql.ts.
  */
 export const POWQL_MAX_NESTING_DEPTH = 64;
-/** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
-function parsePowdbSemver(version) {
-    const m = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(version ?? '').trim());
-    if (!m)
-        return null;
-    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0) };
-}
-/**
- * Is `sem` at least `major.minor.patch`? PATCH-AWARE: `patch` defaults to `0`,
- * so a two-component floor (`atLeastVersion(sem, 0, 19)`) behaves exactly as the
- * old major/minor comparison did (matches every patch of 0.19), while a
- * three-component floor (`atLeastVersion(sem, 0, 19, 1)`) additionally requires
- * the patch, the distinction the link lanes need (0.19.1, never 0.19.0). Every
- * existing two-argument call keeps its prior semantics unchanged.
- */
-function atLeastVersion(sem, major, minor, patch = 0) {
-    if (sem.major !== major)
-        return sem.major > major;
-    if (sem.minor !== minor)
-        return sem.minor > minor;
-    return sem.patch >= patch;
-}
 /**
  * Derive {@link PowdbCapabilities} from an engine version string. A non-semver /
  * unknown version turns every gate OFF (the E017 hint then tells the caller to
@@ -332,6 +310,19 @@ export function powqlSchemaDDL(schema, opts = {}) {
         // m2m junction's `(source_id, target_id)`) marks its columns `required` but
         // cannot enforce the tuple's uniqueness at the engine level.
         const pkIsSingle = meta.primaryKey.length === 1;
+        // The primary key's OWN index: introspection lists it in `indexes` (the
+        // `<table>_pkey` a PRIMARY KEY constraint creates), so a composite key used
+        // to reach the composite-index refusal below even though the type body
+        // already handles it. Identified by what it guarantees rather than by name:
+        // a full (non-partial) unique index over exactly the PK's column SET states
+        // the PK constraint and nothing else, whatever order it lists the columns in.
+        // Anything short of that (non-unique, partial, a subset or superset) is a
+        // genuine composite index and is still refused.
+        const isPrimaryKeyIndex = (idx) => idx.unique &&
+            !idx.partial &&
+            !idx.docPath &&
+            new Set(idx.columns).size === pkSet.size &&
+            idx.columns.every((c) => pkSet.has(c));
         const fields = meta.columns.map((col) => {
             const powqlType = powqlColumnType(col);
             // Gate `json` columns behind the engine's jsonDocs capability when a
@@ -385,8 +376,16 @@ export function powqlSchemaDDL(schema, opts = {}) {
                 stmts.push(`alter ${quotePowqlIdent(meta.name)} add ${kind} (.${quotePowqlIdent(column)}${segs})`);
             }
             else {
+                // The composite PK's index is already the type body's `required` columns
+                // (see isPrimaryKeyIndex); a single-column PK's index is skipped by the
+                // emittedUnique check below.
+                if (idx.columns.length > 1 && isPrimaryKeyIndex(idx))
+                    continue;
                 // Plain column index. PowDB has no composite index (`add index` takes a
-                // single `.column`), so a multi-column entry is a typed E017.
+                // single `.column`), so a multi-column entry is a typed E017. That
+                // includes a composite UNIQUE index other than the PK: it is an
+                // integrity rule the engine cannot enforce, so it is refused rather than
+                // dropped without a word.
                 if (idx.columns.length !== 1) {
                     throw new UnsupportedFeatureError('composite indexes', 'PowDB', `PowDB has no composite index. Index "${idx.name}" on ${meta.name} lists ` +
                         `${idx.columns.length} columns; declare a single-column index (or a doc-field index) instead.`);

package/dist/powql.d.ts

@@ -499,6 +499,21 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * becomes a no-op like {@link parseWriteRow} on the SQL engines.
      */
     private stripWritePii;
+    /**
+     * A single-row write's `select` / `omit`, resolved by {@link projectionPlan}
+     * so the rules and messages are the read path's, and the SQL engines' (an
+     * unknown name is E003, `select` must name something, the pair is refused).
+     * `undefined` for the default return shape. Resolved BEFORE the write is sent,
+     * so a bad projection writes nothing.
+     *
+     * The narrowing itself happens on the returned row ({@link shapeWriteRow}):
+     * PowQL's `returning` takes no column list (see {@link stripWritePii}), so
+     * unlike the SQL engines the unselected columns still cross the wire here.
+     * The RESULT is identical across engines; the byte saving is SQL-only.
+     */
+    private writeReturnPlan;
+    /** Apply a write's return plan to its row, or the default PII strip without one. */
+    private shapeWriteRow;
     /** `{ .c1, .c2, … }` projection clause. */
     private projection;
     /**
@@ -874,12 +889,21 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     }>;
     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;
+     * Upsert as a reselect-or-write inside one flat transaction, for every shape
+     * the native `upsert … on .col` statement cannot express: a conflict target
+     * other than a single-column primary key (it takes one column and PowDB has
+     * no composite unique), and a table under a global filter (its conflict
+     * branch takes no predicate). PowDB's single writer makes the read-then-write
+     * safe from concurrent writers; the transaction makes it atomic with the
+     * write.
+     *
+     * The row is looked up by the conflict columns with `create`'s values for
+     * them, which is what `ON CONFLICT (<cols>)` compares on the SQL engines. The
+     * find and the update run through the transaction's table interface, so a
+     * configured global filter applies to both exactly as it does to any other
+     * read or write, and `skipGlobalFilters` is forwarded to both.
+     */
+    private upsertLookupFirst;
     count(args?: CountArgs<T>): Promise<number>;
     /**
      * Gate ONE field of a per-field `_count`.
@@ -902,6 +926,27 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * instead of values below 0.20, the same drift any stale-metadata query has.
      */
     private assertProjectedCountSupported;
+    /**
+     * Can `aggregate()` compute several aggregates in ONE statement on this engine?
+     *
+     * PowQL refuses a bare multi-aggregate projection (`T { a: sum(.x), b: sum(.y) }`
+     * is "aggregate function in an unsupported position" on every engine version),
+     * so the only one-statement form is a grouping over a literal key,
+     * `T filter … group 1 { agg_0: sum(.x), agg_1: sum(.y) }`, which yields a
+     * single group holding every row the filter matched. Measured against the
+     * embedded addon at 0.7.1 through 0.28: below 0.13 a literal group key does not
+     * parse, from 0.13 to 0.19.1 the grouped per-field `count` disagrees with the
+     * scalar `count(T { .col })` on a nullable column, and from 0.20 every
+     * aggregate kind (count / sum / avg / min / max over int, float, str, an
+     * all-null column, and several filters) answers identically on both wires.
+     *
+     * Derived from the PROBED engine version rather than from a capability flag,
+     * so an unprobed pool (`engineVersion: null`, e.g. an injected pool carrying
+     * {@link ALL_POWDB_CAPABILITIES}) keeps the per-field statements: this changes
+     * the emitted PowQL, and an older engine would reject it outright, the same
+     * probe-only discipline `nestedProjections` follows.
+     */
+    private get groupsAggregatesInOneStatement();
     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. */