@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/errors/error.normalizer.d.ts

@@ -0,0 +1,250 @@
+import { FrameworkError, type OperationErrorCode, type OperationIdentity } from "@aventara/core";
+import { type PrismaConstraintSubject } from "./prisma-error.reader.js";
+/**
+ * T-10 — error normalization: one closed table from `@prisma/client` 7.x
+ * P-codes to Aventara outcomes, and nothing else.
+ *
+ * ## Version bound (C-846)
+ *
+ * The table's keys are P-codes, which are **7.x's** error surface. Prisma 8
+ * replaced them with dotted `NAMESPACE.SUBCODE` codes, so a Prisma 8
+ * adapter re-maps this module rather than patching it.
+ * `error.normalizer.spec.ts` reads `@prisma/client`'s own `package.json`
+ * and fails if the installed major is not `7`, so the bound is enforced
+ * rather than described.
+ *
+ * ## Every code in the table was induced, not inherited
+ *
+ * Nothing here rests on documentation. Each rule was produced by throwing a
+ * real statement at a real engine on this repository's own schema, on
+ * `@prisma/adapter-better-sqlite3` and `@prisma/adapter-pg`, both 7.10.0.
+ * The measured payloads, inlined because the source measurement lives
+ * outside the repository:
+ *
+ * ```text
+ * P2002  author.create duplicate @unique email
+ *   sqlite  meta = { driverAdapterError: { name: "DriverAdapterError", cause: {
+ *             originalCode: "SQLITE_CONSTRAINT_UNIQUE",
+ *             originalMessage: "UNIQUE constraint failed: Author.email",
+ *             kind: "UniqueConstraintViolation",
+ *             constraint: { fields: ["email"] }, table: "Author" } },
+ *           modelName: "Author" }
+ *   pg      meta = { driverAdapterError: { name: "DriverAdapterError", cause: {
+ *             originalCode: "23505",
+ *             originalMessage: "duplicate key value violates unique constraint \"Author_email_key\"",
+ *             kind: "UniqueConstraintViolation",
+ *             constraint: { index: "Author_email_key" }, table: "Author" } },
+ *           modelName: "Author" }
+ *
+ * P2002  author.create violating @@unique([tenantId, handle])
+ *   sqlite  constraint: { fields: ["tenantId", "handle"] }
+ *   pg      constraint: { index: "Author_tenantId_handle_key" }
+ *
+ * P2003  post.create with an authorId that does not exist
+ *   sqlite  meta = { modelName: "Post", driverAdapterError: { cause: {
+ *             originalCode: "SQLITE_CONSTRAINT_FOREIGNKEY",
+ *             originalMessage: "FOREIGN KEY constraint failed",
+ *             kind: "ForeignKeyConstraintViolation",
+ *             constraint: { foreignKey: {} } } } }
+ *   pg      constraint: { index: "Post_authorId_fkey" }, originalCode "23503"
+ *
+ * P2025  author.update / author.delete on a missing unique selector
+ *   both    meta = { modelName: "Author", operation: "an update" }
+ *   both    meta = { modelName: "Author", operation: "a delete" }
+ *
+ * P2025  nested connect whose target does not exist (create, update, upsert)
+ *   both    meta = { modelName: "Post", model: "Author",
+ *                    relation: "AuthorToPost", relationType: "one-to-many",
+ *                    operation: "a nested connect",
+ *                    neededFor: "inline the relation on 'Post' record(s)" }
+ *
+ * P2018  author.update with posts.connect to a missing post
+ *   sqlite  meta = { modelName: "Author", expectedRows: 1,
+ *                    relation: "AuthorToPost", relationType: "one-to-many" }
+ *
+ * P2034  two SERIALIZABLE transactions, both reading then both writing
+ *   pg      meta = { modelName: "Author", driverAdapterError: { cause: {
+ *             originalCode: "40001",
+ *             originalMessage: "could not serialize access due to concurrent update",
+ *             kind: "TransactionWriteConflict" } } }
+ * ```
+ *
+ * ## Two inherited claims that the measurement refutes
+ *
+ * 1. **`meta.errorIdentifier` does not exist.** D-811 and the error-code map
+ *    both state that P2025's cases are told apart by
+ *    `meta.errorIdentifier` (`MISSING_RECORD` / `MISSING_RELATED_RECORD` /
+ *    `INCOMPLETE_CONNECT_INPUT`), and both marked it unverified at the meta
+ *    level. It is **absent from every payload above**; the identifiers are
+ *    internal rule names, not a `meta` key. What 7.10.0 actually emits is
+ *    two different *key sets*, and the discriminant is the presence of
+ *    `meta.relation` (with `meta.model`): present → the failure is about a
+ *    relation reference; absent → the record the call selected was not
+ *    there. That is structural, which is what ADR 0006 requires — the
+ *    alternative, `meta.operation`, is English prose.
+ * 2. **`meta.target` is never emitted.** RC-9's open question is answered:
+ *    the v7 docs are stale (see `PrismaErrorFacts.legacyTarget`).
+ *
+ * Also unobserved: the `{}` meta that `expectNonEmpty` was expected to
+ * carry. `findUniqueOrThrow` and `findFirstOrThrow` both report
+ * `{ modelName, operation: "a query" }`, so no empty-meta P2025 was
+ * produced by any statement tried here. Either arm classifies identically
+ * under the rule above (no `relation` → root record), so the rule is safe
+ * either way, but the shape itself stays unverified.
+ *
+ * ## RC-8 is decided, and this measurement is what decided it
+ *
+ * Three distinct situations used to answer the one `A2008 CONFLICT`. Coarse
+ * but correct, so nothing provisional ever reached the wire and the
+ * discriminant was purely additive (RC-8, D-831). The architect assented
+ * (2026-10-02) to the discrimination this measurement showed to be available:
+ * `A2008` now means the **constraint** case alone, a write conflict or
+ * deadlock answers **`A2013 CONCURRENT_MODIFICATION`**, and the lost-row race
+ * answers **`A2014 STALE_SELECTION`** from the emulator's own seam. The
+ * observed surface each decision rests on is this:
+ *
+ * | Situation | Code | `meta` keys observed | Structurally separable? |
+ * |---|---|---|---|
+ * | Uniqueness violation | `P2002` | `modelName`, `driverAdapterError` | **Yes** — distinct P-code; `cause.kind` is `"UniqueConstraintViolation"`; `cause.constraint` is `{fields}` (SQLite) or `{index}` (PostgreSQL) |
+ * | Write conflict / deadlock | `P2034` | `modelName`, `driverAdapterError` | **Yes** from a constraint violation — distinct P-code; `cause.kind` is `"TransactionWriteConflict"`; **no** `constraint` at all. **No** from each other: `cause.originalCode` is `40001` for a write conflict and `40P01` for a deadlock, and that field is provider-owned and never crosses the boundary |
+ * | Lost-row race | *none* | *none* | **Yes, trivially** — there is no provider error behind it: it is a zero-row count in a sequence the framework manufactured, and it is raised in `execution/first-variant.emulator.ts`, never here |
+ *
+ * So all three are separable **without reading any message text**, which is
+ * what ADR 0006 requires and what C-821 warns `P2028` cannot offer, and that
+ * is why the discrimination is implemented by P-code and by call site alone.
+ * The two provider-backed ones differ by P-code; `driverAdapterError.cause.kind`
+ * is a second, independent witness.
+ *
+ * **A write conflict and a deadlock share `A2013` deliberately.** Both arrive
+ * as `P2034` with identical `meta` keys, differing only in a provider-owned
+ * `originalCode` (`40001` versus `40P01`) that never crosses the boundary.
+ * They are not separable at this seam, so one outcome is the only honest
+ * answer; splitting them later would need a discriminant that does not exist. `describePrismaConflict` is the recorded
+ * surface, and `PrismaConstraintSubject` records that the two engines do not
+ * agree on *which* identifier they can name — a uniqueness discriminant that
+ * promised the caller the constraint's name would be unsatisfiable on SQLite.
+ *
+ * ## F-608 / D-816 — what was observed about non-`Error` throws
+ *
+ * **No Prisma path observed here threw a non-`Error`.** Every induced failure
+ * arrived as a `PrismaClientKnownRequestError`, which extends `Error`
+ * (`error instanceof Error` was asserted true for all of them), and the one
+ * non-Prisma failure the engines produced — `better-sqlite3` refusing a
+ * missing directory — was a `TypeError`. So the primitive-throw ambiguity
+ * F-608 describes did not arise for the only real adapter that exists, and
+ * the general fix (boxing primitive Adapter throws at core's seam) has no
+ * demonstrated urgency. That observation, not a guess, is what Task 14 (§14a)
+ * judges the row on. The adapter half is discharged here:
+ * `prismaOutcomeFailure` returns a `FrameworkError`, so every failure this
+ * module originates is an `Error` subclass, enforced by a spec.
+ *
+ * ## F-723 — why nothing leaks today
+ *
+ * A deliberate `FrameworkError`'s top-level `cause.message` is forwarded
+ * verbatim; that channel is still open and is Phase 13's. What keeps it from
+ * leaking is this module's own rule (C-819): the cause is framework text, and
+ * the reader never reads `message` at all, so there is no provider string in
+ * scope to forward. If that rule is ever relaxed, the leak is immediate —
+ * which is the input Phase 13 should receive.
+ */
+/** The three answers a Prisma failure can get. T-10, verbatim. */
+export type PrismaErrorClassification = {
+    readonly kind: "absence";
+} | {
+    readonly kind: "outcome";
+    readonly code: OperationErrorCode;
+} | {
+    readonly kind: "unclassified";
+};
+/**
+ * When a code is a `null` result rather than a failure (D-811).
+ *
+ * `variants` is read literally from D-811: Prisma's `update`/`delete` throw
+ * P2025 when the selector matches nothing, and core's outcome mapper turns a
+ * returned `null` into `A2003 NOT_FOUND` for exactly those two variants, so
+ * the adapter hands back `null` instead of inventing a failure.
+ *
+ * `subject` is the measured `meta` shape that may be forgiven. The same
+ * P2025 reaches `update.unique` for a second reason — a nested `connect`
+ * whose target is missing — and that one is a caller error about the
+ * *arguments*, not an absent record. `"root-record"` means `meta` carries no
+ * relation reference; the single-member union says that is the one shape
+ * measured, and leaves room for a second if one is ever observed.
+ */
+type PrismaAbsenceRule = {
+    readonly variants: readonly `${string}.${string}`[];
+    readonly subject: "root-record";
+};
+type PrismaErrorRule = {
+    /**
+     * The outcome this code answers. Typed as core's own
+     * `OperationErrorCode`, so the adapter cannot widen the code space —
+     * a code the table does not contain has no rule at all (C-838).
+     */
+    readonly outcome: OperationErrorCode;
+    readonly absence?: PrismaAbsenceRule;
+};
+/** One closed table, scoped to `@prisma/client` 7.x (C-846). */
+export type PrismaErrorTable = Readonly<Record<string, PrismaErrorRule>>;
+/**
+ * The installed-major this table is written against. The spec asserts the
+ * installed `@prisma/client` agrees.
+ */
+export declare const PRISMA_ERROR_TABLE_MAJOR = "7";
+/**
+ * Every code here was induced above. Codes that 7.10.0 *can* raise but that
+ * no statement here produced — `P2000`, `P2011`, `P2014`, `P2017`, `P2020`,
+ * `P2023`, `P2010`, `P2028`, `P2029`, `P2030`, `P2036`, `P2037`, `P2039`,
+ * `P1008`, `P1017`, `P1018` — are **deliberately absent**: an unmeasured
+ * rule is a guess, and D-812's answer for anything unrecognised is to leave
+ * it to core's `AdapterBoundary`, which reports `A3001 ADAPTER_ERROR` with
+ * core's own text and sends the raw error to diagnostics. Adding a row
+ * later is additive and costs nothing; shipping a wrong one is not
+ * recoverable.
+ */
+export declare const PRISMA_ERROR_TABLE: PrismaErrorTable;
+/**
+ * Classifies one failed Prisma call.
+ *
+ * `error` is `unknown` and stays `unknown`: the reader is the only thing
+ * that touches it, and the rules see nothing but measured facts. The
+ * operation is needed because D-811's answer depends on the variant the
+ * caller asked for, which is framework knowledge and not in the error.
+ */
+export declare function classifyPrismaError(error: unknown, operation: Pick<OperationIdentity, "family" | "variant">): PrismaErrorClassification;
+/**
+ * The deliberate failure an `outcome` classification stands for.
+ *
+ * It is a `FrameworkError`, so every failure this adapter originates is an
+ * `Error` subclass — D-816's adapter half, which needs no core change.
+ *
+ * The cause carries framework text and nothing else: no issues, and that is
+ * now the **rule** rather than an absence (C-839, ADR 0008 decision 4). A
+ * conflict is not a Framework Validation Layer failure, ADR 0008 decision 1
+ * makes a V-code *determine* the A-code, and `validationCode` rolls up to only
+ * `A2001`/`A2002`/`A2004`/`A2007`/`A2009` — so a conflict V-code would have no
+ * legal rollup, which is why `A2008`, `A2013` and `A2014` pair with none and
+ * carry `cause.issues` absent. And no provider text, because a deliberate
+ * outcome's top-level `cause.message` is forwarded verbatim (C-819, F-723).
+ * Nothing read off the Prisma error reaches this value.
+ */
+export declare function prismaOutcomeFailure(code: OperationErrorCode): FrameworkError;
+/**
+ * What RC-8 will discriminate on, recorded rather than re-measured.
+ *
+ * **Server-side only.** Every field is provider-owned, so this value never
+ * reaches a `cause` — which is why it is a separate function and not a field
+ * on `PrismaErrorClassification`: nothing can carry it onto the wire by
+ * accident. It is the measurement that answered §14c — whether the three
+ * situations once collapsed into `A2008` are *structurally* separable, which
+ * they are — and it remains the record of what a diagnostics sink could
+ * usefully be told.
+ */
+export type PrismaConflictSubject = {
+    readonly code: string;
+    readonly model: string | undefined;
+    readonly constraint: PrismaConstraintSubject | undefined;
+    readonly metaKeys: readonly string[];
+};
+export declare function describePrismaConflict(error: unknown): PrismaConflictSubject | undefined;
+export {};

package/dist/errors/error.normalizer.js

@@ -0,0 +1,135 @@
+import { FrameworkError, } from "@aventara/core";
+import { readPrismaError, } from "./prisma-error.reader.js";
+/**
+ * The installed-major this table is written against. The spec asserts the
+ * installed `@prisma/client` agrees.
+ */
+export const PRISMA_ERROR_TABLE_MAJOR = "7";
+/**
+ * Every code here was induced above. Codes that 7.10.0 *can* raise but that
+ * no statement here produced — `P2000`, `P2011`, `P2014`, `P2017`, `P2020`,
+ * `P2023`, `P2010`, `P2028`, `P2029`, `P2030`, `P2036`, `P2037`, `P2039`,
+ * `P1008`, `P1017`, `P1018` — are **deliberately absent**: an unmeasured
+ * rule is a guess, and D-812's answer for anything unrecognised is to leave
+ * it to core's `AdapterBoundary`, which reports `A3001 ADAPTER_ERROR` with
+ * core's own text and sends the raw error to diagnostics. Adding a row
+ * later is additive and costs nothing; shipping a wrong one is not
+ * recoverable.
+ */
+export const PRISMA_ERROR_TABLE = {
+    // Uniqueness conflict — caller-actionable state conflict, HTTP 409 (D-810, C-820).
+    P2002: { outcome: "A2008" },
+    // Foreign-key violation — an invalid reference is the same class of
+    // conflict, and D-810 maps it to the same code. These two are what
+    // `A2008` now means, and the whole of it: re-running either request
+    // unchanged fails the same way, which is what separates them from
+    // `A2013`/`A2014`.
+    P2003: { outcome: "A2008" },
+    // Write conflict or deadlock: another operation reached the same state
+    // first, so nothing this one asked for was applied. Both arrive as P2034
+    // and are not separable at this seam, so they share one outcome. Prisma
+    // performs no automatic retry and this adapter adds none (C-822, D-809,
+    // F-705): a retried plan would re-run developer callbacks whose side
+    // effects are not rollback-safe. A retry is the caller's to make.
+    P2034: { outcome: "A2013" },
+    // The required connected records were not found: measured only with a
+    // relation reference in `meta`, and always about the arguments.
+    P2018: { outcome: "A2004" },
+    // Depends on records that were required but not found. A caller error
+    // about the arguments by default; a `null` result on the two strict
+    // unique variants, and only when the missing record is the one the call
+    // selected rather than a relation target (D-811).
+    P2025: {
+        outcome: "A2004",
+        absence: {
+            variants: ["update.unique", "delete.unique"],
+            subject: "root-record",
+        },
+    },
+};
+/** Framework-owned text, one line per code it may emit. */
+const OUTCOME_MESSAGES = {
+    // `A2008` now means the constraint case alone, and its text is
+    // UNCHANGED on purpose. §13.2's narrowed meaning — "would violate a
+    // uniqueness or reference constraint the Resource declares" — is
+    // documentation, NOT a legal wire message: C-819's measured sweeps ban
+    // `constraint`, `Unique` and `UNIQUE` from a provider-originated
+    // envelope, because those are the provider's own words for this very
+    // failure. Narrowing the code's meaning does not license naming the
+    // constraint to the caller, and this line is what keeps the two apart.
+    A2008: "The operation conflicts with the current state of the resource.",
+    A2013: "Another operation modified the same state concurrently, so this operation was not applied and nothing was written.",
+    A2004: "The operation's arguments referenced a record that does not exist.",
+};
+/**
+ * `"root-record"`: the failure is about the record the call selected, not
+ * about a relation target. Measured discriminant, not message text.
+ */
+function matchesAbsenceSubject(subject, facts) {
+    switch (subject) {
+        case "root-record":
+            return facts.relation === undefined;
+    }
+}
+/**
+ * Classifies one failed Prisma call.
+ *
+ * `error` is `unknown` and stays `unknown`: the reader is the only thing
+ * that touches it, and the rules see nothing but measured facts. The
+ * operation is needed because D-811's answer depends on the variant the
+ * caller asked for, which is framework knowledge and not in the error.
+ */
+export function classifyPrismaError(error, operation) {
+    const facts = readPrismaError(error);
+    if (facts.code === undefined) {
+        return { kind: "unclassified" };
+    }
+    const rule = Object.hasOwn(PRISMA_ERROR_TABLE, facts.code)
+        ? PRISMA_ERROR_TABLE[facts.code]
+        : undefined;
+    if (rule === undefined) {
+        return { kind: "unclassified" };
+    }
+    const { absence } = rule;
+    if (absence === undefined) {
+        return { kind: "outcome", code: rule.outcome };
+    }
+    const forgiven = absence.variants.includes(`${operation.family}.${operation.variant}`) &&
+        matchesAbsenceSubject(absence.subject, facts);
+    return forgiven
+        ? { kind: "absence" }
+        : { kind: "outcome", code: rule.outcome };
+}
+/**
+ * The deliberate failure an `outcome` classification stands for.
+ *
+ * It is a `FrameworkError`, so every failure this adapter originates is an
+ * `Error` subclass — D-816's adapter half, which needs no core change.
+ *
+ * The cause carries framework text and nothing else: no issues, and that is
+ * now the **rule** rather than an absence (C-839, ADR 0008 decision 4). A
+ * conflict is not a Framework Validation Layer failure, ADR 0008 decision 1
+ * makes a V-code *determine* the A-code, and `validationCode` rolls up to only
+ * `A2001`/`A2002`/`A2004`/`A2007`/`A2009` — so a conflict V-code would have no
+ * legal rollup, which is why `A2008`, `A2013` and `A2014` pair with none and
+ * carry `cause.issues` absent. And no provider text, because a deliberate
+ * outcome's top-level `cause.message` is forwarded verbatim (C-819, F-723).
+ * Nothing read off the Prisma error reaches this value.
+ */
+export function prismaOutcomeFailure(code) {
+    return new FrameworkError(code, {
+        message: OUTCOME_MESSAGES[code] ?? "The operation could not be completed.",
+    });
+}
+export function describePrismaConflict(error) {
+    const facts = readPrismaError(error);
+    if (facts.code === undefined) {
+        return undefined;
+    }
+    return {
+        code: facts.code,
+        model: facts.modelName,
+        constraint: facts.constraint,
+        metaKeys: facts.metaKeys,
+    };
+}

package/dist/errors/prisma-error.reader.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The total read of one hostile value (T-10's first half).
+ *
+ * Everything on the failure path arrives as `unknown`. `@prisma/client`
+ * 7.10.0 raises `PrismaClientKnownRequestError`, whose `meta` is typed
+ * `Record<string, unknown>` and is **not** a discriminated union, so a
+ * reader that trusts the type would be reading a shape nobody promised.
+ * Worse, the value need not come from Prisma at all: a developer callback,
+ * a driver, or a proxy can hand the adapter anything.
+ *
+ * So this module reads structurally and defensively, under two rules it
+ * never relaxes — the same totality discipline as core's diagnostics
+ * reporter, which also observes values it cannot vouch for:
+ *
+ * 1. **No accessor is ever invoked.** Every read goes through
+ *    `Object.getOwnPropertyDescriptor` and takes `descriptor.value`. An
+ *    accessor descriptor yields `undefined` and its getter is never called,
+ *    so a booby-trapped property cannot run code, mutate state, or throw
+ *    from inside the adapter's failure path.
+ * 2. **Nothing escapes.** Every reflective call is guarded, because a Proxy
+ *    may throw from its `getOwnPropertyDescriptor` or `ownKeys` trap, and a
+ *    reader that throws while classifying a failure would replace a legible
+ *    outcome with an illegible one.
+ *
+ * Reading only *own* properties is deliberate rather than incidental:
+ * 7.10.0 carries `code` and `meta` as own data properties (observed own
+ * keys: `["code","meta","clientVersion","name"]`), so the own read is
+ * sufficient for every real error, and a `code` that exists only as an
+ * inherited accessor is precisely the case rule 1 refuses to touch.
+ *
+ * ## What this module does NOT read
+ *
+ * `message` is never read. At 7.10.0 a `PrismaClientKnownRequestError`
+ * message is not a sentence — it is a rendered call site. Measured
+ * verbatim on this repository's own schema:
+ *
+ * ```text
+ * Invalid `client.author.create()` invocation in
+ * /home/.../packages/prisma7-adapter/src/errors/__probe__.spec.ts:50:18
+ *
+ *   49 await capture("P2002 duplicate email", () =>
+ * → 50 	client.author.create(
+ * Unique constraint failed on the fields: (`email`)
+ * ```
+ *
+ * That single string carries an absolute file path, a source excerpt and
+ * the violated constraint. C-819 forbids all three from reaching `cause`,
+ * and a *deliberate* outcome's top-level `cause.message` is still forwarded
+ * verbatim (register row F-723, open). The cheapest guarantee is not to
+ * read the message at all, so the leak has no source; the raw error still
+ * reaches core's diagnostics sink, which is server-side and may carry it.
+ *
+ * ## Version bound (C-846)
+ *
+ * Everything below is scoped to `@prisma/client` **7.x**. Prisma 8 replaced
+ * P-codes with dotted `NAMESPACE.SUBCODE` codes, which makes a Prisma 8
+ * adapter a re-map of this module rather than a patch to it.
+ */
+/**
+ * The violated constraint as 7.10.0's driver adapters actually report it,
+ * at `meta.driverAdapterError.cause.constraint` (D-810).
+ *
+ * The arms are **provider-shaped, measured on both engines**, not guessed:
+ *
+ * | Engine                            | Unique (P2002)                | Foreign key (P2003)     |
+ * |-----------------------------------|-------------------------------|-------------------------|
+ * | `@prisma/adapter-better-sqlite3`  | `{ fields: ["email"] }`       | `{ foreignKey: {} }`    |
+ * | `@prisma/adapter-pg`              | `{ index: "Author_email_key" }` | `{ index: "Post_authorId_fkey" }` |
+ *
+ * It is therefore **not a string**, and the two engines do not agree on
+ * which identifier they can name — SQLite names columns, PostgreSQL names
+ * the index. Every arm's payload is provider-owned text and never crosses
+ * the boundary (C-819); the *shape* is kept because it is structurally
+ * separable, which is what RC-8 needs from Task 12.
+ */
+export type PrismaConstraintSubject = {
+    readonly kind: "fields";
+    readonly fields: readonly string[];
+} | {
+    readonly kind: "index";
+    readonly index: string;
+} | {
+    readonly kind: "foreign-key";
+} | {
+    readonly kind: "unreadable";
+};
+/**
+ * Everything the normalizer is allowed to know about one failed call.
+ *
+ * Narrow and flat on purpose: a classification rule reads these fields and
+ * nothing else, so no rule can reach back into the raw value and no rule
+ * can depend on a shape this module has not measured.
+ */
+export type PrismaErrorFacts = {
+    /**
+     * The P-code, when it is an own string property. A missing or non-string
+     * `code` leaves this `undefined`, which the table answers as
+     * `unclassified` — never as a guess (D-812).
+     */
+    readonly code: string | undefined;
+    /**
+     * The own, enumerable key names of `meta`, in the order 7.10.0 wrote
+     * them. This is the *structural* signature of a failure, and the only
+     * discriminant ADR 0006 permits: it forbids inferring an outcome from
+     * error text, and `meta.operation` is English prose (`"an update"`,
+     * `"a delete"`, `"a query"`, `"a nested connect"`).
+     */
+    readonly metaKeys: readonly string[];
+    /** `meta.modelName` — the Prisma model the failure occurred on. */
+    readonly modelName: string | undefined;
+    /**
+     * `meta.relation` — present exactly when the failure is about a
+     * *relation reference* rather than about the record the call selected.
+     * This is the measured discriminant behind D-811 (see the normalizer).
+     */
+    readonly relation: string | undefined;
+    /** `meta.model` — the model at the far end of `relation`. */
+    readonly relatedModel: string | undefined;
+    /** `meta.driverAdapterError.cause.constraint`, read structurally. */
+    readonly constraint: PrismaConstraintSubject | undefined;
+    /**
+     * `meta.target` — **read so that it is measured, depended on by
+     * nothing** (C-820, RC-9).
+     *
+     * The v7 error-reference page still documents `{ target: ['email'] }`,
+     * and RC-9 records that whether 7.10.0 ever emits it could not be
+     * determined from the package. It was induced on both engines here and
+     * **`target` was absent from every payload** — P2002 (single and
+     * compound unique), P2003, P2025 (three shapes), P2018 and P2034, on
+     * SQLite and on PostgreSQL. The docs are stale; the installed package
+     * governs (spec §18.1). This field exists so the next reader sees that
+     * measured, and does not "fix" the code to match the documentation.
+     */
+    readonly legacyTarget: readonly string[] | undefined;
+};
+/**
+ * Reads one hostile value into the facts a classification may use.
+ *
+ * Total: every input produces a `PrismaErrorFacts`. `readPrismaError(null)`
+ * and `readPrismaError(Object.create(null))` are as valid as a real
+ * `PrismaClientKnownRequestError` — they simply report nothing, which the
+ * table answers as `unclassified`.
+ */
+export declare function readPrismaError(error: unknown): PrismaErrorFacts;