@aventara/core 1.0.0-rc.1 → 1.0.0-rc.10

package/dist/operations/operation-validator-core.js

@@ -1,10 +1,11 @@
+import { FILTER_MODES, toOneRelinkWithRewrite, } from "../contracts/capability.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { advertisedDirectivesAt, advertisedReducers, advertisedReducersAt, holdsAt, } from "../contracts/field.js";
-import { isPlainRecord } from "../runtime/scalar-runtime.js";
+import { isPlainRecord, unsentReadValueIssue, } from "../runtime/scalar-runtime.js";
 import { routeTransactionReferenceCandidate } from "../transactions/transaction-reference.js";
 import { isOperationFamily, } from "./operation-identity.js";
 import { NESTED_PROJECTION_SCOPE, resolveProjectionScope, } from "./projection-scope.resolver.js";
-import { NESTED_WRITE_SCOPE, resolveWriteScope, } from "./write-scope.resolver.js";
+import { NESTED_WRITE_SCOPE, resolveWriteScope, TO_MANY_UPDATE_WRITE_SCOPE, } from "./write-scope.resolver.js";
 const OPERATION_ARGUMENT_RULES = {
     "find.first": {
         allowed: ["where", "orderBy", "select", "include"],
@@ -190,11 +191,16 @@ function validateScalarCondition(contract, fieldName, field, supported, value, p
         addIssue(state.issues, "V1001", path, `Filter object for field "${fieldName}" must contain an operator.`);
         return;
     }
+    refuseDanglingQualifiers(fieldName, value, path, state);
     for (const operator of operators) {
         if (!includes(supported, operator)) {
             addIssue(state.issues, "V1006", [...path, operator], `Filter operator "${operator}" is not available on field "${fieldName}".`);
             continue;
         }
+        if (operator === "mode") {
+            refuseUnavailableMode(field, fieldName, value, path, state);
+            continue;
+        }
         if (operator === "not") {
             const operand = value[operator];
             if (isPlainRecord(operand) && !checkDepth(contract, state, depth + 1)) {
@@ -204,12 +210,55 @@ function validateScalarCondition(contract, fieldName, field, supported, value, p
         }
     }
 }
+function refuseDanglingQualifiers(fieldName, level, path, state) {
+    const qualifiers = DANGLING_QUALIFIERS.filter((key) => Object.hasOwn(level, key));
+    if (qualifiers.length === 0) {
+        return;
+    }
+    const compares = Object.entries(level).some(([operator, operand]) => !includes(DANGLING_QUALIFIERS, operator) &&
+        !(operator === "not" && isNegatedOperatorObject(operand, state)));
+    if (compares) {
+        return;
+    }
+    for (const qualifier of qualifiers) {
+        addIssue(state.issues, "V1001", [...path, qualifier], `${qualifier} on field "${fieldName}" qualifies no operator: write it next to the operator it applies to (inside "not" to apply to a negated one).`);
+    }
+}
+const DANGLING_QUALIFIERS = ["mode", "path"];
+function isNegatedOperatorObject(operand, state) {
+    return (isPlainRecord(operand) &&
+        !(state.transactionReferences === true &&
+            routeTransactionReferenceCandidate(operand).kind !== "ordinary"));
+}
+function refuseUnavailableMode(field, fieldName, level, path, state) {
+    const mode = level.mode;
+    if (mode === "default" ||
+        typeof mode !== "string" ||
+        !includes(FILTER_MODES, mode)) {
+        return;
+    }
+    const { filterModes = [], pathFilterModes } = field.capabilities;
+    const atPath = Object.hasOwn(level, "path") && pathFilterModes !== undefined;
+    if (includes(atPath ? pathFilterModes : filterModes, mode)) {
+        return;
+    }
+    const where = atPath
+        ? " at a path"
+        : pathFilterModes !== undefined && includes(pathFilterModes, mode)
+            ? " without a path"
+            : "";
+    addIssue(state.issues, "V1006", [...path, "mode"], `Filter mode "${mode}" is not available on field "${fieldName}"${where}.`);
+}
 function validateRelationFilter(contract, fieldName, field, value, path, state, depth) {
     const supported = field.capabilities.filter;
     if (supported === undefined) {
         addIssue(state.issues, "V1006", path, `Filtering is not available on relation "${fieldName}".`);
         return;
     }
+    if (value === undefined) {
+        state.issues.push(unsentReadValueIssue(path));
+        return;
+    }
     if (field.cardinality === "one") {
         if (value === null) {
             if (!field.nullable || !includes(supported, "null")) {
@@ -249,10 +298,26 @@ function validateRelationFilter(contract, fieldName, field, value, path, state,
         validateWhere(contract, field.target, value[operator], [...path, operator], state, depth + 1);
     }
 }
+const UNDEFINED_ARGUMENT_MESSAGES = {
+    where: "where must not be undefined: leave the key out to mean no filter.",
+    limit: "limit must not be undefined: leave the key out to mean no limit.",
+    offset: "offset must not be undefined: leave the key out to mean no offset.",
+    cursor: "cursor must not be undefined: leave the key out to mean no cursor.",
+};
+const EMPTY_BOOLEAN_NODE_MESSAGE = "A boolean node must hold a condition here: an empty one matches every row, and the write would reach more rows.";
+function isEmptyBooleanNode(value) {
+    return Array.isArray(value)
+        ? value.length === 0
+        : isRecord(value) && Object.keys(value).length === 0;
+}
 function validateWhere(contract, resourceName, where, path, state, depth) {
     if (!checkDepth(contract, state, depth)) {
         return;
     }
+    if (where === undefined) {
+        state.issues.push(unsentReadValueIssue(path));
+        return;
+    }
     if (!isRecord(where)) {
         addIssue(state.issues, "V1001", path, "where must be an object.");
         return;
@@ -263,6 +328,13 @@ function validateWhere(contract, resourceName, where, path, state, depth) {
         return;
     }
     for (const [key, value] of Object.entries(where)) {
+        if (state.refuseEmptyNodes === true &&
+            (key === "AND" || key === "OR" || key === "NOT") &&
+            isEmptyBooleanNode(value)) {
+            countFilterNode(contract, state);
+            addIssue(state.issues, "V1001", [...path, key], EMPTY_BOOLEAN_NODE_MESSAGE);
+            continue;
+        }
         if (key === "AND" || key === "OR") {
             countFilterNode(contract, state);
             if (!Array.isArray(value)) {
@@ -270,6 +342,10 @@ function validateWhere(contract, resourceName, where, path, state, depth) {
                 continue;
             }
             value.forEach((entry, index) => {
+                if (state.refuseEmptyNodes === true && isEmptyBooleanNode(entry)) {
+                    addIssue(state.issues, "V1001", [...path, key, index], EMPTY_BOOLEAN_NODE_MESSAGE);
+                    return;
+                }
                 validateWhere(contract, resourceName, entry, [...path, key, index], state, depth + 1);
             });
             continue;
@@ -366,7 +442,9 @@ function validateOrderBy(contract, resourceName, orderBy, path, issues) {
                 valueKeys[1] !== "sort" ||
                 (value.sort !== "asc" && value.sort !== "desc") ||
                 (value.nulls !== "first" && value.nulls !== "last")) {
-                addIssue(issues, "V1001", fieldPath, `Extended null ordering for "${fieldName}" must contain sort and nulls.`);
+                addIssue(issues, "V1001", fieldPath, Object.hasOwn(value, "$ref")
+                    ? `A transaction reference cannot stand in orderBy: order "${fieldName}" by "asc", "desc" or { sort, nulls }.`
+                    : `Null ordering for "${fieldName}" must be exactly { sort: "asc" | "desc", nulls: "first" | "last" }.`);
                 continue;
             }
             if (!field.nullable || field.capabilities.orderNulls !== true) {
@@ -393,6 +471,10 @@ function validateOrderBy(contract, resourceName, orderBy, path, issues) {
     return analysis;
 }
 function validatePaginationValue(contract, name, value, path, issues) {
+    if (value === undefined) {
+        addIssue(issues, "V1001", path, UNDEFINED_ARGUMENT_MESSAGES[name]);
+        return;
+    }
     if (!Number.isInteger(value) || typeof value !== "number" || value < 0) {
         addIssue(issues, "V1001", path, `${name} must be a non-negative integer.`);
         return;
@@ -402,6 +484,10 @@ function validatePaginationValue(contract, name, value, path, issues) {
     }
 }
 function validateCursor(contract, resourceName, cursor, orderBy, path, issues) {
+    if (cursor === undefined) {
+        addIssue(issues, "V1009", path, UNDEFINED_ARGUMENT_MESSAGES.cursor);
+        return;
+    }
     if (!isRecord(cursor) || orderBy === undefined) {
         addIssue(issues, "V1009", path, "Cursor pagination requires an object cursor and explicit deterministic orderBy.");
         return;
@@ -438,6 +524,12 @@ function validateProjection(contract, resourceName, mode, value, scope, path, is
     }
     value.forEach((entry, index) => {
         const entryPath = [...path, index];
+        if (entry === "$defaults") {
+            if (mode !== "select") {
+                addIssue(issues, "V1008", entryPath, "$defaults is a select entry: include already returns the default fields.");
+            }
+            return;
+        }
         if (entry === "$count") {
             if (mode !== "select" ||
                 reducerOwner?.edge.cardinality !== "many" ||
@@ -513,6 +605,9 @@ function validateRelationProjection(contract, edge, scope, value, path, issues)
         if (!includes(edge.capabilities.filter, "nested")) {
             addIssue(issues, "V1006", [...path, "where"], "Nested returned-relation filtering is not available on this edge.");
         }
+        else if (value.where === undefined) {
+            addIssue(issues, "V1001", [...path, "where"], UNDEFINED_ARGUMENT_MESSAGES.where);
+        }
         else {
             const state = {
                 issues,
@@ -586,11 +681,16 @@ function validateScalarMutation(fieldName, field, value, stage, path, issues, tr
         addIssue(issues, "V1001", path, "Scalar mutation action objects may contain only $-prefixed directive keys.");
         return;
     }
+    let unavailable = false;
     for (const directive of directiveKeys) {
         if (!includes(directives, directive)) {
+            unavailable = true;
             addIssue(issues, "V1006", [...path, directive], `Mutation directive "${directive}" is not available on field "${fieldName}".`);
         }
     }
+    if (!unavailable && directiveKeys.length > 1) {
+        addIssue(issues, "V1001", path, "Scalar mutation action objects may contain only one directive.");
+    }
 }
 function validateRelationMutationEntry(contract, edge, directive, value, path, issues, transactionReferences) {
     const target = edge.target;
@@ -610,8 +710,8 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
             addIssue(issues, "V1012", path, "To-many $disconnect requires one or more unique identifiers.");
             return;
         }
-        for (const selector of selectors) {
-            validateUniqueSelector(contract, target, selector, path, issues);
+        for (const { entry: selector, at } of entriesOf(edge, value, path)) {
+            validateUniqueSelector(contract, target, selector, at, issues);
         }
         return;
     }
@@ -626,82 +726,81 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
             addIssue(issues, "V1012", path, "To-many $set requires an identifier array.");
             return;
         }
-        for (const selector of value) {
-            validateUniqueSelector(contract, target, selector, path, issues);
+        for (const { entry: selector, at } of entriesOf(edge, value, path)) {
+            validateUniqueSelector(contract, target, selector, at, issues);
         }
         return;
     }
     if (directive === "$connect") {
-        const selectors = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const selector of selectors) {
-            validateUniqueSelector(contract, target, selector, path, issues);
+        for (const { entry: selector, at } of entriesOf(edge, value, path)) {
+            validateUniqueSelector(contract, target, selector, at, issues);
         }
         return;
     }
     if (directive === "$create") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
-            validateMutationData(contract, target, entry, "create", NESTED_WRITE_SCOPE, path, issues, transactionReferences);
+        for (const { entry, at } of entriesOf(edge, value, path)) {
+            validateMutationData(contract, target, entry, "create", NESTED_WRITE_SCOPE, at, issues, transactionReferences);
         }
         return;
     }
     if (directive === "$connectOrCreate") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (!isRecord(entry) || !("where" in entry) || !("create" in entry)) {
-                addIssue(issues, "V1012", path, "$connectOrCreate requires where and create.");
+                addIssue(issues, "V1012", at, "$connectOrCreate requires where and create.");
                 continue;
             }
-            validateUniqueSelector(contract, target, entry.where, [...path, "where"], issues);
-            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues, transactionReferences);
+            validateUniqueSelector(contract, target, entry.where, [...at, "where"], issues);
+            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...at, "create"], issues, transactionReferences);
         }
         return;
     }
     if (directive === "$update") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (!isRecord(entry) || !("data" in entry)) {
-                addIssue(issues, "V1012", path, "$update requires a data object.");
+                addIssue(issues, "V1012", at, "$update requires a data object.");
                 continue;
             }
             if (edge.cardinality === "many" && !("where" in entry)) {
-                addIssue(issues, "V1012", path, "To-many $update requires where.");
+                addIssue(issues, "V1012", at, "To-many $update requires where.");
                 continue;
             }
             if ("where" in entry) {
                 const state = {
                     issues,
-                    structuralRoot: [...path, "where"],
+                    structuralRoot: [...at, "where"],
                     transactionReferences,
                     scalarOnly: edge.capabilities.nestedWriteFilter === "scalar",
+                    ...(edge.cardinality === "many" ? { refuseEmptyNodes: true } : {}),
                     booleanFilterNodes: 0,
                     nestingExceeded: false,
                     booleanNodesExceeded: false,
                 };
-                validateWhere(contract, target, entry.where, [...path, "where"], state, 1);
+                validateWhere(contract, target, entry.where, [...at, "where"], state, 1);
             }
-            validateMutationData(contract, target, entry.data, "update", NESTED_WRITE_SCOPE, [...path, "data"], issues, transactionReferences);
+            validateMutationData(contract, target, entry.data, "update", edge.cardinality === "many"
+                ? TO_MANY_UPDATE_WRITE_SCOPE
+                : NESTED_WRITE_SCOPE, [...at, "data"], issues, transactionReferences);
         }
         return;
     }
     if (directive === "$delete") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (edge.cardinality === "many") {
                 if (!isRecord(entry) || !("where" in entry)) {
-                    addIssue(issues, "V1012", path, "To-many $delete requires where.");
+                    addIssue(issues, "V1012", at, "To-many $delete requires where.");
                     continue;
                 }
                 const state = {
                     issues,
-                    structuralRoot: [...path, "where"],
+                    structuralRoot: [...at, "where"],
                     transactionReferences,
                     scalarOnly: edge.capabilities.nestedWriteFilter === "scalar",
+                    refuseEmptyNodes: true,
                     booleanFilterNodes: 0,
                     nestingExceeded: false,
                     booleanNodesExceeded: false,
                 };
-                validateWhere(contract, target, entry.where, [...path, "where"], state, 1);
+                validateWhere(contract, target, entry.where, [...at, "where"], state, 1);
             }
             else if (entry !== true &&
                 (!isRecord(entry) || Object.keys(entry).some((key) => key !== "where"))) {
@@ -723,23 +822,34 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
         return;
     }
     if (directive === "$upsert") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (!isRecord(entry) ||
                 !("create" in entry) ||
                 !("update" in entry) ||
                 (edge.cardinality === "many" && !("where" in entry))) {
-                addIssue(issues, "V1012", path, "$upsert requires create/update and requires where on to-many relations.");
+                addIssue(issues, "V1012", at, "$upsert requires create/update and requires where on to-many relations.");
                 continue;
             }
             if ("where" in entry) {
-                validateUniqueSelector(contract, target, entry.where, [...path, "where"], issues);
+                validateUniqueSelector(contract, target, entry.where, [...at, "where"], issues);
             }
-            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues, transactionReferences);
-            validateMutationData(contract, target, entry.update, "update", NESTED_WRITE_SCOPE, [...path, "update"], issues, transactionReferences);
+            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...at, "create"], issues, transactionReferences);
+            validateMutationData(contract, target, entry.update, "update", NESTED_WRITE_SCOPE, [...at, "update"], issues, transactionReferences);
         }
     }
 }
+function entriesOf(edge, value, path) {
+    return edge.cardinality === "many" && Array.isArray(value)
+        ? value.map((entry, index) => ({ entry, at: [...path, index] }))
+        : [{ entry: value, at: path }];
+}
+function refuseToOneRelinkWithRewrite(fieldName, field, value, path, issues) {
+    const paired = field.cardinality === "one" ? toOneRelinkWithRewrite(value) : undefined;
+    if (paired === undefined) {
+        return;
+    }
+    addIssue(issues, "V1012", path, `To-one relation "${fieldName}" cannot combine ${paired.rewrite.join("/")} with ${paired.relink.join("/")} in one write: the row it would update is the newly linked one. Relink in one write and update in another.`);
+}
 function validateRelationMutation(contract, fieldName, field, value, stage, scope, path, issues, transactionReferences) {
     const directives = advertisedDirectivesAt(field.capabilities[stage], scope);
     if (directives === undefined) {
@@ -750,6 +860,7 @@ function validateRelationMutation(contract, fieldName, field, value, stage, scop
         addIssue(issues, "V1012", path, `Relation "${fieldName}" mutation value must be a directive object.`);
         return;
     }
+    refuseToOneRelinkWithRewrite(fieldName, field, value, path, issues);
     for (const [directive, directiveValue] of Object.entries(value)) {
         const directivePath = [...path, directive];
         if (!directive.startsWith("$") || !includes(directives, directive)) {
@@ -817,6 +928,14 @@ function validateMutationArguments(contract, resourceName, request, args, issues
         }
     }
 }
+function emptyNodeRefusalOf(request) {
+    return (request.family === "update" || request.family === "delete") &&
+        (request.variant === "many" ||
+            request.variant === "count" ||
+            request.variant === "first")
+        ? { refuseEmptyNodes: true }
+        : {};
+}
 function isUniqueOperation(request) {
     return (request.variant === "unique" &&
         (request.family === "find" ||
@@ -854,11 +973,15 @@ export function validateOperationArguments(contract, request, options) {
         if (isUniqueOperation(request)) {
             validateUniqueSelector(contract, request.resource, request.arguments.where, ["arguments", "where"], issues);
         }
+        else if (request.arguments.where === undefined) {
+            addIssue(issues, "V1001", ["arguments", "where"], UNDEFINED_ARGUMENT_MESSAGES.where);
+        }
         else {
             const state = {
                 issues,
                 structuralRoot: ["arguments", "where"],
                 transactionReferences: options?.transactionReferences === true,
+                ...emptyNodeRefusalOf(request),
                 booleanFilterNodes: 0,
                 nestingExceeded: false,
                 booleanNodesExceeded: false,

package/dist/operations/operation-validator.d.ts

@@ -2,7 +2,7 @@ import type { AvContract } from "../contracts/contract.js";
 import { type AvOperationIdentity } from "./operation-identity.js";
 import { type OperationValidationOptions, type OperationValidationResult } from "./operation-validator-core.js";
 import type { AvValidationIssue } from "./validation-code.js";
-export type { OperationValidationOptions, OperationValidationResult, SemanticOperationArguments, } from "./operation-validator-core.js";
+export type { OperationValidationOptions, SemanticOperationArguments, } from "./operation-validator-core.js";
 /** The key of a request's operation identity that makes it unavailable. */
 export declare function unavailableOperationKey(contract: AvContract, request: {
     readonly resource: string;

package/dist/operations/structural-limits.walker.d.ts

@@ -3,7 +3,7 @@ import type { AvOperationIdentity } from "./operation-identity.js";
 import type { AvValidationIssue } from "./validation-code.js";
 type Readable = Readonly<Record<string, unknown>>;
 /** What one walk of an operation's arguments found. */
-export type StructuralLimitsFinding = {
+type StructuralLimitsFinding = {
     /** The nesting issue, which wins over any boolean-node issue. */
     readonly nesting: AvValidationIssue | undefined;
     /** The boolean-node issue, when there is no nesting issue. */

package/dist/operations/validation-code.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeGuidance } from "../runtime/error-guidance.js";
+import type { AvValidationCode } from "./validation-code.js";
+/** Cause and fix of every validation code. */
+export declare const VALIDATION_CODE_GUIDANCE: {
+    readonly [C in AvValidationCode]: ErrorCodeGuidance;
+};

package/dist/operations/validation-code.guidance.js

@@ -0,0 +1,90 @@
+export const VALIDATION_CODE_GUIDANCE = {
+    V1000: {
+        cause: "A required value is absent: a create leaves out a required field that has no database default and no compute.create (the path names the field), a required relation and its reference field are both missing, a typed Json field lacks a required key, or a $ref has no fingerprint.",
+        fix: "Send the value at the issue's path. When the server must fill it, give the field a compute.create stage or a database default; a pipe cannot fill it.",
+    },
+    V1001: {
+        cause: "A value of the wrong type: a string where a number is expected, a negative limit, a non-integer id, null given to an operator with no null meaning (gt, contains, in), two directives in one scalar action object (`{ $increment: 1, $decrement: 2 }`), or a server-side value that is not plain data. Also a value that would make the call reach more rows: `undefined` in a filter, a unique selector or a cursor, an empty boolean node (`NOT: {}`, `AND: []`, `OR: []`) in the where of a write (update or delete many, count or first, a to-many $update or $delete).",
+        fix: "Send the type the contract states at that path (the generated client's types say it).",
+    },
+    V1002: {
+        cause: "A value that is not a member of the enum, or outside a typed Json field's AvZ.enum or AvZ.literal.",
+        fix: "Send one of the enum's members.",
+    },
+    V1003: {
+        cause: 'A malformed datetime, decimal, base64 or UUID string, or a failed pattern or format validator (`check: "string_format"`).',
+        fix: "Send the canonical encoding (ISO-8601 UTC datetime, decimal string, base64 bytes) and satisfy the validator that check and params name.",
+    },
+    V1004: {
+        cause: "A number, length or size outside its range: a failed bound, length or size validator, a BigInt outside signed 64 bits, an AvZ.int() outside the safe integer range, or a transaction with no operations. Under A2004 it is also a value the database refused as too long or out of its range, a BigInt beyond what the data source's driver can bind among them (some bind at most ±(2^53 − 1)).",
+        fix: "Send a value inside the range; check and params name the validator that failed.",
+    },
+    V1005: {
+        cause: "A field that does not exist or is hidden in the caller's layer, an unknown Resource (under A2001), or a key a typed Json field's shape does not declare.",
+        fix: "Use a field the caller's contract exposes, expose it through exemptions, or make the call from server code.",
+    },
+    V1006: {
+        cause: "An operator, directive or nested write the field does not offer (at any depth, inside not too; a to-many $update's data takes only what a bulk write takes), a mode it does not offer, or an operation that is not available (under A2002).",
+        fix: "Use what the contract lists for that field or Resource, or expose it through exemptions.",
+    },
+    V1007: {
+        cause: "The where of a unique operation is not exactly one complete identifier.",
+        fix: "Pass exactly one identifier: the id, or every field of one @unique or @@unique.",
+    },
+    V1008: {
+        cause: "Both select and include, a write-only field selected, or a relation that is not selectable there.",
+        fix: "Use select or include, not both, and select only readable fields.",
+    },
+    V1009: {
+        cause: "A cursor without an explicit orderBy, or cursor keys that do not match the ordered fields.",
+        fix: "Give an orderBy and a cursor holding exactly its ordered fields.",
+    },
+    V1010: {
+        cause: "A $ref path the earlier step does not return, a $ref to a step that is not in the transaction, or to a step with no single row (a many or count step).",
+        fix: "Select the referenced field in the earlier step, and reference a single-row step.",
+    },
+    V1011: {
+        cause: "The referenced value's type does not fit its target, a nullable source where only a non-null value is accepted included.",
+        fix: "Reference a field of the target's type, non-null where the target needs it.",
+    },
+    V1012: {
+        cause: "A nested write that does not fit the relation (a list where one record is expected), a reference field set together with its own relation, one record mixing reference fields and relation writes where the adapter cannot run both, or a record written through a relation that writes that relation (or a field holding its reference) back, where the adapter admits no such write. Also a to-one $update or $upsert beside $connect, $connectOrCreate, $create, $set or $disconnect on the same relation: the row it would update is the newly linked one.",
+        fix: "Write either the relation or its reference field, in the relation's cardinality. Relink a to-one relation in one write and update the linked row in another.",
+    },
+    V1013: {
+        cause: "Nested projections, filters or writes deeper than maxNestingDepth.",
+        fix: "Nest less, or raise limits.maxNestingDepth.",
+    },
+    V1014: {
+        cause: "A limit above maxListLimit, or more steps than maxTransactionOperations.",
+        fix: "Paginate or split the plan, or raise the limit.",
+    },
+    V1015: {
+        cause: "A where tree with more nodes than maxBooleanNodes.",
+        fix: "Simplify the filter (in instead of many OR clauses), or raise limits.maxBooleanNodes.",
+    },
+    V1016: {
+        cause: "A $ref to the referencing step itself or a later one, or to an index no step has.",
+        fix: "Reference an earlier step only.",
+    },
+    V1017: {
+        cause: "A hand-written plan whose fingerprint does not match its step.",
+        fix: "Let the generated client, framework.appTx or framework.clientTx build the plan.",
+    },
+    V1018: {
+        cause: "The referenced step returned no value at that path, such as a first step that matched no row.",
+        fix: "Make sure the earlier step returns a row, or use a unique step, which fails with A2003.",
+    },
+    V1019: {
+        cause: "A later step uses a row that an earlier step's delete removed through a database cascade.",
+        fix: "Reorder or drop the dependent step.",
+    },
+    V1020: {
+        cause: "One framework.transaction([...]) list mixes appTx and clientTx steps.",
+        fix: "Build every step of a plan from one origin.",
+    },
+    V1021: {
+        cause: "A Json field's value nests deeper than maxJsonDepth.",
+        fix: "Flatten the value, or raise limits.maxJsonDepth.",
+    },
+};

package/dist/operations/write-scope.resolver.d.ts

@@ -13,3 +13,7 @@ export declare function resolveWriteScope(resource: AvResource<AvContract> | und
  * unrestricted one, at every depth, under every top-level scope.
  */
 export declare const NESTED_WRITE_SCOPE: AvWriteScope;
+/** The position a to-many `$update`'s `data` sits in: the flat-bulk write position. */
+export declare const TO_MANY_UPDATE_WRITE_SCOPE: AvWriteScope;
+/** The position of a relation's other end inside a record written through it. */
+export declare const LOOPBACK_WRITE_SCOPE: AvWriteScope;

package/dist/operations/write-scope.resolver.js

@@ -5,3 +5,5 @@ export function resolveWriteScope(resource, request) {
     return writeScopeOf(lookupOwn(advertised, request.variant));
 }
 export const NESTED_WRITE_SCOPE = "nested";
+export const TO_MANY_UPDATE_WRITE_SCOPE = "bulkWrite";
+export const LOOPBACK_WRITE_SCOPE = "loopback";

package/dist/policy/access-provider.interface.d.ts

@@ -0,0 +1,91 @@
+import type { AvState } from "../runtime/request-state.js";
+import type { AvPolicyEngine } from "./policy-engine.js";
+/**
+ * What the framework's `access` option takes: the policy engine every client
+ * and agent request is checked against, and how a request's state is seeded.
+ * Aventara Access provides one; one written by hand works the same way.
+ *
+ * The request's principal is `ctx.$state.me` (`null` when it is absent), so
+ * `state` names it as `me`. With `access`, the configuration states no
+ * `policy`, and the host no `state` of its own.
+ */
+export interface AvAccessProvider {
+    /** The policy engine (`AvPolicyEngine`), asked about every client and agent request. */
+    readonly policy: AvPolicyEngine;
+    /**
+     * Seeds a request's `ctx.$state` from its headers (a Web `Headers`): `me`, the principal the
+     * policy is asked about (`null` for an anonymous caller), and anything else
+     * the stages read. Called once per request by the host. `request` is the
+     * host's own request when it has one: Express's `req`, Fastify's
+     * `request`, or the Next.js route handler's `Request`. A throw is answered
+     * like any developer failure: a thrown `AvError` as its own outcome,
+     * anything else as an internal failure.
+     */
+    state(input: {
+        readonly headers: {
+            get(name: string): string | null;
+            has(name: string): boolean;
+            forEach(callback: (value: string, name: string) => void): void;
+        };
+        readonly request?: unknown;
+    }): (AvState & {
+        readonly me: unknown;
+    }) | Promise<AvState & {
+        readonly me: unknown;
+    }>;
+    /**
+     * What the clients' `$access` needs beyond `can`: where the app mounted
+     * Aventara Access (`url`), and each verb's route under it, the JSON Schema
+     * of its arguments and result, and its server-side `call`. Compiled into
+     * the ClientContract's `access` section (its `call`s dropped). Left out,
+     * `$access` offers `can` only.
+     */
+    readonly client?: {
+        /** Where the app mounted Access: an absolute `http(s)` URL, or root-relative (`"/api/auth"`). */
+        readonly url: string;
+        /**
+         * The verbs Access offers, each its route, its schemas and its
+         * server-side call. A verb left out is no verb of `$access`: a
+         * `service` profile, with no cookie sign-in, offers no `signIn` or
+         * `signUp`, and only the `kiosk` profile offers `switchUser`, `lock`,
+         * `setPin`, `enrollDevice` and `revokeDevice`. Any other name is
+         * refused.
+         */
+        readonly verbs: {
+            readonly [Verb in "signIn" | "signUp" | "signOut" | "resetPassword" | "me" | "switchUser" | "lock" | "setPin" | "enrollDevice" | "revokeDevice"]?: {
+                /** The route's method. */
+                readonly method: "GET" | "POST";
+                /** Under `url`: `"/sign-in/email"`. */
+                readonly path: string;
+                /**
+                 * The arguments' JSON Schema, in the subset a `json` field's shape
+                 * uses (absent: the verb takes none).
+                 */
+                readonly args?: {
+                    readonly [key: string]: unknown;
+                };
+                /** The result's JSON Schema, in the same subset (`me`: the value when someone is signed in). */
+                readonly result: {
+                    readonly [key: string]: unknown;
+                };
+                /**
+                 * The verb run in process, for a server-side client
+                 * (`framework.serverClient.$access`, Next's `avClient.$access`):
+                 * Access runs it with the request's headers, and the host's own
+                 * request and response when the caller hands them (Express's
+                 * `req`/`res`, Fastify's `request`/`reply`), so a sign-in (or a
+                 * kiosk's switch, lock or enrollment) sets its cookies as Access
+                 * sets them: on the response it is handed, or, in a Server Action,
+                 * through Next's `cookies()`. `me` resolves the token identity, or
+                 * `null` when no one is signed in.
+                 */
+                call(input: {
+                    readonly args: unknown;
+                    readonly headers: Parameters<AvAccessProvider["state"]>[0]["headers"];
+                    readonly request?: unknown;
+                    readonly response?: unknown;
+                }): Promise<unknown>;
+            };
+        };
+    };
+}

package/dist/policy/access-provider.interface.js

@@ -0,0 +1 @@
+export {};