turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/powql.js

@@ -143,6 +143,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) {
@@ -242,7 +257,7 @@ 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 powdb_js_1.PowdbJsonParam(value);
+            tagged = new powdb_js_1.PowdbJsonParam(value, col.name);
         }
         params.push(tagged);
         return `$${params.length}`;
@@ -2496,6 +2511,11 @@ 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)
@@ -2505,10 +2525,19 @@ 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)) {
@@ -2518,11 +2547,18 @@ 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 errors_js_1.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/cjs/prisma-compat.d.ts

@@ -0,0 +1,283 @@
+/**
+ * turbine-orm/prisma-compat, a typed PrismaClient-surface adapter over a
+ * {@link TurbineClient}.
+ *
+ * This subpath lets a codebase that speaks Prisma's `db.model.findMany(...)`
+ * surface run on Turbine with minimal churn. It is a **pure TypeScript shim**:
+ * zero new runtime dependencies, never imported by Turbine core, and driven
+ * entirely by the {@link PrismaCompatMap} that `turbine migrate-from-prisma`
+ * emits (`prisma-map.ts`). Every Prisma model / field / relation / compound
+ * unique name in the map was resolved against live introspected metadata, so
+ * the adapter only ever translates names it can prove exist.
+ *
+ * ## What it does
+ *
+ * - **Model delegates** under both the Prisma model name (`compat.User`) and
+ *   Prisma's client-property spelling with the first letter lowercased
+ *   (`compat.user`, what generated Prisma call sites actually use),
+ *   translating args recursively: `include`→`with`, `select` split into scalar
+ *   selection + relations, field/relation renames both ways through the map,
+ *   `take`/`skip`→`limit`/`offset`, cursor pagination, and compound-unique
+ *   selectors (including custom `@@unique(name:)` names the core `findUnique`
+ *   derivation cannot know).
+ * - **`$transaction`** in both forms: a callback (`$transaction(async (tx) => …)`)
+ *   and Prisma's lazy array batching (`$transaction([a.create(...), b.update(...)])`)
+ *  , the un-awaited delegate calls defer to Turbine's `build*()` methods and
+ *   run atomically through the core batch `$transaction([...])` path.
+ * - **Raw SQL**: `$queryRaw` / `$executeRaw` tagged templates (with
+ *   `Prisma.sql`-style nested-fragment flattening) and the `*Unsafe` variants.
+ * - **Result reshaping**: `_count` objects keyed back to Prisma relation names,
+ *   and to-one relations surfaced as `object | null`.
+ *
+ * ## What it deliberately does NOT do (documented divergences)
+ *
+ * These cannot be faithfully translated and are not attempted; each throws or is
+ * documented rather than silently returning wrong data:
+ *
+ * - `$extends` / client extensions, `$use` with Prisma's middleware param shape.
+ * - `instanceof PrismaClientKnownRequestError`, `.meta`/message byte parity
+ *   (opt into `prismaErrorCodes` for a `.code` like `P2002`, without pretending
+ *   `instanceof` identity).
+ * - `Prisma.join` / `Prisma.raw` composition beyond plain fragment flattening.
+ * - Fluent relation chaining (`prisma.user.findUnique().posts()`).
+ * - Accelerate / Pulse / driver-adapter preview features, the Mongo API, and the
+ *   `prisma migrate`/`db` CLI family (Turbine ships its own migrations).
+ * - **Inclusive bare cursors whose field is not the sort key**, see
+ *   {@link translateCursor}. A bare Prisma cursor is inclusive; translating it
+ *   correctly needs the anchor row's sort-key value. When the cursor field is
+ *   the single `orderBy` field (or the cursor is the single-column PK with no
+ *   `orderBy`) it compiles to a `gte`/`lte` keyset predicate; **otherwise it
+ *   throws** an {@link UnsupportedFeatureError} rather than emit an off-by-one
+ *   page. Pair the cursor with `skip: 1` (Prisma's idiom) for the exact
+ *   exclusive-cursor + `offset` translation.
+ * - **Negative `take`** (take-from-end) and **`skip` on a nested relation
+ *   include** throw, Turbine's `with` clause has no offset and no reverse-take.
+ *
+ * ## Type dependencies (0.41.0)
+ *
+ * - Field-name identity fast path pairs with the generator's
+ *   `--keep-column-names` output (byte-shaped like a snake_case Prisma client).
+ * - Compound-unique default selectors are handled by the core
+ *   `findUnique`-family derivation; this adapter only translates custom
+ *   `@@unique(name:)` names on top.
+ * - To-one relations return `object | null` natively once the unique-FK hasOne
+ *   introspection default is in effect (0.41.0). Until a schema is regenerated,
+ *   the map's `cardinality: 'one'` still drives the first-element-or-null guard,
+ *   so the surface is correct either way.
+ *
+ * @example
+ * ```ts
+ * import { TurbineClient } from 'turbine-orm';
+ * import { createPrismaCompatClient } from 'turbine-orm/prisma-compat';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ * import { PRISMA_MAP } from './generated/turbine/prisma-map.js';
+ *
+ * const db = new TurbineClient({ connectionString: process.env.DATABASE_URL }, SCHEMA);
+ * const prisma = createPrismaCompatClient(db, PRISMA_MAP);
+ *
+ * const users = await prisma.User.findMany({
+ *   where: { email: { contains: '@acme.com' } },
+ *   include: { posts: { orderBy: { createdAt: 'desc' }, take: 5 } },
+ * });
+ * ```
+ */
+import type { TurbineClient } from './client.js';
+import type { DeferredQuery } from './query/index.js';
+import type { PrismaCompatMap, SchemaMetadata } from './schema.js';
+/** A build-only query object with the `build*` methods the adapter drives. */
+export interface CompatQueryInterface {
+    findMany(args?: Record<string, unknown>): Promise<unknown>;
+    findFirst(args?: Record<string, unknown>): Promise<unknown>;
+    findUnique(args: Record<string, unknown>): Promise<unknown>;
+    findFirstOrThrow(args?: Record<string, unknown>): Promise<unknown>;
+    findUniqueOrThrow(args: Record<string, unknown>): Promise<unknown>;
+    create(args: Record<string, unknown>): Promise<unknown>;
+    createMany(args: Record<string, unknown>): Promise<unknown[]>;
+    update(args: Record<string, unknown>): Promise<unknown>;
+    updateMany(args: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    delete(args: Record<string, unknown>): Promise<unknown>;
+    deleteMany(args: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    upsert(args: Record<string, unknown>): Promise<unknown>;
+    count(args?: Record<string, unknown>): Promise<number>;
+    aggregate(args: Record<string, unknown>): Promise<unknown>;
+    groupBy(args: Record<string, unknown>): Promise<unknown[]>;
+    buildFindMany(args?: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindFirst(args?: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindUnique(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindFirstOrThrow(args?: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindUniqueOrThrow(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildCreate(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildCreateMany(args: Record<string, unknown>): DeferredQuery<unknown[]>;
+    buildUpdate(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildUpdateMany(args: Record<string, unknown>): DeferredQuery<{
+        count: number;
+    }>;
+    buildDelete(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildDeleteMany(args: Record<string, unknown>): DeferredQuery<{
+        count: number;
+    }>;
+    buildUpsert(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildCount(args?: Record<string, unknown>): DeferredQuery<number>;
+    buildAggregate(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildGroupBy(args: Record<string, unknown>): DeferredQuery<unknown[]>;
+}
+/** A transaction-scoped client handed to a `$transaction(callback)`. */
+export interface CompatTransactionClient {
+    table(name: string): CompatQueryInterface;
+}
+/** The minimal `TurbineClient` surface the adapter consumes. */
+export interface CompatTurbineClient extends CompatTransactionClient {
+    readonly schema: SchemaMetadata;
+    $transaction<R>(fn: (tx: CompatTransactionClient) => Promise<R>, options?: unknown): Promise<R>;
+    $transaction(queries: readonly DeferredQuery<unknown>[]): Promise<unknown[]>;
+}
+declare const SQL_FRAGMENT: unique symbol;
+/** A composable SQL fragment, the local stand-in for `Prisma.Sql`. */
+export interface Sql {
+    /** Literal string segments; `strings.length === values.length + 1`. */
+    readonly strings: readonly string[];
+    /** Interpolated values, one between each pair of `strings`. */
+    readonly values: readonly unknown[];
+    readonly [SQL_FRAGMENT]: true;
+}
+/**
+ * `Prisma`-compatible raw-SQL helpers, a minimal local implementation so
+ * migrated `Prisma.sql\`…\`` / `Prisma.join(...)` / `Prisma.raw(...)` calls keep
+ * composing. Fragments are flattened at execution time into a single
+ * parameterized statement (values become `$N`), so composition is injection-safe
+ * by construction.
+ */
+export declare const Prisma: {
+    /** Tagged-template fragment: `Prisma.sql\`id = ${id}\``. */
+    sql(strings: TemplateStringsArray, ...values: unknown[]): Sql;
+    /**
+     * Join fragments/values with a separator: `Prisma.join([1, 2, 3])` →
+     * `$1, $2, $3`. Each element that is not already a fragment becomes a bound
+     * value.
+     */
+    join(items: readonly unknown[], separator?: string, prefix?: string, suffix?: string): Sql;
+    /**
+     * A raw, unparameterized SQL fragment. The string is spliced verbatim, never
+     * pass user input here (matches Prisma's `Prisma.raw` contract).
+     */
+    raw(sql: string): Sql;
+    /** An empty fragment. */
+    empty: Sql;
+};
+/** Options for {@link createPrismaCompatClient}. */
+export interface PrismaCompatOptions {
+    /**
+     * When `true`, every to-many `with` relation lacking an explicit `orderBy` is
+     * loaded ordered by the target table's primary key ascending (Prisma's
+     * relation rows come back in a stable order). This passes through to Turbine's
+     * core `stableRelationOrder` flag, it never re-walks the `with` tree. An
+     * explicit per-relation `orderBy` always wins. Default `false`.
+     */
+    stablePkOrder?: boolean;
+    /**
+     * When `true`, thrown {@link TurbineError}s are decorated with a `.code` equal
+     * to the nearest Prisma error code (e.g. `P2002` for a unique violation),
+     * WITHOUT pretending `instanceof PrismaClientKnownRequestError`. Default
+     * `false` (Turbine's own `TURBINE_E0NN` codes are preserved untouched).
+     */
+    prismaErrorCodes?: boolean;
+}
+/** Symbol under which a lazy delegate call exposes its batchable plan. */
+export declare const COMPAT_DEFERRED: unique symbol;
+/**
+ * The per-model type bundle a consumer supplies to type a model delegate.
+ * Populate `Row` (and optionally the arg shapes) from the generated entity
+ * types; unspecified members fall back to permissive shapes.
+ */
+export interface PrismaModelTypes {
+    Row: object;
+    Create?: object;
+    Update?: object;
+    Where?: object;
+    OrderBy?: object;
+    Select?: object;
+    Include?: object;
+}
+type Args = Record<string, unknown>;
+/** A typed model delegate mirroring Prisma's `db.model.*` surface. */
+export interface PrismaModelDelegate<M extends PrismaModelTypes> {
+    findMany(args?: Args): Promise<M['Row'][]>;
+    findFirst(args?: Args): Promise<M['Row'] | null>;
+    findUnique(args: Args): Promise<M['Row'] | null>;
+    findFirstOrThrow(args?: Args): Promise<M['Row']>;
+    findUniqueOrThrow(args: Args): Promise<M['Row']>;
+    create(args: Args): Promise<M['Row']>;
+    createMany(args: Args): Promise<{
+        count: number;
+    }>;
+    update(args: Args): Promise<M['Row']>;
+    updateMany(args: Args): Promise<{
+        count: number;
+    }>;
+    delete(args: Args): Promise<M['Row']>;
+    deleteMany(args?: Args): Promise<{
+        count: number;
+    }>;
+    upsert(args: Args): Promise<M['Row']>;
+    count(args?: Args): Promise<number>;
+    aggregate(args: Args): Promise<Record<string, unknown>>;
+    groupBy(args: Args): Promise<Record<string, unknown>[]>;
+}
+/** The client-level surface (`$transaction` / raw), added to the model map. */
+export interface PrismaCompatClientBase<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>> {
+    $transaction<R>(fn: (tx: PrismaCompatTransactionClient<S>) => Promise<R>, options?: PrismaCompatTxOptions): Promise<R>;
+    $transaction<P extends readonly PromiseLike<unknown>[]>(promises: readonly [...P]): Promise<{
+        [K in keyof P]: Awaited<P[K]>;
+    }>;
+    $queryRaw<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    $queryRawUnsafe<T = unknown>(sql: string, ...params: unknown[]): Promise<T[]>;
+    $executeRaw(strings: TemplateStringsArray, ...values: unknown[]): Promise<number>;
+    $executeRawUnsafe(sql: string, ...params: unknown[]): Promise<number>;
+    $connect(): Promise<void>;
+    $disconnect(): Promise<void>;
+}
+/** Options accepted by the callback form of `$transaction`. */
+export interface PrismaCompatTxOptions {
+    isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable';
+    timeout?: number;
+    maxWait?: number;
+}
+/** The transaction-scoped client handed to a `$transaction(callback)`. */
+export type PrismaCompatTransactionClient<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>> = {
+    [K in keyof S]: PrismaModelDelegate<S[K]>;
+};
+/**
+ * The full typed compat client: a model delegate per Prisma model name, plus the
+ * client-level `$transaction` / raw surface. Parameterize `S` with your
+ * generated entity types for full autocompletion.
+ */
+export type PrismaCompatClient<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>> = {
+    [K in keyof S]: PrismaModelDelegate<S[K]>;
+} & {
+    [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
+ * migrate-from-prisma` emits).
+ *
+ * The returned object exposes a delegate per Prisma model name (by the map's
+ * keys) plus the client-level `$transaction` / `$queryRaw` / `$executeRaw`
+ * surface. Model and field names are translated through the map in both
+ * directions; when field names are identity (the `--keep-column-names` pairing)
+ * result rekeying is skipped entirely.
+ *
+ * @typeParam S - Per-model type bundles (from your generated entity types) for
+ *   full autocompletion. Defaults to a permissive shape.
+ * @param client - The TurbineClient (or generated subclass / `turbineHttp` client).
+ * @param map - The resolved `PRISMA_MAP`.
+ * @param options - {@link PrismaCompatOptions}.
+ */
+export declare function createPrismaCompatClient<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>>(client: TurbineClient, map: PrismaCompatMap, options?: PrismaCompatOptions): PrismaCompatClient<S>;
+export {};

package/dist/cjs/prisma-compat.js

@@ -83,9 +83,10 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMPAT_DEFERRED = exports.Prisma = void 0;
+exports.CLIENT_RESERVED_KEYS = exports.COMPAT_DEFERRED = exports.Prisma = void 0;
 exports.createPrismaCompatClient = createPrismaCompatClient;
 const errors_js_1 = require("./errors.js");
+const warn_registry_js_1 = require("./query/warn-registry.js");
 // ---------------------------------------------------------------------------
 // Prisma.sql-style raw fragments (local, minimal, never imports @prisma/client)
 // ---------------------------------------------------------------------------
@@ -403,7 +404,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);
@@ -428,9 +429,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;
@@ -1043,11 +1120,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')
@@ -1185,6 +1262,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. */
+exports.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(exports.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' && (0, warn_registry_js_1.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
@@ -1220,9 +1370,17 @@ 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);
@@ -1275,7 +1433,7 @@ 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)) {