@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/execution/operation.executor.js

@@ -0,0 +1,210 @@
+import { classifyPrismaError, prismaOutcomeFailure, } from "../errors/error.normalizer.js";
+import { prismaDelegates, } from "../prisma-client.interface.js";
+import { PRISMA_VARIANT_DISPATCH, translateOperation, } from "../translation/operation.translator.js";
+import { runFirstVariantEmulation } from "./first-variant.emulator.js";
+import { shapeCount, shapeRow, shapeRows, } from "./result.shaper.js";
+/**
+ * The execution half of T-7: a translated {@link PrismaCall} → a provider call,
+ * and `Adapter.execute` made real.
+ *
+ * Translation is pure and lives in `translation/operation.translator.ts`; this
+ * module owns the three things that need a client and nothing else:
+ *
+ * 1. **Reaching the delegate.** See {@link delegateKeyOf} — the one derivation in
+ *    this package, and the one place it is made.
+ * 2. **Classifying a failure.** The closed P-code table in
+ *    `errors/error.normalizer.ts` answers `absence` → `null` (D-811),
+ *    `outcome` → a deliberate `FrameworkError`, or `unclassified` → propagate, so
+ *    core's `AdapterBoundary` reports `A3001` with core's own text and sends the
+ *    raw error to diagnostics. The adapter never guesses a code it did not measure.
+ * 3. **Shaping the answer.** `execution/result.shaper.ts` places every `$count`
+ *    envelope, converts every returned value to the runtime form core's output
+ *    validator accepts (C-834's inbound half) and reads the number a count variant
+ *    owes; which of its three entry points runs is the *variant's* `result` row in
+ *    the dispatch table, not a guess from the shape Prisma returned. The shaper is
+ *    handed the model and the Resource as well as the plan, because the scalar a
+ *    returned value belongs to is a fact of the model and not of the value.
+ *
+ * # One executor type, two scopes (D-807, C-804)
+ *
+ * `scope: "root"` is the adapter's own `execute`. `scope: "transaction"` is what
+ * `Adapter.transaction`'s callback hands core: the same code over a transaction
+ * client. The scope decides exactly one thing — whether a first-style emulation
+ * opens its own interactive transaction or reuses the one already open — and a
+ * transaction-scoped executor closes over the transaction client only, so the root
+ * client is unreachable from inside it.
+ *
+ * # C-834 is converted at its own seam, not at this one
+ *
+ * All three value crossings read ONE table, `translation/scalar.conversion.ts`:
+ * a write's data through `mutation.translator.ts`, a filter operand through
+ * `where.translator.ts`, and a returned row through `execution/result.shaper.ts`.
+ * None of them is converted here. Converting at this seam would have put the
+ * scalar table in a fourth place and hidden the gap from the module that owns it.
+ *
+ * **Core's output validation runs after this module, and strips.** For a
+ * projection-carrying variant `planReadOperation` sets `materialize: true` and
+ * `materializeRecord` ends in `Object.fromEntries(plan.requested…)` **[CORE]**, so
+ * a spare key the adapter returned would be removed before the validator saw it.
+ * That is why the emulator's own return value is asserted directly in
+ * `first-variant.emulator.spec.ts` as well as end-to-end here: an end-to-end
+ * assertion about extra keys cannot fail on that path.
+ */
+/** A call the executor cannot issue against the client it was given. */
+export class PrismaExecutionError extends Error {
+    name = "PrismaExecutionError";
+}
+/**
+ * Prisma's delegate property for a model.
+ *
+ * **Derived, and that is a recorded residual rather than a comfortable choice.**
+ * The authoritative token is readable — `generated/<engine>/models/<M>.ts`, a 🟢
+ * file, writes it as the extension key: `GetSelect<{ … },
+ * ExtArgs["result"]["author"]>` for model `Author` — but `types.reader.ts` reads
+ * the 🟢 files for *capability* facts and does not record it, and the client
+ * property itself is declared only in `internal/class.ts`, which that reader
+ * refuses by design. So the rule applied here is Prisma's own: lower-case the
+ * first character and nothing else. `operation.executor.spec.ts` asserts the
+ * derivation against the real generated client for **every** model in the schema,
+ * so it is observed for this repository's six models; a model name whose Prisma
+ * property does not follow the rule would be caught there and not in production.
+ * The clean owner of the fact is the generate-time translation table, beside
+ * `identifierKeys`, and that is left as a pointer rather than taken here.
+ */
+export function delegateKeyOf(model) {
+    const first = model.slice(0, 1);
+    return `${first.toLowerCase()}${model.slice(1)}`;
+}
+export function createPrismaOperationExecutor(dependencies) {
+    const issue = async (call) => resolveDelegateCall(dependencies.client, call)(call.args);
+    return {
+        async execute(operation) {
+            const result = resultKindOf(dispatchOf(operation));
+            const translation = translateOperation({
+                model: dependencies.model,
+                translation: dependencies.translation,
+                operation: operation,
+            });
+            const shaping = {
+                model: dependencies.model,
+                resource: operation.resource,
+                plan: translation.projection,
+            };
+            if (translation.plan.kind === "single") {
+                const call = translation.plan.call;
+                return shape(result, await issueClassified(issue, call, operation), shaping);
+            }
+            const emulated = await runFirstVariantEmulation({
+                steps: translation.plan.steps,
+                identifiers: identifiersOf(dependencies, operation.resource),
+                inUnit: (work) => withUnit(dependencies, (client) => work((call, step) => {
+                    // The READ goes through the same classification as any other
+                    // call; the WRITE's own `P2025` is the emulator's to interpret,
+                    // by call site.
+                    const send = (one) => resolveDelegateCall(client, one)(one.args);
+                    return step === "read"
+                        ? issueClassified(send, call, operation)
+                        : send(call);
+                })),
+            });
+            return emulated === null ? null : shape(result, emulated, shaping);
+        },
+    };
+}
+/**
+ * D-807's unit. Standalone the emulation opens its **own** interactive
+ * transaction and the steps run on **that** client; inside a plan it reuses the
+ * outer transaction client, so its steps roll back with the plan rather than
+ * independently (§14.5). No isolation level is escalated (C-830).
+ */
+async function withUnit(dependencies, work) {
+    if (dependencies.scope === "transaction") {
+        // The plan's transaction is already open and `client` IS its client, so a
+        // nested one would let these steps roll back independently of the plan.
+        return work(dependencies.client);
+    }
+    const options = dependencies.transactionOptions;
+    // The client the callback is handed is the one the steps run on: that is what
+    // makes the two statements one unit rather than two statements near one.
+    return options === undefined
+        ? dependencies.client.$transaction((transactional) => work(transactional))
+        : dependencies.client.$transaction((transactional) => work(transactional), options);
+}
+/**
+ * What the variant owes, read off the dispatch table.
+ *
+ * An `"unavailable"` entry is refused here rather than silently shaped: core
+ * rejects the request with `A2002 UNKNOWN_OPERATION` long before this, because
+ * `operations.deriver.ts` never advertised it, so reaching this line means the
+ * Contract and the adapter have diverged and that is a defect, not a request.
+ */
+function resultKindOf(dispatch) {
+    if (dispatch.kind === "unavailable") {
+        throw new PrismaExecutionError(`the Prisma adapter advertises no call for this operation: ${dispatch.reason}`);
+    }
+    return dispatch.result;
+}
+function dispatchOf(operation) {
+    const table = PRISMA_VARIANT_DISPATCH;
+    const entry = table[`${operation.family}.${operation.variant}`];
+    if (entry === undefined) {
+        throw new PrismaExecutionError(`"${operation.family}.${operation.variant}" is not a standard Aventara operation`);
+    }
+    return entry;
+}
+function identifiersOf(dependencies, resource) {
+    const entry = dependencies.translation[resource];
+    if (entry === undefined) {
+        throw new PrismaExecutionError(`Resource "${resource}" has no Prisma addressing in the translation table`);
+    }
+    return entry.identifierKeys;
+}
+function resolveDelegateCall(client, call) {
+    const key = delegateKeyOf(call.model);
+    const delegate = prismaDelegates(client)[key];
+    if (delegate === undefined) {
+        throw new PrismaExecutionError(`the client exposes no delegate "${key}" for Prisma model "${call.model}"`);
+    }
+    const method = delegate[call.action];
+    if (typeof method !== "function") {
+        throw new PrismaExecutionError(`the delegate "${key}" exposes no "${call.action}", which discovery advertised`);
+    }
+    return (args) => Promise.resolve(method.call(delegate, args));
+}
+/**
+ * Issues one call and routes its failure through the closed P-code table.
+ *
+ * `absence` returns `null`, which core's `OUTCOME_TABLE` turns into `A2003` for a
+ * strict-unique variant (D-811) — the adapter never names the A-code.
+ */
+async function issueClassified(issue, call, operation) {
+    try {
+        return await issue(call);
+    }
+    catch (error) {
+        const classification = classifyPrismaError(error, operation);
+        switch (classification.kind) {
+            case "absence":
+                return null;
+            case "outcome":
+                throw prismaOutcomeFailure(classification.code);
+            case "unclassified":
+                throw error;
+        }
+    }
+}
+function shape(kind, result, shaping) {
+    switch (kind) {
+        case "count":
+            return shapeCount(result);
+        case "rows":
+            if (!Array.isArray(result)) {
+                throw new PrismaExecutionError("a many variant owes an array and Prisma answered something else");
+            }
+            return shapeRows(result, shaping);
+        case "row":
+            return result === null || result === undefined
+                ? null
+                : shapeRow(result, shaping);
+    }
+}

package/dist/execution/result.shaper.d.ts

@@ -0,0 +1,103 @@
+import type { AdapterModel } from "@aventara/core";
+import type { PrismaProjectionPlan } from "../translation/projection.translator.js";
+/**
+ * Task 8 / T-8 — the shape core's output validator expects back (C-832, §10.3),
+ * and C-834's inbound value conversion.
+ *
+ * **The envelope is the adapter's to build, not core's.** `output-validator.ts`
+ * accepts exactly `["count"]` or `["data","count"]` for a relation whose plan
+ * carries the `$count` reducer, and rejects any key outside the projection —
+ * which includes Prisma's own `_count` **[CORE, runtime/output-validator.ts]**.
+ * So Prisma's answer `{ id, posts: [...], _count: { posts: 3 } }` must leave here
+ * as `{ id, posts: { data: [...], count: 3 } }`, with `_count` gone.
+ *
+ * **The three §10.3 shapes, and which one applies:**
+ *
+ * | nested select | shape | this module |
+ * |---|---|---|
+ * | `["id","title"]` | array | returns Prisma's rows, values converted |
+ * | `["$count"]` | `{ count }` | reads `_count.<edge>`; no rows were selected |
+ * | `["id","$count"]` | `{ data, count }` | pairs the rows with `_count.<edge>` |
+ *
+ * # C-834's inbound half lives here, and it is keyed by the MODEL
+ *
+ * The same validator that rejects a spare key also checks every projected
+ * scalar's runtime form, and a decimal must be core's own `Decimal`
+ * **[CORE, output-validator.ts → `normalizeScalarFieldValue`]**. Prisma returns an
+ * object whose constructor is `Decimal2`, so before this conversion existed every
+ * read of a decimal column failed core's output validation and the caller was
+ * told `A3000` — measured through `createFramework(...).execute(...)` on both
+ * engines (2026-10-02). The conversion itself belongs to
+ * `translation/scalar.conversion.ts`, the one table that knows how each scalar
+ * crosses the boundary in either direction; this module owns only *which field a
+ * returned value belongs to*.
+ *
+ * **It answers that from the discovered model, not from the value.** The shaper
+ * walks a row against `AdapterModel`: a key that names a scalar field converts
+ * under that field's scalar, a key that names a relation recurses into the edge's
+ * TARGET Resource, and a key the model does not know passes through for core to
+ * accept or reject. Sniffing the runtime shape instead would be wrong in both
+ * directions at once — a `Decimal2` and a `Json` document are both objects, and a
+ * `Json` column holding the string `"12.5"` is indistinguishable from a decimal
+ * string, so the first `Json` column holding numeric text would quietly come back
+ * as a `Decimal`.
+ *
+ * The plan is still what places a `$count` envelope, and only that. The two are
+ * complementary and neither can do the other's job: the plan records only the
+ * edges that need reshaping (so it cannot drive a walk that must reach every
+ * scalar), and the model does not know which edges requested a reducer (so it
+ * cannot place an envelope).
+ *
+ * **Cardinality is never assumed.** `AdapterOperation` carries no plan, and the
+ * arguments the plan is reconstructed from do not say whether an edge is to-one
+ * or to-many. So recursion is driven by the value Prisma actually returned — an
+ * array is shaped elementwise, a record is shaped as one row, `null` passes
+ * through — which is total without knowing the cardinality at all.
+ *
+ * Nothing here invents a number. A missing or non-numeric `_count` entry for a
+ * planned reducer is a translation/driver disagreement, and it raises rather
+ * than defaulting to `0`: a wrong count that validates is worse than a loud
+ * failure, because core would forward it to the caller as fact.
+ *
+ * **Nothing Prisma returned is written into.** A row is copied only when some
+ * value in it actually changed, so a result needing no conversion and no envelope
+ * comes back by identity.
+ */
+/** What a Prisma result must be read against: the model, the Resource, the plan. */
+export type PrismaRowShaping = {
+    /** The discovered model: field kinds, scalars, relation targets. */
+    readonly model: AdapterModel;
+    /** The Aventara Resource key the rows belong to. */
+    readonly resource: string;
+    /** Where the `$count` reducers sit, reconstructed by projection translation. */
+    readonly plan: PrismaProjectionPlan;
+};
+export type PrismaResultShaper = {
+    shapeRow(row: unknown, shaping: PrismaRowShaping): unknown;
+    shapeRows(rows: readonly unknown[], shaping: PrismaRowShaping): readonly unknown[];
+    shapeCount(result: unknown): number;
+};
+/** A provider result the adapter will not reshape into a claim about the data. */
+export declare class PrismaResultShapeError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Converts every scalar in one provider row and places every `$count` envelope.
+ *
+ * @returns the row unchanged, by identity, when no value needed converting and
+ * the plan records no edge that needs reshaping; a copy otherwise. The row Prisma
+ * returned is never mutated.
+ */
+export declare function shapeRow(row: unknown, shaping: PrismaRowShaping): unknown;
+/** Shapes a `many` result: one pass per row. */
+export declare function shapeRows(rows: readonly unknown[], shaping: PrismaRowShaping): readonly unknown[];
+/**
+ * Reads the number a `count` variant must return.
+ *
+ * Prisma answers a bare number from `count` and `{ count }` from `updateMany` /
+ * `deleteMany`; core requires a non-negative safe integer either way
+ * **[CORE, runtime/output-validator.ts]**.
+ */
+export declare function shapeCount(result: unknown): number;
+/** T-8's shaper, as one value the operation executor can hold. */
+export declare const prismaResultShaper: PrismaResultShaper;

package/dist/execution/result.shaper.js

@@ -0,0 +1,141 @@
+import { receiveScalarValue } from "../translation/scalar.conversion.js";
+/** A provider result the adapter will not reshape into a claim about the data. */
+export class PrismaResultShapeError extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = "PrismaResultShapeError";
+    }
+}
+/** Prisma's spelling of the reducer envelope on the parent row. */
+const PRISMA_COUNT_KEY = "_count";
+/** An edge with no reducer anywhere beneath it. */
+const NO_REDUCERS = { relations: [] };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readCount(row, field) {
+    const counts = row[PRISMA_COUNT_KEY];
+    const count = isRecord(counts) ? counts[field] : undefined;
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) {
+        throw new PrismaResultShapeError(`Prisma returned no \`_count\` for the relation "${field}", which requested the $count reducer.`);
+    }
+    return count;
+}
+/** The nested shaping for one edge: its target Resource, and its own plan. */
+function edgeShaping(shaping, field, node) {
+    return {
+        model: shaping.model,
+        resource: field.target,
+        plan: node?.projection ?? NO_REDUCERS,
+    };
+}
+function shapeValue(value, shaping) {
+    if (!Array.isArray(value)) {
+        return shapeRow(value, shaping);
+    }
+    let changed = false;
+    const shaped = value.map((entry) => {
+        const result = shapeRow(entry, shaping);
+        changed ||= result !== entry;
+        return result;
+    });
+    return changed ? shaped : value;
+}
+function shapeReducerRows(value, field, shaping) {
+    if (!Array.isArray(value)) {
+        throw new PrismaResultShapeError(`Prisma returned no row set for the relation "${field}", whose projection requested rows beside the $count reducer.`);
+    }
+    return value.map((entry) => shapeRow(entry, shaping));
+}
+/**
+ * Converts every scalar in one provider row and places every `$count` envelope.
+ *
+ * @returns the row unchanged, by identity, when no value needed converting and
+ * the plan records no edge that needs reshaping; a copy otherwise. The row Prisma
+ * returned is never mutated.
+ */
+export function shapeRow(row, shaping) {
+    if (!isRecord(row)) {
+        return row;
+    }
+    const resource = shaping.model.resources[shaping.resource];
+    if (resource === undefined) {
+        throw new PrismaResultShapeError(`Resource "${shaping.resource}" is not in the discovered model, so the adapter cannot read the row it returned.`);
+    }
+    const nodes = new Map(shaping.plan.relations.map((relation) => [relation.field, relation]));
+    const envelopes = shaping.plan.relations.filter((relation) => relation.reducers.length > 0);
+    let changed = envelopes.length > 0;
+    const shaped = {};
+    for (const [key, value] of Object.entries(row)) {
+        if (key === PRISMA_COUNT_KEY && envelopes.length > 0) {
+            // The reducer pass below reads it; core rejects it as a spare key.
+            continue;
+        }
+        const field = resource.fields[key];
+        if (field === undefined) {
+            // Not a field of this Resource — Prisma's own `_count` with no reducer
+            // planned, or a divergence. Core's output validation owns that verdict.
+            shaped[key] = value;
+            continue;
+        }
+        if (field.kind === "scalar") {
+            const received = receiveScalarValue(shaping.model, field, value, `${shaping.resource}.${key}`);
+            changed ||= received !== value;
+            shaped[key] = received;
+            continue;
+        }
+        const node = nodes.get(key);
+        if (node !== undefined && node.reducers.length > 0) {
+            // Written by the reducer pass, from the raw row.
+            continue;
+        }
+        const nested = shapeValue(value, edgeShaping(shaping, field, node));
+        changed ||= nested !== value;
+        shaped[key] = nested;
+    }
+    for (const relation of envelopes) {
+        const field = resource.fields[relation.field];
+        if (field === undefined || field.kind !== "relation") {
+            throw new PrismaResultShapeError(`The projection requested the $count reducer on "${relation.field}", which is not a relation of Resource "${shaping.resource}".`);
+        }
+        const count = readCount(row, relation.field);
+        const nested = edgeShaping(shaping, field, relation);
+        shaped[relation.field] = relation.rows
+            ? {
+                data: shapeReducerRows(row[relation.field], relation.field, nested),
+                count,
+            }
+            : { count };
+    }
+    return changed ? shaped : row;
+}
+/** Shapes a `many` result: one pass per row. */
+export function shapeRows(rows, shaping) {
+    let changed = false;
+    const shaped = rows.map((row) => {
+        const result = shapeRow(row, shaping);
+        changed ||= result !== row;
+        return result;
+    });
+    return changed ? shaped : rows;
+}
+/**
+ * Reads the number a `count` variant must return.
+ *
+ * Prisma answers a bare number from `count` and `{ count }` from `updateMany` /
+ * `deleteMany`; core requires a non-negative safe integer either way
+ * **[CORE, runtime/output-validator.ts]**.
+ */
+export function shapeCount(result) {
+    const count = isRecord(result) ? result.count : result;
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) {
+        throw new PrismaResultShapeError("Prisma returned no count for a count operation.");
+    }
+    return count;
+}
+/** T-8's shaper, as one value the operation executor can hold. */
+export const prismaResultShaper = {
+    shapeRow,
+    shapeRows,
+    shapeCount,
+};

package/dist/execution/transaction.executor.d.ts

@@ -0,0 +1,147 @@
+import type { AdapterModel, AdapterOperationExecutor } from "@aventara/core";
+import type { PrismaResourceTranslation } from "../discovery/discovery-artifact.interface.js";
+import type { PrismaDelegateHost, PrismaTransactionOptions } from "../prisma-client.interface.js";
+/**
+ * T-9 — `Adapter.transaction`: one interactive Prisma transaction per framework
+ * plan, and the transaction-scoped executor core runs the plan through.
+ *
+ * The body is one `client.$transaction(async (tx) => work(scopedExecutorFor(tx)),
+ * options)`. Everything interesting about this module is what it deliberately
+ * does **not** do, so each omission is recorded here rather than left to be
+ * rediscovered.
+ *
+ * # The callback form, never the array form (C-803)
+ *
+ * Prisma's array form — `$transaction` applied to a list of prepared calls —
+ * cannot honour a plan at all. An Aventara plan is
+ * **sequential by contract**: operation *n* may carry a `$ref` resolved from
+ * operation *n − 1*'s final data, and core resolves it between calls, so the
+ * second call's arguments do not exist until the first has answered. The array
+ * form takes every call up front. It is therefore a framework invariant and not
+ * a preference, and it is protected twice: {@link PrismaDelegateHost} declares
+ * `$transaction` in its callback form only, so the array overload is not
+ * *representable* through the seam this adapter holds, and
+ * `transaction.executor.spec.ts` asserts both that every call this adapter makes
+ * passes a function and that the array form's own opening token occurs nowhere in
+ * `src` (that spec assembles the token rather than writing it, for the same
+ * reason this sentence does not quote it).
+ *
+ * # The root client is unreachable from inside (C-804)
+ *
+ * `scopedExecutorFor` closes over the callback's `tx` and nothing else, so no
+ * plan operation can reach the client this module was constructed with — there is
+ * no path to it from the value core is handed. `scope: "transaction"` additionally
+ * tells `operation.executor.ts` that an emulated first-style variant must reuse
+ * this transaction rather than open its own (D-807): inside a plan a nested
+ * savepoint would let the emulation roll back independently of the plan, which
+ * §14.5 forbids.
+ *
+ * # No `try`, no `catch`, no wrapper (C-805, C-806)
+ *
+ * Core throws a private frozen abort sentinel out of `work` after it has recorded
+ * a failing operation, and recognises the rejection **by `===` alone**. Prisma
+ * 7.10.0 rethrows the caught value by reference after a best-effort rollback
+ * **[P7R Q3]**, so the contract is met by *adding nothing*: a `catch` that
+ * re-threw anything — even `error` wrapped in context — would turn every plan
+ * failure into core's `foreign-abort` integrity failure and lose the operation's
+ * own code.
+ *
+ * **Prisma swallows its own rollback failures.** The rollback call's rejection is
+ * caught and handed to an internal debug logger — `await
+ * this._engine.transaction("rollback", …).catch(E => { kt("rollback attempt
+ * %d/%d failed: %O", …) })`, with `kt = debug("prisma:client")` **[PKG,
+ * `runtime/client.js`; P7R Q4]** — so a failed rollback never reaches this
+ * module. **Induced, not assumed** (2026-10-02, PostgreSQL 18): a write inside a
+ * transaction, the backend terminated from a second connection, a frozen sentinel
+ * thrown from the callback. Prisma's `ROLLBACK` failed — `prisma:client rollback
+ * attempt 1/1 failed: '{}'` appears under `DEBUG=prisma*` — and the value the
+ * caller received was still that sentinel, by identity, carrying nothing about the
+ * rollback at all. Two consequences, both deliberate: core's `A3002`-on-rollback-
+ * failure branch is **unreachable with this adapter** (it stays for adapters whose
+ * provider reports the failure), and this adapter never claims a rollback
+ * succeeded, because it cannot observe that it did. A commit failure is different:
+ * it is thrown from inside the same `try` and rejects like a callback throw.
+ *
+ * # `maxWait`, `timeout` and `isolationLevel` are adapter-owned (D-806, F-702)
+ *
+ * They are provider concepts: core's `Adapter.transaction(work)` carries no
+ * options and must not grow any, so they are set once at
+ * `createPrismaAdapter({ transactionOptions })` and are not part of Aventara's
+ * public configuration. Prisma's own defaults stand when they are absent —
+ * `maxWait` 2000 ms, `timeout` 5000 ms **[PKG, `runtime/client.d.ts`]** — and the
+ * supported isolation levels come from the provider profile, which discovered
+ * them, rather than from a table written here.
+ *
+ * The options are **not** forwarded to the scoped executor. At `"transaction"`
+ * scope `operation.executor.ts` never opens a transaction, so an option passed
+ * there would be dead configuration that reads as if it did something.
+ *
+ * # `P2028`, as measured rather than as documented (C-821, D-808)
+ *
+ * Induced against PostgreSQL 18 on `@prisma/client` 7.10.0, 2026-10-02 (the
+ * assertions live in `conformance/postgres.conformance.spec.ts`):
+ *
+ * ```text
+ * timeout 1 ms, a query issued after expiry
+ *   P2028  meta = { modelName: "Author", operation: "query", timeout: 1, timeTaken: 66 }
+ * timeout 1 ms, no query after the sleep — the COMMIT is what fails
+ *   P2028  meta = { operation: "commit", timeout: 1, timeTaken: 62 }
+ * maxWait 1 ms with the one connection already held by another transaction
+ *   P2028  meta = {}                     <- EMPTY
+ * isolationLevel: "Bogus"
+ *   P2023  meta = { providedIsolationLevel: "Bogus" }   <- NOT P2028
+ * ```
+ *
+ * The table above is the `isolationLevel` arm only as far as a **malformed** level
+ * goes. A level that IS one of Prisma's five and is simply unsupported by the
+ * provider reaches the transaction manager and raises a `meta`-carrying `P2028` of
+ * its own, measured on both engines (2026-10-02):
+ *
+ * ```text
+ * isolationLevel: "Snapshot"  (a SQL Server level; one of Prisma's five)
+ *   P2028  meta = { isolationLevel: "SNAPSHOT" }
+ * ```
+ *
+ * So of the seven `P2028` classes in 7.10.0 — `TransactionManagerError` plus
+ * `nt`/`un`/`cn`/`fr`/`pn`/`Me`/`dn` **[PKG, `runtime/client.js`]** — the
+ * separable-by-`meta` set is **three**: the transaction-timeout expiry carries
+ * `{ operation, timeout, timeTaken }`, the unsupported isolation level carries
+ * `{ isolationLevel }`, and the acquisition timeout carries nothing and is
+ * separable *by* that emptiness from the other two. It is **not** separable from
+ * the four remaining classes: transaction-not-found, already-committed,
+ * already-rolled-back and internal-consistency all arrive as `P2028` with no
+ * `meta` at all, and telling those five apart needs the message text, which
+ * ADR 0006 forbids. C-821's claim that the invalid isolation level is a
+ * `meta`-carrying `P2028` subclass therefore **holds**, by a narrower route than
+ * C-821 states: only a level Prisma's own union does not contain is rejected by
+ * the query compiler first, as `P2023`. An earlier revision of this comment
+ * withdrew the claim outright; it was measured on the wrong input, and
+ * `conformance/postgres.conformance.spec.ts` and
+ * `conformance/sqlite.conformance.spec.ts` both assert the corrected fact.
+ *
+ * D-808's outcome — `P2028` → `A3002 TRANSACTION_ERROR` — needs no row in the
+ * adapter's P-code table to hold, and that is the honest reading of **where** it
+ * holds. A `P2028` that ends the transaction rejects out of `$transaction` itself,
+ * is not core's sentinel, and core's own `infrastructureFailure` answers `A3002`.
+ * A `P2028` raised by a *delegate call* inside the callback is a different route:
+ * it is unclassified by the closed table, so core's `AdapterBoundary` attributes
+ * `A3001` to that operation. `A3002` is therefore the answer for the failure that
+ * ends the transaction, not a uniform answer for the code — recorded here because
+ * the difference is invisible from the table alone.
+ */
+export type PrismaTransactionExecutorDependencies = {
+    /** The client the transaction is opened on: the application's own. */
+    readonly client: PrismaDelegateHost;
+    readonly model: AdapterModel;
+    /** The generate-time translation table (Prisma addressing per Resource). */
+    readonly translation: Readonly<Record<string, PrismaResourceTranslation>>;
+    /** Adapter-owned, never Aventara public configuration (D-806). */
+    readonly transactionOptions?: PrismaTransactionOptions;
+};
+/**
+ * `Adapter<M>["transaction"]` without the optionality: the adapter mounts it
+ * exactly when the discovered model declares `transactions: "interactive"`
+ * (D-805, DA-12), so the function itself is total.
+ */
+export type PrismaTransactionRunner<M extends AdapterModel> = <T>(work: (executor: AdapterOperationExecutor<M>) => Promise<T>) => Promise<T>;
+export declare function createPrismaTransactionExecutor<M extends AdapterModel>(dependencies: PrismaTransactionExecutorDependencies): PrismaTransactionRunner<M>;

package/dist/execution/transaction.executor.js

@@ -0,0 +1,13 @@
+import { createPrismaOperationExecutor } from "./operation.executor.js";
+export function createPrismaTransactionExecutor(dependencies) {
+    const options = dependencies.transactionOptions;
+    const scopedExecutorFor = (transactional) => createPrismaOperationExecutor({
+        client: transactional,
+        model: dependencies.model,
+        translation: dependencies.translation,
+        scope: "transaction",
+    });
+    return (work) => options === undefined
+        ? dependencies.client.$transaction(async (transactional) => work(scopedExecutorFor(transactional)))
+        : dependencies.client.$transaction(async (transactional) => work(scopedExecutorFor(transactional)), options);
+}

package/dist/generate/artifact.emitter.d.ts

@@ -0,0 +1,50 @@
+import type { PrismaAdapterModel, PrismaReferentialActionTable, PrismaTranslationTable } from "../discovery/discovery-artifact.interface.js";
+import type { PrismaProvider } from "../provider/provider-profile.js";
+/**
+ * T-3.2 under **ADR 0009 (Accepted), which overrides the plan**: the discovery
+ * artifact is **one TypeScript module**, not JSON.
+ *
+ * The plan's T-3.2 says JSON. It predates the ADR and loses to it, for a reason
+ * the ADR states plainly: `resolveJsonModule` widens `"string"` to `string`, so
+ * a JSON model carries no literals, and carrying them would take a second
+ * emitted `.d.ts` beside the data — two emissions from one source, which can
+ * drift. One module written `as const satisfies AdapterModel` makes the value
+ * and the type the same expression, so drift is not merely detectable but
+ * unrepresentable.
+ *
+ * The emitted module is still passive, serializable, introspectable, hashable
+ * and free of runtime callbacks (C-841). It contains three `const` bindings and
+ * no executable statement; `discovery.model` and `discovery.translation`
+ * *reference* their bindings rather than restating them, so there is exactly one
+ * representation of each half in the file.
+ *
+ * **Three halves, and the seam between them is deliberate.** `model` is what
+ * core consumes: canonicalized, digested into `modelHash`, and compiled into the
+ * Contract. `translation` is Prisma addressing — which key a `WhereUniqueInput`
+ * answers to for each identifier. `referentialActions` is what deleting a parent
+ * row does to its children, resolved. Both of the latter sit BESIDE the model
+ * precisely because they must not reach the hash: a `@@unique(name:)` rename
+ * carries no semantic content, and inside the model it would change the Contract
+ * identity and force every generated client to be regenerated for nothing; a
+ * referential action is not part of the model at all, and inside it the action
+ * would reach the compiled Contract and the ClientContract, which have no word
+ * for one.
+ *
+ * **Determinism (C-843).** The model text is the canonical JSON core already
+ * uses for Contract identity, re-indented — not `JSON.stringify` over whatever
+ * key order the readers happened to build. So two generate runs over one schema
+ * emit byte-identical modules, and `modelHash` is a digest of exactly the bytes
+ * the module carries, computed by the same `computeModelHash` the runtime
+ * loader checks it with. One hash function, one canonicalization, both halves.
+ */
+export type PrismaArtifactEmission = {
+    /** e.g. `"7.10.0"`; only the major is fenced at load (C-846). */
+    readonly prismaVersion: string;
+    readonly provider: PrismaProvider;
+    readonly model: PrismaAdapterModel;
+    /** Prisma addressing per Resource — emitted beside `model`, outside the hash. */
+    readonly translation: PrismaTranslationTable;
+    /** Resolved referential actions per Resource — also beside `model`, also outside the hash. */
+    readonly referentialActions: PrismaReferentialActionTable;
+};
+export declare function emitDiscoveryArtifactModule(emission: PrismaArtifactEmission): Promise<string>;