@aventara/prisma7-adapter 0.1.0-pilot.3 → 0.1.0-pilot.4

package/dist/translation/operation.translator.d.ts

@@ -1,85 +1,6 @@
 import type { AdapterModel, AdapterOperation } from "@aventara/core";
 import type { PrismaResourceTranslation } from "../discovery/discovery-artifact.interface.js";
 import { type PrismaProjectionPlan } from "./projection.translator.js";
-/**
- * Splitting translation from execution is the plan's single largest testability
- * decision: everything below is a pure function of the discovered model, the
- * generate-time translation table and the arguments core validated. The database
- * is needed only for the *other* half, `execution/operation.executor.ts`.
- *
- * # The dispatch table is the module
- *
- * {@link PRISMA_VARIANT_DISPATCH} is total over core's own sixteen
- * `family.variant` keys by `satisfies`, so a seventeenth standard operation added
- * to core is a compile error here rather than a variant that quietly reaches no
- * provider call. Reading it answers, in one place, every question of the form
- * "what does Aventara's X actually issue".
- *
- * # The negative half of the table is the load-bearing half
- *
- * Aventara is not an ORM and reaches the database only through the adapter's ORM;
- * a raw statement would forfeit the ORM's own injection protection and oblige
- * Aventara to build its own. Because the exclusion lives in the *type*, a raw call
- * is not representable in a {@link PrismaExecutionPlan} at all: the rule is
- * enforced by the compiler, not by a reviewer's memory.
- * `operation.translator.spec.ts` asserts the same thing from the value side, as
- * the belt to that type's braces.
- *
- * # `delete.many` is a hole in the table, and the hole is the decision
- *
- * `operations.deriver.ts` therefore never advertises it, so core rejects the
- * request with `A2002 UNKNOWN_OPERATION` before any adapter call. The table still
- * carries the key — it is total over core's grammar — with an `"unavailable"`
- * entry, so the omission is a fact a reader can find rather than an absence they
- * have to infer.
- *
- * # First-style variants, and the write route
- *
- * `update.first` and `delete.first` are **framework-manufactured**: a cross-ORM
- * survey found the four-part shape — general filter, ordering decides "first",
- * effect limited to one row, the affected row is returned, all in one call —
- * essentially absent across ORM design, and Prisma 7.10.0 has no
- * `updateFirst`/`deleteFirst` **[PKG]**. So the plan is an ordinary read then
- * write, and its two steps are {@link PrismaExecutionPlan}'s `"emulated"` arm.
- *
- * Every row came out for Route A, and two of them came out *against* Route B:
- *
- * ```text
- * measured 2026-10-02, @prisma/client 7.10.0, SQLite + PostgreSQL 18, identical
- *
- * A  update({ where: { id, AND: […] }, data, select })          -> returned the row
- * A  …with a non-matching AND                                   -> threw P2025, row untouched
- * A  …select reaching a to-many relation AND _count             -> returned both
- * A  delete({ where: { id, AND: […] }, select })                -> returned the deleted row
- * A  …with a non-matching AND                                   -> threw P2025, row still present
- * A  findFirst + update inside $transaction, non-matching AND   -> threw P2025 at the emulator's own call site
- * B  updateManyAndReturn({ where: { id, AND: […] }, … })        -> returned [row]
- * B  …with a non-matching AND                                   -> resolved []
- * B  …select: { posts: { … } }                                  -> REJECTED: "Unknown field `posts` for select
- *                                                                  statement on model `UpdateManyAuthorAndReturnOutputType`"
- * B  …select: { _count: { … } }                                 -> REJECTED: same, for `_count`
- * B  deleteMany({ where: { id, AND: […] } })                    -> { count: 1 } — carries no row at all
- * ```
- *
- * Route B cannot serve a caller projection that reaches a to-many relation or
- * `$count` at all, and its `delete.first` must read before it writes.
- *
- * # The write step of an emulated plan is a template, and says so
- *
- * A `"single"` plan's call is issuable as written. An `"emulated"` plan's write
- * step is **not**, by construction: its `where` carries the caller's re-asserted
- * predicate under `AND` and the identifier is added by
- * `execution/first-variant.emulator.ts` from the row the read returned. That is
- * what "emulated" means — the second statement is not knowable until the first has
- * run — and it is why the emulator, not this module, issues it.
- *
- * Every key below is added only when the corresponding Aventara argument is
- * **present**. An absent argument and an `undefined` one are different arguments
- * to a provider, so `"take" in args` is never made true by accident. An argument
- * this module does not recognise raises rather than being dropped: an argument
- * that typechecks and is silently ignored is worse than an absent one, because the
- * absent one fails loudly at the caller.
- */
 /** The `ModelAction` subset this adapter uses. See the header for the exclusions. */
 export type PrismaAction = "findUnique" | "findFirst" | "findMany" | "count" | "create" | "createMany" | "createManyAndReturn" | "update" | "updateMany" | "updateManyAndReturn" | "delete" | "deleteMany" | "upsert";
 /** One provider call description, as plain data. */
@@ -93,7 +14,6 @@ export type PrismaCall = {
     readonly action: PrismaAction;
     readonly args: Readonly<Record<string, unknown>>;
 };
-/** A variant is either one call, or an emulated sequence. */
 export type PrismaExecutionPlan = {
     readonly kind: "single";
     readonly call: PrismaCall;
@@ -102,13 +22,6 @@ export type PrismaExecutionPlan = {
     readonly steps: readonly PrismaCall[];
     readonly atomicity: "outer-tx" | "own-tx";
 };
-/**
- * What the variant owes its caller, and therefore which shaper runs.
- *
- * It is a property of the *variant*, not of the provider answer, so it belongs in
- * the dispatch table beside the action rather than in a second table the executor
- * would have to keep in step.
- */
 export type PrismaResultKind = "row" | "rows" | "count";
 export type PrismaVariantDispatch = {
     readonly kind: "single";
@@ -123,7 +36,6 @@ export type PrismaVariantDispatch = {
     readonly kind: "unavailable";
     readonly reason: string;
 };
-/** The sixteen-variant dispatch table, total over core's grammar. */
 export declare const PRISMA_VARIANT_DISPATCH: {
     readonly "find.first": {
         readonly kind: "single";
@@ -211,23 +123,10 @@ export declare const PRISMA_VARIANT_DISPATCH: {
 export declare class PrismaOperationTranslationError extends Error {
     readonly name = "PrismaOperationTranslationError";
 }
-/**
- * The translation of one operation: the plan, plus the projection plan the result
- * shaper needs.
- *
- * Returning it beside the plan is what keeps `result.shaper.ts` free of a second,
- * drifting reconstruction.
- */
 export type PrismaOperationTranslation = {
     readonly plan: PrismaExecutionPlan;
     readonly projection: PrismaProjectionPlan;
-    /**
-     * The caller's `where`, translated, or `undefined` when they sent none.
-     *
-     * Recorded for the emulator, which re-asserts it on the write. It is the same
-     * value the read step carries, by identity, so the two halves of the manufacture
-     * cannot assert different predicates.
-     */
+    /** The caller's `where`, translated, or `undefined` when they sent none. */
     readonly predicate: Readonly<Record<string, unknown>> | undefined;
 };
 export type PrismaOperationTranslationInput = {

package/dist/translation/order-pagination.translator.d.ts

@@ -1,21 +1,5 @@
 import { type AdapterModel } from "@aventara/core";
 import type { PrismaIdentifierAddress } from "../discovery/discovery-artifact.interface.js";
-/**
- * Pure functions over plain data: no client, no database, no provider name.
- *
- * The public names are `limit`, `offset` and `cursor`. `take` and `skip` are
- * Prisma's and appear nowhere in this adapter's public types — they are produced
- * here and nowhere else. The tables below are TOTAL over core's own unions, so a
- * pagination capability or a reducer added to core with no emission site is a
- * compile error.
- *
- * # An absent argument and an `undefined` one are different arguments
- *
- * `take: undefined` is a present key with no value, and `"take" in args` is what a
- * provider sees. Every key below is added only when its Aventara argument is
- * present, which is also why `0` is carried through rather than tested for
- * truthiness.
- */
 /** An order or cursor the discovered model does not license. */
 export declare class PrismaOrderTranslationError extends Error {
     readonly name = "PrismaOrderTranslationError";
@@ -27,37 +11,7 @@ export type PrismaPaginationArguments = Readonly<Record<string, unknown>>;
 export type PaginationTranslation = {
     readonly limit?: number;
     readonly offset?: number;
-    /**
-     * The Aventara cursor: the active ordered scalar fields and their values.
-     *
-     * **Only the identifier subset is emitted, and that is faithful translation rather
-     * than a silent drop.** Settled 2026-10-02; do not re-open without reading
-     * `validateCursor` first.
-     *
-     * Core's `CursorInput` type is `Partial<Record<ScalarFieldKey, unknown>>`, which
-     * reads as permissive, but `operation-validator-core.ts`'s `validateCursor` pins
-     * it exactly: the cursor's keys must **equal** the active ordered scalar fields,
-     * and `orderBy` must include a complete Resource identifier as a tie-breaker. So
-     * the non-identifier keys are not optional context a caller happened to send —
-     * core requires every one of them, and has already verified they match `orderBy`.
-     *
-     * Prisma's `cursor` is a `<M>WhereUniqueInput`: it locates a *row*, and the
-     * ordering comes from `orderBy`, which this module translates alongside. The
-     * identifier therefore determines the position completely, and the remaining
-     * ordered keys are already expressed in the emitted `orderBy`.
-     *
-     * Two things follow, both load-bearing. Passing the extra keys through would make
-     * them equality members of a where-unique, *narrowing* the lookup: a key whose
-     * value no longer matches the stored row would resolve the cursor to nothing and
-     * return an empty page instead of a correct one. And narrowing core's
-     * `CursorInput` to the identifier — considered and rejected — would break the
-     * determinism contract `validateCursor` enforces, since core needs the full
-     * ordered set to know the position is unambiguous.
-     *
-     * The type is loose because the Contract is passive data; the precision lives in
-     * the validator. That is the pattern throughout `operation-arguments.ts`, and
-     * reading the type without its validator is how this was briefly mis-analysed.
-     */
+    /** The Aventara cursor: the active ordered scalar fields and their values. */
     readonly cursor?: Readonly<Record<string, unknown>>;
     /**
      * The Resource's Prisma addressing, from the generate-time translation table.

package/dist/translation/projection.translator.d.ts

@@ -1,51 +1,11 @@
 import type { RelationReducer } from "@aventara/core";
-/**
- * **What arrives here is core's plan, not a caller's request.** By the time an
- * `AdapterOperation` reaches the adapter, `planReadOperation` has resolved
- * `include` into `select`, expanded every relation it could resolve into object
- * form, and dropped VIRTUAL scalars from the adapter's half while keeping them in
- * the projection plan it validates against **[CORE,
- * runtime/computed-read-runtime.ts]**. So this module reads one shape: `select` as
- * an array whose entries are field-name strings, the reducer string `"$count"`, or
- * single-key objects carrying a relation's own arguments beside a nested `select`.
- *
- * **Three translations are worth stating because they are not obvious:**
- *
- * 1. A reconstructed list would have to be derived from the model and would drift
- *    from it; this cannot.
- * 2. Since the two emissions coincide, the translator needs no model lookup to
- *    tell a scalar from a relation — and therefore cannot get that lookup wrong.
- * 3. *`$count` is lifted to the level that owns the edge.* Aventara writes the
- *    reducer inside the relation's own `select`; Prisma writes it in the PARENT's
- *    `select`, under `_count`. The `where` placed in `_count` is the relation's
- *    *translated* `where` and carries no pagination, which is what makes `count`
- *    the total matching the nested `where` before limit/offset/cursor.
- *
- * Measured against real databases on both engines — `@prisma/client` 7.10.0,
- * `_count: { select: { posts: { where } } }` beside `posts: { where, take, skip }`
- * — the count was `3` in every case while the row set was `3`, `1`, `2`, `1` and
- * `1` for no pagination, `take: 1`, `skip: 1`, `take: 1 + skip: 1` and `take: 2 +
- * skip: 2`, and `3` again with `cursor + take: 1`. SQLite and PostgreSQL agreed
- * exactly. The filtered-count claim ("since 4.3.0") was re-measured in the same
- * run: `_count` of the same edge answered `5` unfiltered and `3` with the `where`.
- *
- * Injecting the seam also makes the `_count` filter the *same* translated `where`
- * the relation read uses, rather than a second translation of the same predicate
- * that could drift from it.
- */
-/** Core's own word for the reducer set, so the adapter cannot invent a second one. */
 export type PrismaRelationProjection = {
     readonly field: string;
     /** Non-empty exactly when the edge requested a reducer. */
     readonly reducers: readonly RelationReducer[];
-    /** Whether any row field was requested beside the reducer. */
     readonly rows: boolean;
     readonly projection: PrismaProjectionPlan;
 };
-/**
- * It records only the edges that need reshaping — an edge with no reducer anywhere
- * beneath it is absent, which is what lets the shaper return such a row untouched.
- */
 export type PrismaProjectionPlan = {
     readonly relations: readonly PrismaRelationProjection[];
 };
@@ -66,16 +26,11 @@ export type PrismaProjectionTranslation = {
     readonly args: Readonly<Record<string, unknown>>;
     readonly plan: PrismaProjectionPlan;
 };
-/**
- * A projection the adapter will not translate.
- */
+/** A projection the adapter will not translate. */
 export declare class PrismaProjectionTranslationError extends Error {
     constructor(reason: string, path: readonly string[]);
 }
 /**
- * Translates core's planned projection into the Prisma projection arguments and
- * the plan the result shaper needs to place every `$count` envelope.
- *
  * @throws {PrismaProjectionTranslationError} for a projection the adapter will
  * not translate rather than silently reinterpret.
  */

package/dist/translation/scalar.conversion.d.ts

@@ -1,68 +1,4 @@
 import { type AdapterField, type AdapterModel } from "@aventara/core";
-/**
- * # Why this is a module and not three private helpers
- *
- * Three consumers cross the same boundary with the same values: a write's `data`
- * (`mutation.translator.ts`), a filter operand (`where.translator.ts`) and a row
- * coming back (`execution/result.shaper.ts`). The emission table was born inside
- * the mutation translator, which is where the first of the three needed it; a copy
- * in each consumer would be three places to answer "what does a `decimal` look
- * like on the wire", and the second copy to drift would be the one nobody reads.
- *
- * The table is TOTAL over core's `BuiltInScalar` by a mapped type, so a tenth
- * scalar added to the protocol is a compile error here rather than a value that
- * silently crosses unconverted in one direction only.
- *
- * # `decimal` is the one real conversion, and that is measured
- *
- * Eight of the nine scalars pass through in both directions, re-measured on both
- * driver adapters at `@prisma/client` 7.10.0 (2026-10-02): a `bigint` primitive, a
- * `Date` and a `Uint8Array` are what the generated input types accept and what a
- * read returns (`Buffer.isBuffer(v) === false`, `v instanceof Uint8Array ===
- * true`), `Json` is written and returned as a plain object (its prototype IS
- * `Object.prototype`, which is what core's own `isPlainRecord` output check
- * requires **[CORE, runtime/scalar-runtime.ts]**), and an enum member is its own
- * name on both sides. Those are the same forms core's runtime scope requires
- * (`normalizeScalarAtom`'s `"application"` branch), so a pass-through is a
- * decision, not an omission.
- *
- * Neither accepts the other, so the crossing is a real conversion both ways: out,
- * the base-10 string; in, core's own `Decimal`.
- *
- * # Outbound: three different failures, none of them a type error
- *
- * Passing core's `Decimal` through unconverted fails *differently* depending on
- * where it lands, and none of the three is a plain rejection (measured on both
- * engines, 2026-10-02):
- *
- * - as a **write value**: refused at the wire — *"Invalid value for argument
- *   `toString`: We could not serialize [object Function] value."*;
- * - as a **comparison operand** (`gt`, `equals`, …): read as a **FieldRef**, not
- *   as a value — *"PrismaClientValidationError: Argument `_ref` is missing."*;
- * - as a **bare equality operand**: *accepted*, and silently wrong. Core's
- *   `Decimal` keeps its digits in a private field, so `Object.keys` is empty and
- *   Prisma reads the object as an **empty `DecimalFilter`** — `findMany` returned
- *   **2 of 2** rows, byte-identical to passing no predicate at all, where the
- *   string `"1"` returned 1. A misinterpretation that validates is the failure
- *   this module exists to make impossible.
- *
- * # Inbound: the value core's output validator will accept
- *
- * Core validates adapter output in its `"runtime"` scope, which requires the
- * *runtime* form of every scalar — `value instanceof Decimal` for a decimal
- * **[CORE, runtime/output-validator.ts → normalizeScalarFieldValue]**. A
- * `Decimal2` is not one, so an unconverted read fails core's own validation and
- * the caller is told `A3000`.
- *
- * # The scalar identity comes from the model, never from the value
- *
- * Both directions are keyed by the field's discovered scalar, never by the runtime
- * shape of the value. A `Json` column holding `{ "x": 1 }` and a `Decimal`
- * reaching Prisma are both "an object", and a `Json` column holding the string
- * `"12.5"` is indistinguishable from a decimal string: shape-sniffing would
- * convert one of those sooner or later, and silently. The discovered model already
- * knows, so it is asked.
- */
 /** A value this adapter will not convert rather than misrepresent. */
 export declare class PrismaScalarConversionError extends Error {
     readonly name = "PrismaScalarConversionError";

package/dist/translation/where.translator.d.ts

@@ -1,56 +1,4 @@
 import type { AdapterModel } from "@aventara/core";
-/**
- * # Pure, and that is the property to protect
- *
- * No client, no database, no I/O, no provider name. The only inputs are the
- * discovered model and plain data, which is what makes the whole filter grammar
- * exhaustively testable without an engine.
- *
- * # One direction, and no Prisma token the framework did not ask for
- *
- * Every emitted key comes from one of the two tables below, both of which are
- * TOTAL over core's own capability unions — a member added to
- * `ScalarFilterOperator` or `RelationFilterCapability` with no row here is a
- * compile error, not a silently dropped predicate.
- *
- * The inverse matters more. A missing key loses a predicate and shows up as a
- * wrong row count; an INVENTED key silently changes what the query means. So
- * nothing is ever added to the output that the request did not carry: no `equals`
- * wrapper around a bare value, no `is`/`isNot` wrapper around a to-one predicate,
- * no `mode` nobody asked for.
- *
- * A predicate is a key AND an operand, and the operand is a value of the field's
- * scalar type. Those values go out through `scalar.conversion.ts`, the one table
- * that knows how each scalar crosses — the same answers `mutation.translator.ts`
- * uses for a write, because it is the same boundary. {@link
- * SCALAR_FILTER_EMISSIONS} records, per operator, *whether* its operand is such a
- * value: `in` carries a list of them, `isEmpty` carries a boolean, `mode` carries
- * a Prisma keyword, and `path`/`string*`/`array*` carry a position inside a JSON
- * document rather than a value of the column. Converting indiscriminately would
- * corrupt the second kind; converting none of them is what let a core `Decimal`
- * reach Prisma, where it was not rejected but **misread** (measured on both
- * engines, 2026-10-02):
- *
- * - `{ sDecimal: { gt: new Decimal("1") } }` → *"PrismaClientValidationError:
- *   Argument `_ref` is missing."* — Prisma read the object as a **FieldRef**;
- * - `{ sDecimal: new Decimal("1") }` → **no error and 2 of 2 rows**, the same as
- *   no predicate at all, because core's `Decimal` keeps its digits in a private
- *   field and `Object.keys` is therefore empty: Prisma read an **empty
- *   `DecimalFilter`**. The string `"1"` returned 1 row.
- *
- * The second is why the bare-value branch below follows core's own discriminant —
- * `isPlainRecord`, not "is an object" **[CORE, runtime/scalar-runtime.ts
- * `normalizeScalarFilter`]**. A class instance is a VALUE; reading one as an
- * operator record produced `{}`, and an empty filter constrains nothing.
- *
- * # Refusing is part of honouring
- *
- * The adapter assumes validated input and performs no limit checking. It does,
- * however, refuse to EMIT an operator the discovered model does not advertise for
- * that field. Core has already rejected such a request with `V1006`; if one ever
- * arrives here, the model and the Contract have diverged and that is a defect, not
- * a query.
- */
 /** A predicate the model does not license, or a key no vocabulary recognises. */
 export declare class PrismaWhereTranslationError extends Error {
     readonly name = "PrismaWhereTranslationError";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/prisma7-adapter",
-  "version": "0.1.0-pilot.3",
+  "version": "0.1.0-pilot.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The Prisma 7 adapter for Aventara.",
   "type": "module",
@@ -29,7 +29,7 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.3"
+    "@aventara/core": "0.1.0-pilot.4"
   },
   "peerDependencies": {
     "@prisma/adapter-better-sqlite3": "^7.10.0",