@aventara/prisma7-adapter 0.1.0-pilot.0 → 0.1.0-pilot.2

package/dist/discovery/scalar.mapper.d.ts

@@ -2,65 +2,42 @@ import type { PrismaResourceSurface } from "./capability-surface.interface.js";
 import type { PrismaSchemaField } from "./schema-facts.interface.js";
 import { type PrismaDiscoveryDiagnostic, type PrismaScalarMapping } from "./vocabulary.dictionary.js";
 /**
- * T-5 / C-809 — one Prisma column, answered in Aventara's words.
- *
  * # Four answers, no fifth, and no guess
  *
  * The outcome is a closed union because every way this can end is a decision
  * somebody has to be able to read back:
  *
  * - `scalar` — the Prisma type name had a row in the dictionary's total table.
- * - `enum` — the written type is an enum `enums.ts` confirms. It is **not** a
- *   third field kind: C-810 has exactly two, and an enum-backed column is a
- *   ScalarField. `enum.mapper.ts`'s `projectEnumBackedColumn` is where that
- *   becomes a field type ref.
- * - `excluded` — PSL declares the column and the 🟢 types do not expose it. This
- *   is the scalar half of C-808's existence gate, and the reason travels with it:
- *   an exclusion nobody can explain is indistinguishable from a bug.
+ * - `enum` — the written type is an enum `enums.ts` confirms. `enum.mapper.ts`'s
+ *   `projectEnumBackedColumn` is where that becomes a field type ref.
+ * - `excluded` — PSL declares the column and the 🟢 types do not expose it.
  * - `unmapped` — a type name in neither table. A **diagnostic**, never a silent
- *   drop and never a nearest-neighbour guess (C-809).
+ *   drop and never a nearest-neighbour guess.
  *
  * # Why `format` is emitted here at all — and why so little of it is
  *
- * T-3.1's table says `format?` is `CFG`, "policy, not discovery". Spec §6.1 says
- * UUID "is a string scalar plus passive format metadata **when the adapter can
- * prove the format**"; §18.3's discovery mapping says "scalar type → stable
- * framework scalar + optional format"; C-809 says "native types normalize to the
- * nearest stable scalar plus optional format"; and `AdapterScalarField.format?`
- * exists **[CORE]**, which would be a member with no producer if discovery never
- * emitted one. Three specification statements and a type beat one plan line, so
- * discovery does emit `format` — and T-3.1's row is corrected to `PSL` + `CFG`
- * in `vocabulary.dictionary.ts`.
- *
  * What the plan row was *right* about is that most of what looks like a format is
- * policy. `format` is **enforced**: `normalizeScalarFieldValue` turns
- * `format: "uuid"` into a `V1003` rejection of request input **[CORE,
+ * policy. `format` is **enforced**: `normalizeScalarFieldValue` turns `format:
+ * "uuid"` into a `V1003` rejection of request input **[CORE,
  * `runtime/scalar-runtime.ts`]**. So the bar for discovering one is not "the
  * schema suggests it" but "the column itself rejects what Aventara would then
- * reject". That admits `@db.Uuid` — PostgreSQL's `uuid` column refuses
- * `'not-a-uuid'` where `text` accepts it **[RUN8 — 2026-09-28, postgres:18]** —
- * and it excludes `@default(uuid())`, which T-5 also named: on a `text` column
- * only *generated* values are UUIDs and a client may legally write any string, so
- * emitting the format there would make Aventara refuse writes the database
- * accepts. That intent belongs in `FrameworkScalarFieldConfig.format` **[CORE]**,
+ * reject". That intent belongs in `FrameworkScalarFieldConfig.format` **[CORE]**,
  * which the Contract compiler already layers over the adapter's value.
  *
- * It follows that no `format` is emitted for either Phase 8 schema, whose only
- * UUID column is `Author.id String @default(uuid())` with no native type. That is
- * the correct answer, not a gap.
+ * That is the correct answer, not a gap.
  *
  * # Nothing here branches on a provider
  *
- * `@db.Uuid` is unwritable on SQLite, so the SQLite schema simply never carries
- * it and the same table gives the same right answer on both engines without a
- * provider arm (T-3.1 invariant 6).
+ * `@db.Uuid` is unwritable on SQLite, so the SQLite schema simply never carries it
+ * and the same table gives the same right answer on both engines without a
+ * provider arm.
  */
 export type ScalarMappingInput = {
     /** The PSL model name, carried so a diagnostic can name the column in full. */
     readonly resource: string;
     /** PSL — what the column IS. */
     readonly field: PrismaSchemaField;
-    /** TYPE — what this client exposes. The existence gate (C-808). */
+    /** TYPE — what this client exposes. The existence gate. */
     readonly surface: PrismaResourceSurface;
     /** TYPE — `enums.ts`, which is what makes an enum name an enum name. */
     readonly enums: Readonly<Record<string, readonly string[]>>;

package/dist/discovery/scalar.mapper.js

@@ -12,7 +12,6 @@ export function mapPrismaScalarField(input) {
         };
     }
     if (Object.hasOwn(enums, field.type)) {
-        // C-810: this is a ScalarField whose type ref takes the `enum` arm.
         return { outcome: "enum", enum: field.type };
     }
     const mapping = PRISMA_SCALAR_TABLE[field.type];
@@ -25,8 +24,6 @@ export function mapPrismaScalarField(input) {
             },
         };
     }
-    // Matched by exact written spelling, never parsed: `@db.Decimal(10, 2)`
-    // matches no key and therefore proves no format, with no argument list split.
     const proven = field.native
         .map((native) => PRISMA_NATIVE_FORMATS[native])
         .find((format) => format !== undefined);
@@ -35,11 +32,6 @@ export function mapPrismaScalarField(input) {
         mapping: proven === undefined ? mapping : { ...mapping, format: proven },
     };
 }
-/**
- * The gate's message is built from evidence, never from an assumption: `@ignore`
- * is reported only where PSL actually wrote one, because "present in schema,
- * absent from client" with a made-up cause is worse than the bare fact.
- */
 function explainAbsence(field, surface) {
     if (field.ignored) {
         return "it carries `@ignore`";

package/dist/discovery/schema-facts.interface.d.ts

@@ -1,17 +1,15 @@
 /**
- * T-3, source **PSL** — the output of the bounded `schema.prisma` reader.
- *
  * Nothing here is imported from `@prisma/client`: these are this adapter's own
  * facts over schema text, which is what keeps discovery a pure function of plain
- * data and unit-testable without a generated client (T-3).
+ * data and unit-testable without a generated client.
  *
- * Read `schema.reader.ts`'s header for the boundary these facts are drawn on:
- * the reader **locates** tokens and never **evaluates** them.
+ * Read `schema.reader.ts`'s header for the boundary these facts are drawn on: the
+ * reader **locates** tokens and never **evaluates** them.
  */
 import type { PrismaReferentialAction } from "./discovery-artifact.interface.js";
 /** Where a fact — or an unhandled construct — was found. One-based lines, as `prisma validate` reports them. */
 export type PrismaSchemaSite = {
-    /** The schema file as the caller named it; a folder read names each member file (D-802, Prisma 7 folders). */
+    /** The schema file as the caller named it; a folder read names each member file. */
     readonly file: string;
     readonly line: number;
 };
@@ -24,13 +22,12 @@ export type PrismaSchemaSite = {
  * are recognised and deliberately discarded (bucket 2, the reader's explicit
  * `DISCARDED_ATTRIBUTES` list), because their values appear nowhere on the 🟢
  * generated surface. Recording them would fail the generate step on any schema
- * that maps a column name. `name:` is **not** discarded — see
- * {@link PrismaSchemaBlockIdentifier}.
+ * that maps a column name. `name:` is **not** discarded — see {@link
+ * PrismaSchemaBlockIdentifier}.
  *
  * Bucket 3 is recorded rather than dropped because silently dropping an
- * unrecognised attribute is how a grammar change becomes wrong output instead of
- * a build stop. A non-empty `PrismaSchemaFacts.unhandled` FAILS the generate step
- * (T-3.1 invariant 5).
+ * unrecognised attribute is how a grammar change becomes wrong output instead of a
+ * build stop. A non-empty `PrismaSchemaFacts.unhandled` FAILS the generate step.
  */
 export type PrismaSchemaUnknown = {
     readonly kind: PrismaSchemaUnknownKind;
@@ -56,15 +53,21 @@ export type PrismaSchemaUnknownKind =
 export type PrismaSchemaFacts = {
     readonly enums: readonly PrismaSchemaEnum[];
     readonly models: readonly PrismaSchemaModel[];
-    /** Attributes and blocks the reader does not recognise at all (a `type`/`view` block, an
-     *  unrecognised argument, any spelling added after 7.10.0). `@map`/`@@map`/`@@index` are
-     *  recognised and deliberately discarded instead, so they never appear here.
-     *  Never silently dropped: a non-empty list FAILS the generate step (T-3.1 invariant 5). */
+    /**
+     * Attributes and blocks the reader does not recognise at all (a `type`/`view`
+     * block, an unrecognised argument, any spelling added after 7.10.0).
+     * `@map`/`@@map`/`@@index` are recognised and deliberately discarded instead, so
+     * they never appear here. Never silently dropped: a non-empty list FAILS the
+     * generate step.
+     */
     readonly unhandled: readonly PrismaSchemaUnknown[];
 };
 export type PrismaSchemaEnum = {
     readonly name: string;
-    /** Declaration order is semantic (§19.2); a member-level `@map` is discarded (bucket 2), not recorded. */
+    /**
+     * Declaration order is semantic; a member-level `@map` is discarded (bucket 2),
+     * not recorded.
+     */
     readonly values: readonly string[];
     readonly site: PrismaSchemaSite;
 };
@@ -117,7 +120,7 @@ export type PrismaSchemaField = {
     readonly type: string;
     /** `[]` */
     readonly list: boolean;
-    /** `?` — the ONLY source of nullability (T-3.1 invariant 4). */
+    /** `?` — the ONLY source of nullability. */
     readonly optional: boolean;
     /** `@id` */
     readonly id: boolean;
@@ -125,16 +128,14 @@ export type PrismaSchemaField = {
     readonly unique: boolean;
     /** `@updatedAt` */
     readonly updatedAt: boolean;
-    /** `@default(…)`'s argument as RAW TEXT — matched against a table, never parsed (T-3.1 invariant 5). */
+    /** `@default(…)`'s argument as RAW TEXT — matched against a table, never parsed. */
     readonly defaultArgument: string | null;
     readonly relation: PrismaSchemaRelation | null;
     /**
-     * `@db.*` as written, e.g. `@db.Decimal(10, 2)`. Kept verbatim and never
-     * parsed. A native type is the **only** proof discovery accepts for
-     * `format` (C-809, spec §6.1 "when the adapter can prove the format");
-     * configuration may then override it, since `AdapterScalarField.format`
-     * and `FrameworkScalarFieldConfig.format` are separate members the
-     * compiler layers.
+     * `@db.*` as written, e.g. `@db.Decimal(10, 2)`. Kept verbatim and never parsed. A
+     * native type is the **only** proof discovery accepts for `format`; configuration
+     * may then override it, since `AdapterScalarField.format` and
+     * `FrameworkScalarFieldConfig.format` are separate members the compiler layers.
      */
     readonly native: readonly string[];
     /** `@ignore` */
@@ -144,7 +145,7 @@ export type PrismaSchemaField = {
 export type PrismaSchemaRelation = {
     /** `@relation("Name")` — the ONLY evidence pairing a back-reference with its forward reference. */
     readonly name: string | null;
-    /** The FK scalar(s); read, used, then discarded (C-813). */
+    /** The FK scalar(s); read, used, then discarded. */
     readonly fields: readonly string[] | null;
     readonly references: readonly string[] | null;
     /**

package/dist/discovery/schema-facts.interface.js

@@ -1,11 +1 @@
-/**
- * T-3, source **PSL** — the output of the bounded `schema.prisma` reader.
- *
- * Nothing here is imported from `@prisma/client`: these are this adapter's own
- * facts over schema text, which is what keeps discovery a pure function of plain
- * data and unit-testable without a generated client (T-3).
- *
- * Read `schema.reader.ts`'s header for the boundary these facts are drawn on:
- * the reader **locates** tokens and never **evaluates** them.
- */
 export {};

package/dist/discovery/schema.reader.d.ts

@@ -1,39 +1,34 @@
 import type { PrismaSchemaFacts } from "./schema-facts.interface.js";
 /**
- * T-3, source **PSL** — the bounded `schema.prisma` reader.
- *
  * # The boundary, and why this file is a reader and not a parser
  *
  * It **locates** tokens and never **evaluates** them.
  *
  * PSL's model body is line-oriented by the language's own rule, not by this
- * reader's assumption. Re-measured against `prisma` 7.10.0 on 2026-09-28, all
- * four constructs that would let a declaration legally span lines are
- * **rejected** with `Error code: P1012` — so the classic regex-parser failure
- * cannot occur:
+ * reader's assumption. Re-measured against `prisma` 7.10.0 on 2026-09-28, all four
+ * constructs that would let a declaration legally span lines are **rejected** with
+ * `Error code: P1012` — so the classic regex-parser failure cannot occur:
  *
  * 1. a wrapped `@@unique([…])` — the error COUNT is layout-dependent, the
  *    rejection is not. A two-line wrap (`@@unique([x,` / `y])`) gives 2 errors,
  *    both `error: Error validating: This line is not a valid field or attribute
  *    definition.`; a four-line wrap gives 4 — three of that sentence plus one
- *    `Error validating model "A": This field declaration is invalid. It is
- *    either missing a name or a type.`
- * 2. a wrapped field attribute (`@default(uuid())` on the line below `id String @id`)
- *    — 1 error, `This line is not a valid field or attribute definition.`
+ *    `Error validating model "A": This field declaration is invalid. It is either
+ *    missing a name or a type.`
+ * 2. a wrapped field attribute (`@default(uuid())` on the line below `id String
+ *    @id`) — 1 error, `This line is not a valid field or attribute definition.`
  * 3. two block attributes on one line (`@@unique([x]) @@index([y])`) — 1 error,
  *    `This line is not a valid field or attribute definition.`
  * 4. a split field declaration (`id` then `String @id`) — 2 errors, **both**
  *    `Error validating model "A": This field declaration is invalid. It is either
  *    missing a name or a type.`
  *
- * **Correction to the plan's wording (2026-09-28, re-measured, not inherited).**
- * The plan and T-3 previously said all four are rejected *with* `P1012 … This
- * line is not a valid field or attribute definition`. All four are indeed
- * `P1012`, **and the line-oriented conclusion holds unchanged** — the design did
- * not move. But case 4 never emits that sentence at all (it emits *"This field
- * declaration is invalid. It is either missing a name or a type."* twice), and
- * case 1 emits a second, different sentence besides it. The evidence supports the
- * rule; the single-sentence attribution does not, and the plan now says so.
+ * All four are indeed `P1012`, **and the line-oriented conclusion holds
+ * unchanged** — the design did not move. But case 4 never emits that sentence at
+ * all (it emits *"This field declaration is invalid. It is either missing a name
+ * or a type."* twice), and case 1 emits a second, different sentence besides it.
+ * The evidence supports the rule; the single-sentence attribution does not, and
+ * the plan now says so.
  *
  * Re-running it: `prisma` lives at `packages/prisma7-adapter/node_modules/.bin/
  * prisma`, not the worktree root. Invoked from the root it silently produces no
@@ -47,9 +42,9 @@ import type { PrismaSchemaFacts } from "./schema-facts.interface.js";
  * needs a different decision. Hence:
  *
  * - `@default`'s argument is kept as **raw text** and matched against a table
- *   downstream, never parsed (T-3.1 invariant 5).
+ *   downstream, never parsed.
  * - `@db.*` is kept **as written** and never parsed. It is the only proof
- *   discovery accepts for `format` (C-809); configuration overrides it later.
+ *   discovery accepts for `format`; configuration overrides it later.
  * - a field's `type` stays the written token — `Grade` is not resolved to the
  *   enum, which is also why a schema **folder** needs no linker (below).
  * - an attribute is classified three ways, not two (below), and only the third
@@ -60,16 +55,16 @@ import type { PrismaSchemaFacts } from "./schema-facts.interface.js";
  *
  * # The three-way classification (corrected 2026-09-28)
  *
- * 1. **recognised and modelled** — `FIELD_ATTRIBUTES`, `BLOCK_ATTRIBUTES`,
- *    `@db.*` and `RELATION_ARGUMENTS`.
+ * 1. **recognised and modelled** — `FIELD_ATTRIBUTES`, `BLOCK_ATTRIBUTES`, `@db.*`
+ *    and `RELATION_ARGUMENTS`.
  * 2. **recognised and deliberately discarded**, via the explicit
  *    `DISCARDED_ATTRIBUTES` / `DISCARDED_BLOCK_ATTRIBUTE_ARGUMENTS` lists —
- *    `@map`, `@@map`, `@@index`, and `@@id`/`@@unique`'s `map:` argument. The
- *    rule is one line long: an argument is discardable **iff its value appears
- *    nowhere on the 🟢 surface**. The list being explicit is the point: the
- *    discard is a decision a reader can see and audit, not an omission. That
- *    rule is also what took `name:` back OFF this list (2026-09-29): its value
- *    is a `WhereUniqueInput` key and an `AtLeast` key, so it is carried on
+ *    `@map`, `@@map`, `@@index`, and `@@id`/`@@unique`'s `map:` argument. The rule
+ *    is one line long: an argument is discardable **iff its value appears nowhere
+ *    on the 🟢 surface**. The list being explicit is the point: the discard is a
+ *    decision a reader can see and audit, not an omission. That rule is also what
+ *    took `name:` back OFF this list (2026-09-29): its value is a
+ *    `WhereUniqueInput` key and an `AtLeast` key, so it is carried on
  *    `PrismaSchemaBlockIdentifier`.
  * 3. **unrecognised** — on neither list, therefore `unhandled`, therefore a build
  *    stop.
@@ -79,51 +74,45 @@ import type { PrismaSchemaFacts } from "./schema-facts.interface.js";
  * Bucket 2's rule reads "discardable iff the value appears nowhere on the 🟢
  * surface", and `@relation(onDelete: Cascade)` passes that test: measured at
  * 7.10.0, `Cascade` reaches nothing but the 🛑 `internal/class.ts` inline-schema
- * blob. It is still **not** discardable, and this is the first construct where
- * the test and the rule it stands for come apart.
+ * blob. It is still **not** discardable, and this is the first construct where the
+ * test and the rule it stands for come apart.
  *
  * The rule's *reason* was that such attributes configure the database below the
  * ORM entrypoint and therefore carry no framework meaning. A referential action
  * fails that reason while passing the test: it changes what a delete **does** —
- * rows disappear that the caller never named — which is exactly what a
- * transaction planner must reason about before it agrees to run a plan. So
- * invisibility on the generated types is *evidence* for "no framework meaning",
- * and evidence can be outweighed; it was never the meaning itself. `@map` and
- * `@@index` remain discarded because they fail the test AND the reason.
- * `@relation`'s `map:` joins them: a foreign-key constraint name is genuinely
- * DB-side, and it was bucket 3 until now, which made `@relation(map: …)` — valid
- * PSL — a build stop on its own.
- *
- * Actions are read on both arguments and carried **resolved**: an absent
- * argument is not a third state, it is Prisma's effective default, measured
- * rather than assumed (see `REFERENTIAL_ACTIONS` and
- * `resolvePrismaReferentialDefaults`).
+ * rows disappear that the caller never named — which is exactly what a transaction
+ * planner must reason about before it agrees to run a plan. So invisibility on the
+ * generated types is *evidence* for "no framework meaning", and evidence can be
+ * outweighed; it was never the meaning itself. `@map` and `@@index` remain
+ * discarded because they fail the test AND the reason. `@relation`'s `map:` joins
+ * them: a foreign-key constraint name is genuinely DB-side, and it was bucket 3
+ * until now, which made `@relation(map: …)` — valid PSL — a build stop on its own.
+ *
+ * Actions are read on both arguments and carried **resolved**: an absent argument
+ * is not a third state, it is Prisma's effective default, measured rather than
+ * assumed (see `REFERENTIAL_ACTIONS` and `resolvePrismaReferentialDefaults`).
  *
  * Bucket 2 previously did not exist, and a field-level `@map` landed in
  * `unhandled`: the framework would have refused to build against any schema that
- * maps a column name, which is most real Prisma schemas. It was invisible only
- * because both Phase 8 schemas use zero `@map`. The enum **member**-level `@map`
- * discard, which T-3's `PrismaSchemaEnum` and Task 3's enum-mapper case already
- * required, folds into bucket 2 and stops being a special case.
+ * maps a column name, which is most real Prisma schemas.
  *
  * # Arguments are located by NAME, never by position (added 2026-09-29)
  *
- * PSL lets the same argument list arrive positionally or named, and lets the
- * named arguments come in any order. Measured against `prisma validate` 7.10.0
- * and against a generated client on 2026-09-29: `@@unique([b, a])`,
- * `@@unique(fields: [b, a])`, `@@unique(name: "k", map: "m", fields: [b, a])`
- * and every other permutation are accepted, and the client keys the unnamed ones
- * `b_a` and the named ones `k` regardless of the order they were written in. The
- * spelling is therefore not a fact about the schema, and a reader that took the
- * list to be the FIRST argument read `@@unique(fields: [b, a])` as one member
- * called `fields: [b, a]` — silently, with `unhandled` empty — so the generate
- * step refused a schema Prisma accepts. ARGUMENT order does not matter; MEMBER
- * order inside the list still does, because it is part of the identity and of
- * the addressing key.
+ * PSL lets the same argument list arrive positionally or named, and lets the named
+ * arguments come in any order. Measured against `prisma validate` 7.10.0 and
+ * against a generated client on 2026-09-29: `@@unique([b, a])`, `@@unique(fields:
+ * [b, a])`, `@@unique(name: "k", map: "m", fields: [b, a])` and every other
+ * permutation are accepted, and the client keys the unnamed ones `b_a` and the
+ * named ones `k` regardless of the order they were written in. The spelling is
+ * therefore not a fact about the schema, and a reader that took the list to be the
+ * FIRST argument read `@@unique(fields: [b, a])` as one member called `fields: [b,
+ * a]` — silently, with `unhandled` empty — so the generate step refused a schema
+ * Prisma accepts. ARGUMENT order does not matter; MEMBER order inside the list
+ * still does, because it is part of the identity and of the addressing key.
  *
  * The same rule applies to `@relation`, which mixes a positional argument (the
- * relation name) with named ones; it was already order-independent and its FK
- * read was unaffected.
+ * relation name) with named ones; it was already order-independent and its FK read
+ * was unaffected.
  *
  * A list whose members are not plain field names — `@@unique([a(sort: Desc)])`,
  * valid PSL at 7.10.0 — cannot be located without evaluating, so it is bucket 3
@@ -139,9 +128,9 @@ import type { PrismaSchemaFacts } from "./schema-facts.interface.js";
  *
  * Prisma 7 accepts a folder (`prisma validate --schema <folder>` verified at
  * 7.10.0). Blocks are file-local and references are by name, so there is no
- * cross-file grammar and **no linker**: reading a folder appends each file's
- * facts in filename order and nothing is rewritten. Every fact keeps the file and
- * line it was written on.
+ * cross-file grammar and **no linker**: reading a folder appends each file's facts
+ * in filename order and nothing is rewritten. Every fact keeps the file and line
+ * it was written on.
  */
 export type PrismaSchemaSource = {
     readonly file: string;