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

package/README.md

@@ -126,35 +126,48 @@ project's `devDependencies` — if you are generating a Prisma client at all, yo
 
 The step reads two sources in the same instant — the `schema.prisma` text and the generated client's
 own public types — and cross-checks them against each other. What it emits is a TypeScript module
-exporting one `discovery` value with six members: the canonical `AdapterModel` (scalars, enums,
+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
-`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
+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`
+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.
+
+`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.
 
 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:
+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.
-
-### 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.
+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
+   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.
+   ```
+
+   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.
 
 ---
 

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

@@ -1,7 +1,11 @@
 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);
+    /**
+     * `instruction` replaces the general regeneration sentence where the reason
+     * reads as the first half of one sentence with it.
+     */
+    constructor(reason: string, instruction?: string);
 }
 export type PrismaDiscoveryArtifactLoad = {
     readonly artifact: unknown;
@@ -21,6 +25,6 @@ export declare function computeModelHash(model: PrismaAdapterModel): Promise<str
  * 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`.
+ * the `prismaVersion` major fence, then `modelHash`.
  */
 export declare function loadDiscoveryArtifact(load: PrismaDiscoveryArtifactLoad): Promise<PrismaAdapterModel>;

package/dist/discovery/artifact.loader.js

@@ -1,37 +1,12 @@
 import { canonicalizeJson } from "@aventara/core";
-/**
- * T-3.2 — `discover()`'s whole runtime half.
- *
- * This module builds no TypeScript program, parses no PSL and calls no Prisma
- * tooling, and that is guaranteed by construction rather than by assertion:
- * its transitive import graph is this file, `discovery-artifact.interface.ts`
- * and `@aventara/core`. Nothing under `generate/` is reachable from here, and
- * neither is `typescript`, `prisma`, `@prisma/*`, `node:child_process` or
- * `node:fs`. `artifact.loader.spec.ts` walks that graph from source and fails
- * if a specifier appears that should not.
- *
- * The loader reads no file at all: the artifact arrives as a value, and hashing
- * uses `globalThis.crypto.subtle`, so it needs no import either. It checks the
- * two facts the runtime can still get wrong — that the artifact matches itself
- * (`modelHash`) and that the installed `@prisma/client` major is the one it was
- * generated against (C-846) — and nothing else. The model is derived at
- * generate time from the schema and the generated client read in the same
- * instant and cross-checked there, so the runtime never sees the schema and
- * never asks after it.
- */
-/** The `sha256:<hex>` convention core already uses for Contract identity. */
 const HASH_PREFIX = "sha256:";
-/**
- * A stale or corrupt artifact is answered the way cross-phase invariant 15
- * answers a Contract-hash mismatch: fail hard, and say what to run.
- */
-const REGENERATION_INSTRUCTION = "Regenerate the discovery artifact with the adapter's generate step " +
-    "(`aventara-prisma7-generate`) and redeploy it " +
+const REGENERATION_INSTRUCTION = "Regenerate the discovery artifact — `npm run aventara:prepare` in a project " +
+    "set up by `aventara`, or the adapter's generate step " +
+    "(`aventara-prisma7-generate`) — and redeploy it " +
     "alongside the schema and client it was generated from.";
-/** Every artifact failure is this class, and every one of them says how to fix it. */
 export class PrismaDiscoveryArtifactError extends Error {
-    constructor(reason) {
-        super(`${reason} ${REGENERATION_INSTRUCTION}`);
+    constructor(reason, instruction = REGENERATION_INSTRUCTION) {
+        super(`${reason} ${instruction}`);
         this.name = "PrismaDiscoveryArtifactError";
     }
 }
@@ -43,14 +18,6 @@ async function sha256(text) {
     const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
     return `${HASH_PREFIX}${hex(digest)}`;
 }
-/**
- * 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 async function computeModelHash(model) {
     return sha256(canonicalizeJson(model));
 }
@@ -61,7 +28,6 @@ function majorOf(version) {
     const major = /^(\d+)\./.exec(version)?.[1];
     return major;
 }
-/** Shape validation, before any hash is computed over a value that may not have one. */
 function assertArtifactShape(artifact) {
     if (!isRecord(artifact)) {
         throw new PrismaDiscoveryArtifactError("The discovery artifact is not a JSON object.");
@@ -74,17 +40,12 @@ function assertArtifactShape(artifact) {
     if (!isRecord(artifact.model)) {
         throw new PrismaDiscoveryArtifactError("The discovery artifact's `model` is not a JSON object.");
     }
-    // The two beside-the-model halves are checked as members, not as content: this
-    // function asserts the artifact IS a `PrismaDiscoveryArtifact`, and an
-    // assertion that skipped a declared member would be a lie its consumer pays
-    // for. Their entries are not walked here — the runtime half hashes and returns
-    // the model, the executor reads its own addressing keys, and a cascade planner
-    // reads its own edges.
-    //
-    // `referentialActions` is checked for the same reason as `translation` and with
-    // the same consequence: an artifact emitted before the key existed is refused
-    // here and regenerated, rather than reaching a planner as `undefined`.
-    for (const key of ["translation", "referentialActions"]) {
+    for (const key of [
+        "translation",
+        "referentialActions",
+        "client",
+        "createRequirements",
+    ]) {
         if (!isRecord(artifact[key])) {
             throw new PrismaDiscoveryArtifactError(`The discovery artifact's \`${key}\` is not a JSON object.`);
         }
@@ -99,12 +60,6 @@ function assertArtifactShape(artifact) {
         throw new PrismaDiscoveryArtifactError("The discovery artifact's `model.transactions` is not a transaction capability.");
     }
 }
-/**
- * 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 async function loadDiscoveryArtifact(load) {
     const { artifact, installedPrismaVersion } = load;
     assertArtifactShape(artifact);
@@ -114,7 +69,7 @@ export async function loadDiscoveryArtifact(load) {
         throw new PrismaDiscoveryArtifactError(`A Prisma version is not a major.minor.patch version: the artifact declares \`${artifact.prismaVersion}\` and the installed client reports \`${installedPrismaVersion}\`.`);
     }
     if (artifactMajor !== installedMajor) {
-        throw new PrismaDiscoveryArtifactError(`The discovery artifact was generated against Prisma major ${artifactMajor}, and the installed client is major ${installedMajor}. The P-code surface and the generated-client grammar are version-bound (C-846).`);
+        throw new PrismaDiscoveryArtifactError(`The discovery artifact was generated against Prisma major ${artifactMajor}, and the installed client is major ${installedMajor}. The P-code surface and the generated-client grammar are version-bound.`);
     }
     const modelHash = await computeModelHash(artifact.model);
     if (modelHash !== artifact.modelHash) {

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

@@ -1,17 +1,14 @@
 /**
- * T-3, source **TYPE** — the output of the reader over the generated client's
- * 🟢 public types.
- *
  * 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 (T-3).
+ * 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 (T-3.1 invariant 3). */
+    /** 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[]>>;
@@ -33,11 +30,10 @@ export type PrismaScalarSurface = {
     /** `<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 (D-802): `path` is `string[]` on PostgreSQL and `string`
-     * on SQLite, and `in`/`notIn` admit `List<Kind>FieldRefInput` on PostgreSQL
-     * only. Read, not tabulated — T-3.1 invariant 6.
+     * 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>>;
     /**
@@ -103,14 +99,18 @@ export type PrismaRelationSurface = {
      * `<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.
      *
-     * A SEPARATE fact from {@link updateMutations}, and the separation is the C-855
-     * invariant: the create-stage input carries `create`, `connectOrCreate`,
-     * `createMany` (to-many only) and `connect` and nothing else, where the
-     * update-stage input carries eight more. 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.
+     * 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
+     * relation edges — writes this edge without a `?`: a create through the checked
+     * input cannot leave it out. Read as presence of the question mark, the way
+     * {@link PrismaScalarSurface.createOptional} is; `false` where the input has no
+     * 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[];
     /**
@@ -137,24 +137,18 @@ export type PrismaRelationSurface = {
      * # 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.
-     *
-     * Deriving FK ownership here instead would be a tabulated provider-dependent
-     * fact — the shape §18.4 forbids and D-802 exists to prevent — and it would be
-     * wrong the first time Prisma changes which relations it admits into the
-     * projection, while a presence read simply tells the truth again.
+     * 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.
+     * 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`. */
@@ -170,13 +164,8 @@ export type PrismaRelationSurface = {
      */
     readonly bulkReducers: boolean;
     /**
-     * Whether `<M>CreateManyInput` — the data argument of the bulk create — exposes
-     * an entry for this edge.
-     *
-     * The write-side mirror of {@link bulkSelect}, and read the same way: C-818's
-     * rule (*no nested `create`/`connect` inside a top-level `createMany()` or
-     * `createManyAndReturn()`*) is a **consequence** of the bulk input carrying no
-     * relation member, never a row this adapter keeps.
+     * Whether `<M>CreateManyInput` — the data argument of the bulk create — exposes an
+     * entry for this edge.
      */
     readonly bulkCreatable: boolean;
     /**

package/dist/discovery/capability-surface.interface.js

@@ -1,13 +1 @@
-/**
- * T-3, source **TYPE** — the output of the reader over the generated client's
- * 🟢 public types.
- *
- * 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 (T-3).
- *
- * 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 {};

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

@@ -1,11 +1,6 @@
 import type { RelationFieldCapabilities, ScalarFieldCapabilities, ScalarFilterOperator } from "@aventara/core";
 import type { PrismaRelationSurface, PrismaScalarSurface } from "./capability-surface.interface.js";
 /**
- * T-6 — field capabilities, derived from the generated client's own types.
- *
- * # The input is narrower than T-6 writes it, and the narrowing IS the invariant
- *
- * T-6 spells `ScalarCapabilityInput` as `{ field, surface, mapping, profile }`.
  * 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
@@ -13,27 +8,20 @@ import type { PrismaRelationSurface, PrismaScalarSurface } from "./capability-su
  * `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.
+ * ordering operators, and the `path` / `in` / `notIn` operand shapes — have to
+ * come from the surface because nothing else is in scope.
  *
- * Dropping `field` has the same effect on C-812: a lifecycle trait cannot grant a
- * capability if no lifecycle trait can be passed. `mapping` went with them because
- * nothing here reads an Aventara scalar identity to answer a capability question.
+ * `mapping` went with them because nothing here reads an Aventara scalar identity
+ * to answer a capability question.
  *
- * **This is a deviation from T-6 and is reported as one.** It predicted that the
- * `path` question — omit, or translate, where the operand is a JSONPath string —
- * would need `mapping` back. **Task 7 settled it and did not:** see
- * {@link translatable}. 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.
+ * 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. Prisma's declaration order is an input, not a semantic
- * fact, and C-843 wants two generate runs byte-identical; ordering by the Aventara
- * union makes the output independent of how a generator happens to write a member
- * list, while keeping the array reviewable against `contracts/capability.ts`.
+ * closed ordered array.
  *
  * # Absent and empty are different answers
  *
@@ -49,12 +37,6 @@ import type { PrismaRelationSurface, PrismaScalarSurface } from "./capability-su
 export declare class PrismaCapabilityDerivationError extends Error {
     readonly name = "PrismaCapabilityDerivationError";
 }
-/**
- * T-6's `ScalarCapabilityInput`, narrowed — see this module's header.
- *
- * An object rather than a bare parameter because T-6 names an input type and
- * because a later pass may legitimately add `mapping` back.
- */
 export type ScalarCapabilityInput = {
     readonly surface: PrismaScalarSurface;
 };
@@ -62,12 +44,8 @@ export type ScalarCapabilityInput = {
  * 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**. It existed because C-818's answer differs between the singular and
- * the bulk create and the capability shape had nowhere to put the difference, so
- * composition had to pick one variant's answer and the other was unrepresentable —
- * `model.discoverer.ts` recorded that as an open conflict. The scope-qualified
- * members hold both answers at once, so there is nothing left to pick and no caller
- * left to pick it.
+ * 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.
  */
 export type RelationCapabilityInput = {
     readonly surface: PrismaRelationSurface;
@@ -76,17 +54,9 @@ export declare function deriveScalarCapabilities(input: ScalarCapabilityInput):
 /**
  * The Prisma operand for each ADVERTISED operator, keyed by the Aventara name.
  *
- * T-6's three signatures return core types unchanged, and `ScalarFieldCapabilities`
- * has nowhere to put an operand shape — yet the shape is exactly where two engines
- * differ on keys they both carry (`JsonFilter.path` is `string[]` on one and
- * `string` on the other; `in`/`notIn` admit `List<Kind>FieldRefInput` on one only).
  * 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.
- *
- * Keyed by the Aventara operator so Task 7 reads a shape without re-running the
- * rename — and so a provider branch has nothing to be for (§Open question,
- * "How the `path` filter operator is emitted per provider").
  */
 export declare function deriveScalarFilterOperands(input: ScalarCapabilityInput): Readonly<Partial<Record<ScalarFilterOperator, string>>>;
 export declare function deriveRelationCapabilities(input: RelationCapabilityInput): RelationFieldCapabilities;