@aventara/prisma7-adapter 1.0.0-rc.4 → 1.0.0-rc.8

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @aventara/prisma7-adapter
 
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- 1c8e4ee: The discovery artifact's referential actions say `referenceFields` where they said `references`: in
+  `referentialActions.<Resource>.owningEdges[]`, the fields of the Resource itself that hold the reference
+  (`@relation(fields: [...])`). The model's relation fields already use `references` for the target's fields
+  (`@relation(references: [...])`) and `referenceFields` for these, so the same word meant two different lists in one
+  file. The generated `discovery.artifact.ts` changes on the next `aventara:prepare` (it runs on install, build and
+  start), and only in those keys: `modelHash` is unchanged, since the referential actions are outside it, and so is the
+  prebuilt Contracts file `aventara-build` writes. Code that read `owningEdges[i].references` reads
+  `owningEdges[i].referenceFields`.
+- Updated dependencies [1c8e4ee]
+  - @aventara/core@1.0.0-rc.8
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- Updated dependencies [f917c1c]
+  - @aventara/core@1.0.0-rc.7
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- Updated dependencies [1cf72e0]
+  - @aventara/core@1.0.0-rc.6
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- 4795ff1: Two additions for policy engines. A Framework without a policy, and every Contract a caller is served, are unchanged.
+
+  - A policy engine can check a create whose row reaches another Resource through a relation. Discovery now states, on the end of a relation that holds the reference, which of the target's fields its reference fields name, pair by pair (`Note.campaign`: `referenceFields: ["campaignId"]`, `references: ["id"]`). An engine reads them from the model it is built from (a Prisma discovery artifact's `model`) or from `framework.contracts.core`, and asks one `exists` about the row they name: "a player creates a note only in a campaign they play in". Only the adapter's model and the Core Contract carry them. The Application, Client and Agent Contracts, `/_contract`, the MCP tools and every ClientContract hash are unchanged. The discovery artifact's model hash, and so a prebuilt Contracts file's fingerprint, change: regenerate the artifact and rebuild the prebuilt file.
+  - `fieldsOf({ access: "write" })` also names the action that writes the record, `action: "create" | "update"` (an upsert's branches each their own, a nested record its directive's), so an engine can lock a field on update and still let a create write it. A read question names none. An engine that ignores it keeps working.
+
+- 9e178ca: Fixes for applications that check requests with a policy engine. A Framework without a policy behaves as before.
+
+  - A cursor on a row the caller cannot read is answered exactly as a cursor on a row that does not exist, at the root and in a to-many relation, whatever values the caller sends beside the identifier. Before, the page started at the hidden row, so it told that the row exists and where its values sort. The Prisma adapter reads the cursor's row under the read scope first: one statement more for a cursor on a readable row, and only that read for one on a row the caller cannot read.
+  - A unique update with a nested write (`$create`, `$connect`, …) on a row the caller can read but not change answers `A4002`, as the same update without one does. It answered `A2003`. A row the caller cannot read still answers `A2003`.
+  - The `exists` questions a policy asks select the Resource's primary identifier, never another unique field such as a governed `email`.
+  - `policy.principal` may answer with a promise. A synchronous principal works as before; a rejection answers `A3000`, as a throw does.
+  - `AvConstructionError.message` names the first problem and how many more there are, for example `Aventara framework configuration validation failed: CONFIG_INVALID_TYPE at adapter.execute: adapter.execute must be a function (+2 more)`. `stage` and `diagnostics` are unchanged.
+
 ## 1.0.0-rc.4
 
 ### Patch Changes

package/README.md

@@ -529,10 +529,10 @@ discovery.referentialActions;
 // {
 //   Shop:  { owningEdges: [] },
 //   Item:  { owningEdges: [{ field: "shop", target: "Shop",
-//                           cardinality: "one", references: ["shopId"],
+//                           cardinality: "one", referenceFields: ["shopId"],
 //                           onDelete: "cascade", onUpdate: "cascade" }] },
 //   Clerk: { owningEdges: [{ field: "shop", target: "Shop",
-//                           cardinality: "one", references: ["shopId"],
+//                           cardinality: "one", referenceFields: ["shopId"],
 //                           onDelete: "set-null", onUpdate: "cascade" }] },
 // }
 ```
@@ -544,7 +544,7 @@ read the enclosing Resource key: above, that is `Item` (cascade) and `Clerk` (se
 that sentence are Resource names and nothing in the shape tells them apart, so reading it backwards
 produces no error, only a plan that reasons backwards.
 
-`references` are the edge's `@relation(fields: […])`, the scalars that hold the reference. A record
+`referenceFields` are the edge's `@relation(fields: […])`, the scalars that hold the reference (the relation field's `referenceFields` in the model; its `references` are the target's fields). A record
 that writes both a relation and one of its reference fields (`shopId` and `shop: { $connect: … }`,
 whether the relation is required or optional) is refused before the database is reached: `A2004` with
 a `V1012` issue at the relation, message `Set "shopId" or "shop", not both.` The reference fields are
@@ -668,7 +668,9 @@ Resource or operation for one to wrap.
 - A record written through a relation cannot write that relation, or its reference fields, back: Prisma's nested
   input for it leaves them out (a post created in `author.posts` has no `author` or `authorId`; a category created in
   a post's `category` has no `posts`). The artifact states each relation's other end (`inverse`, paired by relation
-  name), the fields that hold its reference (`referenceFields`, from `@relation(fields: …)`) and no relation
+  name), the fields that hold its reference (`referenceFields`, from `@relation(fields: …)`) and the target's fields
+  they hold, pair by pair (`references`, from `@relation(references: …)`, which `@aventara/core` keeps in the Core
+  Contract only, for a policy engine), and no relation
   writable at the `"loopback"` position, so `@aventara/core` refuses such a write before any
   guard or SQL, `A2004` with a `V1012` issue at the field written back, and the types do not offer it. Where a layer
   hides the other end, Prisma's client refuses the write instead and the adapter answers that refusal the same way.

package/dist/discovery/discovery-artifact.interface.d.ts

@@ -42,9 +42,11 @@ export type AvPrismaReferentialEdge = {
     readonly cardinality: "one" | "many";
     /**
      * The scalar fields of the enclosing resource that hold the reference: the
-     * relation's `@relation(fields: […])`, in schema order.
+     * relation's `@relation(fields: […])`, in schema order. Named as the relation
+     * field's `referenceFields` in the model: its `references` are the TARGET's
+     * fields (`@relation(references: […])`).
      */
-    readonly references: readonly string[];
+    readonly referenceFields: readonly string[];
     /** What deleting a `target` row does to rows of the enclosing resource. */
     readonly onDelete: AvPrismaReferentialAction;
     /** The same for an update of the referenced key. Read independently of `onDelete`. */

package/dist/discovery/model.discoverer.js

@@ -245,10 +245,17 @@ function composeResource(input) {
                 const referenceFields = firstReference === undefined
                     ? undefined
                     : [firstReference, ...moreReferences];
+                const [firstTarget, ...moreTargets] = field.relation?.references ?? [];
+                const references = referenceFields === undefined ||
+                    firstTarget === undefined ||
+                    moreTargets.length + 1 !== referenceFields.length
+                    ? undefined
+                    : [firstTarget, ...moreTargets];
                 fields[projection.name] = {
                     ...projection.field,
                     ...(inverse === undefined ? {} : { inverse: inverse.relation }),
                     ...(referenceFields === undefined ? {} : { referenceFields }),
+                    ...(references === undefined ? {} : { references }),
                     capabilities: deriveRelationCapabilities({
                         surface: relationSurface,
                     }),
@@ -259,7 +266,7 @@ function composeResource(input) {
                         field: projection.edge.field,
                         target: projection.edge.target,
                         cardinality: projection.edge.cardinality,
-                        references: [...(referenceFields ?? [])],
+                        referenceFields: [...(referenceFields ?? [])],
                         onDelete: projection.edge.onDelete,
                         onUpdate: projection.edge.onUpdate,
                     });

package/dist/execution/operation.executor.js

@@ -2,9 +2,10 @@ import { locateBackReferenceWrite, } from "../errors/back-reference.locator.js";
 import { locateUnboundBigint } from "../errors/bigint-binding.locator.js";
 import { classifyPrismaError, prismaNestedWriteFailure, prismaOutcomeFailure, prismaValueFailure, } from "../errors/error.normalizer.js";
 import { prismaDelegates, } from "../prisma-client.interface.js";
-import { PRISMA_VARIANT_DISPATCH, translateOperation, } from "../translation/operation.translator.js";
+import { PRISMA_VARIANT_DISPATCH, translateOperation, translateScopedCursorLookup, } from "../translation/operation.translator.js";
 import { runFirstVariantEmulation } from "./first-variant.emulator.js";
 import { shapeCount, shapeRow, shapeRows, } from "./result.shaper.js";
+import { resolveScopedCursors } from "./scoped-cursor.resolver.js";
 export class AvPrismaExecutionError extends Error {
     name = "AvPrismaExecutionError";
 }
@@ -21,8 +22,9 @@ export function createPrismaOperationExecutor(dependencies) {
             : {}),
     });
     return {
-        async execute(operation) {
-            const result = resultKindOf(dispatchOf(operation));
+        async execute(sent) {
+            const result = resultKindOf(dispatchOf(sent));
+            const operation = await withScopedCursorsResolved(dependencies, sent, (call) => issueClassified(issue, call, sent, locatorFor(sent)));
             const translation = translateOperation({
                 model: dependencies.model,
                 translation: dependencies.translation,
@@ -53,6 +55,18 @@ export function createPrismaOperationExecutor(dependencies) {
         },
     };
 }
+async function withScopedCursorsResolved(dependencies, operation, issue) {
+    const args = operation.arguments;
+    const resolved = await resolveScopedCursors(dependencies.model, operation.resource, args, async (resource, cursor) => (await issue(translateScopedCursorLookup({
+        model: dependencies.model,
+        translation: dependencies.translation,
+        resource,
+        cursor,
+    }))) !== null);
+    return resolved === args
+        ? operation
+        : { ...operation, arguments: resolved };
+}
 async function withUnit(dependencies, work) {
     if (dependencies.scope === "transaction") {
         return work(dependencies.client);

package/dist/execution/scoped-cursor.resolver.d.ts

@@ -0,0 +1,11 @@
+import type { AvAdapterModel } from "@aventara/core";
+type Level = Readonly<Record<string, unknown>>;
+/** Whether the row `cursor` (with its `AND`) names on `resource` meets its conditions. */
+export type PrismaScopedCursorLookup = (resource: string, cursor: Level) => Promise<boolean>;
+/**
+ * The operation's arguments with every cursor that carries `AND` resolved: its
+ * address alone when the row meets the conditions, otherwise no cursor and
+ * `limit: 0`. The same object when no cursor carries `AND`.
+ */
+export declare function resolveScopedCursors(model: AvAdapterModel, resource: string, args: Level, lookup: PrismaScopedCursorLookup): Promise<Level>;
+export {};

package/dist/execution/scoped-cursor.resolver.js

@@ -0,0 +1,47 @@
+export async function resolveScopedCursors(model, resource, args, lookup) {
+    return (await resolveLevel(model, resource, args, lookup)) ?? args;
+}
+async function resolveLevel(model, resource, level, lookup) {
+    let resolved;
+    const cursor = level.cursor;
+    if (isRecord(cursor) && Object.hasOwn(cursor, "AND")) {
+        const { AND: _conditions, ...address } = cursor;
+        const { cursor: _cursor, ...rest } = level;
+        resolved = (await lookup(resource, cursor))
+            ? { ...rest, cursor: address }
+            : { ...rest, limit: 0 };
+    }
+    if (Array.isArray(level.select)) {
+        const select = await resolveSelect(model, resource, level.select, lookup);
+        if (select !== undefined) {
+            resolved = { ...(resolved ?? level), select };
+        }
+    }
+    return resolved;
+}
+async function resolveSelect(model, resource, select, lookup) {
+    let changed = false;
+    const entries = [];
+    for (const entry of select) {
+        if (!isRecord(entry)) {
+            entries.push(entry);
+            continue;
+        }
+        const rewritten = {};
+        for (const [name, value] of Object.entries(entry)) {
+            const field = model.resources[resource]?.fields[name];
+            const inner = field?.kind === "relation" && isRecord(value)
+                ? await resolveLevel(model, field.target, value, lookup)
+                : undefined;
+            if (inner !== undefined) {
+                changed = true;
+            }
+            rewritten[name] = inner ?? value;
+        }
+        entries.push(rewritten);
+    }
+    return changed ? entries : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/generate/artifact.emitter.js

@@ -19,7 +19,7 @@ const REFERENTIAL_ACTIONS_DOC = [
     "/**",
     " * The schema's referential actions, per Resource: the relation fields that",
     " * declare `@relation(fields: …)`, each with the fields holding its reference",
-    " * (`references`) and its resolved `onDelete` and `onUpdate`. An edge under",
+    " * (`referenceFields`) and its resolved `onDelete` and `onUpdate`. An edge under",
     " * Resource `R` reads:",
     " *",
     " *   deleting a `target` row does `onDelete` to rows of `R`.",

package/dist/prisma-adapter.description.js

@@ -12,7 +12,7 @@ function translateReferentialActions(table) {
         owningEdges.map((edge) => ({
             field: edge.field,
             target: edge.target,
-            references: edge.references,
+            referenceFields: edge.referenceFields,
             onDelete: DELETE_EFFECTS[edge.onDelete],
         })),
     ]));

package/dist/translation/operation.translator.d.ts

@@ -144,3 +144,14 @@ export type PrismaOperationTranslationInput = {
  * addresses no row — never a silently narrowed or widened call.
  */
 export declare function translateOperation(input: PrismaOperationTranslationInput): PrismaOperationTranslation;
+/**
+ * The unique read that tells whether the row a core cursor names meets the
+ * `AND` conditions it carries: `findUnique` by the cursor's address with the
+ * conditions, translated against `resource`, in its selector.
+ */
+export declare function translateScopedCursorLookup(input: {
+    readonly model: AvAdapterModel;
+    readonly translation: Readonly<Record<string, PrismaResourceTranslation>>;
+    readonly resource: string;
+    readonly cursor: Readonly<Record<string, unknown>>;
+}): PrismaCall;

package/dist/translation/operation.translator.js

@@ -1,6 +1,6 @@
 import { addressIdentifier } from "./identifier.addressing.js";
 import { translateMutationData } from "./mutation.translator.js";
-import { translateOrderBy, translatePagination, } from "./order-pagination.translator.js";
+import { translateCursorLookup, translateOrderBy, translatePagination, } from "./order-pagination.translator.js";
 import { translateProjection, } from "./projection.translator.js";
 import { translateWhere } from "./where.translator.js";
 const FIRST_VARIANT_WRITE_ROUTE = {
@@ -256,10 +256,39 @@ function paginationArguments(context) {
         ...(typeof context.args.offset === "number"
             ? { offset: context.args.offset }
             : {}),
-        ...(isRecord(context.args.cursor) ? { cursor: context.args.cursor } : {}),
+        ...cursorArguments(context.args.cursor),
         identifiers: identifiersOf(context, context.resource),
     });
 }
+function cursorArguments(cursor) {
+    if (!isRecord(cursor)) {
+        return {};
+    }
+    if (Object.hasOwn(cursor, "AND")) {
+        throw new AvPrismaOperationTranslationError("cursor: its `AND` conditions reach no Prisma `cursor`; the executor resolves them before translation");
+    }
+    return { cursor };
+}
+export function translateScopedCursorLookup(input) {
+    const { AND: conditions, ...address } = input.cursor;
+    const identifiers = input.translation[input.resource]?.identifierKeys;
+    if (identifiers === undefined) {
+        throw new AvPrismaOperationTranslationError(`Resource "${input.resource}" has no Prisma addressing in the translation table`);
+    }
+    return {
+        model: input.resource,
+        action: "findUnique",
+        args: translateCursorLookup({
+            cursor: address,
+            conditions: translateWhere({
+                model: input.model,
+                resource: input.resource,
+                where: { AND: conditions },
+            }),
+            identifiers,
+        }),
+    };
+}
 function mutationData(context, stage, argument) {
     return translateMutationData({
         model: context.model,
@@ -322,7 +351,7 @@ function relationArgumentTranslator(context) {
         Object.assign(emitted, translatePagination({
             ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
             ...(typeof args.offset === "number" ? { offset: args.offset } : {}),
-            ...(isRecord(args.cursor) ? { cursor: args.cursor } : {}),
+            ...cursorArguments(args.cursor),
             identifiers: identifiersOf(context, target),
         }));
         return emitted;

package/dist/translation/order-pagination.translator.d.ts

@@ -30,4 +30,23 @@ export type OrderByTranslation = {
     readonly orderBy: unknown;
 };
 export declare function translatePagination(input: PaginationTranslation): PrismaPaginationArguments;
+/**
+ * The Aventara cursor carries the active ordered scalar fields; core guarantees
+ * that they include a complete identifier (`V1009` — *"orderBy must include a
+ * complete Resource identifier as an explicit tie-breaker"*). Prisma's `cursor`
+ * is an ADDRESS, so the identifier is what is emitted: the remaining ordered
+ * fields are the ordering, which `orderBy` already carries, and adding them as
+ * equality members of a where-unique would narrow the address rather than
+ * sharpen it.
+ */
+/**
+ * The unique read that tells whether the row a cursor names meets `conditions`
+ * (a translated `<M>WhereInput`): its address, the conditions in `AND`, and the
+ * address's members selected.
+ */
+export declare function translateCursorLookup(input: {
+    readonly cursor: Readonly<Record<string, unknown>>;
+    readonly conditions: Readonly<Record<string, unknown>>;
+    readonly identifiers: readonly PrismaIdentifierAddress[];
+}): Readonly<Record<string, unknown>>;
 export declare function translateOrderBy(input: OrderByTranslation): PrismaOrderByInput | readonly PrismaOrderByInput[];

package/dist/translation/order-pagination.translator.js

@@ -24,6 +24,21 @@ export function translatePagination(input) {
     }
     return emitted;
 }
+export function translateCursorLookup(input) {
+    const addressed = addressIdentifier({
+        addresses: input.identifiers,
+        values: input.cursor,
+        match: "subset",
+        emit: (_member, value) => value,
+    });
+    if (addressed === undefined) {
+        throw new AvPrismaOrderTranslationError(`cursor: no identifier is complete in { ${Object.keys(input.cursor).join(", ")} }, so it addresses no row`);
+    }
+    return {
+        where: { ...addressed.where, AND: [input.conditions] },
+        select: Object.fromEntries(addressed.address.members.map((member) => [member, true])),
+    };
+}
 function addressCursor(cursor, identifiers) {
     const addressed = addressIdentifier({
         addresses: identifiers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/prisma7-adapter",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.8",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The Prisma 7 adapter for Aventara.",
   "type": "module",
@@ -30,7 +30,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.4"
+    "@aventara/core": "1.0.0-rc.8"
   },
   "peerDependencies": {
     "@prisma/adapter-better-sqlite3": "^7.10.0",