@aventara/prisma7-adapter 0.1.0-pilot.4 → 1.0.0-rc.1

package/README.md

@@ -1,30 +1,28 @@
 # `@aventara/prisma7-adapter`
 
 The Prisma 7 Adapter for Aventara. It discovers what a Prisma schema and its generated client can do,
-compiles that into an Aventara `AdapterModel`, and executes validated Aventara operations against a
+compiles that into an Aventara `AvAdapterModel`, and executes validated Aventara operations against a
 Prisma client the application owns.
 
-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.
+This README is for the person setting the adapter up in an application. It covers what the adapter
+does, what it does not offer, and the two operations whose guarantee is weaker than their names
+suggest. Everything you need is in the body of this file, not in footnotes.
 
-- **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 targets; the adapter is bound to Prisma **7**'s error surface; see
-  [Prisma 7 only](#prisma-7-only).
+- 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
+  7.10.0, and the adapter is bound to Prisma 7's error surface; see [Prisma 7 only](#prisma-7-only).
 
 ---
 
 ## The application owns the Prisma client, and a driver adapter is required
 
-`createPrismaAdapter` takes a client that is **already constructed**. It never constructs one, never
+`createPrismaAdapter` takes a client that is already constructed. It never constructs one, never
 reads a connection string, and never reads an environment variable. The application owns the client's
 lifetime, its pool, its logging, its extensions and its `$disconnect`.
 
-Prisma 7 reaches a database through a **driver adapter**, so the client you hand over must have been
+Prisma 7 reaches a database through a driver adapter, so the client you hand over must have been
 built with one. There is no fallback path, in Prisma or here.
 
 ```ts
@@ -47,31 +45,31 @@ const adapter = await createPrismaAdapter({
   transactionOptions: { timeout: 10_000, isolationLevel: "Serializable" },
 });
 
-const framework = await createFramework({ entrypoint: "/api", adapter });
+const framework = await createFramework({ api: "/api", adapter });
 ```
 
-`provider` and `driver` are **declared by the caller**. The adapter does not inspect client internals
-to guess them, because a guess that is wrong is worse than a declaration that is checked: the driver
-decides whether transactions are advertised at all.
+The caller declares `provider` and `driver`. The adapter does not inspect client internals to guess
+them: the driver decides whether transactions are advertised at all, and a wrong guess would be worse
+than a declaration that is checked.
 
 `createPrismaAdapter` is `async`. Construction verifies the discovery artifact, and the digest it
-checks is a `crypto.subtle` promise — so every fence fires once, here, before an adapter exists.
+checks is a `crypto.subtle` promise, so every check runs once, here, before an adapter exists.
 
 ### `maxWait`, `timeout` and `isolationLevel` are adapter-owned
 
 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.
+configuration. Prisma's own defaults apply when they are absent: `maxWait` 2000 ms, `timeout` 5000 ms.
 
-Supported isolation levels come from the declared provider: PostgreSQL admits `ReadUncommitted`,
+The supported isolation levels come from the declared provider. PostgreSQL admits `ReadUncommitted`,
 `ReadCommitted`, `RepeatableRead` and `Serializable`; SQLite admits `Serializable` only. Asking for a
-level the provider does not support fails the transaction — see [`P2028`](#p2028-covers-seven-situations-and-three-of-them-are-separable).
+level the provider does not support fails the transaction; see [`P2028`](#p2028-covers-seven-situations-and-three-of-them-are-separable).
 
 ---
 
 ## The generate step, and the artifact it emits
 
-Discovery runs **once, at generate time**, and writes a plain-data artifact. At runtime the adapter
+Discovery runs once, at generate time, and writes a plain-data artifact. At runtime the adapter
 loads that artifact, verifies it, and re-derives nothing.
 
 The step ships with the package, as a binary and as a second export:
@@ -87,23 +85,23 @@ npx aventara-prisma7-generate \
   --out      src/discovery.artifact.ts
 ```
 
-`--provider` and `--driver` are declared, never sniffed. The provider is recorded in the artifact; the
-driver decides `AdapterModel.transactions`, which is 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.
+`--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
+the application will actually construct the adapter with. The two cannot drift silently, but they can
+disagree, and core refuses construction when they do.
 
-**The toolchain the step runs on.** The step runs the Prisma 7 CLI itself: `@prisma/prisma7` (bin
-`prisma7`, the Prisma 7 CLI under its own name) when it is installed, otherwise `prisma` only when its
-version is in this package's declared `prisma` range. `npm i prisma` now installs a Prisma 8 release
-candidate, so a project that has Prisma 8 installed keeps `@prisma/prisma7` beside it; with neither
-usable the step refuses in one sentence naming both. TypeScript 6 is supported; TypeScript 7, which has
-no classic compiler API, is refused in one sentence.
+The step runs the Prisma 7 CLI itself: `@prisma/prisma7` (bin `prisma7`, the Prisma 7 CLI under its own
+name) when it is installed, otherwise `prisma` only when its version is in this package's declared
+`prisma` range. `npm i prisma` now installs a Prisma 8 release candidate, so a project that has Prisma 8
+installed keeps `@prisma/prisma7` beside it. With neither usable, the step refuses in one sentence naming
+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 dropped beside the client
-would break the next run.
+`--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.
 
-The same thing programmatically, for a project that already has a build script:
+The same step can run from code, for a project that already has a build script:
 
 ```ts
 import { generatePrismaDiscoveryArtifact } from "@aventara/prisma7-adapter/generate";
@@ -117,119 +115,124 @@ await generatePrismaDiscoveryArtifact({
 });
 ```
 
-**The two entries have different dependency shapes, deliberately.** `@aventara/prisma7-adapter`
-depends on `@aventara/core` and your generated client. `@aventara/prisma7-adapter/generate` additionally
-needs `typescript` and `prisma`, which are declared as **optional peer dependencies**: they are not
-installed on your behalf, nothing reachable from the runtime entry imports either, and so no compiler
-and no Prisma tooling enters a deployed runtime. If you call the generate entry, have both in your
-project's `devDependencies` — if you are generating a Prisma client at all, you already do.
-
-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
-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
-your pipes and computed behaviours have run, and answers a missing value as `A2004` with a `V1000`
+The two entries have different dependencies. `@aventara/prisma7-adapter` depends on `@aventara/core`
+and your generated client. `@aventara/prisma7-adapter/generate` also needs `typescript` and `prisma`,
+which are declared as optional peer dependencies. They are not installed for you, and nothing reachable
+from the runtime entry imports either, so no compiler and no Prisma tooling enters a deployed runtime.
+If you call the generate entry, have both in your project's `devDependencies`; a project that generates
+a Prisma client already does.
+
+The step reads two sources at the same time, the `schema.prisma` text and the generated client's own
+public types, and cross-checks them against each other. It emits a TypeScript module exporting one
+`discovery` value with eight members:
+
+- the canonical `AvAdapterModel` (scalars, enums, Resources with fields, identifiers, available
+  operations and create requirements, 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);
+- a `modelHash`;
+- the `prismaVersion` and database `provider` it was generated against;
+- the artifact's format (`regenerate_with_aventara_prepare`).
+
+Each Resource's create requirements are what a create cannot do without, read off the question marks
+of the generated create inputs: `required` lists the columns with no default (`["title"]`), and
+`oneOf` each required relation with the fields that hold its reference (`[["author", "authorId"]]`:
+write `author`, or `authorId`, not both). `parentSupplies` says which of them a nested create gets
+from its parent (`{ "Author": { "posts": ["author", "authorId"] } }`). They are part of the model, so
+they reach every Contract and the generated client: a create that leaves one out is a type error, and
+at runtime, after your pipes and computed behaviours have run, it is answered `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
-relation it is created through.
+required relation) before the database can refuse it.
 
-`modelHash` digests the **model** and nothing else. The addressing table, the referential actions, the
-client record and the create requirements sit beside it and outside the hash: a database-side rename or a foreign-key action carries no semantic
-content, and inside the hash either would move the Contract identity and force every generated client
-to be regenerated for nothing.
+`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.
+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.
 
-At construction — before the application listens — the adapter checks three things, and fails hard
-with an instruction to regenerate if any is wrong:
+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;
-3. the Prisma client you pass is the one the artifact was **generated from**: the same models, and the
+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;
+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
+   `prisma generate` but not by the generate step (a model or field added, removed or renamed) is
    refused in one sentence naming what differs:
 
    ```text
-   PrismaDiscoveryArtifactError: The Prisma client has changed since the discovery artifact was generated (model `Comment` is in the client and not in the artifact): run `npm run aventara:prepare` (the adapter's `aventara-prisma7-generate`) to regenerate it, then restart.
+   AvPrismaDiscoveryArtifactError: The Prisma client has changed since the discovery artifact was generated (model `Comment` is in the client and not in the artifact): run `npm run aventara:prepare` (the adapter's `aventara-prisma7-generate`) to regenerate it, then restart.
    ```
 
    A value with no recognisable model delegate (a test double, a deep mock) is not compared.
 
-What the client check does not see: a change that leaves every model and field name in place — a type,
-a default, an attribute. Run the generate step in the same build that runs `prisma generate` (a project
-set up by `aventara` does, from `postinstall` and `aventara:prepare`), and deploy the artifact with the
-schema and client it came from.
+The client check does not see a change that leaves every model and field name in place, such as a
+type, a default or an attribute. Run the generate step in the same build that runs `prisma generate`
+(a project set up by `aventara` does, from `postinstall` and `aventara:prepare`), and deploy the
+artifact with the schema and client it came from.
 
 ---
 
 ## What is advertised, what is not, and why
 
-Operation availability is **derived**, never assumed. Every omission is decided in one place, from
-three facts: the generated delegate's own method set, the Resource's identifiers, and the driver's
+Operation availability is derived, never assumed. Every omission is decided in one place, from three
+facts: the generated delegate's own method set, the Resource's identifiers, and the driver's
 transaction capability.
 
-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.
+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.
 
-### `delete.many` is not offered — use `delete.count`
+### `delete.many` is not offered: use `delete.count`
 
-Prisma 7.10.0 has no `deleteManyAndReturn`. `delete.many` owes its caller the deleted rows, and there
-is no provider call that returns them, so the variant is **omitted from every compiled Contract**
-rather than emulated. A request for it is refused by core with `A2002 UNKNOWN_OPERATION` before the
-adapter is reached — zero statements are issued.
+Prisma 7.10.0 has no `deleteManyAndReturn`. `delete.many` owes its caller the deleted rows, and no
+provider call returns them, so the variant is omitted from every compiled Contract instead of being
+emulated. Core refuses a request for it with `A2002 UNKNOWN_OPERATION` before the adapter is reached,
+and no statement is issued.
 
-**Use `delete.count`** to delete a filtered set. It answers a number, including zero.
+To delete a filtered set, use `delete.count`. It answers a number, including zero.
 
 ### Provider-gated capabilities are read from the client's own types, never from a provider table
 
-No module in this package branches on `provider`. A capability is advertised when the **generated
-client's own public types admit it**, and the provider name is not even in scope where capabilities
-are derived — so `if (provider === …)` is a compile error rather than a code-review question. That is
-the rule because a provider table is a second source of truth that drifts, silently, one Prisma
-release at a time.
+No module in this package branches on `provider`. A capability is advertised when the generated
+client's own public types admit it. The provider name is not even in scope where capabilities are
+derived, so `if (provider === …)` is a compile error. A provider table would be a second source of
+truth, and it would drift one Prisma release at a time.
 
-Consequences on PostgreSQL and SQLite, all of them read from generated types rather than
-tabulated:
+On PostgreSQL and SQLite, read from the generated types:
 
 | Capability | PostgreSQL | SQLite | Read from |
 |---|---|---|---|
-| Scalar list fields | advertised | **not advertised** — the connector rejects a list of primitives at schema validation | the schema's own validation plus the generated field set |
-| JSON `path` filter | advertised | **omitted** — the operand is a JSONPath `string` here and `string[]` there, and one protocol name cannot carry both | the written operand shape on `JsonFilter.path` |
+| Scalar list fields | advertised | not advertised: the connector rejects a list of primitives at schema validation | the schema's own validation plus the generated field set |
+| JSON `path` filter | advertised | omitted: the operand is a JSONPath `string` here and `string[]` there, and one protocol name cannot carry both | the written operand shape on `JsonFilter.path` |
 | Case-insensitive `mode`, JSON ordering operators, field-reference `in`/`notIn` operands | as the generated filter types admit | as the generated filter types admit | `<Kind>Filter`'s own members |
 | Explicit null ordering | advertised | advertised | `SortOrderInput`'s admission, per field |
 | `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 |
+| Transactions | `"interactive"` | `"interactive"` | the driver, not the provider (see below) |
 
-**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
-this release makes no claim about them.
+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.
 
 ### `update.many` and `create.many` cannot project a to-many relation
 
-On `update.many` and `create.many`, Prisma's row-returning bulk writes reach **to-one relations
-only**: the generated `*SelectUpdateManyAndReturn` / `*IncludeUpdateManyAndReturn` admit the scalars
-plus a to-one relation and carry no to-many relation and no `$count`, where the unrestricted
-`*Include` carries both.
+On `update.many` and `create.many`, Prisma's row-returning bulk writes reach to-one relations only.
+The generated `*SelectUpdateManyAndReturn` / `*IncludeUpdateManyAndReturn` admit the scalars plus a
+to-one relation and carry no to-many relation and no `$count`, where the unrestricted `*Include`
+carries both.
 
-A to-one projection on `update.many` works. A projection reaching a **to-many** relation or `$count`
-on these two variants is refused before any statement runs: `A2004` (a validation error) with the
-issue `V1008`, nothing written. The Contract advertises each relation's projection per position, and
+A to-one projection on `update.many` works. A projection reaching a to-many relation or `$count` on
+these two variants is refused before any statement runs: `A2004` (a validation error) with the issue
+`V1008`, and nothing is written. The Contract advertises each relation's projection per position, and
 on these two variants the position the bulk result is read in does not include to-many relations.
 
-**In practice:** keep `update.many`/`create.many` projections to scalars and to-one relations; read
-to-many relations with a separate `find`. The adapter deliberately does **not** paper over the gap
-with a follow-up read: that would add a statement and a new consistency window to a bulk write.
+Keep `update.many`/`create.many` projections to scalars and to-one relations, and read to-many
+relations with a separate `find`. The adapter does not fill the gap with a follow-up read, which would
+add a statement and a new consistency window to a bulk write.
 
 ---
 
@@ -237,87 +240,84 @@ with a follow-up read: that would add a statement and a new consistency window t
 
 Read this section before using either.
 
-Aventara's first-style write — *general filter · ordering decides "first" · effect limited to one
-record · the affected record is returned, in one call* — is essentially absent across ORM design,
-because SQL splits the ingredients along a dialect fault line: `UPDATE … ORDER BY … LIMIT` is a
-MySQL/MariaDB extension while `RETURNING` is PostgreSQL/SQLite/MSSQL, so whichever dialect grants the
-limit denies the returning. Prisma 7.10.0's operation set has no `updateFirst` and no `deleteFirst`
-at all.
+Aventara's first-style write takes a general filter, lets the ordering decide which record is "first",
+limits the effect to that one record, and returns the affected record, all in one call. ORMs almost
+never offer this, because SQL splits the ingredients between dialects: `UPDATE … ORDER BY … LIMIT` is
+a MySQL/MariaDB extension while `RETURNING` is PostgreSQL/SQLite/MSSQL, so whichever dialect grants the
+limit denies the returning. Prisma 7.10.0's operation set has no `updateFirst` and no `deleteFirst` at
+all.
 
-So these two are **not** a Prisma-shaped gap an adapter might fill. They are operations the framework
-**manufactures**, out of two statements, inside one adapter-internal transaction:
+The framework builds these two operations out of two statements, inside one adapter-internal
+transaction:
 
 1. `findFirst` with the caller's `where` and `orderBy`, selecting the Resource's identifier. The
-   `orderBy` is the selector for *which* record — ordering and single-record selection are natural on
-   a read. No match answers `A1001 NO_MATCH` with `null` data, and nothing is written.
-2. `update` / `delete` narrowed to the identifier the read returned, **with the caller's original
-   predicate re-asserted alongside it**, carrying the caller's own projection — so the record the
-   contract owes comes back from the write itself. Nothing spare is read, and nothing is stripped.
+   `orderBy` selects which record; ordering and single-record selection are natural on a read. No
+   match answers `A1001 NO_MATCH` with `null` data, and nothing is written.
+2. `update` / `delete` narrowed to the identifier the read returned, with the caller's original
+   predicate re-asserted alongside it, carrying the caller's own projection, so the record the
+   contract owes comes back from the write itself. Nothing extra is read, and nothing is stripped.
 
-They are therefore **non-atomic**, and they have a **defined conflict outcome**. The Contract's own
-vocabulary says so: a *manufactured*, *non-atomic* variant. Neither is ever described as atomic.
+They are therefore non-atomic, and they have a defined conflict outcome. The Contract's own vocabulary
+calls them manufactured, non-atomic variants, and neither is ever described as atomic.
 
 ### What re-assertion closes, which race that is, and the residual it leaves
 
-Re-asserting the caller's predicate on the write closes the **wrong-record race**. Without it the
-write is by identifier alone and could mutate a record that no longer matches what the caller asked
-for; with it the write can only ever reach a record the read selected, and a record that left the
-predicate in between is **detected** rather than mis-mutated — it answers
-`A2014 STALE_SELECTION` (409) with nothing written, and a retry may succeed.
-
-**The published guarantee, verbatim:** *the record written is one the read selected, or nothing is
-written and the caller is told.*
-
-**It does not close stale firstness, and nothing can.** Between the read and the write another writer
-can insert or update a record that sorts *ahead* of the selected one and still matches the original
-predicate. Both statements are blind to it — the read never saw it, and the re-asserted write
-succeeds against the record it was given — so `update.first` can mutate a record that is no longer
-the first ordered match and report **ordinary success**. Nothing detects it, nothing reports it, and
-no re-assertion can, because the missing fact is about a record that was never read.
-
-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)` 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.
-
-**If your operation's correctness depends on the record still being the first ordered match at the
-instant of the write, do not use `update.first`/`delete.first`.** Select the record yourself and use
+Re-asserting the caller's predicate on the write closes the wrong-record race. Without it, the write
+would go by identifier alone and could change a record that no longer matches what the caller asked
+for. With it, the write can only reach a record the read selected. A record that left the predicate in
+between is detected instead of changed: it answers `A2014 STALE_SELECTION` (409) with nothing written,
+and a retry may succeed.
+
+The published guarantee is: *the record written is one the read selected, or nothing is written and
+the caller is told.*
+
+Re-assertion does not close stale firstness, and nothing can. Between the read and the write another
+writer can insert or update a record that sorts ahead of the selected one and still matches the
+original predicate. Neither statement sees it (the read never saw it, and the re-asserted write
+succeeds against the record it was given), so `update.first` can change a record that is no longer the
+first ordered match and report ordinary success. Nothing detects or reports this, and no re-assertion
+can, because the missing fact is about a record that was never read.
+
+This is a documented, permitted property of a framework-manufactured variant. Serializable isolation
+does not fix it. Core's `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 cannot be expressed at all.
+SQLite admits `Serializable` only, and the residual persists there regardless.
+
+If your operation's correctness depends on the record still being the first ordered match at the
+moment of the write, do not use `update.first`/`delete.first`. Select the record yourself and use
 `update.unique`/`delete.unique` on an identifier, inside a transaction plan whose other operations
 make the invariant you need checkable.
 
-Wherever this document says a race is closed, it names which race. A sentence that says "the race is
-closed" without naming one is wrong.
+Wherever this README says a race is closed, it names which race.
 
 ### 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 — 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.
+Prisma does offer a top-level `limit` on `updateMany`, `deleteMany` and `updateManyAndReturn` in
+7.10.0, on every model on PostgreSQL and SQLite. Aventara exposes what the ORM offers, so this is not
+a choice to hide it.
 
-The reason is that `limit` **cannot express this operation**. None of those three argument types
-carries an `orderBy`. So `limit: 1` affects an **arbitrary** matching row, and two identical calls can
-affect different ones. The identifier from the ordered read is what makes the write deterministic.
+`limit` cannot express this operation. None of those three argument types carries an `orderBy`, so
+`limit: 1` affects an arbitrary matching row, and two identical calls can affect different rows. The
+identifier from the ordered read is what makes the write deterministic.
 
-So, stated plainly rather than presented as a principle: **Aventara does not currently expose an
-arbitrary affected-row cap.** If it ever does, it will be named so that nobody can mistake it for an
-ordered window — the hazard belongs in the identifier, not in a sentence beside it.
+Aventara does not currently expose an arbitrary affected-row cap. If it ever does, its name will make
+clear that it is not an ordered window.
 
 ---
 
 ## Errors
 
-### A caller discriminates by **code**, never by message text
+### Branch on the code, never on the message text
 
 Every failure this adapter originates carries framework-authored text and nothing read off the Prisma
 error. No table name, constraint name, column name, SQL fragment, connection string, file path or
-stack reaches a caller — the normalizer never reads the provider's `message` at all, so there is no
-provider string in scope to forward. The whole serialized envelope of every failing path is swept for
-provider markers by this package's own conformance gate.
+stack reaches a caller. The normalizer never reads the provider's `message`, so there is no provider
+string in scope to forward. This package's own conformance gate sweeps the whole serialized envelope
+of every failing path for provider markers.
 
-The consequence is a rule, not an inconvenience: **branch on the code.** Message text is framework
-prose, may change, and deliberately says less than the provider did.
+So branch on the code. Message text is framework prose, may change, and says less than the provider
+did.
 
 ### The three conflict codes
 
@@ -325,137 +325,131 @@ 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 adapter's `update.first` and `delete.first`. | Yes, the same request may succeed. No automatic 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 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.
+`A2008` was narrowed to the constraint case, not repurposed. If you previously treated `A2008` as "any
+conflict", the two situations that left it now have their own codes.
 
-Two consequences worth stating explicitly:
+`A2008`'s narrowed meaning lives in the specification, not in the wire text. The emitted message stays
+*"The operation conflicts with the current state of the resource."* The words "uniqueness" and
+"constraint" are the provider's own words for this failure, and the sanitization rule bans them from a
+provider-originated envelope because it cannot tell a framework-authored "constraint" from Prisma's.
+So this README can say `A2008` means a uniqueness or reference constraint, but the envelope does not
+say so, and nothing should be parsed out of it.
 
-- **`A2008`'s narrowed meaning lives in the specification, not in the wire text.** The emitted message
-  stays *"The operation conflicts with the current state of the resource."* The words "uniqueness" and
-  "constraint" are exactly the provider's own words for this failure and are banned from a
-  provider-originated envelope by the sanitization rule, which cannot tell a framework-authored
-  "constraint" from Prisma's. So this README may say `A2008` *means* a uniqueness or reference
-  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 cannot be told apart here, so one outcome is the honest answer.
+A write conflict and a deadlock share `A2013`. Both arrive as `P2034` with identical `meta` keys and
+differ only in a provider-owned code (`40001` versus `40P01`) that never crosses the boundary. They
+cannot be told apart here, so they get one outcome.
 
 ### None of the three carries `cause.issues`
 
-`A2008`, `A2013` and `A2014` pair with **no** validation code and carry `cause.issues` **absent** — as
-a rule, not as an accident. A conflict is not a Framework Validation Layer failure: validation codes
-*determine* the outcome code and roll up only to the validation outcomes, so a conflict validation
-code would have no legal rollup. Do not write a caller that expects `issues` on a conflict.
+`A2008`, `A2013` and `A2014` pair with no validation code, and `cause.issues` is always absent on
+them. A conflict is not a Framework Validation Layer failure: validation codes determine the outcome
+code and roll up only to the validation outcomes, so a conflict validation code would have no legal
+rollup. Do not write a caller that expects `issues` on a conflict.
 
 ### `P2034` is never retried automatically
 
-Neither Prisma nor this adapter retries a write conflict, and the adapter will not grow one. A
-transaction plan's operations run developer-authored pipeline callbacks, and **re-running a plan
-re-runs those callbacks** — including after hooks whose external side effects are not rollback-safe
-(see below). A retry is the caller's to make, having decided its own operations are safe to repeat.
+Neither Prisma nor this adapter retries a write conflict, and the adapter will not grow a retry. A
+transaction plan's operations run developer-authored pipeline callbacks, and re-running a plan re-runs
+those callbacks, including after hooks whose external side effects are not rollback-safe (see below).
+The caller makes a retry, after deciding its own operations are safe to repeat.
 
 ### An after hook's external side effect inside a plan runs before the commit
 
-State this as a pair, because the behaviour alone reads as a bug and the obligation is what makes it
-a property.
+Inside a transaction plan, a pipeline after hook runs inside the provider transaction, and therefore
+before the provider commits. If a later operation fails, the provider rolls back: the row is absent
+but the external effect has already happened. An email was sent, a queue message published or a cache
+written, for a record that does not exist.
 
-Inside a transaction plan, a pipeline after hook runs **inside** the provider transaction — therefore
-**before** the provider commits. If a later operation fails, the provider rolls back: the row is
-absent and the external effect has already happened. An email was sent, a queue message published, a
-cache written, for a record that does not exist.
-
-That is not a defect to be fixed by the adapter; it is the shape the specification describes, and it
-is asserted against a real provider commit by this package's conformance gate. **The duty is the
-hook author's:** an after hook SHOULD be observational or idempotent, and MUST NOT be relied on to
-undo a mutation. If an effect must not happen unless the plan commits, do not perform it in an after
-hook.
+The specification describes this behaviour, and this package's conformance gate asserts it against a
+real provider commit. The duty falls on the hook author: an after hook SHOULD be observational or
+idempotent, and MUST NOT be relied on to undo a mutation. If an effect must not happen unless the plan
+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 it is shared by **seven** internal classes. The adapter
-answers `A3002 TRANSACTION_ERROR` for the failure that *ends* the transaction, and never reads the
-message text to decide anything.
+`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.
 
-What is separable **structurally** (on PostgreSQL and SQLite, never inferred from docs):
+What can be told apart from the error's structure, measured on PostgreSQL and SQLite:
 
 | 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 |
+| 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 engine) | `P2028` | `{ isolationLevel }` |
-| An isolation level outside Prisma's own set (e.g. `"Bogus"`) | **`P2023`** | `{ providedIsolationLevel }` — a different code entirely |
+| 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
-an internal consistency failure — carry **no `meta` at all** and differ only in their message text.
-Reading error text to tell outcomes apart is forbidden here, so those four are **inseparable**, and
-the acquisition timeout is inseparable *from them*. That is Prisma's limit, not a gap in this
-adapter, and it is recorded so nobody later closes it with message parsing.
+The other four classes (transaction not found, already committed, already rolled back, and an internal
+consistency failure) carry no `meta` at all and differ only in their message text. Reading error text
+to tell outcomes apart is not allowed here, so those four cannot be told apart, and the acquisition
+timeout cannot be told apart from them. That limit is Prisma's, and it is recorded here so nobody later
+works around it by parsing messages.
 
-One asymmetry worth knowing: a `P2028` that ends the transaction rejects out of `$transaction` and
-becomes `A3002`. A `P2028` raised by a *delegate call inside* the callback is unrecognised by the
-closed code table, so it becomes `A3001` attributed to that operation.
+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.
 
 ### Everything unrecognised becomes `A3001`
 
-The code table contains only codes that were **induced** against a real engine on a real schema. A
-Prisma code the table does not contain is deliberately left to core's adapter boundary, which answers
-`A3001 ADAPTER_ERROR` with core's own text and sends the raw error to the diagnostics sink. Adding a
-row later is additive; shipping a guessed one is not recoverable.
+The code table contains only codes that were induced against a real engine on a real schema. A Prisma
+code the table does not contain is left to core's adapter boundary, which answers `A3001 ADAPTER_ERROR`
+with core's own text and sends the raw error to the diagnostics sink. Adding a row later is additive;
+a guessed row, once shipped, cannot be taken back.
 
 ### Prisma 7 only
 
-The code table's keys are P-codes, which are **7.x**'s error surface. Prisma 8 (a release candidate in October 2026)
-is a rewrite: no `@prisma/client`, no `prisma generate`, no driver adapters, dotted `NAMESPACE.SUBCODE` errors with no
-P-codes yet. A Prisma 8 adapter is therefore a **new adapter package**, `@aventara/prisma8-adapter`, not a re-map of
-this one. A project keeping Prisma 7 beside a Prisma 8 install runs the Prisma 7 CLI as `@prisma/prisma7` (bin
-`prisma7`), which the generate step prefers. The
-bound is enforced rather than described: the package's own suite reads the installed
-`@prisma/client`'s version and fails if the major is not `7`, and the discovery artifact records the
-major it was generated against.
+The code table's keys are P-codes, which are Prisma 7.x's error surface. Prisma 8 (a release candidate
+in October 2026) is a rewrite: no `@prisma/client`, no `prisma generate`, no driver adapters, and dotted
+`NAMESPACE.SUBCODE` errors with no P-codes yet. A Prisma 8 adapter will therefore be a new adapter
+package, `@aventara/prisma8-adapter`, instead of a re-map of this one. A project keeping Prisma 7 beside
+a Prisma 8 install runs the Prisma 7 CLI as `@prisma/prisma7` (bin `prisma7`), which the generate step
+prefers. The bound is enforced: the package's own suite reads the installed `@prisma/client`'s version
+and fails if the major is not `7`, and the discovery artifact records the major it was generated
+against.
 
 ---
 
 ## Transactions
 
-`Adapter.transaction` is mounted **exactly when the declared driver supports an interactive
-transaction**. It is one `client.$transaction(async (tx) => …)` per Aventara transaction plan:
+`Adapter.transaction` is mounted exactly when the declared driver supports an interactive
+transaction. It is one `client.$transaction(async (tx) => …)` per Aventara transaction plan:
 
-- the **callback** form only — never the array form. An Aventara plan is sequential by contract, so
-  operation *n* may consume operation *n − 1*'s result and the second call's arguments do not exist
-  until the first has answered. The array form takes every call up front, so it cannot honour a plan
-  at all, and it is not even representable through the interface this adapter holds;
-- 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 core's transaction interface requires and wrapping would turn every plan failure into
-  an integrity failure.
+- It uses the callback form only, never the array form. An Aventara plan is sequential by contract, so
+  operation *n* may consume operation *n − 1*'s result, and the second call's arguments do not exist
+  until the first has answered. The array form takes every call up front, so it cannot carry a plan at
+  all, and the interface this adapter holds cannot even represent it.
+- 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 core's transaction interface requires that, 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
-one, so its two statements roll back *with* the plan rather than independently.
+A first-style variant inside a plan reuses the plan's transaction instead of opening a nested one, so
+its two statements roll back with the plan, not independently.
 
-**Prisma swallows its own rollback failures** — the rollback's rejection reaches an internal debug
-logger and never the caller. So this adapter never claims a rollback succeeded, because it cannot
+Prisma swallows its own rollback failures: the rollback's rejection reaches an internal debug logger
+and never the caller. This adapter therefore never claims a rollback succeeded, because it cannot
 observe that it did. A commit failure is different: it rejects like a callback throw.
 
 ### `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"`: Cloudflare D1 rejects interactive transactions,
+and Prisma says so itself. `@prisma/adapter-pg` and `@prisma/adapter-better-sqlite3` declare
+`"interactive"`, observed by running one.
 
-**This has a consequence consumers must plan for.** The `transactions` capability participates in the
-**ClientContract hash**, and a generated client **fails hard** on a hash mismatch. So one schema, one
-framework configuration and two deployment drivers produce two ClientContracts, two hashes and two
-generated clients — and a client generated against a `"none"` deployment will not run against an
-`"interactive"` one, or the reverse.
+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
+deployment drivers produce two ClientContracts, two hashes and two generated clients, and a client
+generated against a `"none"` deployment will not run against an `"interactive"` one, or the reverse.
 
-Practically: **generate your client against the deployment's own driver**, and treat the driver as
-part of the deployment identity rather than as a connection detail. If you deploy the same application
-over D1 and over PostgreSQL, those are two deployments with two generated clients.
+Generate your client against the deployment's own driver, and treat the driver as part of the
+deployment's identity, not as a connection detail. If you deploy the same application over D1 and over
+PostgreSQL, those are two deployments with two generated clients.
 
 An artifact and a driver cannot drift silently either: an artifact that says `"interactive"` loaded by
 an adapter whose declared driver says `"none"` makes framework construction fail with a capability
@@ -465,111 +459,163 @@ mismatch.
 
 ## Referential actions
 
-**The artifact carries them, the adapter states them to core, and core refuses a transaction plan that
-depends on rows a cascade removed.**
+The artifact carries the referential actions, the adapter states them to core, and core refuses a
+transaction plan that depends on rows a cascade removed.
 
-The generate step resolves each relation edge's referential actions — including the defaults Prisma
-applies when the PSL argument is absent — cross-checks them while reading the schema, and emits them as
-the artifact's `referentialActions` member:
+The generate step resolves each relation edge's referential actions, including the defaults Prisma
+applies when the PSL argument is absent. It cross-checks them while reading the schema, and emits them
+as the artifact's `referentialActions` member:
 
 ```ts
 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" }] },
 // }
 ```
 
-**Read it in one direction.** `onDelete` is declared on the **child** and fires when the **parent** is
-deleted, so an entry under Resource `R` says *deleting a `target` row does `onDelete` to rows of `R`*.
-To answer *"what does deleting a `Shop` do?"*, scan every Resource's `owningEdges` for
-`target === "Shop"` and read the enclosing Resource key — above, that is `Item` (cascade) and `Clerk`
-(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.
-
-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), 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
-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):
+Read it in one direction. `onDelete` is declared on the child and fires when the parent is deleted, so
+an entry under Resource `R` says *deleting a `target` row does `onDelete` to rows of `R`*. To answer
+*"what does deleting a `Shop` do?"*, scan every Resource's `owningEdges` for `target === "Shop"` and
+read the enclosing Resource key: above, that is `Item` (cascade) and `Clerk` (set-null). Both ends of
+that sentence are Resource names and nothing in the shape tells them apart, so reading it backwards
+produces no error, only a plan that reasons backwards.
+
+`references` are the edge's `@relation(fields: […])`, the scalars that hold the reference. A record
+that writes both a relation and one of its reference fields (`shopId` and `shop: { $connect: … }`,
+whether the relation is required or optional) is refused before the database is reached: `A2004` with
+a `V1012` issue at the relation, message `Set "shopId" or "shop", not both.` The reference fields 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 has no entry of its own. Both actions are resolved: an
+absent PSL argument means Prisma's effective default (`set-null` 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 before it reaches the artifact.
+
+Neither the model nor the compiled Contracts carry a referential action or a reference field. The edges
+sit 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):
 
 | Prisma action | core's word | deleting a `target` row does this to rows of the enclosing Resource |
 |---|---|---|
 | `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 — 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 |
 
 Only `cascade` drives core behaviour (the `V1019` closure below). `restrict`, `noAction`, `setNull` and
-`setDefault` are carried as informational adapter facts: the adapter states
-what the schema says rather than collapsing it into what core currently reads.
+`setDefault` are carried as informational adapter facts: the adapter states what the schema says
+instead of reducing it to what core currently reads.
 
-`onUpdate` is not carried: core plans the **delete** closure only.
+`onUpdate` is not carried, because core plans the delete closure only.
 
-**Planning-phase refusal.** Core builds the transitive closure of `cascade` edges
-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. 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.
+Core builds the transitive closure of `cascade` edges once, at framework construction. 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. 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, since a plan cannot know
+which rows a delete will match, and it is plan-scoped: a single delete that cascades runs.
 
 ---
 
-## No raw SQL
+## Raw SQL: developer statements only, always bound
+
+Aventara never writes raw SQL itself. Every standard operation goes through Prisma's typed delegate
+surface. `$queryRawUnsafe`, `$executeRaw`, `$executeRawUnsafe`, `findRaw`, `aggregateRaw` and
+`$runCommandRaw` appear nowhere in this package, and no raw action is representable in the plan the
+translator builds; a test pins that plan to the closed set of thirteen Prisma actions the adapter may
+issue.
+
+Developer SQL reaches the database two ways, both written as a tagged template: `framework.appTx.$sql`,
+a step of an application transaction, and a pipeline stage's `ctx.$sql`, run at once.
 
-The adapter issues **no raw SQL, ever**. `$queryRaw`, `$executeRaw`, the `…Unsafe` variants,
-`findRaw`, `aggregateRaw` and `$runCommandRaw` appear nowhere in this package, public or internal —
-and a raw action is not representable in the plan the translator builds, which is pinned by a test
-asserting the closed set of thirteen Prisma actions the adapter may issue.
+```ts
+const post = framework.appTx.Post.create.one({ data: { title, authorId }, select: ["id"] });
+const job = framework.appTx.$sql<{ msg_id: bigint }>`
+  select pgmq.send('jobs', jsonb_build_object('postId', ${post.$ref("id")}))`;
+const [created, rows] = await framework.transaction([post, job]);
+// rows is { msg_id: bigint }[]
+```
 
-This is an architectural rule with no exception attached. Everything the adapter does, it does through
-Prisma's typed delegate surface.
+The adapter runs it with `$queryRaw` in its tagged-template form. Inside a transaction (an
+`appTx.$sql` step, or a `ctx.$sql` in a step, a forced call or a `ctx.$transaction`) it runs on the
+interactive transaction client, so the statement commits or rolls back with the transaction. A
+`ctx.$sql` made outside any transaction runs on the base client as a plain statement: no `BEGIN` is
+sent around it, so it needs no interactive transaction and works with `@prisma/adapter-d1` too. The
+adapter declares `sqlStatements` with every driver. Every interpolated value is
+a bound parameter, never SQL text, so the text is static and a table or column name cannot come from
+a value. What it binds, measured on both engines with 7.10.0:
+
+- a JSON value (a plain object or array) is bound as its JSON text: cast it, `${value}::jsonb` on
+  PostgreSQL, or read it with `json_extract(${value}, '$.k')` on SQLite;
+- an Aventara `AvDecimal` is bound as its exact decimal text; a `Date`, `bigint`, `Uint8Array` and the
+  primitives are bound as Prisma binds them;
+- a bare placeholder is the database's to type: PostgreSQL reads `select ${1}` as `text`, so cast where
+  the type matters.
+
+The rows come back as `$queryRaw` reads them, except that a PostgreSQL `numeric` becomes Aventara's
+`AvDecimal`. Prisma 7.10.0 cannot read a SQLite BLOB column out of a raw query; such a statement fails
+with `A3001`.
+
+A raw query's failure is always `P2010` on 7.10.0, a syntax error and a constraint violation alike.
+The adapter tells them apart by the driver adapter's own `cause.kind`, never by message text. A
+uniqueness or foreign-key violation answers `A2008`, as it does through a delegate, and everything
+else (a syntax error, a missing table, a null violation) answers `A3001` with the raw error in
+diagnostics. Either way the whole plan rolls back.
+
+`appTx.$sql` exists only in process. `clientTx` has no SQL step, the ClientContract carries nothing of
+it, and no `/_transactions` request can express one. A later step cannot `$ref` a SQL step's rows
+(`A2007`/`V1010`). No guard, pipe, hook, interceptor or filter runs around a SQL step, since it has no
+Resource or operation for one to wrap.
 
 ---
 
-## Also worth knowing
+## Other behaviour
 
-- **`$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.
-- **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.
-- **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;
+- `$count` on a paginated relation reports the count before pagination. 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.
+- 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.
+- 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
-  distinction is deliberate and is core's, not the adapter's.
+  distinction is core's, not the adapter's.
 
 ## Not covered
 
-Stated so nothing here reads as a claim it is not:
-
 - every provider except PostgreSQL and SQLite;
-- implicit many-to-many relations, `type` / `view` / composite blocks and multi-schema — each arrives
-  as a recorded unknown that **stops the generate step** rather than mapping silently;
-- `@default` forms beyond `uuid()`, `cuid()`, `autoincrement()`, `now()` and `dbgenerated(…)` — an
+- implicit many-to-many relations, `type` / `view` / composite blocks and multi-schema. Each arrives
+  as a recorded unknown that stops the generate step instead of mapping silently;
+- `@default` forms beyond `uuid()`, `cuid()`, `autoincrement()`, `now()` and `dbgenerated(…)`. An
   unmatched form is recorded as a defaulted field plus an unknown that fails the generate step, so an
   unconfirmed mapping cannot become a wrong model;
 - whether Neon-HTTP or PlanetScale-HTTP support interactive transactions in Prisma 7. Those drivers
-  are **absent** from the driver set rather than declared `"none"`: an entry with no evidence is a
-  guess.
+  are absent from the driver set instead of declared `"none"`, because an entry with no evidence would
+  be a guess.
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.