@aventara/prisma7-adapter 0.1.0-pilot.0

package/README.md

@@ -0,0 +1,564 @@
+# `@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
+Prisma client the application owns.
+
+This document is written for the person wiring it into 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
+  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
+  [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
+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
+built with one. There is no fallback path, in Prisma or here.
+
+```ts
+import { PrismaPg } from "@prisma/adapter-pg";
+import { createFramework } from "@aventara/core";
+import { createPrismaAdapter } from "@aventara/prisma7-adapter";
+import { PrismaClient } from "./generated/client.js";          // your generated client
+import { discovery } from "./generated/aventara.artifact.js";   // the generate step's output
+
+const client = new PrismaClient({
+  adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
+});
+
+const adapter = await createPrismaAdapter({
+  client,
+  discovery,
+  provider: "postgresql",                 // declared, never sniffed
+  driver: "@prisma/adapter-pg",           // declared, never sniffed
+  // Adapter-owned, and not part of Aventara's public configuration:
+  transactionOptions: { timeout: 10_000, isolationLevel: "Serializable" },
+});
+
+const framework = await createFramework({ entrypoint: "/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.
+
+`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.
+
+### `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
+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`,
+`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).
+
+---
+
+## The generate step, and the artifact it emits
+
+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:
+
+```bash
+prisma generate                           # your client, as usual
+
+npx aventara-prisma7-generate \
+  --schema   prisma/schema.prisma \
+  --client   src/generated \
+  --provider postgresql \
+  --driver   @prisma/adapter-pg \
+  --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.
+
+**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.
+
+**`--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.
+
+The same thing programmatically, for a project that already has a build script:
+
+```ts
+import { generatePrismaDiscoveryArtifact } from "@aventara/prisma7-adapter/generate";
+
+await generatePrismaDiscoveryArtifact({
+  schema: "prisma/schema.prisma",
+  clientDirectory: "src/generated",
+  provider: "postgresql",
+  driver: "@prisma/adapter-pg",
+  artifactFile: "src/discovery.artifact.ts",
+});
+```
+
+**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 six 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
+`modelHash`, and the `prismaVersion` it was generated against.
+
+`modelHash` digests the **model** and nothing else. The addressing table and the referential actions 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.
+
+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 the adapter checks exactly two things, and fails hard with an instruction to
+regenerate if either 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.
+
+### The residual those two checks do not cover
+
+Neither check detects an artifact generated from an **older schema or client at the same major**. A
+stale artifact that is internally consistent and still Prisma 7 loads without complaint, and the
+first symptom is an operation the Contract advertises failing against a column that moved.
+
+Currency is therefore a **process** guarantee, not a runtime one: the generate step reads the schema
+and the client in one instant, so run it in the same build that runs `prisma generate`, and deploy the
+artifact with the schema and client it came from. Wire the generate step into CI, not into the
+runtime.
+
+---
+
+## 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
+transaction capability.
+
+Across the pilot's representative 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`
+
+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.
+
+**Use `delete.count`** to delete a filtered set. 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.
+
+Observed consequences on the two pilot engines, all of them read from generated types rather than
+tabulated:
+
+| 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` |
+| 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 |
+
+**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.
+
+### `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.
+
+A to-one projection on `update.many` works. A projection reaching a **to-many** relation or `$count`
+on these two variants answers `A3001` — sanitized, with nothing written. That is a 500 for an
+argument the Contract advertised, and it is a known, open gap rather than a surprise: the Contract has
+no per-variant projection slot in which to say "available on `update.one`, not on `update.many`".
+
+**Today:** keep `update.many`/`create.many` projections to scalars and to-one relations; read to-many
+relations with a separate `find`. **Phase 9** adds the per-variant projection capability so the
+Contract stops advertising a projection it cannot serve, and the refusal becomes a caller error
+(`A2004`) instead of a server failure. The adapter deliberately does **not** paper over it with a
+follow-up read: that would add a statement and a new consistency window to a bulk write.
+
+---
+
+## `update.first` and `delete.first` are framework-manufactured conveniences
+
+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.
+
+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:
+
+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.
+
+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.
+
+### 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)` seam 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
+`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.
+
+### 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
+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
+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.
+
+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.
+
+---
+
+## Errors
+
+### A caller discriminates by **code**, never by 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.
+
+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.
+
+### The three conflict codes
+
+Three situations used to collapse into one `409 A2008`. They no longer do.
+
+| 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. |
+
+`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.
+
+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 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 are not separable at this seam, so one outcome is the honest answer.
+
+### 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.
+
+### `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.
+
+### 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 — 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.
+
+### `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.
+
+What is separable **structurally** (measured on both pilot engines, 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 }` |
+| 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.
+
+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.
+
+### 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.
+
+### 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.
+
+---
+
+## 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:
+
+- 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 the seam 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
+one, so its two statements roll back *with* the plan rather than 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
+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.
+
+**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.
+
+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.
+
+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
+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 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:
+
+```ts
+discovery.referentialActions;
+// {
+//   Shop:  { owningEdges: [] },
+//   Item:  { owningEdges: [{ field: "shop", target: "Shop",
+//                           cardinality: "one",
+//                           onDelete: "cascade", onUpdate: "cascade" }] },
+//   Clerk: { owningEdges: [{ field: "shop", target: "Shop",
+//                           cardinality: "one",
+//                           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), measured on both
+pilot engines. 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 (the architect's, 2026-10-04, 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 — measured 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, by the architect's choice: the adapter states
+what the schema says rather than collapsing it into what core currently reads.
+
+`onUpdate` is not carried: core plans the **delete** closure only.
+
+**Planning-phase refusal is wired (Phase 9 S10).** 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. 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
+`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.
+
+---
+
+## No raw SQL
+
+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.
+
+This is an architectural rule with no exception attached. Everything the adapter does, it does through
+Prisma's typed delegate surface.
+
+---
+
+## Also worth knowing
+
+- **`$count` on a paginated relation reports the pre-pagination count.** Measured 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.
+
+## Not covered by the pilot
+
+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
+  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.
+
+## 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`.

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

@@ -0,0 +1,26 @@
+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 {
+    constructor(reason: string);
+}
+export type PrismaDiscoveryArtifactLoad = {
+    readonly artifact: unknown;
+    /** The `version` of the `@prisma/client` actually installed beside the caller. */
+    readonly installedPrismaVersion: string;
+};
+/**
+ * The identity of a discovered model: one canonicalization, one digest — over
+ * the model and **nothing else**. The artifact's `translation` half is Prisma
+ * addressing, and hashing it would put a DB-side rename into the Contract
+ * identity; its `referentialActions` half is what a delete does below the ORM
+ * entrypoint, and hashing it would put a foreign-key action into the Contract
+ * 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 (C-846), then `modelHash`.
+ */
+export declare function loadDiscoveryArtifact(load: PrismaDiscoveryArtifactLoad): Promise<PrismaAdapterModel>;