@aventara/prisma7-adapter 0.1.0-pilot.0

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

@@ -0,0 +1,188 @@
+import type { PrismaIdentifierAddress } from "./discovery-artifact.interface.js";
+import type { PrismaSchemaBlockIdentifier, PrismaSchemaModel } from "./schema-facts.interface.js";
+/**
+ * PSL uniqueness → `AdapterIdentifier` tuples **[CORE]**: C-814 and C-815.
+ *
+ * # Why identity comes from PSL
+ *
+ * Because the generated types cannot state it. Measured on 2026-09-28 against
+ * prisma 7.10.0, on a two-model scratch client generated for this purpose:
+ *
+ * ```prisma
+ * model Delta   { code String @unique  name String }
+ * model Epsilon { code String @id      name String }
+ * ```
+ *
+ * `models/Delta.ts` and `models/Epsilon.ts` are **byte-identical** — equal
+ * md5 after a case-insensitive `Delta|delta → MODEL|model` substitution and
+ * after removing one 4-line `StringFieldUpdateOperationsInput` block, which is
+ * the generator's first-file-wins dedup of a shared input type and lands in
+ * whichever model file sorts first. Both declare their `AtLeast` key set as
+ * `}, "code">` on the same line. A grep for `primaryKey|isId|isUnique` over
+ * the 🟢 files of that client and of **both** Phase 8 clients is empty — not
+ * only over the 🟢 files: over the whole generated tree, `internal/`
+ * included.
+ *
+ * So `@id` and `@unique` are the same fact to TYPE, and a compound `@@id` is
+ * the same fact as a compound `@@unique`. PSL is the only source that
+ * distinguishes them.
+ *
+ * # Why that negative costs the model nothing
+ *
+ * `AdapterResource.identifiers` is `readonly AdapterIdentifier<TFields>[]`
+ * **[CORE]** — an **unmarked set** of non-empty scalar field tuples with no
+ * primary/secondary distinction. Aventara never asks which identifier is the
+ * primary key, so a source that cannot tell `@id` from `@unique` withholds
+ * nothing this mapper needs.
+ *
+ * # The types are a cross-check, and a one-sided one
+ *
+ * `PrismaResourceSurface.uniqueKeys` — `AtLeast<…, K>`'s key union — is
+ * checked two-directionally and never read as a source (C-814): every
+ * identifier's **stored** key must appear among the keys, and every key with no
+ * identifier behind it must be explained by C-815 and by nothing else. Stored,
+ * not re-derived: matching a key computed as `members.join("_")` is what used to
+ * refuse a schema carrying `@@unique(…, name: "X")`, whose surface key is `X`.
+ * Equality is unsatisfiable by construction, because C-815 omits a criterion
+ * the generator still emits a key for. Measured: `Author` has three keys
+ * (`"id" | "email" | "tenantId_handle"`, identical on both engines) and two
+ * identifiers.
+ *
+ * What the two directions do **not** catch is this mapper keeping a criterion
+ * C-815 rejects: an extra identifier only removes a key from the explained
+ * set, so both directions still pass. Measured on 2026-09-28 — a build of this
+ * mapper without the C-815 branch passes the cross-check on all eight
+ * model/engine pairs. The cross-check guards the two readers against each
+ * other; C-815 is pinned by its own cases.
+ *
+ * Its key **ORDERING is not used at all**. It appears to list the primary key
+ * first, but that is an undocumented generator artifact, it is ordering inside
+ * a union — which TypeScript does not preserve semantically — and it
+ * degenerates completely when a model has exactly one unique criterion, the
+ * common case. Nothing here may start depending on it.
+ *
+ * # Nothing here sorts
+ *
+ * Member order is the attribute's list as written, never the field declaration
+ * order (`@@unique([y, x])` is `["y", "x"]` even where `x` is declared first),
+ * and the identifiers themselves come out in PSL's own order: field-level
+ * criteria in field declaration order, then `@@id`, then `@@unique` as
+ * written. Order enters the Contract hash (§19.2), so a deterministic order
+ * derived from PSL is the point, not a convenience.
+ */
+/** Which PSL spelling a criterion came from. Reported, and never used to rank one. */
+export type PrismaIdentifierSource = "@id" | "@unique" | "@@id" | "@@unique";
+/** One uniqueness criterion as PSL states it, before C-815 is applied. */
+export type PrismaUniquenessCriterion = {
+    readonly source: PrismaIdentifierSource;
+    /** Member order as written in the attribute's list. Never sorted. */
+    readonly members: readonly string[];
+    /**
+     * The Prisma addressing key for this criterion — {@link prismaUniqueInputKey}
+     * over the PSL facts, computed once here.
+     *
+     * Carried by the OMISSIONS too, and not only by the usable identifiers,
+     * because the TYPE cross-check's second direction matches an `AtLeast` key
+     * against the omission that explains it: a named criterion C-815 rejects is
+     * keyed by its name on the generated surface, so an omission without its key
+     * would leave that key unexplained and fail a schema Prisma accepts.
+     */
+    readonly key: string;
+};
+/**
+ * A criterion that is NOT a usable identifier, recorded with its reason.
+ *
+ * Recorded rather than dropped for two independent reasons: C-814 requires the
+ * omission to be reported, and the TYPE cross-check needs it — the generator
+ * emits an `AtLeast` key for a criterion C-815 rejects, and an unrecorded
+ * omission would leave that key unexplained and indistinguishable from a
+ * reader bug.
+ *
+ * A discriminated union, because the arms carry different evidence: which
+ * members are nullable is not the same fact as which members are not scalar
+ * columns at all.
+ *
+ * These are not `PrismaDiscoveryDiagnostic`s. A diagnostic carries prose for
+ * an engineer; the cross-check needs the member names as data.
+ */
+export type PrismaIdentifierOmission = PrismaUniquenessCriterion & ({
+    /** C-815: SQL uniqueness does not constrain NULLs. */
+    readonly reason: "nullable-participant";
+    readonly nullableMembers: readonly string[];
+} | {
+    /**
+     * A member that is not a scalar column this adapter can name: absent
+     * from the model, a relation field, a list, or `@ignore`d out of the
+     * generated client. Valid PSL cannot produce the first three; `@ignore`
+     * can, and keeping it would emit an identifier over a key no
+     * `AdapterFieldMap` carries.
+     */
+    readonly reason: "unresolved-participant";
+    readonly unresolvedMembers: readonly string[];
+} | {
+    /** An empty member list: `AdapterIdentifier` is non-empty by type. */
+    readonly reason: "no-participants";
+});
+/**
+ * What one model's identity reads as: the usable criteria, each as the tuple
+ * core consumes **paired with** the Prisma key that addresses it, and why the
+ * rest are not usable.
+ *
+ * One list, two projections, which is the reason the pair is not split here:
+ * the composer takes `.members` for `AdapterResource.identifiers` (model
+ * content, hashed, Contract-bound) and the whole address for the artifact's
+ * translation table (adapter-private, unhashed). Two parallel lists would have
+ * to be kept in step; these cannot drift because they are one.
+ *
+ * `PrismaIdentifierAddress.members` is derived from `AdapterResource`, so a
+ * change in core's identifier type reaches this mapper as a compile error.
+ * Discovery is where the field map is being **built**, so the abstract form is
+ * what applies — `AdapterScalarFieldKey` widens to `string` through
+ * `AdapterFieldMap<M>`, making an identifier here a non-empty tuple of field
+ * names. The concrete keys are pinned later, in the emitted artifact
+ * (`PrismaDiscoveryArtifact<M>`).
+ */
+export type PrismaIdentifierMapping = {
+    readonly identifiers: readonly PrismaIdentifierAddress[];
+    readonly omitted: readonly PrismaIdentifierOmission[];
+};
+/**
+ * The Prisma addressing key for a uniqueness criterion: the key a
+ * `WhereUniqueInput` accepts, and the key the generated `AtLeast<…, K>` union
+ * lists.
+ *
+ * Computed **once**, here, at generate time — the architect's decision on
+ * 2026-09-29: *"store it, less processing and less room for drifting."* Runtime
+ * matches the stored key and never re-derives it.
+ *
+ * The rule, measured at 7.10.0 (regenerated 2026-09-29 over five models):
+ *
+ * | criterion                          | key       | wraps |
+ * | ---------------------------------- | --------- | ----- |
+ * | `id String @id` / `@unique`        | `id`      | no    |
+ * | `@@unique([b, a])`                 | `b_a`     | yes   |
+ * | `@@id([a, b])`                     | `a_b`     | yes   |
+ * | `@@unique([b, a], name: "altKey")` | `altKey`  | yes   |
+ * | `@@id([a, b], name: "pk")`         | `pk`      | yes   |
+ * | any of the above, `map: "…"`       | unchanged | —     |
+ *
+ * Two of those rows are why this is a function of the PSL facts and not of the
+ * members alone. A custom `name:` **replaces** the positional alias rather than
+ * adding to it, so `members.join("_")` is simply wrong for a named criterion —
+ * which is precisely what made the cross-check refuse a schema Prisma accepts,
+ * reporting a correctly-discovered identifier as an invented constraint (fixed
+ * 2026-09-29; `map:` stays invisible and stays discarded).
+ *
+ * What this key is **not** is part of the identifier. `AdapterIdentifier` is a
+ * tuple of field names with nowhere to put a name (C-814), and this key lives in
+ * the artifact's translation table beside the model, never in it.
+ */
+export declare function prismaUniqueInputKey(uniqueness: PrismaSchemaBlockIdentifier): string;
+/**
+ * One model's identity, read from PSL alone.
+ *
+ * A pure function of plain data: no generated client, no `@prisma/client`
+ * import, and no TYPE input — which is what lets the cross-check be an
+ * independent second opinion rather than a tautology.
+ */
+export declare function mapPrismaIdentifiers(model: PrismaSchemaModel): PrismaIdentifierMapping;

package/dist/discovery/identifier.mapper.js

@@ -0,0 +1,132 @@
+/**
+ * The Prisma addressing key for a uniqueness criterion: the key a
+ * `WhereUniqueInput` accepts, and the key the generated `AtLeast<…, K>` union
+ * lists.
+ *
+ * Computed **once**, here, at generate time — the architect's decision on
+ * 2026-09-29: *"store it, less processing and less room for drifting."* Runtime
+ * matches the stored key and never re-derives it.
+ *
+ * The rule, measured at 7.10.0 (regenerated 2026-09-29 over five models):
+ *
+ * | criterion                          | key       | wraps |
+ * | ---------------------------------- | --------- | ----- |
+ * | `id String @id` / `@unique`        | `id`      | no    |
+ * | `@@unique([b, a])`                 | `b_a`     | yes   |
+ * | `@@id([a, b])`                     | `a_b`     | yes   |
+ * | `@@unique([b, a], name: "altKey")` | `altKey`  | yes   |
+ * | `@@id([a, b], name: "pk")`         | `pk`      | yes   |
+ * | any of the above, `map: "…"`       | unchanged | —     |
+ *
+ * Two of those rows are why this is a function of the PSL facts and not of the
+ * members alone. A custom `name:` **replaces** the positional alias rather than
+ * adding to it, so `members.join("_")` is simply wrong for a named criterion —
+ * which is precisely what made the cross-check refuse a schema Prisma accepts,
+ * reporting a correctly-discovered identifier as an invented constraint (fixed
+ * 2026-09-29; `map:` stays invisible and stays discarded).
+ *
+ * What this key is **not** is part of the identifier. `AdapterIdentifier` is a
+ * tuple of field names with nowhere to put a name (C-814), and this key lives in
+ * the artifact's translation table beside the model, never in it.
+ */
+export function prismaUniqueInputKey(uniqueness) {
+    return uniqueness.name ?? uniqueness.members.join("_");
+}
+/**
+ * Every uniqueness criterion PSL states, in PSL's own order. A field spelled
+ * `@id @unique` yields two criteria with the same key; the caller keeps the
+ * first, so `@id` wins and one column does not become two identifiers.
+ */
+function* uniquenessCriteria(model) {
+    const criterion = (source, uniqueness) => ({
+        source,
+        members: uniqueness.members,
+        key: prismaUniqueInputKey(uniqueness),
+    });
+    for (const field of model.fields) {
+        // A field-level criterion has no `name:` to carry: PSL gives `@id` and
+        // `@unique` no such argument, and Prisma keys them by the column.
+        if (field.id) {
+            yield criterion("@id", { members: [field.name], name: null });
+        }
+        if (field.unique) {
+            yield criterion("@unique", { members: [field.name], name: null });
+        }
+    }
+    if (model.blockId !== null) {
+        yield criterion("@@id", model.blockId);
+    }
+    for (const blockUnique of model.blockUniques) {
+        yield criterion("@@unique", blockUnique);
+    }
+}
+/**
+ * One model's identity, read from PSL alone.
+ *
+ * A pure function of plain data: no generated client, no `@prisma/client`
+ * import, and no TYPE input — which is what lets the cross-check be an
+ * independent second opinion rather than a tautology.
+ */
+export function mapPrismaIdentifiers(model) {
+    // The scalar columns this adapter can actually name: a relation field, a list
+    // and an `@ignore`d column are all keys no `AdapterFieldMap` will carry.
+    const columns = new Map();
+    for (const field of model.fields) {
+        if (field.relation !== null || field.list || field.ignored) {
+            continue;
+        }
+        columns.set(field.name, field);
+    }
+    const identifiers = [];
+    const omitted = [];
+    // Deduplication is on the MEMBER TUPLE, not on the addressing key: the tuple
+    // is what `@id @unique` duplicates, and it identifies a criterion injectively,
+    // while a key does not — a custom `name:` can collide with a field name, and
+    // keying the seen-set would then silently drop a different criterion.
+    const seen = new Set();
+    for (const criterion of uniquenessCriteria(model)) {
+        const tuple = JSON.stringify(criterion.members);
+        if (seen.has(tuple)) {
+            continue;
+        }
+        seen.add(tuple);
+        const [head, ...tail] = criterion.members;
+        if (head === undefined) {
+            omitted.push({ ...criterion, reason: "no-participants" });
+            continue;
+        }
+        const unresolvedMembers = criterion.members.filter((member) => !columns.has(member));
+        if (unresolvedMembers.length > 0) {
+            omitted.push({
+                ...criterion,
+                reason: "unresolved-participant",
+                unresolvedMembers,
+            });
+            continue;
+        }
+        // C-815. SQL uniqueness does not constrain NULLs, so a criterion with any
+        // nullable participant does not guarantee AT MOST ONE row and is not an
+        // `Identifier`. Recorded, never dropped: the generator still emits an
+        // `AtLeast` key for it, and the TYPE cross-check needs the omission to
+        // explain that key.
+        //
+        // C-815 is typed a Derived Decision because no source states it. Prisma
+        // states the same rule from its own side, which is the nearest thing to a
+        // source there is: a model whose ONLY criterion has a nullable participant
+        // is rejected at validate time with P1012, "Each model must have at least
+        // one unique criteria that has only required fields … The following unique
+        // criterias were not considered as they contain fields that are not
+        // required: - a, b" (7.10.0, measured 2026-09-28).
+        const nullableMembers = criterion.members.filter((member) => columns.get(member)?.optional === true);
+        if (nullableMembers.length > 0) {
+            omitted.push({
+                ...criterion,
+                reason: "nullable-participant",
+                nullableMembers,
+            });
+            continue;
+        }
+        identifiers.push({ members: [head, ...tail], key: criterion.key });
+    }
+    return { identifiers, omitted };
+}

package/dist/discovery/model.discoverer.d.ts

@@ -0,0 +1,108 @@
+import { type TransactionCapability } from "@aventara/core";
+import type { PrismaComposedArtifact, PrismaModelComposer } from "../generate/prisma.generate.js";
+import type { PrismaCapabilitySurface } from "./capability-surface.interface.js";
+import type { PrismaSchemaFacts } from "./schema-facts.interface.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 declare class PrismaModelCompositionError extends Error {
+    readonly name = "PrismaModelCompositionError";
+    readonly diagnostics: readonly string[];
+    constructor(diagnostics: readonly string[]);
+}
+export type PrismaModelCompositionOptions = {
+    /**
+     * The driver's transaction capability (T-2). The ONLY declared fact
+     * composition accepts, and deliberately not the whole profile: a
+     * `PrismaProviderProfile` carries `provider`.
+     */
+    readonly transactions: TransactionCapability;
+};
+export type PrismaModelDiscoveryInput = PrismaModelCompositionOptions & {
+    /** PSL — what the schema says. */
+    readonly facts: PrismaSchemaFacts;
+    /** TYPE — what this client can do. */
+    readonly surface: PrismaCapabilitySurface;
+    /** Resource names the existence gate admitted, in PSL declaration order. */
+    readonly admitted: readonly string[];
+};
+/**
+ * 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 declare function createPrismaModelComposer(options: PrismaModelCompositionOptions): PrismaModelComposer;
+export declare function discoverPrismaModel(input: PrismaModelDiscoveryInput): PrismaComposedArtifact;