@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/generate/prisma.generate.js

@@ -0,0 +1,278 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import ts from "typescript";
+import { computeModelHash } from "../discovery/artifact.loader.js";
+import { readPrismaSchema } from "../discovery/schema.reader.js";
+import { readPrismaCapabilitySurface } from "../discovery/types.reader.js";
+import { emitDiscoveryArtifactModule } from "./artifact.emitter.js";
+import { readDeclaredSupport } from "./declared-support.reader.js";
+import { applyExistenceGate } from "./existence.gate.js";
+import { resolvePrismaCli } from "./prisma-cli.resolver.js";
+import { crossCheckReaders, describeReaderFindings, } from "./reader-crosscheck.js";
+/**
+ * Task 3 — the adapter's **generate step**: a devDependency-only executable and
+ * the only module that runs `prisma` or spawns a process. Nothing under
+ * `execution/`, and nothing in `discovery/artifact.loader.ts`, imports it; the
+ * package's build `exclude` keeps `src/generate/**` out of `dist` entirely, so
+ * a deployed application never carries `typescript`, a PSL reader or a child
+ * process.
+ *
+ * **The order is fixed, and each step earns its place:**
+ *
+ * 1. **The pinned `prisma` major** (C-846). PSL's grammar and the generated
+ *    client's shape are version-bound; a major this reader has never seen must
+ *    stop the build rather than produce a wrong `AdapterModel` from a grammar
+ *    nobody read.
+ * 2. **`@prisma/client/runtime/client` resolves** (§1.2 item 16). This one is
+ *    first among equals, because its failure is *silent*: every generated file
+ *    opens `// @ts-nocheck`, so with the runtime unresolvable a TypeScript
+ *    program over the generated tree reports **zero** diagnostics while
+ *    `FieldRef` degrades to its uninstantiated form and `JsonValue` stops being
+ *    a union — flipping a types-derived nullability from `true` to `false` with
+ *    nothing anywhere to say so **[RUN8]**. The guard is therefore a module
+ *    *resolution*, never a diagnostic count: a diagnostic count is exactly the
+ *    instrument that reads clean in this failure.
+ * 3. **`prisma generate`**, run by this step itself. The two sources must
+ *    describe one instant; a client generated by some earlier command may
+ *    describe an older schema, and nothing downstream could tell.
+ * 4. **Both sources read in that same run** — PSL for the semantic model, the
+ *    🟢 generated types for the capability surface and for existence.
+ * 5. **The structural checks, in that order.** The existence gate first (T-3.1
+ *    invariant 3), because it decides *which* entities exist and a cross-check
+ *    of an entity nobody admitted is noise; then the reader-versus-reader
+ *    cross-check (`reader-crosscheck.ts`), which answers the reverse direction
+ *    the gate hands it and every other fact both sources carry. Its findings
+ *    stop the step; its two documented exemptions are reported and carried out
+ *    on the result.
+ * 6. **Emit** one TypeScript module (ADR 0009).
+ *
+ * The plan's §9 sketch puts the runtime check *after* `prisma generate`; the
+ * order above is the brief's, and it is the better one — module resolution
+ * walks `node_modules` upward from the client directory and does not need the
+ * directory populated, so nothing is gained by generating output first that the
+ * step is about to refuse to read.
+ *
+ * **The two readers fail differently, and the step keeps them different.** A
+ * PSL `unhandled` entry means *I located a token I do not model*: there is a
+ * construct, a spelling and a site to report, so they are aggregated and
+ * reported together. A types-reader failure means *I cannot read the surface at
+ * all*: there is nothing to record, so it throws. Inventing an `unhandled`
+ * vocabulary for the type surface would be a second parallel representation of
+ * "something went wrong" for no gain.
+ */
+/** The `prisma` major this reader's grammar was written against (C-846). */
+export const PINNED_PRISMA_MAJOR = 7;
+export class PrismaGenerateStepError extends Error {
+    name = "PrismaGenerateStepError";
+}
+const run = promisify(execFile);
+/**
+ * The Prisma CLI this step runs, chosen as D11 states (`prisma-cli.resolver.ts`):
+ * `@prisma/prisma7`'s `prisma7` when it is installed, else `prisma` when its
+ * version is in the adapter's declared range, else a refusal naming both. Looked
+ * up from this package — where an optional peer is linked — and then from the
+ * project the step runs in.
+ */
+export function resolveInstalledPrismaCli() {
+    const resolution = resolvePrismaCli({
+        searchFrom: [import.meta.url, path.join(process.cwd(), "package.json")],
+        range: readDeclaredSupport().prisma,
+    });
+    if (resolution.kind === "refused") {
+        throw new PrismaGenerateStepError(resolution.reason);
+    }
+    return resolution.cli;
+}
+/**
+ * The version fence's input: the version of the Prisma CLI this step runs, which
+ * is the tool that produces the client and the grammar the PSL reader was
+ * written against. (`@prisma/client`'s version is a different fact, fenced at
+ * load time against the artifact — see `discovery/artifact.loader.ts`.)
+ */
+export async function readInstalledPrismaVersion() {
+    return resolveInstalledPrismaCli().version;
+}
+/**
+ * D4 — the types reader and the runtime-resolution fence use TypeScript's
+ * classic compiler API. TypeScript 7 has none (plan B3: `createProgram` and
+ * `resolveModuleName` are absent; the package exports its version and nothing
+ * else), and before this check the step died on it with a `TypeError` stack.
+ * Asked of the API itself rather than of the version, because the API is what
+ * the step needs.
+ */
+function assertClassicCompilerApi() {
+    // Three members, not `Partial<typeof ts>`: a mapped type over the whole
+    // compiler namespace costs thousands of instantiations to ask three questions.
+    const compiler = ts;
+    if (typeof compiler?.createProgram === "function" &&
+        typeof compiler.resolveModuleName === "function") {
+        return;
+    }
+    throw new PrismaGenerateStepError(`the installed \`typescript\` ${compiler?.version ?? "(no version)"} has no classic compiler API (\`createProgram\`), which this step reads the generated client's types with; install \`typescript\` in this adapter's declared range ${readDeclaredSupport().typescript}.`);
+}
+/**
+ * Whether `@prisma/client/runtime/client` resolves from inside the generated
+ * tree — the single question §1.2 item 16 turns on.
+ *
+ * Asked as a module resolution, never as a diagnostic count, and asked from a
+ * file path *inside* `clientDirectory` because resolution walks `node_modules`
+ * upward from the importer. The directory need not exist yet: resolution is a
+ * path question, which is what lets this fence run before `prisma generate`.
+ */
+export function clientRuntimeResolves(clientDirectory) {
+    const containing = path.join(path.resolve(clientDirectory), "models", "_.ts");
+    const resolved = ts.resolveModuleName("@prisma/client/runtime/client", containing, {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+    }, ts.sys);
+    return resolved.resolvedModule !== undefined;
+}
+export function createPrismaGenerateToolchain() {
+    assertClassicCompilerApi();
+    // Resolved once per toolchain, so the version the fence reads and the CLI the
+    // step runs cannot be two different installs.
+    let cli;
+    const prismaCli = () => {
+        cli ??= resolveInstalledPrismaCli();
+        return cli;
+    };
+    return {
+        installedPrismaVersion: async () => prismaCli().version,
+        clientRuntimeResolves,
+        runPrismaGenerate: async (schema) => {
+            // The CLI is the one resolved beside THIS package (or the project), run
+            // by path with this `node`: invoking whatever `prisma` is on PATH, or at
+            // a workspace root, can be a different install — or produce no output at
+            // all, which looks exactly like success.
+            await run(process.execPath, [
+                prismaCli().entry,
+                "generate",
+                "--schema",
+                schema,
+            ]);
+        },
+        readSchema: readPrismaSchema,
+        readSurface: (clientDirectory) => readPrismaCapabilitySurface(clientDirectory).surface,
+        writeArtifact: writeArtifactAtomically,
+    };
+}
+/**
+ * Writes the artifact so that no reader can ever open a partial file.
+ *
+ * Other packages' tests import the artifact while this package's `test` script
+ * regenerates it, and turbo runs the two in parallel. `writeFile` truncates in
+ * place, so a concurrent `import` could read an empty module — measured: the
+ * client's pilot fixture failed with ``Cannot read properties of undefined
+ * (reading 'enums')``. Two rules close it:
+ *
+ * - **unchanged bytes are not written** — generation is deterministic, so the
+ *   common re-run touches nothing (and keeps the file's mtime for incremental
+ *   tooling);
+ * - **changed bytes land by `rename`** from a sibling temporary file, which POSIX
+ *   makes atomic within one directory: a reader sees the old file or the new one.
+ */
+async function writeArtifactAtomically(file, source) {
+    const current = await readFile(file, "utf8").catch(() => undefined);
+    if (current === source) {
+        return;
+    }
+    await mkdir(path.dirname(file), { recursive: true });
+    const staged = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(staged, source, "utf8");
+        await rename(staged, file);
+    }
+    catch (error) {
+        await rm(staged, { force: true });
+        throw error;
+    }
+}
+function majorOf(version) {
+    const major = /^(\d+)\./.exec(version)?.[1];
+    return major === undefined ? undefined : Number(major);
+}
+function assertPinnedMajor(version) {
+    const major = majorOf(version);
+    if (major === undefined) {
+        throw new PrismaGenerateStepError(`the installed \`prisma\` reports \`${version}\`, which is not a major.minor.patch version, so its major cannot be fenced against the pinned major ${PINNED_PRISMA_MAJOR} (C-846).`);
+    }
+    if (major !== PINNED_PRISMA_MAJOR) {
+        throw new PrismaGenerateStepError(`the installed \`prisma\` is major ${major} and this adapter's readers are written against pinned major ${PINNED_PRISMA_MAJOR} (C-846). PSL's grammar and the generated client's shape are version-bound, so a new major stops the build here rather than producing an AdapterModel from a grammar nobody has read.`);
+    }
+}
+function assertClientRuntimeResolves(toolchain, clientDirectory) {
+    if (toolchain.clientRuntimeResolves(clientDirectory)) {
+        return;
+    }
+    throw new PrismaGenerateStepError(`\`@prisma/client/runtime/client\` does not resolve from ${clientDirectory}, so nothing read from the generated types can be trusted. This failure is SILENT by construction: every generated file opens \`// @ts-nocheck\`, so a program over the tree reports zero diagnostics while \`FieldRef\` degrades to its uninstantiated form and \`JsonValue\` stops being a union — flipping a types-derived nullability from \`true\` to \`false\` with no signal anywhere. Install \`@prisma/client\` where the generated output can resolve it, then regenerate.`);
+}
+function assertNothingUnhandled(facts) {
+    if (facts.unhandled.length === 0) {
+        return;
+    }
+    throw new PrismaGenerateStepError([
+        "the schema reader located constructs it does not model, and a silently dropped construct is how a grammar change becomes wrong output instead of a build stop:",
+        ...facts.unhandled.map((unknown) => `  - ${unknown.spelling} (${unknown.kind}) in \`${unknown.block ?? "<top level>"}\` at ${unknown.site.file}:${unknown.site.line}: ${unknown.text}`),
+    ].join("\n"));
+}
+export async function runPrismaGenerateStep(request) {
+    const toolchain = request.toolchain ?? createPrismaGenerateToolchain();
+    // 1. The version fence, before anything is run or read. The version is read
+    // ONCE and carried to the emit: a second read could answer differently, and
+    // an artifact stamped with a version the fence never saw is exactly the
+    // artifact the fence exists to prevent.
+    const prismaVersion = await toolchain.installedPrismaVersion();
+    assertPinnedMajor(prismaVersion);
+    // 2. The silent one.
+    assertClientRuntimeResolves(toolchain, request.clientDirectory);
+    // 3. This step generates the client it is about to read.
+    await toolchain.runPrismaGenerate(request.schema);
+    // 4. Both sources, in that same run.
+    const facts = await toolchain.readSchema(request.schema);
+    assertNothingUnhandled(facts);
+    // The types reader's failure mode is a throw with nothing to record, so it
+    // is re-raised as this step's own error with the cause preserved rather than
+    // aggregated into a vocabulary invented for it.
+    let surface;
+    try {
+        surface = toolchain.readSurface(request.clientDirectory);
+    }
+    catch (cause) {
+        throw new PrismaGenerateStepError(`the capability surface at ${request.clientDirectory} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    // 5. The structural checks. The gate decides existence; the cross-check then
+    // compares every fact both readers carry. A finding means one of the two
+    // READERS is wrong, never that the schema is — so the step stops rather than
+    // emitting a model it cannot justify.
+    const { admitted, excluded } = applyExistenceGate(facts, surface);
+    const { findings, exemptions } = crossCheckReaders(facts, surface);
+    if (findings.length > 0) {
+        throw new PrismaGenerateStepError(describeReaderFindings(findings));
+    }
+    // 6. Emit.
+    const { model, translation, referentialActions } = request.composeModel({
+        facts,
+        surface,
+        admitted,
+    });
+    const source = await emitDiscoveryArtifactModule({
+        prismaVersion,
+        provider: request.provider,
+        model,
+        translation,
+        referentialActions,
+    });
+    await toolchain.writeArtifact(request.artifactFile, source);
+    const modelHash = await computeModelHash(model);
+    return {
+        artifactFile: request.artifactFile,
+        source,
+        modelHash,
+        admitted,
+        excluded,
+        exemptions,
+    };
+}

package/dist/generate/reader-crosscheck.d.ts

@@ -0,0 +1,156 @@
+import type { PrismaCapabilitySurface } from "../discovery/capability-surface.interface.js";
+import type { PrismaIdentifierMapping } from "../discovery/identifier.mapper.js";
+import type { PrismaSchemaFacts, PrismaSchemaModel } from "../discovery/schema-facts.interface.js";
+/**
+ * Task 6 — the **reader-versus-reader cross-check**: PSL's facts against the 🟢
+ * generated types' facts, at the one instant the generate step reads both.
+ *
+ * # It is a self-test of the two readers, not a check on the developer
+ *
+ * That framing decides every case in this module. A finding here does not mean
+ * *your schema is wrong*; it means **one of this adapter's two readers is
+ * wrong**, or the client it read was generated from a different schema than the
+ * one PSL was read from. The remedy is never "edit the schema" — it is
+ * regenerate, or fix a reader.
+ *
+ * It follows that the check can only see facts **both** sources carry. That is
+ * not a gap to be closed by trying harder; it is arithmetic. The honest limit is
+ * measured below.
+ *
+ * # What it cannot see, measured rather than described
+ *
+ * **Re-measured 2026-10-02 on BOTH Phase 8 engines (prisma 7.10.0), by
+ * `reader-crosscheck.spec.ts`'s "what the cross-check cannot see, by arithmetic"
+ * case.** Four *real semantic* schema edits, each applied to the schema text
+ * alone with the generated client left where it was, produce **zero findings
+ * between them — eight measurements, eight zeros**:
+ *
+ * | edit                                                | sqlite | postgres |
+ * | --------------------------------------------------- | ------ | -------- |
+ * | `@default(uuid())` → `@default(cuid())`             | 0      | 0        |
+ * | `@default(now())` → `@default(dbgenerated("…"))`    | 0      | 0        |
+ * | `@default(BRONZE)` → `@default(GOLD)`               | 0      | 0        |
+ * | `@relation("Mentorship")` → `@relation("Coaching")` | 0      | 0        |
+ *
+ * Every one of them changes what the database does. None of them is visible to a
+ * cross-check, because none of them reaches the 🟢 surface at all: a `@default`
+ * argument's *content* and a relation's *name* are PSL-exclusive (the name
+ * appears nowhere on the generated surface, which is why `field.mapper.ts` pairs
+ * edges from PSL alone). A fifth class is the mirror image: which filter
+ * operators a `<Kind>Filter` exposes is 🟢-exclusive, so a reader that
+ * under-reads one is equally invisible — seeded as the sixth edit in
+ * `__fixtures__/diverged-surface.ts` and caught by nothing.
+ *
+ * **So this module is not a schema-drift detector and must not be trusted as
+ * one.** Staleness — a developer who edits `schema.prisma` and does not re-run
+ * the generate step — is prevented by the step *running `prisma generate`
+ * itself*, so that both sources describe one instant (T-3.2, the architect's
+ * 2026-09-27 ruling). What survives that ruling catches a different failure
+ * again: `modelHash` proves the artifact is internally intact and the
+ * `prismaVersion` major fence catches a client that moved underneath it. Neither
+ * notices a schema that moved, and neither does this.
+ *
+ * # Two exemptions, and both are explanations rather than allowances
+ *
+ * A freshly generated pair is not silent, and the two cases where it speaks are
+ * *understood*:
+ *
+ * 1. **`json-null-is-a-value`** — the one disagreement a pristine pair produces
+ *    on both engines. JSON null is a *value*, so `JsonFilterBase` writes `|
+ *    null` operands (`array_starts_with`, `array_ends_with`, and
+ *    `array_contains` on PostgreSQL) on a column PSL declares **required**. A
+ *    plausible "the operands mention null, therefore the column is nullable"
+ *    rule is right for every other scalar and wrong for every `Json` one, which
+ *    is why nullability comes from PSL's `?` and nothing else (T-3.1 invariant
+ *    4) and why this one is exempted by PSL *type* rather than waved through.
+ * 2. **`nullable-participant-key`** — `Author`'s `tenantId_handle` `AtLeast` key
+ *    has no identifier behind it, because C-815 omits a tuple with a nullable
+ *    participant (`handle String?`) while the generator still emits a key for
+ *    it. C-814's rule is therefore a **subset relation with one closed
+ *    explanation, never an equality**: equality is unsatisfiable by
+ *    construction.
+ *
+ * Each exemption is **recorded with its reason**, not dropped. A spec can then
+ * assert both by name and by reason, so an unexplained third disagreement fails
+ * rather than hiding behind "the pair is clean".
+ *
+ * # What belongs to other modules, and is deliberately not restated here
+ *
+ * - **A PSL-declared entity the 🟢 types do not expose** is the EXISTENCE GATE's
+ *   answer (`existence.gate.ts`, C-808): it decides admission and whether the
+ *   absence is explained. This module answers only the reverse direction — a
+ *   type-exclusive resource or field — which the gate's own header hands to it.
+ * - **A `FieldRef` token that disagrees with the written PSL type** is
+ *   `field.mapper.ts`'s, where it *throws*: the two readers describing one field
+ *   two ways is not a schema a Contract can be compiled from. Restating the rule
+ *   here would be two owners for one fact.
+ * - **A create-optional marker with no PSL cause** is `field.mapper.ts`'s
+ *   `crossCheckCreateOptional`, run by `model.discoverer.ts` where the field
+ *   projections already exist. It needs the projected lifecycle, which this
+ *   module does not compute.
+ */
+/** A disagreement about a fact both sources carry: one of the readers is wrong. */
+export type PrismaReaderFindingKind = 
+/** The 🟢 types expose a resource PSL does not declare. */
+"resource-exclusive-to-types"
+/** The 🟢 types expose a field PSL does not declare on that model. */
+ | "field-exclusive-to-types"
+/** PSL's `?` and the operands the 🟢 filter admits disagree. */
+ | "nullability"
+/** C-814's subset rule is broken in one of its two directions. */
+ | "identifier-key"
+/** An enum is exposed and not declared, declared and not exposed, or its members differ. */
+ | "enum";
+export type PrismaReaderFinding = {
+    readonly kind: PrismaReaderFindingKind;
+    /**
+     * What the finding is about: `Model`, `Model.field`, `Enum`, or
+     * `Model:whereUniqueKey`. The **colon** marks an addressing key rather than a
+     * field path, because a `@@unique(name:)` key may be spelled like a column and
+     * reading one as the other is how C-814's cross-check once refused a schema
+     * Prisma accepts.
+     */
+    readonly entity: string;
+    readonly message: string;
+};
+/** A disagreement that is understood, and therefore not a finding. */
+export type PrismaReaderExemptionKind = "json-null-is-a-value" | "nullable-participant-key";
+export type PrismaReaderExemption = {
+    readonly kind: PrismaReaderExemptionKind;
+    readonly entity: string;
+    /** Why the two sources may differ here. Recorded so a spec can assert the reason. */
+    readonly reason: string;
+};
+export type PrismaReaderCrossCheck = {
+    /** Fatal: the generate step refuses on any one of these. */
+    readonly findings: readonly PrismaReaderFinding[];
+    /** Reported, never fatal. */
+    readonly exemptions: readonly PrismaReaderExemption[];
+};
+/** One direction of C-814's subset rule, as a finding a spec can match on. */
+export type PrismaIdentifierKeyFinding = {
+    readonly key: string;
+    readonly reason: string;
+};
+/**
+ * C-814's two directions, in one total function.
+ *
+ * Exported because it has **two callers that must check one rule**: the generate
+ * step, through {@link crossCheckReaders}, and `identifier.mapper.spec.ts`, whose
+ * own cases were written against a local copy while this file did not exist. The
+ * explanation is re-derived **from PSL**, never taken on the mapping's word —
+ * otherwise a mapper that invented a nullable participant would clear its own
+ * exemption.
+ */
+export declare function crossCheckIdentifierKeys(declared: PrismaSchemaModel, mapping: PrismaIdentifierMapping, uniqueKeys: readonly string[]): readonly PrismaIdentifierKeyFinding[];
+/**
+ * The whole cross-check: a pure function of the two readers' output.
+ *
+ * The order is a property of the model and not of how the readers happened to
+ * build their records: resources in PSL declaration order, and within one
+ * resource the type-exclusive fields, then nullability in PSL field order, then
+ * the identifier keys; enums last.
+ */
+export declare function crossCheckReaders(facts: PrismaSchemaFacts, surface: PrismaCapabilitySurface): PrismaReaderCrossCheck;
+/** The sentence the generate step refuses with. Built here, so one wording exists. */
+export declare function describeReaderFindings(findings: readonly PrismaReaderFinding[]): string;

package/dist/generate/reader-crosscheck.js

@@ -0,0 +1,202 @@
+import { mapPrismaEnum } from "../discovery/enum.mapper.js";
+import { mapPrismaIdentifiers } from "../discovery/identifier.mapper.js";
+const JSON_EXEMPTION_REASON = "`Json` admits JSON null as a VALUE, so the generated `JsonFilterBase` writes `| null` operands " +
+    "(`array_starts_with`, `array_ends_with`, and `array_contains` on PostgreSQL) on a column PSL " +
+    "declares required. Nullability therefore comes from PSL's `?` and nothing else (T-3.1 invariant 4).";
+function nullableParticipantReason(key, nullableMembers) {
+    return (`C-815 omits the uniqueness criterion behind \`${key}\` because [${nullableMembers.join(", ")}] ` +
+        "is nullable and SQL uniqueness does not constrain NULLs, while the generator still emits an " +
+        "`AtLeast` key for it. C-814's rule is a subset relation with this one closed explanation, " +
+        "never an equality: equality is unsatisfiable by construction.");
+}
+/**
+ * C-814's two directions, in one total function.
+ *
+ * Exported because it has **two callers that must check one rule**: the generate
+ * step, through {@link crossCheckReaders}, and `identifier.mapper.spec.ts`, whose
+ * own cases were written against a local copy while this file did not exist. The
+ * explanation is re-derived **from PSL**, never taken on the mapping's word —
+ * otherwise a mapper that invented a nullable participant would clear its own
+ * exemption.
+ */
+export function crossCheckIdentifierKeys(declared, mapping, uniqueKeys) {
+    const findings = [];
+    const nullableInPsl = new Set(declared.fields.filter((f) => f.optional).map((f) => f.name));
+    const identifierKeys = mapping.identifiers.map((address) => address.key);
+    // (a) An identifier the types do not key means the PSL reader invented a
+    //     constraint.
+    for (const key of identifierKeys) {
+        if (!uniqueKeys.includes(key)) {
+            findings.push({
+                key,
+                reason: "an identifier with no `AtLeast` key behind it",
+            });
+        }
+    }
+    // (b) A key with no identifier must be explained by C-815's nullable
+    //     participant and by nothing else.
+    for (const key of uniqueKeys) {
+        if (identifierKeys.includes(key)) {
+            continue;
+        }
+        const omission = mapping.omitted.find((o) => o.key === key);
+        if (omission === undefined) {
+            findings.push({
+                key,
+                reason: "an `AtLeast` key with neither an identifier nor an omission",
+            });
+            continue;
+        }
+        if (omission.reason !== "nullable-participant") {
+            findings.push({
+                key,
+                reason: `omitted as ${omission.reason}, which C-815 does not license`,
+            });
+            continue;
+        }
+        const unproven = omission.nullableMembers.filter((member) => !nullableInPsl.has(member));
+        if (omission.nullableMembers.length === 0 || unproven.length > 0) {
+            findings.push({
+                key,
+                reason: `claimed nullable participants [${omission.nullableMembers.join(", ")}] are not optional in PSL`,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * The whole cross-check: a pure function of the two readers' output.
+ *
+ * The order is a property of the model and not of how the readers happened to
+ * build their records: resources in PSL declaration order, and within one
+ * resource the type-exclusive fields, then nullability in PSL field order, then
+ * the identifier keys; enums last.
+ */
+export function crossCheckReaders(facts, surface) {
+    const findings = [];
+    const exemptions = [];
+    const declaredModels = new Map(facts.models.map((m) => [m.name, m]));
+    for (const name of Object.keys(surface.resources)) {
+        if (declaredModels.has(name)) {
+            continue;
+        }
+        findings.push({
+            kind: "resource-exclusive-to-types",
+            entity: name,
+            message: `the generated 🟢 types expose a model \`${name}\` that \`schema.prisma\` does not declare. The two readers describe one instant, so this is a stale generated client or a reader defect — the schema cannot have said it.`,
+        });
+    }
+    for (const model of facts.models) {
+        const exposed = surface.resources[model.name];
+        if (exposed === undefined) {
+            // A PSL-declared model the types do not expose is the existence gate's
+            // answer, with its own explained/unexplained split. Not restated here.
+            continue;
+        }
+        const declaredFields = new Set(model.fields.map((f) => f.name));
+        for (const field of [
+            ...Object.keys(exposed.scalarFields),
+            ...Object.keys(exposed.relationFields),
+        ]) {
+            if (declaredFields.has(field)) {
+                continue;
+            }
+            findings.push({
+                kind: "field-exclusive-to-types",
+                entity: `${model.name}.${field}`,
+                message: `the generated 🟢 types expose \`${model.name}.${field}\` and \`schema.prisma\` declares no such member. A rename seen by only one of the two readers looks exactly like this.`,
+            });
+        }
+        for (const field of model.fields) {
+            const scalar = exposed.scalarFields[field.name];
+            if (scalar === undefined) {
+                // A relation edge's nullability is checked by `field.mapper.ts`, which
+                // has the payload's own `nullable` and throws on a disagreement.
+                continue;
+            }
+            // A scalar LIST is out of scope, and the exclusion is a scoping decision
+            // rather than a measurement: `StringNullableListFilter.equals` is
+            // `string[] | null` on a `String[]` column PSL declares required
+            // (`Post.tags` on PostgreSQL), because the `null` there is about the
+            // absence of the whole list and not about an element. The rule below is a
+            // per-column nullability signal only where the column holds one value.
+            if (field.list) {
+                continue;
+            }
+            const nullAdmitting = Object.entries(scalar.filterOperands)
+                .filter(([, written]) => /\bnull\b/.test(written))
+                .map(([key]) => key);
+            const typesSayNullable = nullAdmitting.length > 0;
+            if (typesSayNullable === field.optional) {
+                continue;
+            }
+            if (field.type === "Json" && typesSayNullable) {
+                exemptions.push({
+                    kind: "json-null-is-a-value",
+                    entity: `${model.name}.${field.name}`,
+                    reason: JSON_EXEMPTION_REASON,
+                });
+                continue;
+            }
+            findings.push({
+                kind: "nullability",
+                entity: `${model.name}.${field.name}`,
+                message: `\`${model.name}.${field.name}\` is ${field.optional ? "optional" : "required"} in \`schema.prisma\` and the generated 🟢 filter ${typesSayNullable ? `admits \`null\` on [${nullAdmitting.join(", ")}]` : "admits `null` nowhere"}. PSL's \`?\` is the only source of nullability, so the model is built from it either way — this says one of the two readers, or the client, is from a different schema.`,
+            });
+        }
+        const mapping = mapPrismaIdentifiers(model);
+        for (const finding of crossCheckIdentifierKeys(model, mapping, exposed.uniqueKeys)) {
+            findings.push({
+                kind: "identifier-key",
+                entity: `${model.name}:${finding.key}`,
+                message: `\`${model.name}\`'s \`WhereUniqueInput\` key \`${finding.key}\` is ${finding.reason} (C-814).`,
+            });
+        }
+        for (const omission of mapping.omitted) {
+            if (omission.reason !== "nullable-participant" ||
+                !exposed.uniqueKeys.includes(omission.key)) {
+                continue;
+            }
+            exemptions.push({
+                kind: "nullable-participant-key",
+                entity: `${model.name}:${omission.key}`,
+                reason: nullableParticipantReason(omission.key, omission.nullableMembers),
+            });
+        }
+    }
+    for (const name of Object.keys(surface.enums)) {
+        if (facts.enums.some((declared) => declared.name === name)) {
+            continue;
+        }
+        findings.push({
+            kind: "enum",
+            entity: name,
+            message: `the generated 🟢 \`enums.ts\` exposes \`${name}\` and \`schema.prisma\` declares no such enum.`,
+        });
+    }
+    for (const declared of facts.enums) {
+        // The member comparison is the ENUM MAPPER's own rule, invoked rather than
+        // restated: declaration order is semantic (§19.2) and enters the Contract
+        // hash, so "diverged" is the same judgement in both callers.
+        const mapped = mapPrismaEnum({
+            declared,
+            exposed: surface.enums[declared.name],
+        });
+        if (mapped.outcome === "enum") {
+            continue;
+        }
+        findings.push({
+            kind: "enum",
+            entity: declared.name,
+            message: mapped.diagnostic.message,
+        });
+    }
+    return { findings, exemptions };
+}
+/** The sentence the generate step refuses with. Built here, so one wording exists. */
+export function describeReaderFindings(findings) {
+    return [
+        "the two discovery readers disagree about facts they both carry, which means one of THEM is wrong — not the schema:",
+        ...findings.map((finding) => `  - [${finding.kind}] ${finding.entity}: ${finding.message}`),
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { PrismaAdapterModel, PrismaDiscoveryArtifact, PrismaReferentialAction, PrismaReferentialActionTable, PrismaReferentialEdge, PrismaResourceReferentialActions, } from "./discovery/discovery-artifact.interface.js";
+export type { PrismaAdapterOptions } from "./prisma.adapter.js";
+export { createPrismaAdapter } from "./prisma.adapter.js";
+export type { PrismaDelegate, PrismaDelegateHost, PrismaDelegateIndex, PrismaTransactionOptions, } from "./prisma-client.interface.js";
+export type { PrismaDriver, PrismaIsolationLevel, PrismaProvider, PrismaProviderProfile, } from "./provider/provider-profile.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { createPrismaAdapter } from "./prisma.adapter.js";