@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/discovery/model.discoverer.js

@@ -0,0 +1,341 @@
+import { BUILT_IN_SCALARS, } from "@aventara/core";
+import { deriveRelationCapabilities, deriveScalarCapabilities, } from "./capability.deriver.js";
+import { mapPrismaEnum } from "./enum.mapper.js";
+import { crossCheckCreateOptional, projectPrismaField, } from "./field.mapper.js";
+import { mapPrismaIdentifiers } from "./identifier.mapper.js";
+import { deriveResourceOperations } from "./operations.deriver.js";
+/**
+ * Task 6 — **composition**: the one place the two readers' facts become the two
+ * halves of the discovery artifact.
+ *
+ * Every rule it applies belongs to somebody else. That is the design, not a
+ * shortcut: the scalar table is `scalar.mapper.ts`'s, the field projection and the
+ * lifecycle traits are `field.mapper.ts`'s, identity is `identifier.mapper.ts`'s,
+ * capabilities are `capability.deriver.ts`'s, the §8.3 variant gate is
+ * `operations.deriver.ts`'s and nowhere else, and the enum comparison is
+ * `enum.mapper.ts`'s. This module **orders and assembles**, and it owns exactly
+ * two judgements of its own:
+ *
+ * 1. **Which diagnostics are fatal.** A mapper answers with a diagnostic; whether
+ *    the build stops is composition's call, because only composition knows that a
+ *    model with an unmapped column cannot produce a Contract at all.
+ * 2. **The scalar registry.** `ScalarRegistry` is the set of Aventara scalar
+ *    identities the discovered fields actually use — a fact no single field can
+ *    state and only the whole pass can.
+ *
+ * # Three halves, from one pass over one field list
+ *
+ * `model` is core's: canonicalized, hashed, compiled into the Contract.
+ * `translation` is the adapter's Prisma addressing, and `referentialActions` is
+ * what the resolved `@relation(onDelete:/onUpdate:)` arguments say. All three are
+ * built from the SAME pass: the translation table from the same
+ * `mapPrismaIdentifiers` answer the model's `identifiers` come from — `.members`
+ * into the model, the whole address into the table — and the action table from the
+ * same `projectPrismaField` answer the model's relation fields come from. Two
+ * parallel passes would have to be kept in step; one pass cannot drift.
+ *
+ * `PrismaTranslationTable<M>` and `PrismaReferentialActionTable<M>` are mapped
+ * types over the model's resources, so a resource this module adds to the model
+ * and forgets to address — or forgets to answer the actions for — is a **compile
+ * error** rather than a runtime `undefined` at the first unique read or the first
+ * cascade question.
+ *
+ * The action table carries **only owning edges**, because only an owning edge has
+ * an action: PSL forbids the back-reference from declaring one, so the
+ * back-reference's answer is its partner's. Its direction is the one documented on
+ * `PrismaReferentialEdge` and on `field.mapper.ts`'s `PrismaRelationEdge` —
+ * *deleting a `target` does `onDelete` to rows of the enclosing resource* — and it
+ * is carried out of field projection unchanged rather than re-derived here.
+ *
+ * # No provider reaches this module, and that is enforced by the input
+ *
+ * The composer is created with a {@link TransactionCapability} and nothing else.
+ * `provider` is not a member anywhere on the path, so `if (provider === …)` is a
+ * compile error rather than a convention (dictionary invariant 6, D-802). The
+ * generate step keeps `provider` only to stamp the artifact, which is a recorded
+ * fact and not a branch.
+ *
+ * `transactions` is a **driver** fact (T-2) and the driver is a runtime choice, so
+ * it is declared to the composer at generate time. The two cannot silently
+ * disagree: an artifact that says `"interactive"` loaded by an adapter whose
+ * declared driver says `"none"` mounts no `transaction`, and core refuses
+ * construction with `DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH` **[CORE,
+ * framework.factory.ts]** — a hard, legible failure rather than a silent one.
+ *
+ * # The C-818 conflict this header used to record is closed
+ *
+ * It read: a relation carries create directives for `create.one` and none for
+ * `create.many` **[DOC7]**, `AdapterRelationField.capabilities` is one record per
+ * field with a single `create` member, so composition had to ask
+ * `deriveRelationCapabilities` for the `"create.one"` answer — the permissive one —
+ * and C-818's restriction was unrepresentable in the Contract.
+ *
+ * The capability members are **scope-qualified** now, so the one record holds both
+ * answers: the create stage is advertised at the `nested` write scope and not at the
+ * bulk one. Composition asks for no variant, passes no `operation`, and advertises
+ * nothing it cannot honour. The mutation translator keeps its refusal — it is the
+ * belt to core's braces, not the only guard (C-855) — but it is no longer the ONLY
+ * place the restriction exists.
+ */
+/** Composition refuses: the collected diagnostics, named and reported together. */
+export class PrismaModelCompositionError extends Error {
+    name = "PrismaModelCompositionError";
+    diagnostics;
+    constructor(diagnostics) {
+        super([
+            "discovery cannot compose an AdapterModel from this schema and client:",
+            ...diagnostics.map((diagnostic) => `  - ${diagnostic}`),
+        ].join("\n"));
+        this.diagnostics = diagnostics;
+    }
+}
+/**
+ * The generate step's `composeModel` seam, filled.
+ *
+ * A factory rather than a bare function because the step's seam takes only the
+ * readers' output — order and refusal over external effects is the step's job, and
+ * the declared driver fact is the caller's.
+ */
+export function createPrismaModelComposer(options) {
+    return (input) => discoverPrismaModel({ ...input, ...options });
+}
+export function discoverPrismaModel(input) {
+    const diagnostics = [];
+    const declared = new Map(input.facts.models.map((m) => [m.name, m]));
+    const modelNames = new Set(declared.keys());
+    const admitted = new Set(input.admitted);
+    const enums = composeEnums(input, diagnostics);
+    const resources = {};
+    const translation = {};
+    const referentialActions = {};
+    const usedScalars = new Set();
+    for (const name of input.admitted) {
+        const model = declared.get(name);
+        const exposed = input.surface.resources[name];
+        if (model === undefined || exposed === undefined) {
+            // The existence gate admitted it, so both halves must be there. A
+            // diagnostic rather than a throw: the caller gets the whole list.
+            diagnostics.push(`\`${name}\` was admitted by the existence gate and is absent from ${model === undefined ? "the PSL facts" : "the capability surface"}, which the gate cannot produce — this is a reader defect.`);
+            continue;
+        }
+        const composed = composeResource({
+            model,
+            exposed,
+            surface: input.surface,
+            modelNames,
+            admitted,
+            transactions: input.transactions,
+            diagnostics,
+            usedScalars,
+        });
+        resources[name] = composed.resource;
+        translation[name] = composed.translation;
+        referentialActions[name] = composed.referentialActions;
+    }
+    if (diagnostics.length > 0) {
+        throw new PrismaModelCompositionError(diagnostics);
+    }
+    return {
+        model: {
+            scalars: composeScalarRegistry(usedScalars),
+            enums,
+            resources,
+            transactions: input.transactions,
+        },
+        translation,
+        referentialActions,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Enums                                                              *
+ * ------------------------------------------------------------------ */
+function composeEnums(input, diagnostics) {
+    const enums = {};
+    for (const declared of input.facts.enums) {
+        // The mapper's judgement, forwarded. Declaration order is semantic and
+        // enters the Contract hash, so "diverged" is fatal here for the same reason
+        // `reader-crosscheck.ts` reports it: the client is from another schema.
+        const mapped = mapPrismaEnum({
+            declared,
+            exposed: input.surface.enums[declared.name],
+        });
+        if (mapped.outcome === "enum") {
+            enums[mapped.name] = mapped.definition;
+            continue;
+        }
+        if (mapped.outcome === "diverged") {
+            diagnostics.push(mapped.diagnostic.message);
+        }
+        // `excluded` is the existence rule applied to an enum: declared in PSL and
+        // absent from the generated `enums.ts`. It is NOT fatal, exactly as an
+        // `@ignore`d model is not: an enum the client cannot name has no place in a
+        // Contract, and any column typed by it is itself absent from the 🟢 surface
+        // and therefore already excluded by the field-level gate.
+    }
+    return enums;
+}
+/* ------------------------------------------------------------------ *
+ * One resource                                                       *
+ * ------------------------------------------------------------------ */
+function composeResource(input) {
+    const { model, exposed, diagnostics } = input;
+    const fields = {};
+    /** Owning edges only, in PSL field-declaration order (see this module's header). */
+    const owningEdges = [];
+    const unknowns = [];
+    /** What the create-optional cross-check consumes: PSL's own answers. */
+    const projectedScalars = [];
+    for (const field of model.fields) {
+        const projection = projectPrismaField({
+            resource: model.name,
+            field,
+            siblings: model.fields,
+            surface: exposed,
+            enums: input.surface.enums,
+            models: input.modelNames,
+        });
+        switch (projection.outcome) {
+            case "excluded":
+                // The existence gate has already decided this absence is explained;
+                // re-deciding it here would be a second owner for C-808.
+                continue;
+            case "unmapped":
+                diagnostics.push(projection.diagnostic.message);
+                continue;
+            case "scalar": {
+                unknowns.push(...projection.unknowns);
+                const scalarSurface = exposed.scalarFields[field.name];
+                if (scalarSurface === undefined) {
+                    diagnostics.push(`\`${model.name}.${field.name}\` projected as a scalar and carries no scalar surface, which is a reader defect.`);
+                    continue;
+                }
+                const type = projection.field.type;
+                if ("scalar" in type) {
+                    // Narrowed by membership rather than asserted: `AdapterScalarField`'s
+                    // type ref is `keyof M["scalars"]`, which is `string` on the general
+                    // model, and the registry must carry built-in identities only.
+                    const scalar = BUILT_IN_SCALARS.find((candidate) => candidate === type.scalar);
+                    if (scalar === undefined) {
+                        diagnostics.push(`\`${model.name}.${field.name}\` mapped to the scalar identity \`${type.scalar}\`, which is not one of Aventara's built-in scalars (${BUILT_IN_SCALARS.join(", ")}).`);
+                        continue;
+                    }
+                    input.usedScalars.add(scalar);
+                }
+                fields[projection.name] = {
+                    ...projection.field,
+                    capabilities: deriveScalarCapabilities({ surface: scalarSurface }),
+                };
+                projectedScalars.push({
+                    name: projection.name,
+                    nullable: projection.field.nullable,
+                    list: projection.field.list,
+                    lifecycle: projection.field.lifecycle,
+                });
+                continue;
+            }
+            case "relation": {
+                const relationSurface = exposed.relationFields[field.name];
+                if (relationSurface === undefined) {
+                    diagnostics.push(`\`${model.name}.${field.name}\` projected as a relation and carries no relation surface, which is a reader defect.`);
+                    continue;
+                }
+                if (!input.admitted.has(projection.field.target)) {
+                    // An edge to a resource the model does not carry would compile into a
+                    // Contract that references a Resource that is not there.
+                    diagnostics.push(`\`${model.name}.${field.name}\` targets \`${projection.field.target}\`, which the existence gate did not admit, so the edge would point at a Resource the model does not carry.`);
+                    continue;
+                }
+                fields[projection.name] = {
+                    ...projection.field,
+                    // No variant is named: the scope-qualified members carry both create
+                    // answers at once. See this module's header for the conflict that
+                    // closed.
+                    capabilities: deriveRelationCapabilities({
+                        surface: relationSurface,
+                    }),
+                };
+                // The edge's resolved actions, carried out of the SAME projection the
+                // field above came from. Both members are non-null exactly on an owning
+                // edge, and PSL forbids a back-reference from declaring either — so the
+                // pair is tested together rather than one member at a time, and a
+                // back-reference contributes nothing instead of contributing two nulls.
+                if (projection.edge.onDelete !== null &&
+                    projection.edge.onUpdate !== null) {
+                    owningEdges.push({
+                        field: projection.edge.field,
+                        // The PARENT. Deleting one of these does `onDelete` to rows of
+                        // `model.name`, which is the key this list hangs under.
+                        target: projection.edge.target,
+                        cardinality: projection.edge.cardinality,
+                        onDelete: projection.edge.onDelete,
+                        onUpdate: projection.edge.onUpdate,
+                    });
+                }
+                continue;
+            }
+        }
+    }
+    if (unknowns.length > 0) {
+        // T-3.1 invariant 5: an unrecognised construct is a build stop, never a
+        // column Aventara quietly decides the client must supply.
+        for (const unknown of unknowns) {
+            diagnostics.push(`${unknown.spelling} (${unknown.kind}) in \`${unknown.block ?? "<top level>"}\` at ${unknown.site.file}:${unknown.site.line}: ${unknown.text} — the reader does not model it, and a silently dropped construct is how a grammar change becomes wrong output instead of a build stop.`);
+        }
+    }
+    // Task 4's cross-check, run from the SURFACE's own `createOptional` bit. The
+    // marker is one bit over several causes and is never read as a trait; this is
+    // the one direction it is read in.
+    const createOptional = Object.entries(exposed.scalarFields)
+        .filter(([, scalar]) => scalar.createOptional)
+        .map(([name]) => name);
+    const creatability = crossCheckCreateOptional({
+        resource: model.name,
+        fields: projectedScalars,
+        createOptional,
+    });
+    diagnostics.push(...creatability.messages);
+    const identifiers = mapPrismaIdentifiers(model);
+    const members = identifiers.identifiers.map((address) => address.members);
+    return {
+        resource: {
+            fields,
+            identifiers: members,
+            // The §8.3 gate's single home. Composition supplies its three inputs and
+            // omits nothing itself.
+            operations: deriveResourceOperations({
+                operations: exposed.operations,
+                identifiers: members,
+                transactions: input.transactions,
+            }),
+        },
+        // The same list's other projection: `members` above, the whole address here.
+        translation: { identifierKeys: identifiers.identifiers },
+        referentialActions: { owningEdges },
+    };
+}
+/* ------------------------------------------------------------------ *
+ * The scalar registry                                                *
+ * ------------------------------------------------------------------ */
+/**
+ * The Aventara scalar identities the discovered fields actually use, in core's
+ * own `BUILT_IN_SCALARS` declaration order.
+ *
+ * Ordered by the union rather than by field declaration order for the reason
+ * `capability.deriver.ts` orders its lists that way: the canonical form must be a
+ * property of the model and not of how a schema happened to be written. (The
+ * emitted artifact is canonicalized again before hashing, so this order is for
+ * readers of the model in memory; it costs nothing and removes a question.)
+ *
+ * An enum-backed column contributes NO scalar: C-810 makes it a ScalarField whose
+ * type ref takes the `enum` arm, and the enum registry is where its identity
+ * lives.
+ */
+function composeScalarRegistry(used) {
+    const scalars = {};
+    for (const scalar of BUILT_IN_SCALARS) {
+        if (used.has(scalar)) {
+            scalars[scalar] = { builtin: true };
+        }
+    }
+    return scalars;
+}

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

@@ -0,0 +1,75 @@
+import type { AdapterResource, ResourceOperations, TransactionCapability } from "@aventara/core";
+import type { PrismaAdapterModel } from "./discovery-artifact.interface.js";
+/**
+ * T-6 — `deriveResourceOperations`, **the single home of the §8.3 gate**.
+ *
+ * §8.3: *"an adapter … MUST advertise the variant only when it can preserve
+ * framework semantics atomically enough for the provider… If the provider cannot
+ * guarantee the required semantics, the variant is omitted."* Every omission in
+ * Phase 8 is decided here. No mapper, no discoverer, no emitter and no executor
+ * may drop a variant, because an omission in two places is an omission nobody can
+ * audit.
+ *
+ * # Three inputs, and `provider` is not one of them
+ *
+ * The available operation set is read from the client's own `<M>Delegate` (T-3) —
+ * at 7.10.0, identically on both Phase 8 engines and on all six models (four
+ * when this was first measured; re-measured over `User` and `Profile` too when
+ * the one-to-one fixture landed, and the set is unchanged):
+ *
+ * ```text
+ * findUnique, findUniqueOrThrow, findFirst, findFirstOrThrow, findMany, create,
+ * createMany, createManyAndReturn, delete, update, deleteMany, updateMany,
+ * updateManyAndReturn, upsert, count, aggregate, groupBy
+ * ```
+ *
+ * The second input is the model's identifiers, because `find.unique`,
+ * `update.unique`, `delete.unique` and `upsert.unique` are meaningless without
+ * one. The third is `transactions` — the **only** declared profile row this gate
+ * needs. The whole `PrismaProviderProfile` is deliberately NOT accepted: it
+ * carries `provider`, and a module that cannot be handed a provider cannot branch
+ * on one (dictionary invariant 6). `isolationLevels` is not a precondition of any
+ * variant (C-830: Phase 8 escalates no isolation).
+ *
+ * `supportsEmulatedFirstVariants` is **derived, exactly `transactions !== "none"`,
+ * and stored nowhere** (T-2's amendment, D-824). A stored copy would be a second
+ * source of truth for a one-line derivation.
+ *
+ * # What is NOT gated here, and why that is deliberate
+ *
+ * `delete.many` is absent on **every** profile (C-829, D-826): 7.10.0 has no
+ * `deleteManyAndReturn`, the architect ruled the variant omitted rather than
+ * emulated, and the omission does **not** vary with `transactions`. Pairing it
+ * with the emulation gate would re-teach the read-capability-depends-on-
+ * transaction-capability coupling C-829 records as no longer existing.
+ *
+ * The first-style variants' preconditions are the **read**, an identifier, a
+ * transaction — the three `emulatedFirst` carries, because all three are shared —
+ * and then **the chosen route's own write call**, which each family contributes
+ * itself. §14e's route is **Route A**: the read selects the identifier and the
+ * write is Prisma's own `update`/`delete` narrowed to it with the caller's
+ * predicate re-asserted under `AND`. Task 10 measured both routes on the real
+ * 7.10.0 client on both engines, every row came out for Route A, and the choice is
+ * propagated across the 21 rows of `translation/operation.translator.ts`'s table;
+ * `FIRST_VARIANT_WRITE_ROUTE` there is the one cell that names it.
+ *
+ * So `update.first` reads `emulatedFirst && exposes("update")` and `delete.first`
+ * reads `emulatedFirst && exposes("delete")`. Under Route B those cells would read
+ * `updateManyAndReturn` and `deleteMany` instead — which is exactly why the write
+ * call is NOT folded into `emulatedFirst`: a shared precondition naming one route's
+ * call would assert a gate the other route does not have, an assertion that cannot
+ * fail for the right reason (C-817, T-7.1.1). A reversal of §14e is an edit to
+ * these two cells and to the translator's one, and to nothing else here.
+ */
+/** Core's own identifier tuples for a discovered Resource. */
+type DiscoveredIdentifiers = AdapterResource<PrismaAdapterModel>["identifiers"];
+export type ResourceOperationsInput = {
+    /** `<M>Delegate`'s own methods, as the types reader read them (T-3). */
+    readonly operations: readonly string[];
+    /** The model's usable identifiers; empty means no unique addressing exists. */
+    readonly identifiers: DiscoveredIdentifiers;
+    /** The one declared profile row this gate reads (T-2's amendment). */
+    readonly transactions: TransactionCapability;
+};
+export declare function deriveResourceOperations(input: ResourceOperationsInput): ResourceOperations;
+export {};

package/dist/discovery/operations.deriver.js

@@ -0,0 +1,92 @@
+/* ------------------------------------------------------------------ *
+ * The scopes each advertised variant qualifies its arguments with      *
+ * ------------------------------------------------------------------ */
+/**
+ * The scope follows the **Prisma call the gate below routes the variant to**, and
+ * those calls fall into four argument shapes. The scope therefore sits beside the
+ * gate that chose the call, where a reversal of §14e's route is visible as an edit
+ * to one cell — not in a constant in core, which would be a tabulated provider fact
+ * and wrong for the next adapter (D-802, §4 Q2).
+ *
+ * **The narrowest honest encoding (F-821).** Two of the four shapes are the
+ * unrestricted positions — the `"record"` projection and the `"nested"` data
+ * argument — which is exactly what core's readers (`projectionScopeOf`,
+ * `writeScopeOf`) answer for `true`. A descriptor stating them carries no
+ * information: core's canonicalizer collapsed it before any Contract value or
+ * hash, but it lengthened the artifact and moved its `modelHash`. So those
+ * variants are `true`, and a descriptor is stated only where it narrows: the two
+ * bulk shapes. `true` also stays the answer for the variants with no
+ * scope-qualified argument at all (`count` / `deleteMany` return a number, and the
+ * delete family has no data argument) — `OperationVariantScopes` requires at least
+ * one scope, so nothing else is representable there.
+ */
+/**
+ * A row-returning read (`findFirst`, `findUnique`, `findMany`), and a
+ * row-returning write or delete of ONE addressed record (`create`, `update`,
+ * `upsert`, `delete`, and the emulated first-style variants, whose §14e Route A
+ * write is Prisma's own `update` / `delete` narrowed to the identifier): the
+ * unrestricted projection and, for a write, the nested data argument — what
+ * `true` already means.
+ */
+const SINGLE_RECORD = true;
+/** `createManyAndReturn` / `updateManyAndReturn`: both axes are the bulk ones. */
+const WRITES_MANY_AND_RETURNS = {
+    projection: "bulkWrite",
+    write: "bulkWrite",
+};
+/** `createMany` / `updateMany`: the same flat data argument, and no projection. */
+const WRITES_MANY_AND_COUNTS = { write: "bulkWrite" };
+/** `count` / `deleteMany`: no projection argument and no data argument. */
+const QUALIFIES_NO_ARGUMENT = true;
+export function deriveResourceOperations(input) {
+    const exposes = (method) => input.operations.includes(method);
+    const addressable = input.identifiers.length > 0;
+    // Derived, never stored: the emulated read-then-write sequence runs inside one
+    // interactive transaction (D-807), so a driver without one cannot carry it.
+    const emulates = input.transactions !== "none";
+    /** A first-style variant is a read, an identifier to write by, and a transaction. */
+    const emulatedFirst = exposes("findFirst") && addressable && emulates;
+    const find = {
+        ...(exposes("findFirst") ? { first: SINGLE_RECORD } : {}),
+        ...(exposes("findUnique") && addressable ? { unique: SINGLE_RECORD } : {}),
+        ...(exposes("findMany") ? { many: SINGLE_RECORD } : {}),
+        ...(exposes("count") ? { count: QUALIFIES_NO_ARGUMENT } : {}),
+    };
+    const create = {
+        ...(exposes("create") ? { one: SINGLE_RECORD } : {}),
+        // C-817: the row-returning bulk write is what `create.many` owes its caller.
+        ...(exposes("createManyAndReturn")
+            ? { many: WRITES_MANY_AND_RETURNS }
+            : {}),
+        ...(exposes("createMany") ? { count: WRITES_MANY_AND_COUNTS } : {}),
+    };
+    const update = {
+        ...(emulatedFirst && exposes("update") ? { first: SINGLE_RECORD } : {}),
+        ...(exposes("update") && addressable ? { unique: SINGLE_RECORD } : {}),
+        ...(exposes("updateManyAndReturn")
+            ? { many: WRITES_MANY_AND_RETURNS }
+            : {}),
+        ...(exposes("updateMany") ? { count: WRITES_MANY_AND_COUNTS } : {}),
+    };
+    const remove = {
+        ...(emulatedFirst && exposes("delete") ? { first: SINGLE_RECORD } : {}),
+        ...(exposes("delete") && addressable ? { unique: SINGLE_RECORD } : {}),
+        // `many` is ABSENT unconditionally (C-829). `delete.count` is the supported
+        // way to delete a filtered set.
+        ...(exposes("deleteMany") ? { count: QUALIFIES_NO_ARGUMENT } : {}),
+    };
+    const upsert = {
+        ...(exposes("upsert") && addressable ? { unique: SINGLE_RECORD } : {}),
+    };
+    return {
+        ...(nonEmpty(find) ? { find } : {}),
+        ...(nonEmpty(create) ? { create } : {}),
+        ...(nonEmpty(update) ? { update } : {}),
+        ...(nonEmpty(remove) ? { delete: remove } : {}),
+        ...(nonEmpty(upsert) ? { upsert } : {}),
+    };
+}
+/** A family with no available variant is absent, not an empty object. */
+function nonEmpty(family) {
+    return Object.keys(family).length > 0;
+}

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

@@ -0,0 +1,81 @@
+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.
+ * - `unmapped` — a type name in neither table. A **diagnostic**, never a silent
+ *   drop and never a nearest-neighbour guess (C-809).
+ *
+ * # 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,
+ * `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]**,
+ * 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.
+ *
+ * # 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).
+ */
+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). */
+    readonly surface: PrismaResourceSurface;
+    /** TYPE — `enums.ts`, which is what makes an enum name an enum name. */
+    readonly enums: Readonly<Record<string, readonly string[]>>;
+};
+export type ScalarMappingOutcome = {
+    readonly outcome: "scalar";
+    readonly mapping: PrismaScalarMapping;
+} | {
+    readonly outcome: "enum";
+    readonly enum: string;
+} | {
+    readonly outcome: "excluded";
+    readonly diagnostic: PrismaDiscoveryDiagnostic;
+} | {
+    readonly outcome: "unmapped";
+    readonly diagnostic: PrismaDiscoveryDiagnostic;
+};
+export declare function mapPrismaScalarField(input: ScalarMappingInput): ScalarMappingOutcome;

package/dist/discovery/scalar.mapper.js

@@ -0,0 +1,51 @@
+import { PRISMA_NATIVE_FORMATS, PRISMA_SCALAR_TABLE, } from "./vocabulary.dictionary.js";
+export function mapPrismaScalarField(input) {
+    const { resource, field, surface, enums } = input;
+    const column = `${resource}.${field.name}`;
+    if (!Object.hasOwn(surface.scalarFields, field.name)) {
+        return {
+            outcome: "excluded",
+            diagnostic: {
+                code: "not-exposed",
+                message: `${column} is declared in schema.prisma and absent from the generated 🟢 types, so it is omitted: ${explainAbsence(field, surface)}`,
+            },
+        };
+    }
+    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];
+    if (mapping === undefined) {
+        return {
+            outcome: "unmapped",
+            diagnostic: {
+                code: "unmapped-prisma-type",
+                message: `${column} is written as \`${field.type}\`, which is neither a built-in Prisma scalar (${Object.keys(PRISMA_SCALAR_TABLE).join(", ")}) nor an enum the generated \`enums.ts\` exposes. Discovery does not guess a nearest scalar.`,
+            },
+        };
+    }
+    // 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);
+    return {
+        outcome: "scalar",
+        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`";
+    }
+    if (Object.hasOwn(surface.relationFields, field.name)) {
+        return "the 🟢 types expose it as a relation edge, not a scalar column";
+    }
+    return "no schema attribute explains it — a provider drop, an `Unsupported(…)` column or a preview-feature exclusion";
+}