@aventara/prisma7-adapter 0.1.0-pilot.3 → 1.0.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,190 @@
+# @aventara/prisma7-adapter
+
+## 1.0.0-rc.0
+
+### Major Changes
+
+- First release candidate of Aventara 1.0. The public API is now considered stable; changes before 1.0.0 are possible
+  based on feedback.
+
+### Minor Changes
+
+- 24ffbab: A nested `$update` or `$delete` through a to-many relation filters plain fields only on Prisma 7, and Aventara now says
+  so up front: a relation filter in its `where` — `{ posts: { $update: { where: { category: { name: "x" } }, … } } }`, at
+  any depth, under `AND`/`OR`/`NOT` too — is refused with `A2004` / `V1006` before the database is asked, and is a type
+  error in `framework.application`, `framework.client`, `appTx`/`clientTx` and the generated client. Before, it reached
+  Prisma and fail as `A3001`. A to-one relation's nested filter keeps relation filters. The limit is stated by the adapter
+  in the Contract (`nestedWriteFilter: "scalar"`), so the ClientContract hash changes: regenerate the client.
+
+### Patch Changes
+
+- 24ffbab: Each package ships its `CHANGELOG.md`, so the release notes are in the installed package beside the README.
+- a973e89: A write that sets an optional relation both ways — its reference field and the relation itself, such as `categoryId`
+  and `category: { $connect: … }` in the same record — is now refused before it reaches the database, exactly like a
+  required relation: `A2004` with a `V1012` issue at the relation, message `Set "categoryId" or "category", not both.`
+  Before, the database refused it and the caller received `A3001`. It applies to `create`, `update` and `upsert`, to
+  nested writes at any depth, and to each step of a transaction.
+
+  The discovery artifact now records, for each relation, the fields that hold its reference (`references` on each edge
+  of `referentialActions`), and a create requirement no longer repeats them. Regenerate your artifact with
+  `npm run aventara:prepare` (or `aventara-prisma7-generate`); an artifact from an earlier version is refused with a
+  message that says so. An adapter's `referentialActions` edges carry the same `references` member.
+
+- a973e89: With the Prisma adapter, a record that writes one relation through its reference field and another relation directly —
+  such as `authorId` beside `category: { $connect: … }` — is now refused before it reaches the database: `A2004` with a
+  `V1012` issue at the relation write, message
+  `Use relation fields only, or reference fields only, in one record: "authorId" is a reference field and "category" is a relation.`
+  Before, Prisma refused it and the caller received `A3001`. Write the record's relations all as relations
+  (`author: { $connect: … }, category: { $connect: … }`) or all through their fields (`authorId`, `categoryId`). A
+  reference field beside a relation that holds no reference on that side — `mentorId` beside `posts: { $create: … }` on
+  an author — is unchanged and still accepted. It applies to `create`, `update` and `upsert`, to nested writes at any
+  depth, and to each step of a transaction.
+
+  The limit is part of the Contract: a Contract whose data source has it carries `referenceWrites: "uniform"`, so the
+  Contract hash of every Prisma-backed application changes. Regenerate your discovery artifact
+  (`npm run aventara:prepare`) and your generated client (`avclient generate`). An adapter states the limit with
+  `referenceWrites: "uniform"` in its model; without it, nothing changes.
+
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies
+- Updated dependencies [a973e89]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [24ffbab]
+- Updated dependencies [2d00ad7]
+- Updated dependencies [384a50c]
+- Updated dependencies [d43d1cc]
+- Updated dependencies [3f98749]
+- Updated dependencies [032f792]
+- Updated dependencies [dbe6961]
+  - @aventara/core@1.0.0-rc.0
+
+## 0.1.0-pilot.4
+
+### Patch Changes
+
+- f37dcd6: A discovery artifact written by an older version of the adapter now fails the TypeScript build with an error that
+  says what to do: `Property 'regenerate_with_aventara_prepare' is missing`. Run `npm run aventara:prepare`
+  (or `aventara-prisma7-generate`) to regenerate it. Every newly generated artifact carries the property, and
+  `createPrismaAdapter` refuses an out-of-date artifact at startup with the same instruction.
+- f37dcd6: The documentation shipped with the package — the comments an editor shows on hover, and the README — now describes
+  what each export does, how to use it, what it returns and what it throws. Notes about how the package was built and
+  why are no longer part of what is published.
+
+  The generate step's error messages name "the generated client's types" in words instead of Prisma's emoji labels.
+
+- Updated dependencies [f37dcd6]
+  - @aventara/core@0.1.0-pilot.4
+
+## 0.1.0-pilot.3
+
+### Patch Changes
+
+- The manifest declares the adapter's CLI alias, `aventara.adapter.alias: "prisma7"`: the value `aventara new --orm` and `aventara init --orm` take.
+- @aventara/core@0.1.0-pilot.3
+
+## 0.1.0-pilot.2
+
+### Patch Changes
+
+- e69e88d: The published packages are written for the people who use them. The JavaScript ships without comments; the type
+  declarations keep their documentation, and it, the error messages, the protocol fixtures' labels and the comments in a
+  generated client no longer carry the project's internal development notes.
+- 06ed5d8: A relation write that would leave a child without the parent its required relation demands — `$set: []` or
+  `$disconnect` on a to-many whose children require the parent — now answers `A2008` (the same conflict a violated
+  reference constraint answers) instead of `A3001`. Nothing is written.
+- 23937f8: A create that lacks a value the database requires is refused as `A2004` with a `V1000` issue at the value's path,
+  instead of reaching the database and answering `A3001`. It covers `create.one`, every row of `create.many`, `upsert`'s
+  `create` branch, nested `$create` (and `$connectOrCreate`/`$upsert` creates) at any depth, and transaction steps
+  (`["operations", i, "args", …]`). A required relation is satisfied by writing it or every scalar that holds its
+  reference; a nested create never needs the relation it is created through. Defaults, `@updatedAt`, autoincrement,
+  optional and list columns are never required. The check runs after pipes and computed behaviours, so a value they
+  supply counts.
+
+  An adapter states the requirements through the new optional `Adapter.createRequirements`; the Prisma 7 adapter reads
+  them from the generated client's create inputs at generate time and records them in the discovery artifact, so the
+  artifact must be regenerated (`aventara:prepare`).
+
+- 287fc27: A discovery artifact older than the Prisma client is refused at startup. The artifact now records the client it was
+  generated from (each model and its field references), and `createPrismaAdapter` — which runs before the application
+  listens — compares that record with the client it is given: a model or field added, removed or renamed since the
+  artifact was generated stops the server with one sentence naming the difference and `aventara:prepare`. An artifact
+  generated by an earlier version carries no record and is refused with the same instruction; a project set up by
+  `aventara` regenerates it on install.
+- Updated dependencies [c2a3b7c]
+- Updated dependencies [e69e88d]
+- Updated dependencies [ab58424]
+- Updated dependencies [23937f8]
+  - @aventara/core@0.1.0-pilot.2
+
+## 0.1.0-pilot.1
+
+### Patch Changes
+
+- 799346e: The package READMEs (each package's npm page) are rewritten for the people who use the packages. The Prisma 7
+  adapter's README now states the actual behaviour of a to-many relation or `$count` projected on
+  `update.many`/`create.many`: a validation refusal, `A2004` with `V1008`, before any statement runs (it said `A3001`).
+  Every install or run command names the `@pilot` dist-tag.
+- Updated dependencies [a45f8a8]
+- Updated dependencies [799346e]
+  - @aventara/core@0.1.0-pilot.1
+
+## 0.1.0-pilot.0
+
+### Minor Changes
+
+- First pilot release of `@aventara/prisma7-adapter`, the Prisma 7 adapter. Peers: `@prisma/client`, `prisma` and the
+  driver adapters `^7.10.0`; `typescript` `>=5.5.0 <7` for the generate step. `typescript` and `prisma` are optional
+  peers used only by the generate step, so neither enters a deployed install.
+
+  - **`createPrismaAdapter({ client, discovery, provider, driver, transactionOptions? })`** is the entry point. Your
+    application owns the Prisma client, built with a driver adapter; the adapter never builds one, reads a connection
+    string or reads an environment variable. `provider` and `driver` are stated by you, and the driver decides whether
+    transactions are offered. It is `async` because it verifies the discovery artifact.
+  - **Discovery runs at generate time.** `aventara-prisma7-generate` (or the `@aventara/prisma7-adapter/generate`
+    export) reads `schema.prisma` and the generated client's types and writes one module, the discovery artifact: the
+    model, how each Resource is addressed, its referential actions, a `modelHash` and the Prisma version. At startup the
+    adapter checks that the artifact matches its `modelHash` and that the installed `@prisma/client` major is the one it
+    was generated against, and stops with an instruction to regenerate otherwise. The artifact is rewritten only when its
+    bytes change, and replaced atomically, so a reader never sees a half-written file.
+  - **The Contract says what Prisma serves.** `createMany`/`updateMany` results project fewer relations than a read
+    (the rule is which side holds the foreign key, not cardinality); the Contract advertises that per argument position,
+    and an out-of-position projection or nested write is refused with `A2004` (`V1008` / `V1006`) before any query.
+  - **Cascading deletes.** The schema's referential actions are stated to the Framework, so a transaction step that
+    depends on rows an earlier step's cascading delete removed is refused before the plan runs (`A2004`/`V1019`).
+  - **Conflicts are told apart:** `A2008 CONFLICT` for a uniqueness or reference constraint, `A2013
+CONCURRENT_MODIFICATION` when another operation changed the same state, `A2014 STALE_SELECTION` when the selected
+    record changed before the write.
+  - **Behaviours to know:**
+    - `delete.many` is not offered (Prisma 7 has no `deleteManyAndReturn`); use `delete.count`.
+    - `update.first` and `delete.first` are a read followed by a write narrowed to the record the read selected, and are
+      not atomic: the record written is one the read selected, or nothing is written and you are told (`A2014`). A
+      record that comes to sort first between the two statements is not seen. If firstness at the instant of the write
+      matters, select the record yourself and use `update.unique`/`delete.unique`.
+    - A serialization failure (`P2034`) is never retried automatically: a retry would re-run your pipeline callbacks.
+      Retrying is yours to decide.
+    - Whether transactions are offered depends on the driver and is part of the ClientContract hash, so generate the
+      client against the deployment's own driver.
+    - No raw SQL is ever issued.
+    - PostgreSQL and SQLite are supported.
+  - Every export has a `default` condition, so a CommonJS project can `require()` it. The manifest declares what the
+    adapter supports (providers, drivers, generators), which `@aventara/cli` reads.
+
+### Patch Changes
+
+- Updated dependencies
+  - @aventara/core@0.1.0-pilot.0

package/README.md

@@ -4,16 +4,16 @@ The Prisma 7 Adapter for Aventara. It discovers what a Prisma schema and its gen
 compiles that into an Aventara `AdapterModel`, and executes validated Aventara operations against a
 Prisma client the application owns.
 
-This document is written for the person wiring it into an application. It states what the adapter
+This document is written for the person setting it up in an application. It states what the adapter
 does, what it deliberately does **not** offer, and the two places where a correct Aventara operation
 has a weaker guarantee than its name suggests. Everything a consumer has to know is in the body of
 this file; nothing load-bearing is in a footnote.
 
-- **Status:** pilot. Two engines are proven — PostgreSQL and SQLite. Every other Prisma provider is
+- **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). 7.10.0 is the version the
-  error map was measured on; the adapter is bound to Prisma **7**'s error surface; see
+  error map targets; the adapter is bound to Prisma **7**'s error surface; see
   [Prisma 7 only](#prisma-7-only).
 
 ---
@@ -59,8 +59,8 @@ checks is a `crypto.subtle` promise — so every fence fires once, here, before
 
 ### `maxWait`, `timeout` and `isolationLevel` are adapter-owned
 
-They are provider concepts. Core's `Adapter.transaction(work)` seam carries no options and must not
-grow any, so these live on `createPrismaAdapter({ transactionOptions })` and are not Aventara public
+They are provider concepts. Core's `Adapter.transaction(work)` interface carries no options and will
+not grow any, so these live on `createPrismaAdapter({ transactionOptions })` and are not Aventara public
 configuration. Prisma's own defaults stand when they are absent: `maxWait` 2000 ms, `timeout` 5000 ms.
 
 Supported isolation levels come from the declared provider: PostgreSQL admits `ReadUncommitted`,
@@ -127,14 +127,15 @@ project's `devDependencies` — if you are generating a Prisma client at all, yo
 The step reads two sources in the same instant — the `schema.prisma` text and the generated client's
 own public types — and cross-checks them against each other. What it emits is a TypeScript module
 exporting one `discovery` value with eight members: the canonical `AdapterModel` (scalars, enums,
-Resources with fields, identifiers and available operations, plus the `transactions` capability), the
+Resources with fields, identifiers and available operations, plus the `transactions` capability and the
+`referenceWrites` limit), the
 Prisma addressing each Resource is reached by, the resolved referential actions per Resource, a record
 of the generated client it was read from (each model and its field references), the create
 requirements per Resource, a `modelHash`, and the `prismaVersion` it was generated against.
 
 The create requirements are what a create cannot do without — a column with no default, or a required
-relation, which may be written instead through the scalar fields that hold its reference — read off the
-question marks of the generated create inputs. The framework checks every create against them after
+relation, which may be written instead through the scalar fields that hold its reference (the edge's
+`references`, below) — read off the question marks of the generated create inputs. The framework checks every create against them after
 your pipes and computed behaviours have run, and answers a missing value as `A2004` with a `V1000`
 issue at its path (`["arguments", "data", "title"]`, or `["arguments", "data", "author"]` for a
 required relation) instead of letting the database refuse it. A nested create does not need the
@@ -177,7 +178,7 @@ Operation availability is **derived**, never assumed. Every omission is decided
 three facts: the generated delegate's own method set, the Resource's identifiers, and the driver's
 transaction capability.
 
-Across the pilot's representative schema the compiled Contracts advertise **fifteen** distinct
+For a typical schema the compiled Contracts advertise **fifteen** distinct
 `family.variant` operations, identically on all three Contract scopes. `delete.many` is **not** one of
 them.
 
@@ -198,7 +199,7 @@ are derived — so `if (provider === …)` is a compile error rather than a code
 the rule because a provider table is a second source of truth that drifts, silently, one Prisma
 release at a time.
 
-Observed consequences on the two pilot engines, all of them read from generated types rather than
+Consequences on PostgreSQL and SQLite, all of them read from generated types rather than
 tabulated:
 
 | Capability | PostgreSQL | SQLite | Read from |
@@ -213,7 +214,7 @@ tabulated:
 **Beyond PostgreSQL and SQLite nothing here 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 rather than failing at runtime — but the
-pilot makes no claim about them.
+this release makes no claim about them.
 
 ### `update.many` and `create.many` cannot project a to-many relation
 
@@ -277,7 +278,7 @@ no re-assertion can, because the missing fact is about a record that was never r
 
 This is a **documented, permitted property** of a framework-manufactured variant, published as
 policy rather than discovered in practice. Serializable isolation is not the remedy: core's
-`Adapter.transaction(work)` seam carries no isolation parameter, so an adapter cannot set a level for
+`Adapter.transaction(work)` interface carries no isolation parameter, so an adapter cannot set a level for
 a manufactured variant or for a plan, and a provider transaction's level is fixed before its first
 statement, so a per-operation escalation is not expressible at all. SQLite admits `Serializable`
 only, and the residual persists there regardless.
@@ -293,7 +294,7 @@ closed" without naming one is wrong.
 ### Why the write is by identifier and not by Prisma's `limit`
 
 Prisma **does** offer a top-level `limit` on `updateMany`, `deleteMany` and `updateManyAndReturn` in
-7.10.0 — measured, present on every model of both pilot engines. The adapter does not use it, and the
+7.10.0 — present on every model on PostgreSQL and SQLite. The adapter does not use it, and the
 reason is not concealment: Aventara's doctrine is to **expose** what the ORM offers, not to hide it.
 
 The reason is that `limit` **cannot express this operation**. None of those three argument types
@@ -321,13 +322,13 @@ prose, may change, and deliberately says less than the provider did.
 
 ### The three conflict codes
 
-Three situations used to collapse into one `409 A2008`. They no longer do.
+Three different situations each have their own code.
 
 | Code | Means | Retry? |
 |---|---|---|
 | `A2008 CONFLICT` | The operation would violate a **uniqueness or reference constraint** the Resource declares. Raised from Prisma's `P2002` and `P2003`. | No — re-running the same request unchanged fails the same way. |
 | `A2013 CONCURRENT_MODIFICATION` | Another operation **modified the same state concurrently**, so this operation was not applied and nothing was written. Raised from Prisma's `P2034`. | Yes, the same request may succeed. The framework performs **no** automatic retry. |
-| `A2014 STALE_SELECTION` | The state this operation had **selected changed** before its effect could be applied, so nothing was written. Raised by the first-variant manufacture's own seam. | Yes, the same request may succeed. No automatic retry. |
+| `A2014 STALE_SELECTION` | The state this operation had **selected changed** before its effect could be applied, so nothing was written. Raised by the adapter's `update.first` and `delete.first`. | Yes, the same request may succeed. No automatic retry. |
 
 `A2008` **narrowed** to the constraint case; it was not repurposed. If you previously treated `A2008`
 as "any conflict", the two situations that left it now have their own codes.
@@ -342,7 +343,7 @@ Two consequences worth stating explicitly:
   constraint; the envelope does **not** say so, and nothing should be parsed out of it.
 - **A write conflict and a deadlock share `A2013` deliberately.** Both arrive as `P2034` with
   identical `meta` keys, differing only in a provider-owned code (`40001` versus `40P01`) that never
-  crosses the boundary. They are not separable at this seam, so one outcome is the honest answer.
+  crosses the boundary. They cannot be told apart here, so one outcome is the honest answer.
 
 ### None of the three carries `cause.issues`
 
@@ -380,13 +381,13 @@ hook.
 answers `A3002 TRANSACTION_ERROR` for the failure that *ends* the transaction, and never reads the
 message text to decide anything.
 
-What is separable **structurally** (measured on both pilot engines, never inferred from docs):
+What is separable **structurally** (on PostgreSQL and SQLite, never inferred from docs):
 
 | Situation | Code | `meta` |
 |---|---|---|
 | Transaction-timeout expiry | `P2028` | `{ operation, timeout, timeTaken }` — the expiry is identifiable |
 | `maxWait` acquisition timeout | `P2028` | **empty** — identifiable *by* that emptiness, and by nothing finer |
-| Valid-but-unsupported isolation level (e.g. `Snapshot` on either pilot engine) | `P2028` | `{ isolationLevel }` |
+| Valid-but-unsupported isolation level (e.g. `Snapshot` on either engine) | `P2028` | `{ isolationLevel }` |
 | An isolation level outside Prisma's own set (e.g. `"Bogus"`) | **`P2023`** | `{ providedIsolationLevel }` — a different code entirely |
 
 The remaining **four** classes — transaction not found, already committed, already rolled back, and
@@ -431,7 +432,7 @@ transaction**. It is one `client.$transaction(async (tx) => …)` per Aventara t
 - the **root client is unreachable** from inside the callback: the executor core is handed closes over
   the transaction client and nothing else;
 - the value the callback threw is rethrown **by identity**. The adapter adds no `try`, no `catch` and
-  no wrapper, because that is what the seam requires and wrapping would turn every plan failure into
+  no wrapper, because that is what core's transaction interface requires and wrapping would turn every plan failure into
   an integrity failure.
 
 A first-style variant inside a plan **reuses the plan's transaction** rather than opening a nested
@@ -477,10 +478,10 @@ discovery.referentialActions;
 // {
 //   Shop:  { owningEdges: [] },
 //   Item:  { owningEdges: [{ field: "shop", target: "Shop",
-//                           cardinality: "one",
+//                           cardinality: "one", references: ["shopId"],
 //                           onDelete: "cascade", onUpdate: "cascade" }] },
 //   Clerk: { owningEdges: [{ field: "shop", target: "Shop",
-//                           cardinality: "one",
+//                           cardinality: "one", references: ["shopId"],
 //                           onDelete: "set-null", onUpdate: "cascade" }] },
 // }
 ```
@@ -492,14 +493,28 @@ To answer *"what does deleting a `Shop` do?"*, scan every Resource's `owningEdge
 (set-null). Both ends of that sentence are Resource names and nothing in the shape tells them apart, so
 the inverted reading produces no error at all, only a plan that reasons backwards.
 
+`references` are the edge's `@relation(fields: […])` — the scalars that hold the reference. A record
+that writes a relation and one of its reference fields both (`shopId` and `shop: { $connect: … }`,
+required relation or optional) is refused before the database is reached: `A2004` with a `V1012` issue
+at the relation, message `Set "shopId" or "shop", not both.` They are also what a required relation may
+be written through instead of the relation itself.
+
+Prisma takes one record's relations either all as relation writes or all through their reference
+fields — its checked and unchecked inputs — so every artifact's model states `referenceWrites: "uniform"`,
+and every Contract compiled from it carries the same member. A record that writes `shopId` beside
+another relation's write (`supplier: { $connect: … }`) is refused before the database is reached:
+`A2004` with a `V1012` issue at the relation write. A reference field beside a back-reference (a
+relation that holds no reference on that side, such as a shop's `items`) mixes nothing and is
+accepted.
+
 Only **owning** edges appear: PSL forbids the non-owning side of a relation from declaring an action,
 so a back-reference's answer is its partner's and carries no entry of its own. Both actions are
 *resolved* — an absent PSL argument is not a third state but Prisma's effective default (`set-null`
-where every foreign-key scalar is optional, `restrict` otherwise, `cascade` on update), measured on both
-pilot engines. An action spelling the reader cannot name stops the generate step rather than reaching
+where every foreign-key scalar is optional, `restrict` otherwise, `cascade` on update), on both
+PostgreSQL and SQLite. An action spelling the reader cannot name stops the generate step rather than reaching
 the artifact.
 
-Neither the model nor the compiled Contracts carry a referential action — the actions are beside the
+Neither the model nor the compiled Contracts carry a referential action or a reference field — the edges are beside the
 model and outside `modelHash`, so they move no Contract value and no hash. `createPrismaAdapter` states
 them to core through the adapter's optional `referentialActions` member, translated one to one into core's
 five words (mirroring Prisma's and SQL's actions; direction unchanged):
@@ -508,7 +523,7 @@ five words (mirroring Prisma's and SQL's actions; direction unchanged):
 |---|---|---|
 | `cascade` | `cascade` | deletes them, and the closure recurses into them |
 | `restrict` | `restrict` | refuses the delete while they reference it |
-| `no-action` | `noAction` | refuses the delete while they reference it — measured identical to `restrict` on both engines, because `NoAction` is not `DEFERRABLE` on either |
+| `no-action` | `noAction` | refuses the delete while they reference it — identical to `restrict` on both engines, because `NoAction` is not `DEFERRABLE` on either |
 | `set-null` | `setNull` | keeps them, the reference set to null |
 | `set-default` | `setDefault` | keeps them, the reference set to its column default |
 
@@ -522,8 +537,8 @@ what the schema says rather than collapsing it into what core currently reads.
 once, at framework construction, and the transaction planner refuses a step that depends on rows an
 earlier step's cascade removed — its own Resource, or one its arguments reach through a relation — with
 `A2004`/`V1019` *"Transaction step depends on a row removed by an earlier step's cascade"*, before any
-provider statement is issued. It is measured on both pilot engines against `Metric.author`
-(`onDelete: Cascade`), the pilot schemas' one cascade edge: deleting an `Author` and then reading its
+provider statement is issued. For example, with `Metric.author`
+(`onDelete: Cascade`) as the one cascade edge: deleting an `Author` and then reading its
 `Metric` rows is refused; deleting an `Author` and then reading `Post` (`Restrict`), or a `Category` and
 then `Post` (`SetNull`), is not. The refusal is per Resource — a plan cannot know which rows a delete
 will match — and plan-scoped: a single delete that cascades runs.
@@ -544,7 +559,7 @@ Prisma's typed delegate surface.
 
 ## Also worth knowing
 
-- **`$count` on a paginated relation reports the pre-pagination count.** Measured on both engines: a
+- **`$count` on a paginated relation reports the pre-pagination count.** On both engines, a
   relation's `_count` is unaffected by `take`/`skip`/`cursor` applied to the same relation in the same
   query. A filter on the relation *does* affect it.
 - **`limit`/`offset`/`cursor` are the public names.** Prisma's `take`/`skip` never surface.
@@ -555,7 +570,7 @@ Prisma's typed delegate surface.
   `find.first`, `update.first` and `delete.first` answer `A1001 NO_MATCH` with `null` data. The
   distinction is deliberate and is core's, not the adapter's.
 
-## Not covered by the pilot
+## Not covered
 
 Stated so nothing here reads as a claim it is not:
 

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

@@ -1,4 +1,4 @@
-import type { PrismaAdapterModel } from "./discovery-artifact.interface.js";
+import { type PrismaAdapterModel } from "./discovery-artifact.interface.js";
 /** Every artifact failure is this class, and every one of them says how to fix it. */
 export declare class PrismaDiscoveryArtifactError extends Error {
     /**
@@ -21,10 +21,5 @@ export type PrismaDiscoveryArtifactLoad = {
  * identity and into every generated client.
  */
 export declare function computeModelHash(model: PrismaAdapterModel): Promise<string>;
-/**
- * Validates an artifact and hands back its model **unchanged**.
- *
- * Three checks, in the order that makes each one's failure legible: shape, then
- * the `prismaVersion` major fence, then `modelHash`.
- */
+/** Validates an artifact and hands back its model **unchanged**. */
 export declare function loadDiscoveryArtifact(load: PrismaDiscoveryArtifactLoad): Promise<PrismaAdapterModel>;

package/dist/discovery/artifact.loader.js

@@ -1,4 +1,5 @@
-import { canonicalizeJson } from "@aventara/core";
+import { canonicalizeJson } from "@aventara/core/internal";
+import { DISCOVERY_ARTIFACT_FORMAT, } from "./discovery-artifact.interface.js";
 const HASH_PREFIX = "sha256:";
 const REGENERATION_INSTRUCTION = "Regenerate the discovery artifact — `npm run aventara:prepare` in a project " +
     "set up by `aventara`, or the adapter's generate step " +
@@ -32,6 +33,9 @@ function assertArtifactShape(artifact) {
     if (!isRecord(artifact)) {
         throw new PrismaDiscoveryArtifactError("The discovery artifact is not a JSON object.");
     }
+    if (artifact.regenerate_with_aventara_prepare !== DISCOVERY_ARTIFACT_FORMAT) {
+        throw new PrismaDiscoveryArtifactError("The discovery artifact was written by another version of @aventara/prisma7-adapter.");
+    }
     for (const key of ["prismaVersion", "provider", "modelHash"]) {
         if (typeof artifact[key] !== "string") {
             throw new PrismaDiscoveryArtifactError(`The discovery artifact's \`${key}\` is not a string.`);
@@ -59,6 +63,9 @@ function assertArtifactShape(artifact) {
         artifact.model.transactions !== "interactive") {
         throw new PrismaDiscoveryArtifactError("The discovery artifact's `model.transactions` is not a transaction capability.");
     }
+    if (artifact.model.referenceWrites !== "uniform") {
+        throw new PrismaDiscoveryArtifactError("The discovery artifact's `model.referenceWrites` is not `uniform`, which every Prisma model is.");
+    }
 }
 export async function loadDiscoveryArtifact(load) {
     const { artifact, installedPrismaVersion } = load;

package/dist/discovery/capability-surface.interface.d.ts

@@ -1,14 +1,4 @@
-/**
- * Nothing here is imported from `@prisma/client`: these are this adapter's own
- * facts over public generated types, which is what keeps discovery a pure function
- * of plain data and unit-testable without a client.
- *
- * Read `types.reader.ts`'s header for the two rules that give these facts their
- * meaning: only the 🟢 files are opened, and token-shaped facts come from the
- * **written** type arguments rather than from the instantiated reference.
- */
 export type PrismaCapabilitySurface = {
-    /** The EXISTENCE GATE: an entity is discoverable iff it appears here. */
     readonly resources: Readonly<Record<string, PrismaResourceSurface>>;
     /** `enums.ts`'s `as const` objects, in property order. */
     readonly enums: Readonly<Record<string, readonly string[]>>;
@@ -19,7 +9,6 @@ export type PrismaResourceSurface = {
     readonly relationFields: Readonly<Record<string, PrismaRelationSurface>>;
     /** `AtLeast<…, K>`'s key union — cross-check only; order unused. */
     readonly uniqueKeys: readonly string[];
-    /** `<M>Delegate`'s own methods → `ResourceOperations`. */
     readonly operations: readonly string[];
     /** e.g. `updateMany` → `["data", "where", "limit"]`. */
     readonly manyWriteArguments: Readonly<Record<string, readonly string[]>>;
@@ -29,24 +18,12 @@ export type PrismaScalarSurface = {
     readonly token: string;
     /** `<Kind>Filter` keys, in Prisma's spelling — NAMES ONLY. */
     readonly filters: readonly string[];
-    /**
-     * The operand SHAPE per filter key, as written in the generated type — because two
-     * engines can carry the same key with different operands, and a name set cannot
-     * express that: `path` is `string[]` on PostgreSQL and `string` on SQLite, and
-     * `in`/`notIn` admit `List<Kind>FieldRefInput` on PostgreSQL only.
-     */
     readonly filterOperands: Readonly<Record<string, string>>;
     /**
      * `<M>UncheckedCreateInput`'s entry for this field, read as the keys of the
      * `…Input` it references: `[]` for a plain value, and **`null` where the client
      * exposes no entry at all**, which is the only evidence that a column is not
      * creatable.
-     *
-     * The UNCHECKED input is the source because it is what the delegate accepts:
-     * `create`'s argument is `XOR<<M>CreateInput, <M>UncheckedCreateInput>`, and the
-     * checked half omits every foreign-key scalar (the relation owns it there). Read
-     * from the checked half, `Post.authorId` and `Post.categoryId` come back absent
-     * and Aventara would refuse writes Prisma accepts.
      */
     readonly createOperations: readonly string[] | null;
     /**
@@ -77,11 +54,6 @@ export type PrismaScalarSurface = {
      * `<Kind>FieldUpdateOperationsInput`, or of `<M>Update<field>Input` for a scalar
      * list (`set`, `push`), or `[]` for a plain value (`Json`), or `null` where the
      * client exposes no entry.
-     *
-     * Measured at 7.10.0 (2026-10-02): reading `<M>UpdateInput` instead under-reports
-     * six of the twenty-five scalar columns per engine — `Author.mentorId`,
-     * `Metric.authorId`, `Post.authorId`, `Post.categoryId`, `Category.id` and
-     * `Post.id` — every one of which `<M>UncheckedUpdateInput` admits.
      */
     readonly updateOperations: readonly string[] | null;
     readonly orderable: boolean;
@@ -89,19 +61,11 @@ export type PrismaScalarSurface = {
     readonly nullsOrderable: boolean;
 };
 export type PrismaRelationSurface = {
-    /** Read off `$<Target>Payload`'s own `name` literal, never off the alias's spelling. */
     readonly target: string;
     readonly many: boolean;
     readonly nullable: boolean;
     /** `ListRelationFilter` vs `[Nullable]ScalarRelationFilter`. */
     readonly filters: readonly string[];
-    /**
-     * `<T>CreateNested{One,Many}Without<M>Input` keys — the **create** stage's own
-     * nested-write input, read off `<M>CreateInput`'s entry for this edge.
-     *
-     * Reusing one list for both stages advertises five directives per to-many edge,
-     * and two per to-one edge, that Prisma has no key for at the create stage.
-     */
     readonly createMutations: readonly string[];
     /**
      * Whether `<M>CreateInput` — the CHECKED create input, the only one that carries
@@ -111,20 +75,15 @@ export type PrismaRelationSurface = {
      * entry for the edge at all.
      */
     readonly createRequired: boolean;
-    /** `<T>Update*Without<M>NestedInput` keys — the **update** stage's own input. */
     readonly updateMutations: readonly string[];
     /**
-     * `<M>$<edge>Args`'s own member names, as written. The edge's whole argument
-     * surface, because four separate capabilities are read off it — pagination,
-     * ordering, nested filtering of the returned edge, and projection — and a
-     * residual cannot answer the other three.
+     * Whether the update stage's `deleteMany` takes a `<T>ScalarWhereInput` — a filter of
+     * the target's scalar fields only, which `updateMany`'s `where` shares. Read off the
+     * nested input's own member type; `false` where the input has no `deleteMany` (a
+     * to-one edge, whose `update`/`delete` take a full `<T>WhereInput`).
      */
+    readonly scalarNestedWriteFilter: boolean;
     readonly edgeArguments: readonly string[];
-    /**
-     * {@link edgeArguments} minus what projection and predicate already own — a
-     * derived projection kept because it is the one a to-one/to-many split reads at
-     * a glance: a to-one edge leaves nothing.
-     */
     readonly pagination: readonly string[];
     /** The edge is admitted by `<M>OrderByWithRelationInput`. */
     readonly orderable: boolean;
@@ -133,22 +92,6 @@ export type PrismaRelationSurface = {
     /**
      * Whether **every** `<M>Select{Create,Update}ManyAndReturn` the client declares
      * lists this edge.
-     *
-     * # Presence, read. Not foreign-key ownership, computed
-     *
-     * The *explanation* for which edges survive into a bulk-returning write's
-     * projection is foreign-key ownership rather than cardinality — a to-one that does
-     * not hold its own FK is absent, which is what the `User`/`Profile` fixture exists
-     * to prove. That explanation is **not** the mechanism. The mechanism is this
-     * member: the edge is in the type, or it is not.
-     *
-     * **Every**, not *any*: one {@link ProjectionScope} covers both bulk-returning
-     * variants, so a scope the adapter advertises must hold in both. At 7.10.0 the two
-     * types agree member-for-member on both pilot engines, so the conjunction is
-     * currently indistinguishable from either half — `types.reader.spec.ts` asserts
-     * that agreement, so the day it stops holding is the day a reader reports it
-     * instead of silently picking a side. **Zero declared types answer `false`**,
-     * never vacuously `true`: a client with no `*AndReturn` type admits nothing there.
      */
     readonly bulkSelect: boolean;
     /** The {@link bulkSelect} question asked of `<M>Include{Create,Update}ManyAndReturn`. */
@@ -164,8 +107,8 @@ export type PrismaRelationSurface = {
      */
     readonly bulkReducers: boolean;
     /**
-     * Whether `<M>CreateManyInput` — the data argument of the bulk create — exposes an
-     * entry for this edge.
+     * Whether `<M>CreateManyInput` — the data argument of the bulk create — exposes
+     * an entry for this edge.
      */
     readonly bulkCreatable: boolean;
     /**