@aventara/prisma7-adapter 0.1.0-pilot.3 → 0.1.0-pilot.4

package/README.md

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

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

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

package/dist/discovery/artifact.loader.js

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

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

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

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

@@ -1,38 +1,5 @@
 import type { RelationFieldCapabilities, ScalarFieldCapabilities, ScalarFilterOperator } from "@aventara/core";
 import type { PrismaRelationSurface, PrismaScalarSurface } from "./capability-surface.interface.js";
-/**
- * This module accepts `surface` alone, and that is deliberate: dictionary
- * invariant 6 says a capability is read from the client's own types and never
- * tabulated from a provider row, and the strongest available mechanism for that is
- * to make the provider **unrepresentable** rather than merely unread. A
- * `PrismaProviderProfile` in this input is a `provider` member one keystroke from
- * a branch; with no such member, `if (provider === …)` is a compile error, and the
- * three per-engine differences this pass exists to prove — `mode`, `JsonFilter`'s
- * ordering operators, and the `path` / `in` / `notIn` operand shapes — have to
- * come from the surface because nothing else is in scope.
- *
- * `mapping` went with them because nothing here reads an Aventara scalar identity
- * to answer a capability question.
- *
- * The answer is read off the recorded operand shape, which is already on the
- * surface; the Aventara scalar identity would have been a second, weaker source
- * for the same fact. `mapping` stays out.
- *
- * # Order is canonical, not incidental
- *
- * Every list is emitted in **core's own union declaration order**, held below as a
- * closed ordered array.
- *
- * # Absent and empty are different answers
- *
- * `create: []` / `update: []` mean **writable with no directive** — plain
- * assignment, which is what `set` alone is. An absent `create` / `update` means
- * **not writable**, and core enforces exactly that: `validateScalarMutation`
- * answers `V1006` *"is not writable during <stage>"* when the member is
- * `undefined` **[CORE, operations/operation-validator-core.ts]**. So the two must
- * not be conflated, and the surface's `null` (the client exposes no entry for this
- * column at this stage) is the only thing that produces the absent form.
- */
 /** A Prisma spelling that no dictionary table recognises: a build stop, never a drop. */
 export declare class PrismaCapabilityDerivationError extends Error {
     readonly name = "PrismaCapabilityDerivationError";
@@ -40,23 +7,11 @@ export declare class PrismaCapabilityDerivationError extends Error {
 export type ScalarCapabilityInput = {
     readonly surface: PrismaScalarSurface;
 };
-/**
- * A relation's capabilities are answered for the field, not for an operation.
- *
- * The `operation: "create.one" | "create.many"` parameter this input used to carry
- * is **gone**. The scope-qualified members hold both answers at once, so there is
- * nothing left to pick and no caller left to pick it.
- */
+/** A relation's capabilities are answered for the field, not for an operation. */
 export type RelationCapabilityInput = {
     readonly surface: PrismaRelationSurface;
 };
 export declare function deriveScalarCapabilities(input: ScalarCapabilityInput): ScalarFieldCapabilities;
-/**
- * The Prisma operand for each ADVERTISED operator, keyed by the Aventara name.
- *
- * A deriver that answered operator NAMES alone would report the two engines
- * identical where they are not, so the shape is carried beside the capability
- * rather than discarded.
- */
+/** The Prisma operand for each ADVERTISED operator, keyed by the Aventara name. */
 export declare function deriveScalarFilterOperands(input: ScalarCapabilityInput): Readonly<Partial<Record<ScalarFilterOperator, string>>>;
 export declare function deriveRelationCapabilities(input: RelationCapabilityInput): RelationFieldCapabilities;