@aventara/prisma7-adapter 0.1.0-pilot.0 → 0.1.0-pilot.2

package/dist/translation/scalar.conversion.js

@@ -1,97 +1,14 @@
 import { Decimal, } from "@aventara/core";
-/**
- * C-834 — the scalar value conversion, in **one** table and **both**
- * directions.
- *
- * # 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. {@link SCALAR_BOUNDARY_CROSSINGS} is therefore the single owner, and
- * Task 10's `identifier.addressing.ts` is the precedent — extracted for exactly
- * this reason.
- *
- * 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.
- *
- * `decimal` is the exception §6.2 names: *the public `Decimal` MUST NOT be
- * `Prisma.Decimal`*, and it is not — core's `Decimal` is a class with one
- * private `#value` and a `toString`, while Prisma's is its bundled decimal.js,
- * whose constructor is named `Decimal2`. 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`. Converting here is therefore not a courtesy: it is
- * the adapter's half of §6.2.
- *
- * # 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 class PrismaScalarConversionError extends Error {
     name = "PrismaScalarConversionError";
 }
 function identity(value) {
     return value;
 }
-/** A scalar whose Prisma representation IS its Aventara runtime form. */
 const PASS_THROUGH = {
     outbound: identity,
     inbound: identity,
 };
-/**
- * What each Aventara scalar becomes on the way to Prisma and on the way back.
- *
- * Total over `BuiltInScalar`: a scalar added to the protocol cannot reach a
- * provider until both of its directions are decided here.
- */
 const SCALAR_BOUNDARY_CROSSINGS = {
     string: PASS_THROUGH,
     boolean: PASS_THROUGH,
@@ -103,16 +20,6 @@ const SCALAR_BOUNDARY_CROSSINGS = {
     bytes: PASS_THROUGH,
     json: PASS_THROUGH,
 };
-/**
- * Core's `Decimal` → the base-10 string every Prisma decimal input accepts
- * (`DecimalFieldUpdateOperationsInput` takes `runtime.Decimal | DecimalJsLike |
- * number | string`, and `DecimalFilter`'s operands the same).
- *
- * A value that is not core's `Decimal` is refused rather than coerced: core
- * normalizes every decimal to its own `Decimal` before the adapter is called
- * (C-845), so a string or a number arriving here means the request bypassed
- * validation, and guessing at it would be the adapter inventing precision.
- */
 function emitDecimal(value, path) {
     if (value === null) {
         return null;
@@ -120,24 +27,13 @@ function emitDecimal(value, path) {
     if (value instanceof Decimal) {
         return value.toString();
     }
-    throw new PrismaScalarConversionError(`${path}: a decimal value reaches the adapter as an Aventara Decimal (core normalizes before the adapter, C-834); the adapter will not guess at a ${describeValue(value)}`);
+    throw new PrismaScalarConversionError(`${path}: a decimal value reaches the adapter as an Aventara Decimal; the adapter will not guess at a ${describeValue(value)}`);
 }
-/**
- * Prisma's decimal → core's `Decimal`, which is the only decimal form core's
- * output validator accepts in its runtime scope.
- *
- * The text is read through `String(value)`, which is exactly what RC-10
- * measured as lossless for 7.10.0's `Decimal2` on both driver adapters
- * (`String(v) === "12345.6789"`). A text core's own `Decimal` constructor
- * rejects is reported as a conversion failure naming the form observed, rather
- * than passed on to fail later as core's generic `A3000`.
- */
 function receiveDecimal(value, path) {
     if (value === null) {
         return null;
     }
     if (value instanceof Decimal) {
-        // Already core's: a fake adapter, or a value this adapter round-tripped.
         return value;
     }
     if (typeof value !== "object" &&
@@ -153,28 +49,14 @@ function receiveDecimal(value, path) {
         throw new PrismaScalarConversionError(`${path}: the provider returned ${describeValue(value)} for a decimal column, whose text "${text}" is not a decimal core accepts`);
     }
 }
-/**
- * One value out of Aventara and into a Prisma argument.
- *
- * @throws {PrismaScalarConversionError} for a value the adapter will not
- * represent rather than let a provider misread.
- */
 export function emitScalarValue(model, field, value, path) {
     return convert("outbound", model, field, value, path);
 }
-/**
- * One value out of a Prisma result and into the runtime form core's output
- * validator accepts.
- *
- * @throws {PrismaScalarConversionError} for a provider value the adapter cannot
- * honestly read as that scalar.
- */
 export function receiveScalarValue(model, field, value, path) {
     return convert("inbound", model, field, value, path);
 }
 function convert(direction, model, field, value, path) {
     if (!("scalar" in field.type)) {
-        // An enum member is its own name on both sides.
         return value;
     }
     const scalar = field.type.scalar;
@@ -186,12 +68,6 @@ function convert(direction, model, field, value, path) {
     }
     return convertAtoms(SCALAR_BOUNDARY_CROSSINGS[scalar][direction], value, path);
 }
-/**
- * A scalar list's members convert one by one, and the array is rebuilt rather
- * than written into: a translator that mutated its argument would corrupt the
- * second attempt of a retried operation, and a shaper that mutated a provider
- * row would corrupt whatever else holds it.
- */
 function convertAtoms(crossing, value, path) {
     if (!Array.isArray(value)) {
         return crossing(value, path);
@@ -202,15 +78,11 @@ function convertAtoms(crossing, value, path) {
         changed ||= result !== member;
         return result;
     });
-    // The same array, by identity, when no member needed converting: the shaper's
-    // copy-on-write depends on being able to tell.
     return changed ? converted : value;
 }
-/** Whether a discovered scalar key is one this adapter has a crossing for. */
 function isBuiltInScalar(key) {
     return Object.hasOwn(SCALAR_BOUNDARY_CROSSINGS, key);
 }
-/** Names what arrived, without quoting a value that may be large or secret. */
 function describeValue(value) {
     if (value === null) {
         return "null";

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

@@ -1,42 +1,35 @@
 import type { AdapterModel } from "@aventara/core";
 /**
- * T-7 — `where` translation: one validated Aventara predicate in, one Prisma
- * `<M>WhereInput` out.
- *
  * # 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 (T-7's "single largest testability
- * decision").
+ * 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. That is C-855's emission half:
- * *"capability derivation advertises an argument only when a named translator
- * step emits it"*, and this module is that step for the filter vocabulary.
+ * 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
- * (§18.5), no `mode` nobody asked for.
- *
- * # Values cross the boundary too (C-834)
+ * 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):
+ * 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**;
@@ -52,15 +45,11 @@ import type { AdapterModel } from "@aventara/core";
  *
  * # Refusing is part of honouring
  *
- * The adapter assumes validated input (C-845) and performs no limit checking.
- * It does, however, refuse to EMIT an operator the discovered model does not
- * advertise for that field. That is not a second validation pass for the
- * caller's benefit: it is the mechanism C-855 names — an argument is honoured or
- * the variant is omitted — enforced at the emission site, so an operator that
- * discovery decided not to advertise cannot reach a provider by another route.
- * 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.
+ * 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 {

package/dist/translation/where.translator.js

@@ -1,68 +1,4 @@
 import { emitScalarValue } from "./scalar.conversion.js";
-/**
- * T-7 — `where` translation: one validated Aventara predicate in, one Prisma
- * `<M>WhereInput` out.
- *
- * # 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 (T-7's "single largest testability
- * decision").
- *
- * # 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. That is C-855's emission half:
- * *"capability derivation advertises an argument only when a named translator
- * step emits it"*, and this module is that step for the filter vocabulary.
- *
- * 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
- * (§18.5), no `mode` nobody asked for.
- *
- * # Values cross the boundary too (C-834)
- *
- * 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 (C-845) and performs no limit checking.
- * It does, however, refuse to EMIT an operator the discovered model does not
- * advertise for that field. That is not a second validation pass for the
- * caller's benefit: it is the mechanism C-855 names — an argument is honoured or
- * the variant is omitted — enforced at the emission site, so an operator that
- * discovery decided not to advertise cannot reach a provider by another route.
- * 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 class PrismaWhereTranslationError extends Error {
     name = "PrismaWhereTranslationError";
 }
@@ -99,7 +35,6 @@ const RELATION_FILTER_EMISSIONS = {
     every: { kind: "key", token: "every" },
     none: { kind: "key", token: "none" },
 };
-/** Core's boolean nodes, whose spelling Prisma shares. */
 const BOOLEAN_NODES = { AND: "AND", OR: "OR", NOT: "NOT" };
 export function translateWhere(input) {
     return translateNode(input.model, input.resource, input.where, "where");
@@ -122,8 +57,6 @@ function translateNode(model, resourceKey, node, path) {
             continue;
         }
         if (key === BOOLEAN_NODES.NOT) {
-            // Aventara's `NOT` is ONE node. Prisma admits an array too; emitting one
-            // for a single node would be a shape the request never carried.
             emitted[key] = translateNode(model, resourceKey, value, `${path}.${key}`);
             continue;
         }
@@ -143,9 +76,6 @@ function translateScalarPredicate(model, field, value, path) {
     if (advertised === undefined || advertised.length === 0) {
         throw new PrismaWhereTranslationError(`${path}: filtering is not available on this field`);
     }
-    // Core's own rule: a value that is not a PLAIN record — `null` and a class
-    // instance included — IS equality, and Prisma spells that the same way.
-    // Wrapping it in `{ equals: … }` would emit a token the request never carried.
     if (!isPlainRecord(value)) {
         requireOperator(advertised, "equals", path);
         return emitScalarValue(model, field, value, path);
@@ -161,7 +91,6 @@ function translateScalarPredicate(model, field, value, path) {
     }
     return operand;
 }
-/** One operator's operand, converted as the operator's shape says it must be. */
 function emitOperand(model, field, shape, argument, path) {
     switch (shape) {
         case "opaque":
@@ -172,13 +101,8 @@ function emitOperand(model, field, shape, argument, path) {
             if (!Array.isArray(argument)) {
                 throw new PrismaWhereTranslationError(`${path} must be an array of values`);
             }
-            // `emitScalarValue` converts an array elementwise, which is what a list
-            // operand is — and what a LIST column's single value would be too, so the
-            // array is handed over whole rather than mapped here.
             return emitScalarValue(model, field, argument, path);
         case "value-or-filter":
-            // Core recurses on `not` exactly when its operand is a plain record, so
-            // the adapter does too; anything else is a value.
             return isPlainRecord(argument)
                 ? translateScalarPredicate(model, field, argument, path)
                 : emitScalarValue(model, field, argument, path);
@@ -194,7 +118,6 @@ function translateRelationPredicate(model, field, value, path) {
     if (field.cardinality === "one") {
         requireRelationFilter(advertised, "match", path);
         assertEmission("match", path);
-        // §18.5: the nested predicate, unwrapped. No `is`.
         return translateNode(model, field.target, value, path);
     }
     if (!isRecord(value)) {
@@ -214,7 +137,6 @@ function translateRelationPredicate(model, field, value, path) {
     }
     return operand;
 }
-/** The two capabilities whose emission is a shape rather than a key. */
 function assertEmission(capability, path) {
     const emission = RELATION_FILTER_EMISSIONS[capability];
     if (emission.kind === "key" || emission.kind === "edge-argument") {
@@ -240,11 +162,6 @@ function isRelationFilterCapability(key) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/**
- * Core's discriminant between a filter record and a VALUE, mirrored
- * **[CORE, runtime/scalar-runtime.ts `isPlainRecord`]**: a class instance — a
- * core `Decimal`, a `Date`, a `Uint8Array` — is a value, not a bag of operators.
- */
 function isPlainRecord(value) {
     if (!isRecord(value)) {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/prisma7-adapter",
-  "version": "0.1.0-pilot.0",
+  "version": "0.1.0-pilot.2",
   "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.0"
+    "@aventara/core": "0.1.0-pilot.2"
   },
   "peerDependencies": {
     "@prisma/adapter-better-sqlite3": "^7.10.0",
@@ -90,7 +90,7 @@
     "typescript-6": "npm:typescript@6.0.3"
   },
   "scripts": {
-    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json",
+    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json --removeComments --declaration false && node node_modules/typescript/bin/tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
     "typecheck": "node node_modules/typescript/bin/tsc -p tsconfig.typecheck.json --noEmit",
     "generate": "node node_modules/typescript/bin/tsc -p tsconfig.generate.json && node .generate/generate/discovery.generate.js && prisma generate --schema src/discovery/__fixtures__/ignore.prisma",
     "db:push": "prisma db push --config prisma.config.sqlite.ts && sh -c 'if [ -n \"$AVENTARA_TEST_POSTGRES_URL\" ]; then prisma db push --config prisma.config.postgres.ts; else echo \"AVENTARA_TEST_POSTGRES_URL is unset: skipping the PostgreSQL schema push\"; fi'",