@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/discovery/capability.deriver.js

@@ -0,0 +1,350 @@
+import { PRISMA_EDGE_ARGUMENTS, PRISMA_FILTER_OPERATORS, PRISMA_REDUCERS, PRISMA_RELATION_DIRECTIVES, PRISMA_RELATION_FILTERS, PRISMA_SCALAR_DIRECTIVES, } from "./vocabulary.dictionary.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
+ * 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.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * # 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`.
+ *
+ * # 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 class PrismaCapabilityDerivationError extends Error {
+    name = "PrismaCapabilityDerivationError";
+}
+/* ------------------------------------------------------------------ *
+ * Canonical orders — core's own union declaration order [CORE]        *
+ * ------------------------------------------------------------------ */
+const FILTER_OPERATOR_ORDER = [
+    "equals",
+    "not",
+    "in",
+    "notIn",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "contains",
+    "startsWith",
+    "endsWith",
+    "mode",
+    "has",
+    "hasEvery",
+    "hasSome",
+    "isEmpty",
+    "path",
+    "stringContains",
+    "stringStartsWith",
+    "stringEndsWith",
+    "arrayContains",
+    "arrayStartsWith",
+    "arrayEndsWith",
+];
+const SCALAR_DIRECTIVE_ORDER = [
+    "$increment",
+    "$decrement",
+    "$multiply",
+    "$divide",
+    "$push",
+    "$unset",
+];
+const RELATION_FILTER_ORDER = [
+    "nested",
+    "match",
+    "null",
+    "some",
+    "every",
+    "none",
+];
+const RELATION_DIRECTIVE_ORDER = [
+    "$create",
+    "$connect",
+    "$connectOrCreate",
+    "$disconnect",
+    "$set",
+    "$update",
+    "$delete",
+    "$upsert",
+];
+const PAGINATION_ORDER = [
+    "limit",
+    "offset",
+    "cursor",
+];
+/* ------------------------------------------------------------------ *
+ * Scalars                                                            *
+ * ------------------------------------------------------------------ */
+export function deriveScalarCapabilities(input) {
+    const { surface } = input;
+    const operands = deriveScalarFilterOperands(input);
+    const filter = canonical(FILTER_OPERATOR_ORDER, surface.filters
+        .map((key) => look(PRISMA_FILTER_OPERATORS, key, "a scalar filter operator"))
+        .filter((operator) => translatable(operator, operands)));
+    return {
+        // The column is in `$<M>Payload.scalars`, which is the set the client
+        // actually returns — the existence gate's own evidence (T-3.1 invariant 3).
+        select: true,
+        ...(filter.length > 0 ? { filter } : {}),
+        order: surface.orderable,
+        // C-836: only where `SortOrderInput` is admitted for THIS field. Absent, not
+        // `false`, elsewhere — core reads `orderNulls !== true` either way, and an
+        // absent member keeps the canonical form free of negative facts.
+        ...(surface.nullsOrderable ? { orderNulls: true } : {}),
+        ...directives("create", surface.createOperations),
+        ...directives("update", surface.updateOperations),
+    };
+}
+/**
+ * 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 function deriveScalarFilterOperands(input) {
+    const operands = {};
+    for (const operator of FILTER_OPERATOR_ORDER) {
+        for (const [key, written] of Object.entries(input.surface.filterOperands)) {
+            if (look(PRISMA_FILTER_OPERATORS, key, "a scalar filter operator") ===
+                operator) {
+                operands[operator] = written;
+            }
+        }
+    }
+    return operands;
+}
+/**
+ * Whether an advertised operator's OPERAND can be honoured — Task 7's half of
+ * §9.2's rule that *"JSON path/content operators are exposed only where provider
+ * behavior can be mapped reliably"*.
+ *
+ * Exactly one operator reaches this test today, and it is the one the plan left
+ * open (§12, "How the `path` filter operator is emitted per provider"):
+ * `JsonFilterBase.path` is `string[]` on one engine and a JSONPath `string` on
+ * the other, measured 2026-10-02 at 7.10.0 — and the engines enforce it at
+ * RUNTIME, not only in the types:
+ *
+ * - PostgreSQL: *"Argument `path`: Invalid value provided. Expected String[], provided String."*
+ * - SQLite: *"Argument `path`: Invalid value provided. Expected String, provided (String)."*
+ *
+ * So one canonical Aventara operand cannot be carried to both, and the choice is
+ * §9.2's other ending: **the operator is not advertised where the operand is the
+ * JSONPath string**. Translating instead would mean synthesizing a JSONPath from
+ * a segment list — an escaping and array-index dialect nobody has measured — and
+ * a translation that is wrong on `{"a.b": …}` is the silent behaviour change
+ * C-855 exists to prevent. Omission is expressible in
+ * `ScalarFieldCapabilities.filter` exactly as it stands, so nothing escalates to
+ * core.
+ *
+ * The decision is read off the recorded operand SHAPE and nothing else. No
+ * `provider` is in scope here, by construction (see this module's header), and no
+ * Aventara scalar identity is needed either: T-6's `mapping` would be a second,
+ * weaker source for a fact the operand already states.
+ */
+function translatable(operator, operands) {
+    if (operator !== "path") {
+        return true;
+    }
+    return admitsStringList(operands.path);
+}
+/** Whether a written operand type admits a list of strings. */
+function admitsStringList(written) {
+    if (written === undefined) {
+        return false;
+    }
+    return written
+        .split("|")
+        .map((member) => member.trim())
+        .includes("string[]");
+}
+function directives(stage, operations) {
+    if (operations === null) {
+        // The client exposes no entry for this column at this stage: not writable.
+        return {};
+    }
+    return {
+        [stage]: canonical(SCALAR_DIRECTIVE_ORDER, operations
+            .map((key) => look(PRISMA_SCALAR_DIRECTIVES, key, "a scalar mutation directive"))
+            .filter((directive) => directive !== null)),
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Relations                                                          *
+ * ------------------------------------------------------------------ */
+/* ------------------------------------------------------------------ *
+ * The scope arms — the narrowest encoding that is still honest         *
+ * ------------------------------------------------------------------ */
+/**
+ * The projection answer for one member: the **unqualified** arm where the
+ * capability holds in every scope, the qualified arm only where it is genuinely
+ * narrower, and `false` where it holds nowhere.
+ *
+ * # Why the full list is never emitted
+ *
+ * `RelationProjectionCapability` is a union, and a list naming every
+ * `ProjectionScope` says exactly what `true` says. Emitting it would put one
+ * semantic fact into two encodings — one fact with two hashes, which is C-843 and
+ * `AGENT.md`'s one-source-of-truth rule, and the ground on which the architect
+ * rejected the flat-or-per-variant option. So the degenerate list is not produced
+ * here at all. S4's canonicalizing collapse is the safety net for a *different*
+ * producer; this one does not need it.
+ *
+ * # Non-emptiness
+ *
+ * `ProjectionScopes` is a non-empty tuple, so "holds nowhere" cannot be spelled as
+ * `[]`. It is `false` — *the capability is absent*, which is the answer this module
+ * already gave before any scope existed and the answer `absent ≠ empty` requires.
+ * Every array below is a literal with a written member, so the tuple's lower bound
+ * is discharged by construction rather than by an assertion.
+ */
+function projectableIn(unrestricted, bulk) {
+    if (unrestricted && bulk) {
+        return true;
+    }
+    if (unrestricted) {
+        return ["record"];
+    }
+    if (bulk) {
+        return ["bulkWrite"];
+    }
+    return false;
+}
+/**
+ * The reducer answer: the bare reducer list where the reducers hold in every
+ * projection scope, the scoped form where they are narrower.
+ *
+ * The reducer list and the scope list stay separate facts, so `[]` keeps meaning
+ * what it means and the scope says only where the reducers may be asked for.
+ */
+function reducersIn(reducers, bulk) {
+    return bulk ? reducers : { reducers, scopes: ["record"] };
+}
+/**
+ * The write answer for one stage, on the same rule: the bare directive list where
+ * the stage holds in every write scope, the scoped form where it is narrower.
+ *
+ * The directive list is carried through rather than replaced, because `[]` already
+ * means *"writable with no directive"* and an absent member means *"not writable
+ * during this stage"* — two live answers core distinguishes (`V1006`), and a scope
+ * qualifier must not collapse them into a third.
+ */
+function writableIn(directives, bulk) {
+    return bulk ? directives : { directives, scopes: ["nested"] };
+}
+export function deriveRelationCapabilities(input) {
+    const { surface } = input;
+    const edgeArguments = new Set(surface.edgeArguments);
+    for (const argument of edgeArguments) {
+        look(PRISMA_EDGE_ARGUMENTS, argument, "an edge argument");
+    }
+    const filter = canonical(RELATION_FILTER_ORDER, [
+        // The edge's own `where` argument is what core calls `nested`: filtering the
+        // RETURNED edge **[CORE, operations/operation-validator-core.ts]**.
+        ...(edgeArguments.has("where") ? ["nested"] : []),
+        ...surface.filters.map((key) => look(PRISMA_RELATION_FILTERS, key, "a relation filter")),
+        // A null absence predicate needs a nullable edge; `[Nullable]ScalarRelationFilter`
+        // carries the same two keys either way, so nullability is the discriminant.
+        ...(surface.nullable ? ["null"] : []),
+    ]);
+    const pagination = canonical(PAGINATION_ORDER, surface.pagination
+        .map((argument) => look(PRISMA_EDGE_ARGUMENTS, argument, "an edge argument"))
+        .filter((capability) => capability !== null));
+    const reducers = surface.reducers.map((key) => look(PRISMA_REDUCERS, key, "a relation reducer"));
+    const directives = (keys) => canonical(RELATION_DIRECTIVE_ORDER, keys
+        .map((key) => look(PRISMA_RELATION_DIRECTIVES, key, "a relation mutation directive"))
+        .filter((directive) => directive !== null));
+    return {
+        // The edge's own `select` / `include` arguments answer the UNRESTRICTED
+        // position; the surface's `bulkSelect` / `bulkInclude` answer the bulk one.
+        // Both are presence reads: see `PrismaRelationSurface.bulkSelect` for why the
+        // foreign-key rule is the explanation and not the mechanism.
+        select: projectableIn(edgeArguments.has("select"), surface.bulkSelect),
+        include: projectableIn(edgeArguments.has("include"), surface.bulkInclude),
+        ...(filter.length > 0 ? { filter } : {}),
+        order: surface.orderable,
+        ...(pagination.length > 0 ? { pagination } : {}),
+        ...(reducers.length > 0
+            ? { reducers: reducersIn(reducers, surface.bulkReducers) }
+            : {}),
+        // C-818, now EXPRESSIBLE rather than recorded as a conflict: the bulk create
+        // input carries no entry for this edge, so the create stage is advertised at
+        // the `nested` scope and nowhere else. Composition no longer has to choose
+        // between the two create variants' answers, and nothing is advertised to
+        // `create.many` that Prisma has no key for.
+        //
+        // C-855: each stage is still derived from ITS OWN nested input. The
+        // create-stage input admits `create` / `connectOrCreate` / `createMany` /
+        // `connect` and nothing more, so reusing the update-stage list here advertised
+        // five directives per to-many edge — and two per to-one edge — that Prisma
+        // rejects outright and `mutation.translator.ts` therefore refuses.
+        create: writableIn(directives(surface.createMutations), surface.bulkCreatable),
+        update: writableIn(directives(surface.updateMutations), surface.bulkUpdatable),
+    };
+}
+/* ------------------------------------------------------------------ *
+ * The two shared mechanics                                           *
+ * ------------------------------------------------------------------ */
+/**
+ * A dictionary lookup that refuses rather than returning `undefined`.
+ *
+ * A Prisma key no table recognises is a vocabulary gap — a 7.11 spelling, a
+ * provider feature nobody measured — and dropping one silently is precisely
+ * C-855's failure mode seen from the discovery side: a capability that quietly
+ * does not exist. The dictionary's `null` is the deliberate "no Aventara word"
+ * answer and passes through.
+ */
+function look(table, key, what) {
+    if (!(key in table)) {
+        throw new PrismaCapabilityDerivationError(`the generated types offer "${key}" as ${what} and the dictionary has no row for it`);
+    }
+    return table[key];
+}
+/** The members present, in the canonical order, deduplicated. */
+function canonical(order, present) {
+    const seen = new Set(present);
+    return order.filter((member) => seen.has(member));
+}

package/dist/discovery/discovery-artifact.interface.d.ts

@@ -0,0 +1,210 @@
+import type { AdapterResource, EnumDefinition, ScalarRegistry, TransactionCapability } from "@aventara/core";
+import type { PrismaProvider } from "../provider/provider-profile.js";
+/**
+ * T-4 — the discovery output, produced and never redefined.
+ *
+ * A plain `type`, not `interface … extends`: `AdapterModel.resources` is
+ * self-typed `AdapterResource<this>`, and a nominal `extends` hits TS2430.
+ * Phase 8 adds no member.
+ *
+ * (§9 of the plan names no owning file for this alias. It lives here because
+ * this is the Task 2 file that needs it — the artifact is what carries it.)
+ */
+export type PrismaAdapterModel = {
+    readonly scalars: ScalarRegistry;
+    readonly enums: Readonly<Record<string, EnumDefinition>>;
+    readonly resources: Readonly<Record<string, AdapterResource<PrismaAdapterModel>>>;
+    readonly transactions: TransactionCapability;
+};
+/**
+ * One identifier, and the **Prisma addressing key** that reaches it.
+ *
+ * `members` is the identifier as core carries it — derived from
+ * `AdapterResource` rather than restated, so a change to core's identifier type
+ * is a compile error here. `key` is the same criterion's *Prisma* spelling: the
+ * key a `WhereUniqueInput` accepts, and the key the generated `AtLeast<…, K>`
+ * union lists.
+ *
+ * The two are different facts, and the whole reason this type exists is that
+ * they are not derivable from one another. Measured at 7.10.0 (2026-09-29):
+ *
+ * - a single-column criterion keys by the field name and does **not** wrap:
+ *   `{ id: "x" }`;
+ * - a compound keys by its members joined with `_` **in attribute order** and
+ *   does wrap: `@@unique([b, a])` → `{ b_a: { b, a } }`;
+ * - `name: "X"` **replaces** the positional form on both sides — `}, "id" |
+ *   "altKey">` and `altKey?: Prisma.…CompoundUniqueInput`;
+ * - `map:` affects neither: it reaches only the 🛑 inline-schema blob.
+ *
+ * So `key` is stored at generate time and **matched** at runtime, never
+ * re-derived: `members.join("_")` is wrong for every named criterion, and
+ * whether it wraps is `members.length > 1`.
+ */
+export type PrismaIdentifierAddress = {
+    readonly members: AdapterResource<PrismaAdapterModel>["identifiers"][number];
+    readonly key: string;
+};
+/** One Resource's Prisma addressing, in the order the identifiers were discovered. */
+export type PrismaResourceTranslation = {
+    readonly identifierKeys: readonly PrismaIdentifierAddress[];
+};
+/**
+ * The **translation table**: Prisma addressing for every discovered Resource.
+ *
+ * Keyed on `M`'s own resource keys, so a table missing a Resource — or naming
+ * one the model does not have — is a compile error rather than a runtime
+ * `undefined` at the first unique read.
+ *
+ * It sits **beside** {@link PrismaDiscoveryArtifact.model}, never inside it, and
+ * that placement is the point: the model is canonicalized, hashed and compiled
+ * into the Contract, so a Prisma addressing key in it would put a DB-side
+ * rename into the Contract hash and force every client to be regenerated for a
+ * change with zero semantic content. This half is adapter-private: the executor
+ * reads it, core never sees it.
+ */
+export type PrismaTranslationTable<M extends PrismaAdapterModel = PrismaAdapterModel> = {
+    readonly [R in keyof M["resources"]]: PrismaResourceTranslation;
+};
+/**
+ * A referential action in Aventara's own vocabulary.
+ *
+ * Prisma's set — `Cascade | Restrict | NoAction | SetNull | SetDefault` — is the
+ * SQL-standard set spelled in PascalCase, so a faithful mapping exists and no
+ * Prisma spelling has to travel with the fact. These words are SQL's own
+ * (`ON DELETE SET NULL`), which is why the mapping is a rename and not a
+ * translation: nothing about it is Prisma-shaped, and the next adapter can state
+ * the same fact without inheriting this one's vocabulary.
+ *
+ * It is declared **here**, on the artifact side, rather than beside the PSL
+ * facts that resolve it: the artifact is what carries the vocabulary off the
+ * generate step and across the package boundary, and `schema-facts.interface.ts`
+ * imports it from here so that there is one spelling and the dependency runs
+ * generate-time → artifact rather than the other way about.
+ */
+export type PrismaReferentialAction = "cascade" | "restrict" | "no-action" | "set-null" | "set-default";
+/**
+ * One **owning** relation edge's resolved referential actions.
+ *
+ * # The direction, which is the whole point of this type
+ *
+ * `onDelete` is declared on the **child** — `Kid.parent @relation(…, onDelete:
+ * Cascade)` — and fires when the **parent** is deleted. PSL enforces that itself:
+ * `prisma validate` 7.10.0 refuses the action on the other edge, naming the
+ * opposite field. So an entry under resource `R` reads:
+ *
+ * > **deleting a `target` row does `onDelete` to rows of `R`.**
+ *
+ * A consumer asking *"what does deleting an `X` do?"* scans every resource's
+ * {@link PrismaResourceReferentialActions.owningEdges} for `target === "X"` and
+ * reads the enclosing resource key off the table. It never has to work out which
+ * side of a pair declared what.
+ *
+ * **Reversing that reading is silent.** Nothing in the shape distinguishes
+ * `resource` from `target`, both are resource names, and a planner built on the
+ * inverted reading cascades the wrong way with no type error and no runtime
+ * complaint. That is why the convention is restated here as well as on
+ * `field.mapper.ts`'s `PrismaRelationEdge`, which is where these values are
+ * carried out of field projection.
+ *
+ * # Both members are resolved, so neither is nullable
+ *
+ * An absent `@relation(onDelete:)` is **not** a third state: it is Prisma's
+ * effective default, measured at 7.10.0 with `prisma migrate diff` and identical
+ * on `postgresql` and `sqlite` — `SET NULL` when every scalar in `fields:` is
+ * optional, `RESTRICT` otherwise, and `CASCADE` on update
+ * (`schema.reader.ts`'s `resolvePrismaReferentialDefaults`). An action the reader
+ * cannot name is recorded in `unhandled` and fails the generate step, so no
+ * artifact ever carries an unresolved one.
+ */
+export type PrismaReferentialEdge = {
+    /** The edge's field name on the enclosing (child) resource. */
+    readonly field: string;
+    /** The resource the edge points AT — the parent, whose deletion fires `onDelete`. */
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+    /** What deleting a `target` row does to rows of the ENCLOSING resource. */
+    readonly onDelete: PrismaReferentialAction;
+    /** The same for an update of the referenced key. Read independently of `onDelete`. */
+    readonly onUpdate: PrismaReferentialAction;
+};
+/**
+ * One Resource's owning edges, in PSL field-declaration order.
+ *
+ * Only **owning** edges appear — the ones that declare `@relation(fields: …)`,
+ * which is what makes an edge the foreign-key side and the only side PSL lets
+ * carry an action. A back-reference's actions are its partner's, so an entry for
+ * it would carry two nulls and no fact; a resource with no owning edge carries an
+ * empty list, which is itself the answer that deleting anything leaves its rows
+ * alone.
+ */
+export type PrismaResourceReferentialActions = {
+    readonly owningEdges: readonly PrismaReferentialEdge[];
+};
+/**
+ * The **referential-action table**: every discovered Resource's owning edges,
+ * resolved.
+ *
+ * Keyed on `M`'s own resource keys for the reason {@link PrismaTranslationTable}
+ * is — a resource the model carries and the table forgets is a compile error at
+ * the generate step rather than a runtime `undefined` — and it sits **beside**
+ * {@link PrismaDiscoveryArtifact.model} and outside `modelHash` for the reason
+ * that one does: `modelHash` digests the model, and a referential action is not
+ * part of the model. Putting it inside would push referential-action vocabulary
+ * into the compiled Contract and the ClientContract, where core has no word for
+ * it, and would move the Contract identity of every schema that has a relation.
+ *
+ * Phase 8 owns the half that makes the facts exist and readable; the core seam
+ * that plans a cascade from them is Phase 9's (S10): `createPrismaAdapter`
+ * translates this table into core's words and states it as the adapter's
+ * `referentialActions`, and core builds the closure from that.
+ */
+export type PrismaReferentialActionTable<M extends PrismaAdapterModel = PrismaAdapterModel> = {
+    readonly [R in keyof M["resources"]]: PrismaResourceReferentialActions;
+};
+/**
+ * T-3.2 — what the generate step emits and the adapter loads.
+ *
+ * **ADR 0009 (Accepted) overrides the plan here: the artifact is one TypeScript
+ * module, not JSON.** `resolveJsonModule` widens `"string"` to `string`, so a
+ * JSON artifact would force a second emitted declaration purely to carry the
+ * literals, and two emissions from one source can drift. One module written
+ * `as const satisfies AdapterModel` makes value and type the same literal, and
+ * makes drift unrepresentable rather than merely detectable.
+ *
+ * It is still passive, serializable, introspectable, hashable and free of
+ * runtime callbacks (C-841): a `.ts` module whose only expression is a frozen
+ * object literal is JSON that carries its own type.
+ *
+ * `M` is the reason this type is generic at all. The emitted module's `model`
+ * is a literal type; if this alias pinned `model` to the general
+ * {@link PrismaAdapterModel}, every resource key and field key would be erased
+ * to `string` on the way to `createPrismaAdapter`, `EffectiveFieldKey` would
+ * degenerate, and core's whole config-typing workstream would buy nothing —
+ * silently, with no compile error anywhere. `model: M` is a bare property
+ * position, which is what makes `M` actually infer at the call site;
+ * `typed-artifact.test-d.ts` is what proves it still does.
+ *
+ * The default keeps the unparameterised spelling meaning what it always meant:
+ * "some Prisma adapter model".
+ */
+export type PrismaDiscoveryArtifact<M extends PrismaAdapterModel = PrismaAdapterModel> = {
+    /** e.g. `"7.10.0"`; only the major is fenced (C-846). */
+    readonly prismaVersion: string;
+    readonly provider: PrismaProvider;
+    /** `sha256:<hex>` of the canonicalized `model` below — and of nothing else. */
+    readonly modelHash: string;
+    readonly model: M;
+    /**
+     * Prisma addressing beside the model, and outside `modelHash` by
+     * construction: see {@link PrismaTranslationTable}.
+     */
+    readonly translation: PrismaTranslationTable<M>;
+    /**
+     * The resolved referential actions, beside the model and outside `modelHash`
+     * on the same construction: see {@link PrismaReferentialActionTable}.
+     *
+     * Direction, because getting it backwards is silent: an entry under resource
+     * `R` says **deleting a `target` row does `onDelete` to rows of `R`**.
+     */
+    readonly referentialActions: PrismaReferentialActionTable<M>;
+};

package/dist/discovery/discovery-artifact.interface.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,59 @@
+import type { EnumDefinition } from "@aventara/core";
+import type { PrismaSchemaEnum } from "./schema-facts.interface.js";
+import type { PrismaDiscoveryDiagnostic } from "./vocabulary.dictionary.js";
+/**
+ * PSL enums → `EnumDefinition` **[CORE]**, and the one line of C-810.
+ *
+ * # Declaration order is semantic, so nothing here sorts
+ *
+ * §19.2 puts enum declaration order among the arrays whose order survives
+ * canonicalization and enters the Contract hash. `definition.values` is therefore
+ * PSL's order, copied — the types are a **cross-check**, not the source, exactly
+ * as T-3.1's `enum values` row says.
+ *
+ * # What a cross-check failure means
+ *
+ * `enums.ts` and `schema.prisma` were read in the same instant by the same
+ * generate step (D-802). If they disagree, one of them is stale, and the answer
+ * is `diverged` — a build stop — rather than a preference for either. The message
+ * prints both orders because "the enum diverged" without them costs the reader a
+ * second investigation.
+ *
+ * # A member-level `@map` never reaches here, from either side
+ *
+ * PSL's reader discards it as bucket 2 (a database name, which Aventara has no
+ * word for), and the generated `enums.ts` writes the member name on *both* sides
+ * of a mapped member — `GAMMA: 'GAMMA'`, not `GAMMA: 'g'` **[RUN8 — 2026-09-28,
+ * prisma 7.10.0]**. So the cross-check compares Aventara identities on both
+ * sides, and the mapper has nothing to resurrect.
+ */
+export type EnumMappingInput = {
+    /** PSL — the source of the values and their order. */
+    readonly declared: PrismaSchemaEnum;
+    /** TYPE — `enums.ts`'s member list, or `undefined` when the 🟢 types omit the enum entirely. */
+    readonly exposed: readonly string[] | undefined;
+};
+export type EnumMappingOutcome = {
+    readonly outcome: "enum";
+    readonly name: string;
+    readonly definition: EnumDefinition;
+} | {
+    readonly outcome: "excluded";
+    readonly diagnostic: PrismaDiscoveryDiagnostic;
+} | {
+    readonly outcome: "diverged";
+    readonly diagnostic: PrismaDiscoveryDiagnostic;
+};
+/**
+ * C-810 made concrete: an enum-backed column projects to a **ScalarField** whose
+ * type ref takes the `enum` arm. The `kind` is a literal `"scalar"`, so a third
+ * structural kind cannot be introduced here without the type changing.
+ */
+export type EnumBackedColumn = {
+    readonly kind: "scalar";
+    readonly type: {
+        readonly enum: string;
+    };
+};
+export declare function mapPrismaEnum(input: EnumMappingInput): EnumMappingOutcome;
+export declare function projectEnumBackedColumn(name: string): EnumBackedColumn;

package/dist/discovery/enum.mapper.js

@@ -0,0 +1,32 @@
+export function mapPrismaEnum(input) {
+    const { declared, exposed } = input;
+    if (exposed === undefined) {
+        return {
+            outcome: "excluded",
+            diagnostic: {
+                code: "not-exposed",
+                message: `enum \`${declared.name}\` is declared in ${declared.site.file}:${declared.site.line} and absent from the generated \`enums.ts\`, so it is omitted rather than projected into a Contract the client cannot name.`,
+            },
+        };
+    }
+    const declaredOrder = declared.values.join(", ");
+    const exposedOrder = exposed.join(", ");
+    if (declaredOrder !== exposedOrder) {
+        return {
+            outcome: "diverged",
+            diagnostic: {
+                code: "enum-diverged",
+                message: `enum \`${declared.name}\` reads [${declaredOrder}] in ${declared.site.file} and [${exposedOrder}] in the generated \`enums.ts\`. Declaration order is semantic (§19.2) and enters the Contract hash, so this is a stale generated client, not a cosmetic difference.`,
+            },
+        };
+    }
+    return {
+        outcome: "enum",
+        name: declared.name,
+        // PSL's order, copied. Never sorted, never taken from the cross-check.
+        definition: { values: [...declared.values] },
+    };
+}
+export function projectEnumBackedColumn(name) {
+    return { kind: "scalar", type: { enum: name } };
+}