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

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

@@ -1,10 +1,11 @@
+import { FILTER_MODES, } 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;
@@ -513,6 +599,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 +675,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 +704,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 +720,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 +816,27 @@ 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 validateRelationMutation(contract, fieldName, field, value, stage, scope, path, issues, transactionReferences) {
     const directives = advertisedDirectivesAt(field.capabilities[stage], scope);
     if (directives === undefined) {
@@ -817,6 +914,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 +959,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/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.",
+        fix: "Write either the relation or its reference field, in the relation's cardinality.",
+    },
+    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/protocol/protocol.handler.js

@@ -1,16 +1,53 @@
+import { copyAtDoor } from "../runtime/caller-data.door.js";
 import { createDiagnosticsReporter, createReporter, } from "../runtime/diagnostics-reporter.js";
 import { sanitizeOperationFailure } from "../runtime/error-boundary.js";
+import { capturePlanAtCall } from "../transactions/transaction-plan-validator.js";
 import { decodeOperationRequest, decodeTransactionRequest, isParsedByDecoder, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
-function operationEntry(context, request) {
-    return context.owned !== undefined && isParsedByDecoder(request.arguments)
-        ? context.owned.execute
-        : context.execute;
+function admitOperation(context, request) {
+    const owned = context.owned;
+    if (isParsedByDecoder(request.arguments)) {
+        return { request, run: owned?.execute ?? context.execute };
+    }
+    const copy = copyAtDoor(request.arguments);
+    if (owned === undefined) {
+        return {
+            request: copy.ok ? { ...request, arguments: copy.value } : request,
+            run: context.execute,
+        };
+    }
+    if (copy.ok) {
+        return {
+            request: { ...request, arguments: copy.value },
+            run: (admitted) => owned.execute(admitted),
+        };
+    }
+    return {
+        request: { ...request, arguments: {} },
+        run: (admitted) => owned.execute(admitted, copy.error),
+    };
 }
-function transactionEntry(context, request) {
-    return context.owned !== undefined && isParsedByDecoder(request.plan)
-        ? context.owned.executeTransaction
-        : context.executeTransaction;
+function admitTransaction(context, request) {
+    const owned = context.owned;
+    if (isParsedByDecoder(request.plan)) {
+        return {
+            request,
+            run: owned?.executeTransaction ?? context.executeTransaction,
+        };
+    }
+    const captured = capturePlanAtCall(request.plan);
+    if (owned === undefined) {
+        return {
+            request: captured.refused.size === 0
+                ? { ...request, plan: captured.plan }
+                : request,
+            run: context.executeTransaction,
+        };
+    }
+    return {
+        request: { ...request, plan: captured.plan },
+        run: (admitted) => owned.executeTransaction(admitted, captured.refused.size === 0 ? undefined : captured.refused),
+    };
 }
 async function seededState(options, report, view) {
     if (options?.state === undefined) {
@@ -48,11 +85,12 @@ export async function handleOperationRequest(context, request, options) {
     if (!decoded.ok) {
         return decoded.response;
     }
-    const seeded = await seededState(options, createDiagnosticsReporter(context.sink, decoded.request), { path: ["arguments"], arguments: decoded.request.arguments });
+    const admitted = admitOperation(context, decoded.request);
+    const seeded = await seededState(options, createDiagnosticsReporter(context.sink, admitted.request), { path: ["arguments"], arguments: admitted.request.arguments });
     const response = seeded.ok
-        ? await operationEntry(context, decoded.request)(seeded.state === undefined
-            ? decoded.request
-            : { ...decoded.request, state: seeded.state })
+        ? await admitted.run(seeded.state === undefined
+            ? admitted.request
+            : { ...admitted.request, state: seeded.state })
         : seeded.response;
     return encodeOperationResponse(response, decoded.requestId, operationUnencodableReport(context.sink, decoded.request));
 }
@@ -61,15 +99,16 @@ export async function handleTransactionRequest(context, request, options) {
     if (!decoded.ok) {
         return decoded.response;
     }
+    const admitted = admitTransaction(context, decoded.request);
     const seeded = await seededState(options, createReporter(context.sink, {
         kind: "transaction",
         origin: context.origin,
         requestId: decoded.requestId,
-    }), { path: ["plan"], arguments: decoded.request.plan });
+    }), { path: ["plan"], arguments: admitted.request.plan });
     const response = seeded.ok
-        ? await transactionEntry(context, decoded.request)(seeded.state === undefined
-            ? decoded.request
-            : { ...decoded.request, state: seeded.state })
+        ? await admitted.run(seeded.state === undefined
+            ? admitted.request
+            : { ...admitted.request, state: seeded.state })
         : seeded.response;
     return encodeTransactionResponse(response, decoded.requestId, planUnencodableReport(context.sink, decoded.requestId, context.origin));
 }

package/dist/runtime/caller-data.copier.d.ts

@@ -41,6 +41,22 @@ export type CallerDataPolicy = {
     readonly keep?: CallerDataKeep;
     readonly mirror?: CallerDataMirror;
 };
+/** The members a structural mirror copies by value rather than mirroring. */
+type MirrorMembers = {
+    /** The policy a member at `path` (from the mirror's root) is copied by, or `undefined`. */
+    readonly copyAt: (path: CallerDataPath) => CallerDataPolicy | undefined;
+    /** Receives a member whose copy failed; the mirror holds `undefined` for it. */
+    readonly refused: (path: CallerDataPath, error: AvCallerDataError) => void;
+};
+/**
+ * Mirrors `value` by its descriptors, as a `$ref` control object is mirrored (no
+ * getter runs, an accessor stays a tripwire), except the members `members.copyAt`
+ * names by their path: each is copied by value under the policy it returns, and one
+ * whose copy fails is reported to `members.refused` and held as `undefined`.
+ *
+ * @throws {@link AvCallerDataError} at `[]` when `value` itself cannot be reflected.
+ */
+export declare function mirrorCallerData(value: object, members: MirrorMembers): unknown;
 /**
  * Places a mirror tripwire's failure in the value the door copied: its path from the
  * copy's root, where `error.path` started from the mirror. A failure that is not a
@@ -57,3 +73,4 @@ export declare function locateCallerDataError(error: AvCallerDataError, copy: un
 export declare function copyCallerData(value: unknown, policy?: CallerDataPolicy): unknown;
 /** The `V1001` message a door answers a {@link AvCallerDataError} with. */
 export declare function callerDataFailureMessage(kind: CallerDataFailureKind): string;
+export {};