@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/discovery/artifact.loader.js

@@ -0,0 +1,124 @@
+import { canonicalizeJson } from "@aventara/core";
+/**
+ * T-3.2 — `discover()`'s whole runtime half.
+ *
+ * This module builds no TypeScript program, parses no PSL and calls no Prisma
+ * tooling, and that is guaranteed by construction rather than by assertion:
+ * its transitive import graph is this file, `discovery-artifact.interface.ts`
+ * and `@aventara/core`. Nothing under `generate/` is reachable from here, and
+ * neither is `typescript`, `prisma`, `@prisma/*`, `node:child_process` or
+ * `node:fs`. `artifact.loader.spec.ts` walks that graph from source and fails
+ * if a specifier appears that should not.
+ *
+ * The loader reads no file at all: the artifact arrives as a value, and hashing
+ * uses `globalThis.crypto.subtle`, so it needs no import either. It checks the
+ * two facts the runtime can still get wrong — that the artifact matches itself
+ * (`modelHash`) and that the installed `@prisma/client` major is the one it was
+ * generated against (C-846) — and nothing else. The model is derived at
+ * generate time from the schema and the generated client read in the same
+ * instant and cross-checked there, so the runtime never sees the schema and
+ * never asks after it.
+ */
+/** The `sha256:<hex>` convention core already uses for Contract identity. */
+const HASH_PREFIX = "sha256:";
+/**
+ * A stale or corrupt artifact is answered the way cross-phase invariant 15
+ * answers a Contract-hash mismatch: fail hard, and say what to run.
+ */
+const REGENERATION_INSTRUCTION = "Regenerate the discovery artifact with the adapter's generate step " +
+    "(`aventara-prisma7-generate`) and redeploy it " +
+    "alongside the schema and client it was generated from.";
+/** Every artifact failure is this class, and every one of them says how to fix it. */
+export class PrismaDiscoveryArtifactError extends Error {
+    constructor(reason) {
+        super(`${reason} ${REGENERATION_INSTRUCTION}`);
+        this.name = "PrismaDiscoveryArtifactError";
+    }
+}
+function hex(digest) {
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function sha256(text) {
+    const bytes = new TextEncoder().encode(text);
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return `${HASH_PREFIX}${hex(digest)}`;
+}
+/**
+ * The identity of a discovered model: one canonicalization, one digest — over
+ * the model and **nothing else**. The artifact's `translation` half is Prisma
+ * addressing, and hashing it would put a DB-side rename into the Contract
+ * identity; its `referentialActions` half is what a delete does below the ORM
+ * entrypoint, and hashing it would put a foreign-key action into the Contract
+ * identity and into every generated client.
+ */
+export async function computeModelHash(model) {
+    return sha256(canonicalizeJson(model));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function majorOf(version) {
+    const major = /^(\d+)\./.exec(version)?.[1];
+    return major;
+}
+/** Shape validation, before any hash is computed over a value that may not have one. */
+function assertArtifactShape(artifact) {
+    if (!isRecord(artifact)) {
+        throw new PrismaDiscoveryArtifactError("The discovery artifact is not a JSON object.");
+    }
+    for (const key of ["prismaVersion", "provider", "modelHash"]) {
+        if (typeof artifact[key] !== "string") {
+            throw new PrismaDiscoveryArtifactError(`The discovery artifact's \`${key}\` is not a string.`);
+        }
+    }
+    if (!isRecord(artifact.model)) {
+        throw new PrismaDiscoveryArtifactError("The discovery artifact's `model` is not a JSON object.");
+    }
+    // The two beside-the-model halves are checked as members, not as content: this
+    // function asserts the artifact IS a `PrismaDiscoveryArtifact`, and an
+    // assertion that skipped a declared member would be a lie its consumer pays
+    // for. Their entries are not walked here — the runtime half hashes and returns
+    // the model, the executor reads its own addressing keys, and a cascade planner
+    // reads its own edges.
+    //
+    // `referentialActions` is checked for the same reason as `translation` and with
+    // the same consequence: an artifact emitted before the key existed is refused
+    // here and regenerated, rather than reaching a planner as `undefined`.
+    for (const key of ["translation", "referentialActions"]) {
+        if (!isRecord(artifact[key])) {
+            throw new PrismaDiscoveryArtifactError(`The discovery artifact's \`${key}\` is not a JSON object.`);
+        }
+    }
+    for (const key of ["scalars", "enums", "resources"]) {
+        if (!isRecord(artifact.model[key])) {
+            throw new PrismaDiscoveryArtifactError(`The discovery artifact's \`model.${key}\` is not a JSON object.`);
+        }
+    }
+    if (artifact.model.transactions !== "none" &&
+        artifact.model.transactions !== "interactive") {
+        throw new PrismaDiscoveryArtifactError("The discovery artifact's `model.transactions` is not a transaction capability.");
+    }
+}
+/**
+ * Validates an artifact and hands back its model **unchanged**.
+ *
+ * Three checks, in the order that makes each one's failure legible: shape, then
+ * the `prismaVersion` major fence (C-846), then `modelHash`.
+ */
+export async function loadDiscoveryArtifact(load) {
+    const { artifact, installedPrismaVersion } = load;
+    assertArtifactShape(artifact);
+    const artifactMajor = majorOf(artifact.prismaVersion);
+    const installedMajor = majorOf(installedPrismaVersion);
+    if (artifactMajor === undefined || installedMajor === undefined) {
+        throw new PrismaDiscoveryArtifactError(`A Prisma version is not a major.minor.patch version: the artifact declares \`${artifact.prismaVersion}\` and the installed client reports \`${installedPrismaVersion}\`.`);
+    }
+    if (artifactMajor !== installedMajor) {
+        throw new PrismaDiscoveryArtifactError(`The discovery artifact was generated against Prisma major ${artifactMajor}, and the installed client is major ${installedMajor}. The P-code surface and the generated-client grammar are version-bound (C-846).`);
+    }
+    const modelHash = await computeModelHash(artifact.model);
+    if (modelHash !== artifact.modelHash) {
+        throw new PrismaDiscoveryArtifactError("The discovery artifact's `modelHash` does not match its own `model`, so the artifact is corrupt or was edited by hand.");
+    }
+    return artifact.model;
+}

package/dist/discovery/capability-surface.interface.d.ts

@@ -0,0 +1,191 @@
+/**
+ * T-3, source **TYPE** — the output of the reader over the generated client's
+ * 🟢 public types.
+ *
+ * Nothing here is imported from `@prisma/client`: these are this adapter's own
+ * facts over public generated types, which is what keeps discovery a pure
+ * function of plain data and unit-testable without a client (T-3).
+ *
+ * Read `types.reader.ts`'s header for the two rules that give these facts their
+ * meaning: only the 🟢 files are opened, and token-shaped facts come from the
+ * **written** type arguments rather than from the instantiated reference.
+ */
+export type PrismaCapabilitySurface = {
+    /** The EXISTENCE GATE: an entity is discoverable iff it appears here (T-3.1 invariant 3). */
+    readonly resources: Readonly<Record<string, PrismaResourceSurface>>;
+    /** `enums.ts`'s `as const` objects, in property order. */
+    readonly enums: Readonly<Record<string, readonly string[]>>;
+};
+export type PrismaResourceSurface = {
+    /** `$<M>Payload.scalars` ∪ `<M>FieldRefs`. */
+    readonly scalarFields: Readonly<Record<string, PrismaScalarSurface>>;
+    readonly relationFields: Readonly<Record<string, PrismaRelationSurface>>;
+    /** `AtLeast<…, K>`'s key union — cross-check only; order unused. */
+    readonly uniqueKeys: readonly string[];
+    /** `<M>Delegate`'s own methods → `ResourceOperations`. */
+    readonly operations: readonly string[];
+    /** e.g. `updateMany` → `["data", "where", "limit"]`. */
+    readonly manyWriteArguments: Readonly<Record<string, readonly string[]>>;
+};
+export type PrismaScalarSurface = {
+    /** `FieldRef<"M", 'String'>` — the scalar token, or the enum's name. */
+    readonly token: string;
+    /** `<Kind>Filter` keys, in Prisma's spelling — NAMES ONLY. */
+    readonly filters: readonly string[];
+    /**
+     * The operand SHAPE per filter key, as written in the generated type — because
+     * two engines can carry the same key with different operands, and a name set
+     * cannot express that (D-802): `path` is `string[]` on PostgreSQL and `string`
+     * on SQLite, and `in`/`notIn` admit `List<Kind>FieldRefInput` on PostgreSQL
+     * only. Read, not tabulated — T-3.1 invariant 6.
+     */
+    readonly filterOperands: Readonly<Record<string, string>>;
+    /**
+     * `<M>UncheckedCreateInput`'s entry for this field, read as the keys of the
+     * `…Input` it references: `[]` for a plain value, and **`null` where the client
+     * exposes no entry at all**, which is the only evidence that a column is not
+     * creatable.
+     *
+     * The UNCHECKED input is the source because it is what the delegate accepts:
+     * `create`'s argument is `XOR<<M>CreateInput, <M>UncheckedCreateInput>`, and the
+     * checked half omits every foreign-key scalar (the relation owns it there). Read
+     * from the checked half, `Post.authorId` and `Post.categoryId` come back absent
+     * and Aventara would refuse writes Prisma accepts.
+     */
+    readonly createOperations: readonly string[] | null;
+    /**
+     * Whether `<M>UncheckedCreateInput` writes this member with a `?`.
+     *
+     * A **different fact** from {@link createOperations}, which is why both are
+     * recorded: `createOperations` answers *what may be written* — the directive
+     * keys, `[]` for a plain value and `null` where the client exposes no entry at
+     * all — and erases the question mark on the way. `createOptional` answers
+     * *whether a value may be omitted*, and nothing else on this surface carries
+     * it.
+     *
+     * It is **one bit over several causes** — `@default(…)`, `@updatedAt`, plain
+     * nullability, and a scalar list, which needs no value because the empty list
+     * is one — so it is never read as a lifecycle trait. Its only consumer is
+     * `field.mapper.ts`'s `crossCheckCreateOptional`, which runs it as a check in
+     * one direction: every member the types mark optional must have a PSL cause.
+     * Deriving a trait from it would make the two readers agree by construction
+     * and detect nothing.
+     *
+     * `false` where the client exposes no entry for the column at all, which
+     * {@link createOperations}`=== null` is the evidence for; the two never
+     * disagree about presence because they are read from the same member.
+     */
+    readonly createOptional: boolean;
+    /**
+     * `<M>UncheckedUpdateInput`'s entry, read the same way — the keys of
+     * `<Kind>FieldUpdateOperationsInput`, or of `<M>Update<field>Input` for a scalar
+     * list (`set`, `push`), or `[]` for a plain value (`Json`), or `null` where the
+     * client exposes no entry.
+     *
+     * Measured at 7.10.0 (2026-10-02): reading `<M>UpdateInput` instead under-reports
+     * six of the twenty-five scalar columns per engine — `Author.mentorId`,
+     * `Metric.authorId`, `Post.authorId`, `Post.categoryId`, `Category.id` and
+     * `Post.id` — every one of which `<M>UncheckedUpdateInput` admits.
+     */
+    readonly updateOperations: readonly string[] | null;
+    readonly orderable: boolean;
+    /** `SortOrderInput` admitted for this field. */
+    readonly nullsOrderable: boolean;
+};
+export type PrismaRelationSurface = {
+    /** Read off `$<Target>Payload`'s own `name` literal, never off the alias's spelling. */
+    readonly target: string;
+    readonly many: boolean;
+    readonly nullable: boolean;
+    /** `ListRelationFilter` vs `[Nullable]ScalarRelationFilter`. */
+    readonly filters: readonly string[];
+    /**
+     * `<T>CreateNested{One,Many}Without<M>Input` keys — the **create** stage's own
+     * nested-write input, read off `<M>CreateInput`'s entry for this edge.
+     *
+     * A SEPARATE fact from {@link updateMutations}, and the separation is the C-855
+     * invariant: the create-stage input carries `create`, `connectOrCreate`,
+     * `createMany` (to-many only) and `connect` and nothing else, where the
+     * update-stage input carries eight more. Reusing one list for both stages
+     * advertises five directives per to-many edge, and two per to-one edge, that
+     * Prisma has no key for at the create stage.
+     */
+    readonly createMutations: readonly string[];
+    /** `<T>Update*Without<M>NestedInput` keys — the **update** stage's own input. */
+    readonly updateMutations: readonly string[];
+    /**
+     * `<M>$<edge>Args`'s own member names, as written. The edge's whole argument
+     * surface, because four separate capabilities are read off it — pagination,
+     * ordering, nested filtering of the returned edge, and projection — and a
+     * residual cannot answer the other three.
+     */
+    readonly edgeArguments: readonly string[];
+    /**
+     * {@link edgeArguments} minus what projection and predicate already own — a
+     * derived projection kept because it is the one a to-one/to-many split reads at
+     * a glance: a to-one edge leaves nothing.
+     */
+    readonly pagination: readonly string[];
+    /** The edge is admitted by `<M>OrderByWithRelationInput`. */
+    readonly orderable: boolean;
+    /** `_count` on `<M>Include` / `<M>CountOutputType`. */
+    readonly reducers: readonly string[];
+    /**
+     * Whether **every** `<M>Select{Create,Update}ManyAndReturn` the client declares
+     * lists this edge.
+     *
+     * # Presence, read. Not foreign-key ownership, computed
+     *
+     * The *explanation* for which edges survive into a bulk-returning write's
+     * projection is foreign-key ownership rather than cardinality — a to-one that
+     * does not hold its own FK is absent, which is what the `User`/`Profile`
+     * fixture exists to prove. That explanation is **not** the mechanism. The
+     * mechanism is this member: the edge is in the type, or it is not.
+     *
+     * Deriving FK ownership here instead would be a tabulated provider-dependent
+     * fact — the shape §18.4 forbids and D-802 exists to prevent — and it would be
+     * wrong the first time Prisma changes which relations it admits into the
+     * projection, while a presence read simply tells the truth again.
+     *
+     * **Every**, not *any*: one {@link ProjectionScope} covers both bulk-returning
+     * variants, so a scope the adapter advertises must hold in both. At 7.10.0 the
+     * two types agree member-for-member on both pilot engines, so the conjunction
+     * is currently indistinguishable from either half — `types.reader.spec.ts`
+     * asserts that agreement, so the day it stops holding is the day a reader
+     * reports it instead of silently picking a side. **Zero declared types answer
+     * `false`**, never vacuously `true`: a client with no `*AndReturn` type admits
+     * nothing there.
+     */
+    readonly bulkSelect: boolean;
+    /** The {@link bulkSelect} question asked of `<M>Include{Create,Update}ManyAndReturn`. */
+    readonly bulkInclude: boolean;
+    /**
+     * Whether `_count` is listed by every one of those **four** types — the same
+     * presence question, asked of the reducer key rather than of the edge.
+     *
+     * A model-level fact carried on each edge because the capability it qualifies
+     * is the edge's: `RelationFieldCapabilities.reducers` says which reducers *this
+     * relation* admits, and `_count` is the one projection key all of them are
+     * asked for through.
+     */
+    readonly bulkReducers: boolean;
+    /**
+     * Whether `<M>CreateManyInput` — the data argument of the bulk create — exposes
+     * an entry for this edge.
+     *
+     * The write-side mirror of {@link bulkSelect}, and read the same way: C-818's
+     * rule (*no nested `create`/`connect` inside a top-level `createMany()` or
+     * `createManyAndReturn()`*) is a **consequence** of the bulk input carrying no
+     * relation member, never a row this adapter keeps.
+     */
+    readonly bulkCreatable: boolean;
+    /**
+     * Whether `<M>UpdateManyMutationInput` or `<M>UncheckedUpdateManyInput` exposes
+     * an entry for this edge.
+     *
+     * Both halves, because `updateMany`'s `data` is the `XOR` of them — exactly the
+     * reason {@link PrismaScalarSurface.updateOperations} reads the unchecked half:
+     * reading one input alone under-reports what the delegate accepts.
+     */
+    readonly bulkUpdatable: boolean;
+};

package/dist/discovery/capability-surface.interface.js

@@ -0,0 +1,13 @@
+/**
+ * T-3, source **TYPE** — the output of the reader over the generated client's
+ * 🟢 public types.
+ *
+ * Nothing here is imported from `@prisma/client`: these are this adapter's own
+ * facts over public generated types, which is what keeps discovery a pure
+ * function of plain data and unit-testable without a client (T-3).
+ *
+ * Read `types.reader.ts`'s header for the two rules that give these facts their
+ * meaning: only the 🟢 files are opened, and token-shaped facts come from the
+ * **written** type arguments rather than from the instantiated reference.
+ */
+export {};

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

@@ -0,0 +1,92 @@
+import type { RelationFieldCapabilities, ScalarFieldCapabilities, ScalarFilterOperator } from "@aventara/core";
+import type { PrismaRelationSurface, PrismaScalarSurface } from "./capability-surface.interface.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 declare class PrismaCapabilityDerivationError extends Error {
+    readonly name = "PrismaCapabilityDerivationError";
+}
+/**
+ * T-6's `ScalarCapabilityInput`, narrowed — see this module's header.
+ *
+ * An object rather than a bare parameter because T-6 names an input type and
+ * because a later pass may legitimately add `mapping` back.
+ */
+export type ScalarCapabilityInput = {
+    readonly surface: PrismaScalarSurface;
+};
+/**
+ * A relation's capabilities are answered for the field, not for an operation.
+ *
+ * The `operation: "create.one" | "create.many"` parameter this input used to carry
+ * is **gone**. It existed because C-818's answer differs between the singular and
+ * the bulk create and the capability shape had nowhere to put the difference, so
+ * composition had to pick one variant's answer and the other was unrepresentable —
+ * `model.discoverer.ts` recorded that as an open conflict. The scope-qualified
+ * members hold both answers at once, so there is nothing left to pick and no caller
+ * left to pick it.
+ */
+export type RelationCapabilityInput = {
+    readonly surface: PrismaRelationSurface;
+};
+export declare function deriveScalarCapabilities(input: ScalarCapabilityInput): ScalarFieldCapabilities;
+/**
+ * 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 declare function deriveScalarFilterOperands(input: ScalarCapabilityInput): Readonly<Partial<Record<ScalarFilterOperator, string>>>;
+export declare function deriveRelationCapabilities(input: RelationCapabilityInput): RelationFieldCapabilities;