@aventara/prisma7-adapter 1.0.0-rc.1 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -1,5 +1,184 @@
 # @aventara/prisma7-adapter
 
+## 1.0.0-rc.3
+
+### Patch Changes
+
+- b38034d: `aventara-prisma7-generate` refuses a `--provider` that the schema's `datasource` block contradicts, or a block naming
+  a provider the adapter does not support, before `prisma generate` runs, so neither the Prisma client nor the artifact
+  is written:
+
+  ```text
+  aventara-prisma7-generate: --provider postgresql contradicts the schema's datasource `db` (prisma/schema.prisma:12), which names provider "sqlite"; pass --provider sqlite.
+  ```
+
+  PSL's `postgres` spelling counts as `postgresql`, and a provider that is not a string literal is not compared.
+  Before, the flag was taken on trust, and a wrong one wrote the wrong provider into the artifact and the wrong filter
+  modes into the Contract.
+
+  When the file system refuses the artifact file (`--out`), the step says so in one sentence naming the file and why,
+  such as
+  `the artifact file /app/src/generated/aventara/discovery.artifact.ts (--out) cannot be written: permission denied (EACCES).`,
+  and leaves no staged file behind. Before, every such failure except a directory printed a stack trace.
+
+- b38034d: On PostgreSQL, a `@unique` value too long for its index (an index row past the B-tree's 8191 bytes, SQLSTATE
+  `54000`) is answered `422 A2004`, not `500 A3001`: one `V1004` issue at `["arguments"]`, as a value too long for its
+  column already was. The adapter reads the SQLSTATE, never the message. The issue's message for a value too long now
+  reads `The database refused this value: it is longer than the database can hold for its column.`
+  (it said `longer than its column can hold`, which an index refusal is not).
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+  - @aventara/core@1.0.0-rc.3
+
+## 1.0.0-rc.2
+
+### Patch Changes
+
+- On Cloudflare D1, a `BigInt` value beyond ±(2^53 − 1) is answered `A2004`, not `A3001`. `@prisma/adapter-d1`
+  binds a bigint as a JavaScript number and refuses one beyond that range before the statement runs, written,
+  compared in a filter or used in an `$increment`, and Prisma reports it as a database error (`P2039`). The adapter
+  answers that refusal as a value the database refused: `422 A2004` with one `V1004` issue, `The database refused
+  this value: it is outside the range its column can hold.`, at the value in the arguments (for example
+  `["arguments", "where", "views", "gt"]`). Nothing is written by the refused statement. It reads the arguments only
+  after the driver refused them, and only for the D1 driver; every other D1 database error stays `A3001`, and so does
+  a raw `ctx.$sql` statement binding such a value. Within ±(2^53 − 1) a bigint round-trips exactly on D1.
+  In rc.1 the refusal answered `500 A3001`. Measured on 7.10.0 through Miniflare's D1 binding.
+- The README's D1 notes are corrected: D1 is measured in process through Miniflare, where Prisma's client refuses
+  an interactive `$transaction` and the D1 driver runs Prisma's implicit transaction for a nested write as single
+  statements, so a nested write is not atomic on D1.
+- The optional `typescript` peer range is `>=5.7.0 <7` (it was `>=5.5.0 <7`). Under TypeScript 5.5 and 5.6 a
+  variant's stages written inline in `createFramework` are told `unknown` arguments, so `ctx.$args.data` and the
+  documented spread pipe `(args) => ({ ...args, data: { ...args.data, title: "t" } })` do not compile; TypeScript 5.7
+  and later type them. A project on TypeScript 5.5 or 5.6 upgrades to 5.7 or later.
+- `createPrismaAdapter` checks the installed `@prisma/client`'s major against the discovery artifact's, as the
+  README says. It reads the version from `@prisma/client/package.json`, resolved from the adapter's own location and
+  then from the working directory, and refuses an artifact generated against another major with
+  `AvPrismaDiscoveryArtifactError`. In rc.1 the artifact's version stood in for the installed one when no
+  `installedPrismaVersion` was passed, which a scaffolded project never does, so the check compared the artifact with
+  itself. Where the version cannot be read (a runtime without Node's module loader, a bundle deployed without
+  `@prisma/client`), the adapter starts and emits a warning, code `AVENTARA_PRISMA_VERSION_UNCHECKED`, saying the
+  majors were not compared. `installedPrismaVersion` still overrides the version read.
+- `aventara-prisma7-generate` refuses an `--out` inside `--client`, before `prisma generate` runs: exit 1 and one
+  sentence naming both paths. Prisma's next `prisma generate` clears the client's directory, so an artifact written
+  there was deleted. In rc.1 the step wrote it and exited 0. The same refusal applies to
+  `generatePrismaDiscoveryArtifact` and `runPrismaGenerateStep`.
+- `aventara-prisma7-generate` refuses an `--out` that names a directory in one sentence (exit 1), before
+  `prisma generate` runs. In rc.1 it ran Prisma and then failed with an `EISDIR` stack trace.
+- A nested write that writes its relation back is answered `A2004`, not `A3001`. Prisma writes a record reached
+  through a relation without that relation's other end, so it refuses a post created in `author.posts` that names
+  `author` or `authorId`, and a category created in a post's `category` that nests `posts`. The discovery artifact
+  now states each relation's other end (`inverse`, paired from the schema by relation name) and no relation writable
+  at the `"loopback"` position, so `@aventara/core` refuses such a write before any guard or SQL: `A2004`, `V1012` at
+  the field written back. It holds for `$create`, `$connectOrCreate`, `$update` and `$upsert`, to-one and to-many,
+  self-relations and one-to-ones. Where a layer hides the relation's other end, its Contract states no pairing and
+  Prisma's client is the one that refuses: the adapter answers that refusal as the caller's too, `A2004` with a
+  `V1012` issue at the field and the message `The data source refused this nested write: a record written through a
+  relation cannot write that relation or its reference fields back.` It reads the arguments only after Prisma
+  refused them; every other refusal of Prisma's client stays `A3001`. In rc.1 every case answered `500 A3001`.
+  Measured on 7.10.0, SQLite and PostgreSQL. Run `npm run aventara:prepare` to regenerate the artifact: the model's
+  hash and every Contract's hash change.
+- The discovery artifact states each relation's reference fields (`referenceFields`, read from the schema's
+  `@relation(fields: …)`), on optional and required relations alike, and none on the end that holds no reference.
+  So the types leave `categoryId` out of a post created in `Category.posts`, as `@aventara/core` refuses it. Run
+  `npm run aventara:prepare` to regenerate the artifact: the model's hash and every Contract's hash change.
+- A `$divide` by zero is answered `A2004`, not `A3001`. It reaches the database as given: PostgreSQL refuses the
+  division (`P2039`, `22012`) and the adapter answers `V1004` `The database refused this value: it divides by zero.`;
+  SQLite computes NULL and the `NOT NULL` column refuses it (`P2011`), answered `V1004` `The database refused this
+  value: the write computes no value for a column that requires one, as a division by zero does.` Both at
+  `["arguments"]`, nothing written. `P2011` reaches the adapter only this way: core refuses a `null` for a required
+  field and a missing one, and so does Prisma's client before the query. In rc.1 both answered `500 A3001`. Measured
+  on 7.10.0 for `Int`, `BigInt`, `Float` and `Decimal`, in `update` and `updateMany`.
+- `null` on a nullable `Json` field is the database NULL, as on every other nullable field. A write of `null`
+  (create, update, upsert, bulk, nested, a plan step) is sent as Prisma's `DbNull`; `{ meta: null }` and
+  `{ meta: { equals: null } }` are sent as Prisma's `AnyNull` and match every row that reads back `null` (a database
+  NULL or a JSON `null` stored by other means), and `{ meta: { not: null } }` matches the other rows. A JSON `null`
+  inside a value is sent as written, and so is a `null` beside a `path`: Prisma matches the documents whose value at
+  that path is a JSON `null`. In rc.1 a write of `null` stored a JSON `null`, `equals: null` matched only the stored
+  JSON nulls, and `{ meta: null }` failed with `500 A3001`. Reads are unchanged. Measured on 7.10.0, SQLite and
+  PostgreSQL.
+- A to-one relation filter is sent under Prisma's `is`. `{ category: {} }` matches the rows that have a related row and
+  `{ NOT: { category: {} } }` the rows that have none. In rc.1 the empty predicate was sent unwrapped, which Prisma
+  reads as no condition: both matched every row, and `Post.delete.count({ where: { NOT: { author: {} } } })` deleted
+  every post although each has its required author. A non-empty nested `where` and `null` match what they did.
+- A value the database refuses is answered `A2004`, not `A3001`. Text-match operands and written values reach Prisma
+  as given (`%` and `_` are what the engine's `LIKE` makes of them, a column rounds or keeps what it does); when
+  PostgreSQL refuses a caller's value, the adapter answers `A2004` with one issue at `["arguments"]` (Prisma's error
+  names no column): `V1004` for a value too long for its column (`P2000`), out of its column's range (`P2020`: a
+  `Decimal` past its precision, `Number.MAX_VALUE` in a `Float`, an `Int` `$increment` past 2^31) or a `DateTime`
+  outside PostgreSQL's range (`P2039`, `22009`); `V1001` for U+0000 in text or `json` (`P2039`, `22021` and `22P05`),
+  a lone surrogate in `json` (`P2007`) and a `LIKE` pattern ending in `\` (`P2039`, `22025`). The issue's message
+  says which of these the database refused, in core's words and none of the database's (`The database refused this
+  value: it is longer than its column can hold.`), not the code's generic text. Inside a plan the
+  issue stands at the step (`["operations", i, "args"]`) and the plan rolls back. Every other database failure stays
+  `A3001`. In rc.1 each of these answered `500 A3001`. Measured on 7.10.0, SQLite and PostgreSQL; SQLite refused none
+  of these values.
+- A field's `not` holding an operator object now means the negation of the whole object, on every field type, on
+  both engines, in reads and in bulk writes. `{ f: { not: X } }` matches exactly the rows `{ NOT: { f: X } }` matches:
+  a row where `X` is neither true nor false (the column is `NULL`, a `json` `path` is not in the document, a `json`
+  value is not the kind the operator reads) matches neither `X` nor `not: X`, as SQL's `NOT` reads it. The adapter
+  sends it to Prisma as `NOT` of the field's filter, ANDed with the rest of the `where`, because Prisma's own
+  field-level `not` says less (measured on 7.10.0, SQLite and PostgreSQL):
+  - In rc.1, a `json` field's `not` holding operators matched every row on both engines, because Prisma reads that
+    `not` as a JSON value to compare the document with. That covers `{ meta: { not: { path: ["label"],
+    stringContains: "x" } } }`, `{ meta: { not: { equals: { a: 1 } } } }` and every other operator under it, and an
+    `update.many`, `update.count`, `delete.count` or `delete.first` under such a filter wrote or deleted every row
+    the rest of the filter allowed.
+  - In rc.1, two or more operators under `not` were negated one at a time and ANDed, so
+    `{ views: { not: { gt: 2, lte: 5 } } }` matched no row. It now matches the rows outside that range.
+  - In rc.1 on PostgreSQL, a `mode` inside `not` (`{ title: { not: { contains: "x", mode: "insensitive" } } }`)
+    failed with `A3001`, because Prisma's filter under `not` has no `mode`. It now matches the titles that do not
+    contain `x` in any case.
+
+  The object under `not` is its own level: nothing from the object around it reaches into it. In rc.1 on
+  PostgreSQL, `{ title: { mode: "insensitive", not: { contains: "x" } } }` excluded `X` as well as `x`, because Prisma
+  applied the outer `mode` inside its own `not`. Core now refuses that filter (`A2004`, `V1001` at the `mode`); write
+  `{ title: { not: { contains: "x", mode: "insensitive" } } }`. A plain value under `not` (`{ not: "x" }`,
+  `{ not: null }`) is equality negated and is sent as before.
+- A `json` field's bare value in a filter is equality on both engines: `{ meta: "x" }` and `{ meta: [1, 2] }` are sent
+  to Prisma as `{ equals: … }`. In rc.1 they failed with `A3001`, because Prisma's Json filter takes no bare value.
+- Filter modes, measured on each engine. PostgreSQL offers `"default"`, `"sensitive"` and `"insensitive"` on a string
+  column and on a `json` value at a `path`; on a whole `json` document it offers `"default"` and `"sensitive"`, because
+  Prisma accepts an insensitive `stringContains` there and PostgreSQL then fails (`42883 function lower(jsonb) does not
+  exist`, answered `A3001`). That filter is now refused before any query (`A2004`, `V1006` at the `mode`). SQLite, and
+  so D1, offers `"default"` only: its `LIKE` folds ASCII case and nothing else, and `equals` folds none, so neither
+  promise holds. Every string field with a text operator now offers `mode` (on SQLite with `"default"` alone), and
+  `"default"` and `"sensitive"` are sent to Prisma as no `mode` at all. Regenerate the discovery artifact
+  (`aventara:prepare`).
+- 9366e16: The discovery artifact names the model's type: it exports `AvModel`, and `model` is declared with it
+  (`typeof model` is `AvModel`). A project that emits declarations (Nest's `declaration: true`) now writes that
+  name wherever an exported declaration holds the model, instead of the whole model. Over 50 models the scaffold's
+  `aventara.config.d.ts` goes from 485 KB to 0.4 KB, and a `buildFramework` / `AppFramework` module from 931 KB to
+  0.6 KB (1.2 MB to 0.6 KB, and 2.4 MB to 22 KB for exported configurations holding typed stages, in the consumer-build
+  gate). Regenerate the artifact (`aventara:prepare`, which runs on install, build and start) to get it; Contract bytes
+  and hashes are unchanged.
+- New: `aventara-prisma7-generate --config <file>`, optional. Given your Aventara configuration module
+  (`src/aventara.config.ts` in a project set up by `aventara`; its `aventaraConfig` export, a function or a value, or
+  its default export), the artifact states which fields it computes on create and on update, per layer. They are read
+  off the configuration's TypeScript type, never by running it, so nothing connects to a database and no environment
+  is needed. The artifact exports them as `computedFields` (type `AvComputedFields`), carries them on `AvModel` so a
+  variant's guards, pipes and filters may leave exactly those fields out of a create, and hands them to the framework
+  through `discovery.computedFields`, which it compares with the configuration at startup. A configuration that is
+  not a literal where a compute stage is written (one annotated with the wide `AvConfig`, a conditional spread) is not
+  read: the step prints where, and the artifact states nothing, so those stages may leave any create field out. A
+  `--config` file that does not exist, or exports neither `aventaraConfig` nor a default, stops the step.
+  `generatePrismaDiscoveryArtifact` and `runPrismaGenerateStep` take the same `config`, and
+  `readConfigComputedFields` is exported from `@aventara/prisma7-adapter/generate`.
+- The discovery artifact's format is now 4 (`computedFields` is new): an artifact written before it is refused with
+  the regeneration instruction. `aventara:prepare` regenerates it on install, build and start.
+- A transaction that expired (or was closed) under a step is answered `A3002`, as when the COMMIT finds it expired:
+  Prisma's `P2028`, raised by the step's own call, is the transaction's failure, at that step (`cause.operation`),
+  and the plan rolls back. In rc.1 it was unclassified and answered `500 A3001`, an adapter failure. Measured on
+  7.10.0, SQLite and PostgreSQL.
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+  - @aventara/core@1.0.0-rc.2
+
 ## 1.0.0-rc.1
 
 ### Patch Changes

package/README.md

@@ -11,7 +11,7 @@ suggest. Everything you need is in the body of this file, not in footnotes.
 - Status: release candidate. Two engines are proven, PostgreSQL and SQLite. Every other Prisma provider is
   unmeasured, and this file says so where it matters.
 - Peer dependencies: `@prisma/client` `^7.10.0` (required); `prisma`, `@prisma/adapter-better-sqlite3`
-  and `@prisma/adapter-pg` `^7.10.0` and `typescript` `>=5.5.0 <7` (optional). The error map targets
+  and `@prisma/adapter-pg` `^7.10.0` and `typescript` `>=5.7.0 <7` (optional). The error map targets
   7.10.0, and the adapter is bound to Prisma 7's error surface; see [Prisma 7 only](#prisma-7-only).
 
 ---
@@ -82,11 +82,13 @@ npx aventara-prisma7-generate \
   --client   src/generated \
   --provider postgresql \
   --driver   @prisma/adapter-pg \
-  --out      src/discovery.artifact.ts
+  --out      src/discovery.artifact.ts \
+  --config   src/aventara.config.ts
 ```
 
-`--provider` and `--driver` are declared, never sniffed. The provider is recorded in the artifact. The
-driver decides `AvAdapterModel.transactions`, a driver fact the schema cannot state. Declare the driver
+`--provider` and `--driver` are declared, never sniffed. The provider is recorded in the artifact, and the
+step refuses a `--provider` that the schema's `datasource` block contradicts (`provider = "sqlite"` with
+`--provider postgresql`), naming the flag to pass. The driver decides `AvAdapterModel.transactions`, a driver fact the schema cannot state. Declare the driver
 the application will actually construct the adapter with. The two cannot drift silently, but they can
 disagree, and core refuses construction when they do.
 
@@ -97,9 +99,20 @@ installed keeps `@prisma/prisma7` beside it. With neither usable, the step refus
 both. TypeScript 6 is supported; TypeScript 7, which has no classic compiler API, is refused in one
 sentence.
 
-`--out` must not be inside `--client`. The types reader reads every `.ts` file under the client root
-and refuses one that is not generated-client output, so an artifact written beside the client would
-break the next run.
+`--config` is optional. It names your Aventara configuration module: its `aventaraConfig` export (a
+function, as the `aventara` scaffold writes it, or a value) or its default export. The step reads the
+configuration's TypeScript type, never runs it, and states in the artifact which fields its
+`compute.create` and `compute.update` stages fill, per layer (`computedFields`). A variant's guards,
+pipes and filters, which run before write compute, may then leave exactly those fields out of a create;
+every other required field stays required. Without `--config`, or when the configuration is not a
+literal where a compute stage is written (the step prints where), the artifact states nothing and those
+stages may leave any create field out. When the framework starts, it compares the statement with the
+configuration and warns (`AVENTARA_STALE_GENERATED_TYPES`) if you changed a compute stage without
+running the step again.
+
+`--out` must not be inside `--client`: Prisma's next `prisma generate` clears that directory and would
+delete the artifact. The step refuses such an `--out`, and one that names a directory, in one sentence
+before Prisma runs.
 
 The same step can run from code, for a project that already has a build script:
 
@@ -146,19 +159,31 @@ at runtime, after your pipes and computed behaviours have run, it is answered `A
 issue at its path (`["arguments", "data", "title"]`, or `["arguments", "data", "author"]` for a
 required relation) before the database can refuse it.
 
+The module also exports the model's type by name, `AvModel` (`typeof model` is that type). A
+project that emits declarations (Nest's `declaration: true`) writes that name wherever an exported
+declaration holds the model, such as the scaffold's `aventaraConfig()`, an `AppFramework` alias or
+`defineResource<typeof model>()`, so those declarations stay under a kilobyte at any schema size. Before
+the name, each mention wrote the whole model out, about 0.5 MB over 50 models.
+
 `modelHash` digests the model and nothing else. The addressing table, the referential actions and the
 client record sit beside it and outside the hash. A database-side rename or a foreign-key action
 changes no semantics; inside the hash, either would move the Contract identity and force every
 generated client to be regenerated for nothing.
 
 On the runtime path there is no TypeScript program, no PSL parser and no Prisma tooling. The loader
-reads no file: the artifact arrives as a value you import.
+reads no file: the artifact arrives as a value you import. The adapter reads one: the installed
+`@prisma/client`'s `package.json`, for its version.
 
 At construction, before the application listens, the adapter checks three things and fails hard with
 an instruction to regenerate if any is wrong:
 
 1. the artifact matches itself: the `modelHash` over its own canonicalized model;
-2. the installed `@prisma/client` major is the one the artifact was generated against;
+2. the installed `@prisma/client` major is the one the artifact was generated against. The version is
+   read from `@prisma/client/package.json`, resolved from the adapter's own location and then from the
+   working directory. Where it cannot be read (a runtime without Node's module loader, a bundle
+   deployed without `@prisma/client`), the adapter starts and emits a warning, code
+   `AVENTARA_PRISMA_VERSION_UNCHECKED`, saying the majors were not compared;
+   `installedPrismaVersion` overrides the version read;
 3. the Prisma client you pass is the one the artifact was generated from: the same models, and the
    same field references (`prisma.<model>.fields`) on each. A schema change followed by
    `prisma generate` but not by the generate step (a model or field added, removed or renamed) is
@@ -213,10 +238,13 @@ On PostgreSQL and SQLite, read from the generated types:
 | `create.many` / `update.many` (row-returning bulk writes) | advertised | advertised | `createManyAndReturn` / `updateManyAndReturn` on the delegate |
 | Transactions | `"interactive"` | `"interactive"` | the driver, not the provider (see below) |
 
-Nothing beyond PostgreSQL and SQLite is measured. MySQL, SQL Server, MongoDB, CockroachDB and D1 were
-not generated against. Because every capability is read from the client you actually generated, a
-provider that lacks something advertises less instead of failing at runtime, but this release makes no
-claim about those providers.
+Nothing beyond PostgreSQL and SQLite is measured. Cloudflare D1 is SQLite through `@prisma/adapter-d1`:
+it reads the same generated client, so its capabilities are SQLite's, and it is measured in process
+through Miniflare's D1 binding, where it differs from SQLite in two ways (no transactions, and a bigint
+within ±(2^53 − 1); see below). MySQL, SQL Server, MongoDB and CockroachDB were not generated against.
+Because every capability is read from the client you actually generated, a provider that lacks
+something advertises less instead of failing at runtime, but this release makes no claim about those
+providers.
 
 ### `update.many` and `create.many` cannot project a to-many relation
 
@@ -372,8 +400,7 @@ commits, do not perform it in an after hook.
 ### `P2028` covers seven situations, and three of them are separable
 
 `P2028` is Prisma 7's transaction code, and seven internal classes share it. The adapter answers
-`A3002 TRANSACTION_ERROR` for the failure that ends the transaction, and never reads the message text
-to decide anything.
+`A3002 TRANSACTION_ERROR` wherever it is met, and never reads the message text to decide anything.
 
 What can be told apart from the error's structure, measured on PostgreSQL and SQLite:
 
@@ -391,8 +418,9 @@ timeout cannot be told apart from them. That limit is Prisma's, and it is record
 works around it by parsing messages.
 
 A `P2028` that ends the transaction rejects out of `$transaction` and becomes `A3002`. A `P2028`
-raised by a delegate call inside the callback is not in the closed code table, so it becomes `A3001`
-attributed to that operation.
+raised by a delegate call (or a raw statement) inside the callback, such as a step that runs after the
+`timeout` passed, is in the closed code table and also becomes `A3002`, attributed to that operation
+(`cause.operation`). In rc.1 that second case was unclassified and answered `A3001`.
 
 ### Everything unrecognised becomes `A3001`
 
@@ -438,9 +466,12 @@ observe that it did. A commit failure is different: it rejects like a callback t
 
 ### `transactions` is a driver fact, and it reaches the ClientContract hash
 
-`@prisma/adapter-d1` declares `transactions: "none"`: Cloudflare D1 rejects interactive transactions,
-and Prisma says so itself. `@prisma/adapter-pg` and `@prisma/adapter-better-sqlite3` declare
-`"interactive"`, observed by running one.
+`@prisma/adapter-d1` declares `transactions: "none"`: Prisma's client refuses an interactive
+`$transaction` on D1 itself. Prisma still opens its own implicit transaction for a nested write (a
+`$create` under a relation, a `$connect`), and the D1 driver runs it as single statements, so a nested
+write is not atomic on D1: when a later statement fails, the rows the earlier ones wrote are kept.
+`@prisma/adapter-pg` and `@prisma/adapter-better-sqlite3` declare `"interactive"`, observed by running
+one.
 
 Plan for the consequence. The `transactions` capability is part of the ClientContract hash, and a
 generated client fails hard on a hash mismatch. So one schema, one framework configuration and two
@@ -597,6 +628,23 @@ Resource or operation for one to wrap.
 - `limit`/`offset`/`cursor` are the public names. Prisma's `take`/`skip` never surface.
 - Decimal values are converted in both directions. Prisma's bundled decimal object is not an Aventara
   public type and does not reach a caller as one.
+- Values and filter operands reach Prisma as given: a `contains`, `startsWith` or `endsWith` operand is the
+  engine's `LIKE` pattern (`%` and `_` included), and a column stores, rounds or widens a value as the engine does.
+  A value PostgreSQL refuses (too long for its column, out of its range, U+0000 in text, a `LIKE` pattern ending in
+  `\`) answers `A2004` with one issue at `["arguments"]` (`V1004` or `V1001`), not `A3001`.
+- On D1, a `BigInt` value must lie within ±(2^53 − 1) (±9,007,199,254,740,991), not the full signed 64-bit
+  range: the D1 driver binds a bigint as a JavaScript number and refuses one beyond that before the
+  statement runs. A value beyond it, written, compared in a filter or used in an `$increment`, answers
+  `A2004` with one `V1004` issue at the value (`["arguments", "data", "views"]`), and the statement that
+  carries it writes nothing. A `ctx.$sql` statement binding such a value answers `A3001`: its SQL is
+  yours.
+- A record written through a relation cannot write that relation, or its reference fields, back: Prisma's nested
+  input for it leaves them out (a post created in `author.posts` has no `author` or `authorId`; a category created in
+  a post's `category` has no `posts`). The artifact states each relation's other end (`inverse`, paired by relation
+  name), the fields that hold its reference (`referenceFields`, from `@relation(fields: …)`) and no relation
+  writable at the `"loopback"` position, so `@aventara/core` refuses such a write before any
+  guard or SQL, `A2004` with a `V1012` issue at the field written back, and the types do not offer it. Where a layer
+  hides the other end, Prisma's client refuses the write instead and the adapter answers that refusal the same way.
 - Count variants return numbers, including zero. `create.many` and `update.many` return arrays.
 - `find.unique`, `update.unique` and `delete.unique` answer `A2003 NOT_FOUND` on a missing target;
   `find.first`, `update.first` and `delete.first` answer `A1001 NO_MATCH` with `null` data. The

package/dist/discovery/artifact.loader.d.ts

@@ -9,8 +9,12 @@ export declare class AvPrismaDiscoveryArtifactError extends Error {
 }
 export type PrismaDiscoveryArtifactLoad = {
     readonly artifact: unknown;
-    /** The `version` of the `@prisma/client` actually installed beside the caller. */
-    readonly installedPrismaVersion: string;
+    /**
+     * The `version` of the `@prisma/client` actually installed beside the caller;
+     * `undefined` when it could not be read, and the majors are then not compared
+     * (the adapter says so at startup).
+     */
+    readonly installedPrismaVersion: string | undefined;
 };
 /**
  * The identity of a discovered model: one canonicalization, one digest — over

package/dist/discovery/artifact.loader.js

@@ -49,6 +49,9 @@ function assertArtifactShape(artifact) {
             throw new AvPrismaDiscoveryArtifactError(`The discovery artifact's \`${key}\` is not a JSON object.`);
         }
     }
+    if (artifact.computedFields !== null && !isRecord(artifact.computedFields)) {
+        throw new AvPrismaDiscoveryArtifactError("The discovery artifact's `computedFields` is neither a JSON object nor null.");
+    }
     for (const key of ["scalars", "enums", "resources"]) {
         if (!isRecord(artifact.model[key])) {
             throw new AvPrismaDiscoveryArtifactError(`The discovery artifact's \`model.${key}\` is not a JSON object.`);
@@ -66,7 +69,9 @@ export async function loadDiscoveryArtifact(load) {
     const { artifact, installedPrismaVersion } = load;
     assertArtifactShape(artifact);
     const artifactMajor = majorOf(artifact.prismaVersion);
-    const installedMajor = majorOf(installedPrismaVersion);
+    const installedMajor = installedPrismaVersion === undefined
+        ? artifactMajor
+        : majorOf(installedPrismaVersion);
     if (artifactMajor === undefined || installedMajor === undefined) {
         throw new AvPrismaDiscoveryArtifactError(`A Prisma version is not a major.minor.patch version: the artifact declares \`${artifact.prismaVersion}\` and the installed client reports \`${installedPrismaVersion}\`.`);
     }

package/dist/discovery/capability.deriver.d.ts

@@ -1,4 +1,5 @@
 import type { AvRelationFieldCapabilities, AvScalarFieldCapabilities, AvScalarFilterOperator } from "@aventara/core";
+import type { PrismaFilterModeFacts } from "../provider/provider-profile.js";
 import type { PrismaRelationSurface, PrismaScalarSurface } from "./capability-surface.interface.js";
 /** A Prisma spelling that no dictionary table recognises: a build stop, never a drop. */
 export declare class AvPrismaCapabilityDerivationError extends Error {
@@ -6,6 +7,8 @@ export declare class AvPrismaCapabilityDerivationError extends Error {
 }
 export type ScalarCapabilityInput = {
     readonly surface: PrismaScalarSurface;
+    /** The `mode`s the engine honours (see this module's header). */
+    readonly filterModes: PrismaFilterModeFacts;
 };
 /** A relation's capabilities are answered for the field, not for an operation. */
 export type RelationCapabilityInput = {
@@ -13,5 +16,5 @@ export type RelationCapabilityInput = {
 };
 export declare function deriveScalarCapabilities(input: ScalarCapabilityInput): AvScalarFieldCapabilities;
 /** The Prisma operand for each ADVERTISED operator, keyed by the Aventara name. */
-export declare function deriveScalarFilterOperands(input: ScalarCapabilityInput): Readonly<Partial<Record<AvScalarFilterOperator, string>>>;
+export declare function deriveScalarFilterOperands(input: Pick<ScalarCapabilityInput, "surface">): Readonly<Partial<Record<AvScalarFilterOperator, string>>>;
 export declare function deriveRelationCapabilities(input: RelationCapabilityInput): AvRelationFieldCapabilities;

package/dist/discovery/capability.deriver.js

@@ -61,18 +61,50 @@ const PAGINATION_ORDER = [
 export function deriveScalarCapabilities(input) {
     const { surface } = input;
     const operands = deriveScalarFilterOperands(input);
-    const filter = canonical(FILTER_OPERATOR_ORDER, surface.filters
+    const derived = surface.filters
         .map((key) => look(PRISMA_FILTER_OPERATORS, key, "a scalar filter operator"))
-        .filter((operator) => translatable(operator, operands)));
+        .filter((operator) => translatable(operator, operands));
+    const modes = filterModes(derived, input.filterModes);
+    const filter = canonical(FILTER_OPERATOR_ORDER, [
+        ...derived,
+        ...(modes === undefined ? [] : ["mode"]),
+    ]);
     return {
         select: true,
         ...(filter.length > 0 ? { filter } : {}),
+        ...(modes ?? {}),
         order: surface.orderable,
         ...(surface.nullsOrderable ? { orderNulls: true } : {}),
         ...directives("create", surface.createOperations),
         ...directives("update", surface.updateOperations),
     };
 }
+const TEXT_OPERATORS = [
+    "contains",
+    "startsWith",
+    "endsWith",
+];
+const JSON_TEXT_OPERATORS = [
+    "stringContains",
+    "stringStartsWith",
+    "stringEndsWith",
+];
+function filterModes(operators, facts) {
+    const admitted = (modes) => modes.filter((mode) => mode !== "insensitive" || operators.includes("mode"));
+    if (operators.some((operator) => JSON_TEXT_OPERATORS.includes(operator))) {
+        return {
+            filterModes: admitted(facts.jsonDocument),
+            ...(operators.includes("path")
+                ? { pathFilterModes: admitted(facts.jsonPath) }
+                : {}),
+        };
+    }
+    if (operators.includes("mode") ||
+        operators.some((operator) => TEXT_OPERATORS.includes(operator))) {
+        return { filterModes: admitted(facts.text) };
+    }
+    return undefined;
+}
 export function deriveScalarFilterOperands(input) {
     const operands = {};
     for (const operator of FILTER_OPERATOR_ORDER) {
@@ -126,7 +158,10 @@ function reducersIn(reducers, bulk) {
     return bulk ? reducers : { reducers, scopes: ["record"] };
 }
 function writableIn(directives, bulk) {
-    return bulk ? directives : { directives, scopes: ["nested"] };
+    return {
+        directives,
+        scopes: bulk ? ["nested", "bulkWrite"] : ["nested"],
+    };
 }
 export function deriveRelationCapabilities(input) {
     const { surface } = input;

package/dist/discovery/discovery-artifact.interface.d.ts

@@ -1,4 +1,4 @@
-import type { AvAdapterModel, AvEnumDefinition, AvScalarRegistry, AvTransactionCapability } from "@aventara/core";
+import type { AvAdapterModel, AvConfigComputedFields, AvEnumDefinition, AvScalarRegistry, AvTransactionCapability } from "@aventara/core";
 import type { AvAdapterResource } from "@aventara/core/internal";
 import type { AvPrismaProvider } from "../provider/provider-profile.js";
 /** The adapter model a discovery artifact carries, in Aventara's vocabulary. */
@@ -73,7 +73,7 @@ export type AvPrismaReferentialActionTable<M extends AvPrismaAdapterModel = AvPr
  */
 export type PrismaClientShape = Readonly<Record<string, readonly string[]>>;
 /** The current discovery artifact format. */
-export declare const DISCOVERY_ARTIFACT_FORMAT = 3;
+export declare const DISCOVERY_ARTIFACT_FORMAT = 4;
 /**
  * The discovery artifact: the module `aventara-prisma7-generate` writes from
  * your schema and generated client. Import its `discovery` export and pass it
@@ -106,4 +106,12 @@ export type AvPrismaDiscoveryArtifact<M extends AvPrismaAdapterModel = AvPrismaA
      * against; not part of `modelHash`.
      */
     readonly client: PrismaClientShape;
+    /**
+     * Which fields the configuration's write compute fills, per layer, as the
+     * generate step read them off the configuration it was given (`--config`);
+     * `null` when it was given none. The model's type carries the same statement
+     * for the pipeline stages' types; this value is compared with the
+     * configuration when the framework starts. Not part of `modelHash`.
+     */
+    readonly computedFields: AvConfigComputedFields | null;
 };

package/dist/discovery/discovery-artifact.interface.js

@@ -1 +1 @@
-export const DISCOVERY_ARTIFACT_FORMAT = 3;
+export const DISCOVERY_ARTIFACT_FORMAT = 4;

package/dist/discovery/installed-client.locator.d.ts

@@ -0,0 +1,13 @@
+/** What the locator found: the version, or why it has none. */
+export type InstalledPrismaClientVersion = {
+    readonly kind: "read";
+    readonly version: string;
+} | {
+    readonly kind: "unread";
+    readonly reason: string;
+};
+/**
+ * Reads the installed `@prisma/client`'s version, resolved as described above.
+ * Never throws: a version it cannot read is answered `unread` with the reason.
+ */
+export declare function locateInstalledPrismaClientVersion(): InstalledPrismaClientVersion;

package/dist/discovery/installed-client.locator.js

@@ -0,0 +1,43 @@
+const MANIFEST = "@prisma/client/package.json";
+function resolutionBases(process) {
+    const bases = [];
+    try {
+        if (typeof import.meta.url === "string") {
+            bases.push(import.meta.url);
+        }
+    }
+    catch {
+    }
+    const cwd = process?.cwd?.();
+    if (typeof cwd === "string") {
+        bases.push(`${cwd.replace(/[\\/]+$/, "")}/package.json`);
+    }
+    return bases;
+}
+export function locateInstalledPrismaClientVersion() {
+    const process = globalThis.process;
+    const moduleApi = process?.getBuiltinModule?.("node:module");
+    if (typeof moduleApi?.createRequire !== "function") {
+        return {
+            kind: "unread",
+            reason: "this runtime has no Node module loader to resolve it with",
+        };
+    }
+    const tried = [];
+    for (const base of resolutionBases(process)) {
+        try {
+            const manifest = moduleApi.createRequire(base)(MANIFEST);
+            if (typeof manifest.version === "string") {
+                return { kind: "read", version: manifest.version };
+            }
+            tried.push(`${base} (its package.json states no version)`);
+        }
+        catch {
+            tried.push(base);
+        }
+    }
+    return {
+        kind: "unread",
+        reason: `\`${MANIFEST}\` does not resolve from ${tried.length === 0 ? "anywhere this runtime names" : tried.join(" or ")}`,
+    };
+}

package/dist/discovery/model.discoverer.d.ts

@@ -1,5 +1,6 @@
 import type { AvTransactionCapability } from "@aventara/core";
 import type { PrismaComposedArtifact, PrismaModelComposer } from "../generate/prisma.generate.js";
+import type { PrismaFilterModeFacts } from "../provider/provider-profile.js";
 import type { PrismaCapabilitySurface } from "./capability-surface.interface.js";
 import type { PrismaSchemaFacts } from "./schema-facts.interface.js";
 /** Thrown when the schema cannot be composed into a model; lists every problem. */
@@ -10,6 +11,8 @@ export declare class AvPrismaModelCompositionError extends Error {
 }
 export type PrismaModelCompositionOptions = {
     readonly transactions: AvTransactionCapability;
+    /** The `mode`s the engine's comparisons honour (`provider-profile.ts`). */
+    readonly filterModes: PrismaFilterModeFacts;
 };
 export type PrismaModelDiscoveryInput = PrismaModelCompositionOptions & {
     /** PSL — what the schema says. */

package/dist/discovery/model.discoverer.js

@@ -42,8 +42,10 @@ export function discoverPrismaModel(input) {
             modelNames,
             admitted,
             transactions: input.transactions,
+            filterModes: input.filterModes,
             diagnostics,
             usedScalars,
+            declared,
         });
         resources[name] = composed.resource;
         translation[name] = composed.translation;
@@ -215,7 +217,10 @@ function composeResource(input) {
                 }
                 fields[projection.name] = {
                     ...projection.field,
-                    capabilities: deriveScalarCapabilities({ surface: scalarSurface }),
+                    capabilities: deriveScalarCapabilities({
+                        surface: scalarSurface,
+                        filterModes: input.filterModes,
+                    }),
                 };
                 projectedScalars.push({
                     name: projection.name,
@@ -235,8 +240,15 @@ function composeResource(input) {
                     diagnostics.push(`\`${model.name}.${field.name}\` targets \`${projection.field.target}\`, which the existence gate did not admit, so the edge would point at a Resource the model does not carry.`);
                     continue;
                 }
+                const inverse = inverseOf(input.declared, model.name, field);
+                const [firstReference, ...moreReferences] = field.relation?.fields ?? [];
+                const referenceFields = firstReference === undefined
+                    ? undefined
+                    : [firstReference, ...moreReferences];
                 fields[projection.name] = {
                     ...projection.field,
+                    ...(inverse === undefined ? {} : { inverse: inverse.relation }),
+                    ...(referenceFields === undefined ? {} : { referenceFields }),
                     capabilities: deriveRelationCapabilities({
                         surface: relationSurface,
                     }),
@@ -247,7 +259,7 @@ function composeResource(input) {
                         field: projection.edge.field,
                         target: projection.edge.target,
                         cardinality: projection.edge.cardinality,
-                        references: [...(field.relation?.fields ?? [])],
+                        references: [...(referenceFields ?? [])],
                         onDelete: projection.edge.onDelete,
                         onUpdate: projection.edge.onUpdate,
                     });