turbine-orm 0.49.0 → 0.50.0

package/dist/powdb.js

@@ -141,8 +141,11 @@ export class PowdbFloatParam {
  */
 export class PowdbJsonParam {
     value;
-    constructor(value) {
+    column;
+    /** `column` is diagnostic only: it names the target column when serialization fails. */
+    constructor(value, column) {
         this.value = value;
+        this.column = column;
     }
 }
 /** Minimum PowDB server version the networked transport requires. */
@@ -597,9 +600,10 @@ export function powqlSchemaDDL(schema, opts = {}) {
         // Declared indexes: PowDB doc-field expression indexes (docPath) and plain
         // single-column indexes. A doc-field index MUST be parenthesized (the engine
         // rejects a bare JSON path); string path segments emit lexer-exact via the
-        // shared `encodePowqlString`, integer array indexes emit bare. A json
-        // document column reference stays dotted-bare (`.col`), which bypasses
-        // keyword lookup on every engine version exactly like a filter path.
+        // shared `encodePowqlString`, integer array indexes emit bare. The json
+        // document column goes through `quotePowqlIdent` exactly like the plain
+        // index branch below, so a keyword or non-bare identifier is backtick-quoted
+        // instead of being spliced raw into the statement.
         for (const idx of meta.indexes) {
             const kind = idx.unique ? 'unique' : 'index';
             if (idx.docPath) {
@@ -610,7 +614,7 @@ export function powqlSchemaDDL(schema, opts = {}) {
                     throw new ValidationError(`[turbine] Doc-field index "${idx.name}" on ${meta.name} has no target json column.`);
                 }
                 const segs = idx.docPath.map((s) => (typeof s === 'number' ? `->${s}` : `->${encodePowqlString(s)}`)).join('');
-                stmts.push(`alter ${quotePowqlIdent(meta.name)} add ${kind} (.${column}${segs})`);
+                stmts.push(`alter ${quotePowqlIdent(meta.name)} add ${kind} (.${quotePowqlIdent(column)}${segs})`);
             }
             else {
                 // Plain column index. PowDB has no composite index (`add index` takes a
@@ -718,6 +722,36 @@ async function listPowdbLinks(exec) {
 function powdbCell(v) {
     return v === null || v === undefined ? '' : String(v);
 }
+/**
+ * Serialize a json-column value to the canonical JSON text both transports
+ * send. `JSON.stringify` can throw (circular structure, a BigInt cell, a
+ * throwing `toJSON`) and can return `undefined` (a value that serializes to
+ * nothing, e.g. a `toJSON` returning undefined); both surface as a typed E003
+ * naming the column instead of a raw TypeError or an undefined param.
+ */
+function powdbJsonText(param, position) {
+    const where = `for column "${param.column ?? '(unknown)'}"${position ? ` (${position})` : ''}`;
+    let json;
+    try {
+        json = JSON.stringify(param.value);
+    }
+    catch (err) {
+        throw new ValidationError(`[turbine] The json value ${where} cannot be serialized for PowDB: ${err.message}`);
+    }
+    if (json === undefined) {
+        throw new ValidationError(`[turbine] The json value ${where} serializes to nothing (JSON.stringify returned undefined); ` +
+            'write `null` explicitly instead.');
+    }
+    return json;
+}
+/** Convert a Date to PowDB epoch micros, refusing an invalid Date (getTime() is NaN). */
+function powdbDateMicros(value, position) {
+    const ms = value.getTime();
+    if (!Number.isFinite(ms)) {
+        throw new ValidationError(`[turbine] Invalid Date${position ? ` (${position})` : ''} cannot be encoded as a PowDB timestamp.`);
+    }
+    return BigInt(ms) * 1000n;
+}
 /** Coerce a JS value into a PowDB positional param (the write side). */
 function toPowdbParam(value, col) {
     if (value instanceof PowdbFloatParam)
@@ -725,11 +759,11 @@ function toPowdbParam(value, col) {
     // json document: serialize to canonical JSON text and bind as a str param,
     // the engine validates it as JSON and stores the canonical binary form.
     if (value instanceof PowdbJsonParam)
-        return JSON.stringify(value.value);
+        return powdbJsonText(value);
     if (value === undefined || value === null)
         return null;
     if (value instanceof Date)
-        return BigInt(value.getTime()) * 1000n; // ms → micros (int column)
+        return powdbDateMicros(value); // ms → micros (int column)
     if (col && isDateColumn(col) && typeof value === 'number')
         return BigInt(value) * 1000n;
     if (typeof value === 'boolean' ||
@@ -1585,36 +1619,74 @@ function normalizeEmbeddedResult(r) {
  * quotes, backslashes, `$N`, `"); drop … --`, raw CR, and emoji all round-trip
  * as data and cannot break out of the literal or inject a second statement.
  */
-export function encodePowqlLiteral(value) {
+export function encodePowqlLiteral(value, position) {
+    const at = position ? ` (${position})` : '';
     if (value instanceof PowdbFloatParam) {
         const n = value.value;
         if (!Number.isFinite(n))
-            throw new ValidationError(`[turbine] Non-finite float cannot be encoded for PowDB.`);
+            throw new ValidationError(`[turbine] Non-finite float cannot be encoded for PowDB${at}.`);
         // Force a float-form literal so an integer-valued float column stays a float.
-        return Number.isInteger(n) ? `${n}.0` : String(n);
+        const text = powqlNumberText(n);
+        return text.includes('.') ? text : `${text}.0`;
     }
     // json document: emit the canonical JSON text as a PowQL string literal (the
     // embedded engine validates and stores it as a json document).
     if (value instanceof PowdbJsonParam)
-        return encodePowqlString(JSON.stringify(value.value));
+        return encodePowqlString(powdbJsonText(value, position), position);
     if (value === undefined || value === null)
         return 'null';
     if (value instanceof Date)
-        return `${BigInt(value.getTime()) * 1000n}`; // epoch micros (int column)
+        return `${powdbDateMicros(value, position)}`; // epoch micros (int column)
     if (typeof value === 'boolean')
         return value ? 'true' : 'false';
     if (typeof value === 'bigint')
         return value.toString();
     if (typeof value === 'number') {
         if (!Number.isFinite(value))
-            throw new ValidationError(`[turbine] Non-finite number cannot be encoded for PowDB.`);
-        // `String(n)` renders an integer as an int literal (`42`) and a fractional
-        // number as a float literal (`4.2`) — PowQL distinguishes them by the dot.
-        return String(value);
+            throw new ValidationError(`[turbine] Non-finite number cannot be encoded for PowDB${at}.`);
+        // Renders an integer as an int literal (`42`) and a fractional number as a
+        // float literal (`4.2`); PowQL distinguishes them by the dot.
+        return powqlNumberText(value);
     }
     if (typeof value === 'string')
-        return encodePowqlString(value);
-    throw new ValidationError(`[turbine] Value of type ${typeof value} cannot be encoded as a PowDB literal.`);
+        return encodePowqlString(value, position);
+    throw new ValidationError(`[turbine] Value of type ${typeof value} cannot be encoded as a PowDB literal${at}.`);
+}
+/**
+ * Render a finite JS number as PowQL numeric text.
+ *
+ * `String(n)` is used verbatim for every ordinary magnitude (an integer becomes
+ * `42`, a fractional number `4.2`), but it switches to exponential notation at
+ * `1e21` and below `1e-6` (`1e+21`, `1.5e-7`), which the PowQL lexer does not
+ * accept as a number token (and which the float path would further mangle into
+ * `1e+21.0`). Those two ranges are expanded into plain decimal digits so any
+ * finite double round-trips to a literal the engine can parse.
+ */
+function powqlNumberText(n) {
+    const s = String(n);
+    if (!s.includes('e') && !s.includes('E'))
+        return s;
+    // Integer-valued doubles (|n| >= 1e21) expand exactly through BigInt.
+    if (Number.isInteger(n))
+        return BigInt(n).toString();
+    const m = /^(-?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/.exec(s);
+    if (!m) {
+        throw new ValidationError(`[turbine] Number ${s} cannot be rendered as a PowDB literal.`);
+    }
+    const sign = m[1] ?? '';
+    const intPart = m[2] ?? '';
+    const fracPart = m[3] ?? '';
+    const exp = Number(m[4]);
+    const digits = intPart + fracPart;
+    const pointPos = intPart.length + exp;
+    let body;
+    if (pointPos <= 0)
+        body = `0.${'0'.repeat(-pointPos)}${digits}`;
+    else if (pointPos >= digits.length)
+        body = digits + '0'.repeat(pointPos - digits.length);
+    else
+        body = `${digits.slice(0, pointPos)}.${digits.slice(pointPos)}`;
+    return sign + body;
 }
 /**
  * The newest PowDB engine LINE (major.minor) whose lexer escape handling
@@ -1646,8 +1718,21 @@ export function encodePowqlLiteral(value) {
  * already covers every 0.19.x patch — no bump is needed for 0.19.1.
  */
 export const POWQL_LEXER_TESTED_CEILING = '0.19';
-/** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
-function encodePowqlString(s) {
+/**
+ * Escape a string into a PowQL `"…"` literal, matching the engine lexer's
+ * escape rules.
+ *
+ * A raw NUL (U+0000) is REFUSED rather than emitted: the lexer defines no `\0`
+ * escape (its escape set is exactly `\"`, `\\`, `\n`, `\t`, see
+ * {@link POWQL_LEXER_TESTED_CEILING}), so a NUL would travel into the query
+ * text as a raw byte and any layer that treats that text as a C string would
+ * silently truncate the statement there.
+ */
+function encodePowqlString(s, position) {
+    if (s.includes('\0')) {
+        throw new ValidationError(`[turbine] String value${position ? ` (${position})` : ''} contains a NUL byte (U+0000), which PowQL string ` +
+            'literals cannot represent. Strip it before writing.');
+    }
     let out = '"';
     for (const ch of s) {
         if (ch === '\\')
@@ -1677,7 +1762,7 @@ export function materializePowql(powql, params) {
         if (idx < 0 || idx >= params.length) {
             throw new ValidationError(`[turbine] PowQL placeholder $${n} has no bound parameter (have ${params.length}).`);
         }
-        return encodePowqlLiteral(params[idx]);
+        return encodePowqlLiteral(params[idx], `parameter $${n}`);
     });
 }
 /**

package/dist/powql.d.ts

@@ -556,6 +556,11 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * 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;
     /**

package/dist/powql.js

@@ -107,6 +107,21 @@ const OPERATOR_KEYS = new Set([
     'endsWith',
     'mode',
 ]);
+/**
+ * Aggregate keys accepted inside a per-field `having` filter, mapped to the
+ * PowQL function each one emits. The set is FIXED: any other key is rejected by
+ * {@link PowqlInterface.buildHaving} rather than interpolated into the query
+ * text (the SQL builder holds the same contract, see `aggFnByKey` in
+ * query/aggregates.ts). A Map is used deliberately so an inherited object key
+ * (`constructor`, `toString`, `__proto__`) can never resolve to a function name.
+ */
+const POWQL_HAVING_AGG_FNS = new Map([
+    ['_sum', 'sum'],
+    ['_avg', 'avg'],
+    ['_min', 'min'],
+    ['_max', 'max'],
+    ['_count', 'count'],
+]);
 /** Filters that have no PowDB representation and must throw E017. */
 function rejectUnsupportedFilter(value, field) {
     if ('distance' in value || 'metric' in value) {
@@ -206,7 +221,7 @@ export class PowqlInterface {
             // json document column: a JS object/array is serialized to canonical JSON
             // text and stored as a json document (a JS string passes through raw, same
             // contract as pg jsonb; `null` stays `null`).
-            tagged = new PowdbJsonParam(value);
+            tagged = new PowdbJsonParam(value, col.name);
         }
         params.push(tagged);
         return `$${params.length}`;
@@ -2460,6 +2475,11 @@ export class PowqlInterface {
      * 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.
      */
     buildHaving(having, params, aggInner) {
         if (!having)
@@ -2469,10 +2489,19 @@ export class PowqlInterface {
             if (typeof filter === 'number')
                 return `${expr} = ${this.param(filter, params)}`;
             const f = filter;
-            const ops = { equals: '=', gt: '>', gte: '>=', lt: '<', lte: '<=', not: '!=' };
+            // Map (not an object literal) so an inherited key such as `constructor`
+            // cannot resolve to a truthy value and reach the emitted PowQL.
+            const ops = new Map([
+                ['equals', '='],
+                ['gt', '>'],
+                ['gte', '>='],
+                ['lt', '<'],
+                ['lte', '<='],
+                ['not', '!='],
+            ]);
             return Object.entries(f)
-                .filter(([k]) => ops[k])
-                .map(([k, v]) => `${expr} ${ops[k]} ${this.param(v, params)}`)
+                .filter(([k]) => ops.has(k))
+                .map(([k, v]) => `${expr} ${ops.get(k)} ${this.param(v, params)}`)
                 .join(' and ');
         };
         for (const [key, spec] of Object.entries(having)) {
@@ -2482,11 +2511,18 @@ export class PowqlInterface {
                 conds.push(cmp('count(*)', spec));
             }
             else {
-                for (const [fn, filter] of Object.entries(spec)) {
+                for (const [aggKey, filter] of Object.entries(spec)) {
                     if (filter == null)
                         continue;
+                    // The function token is emitted verbatim into the PowQL text, so it
+                    // must come from the fixed allowlist, never from the caller's key.
+                    const fn = POWQL_HAVING_AGG_FNS.get(aggKey);
+                    if (!fn) {
+                        throw new ValidationError(`[turbine] Unknown aggregate "${aggKey}" in having for field "${key}" on table "${this.table}". ` +
+                            `Supported: ${[...POWQL_HAVING_AGG_FNS.keys()].join(', ')}.`);
+                    }
                     const inner = aggInner.get(key) ?? this.ref(key);
-                    conds.push(cmp(`${fn.slice(1)}(${inner})`, filter));
+                    conds.push(cmp(`${fn}(${inner})`, filter));
                 }
             }
         }

package/dist/prisma-compat.d.ts

@@ -260,6 +260,8 @@ export type PrismaCompatClient<S extends Record<string, PrismaModelTypes> = Reco
 } & {
     [K in keyof S as Uncapitalize<K & string>]: PrismaModelDelegate<S[K]>;
 } & PrismaCompatClientBase<S>;
+/** @internal Names on a compat client that are NOT model delegates. */
+export declare const CLIENT_RESERVED_KEYS: ReadonlySet<string>;
 /**
  * Create a PrismaClient-surface adapter over a {@link TurbineClient}, driven by a
  * {@link PrismaCompatMap} (the `prisma-map.ts` that `turbine

package/dist/prisma-compat.js

@@ -82,6 +82,7 @@
  * ```
  */
 import { TurbineError, TurbineErrorCode, UnsupportedFeatureError, ValidationError, wrapPgError } from './errors.js';
+import { shouldWarnOnce } from './query/warn-registry.js';
 // ---------------------------------------------------------------------------
 // Prisma.sql-style raw fragments (local, minimal, never imports @prisma/client)
 // ---------------------------------------------------------------------------
@@ -399,7 +400,7 @@ function modelName(ctx, mm) {
  * `where` / `orderBy` are translated first so the cursor step (which may inject
  * a keyset predicate) operates in the translated turbine-field space.
  */
-function translateReadArgs(ctx, mm, prismaArgs) {
+function translateReadArgs(ctx, mm, prismaArgs, kind) {
     const t = {};
     if (prismaArgs.where !== undefined)
         t.where = translateWhere(ctx, mm, prismaArgs.where);
@@ -424,9 +425,85 @@ function translateReadArgs(ctx, mm, prismaArgs) {
         t.includePii = prismaArgs.includePii;
     if (ctx.options.stablePkOrder)
         t.stableRelationOrder = true;
+    // ORDER IS LOAD-BEARING: translateCursor MUST run BEFORE applyImplicitPkOrder.
+    // The cursor translation reads `t.orderBy` to decide the seek direction and to
+    // validate that a bare inclusive cursor names the sort key; it must see the
+    // USER's ordering, never an ordering this layer invented. Swap these two lines
+    // and a bare inclusive cursor on a non-PK field silently compiles against the
+    // injected primary-key order instead of throwing. See the guard test
+    // "cursor decisions are made against the user's own orderBy".
     translateCursor(ctx, mm, prismaArgs, t);
+    applyImplicitPkOrder(ctx, mm, t, kind);
     return t;
 }
+/**
+ * Prisma appends an implicit `ORDER BY <primary key> ASC` to a paginated read;
+ * Turbine emits a bare `LIMIT`. An unordered `LIMIT` is not stable in Postgres:
+ * once the heap changes underneath it (autovacuum, a heap rewrite, a plan flip)
+ * successive pages can repeat a row or skip one entirely, and the unordered
+ * plan is also the slower one (a seq scan instead of a primary-key index scan).
+ *
+ * So a top-level compat read whose page is not already ordered gets the model's
+ * primary key ascending, matching Prisma. An explicit `orderBy` always wins, a
+ * composite primary key orders on every column in declaration order, and a model
+ * with no primary key is left exactly as it was (nothing is invented).
+ *
+ * ## Which reads this covers
+ *
+ * - `findMany` only when it paginates (`take` / `skip`): without a limit there
+ *   is no page to be unstable.
+ * - `findFirst` / `findFirstOrThrow` ALWAYS: core compiles both to a bare
+ *   `LIMIT 1`, which is the single most common nondeterministic read shape in
+ *   Prisma-shaped code ("give me any one row" quietly becoming "give me
+ *   whichever row the heap hands back today").
+ * - `findUnique` / `findUniqueOrThrow` NEVER: they are addressed by a unique
+ *   key, so at most one row matches and an ordering is pure overhead.
+ * - Nested relation includes (`include: { posts: { take: 3 } }`) are NOT
+ *   touched here, deliberately. Relation ordering is a core concern (core owns
+ *   the target table's metadata and the subquery shape), and core already
+ *   exposes it as `stableRelationOrder`, which this layer forwards from the
+ *   {@link PrismaCompatOptions.stablePkOrder} option. Re-walking the `with` tree
+ *   here would duplicate that mechanism and fight it inside the subquery.
+ *
+ * ## Mirrored exclusions (keep in sync with core `isUnorderedPage`)
+ *
+ * Core's `QueryInterface.isUnorderedPage` (query/builder.ts) excludes both
+ * `distinct` and `cursor`. This layer mirrors them one at a time rather than
+ * copying the predicate, because the two layers do NOT have the same default:
+ *
+ * - `distinct`: EXCLUDED, same as core, and this one is a hard requirement.
+ *   Adding an `orderBy` flips core's `DISTINCT ON` out of its plain branch into
+ *   the two-level derived-table rewrite whose OUTER `ORDER BY` can only see the
+ *   projected columns, so `distinct` + `select` + `take` would fail at runtime
+ *   with `column "id" does not exist`. Injecting also lifts the `LIMIT` outside
+ *   the `DISTINCT ON`, so the inner scan stops being limited. `distinct` reads
+ *   keep the exact SQL they emitted before this ordering existed.
+ * - `cursor`: NOT excluded here, unlike core. Core is a general-purpose layer
+ *   whose cursor callers chose their own ordering; this layer's contract is
+ *   Prisma parity, and Prisma pairs cursor pagination with the same implicit
+ *   primary-key order. The injection is safe because it runs strictly AFTER
+ *   {@link translateCursor}: the cursor comparison direction was already
+ *   resolved from the user's own `orderBy` (ascending by default, matching an
+ *   ascending primary key), and the bare-inclusive-cursor branch has already
+ *   set or demanded an `orderBy`, so only the exclusive `cursor` + `skip`
+ *   branch reaches here. It gains an `ORDER BY <pk> ASC` and nothing else.
+ */
+function applyImplicitPkOrder(ctx, mm, t, kind) {
+    if (kind === 'unique')
+        return;
+    if (t.orderBy !== undefined)
+        return;
+    if (t.distinct !== undefined)
+        return;
+    if (kind === 'many' && t.limit === undefined && t.offset === undefined)
+        return;
+    const meta = ctx.schema.tables[mm.table];
+    const pk = meta?.primaryKey ?? [];
+    if (pk.length === 0)
+        return;
+    const fields = pk.map((col) => meta?.reverseColumnMap?.[col] ?? col);
+    t.orderBy = fields.length === 1 ? { [fields[0]]: 'asc' } : fields.map((f) => ({ [f]: 'asc' }));
+}
 /** turbine field names of the model's single-column primary key, if any. */
 function singleColumnPkField(ctx, mm) {
     const pk = ctx.schema.tables[mm.table]?.primaryKey;
@@ -1039,11 +1116,11 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
         return args;
     };
     return {
-        findMany: (args = {}) => defer(() => translateReadArgs(ctx, mm, args), (qi, t) => qi.findMany(t).then((r) => reshapeRows(ctx, mm, r)), { build: (qi, t) => qi.buildFindMany(t), reshape: (raw) => reshapeRows(ctx, mm, raw) }),
-        findFirst: (args = {}) => defer(() => translateReadArgs(ctx, mm, args), (qi, t) => qi.findFirst(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirst(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
-        findUnique: (args) => defer(() => translateReadArgs(ctx, mm, requireWhere(args, 'findUnique')), (qi, t) => qi.findUnique(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindUnique(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
-        findFirstOrThrow: (args = {}) => defer(() => translateReadArgs(ctx, mm, args), (qi, t) => qi.findFirstOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirstOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
-        findUniqueOrThrow: (args) => defer(() => translateReadArgs(ctx, mm, requireWhere(args, 'findUniqueOrThrow')), (qi, t) => qi.findUniqueOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindUniqueOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
+        findMany: (args = {}) => defer(() => translateReadArgs(ctx, mm, args, 'many'), (qi, t) => qi.findMany(t).then((r) => reshapeRows(ctx, mm, r)), { build: (qi, t) => qi.buildFindMany(t), reshape: (raw) => reshapeRows(ctx, mm, raw) }),
+        findFirst: (args = {}) => defer(() => translateReadArgs(ctx, mm, args, 'first'), (qi, t) => qi.findFirst(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirst(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
+        findUnique: (args) => defer(() => translateReadArgs(ctx, mm, requireWhere(args, 'findUnique'), 'unique'), (qi, t) => qi.findUnique(t).then((r) => reshapeRowOrNull(ctx, mm, r)), { build: (qi, t) => qi.buildFindUnique(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) }),
+        findFirstOrThrow: (args = {}) => defer(() => translateReadArgs(ctx, mm, args, 'first'), (qi, t) => qi.findFirstOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindFirstOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
+        findUniqueOrThrow: (args) => defer(() => translateReadArgs(ctx, mm, requireWhere(args, 'findUniqueOrThrow'), 'unique'), (qi, t) => qi.findUniqueOrThrow(t).then((r) => reshapeRow(ctx, mm, r)), { build: (qi, t) => qi.buildFindUniqueOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) }),
         create: (args) => defer(() => {
             const t = { data: translateWriteData(ctx, mm, applyCreateDefaults(mm, args.data)) };
             if (typeof args.timeout === 'number')
@@ -1181,6 +1258,79 @@ function flattenTemplate(strings, values, ph) {
 // ---------------------------------------------------------------------------
 // createPrismaCompatClient
 // ---------------------------------------------------------------------------
+/**
+ * The client-level members every compat client carries, as a total map over
+ * {@link PrismaCompatClientBase}. Declaring it `Record<keyof …, true>` makes the
+ * compiler keep it in sync: adding a `$method` to the interface without listing
+ * it here is a type error, and listing one that does not exist is too. The
+ * derived key set is what {@link junctionModels} refuses to shadow.
+ */
+const CLIENT_RESERVED_KEY_MAP = {
+    $transaction: true,
+    $queryRaw: true,
+    $queryRawUnsafe: true,
+    $executeRaw: true,
+    $executeRawUnsafe: true,
+    $connect: true,
+    $disconnect: true,
+};
+/** @internal Names on a compat client that are NOT model delegates. */
+export const CLIENT_RESERVED_KEYS = new Set(Object.keys(CLIENT_RESERVED_KEY_MAP));
+/** Warn-once namespace for junction accessors dropped on a name collision. */
+const JUNCTION_WARN_NS = 'prismaCompatJunction';
+/**
+ * Synthesize a model map per implicit many-to-many JUNCTION table, keyed by the
+ * junction's raw table name (`_ReportToSchedule`, `post_tags`, ...).
+ *
+ * Prisma's schema has no model for an implicit junction, so `PRISMA_MAP` has no
+ * entry for it and the adapter would expose no accessor: a compat caller had no
+ * way to touch link rows at all, not even inside a `$transaction`. The junction
+ * tables ARE in the Turbine schema metadata (`through.table` on every
+ * many-to-many relation), so the delegate is a plain identity mapping over the
+ * real table: no field renames, no relations, no compound uniques.
+ *
+ * A junction accessor is an ESCAPE HATCH, never worth breaking a real member of
+ * the client for, so it FAILS SAFE: the name is skipped (leaving the existing
+ * member intact) whenever it collides with anything the client already exposes,
+ * which is a Prisma model name, a table some model maps to, a model's
+ * lowercased Prisma-property alias (`compat.user` for `model User`), or one of
+ * the client-level {@link CLIENT_RESERVED_KEYS} (a junction table named
+ * `$transaction` must not turn the transaction surface into a delegate).
+ *
+ * Every skip except the mapped-table one loses a capability the caller might
+ * expect, so those warn once per junction name in dev; a table that a model
+ * already maps to is not a loss (the model IS that table's accessor).
+ */
+function junctionModels(ctx, map, tableToModel) {
+    const out = [];
+    const seen = new Set(CLIENT_RESERVED_KEYS);
+    for (const model of Object.keys(map.models)) {
+        seen.add(model);
+        const alias = prismaPropertyAlias(model);
+        if (alias)
+            seen.add(alias);
+    }
+    for (const table of Object.values(ctx.schema.tables)) {
+        for (const rel of Object.values(table.relations ?? {})) {
+            if (rel.type !== 'manyToMany')
+                continue;
+            const name = rel.through?.table;
+            if (!name || !ctx.schema.tables[name] || tableToModel.has(name))
+                continue;
+            if (seen.has(name)) {
+                if (process.env.NODE_ENV !== 'production' && shouldWarnOnce(JUNCTION_WARN_NS, name)) {
+                    console.warn(`[turbine] prisma-compat: the many-to-many junction table "${name}" collides with an ` +
+                        'existing client member of the same name, so no junction accessor was created for it. ' +
+                        'Reach its rows through $queryRaw / $executeRaw, or through the owning model relation.');
+                }
+                continue;
+            }
+            seen.add(name);
+            out.push([name, { table: name, accessor: name, fields: {}, relations: {}, compoundUniques: {} }]);
+        }
+    }
+    return out;
+}
 /**
  * Create a PrismaClient-surface adapter over a {@link TurbineClient}, driven by a
  * {@link PrismaCompatMap} (the `prisma-map.ts` that `turbine
@@ -1216,9 +1366,17 @@ export function createPrismaCompatClient(client, map, options = {}) {
             prismaErrorCodes: options.prismaErrorCodes ?? false,
         },
     };
+    // Every model the client exposes: the map's Prisma models, plus the implicit
+    // many-to-many junction tables (see below). Both delegate loops (base and
+    // transaction-scoped) build from this ONE list, so an accessor can never
+    // exist on the client but be missing inside `$transaction`.
+    const delegateModels = [
+        ...Object.entries(map.models),
+        ...junctionModels(ctx, map, tableToModel),
+    ];
     // Delegates bound to the base client (each call reads db.table(...) lazily).
     const delegates = new Map();
-    for (const [prismaModel, mm] of Object.entries(map.models)) {
+    for (const [prismaModel, mm] of delegateModels) {
         delegates.set(prismaModel, makeDelegate(ctx, mm, () => db.table(mm.table), (fn) => db.$transaction((tx) => fn((n) => tx.table(n)))));
     }
     const ph = placeholderOf(db);
@@ -1271,7 +1429,7 @@ export function createPrismaCompatClient(client, map, options = {}) {
             const fn = arg;
             return db.$transaction((tx) => {
                 const txDelegates = {};
-                for (const [prismaModel, mm] of Object.entries(map.models)) {
+                for (const [prismaModel, mm] of delegateModels) {
                     txDelegates[prismaModel] = makeDelegate(ctx, mm, () => tx.table(mm.table), (fn) => fn((n) => tx.table(n)));
                     const alias = prismaPropertyAlias(prismaModel);
                     if (alias && !(alias in map.models) && !(alias in txDelegates)) {

package/dist/query/aggregates.js

@@ -11,6 +11,7 @@
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
 import { isJsonPathOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries } from './filters.js';
+import { ownLookup } from './utils.js';
 import * as whereMod from './where.js';
 /**
  * Enforce the PII contract on the aggregate surface. A PII-tagged
@@ -232,8 +233,8 @@ export function buildGroupBy(qi, args) {
     // no `$n` renumbering. `offset` without a deterministic `orderBy` yields an
     // arbitrary window (same caveat as findMany).
     if (args.limit !== undefined || args.offset !== undefined) {
-        const limitPh = args.limit !== undefined ? qi.paginationRef(args.limit, params) : undefined;
-        const offsetPh = args.offset !== undefined ? qi.paginationRef(args.offset, params) : undefined;
+        const limitPh = args.limit !== undefined ? qi.paginationRef(args.limit, params, 'limit') : undefined;
+        const offsetPh = args.offset !== undefined ? qi.paginationRef(args.offset, params, 'skip/offset') : undefined;
         sql += qi.buildPagination(limitPh, offsetPh, args.orderBy !== undefined);
     }
     return {
@@ -513,7 +514,10 @@ export function buildHavingClauses(qi, having, params, jsonAggExprs) {
         for (const [aggKey, filter] of Object.entries(value)) {
             if (filter === undefined)
                 continue;
-            const fn = aggFnByKey[aggKey];
+            // ownLookup, not a bare index: an inherited Object.prototype member
+            // ("constructor", "toString", …) would otherwise resolve to a truthy
+            // builtin and be spliced into the HAVING clause as its source text.
+            const fn = ownLookup(aggFnByKey, aggKey);
             if (!fn) {
                 throw new ValidationError(`[turbine] Unknown aggregate "${aggKey}" in having for field "${key}" on table "${qi.table}". ` +
                     `Supported: ${Object.keys(aggFnByKey).join(', ')}.`);