@aventara/prisma7-adapter 0.1.0-pilot.0

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

@@ -0,0 +1,244 @@
+import { type AdapterLifecycleTrait, type AdapterRelationField, type AdapterScalarField } from "@aventara/core";
+import type { PrismaResourceSurface } from "./capability-surface.interface.js";
+import type { PrismaAdapterModel, PrismaReferentialAction } from "./discovery-artifact.interface.js";
+import type { PrismaSchemaField, PrismaSchemaUnknown } from "./schema-facts.interface.js";
+import { type PrismaDiscoveryDiagnostic, type PrismaEvidence } from "./vocabulary.dictionary.js";
+/**
+ * Task 4 — one PSL field, answered as an `AdapterScalarField` or an
+ * `AdapterRelationField` (C-808, C-811, C-813).
+ *
+ * # Nullability comes from PSL, and the required `Json` column is why
+ *
+ * `nullable` is `PrismaSchemaField.optional` — PSL's `?` — and **nothing else**
+ * (T-3.1 invariant 4). The type surface cannot answer the question, and the
+ * damage is not hypothetical: `$MetricPayload.scalars.sJson` resolves to
+ * `null | string | number | false | true | JsonObject | JsonArray` while PSL says
+ * `sJson Json`, required, because JSON null is a *value*. The reader's own facts
+ * point the same wrong way — `JsonFilterBase.array_contains` admits `| null` and
+ * `equals` admits `JsonNullValueFilter` on that same required column — so a
+ * plausible "the operands mention null, therefore the column is nullable" rule
+ * is wrong for **every** `Json` field while being right everywhere else. That is
+ * the whole reason this rule is stated as a rule rather than left to taste.
+ *
+ * # The create-optional marker is a cross-check, never a source
+ *
+ * {@link crossCheckCreateOptional} is a separate function that *consumes* this
+ * projection, and the data flows one way only: the marker never reaches
+ * {@link projectPrismaField}. `<M>UncheckedCreateInput`'s `?` is **one bit over
+ * several causes** — `@default(uuid())`, `@default(BRONZE)`, `@default(now())`,
+ * `@updatedAt`, plain nullability, and a scalar list, which needs no value
+ * because the empty list is one — and nothing on the 🟢 surface tells them
+ * apart. Deriving a trait *from* the marker would invert the check into the bug
+ * it exists to catch: it would make the two readers agree by construction and
+ * detect nothing.
+ *
+ * # `@default` is matched, never parsed
+ *
+ * {@link matchPrismaDefault} walks `PRISMA_DEFAULT_TABLE` over the raw argument
+ * text the PSL reader carried across unchanged. B1 deferred this matcher to this
+ * task deliberately: the dictionary owns the data, and the lookup belongs where
+ * a red test can drive it.
+ *
+ * The matcher adds **one** discriminant the dictionary's table does not state,
+ * and it is a shape test rather than a parse: an argument that begins with an
+ * identifier followed by `(` is a *generator form*, and anything else is a
+ * *static value*. Both are `DEFAULTED`; only an unrecognised generator form
+ * records an unknown. Without that split, `tier Tier @default(BRONZE)` — a field
+ * of the Phase 8 schemas — would record an unknown and fail the generate step,
+ * while C-811's own acceptance criteria say `@default("x")` is `["DEFAULTED"]`
+ * with nothing recorded. The test never reads *inside* the argument, so
+ * `dbgenerated("gen_random_uuid()")` remains a key and `"a, b // not a comment"`
+ * remains opaque text.
+ *
+ * # A relation carries four members, and the FK is not one of them
+ *
+ * `target`, `cardinality`, `nullable`, and (from Task 6) `capabilities`. The
+ * `@relation(fields: […], references: […])` scalars are read, used to identify
+ * the FK column and check it against the edge's own optionality, and then
+ * **discarded** (C-813). `@relation`'s *name* is not an Aventara concept either,
+ * and its referential actions are not core's yet, so both travel beside the
+ * projection as {@link PrismaRelationEdge} rather than inside it: pairing is
+ * discovery-internal, and it is **PSL-only** — the name
+ * appears nowhere on the 🟢 surface, so from the types alone `Author` has two
+ * `Author` edges with nothing to pair them.
+ *
+ * # Two failure vocabularies, kept apart
+ *
+ * A **diagnostic** is about the schema: PSL declares a column the 🟢 types do
+ * not expose (C-808's existence gate, whose fatality the generate step decides),
+ * or a Prisma type name in no table. A **throw** is about the readers: the two
+ * sources disagree about a fact they both state, which no schema can cause and
+ * no diagnostic vocabulary describes. The types reader draws the same line.
+ */
+/** A reader-versus-reader disagreement: not a schema problem, and not recoverable. */
+export declare class PrismaFieldProjectionError extends Error {
+    readonly name = "PrismaFieldProjectionError";
+}
+/**
+ * The projection minus `capabilities`, which is Task 6's and is derived from the
+ * capability surface rather than from PSL. `Omit` rather than a restatement, so
+ * the composed field is the core type by construction.
+ */
+export type ProjectedScalarField = Omit<AdapterScalarField<PrismaAdapterModel>, "capabilities">;
+export type ProjectedRelationField = Omit<AdapterRelationField<PrismaAdapterModel>, "capabilities">;
+/**
+ * One relation edge as PSL states it — the pairing evidence and the referential
+ * actions, neither of which the projected field carries.
+ *
+ * # Why the actions ride here and not on `AdapterRelationField`
+ *
+ * `AdapterRelationField` is core's type and its members are C-813's (`target`,
+ * `cardinality`, `nullable`, `capabilities`). Wiring a referential action into
+ * the Contract is a core change and belongs to the task that owns core's
+ * transaction planner, not to discovery. Until then the fact lives where
+ * discovery can state it truthfully.
+ *
+ * # The lookup is inverted, and the edge is shaped so a consumer need not invert
+ *
+ * `onDelete` is declared on the CHILD — `Kid.parent @relation(…, onDelete:
+ * Cascade)` — and fires when the PARENT is deleted. So an edge reads:
+ * **deleting a `target` does `onDelete` to rows of `resource`.** A consumer
+ * asking "what does deleting `X` remove?" filters `target === X && onDelete ===
+ * "cascade"` and reads off `resource`; it does not have to re-derive which side
+ * of a pair declared what.
+ *
+ * `null` on both members means this edge is not the owning side (it declares no
+ * `fields:`), so the actions are on its partner — never that no action applies.
+ */
+export type PrismaRelationEdge = {
+    /** The model DECLARING the edge — the child, where an owning edge is concerned. */
+    readonly resource: string;
+    readonly field: string;
+    /** The model the edge points AT — the parent, whose deletion fires `onDelete`. */
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+    /** `@relation("Name")`, or `null` where PSL wrote none. PSL-only. */
+    readonly relationName: string | null;
+    /**
+     * What deleting a `target` row does to this `resource` row, resolved (an
+     * absent PSL argument already carries Prisma's measured default). `null` on a
+     * non-owning edge.
+     */
+    readonly onDelete: PrismaReferentialAction | null;
+    /** The same for an update of the referenced key. `null` on a non-owning edge. */
+    readonly onUpdate: PrismaReferentialAction | null;
+};
+export type FieldProjectionInput = {
+    readonly resource: string;
+    /** PSL — what the field IS. */
+    readonly field: PrismaSchemaField;
+    /** The model's other fields: the only way to identify an FK scalar by name. */
+    readonly siblings: readonly 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[]>>;
+    /** PSL — the model names, which is what makes a written type name a relation. */
+    readonly models: ReadonlySet<string>;
+};
+export type FieldProjection = {
+    readonly outcome: "scalar";
+    readonly name: string;
+    readonly field: ProjectedScalarField;
+    /** Recorded unknowns; a non-empty list FAILS the generate step (T-3.1 invariant 5). */
+    readonly unknowns: readonly PrismaSchemaUnknown[];
+} | {
+    readonly outcome: "relation";
+    readonly name: string;
+    readonly field: ProjectedRelationField;
+    readonly edge: PrismaRelationEdge;
+} | {
+    readonly outcome: "excluded";
+    readonly diagnostic: PrismaDiscoveryDiagnostic;
+} | {
+    readonly outcome: "unmapped";
+    readonly diagnostic: PrismaDiscoveryDiagnostic;
+};
+export declare function projectPrismaField(input: FieldProjectionInput): FieldProjection;
+export type PrismaDefaultOutcome = 
+/** A row of `PRISMA_DEFAULT_TABLE` matched, and its evidence travels with it. */
+{
+    readonly form: "table";
+    readonly traits: readonly AdapterLifecycleTrait[];
+    readonly evidence: PrismaEvidence;
+}
+/** A static value — a literal, a number, a boolean, an enum member, a list. */
+ | {
+    readonly form: "static";
+    readonly traits: readonly AdapterLifecycleTrait[];
+}
+/** A generator form the table does not carry: `DEFAULTED`, plus a recorded unknown. */
+ | {
+    readonly form: "unrecognised-generator";
+    readonly traits: readonly AdapterLifecycleTrait[];
+};
+/**
+ * T-3.1's `@default` table, looked up — never evaluated. The argument arrives as
+ * opaque text precisely so that this function can be a lookup.
+ */
+export declare function matchPrismaDefault(argument: string): PrismaDefaultOutcome;
+/** Why a field is legitimately optional in `<M>UncheckedCreateInput`. */
+export type CreateOptionalCause = AdapterLifecycleTrait | "nullable"
+/** A scalar list needs no value: the empty list is one. */
+ | "list";
+export type CreateOptionalCrossCheckInput = {
+    readonly resource: string;
+    /**
+     * The **projected** scalar fields — PSL's answers, already computed. Relation
+     * edges are not passed: every edge is optional in a create input regardless of
+     * anything PSL says, so they carry no information for this check.
+     */
+    readonly fields: readonly {
+        readonly name: string;
+        readonly nullable: boolean;
+        readonly list: boolean;
+        readonly lifecycle: readonly AdapterLifecycleTrait[];
+    }[];
+    /** TYPE — `<M>UncheckedCreateInput`'s optional members. */
+    readonly createOptional: readonly string[];
+};
+export type CreateOptionalCrossCheck = {
+    readonly explained: readonly {
+        readonly name: string;
+        readonly cause: CreateOptionalCause;
+    }[];
+    /** Marked optional by the types with nothing in PSL to explain it. */
+    readonly unexplained: readonly string[];
+    readonly messages: readonly string[];
+};
+/**
+ * TYPE's only contribution to lifecycle: a check, run in one direction.
+ *
+ * Every field the 🟢 `<M>UncheckedCreateInput` marks optional must carry a PSL
+ * cause. A field the types mark optional with no cause means **one of the two
+ * readers is wrong** — that is the entire signal, and it is why the marker is
+ * never read as a trait. Names the types mark that this model does not project
+ * as a scalar (relation edges) are skipped rather than reported: their
+ * optionality is structural.
+ */
+export declare function crossCheckCreateOptional(input: CreateOptionalCrossCheckInput): CreateOptionalCrossCheck;
+export type PrismaRelationPair = readonly [
+    PrismaRelationEdge,
+    PrismaRelationEdge
+];
+export type PrismaRelationPairing = {
+    readonly pairs: readonly PrismaRelationPair[];
+    /** Edges nothing pairs: a back-reference the schema never declared, or an ambiguity. */
+    readonly unpaired: readonly PrismaRelationEdge[];
+};
+/**
+ * Pairs each edge with its back-reference, which **only PSL can do**.
+ *
+ * An explicit `@relation("Name")` is the pairing evidence, and for the two
+ * `Author` → `Author` edges it is the *only* evidence: the name appears nowhere
+ * on the 🟢 surface, so from the types alone there are two self-edges and
+ * nothing to say they are one relation.
+ *
+ * Unnamed edges are paired by the unordered model pair, which is unambiguous
+ * because PSL requires a name as soon as two relations connect the same two
+ * models. Where an unordered pair still has more than two edges, they are left
+ * unpaired rather than guessed: the implicit name Prisma would compute lives in
+ * the 🛑 runtime data model, and re-deriving it here would be this module
+ * reimplementing the generator.
+ */
+export declare function pairPrismaRelationEdges(edges: readonly PrismaRelationEdge[]): PrismaRelationPairing;

package/dist/discovery/field.mapper.js

@@ -0,0 +1,387 @@
+import { LIFECYCLE_TRAITS, } from "@aventara/core";
+import { projectEnumBackedColumn } from "./enum.mapper.js";
+import { mapPrismaScalarField } from "./scalar.mapper.js";
+import { PRISMA_DEFAULT_TABLE, PRISMA_UNMATCHED_DEFAULT_TRAITS, } from "./vocabulary.dictionary.js";
+/**
+ * Task 4 — one PSL field, answered as an `AdapterScalarField` or an
+ * `AdapterRelationField` (C-808, C-811, C-813).
+ *
+ * # Nullability comes from PSL, and the required `Json` column is why
+ *
+ * `nullable` is `PrismaSchemaField.optional` — PSL's `?` — and **nothing else**
+ * (T-3.1 invariant 4). The type surface cannot answer the question, and the
+ * damage is not hypothetical: `$MetricPayload.scalars.sJson` resolves to
+ * `null | string | number | false | true | JsonObject | JsonArray` while PSL says
+ * `sJson Json`, required, because JSON null is a *value*. The reader's own facts
+ * point the same wrong way — `JsonFilterBase.array_contains` admits `| null` and
+ * `equals` admits `JsonNullValueFilter` on that same required column — so a
+ * plausible "the operands mention null, therefore the column is nullable" rule
+ * is wrong for **every** `Json` field while being right everywhere else. That is
+ * the whole reason this rule is stated as a rule rather than left to taste.
+ *
+ * # The create-optional marker is a cross-check, never a source
+ *
+ * {@link crossCheckCreateOptional} is a separate function that *consumes* this
+ * projection, and the data flows one way only: the marker never reaches
+ * {@link projectPrismaField}. `<M>UncheckedCreateInput`'s `?` is **one bit over
+ * several causes** — `@default(uuid())`, `@default(BRONZE)`, `@default(now())`,
+ * `@updatedAt`, plain nullability, and a scalar list, which needs no value
+ * because the empty list is one — and nothing on the 🟢 surface tells them
+ * apart. Deriving a trait *from* the marker would invert the check into the bug
+ * it exists to catch: it would make the two readers agree by construction and
+ * detect nothing.
+ *
+ * # `@default` is matched, never parsed
+ *
+ * {@link matchPrismaDefault} walks `PRISMA_DEFAULT_TABLE` over the raw argument
+ * text the PSL reader carried across unchanged. B1 deferred this matcher to this
+ * task deliberately: the dictionary owns the data, and the lookup belongs where
+ * a red test can drive it.
+ *
+ * The matcher adds **one** discriminant the dictionary's table does not state,
+ * and it is a shape test rather than a parse: an argument that begins with an
+ * identifier followed by `(` is a *generator form*, and anything else is a
+ * *static value*. Both are `DEFAULTED`; only an unrecognised generator form
+ * records an unknown. Without that split, `tier Tier @default(BRONZE)` — a field
+ * of the Phase 8 schemas — would record an unknown and fail the generate step,
+ * while C-811's own acceptance criteria say `@default("x")` is `["DEFAULTED"]`
+ * with nothing recorded. The test never reads *inside* the argument, so
+ * `dbgenerated("gen_random_uuid()")` remains a key and `"a, b // not a comment"`
+ * remains opaque text.
+ *
+ * # A relation carries four members, and the FK is not one of them
+ *
+ * `target`, `cardinality`, `nullable`, and (from Task 6) `capabilities`. The
+ * `@relation(fields: […], references: […])` scalars are read, used to identify
+ * the FK column and check it against the edge's own optionality, and then
+ * **discarded** (C-813). `@relation`'s *name* is not an Aventara concept either,
+ * and its referential actions are not core's yet, so both travel beside the
+ * projection as {@link PrismaRelationEdge} rather than inside it: pairing is
+ * discovery-internal, and it is **PSL-only** — the name
+ * appears nowhere on the 🟢 surface, so from the types alone `Author` has two
+ * `Author` edges with nothing to pair them.
+ *
+ * # Two failure vocabularies, kept apart
+ *
+ * A **diagnostic** is about the schema: PSL declares a column the 🟢 types do
+ * not expose (C-808's existence gate, whose fatality the generate step decides),
+ * or a Prisma type name in no table. A **throw** is about the readers: the two
+ * sources disagree about a fact they both state, which no schema can cause and
+ * no diagnostic vocabulary describes. The types reader draws the same line.
+ */
+/** A reader-versus-reader disagreement: not a schema problem, and not recoverable. */
+export class PrismaFieldProjectionError extends Error {
+    name = "PrismaFieldProjectionError";
+}
+export function projectPrismaField(input) {
+    return input.models.has(input.field.type)
+        ? projectRelationField(input)
+        : projectScalarField(input);
+}
+/* ------------------------------------------------------------------ *
+ * Scalars                                                            *
+ * ------------------------------------------------------------------ */
+function projectScalarField(input) {
+    const { resource, field, surface, enums } = input;
+    const mapped = mapPrismaScalarField({ resource, field, surface, enums });
+    if (mapped.outcome === "excluded" || mapped.outcome === "unmapped") {
+        // The existence gate and the unmapped-type diagnostic are the scalar
+        // mapper's own answers, forwarded whole: restating them here would be a
+        // second wording of one decision.
+        return mapped;
+    }
+    const exposed = surface.scalarFields[field.name];
+    if (exposed === undefined) {
+        throw new PrismaFieldProjectionError(`${resource}.${field.name} passed the existence gate and has no scalar surface`);
+    }
+    assertTokenAgrees(resource, field, exposed.token);
+    const lifecycle = projectLifecycle(resource, field);
+    const type = mapped.outcome === "enum"
+        ? projectEnumBackedColumn(mapped.enum).type
+        : { scalar: mapped.mapping.scalar };
+    const format = mapped.outcome === "scalar" ? mapped.mapping.format : undefined;
+    return {
+        outcome: "scalar",
+        name: field.name,
+        field: {
+            kind: "scalar",
+            type,
+            ...(format === undefined ? {} : { format }),
+            // PSL's `?`, and nothing else (T-3.1 invariant 4).
+            nullable: field.optional,
+            list: field.list,
+            lifecycle: lifecycle.traits,
+        },
+        unknowns: lifecycle.unknowns,
+    };
+}
+/**
+ * The `FieldRef` token against the written PSL type.
+ *
+ * **A token carries its list suffix** — `Post.tags` reads as `String[]`, not
+ * `String` — so the suffix is split off before the names are compared and is
+ * then the TYPE half of `list`. Comparing the raw token to the PSL type name
+ * would make every list field look like a type mismatch, and a provider-drop
+ * check built on that would fire on a field that is present.
+ */
+function assertTokenAgrees(resource, field, token) {
+    const listed = token.endsWith("[]");
+    const base = listed ? token.slice(0, -2) : token;
+    if (base !== field.type) {
+        throw new PrismaFieldProjectionError(`${resource}.${field.name} is written \`${field.type}\` in schema.prisma and the 🟢 types carry the FieldRef token \`${token}\`. The two readers describe one instant, so this is a stale generated client or a reader defect, not a schema the adapter can translate.`);
+    }
+    if (listed !== field.list) {
+        throw new PrismaFieldProjectionError(`${resource}.${field.name} is ${field.list ? "a list" : "not a list"} in schema.prisma and the 🟢 types carry the FieldRef token \`${token}\`, which says the opposite.`);
+    }
+}
+/* ------------------------------------------------------------------ *
+ * Lifecycle (C-811)                                                  *
+ * ------------------------------------------------------------------ */
+/**
+ * The three adapter traits in core's own declaration order, so a trait list has
+ * one canonical order and it is not this module's invention. Order is semantic:
+ * it enters the Contract hash.
+ */
+const ADAPTER_TRAIT_ORDER = LIFECYCLE_TRAITS.filter((trait) => trait === "DEFAULTED" ||
+    trait === "GENERATED_ON_CREATE" ||
+    trait === "GENERATED_ON_UPDATE");
+/** An argument that begins with an identifier and an open paren: a generator form. */
+const GENERATOR_FORM = /^[A-Za-z_][A-Za-z0-9_]*\(/;
+/**
+ * T-3.1's `@default` table, looked up — never evaluated. The argument arrives as
+ * opaque text precisely so that this function can be a lookup.
+ */
+export function matchPrismaDefault(argument) {
+    for (const row of PRISMA_DEFAULT_TABLE) {
+        const matched = "literal" in row.match
+            ? row.match.literal === argument
+            : row.match.pattern.test(argument);
+        if (matched) {
+            return { form: "table", traits: row.traits, evidence: row.evidence };
+        }
+    }
+    return GENERATOR_FORM.test(argument)
+        ? {
+            form: "unrecognised-generator",
+            traits: PRISMA_UNMATCHED_DEFAULT_TRAITS,
+        }
+        : { form: "static", traits: PRISMA_UNMATCHED_DEFAULT_TRAITS };
+}
+function projectLifecycle(resource, field) {
+    const present = new Set();
+    const unknowns = [];
+    if (field.defaultArgument !== null) {
+        const outcome = matchPrismaDefault(field.defaultArgument);
+        for (const trait of outcome.traits) {
+            present.add(trait);
+        }
+        if (outcome.form === "unrecognised-generator") {
+            // Recorded as the same `PrismaSchemaUnknown` the PSL reader records, so
+            // it fails the generate step by construction rather than through a second
+            // rule written for it. An unrecognised generator function is a build stop,
+            // not a column Aventara quietly decides the client must supply.
+            unknowns.push({
+                kind: "attribute-argument",
+                spelling: "@default",
+                text: field.defaultArgument,
+                block: resource,
+                site: field.site,
+            });
+        }
+    }
+    if (field.updatedAt) {
+        present.add("GENERATED_ON_UPDATE");
+    }
+    return {
+        traits: ADAPTER_TRAIT_ORDER.filter((trait) => present.has(trait)),
+        unknowns,
+    };
+}
+/**
+ * TYPE's only contribution to lifecycle: a check, run in one direction.
+ *
+ * Every field the 🟢 `<M>UncheckedCreateInput` marks optional must carry a PSL
+ * cause. A field the types mark optional with no cause means **one of the two
+ * readers is wrong** — that is the entire signal, and it is why the marker is
+ * never read as a trait. Names the types mark that this model does not project
+ * as a scalar (relation edges) are skipped rather than reported: their
+ * optionality is structural.
+ */
+export function crossCheckCreateOptional(input) {
+    const byName = new Map(input.fields.map((field) => [field.name, field]));
+    const explained = [];
+    const unexplained = [];
+    const messages = [];
+    for (const name of input.createOptional) {
+        const projected = byName.get(name);
+        if (projected === undefined) {
+            continue;
+        }
+        const cause = causeOf(projected);
+        if (cause === null) {
+            unexplained.push(name);
+            messages.push(`\`${input.resource}.${name}\` is optional in the generated \`${input.resource}UncheckedCreateInput\` and schema.prisma gives no reason: it carries no \`@default\`, no \`@updatedAt\`, no \`?\` and no \`[]\`. The marker is one bit over several causes and is never read as a trait, so a field optional in the types with none of them in PSL means one of the two readers is wrong.`);
+            continue;
+        }
+        explained.push({ name, cause });
+    }
+    return { explained, unexplained, messages };
+}
+function causeOf(projected) {
+    // Lifecycle first, in core's order, so a field with both a default and a
+    // nullable column reports the stronger cause.
+    const trait = ADAPTER_TRAIT_ORDER.filter((candidate) => projected.lifecycle.includes(candidate));
+    // `GENERATED_ON_CREATE` outranks the `DEFAULTED` that always accompanies it:
+    // it is the more specific reason the client may omit the value.
+    const strongest = trait.includes("GENERATED_ON_CREATE")
+        ? "GENERATED_ON_CREATE"
+        : trait[0];
+    if (strongest !== undefined) {
+        return strongest;
+    }
+    if (projected.nullable) {
+        return "nullable";
+    }
+    return projected.list ? "list" : null;
+}
+/* ------------------------------------------------------------------ *
+ * Relations (C-813)                                                  *
+ * ------------------------------------------------------------------ */
+function projectRelationField(input) {
+    const { resource, field, siblings, surface } = input;
+    const column = `${resource}.${field.name}`;
+    const exposed = surface.relationFields[field.name];
+    if (exposed === undefined) {
+        return {
+            outcome: "excluded",
+            diagnostic: {
+                code: "not-exposed",
+                message: `${column} is declared in schema.prisma as an edge to \`${field.type}\` and absent from the generated 🟢 types, so it is omitted: ${field.ignored ? "it carries `@ignore`" : "no schema attribute explains it — a provider drop or a preview-feature exclusion"}.`,
+            },
+        };
+    }
+    const cardinality = field.list ? "many" : "one";
+    // A to-many edge is a collection, and an absent collection is an empty one:
+    // never nullable. A to-one edge is nullable exactly where PSL wrote `?`.
+    const nullable = cardinality === "many" ? false : field.optional;
+    // TYPE is the cross-check, from `$<M>Payload.objects`: `mentor:
+    // $AuthorPayload | null`, `mentees: $AuthorPayload[]`.
+    if (exposed.many !== field.list) {
+        throw new PrismaFieldProjectionError(`${column} is ${field.list ? "a list" : "a single edge"} in schema.prisma and the 🟢 payload says the opposite.`);
+    }
+    if (exposed.nullable !== nullable) {
+        throw new PrismaFieldProjectionError(`${column} is ${nullable ? "optional" : "required"} in schema.prisma and the 🟢 payload ${exposed.nullable ? "admits" : "refuses"} \`null\`.`);
+    }
+    if (exposed.target !== field.type) {
+        throw new PrismaFieldProjectionError(`${column} targets \`${field.type}\` in schema.prisma and \`${exposed.target}\` on the 🟢 payload.`);
+    }
+    assertForeignKeyAgrees(column, field, siblings, nullable);
+    return {
+        outcome: "relation",
+        name: field.name,
+        // Four members. No target field schema, no FK, no join-table name, no
+        // owning-side metadata (C-813).
+        field: {
+            kind: "relation",
+            target: field.type,
+            cardinality,
+            nullable,
+        },
+        edge: {
+            resource,
+            field: field.name,
+            target: field.type,
+            cardinality,
+            relationName: field.relation?.name ?? null,
+            // Carried, not projected: the action changes what a delete DOES, so it
+            // is evidence a transaction planner needs, and it is not a member of
+            // `AdapterRelationField` (see the edge's own doc).
+            onDelete: field.relation?.onDelete ?? null,
+            onUpdate: field.relation?.onUpdate ?? null,
+        },
+    };
+}
+/**
+ * The FK, read and then discarded.
+ *
+ * `fields: […]` is used for exactly two things, both of them checks: each named
+ * scalar must be a column this model declares, and an **optional FK forces an
+ * optional edge**. PSL enforces the second itself — `prisma validate` 7.10.0
+ * answers *"The relation field `author` uses the scalar fields authorId. At
+ * least one of those fields is optional. Hence the relation field must be
+ * optional as well."* — so a violation can only come from a reader defect.
+ *
+ * The converse does **not** hold, and assuming it would be wrong: `mentor
+ * Author? @relation(fields: [mentorId])` with `mentorId String` **required** is
+ * valid PSL at 7.10.0 and its client still types `mentor: $AuthorPayload |
+ * null`. So the FK is not the source of nullability — the edge's own `?` is.
+ *
+ * Nothing about the FK enters the projection.
+ */
+function assertForeignKeyAgrees(column, field, siblings, nullable) {
+    for (const name of field.relation?.fields ?? []) {
+        const scalar = siblings.find((sibling) => sibling.name === name);
+        if (scalar === undefined) {
+            throw new PrismaFieldProjectionError(`${column} names \`${name}\` in \`@relation(fields: …)\` and the model declares no such column.`);
+        }
+        if (scalar.optional && !nullable) {
+            throw new PrismaFieldProjectionError(`${column} is required and its foreign key \`${name}\` is optional. PSL forbids this combination, so the schema cannot have said it: one of the readers is wrong.`);
+        }
+    }
+}
+/**
+ * Pairs each edge with its back-reference, which **only PSL can do**.
+ *
+ * An explicit `@relation("Name")` is the pairing evidence, and for the two
+ * `Author` → `Author` edges it is the *only* evidence: the name appears nowhere
+ * on the 🟢 surface, so from the types alone there are two self-edges and
+ * nothing to say they are one relation.
+ *
+ * Unnamed edges are paired by the unordered model pair, which is unambiguous
+ * because PSL requires a name as soon as two relations connect the same two
+ * models. Where an unordered pair still has more than two edges, they are left
+ * unpaired rather than guessed: the implicit name Prisma would compute lives in
+ * the 🛑 runtime data model, and re-deriving it here would be this module
+ * reimplementing the generator.
+ */
+export function pairPrismaRelationEdges(edges) {
+    const groups = new Map();
+    for (const edge of edges) {
+        const key = edge.relationName === null
+            ? `implicit:${[edge.resource, edge.target].sort().join("<->")}`
+            : `named:${edge.relationName}`;
+        const group = groups.get(key);
+        if (group === undefined) {
+            groups.set(key, [edge]);
+        }
+        else {
+            group.push(edge);
+        }
+    }
+    const pairs = [];
+    const unpaired = [];
+    for (const group of [...groups.keys()].sort().map((key) => groups.get(key))) {
+        const [first, second, ...rest] = group ?? [];
+        if (first === undefined) {
+            continue;
+        }
+        if (second === undefined || rest.length > 0) {
+            unpaired.push(...(group ?? []));
+            continue;
+        }
+        if (first.resource !== second.target || first.target !== second.resource) {
+            unpaired.push(first, second);
+            continue;
+        }
+        pairs.push(sortKey(first) <= sortKey(second) ? [first, second] : [second, first]);
+    }
+    // Sorted by the first edge, so the answer's order is a property of the model
+    // and not of how the groups happened to be keyed.
+    return {
+        pairs: [...pairs].sort((left, right) => sortKey(left[0]).localeCompare(sortKey(right[0]))),
+        unpaired,
+    };
+}
+function sortKey(edge) {
+    return `${edge.resource}.${edge.field}`;
+}