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

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,20 @@ 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.",
+};
 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;
@@ -366,7 +425,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 +454,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 +467,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 +582,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 +658,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;
@@ -680,7 +757,9 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
                 };
                 validateWhere(contract, target, entry.where, [...path, "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, [...path, "data"], issues, transactionReferences);
         }
         return;
     }
@@ -854,6 +933,9 @@ 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,

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.",
+        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.",
+        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 {};

package/dist/runtime/caller-data.copier.js

@@ -268,7 +268,7 @@ function pathSegment(array, key) {
     }
     return key;
 }
-function mirrorControlData(value) {
+function mirrorControlData(value, members) {
     const shape = reflectNode(value);
     if (shape === undefined) {
         throw new AvCallerDataError("unreadable-value", []);
@@ -375,6 +375,20 @@ function mirrorControlData(value) {
                 continue;
             }
             const memberLink = childLink(link, pathSegment(shape.array, key));
+            const byValue = members?.copyAt(pathOf(memberLink));
+            if (byValue !== undefined) {
+                try {
+                    store(copyCallerData(member, byValue));
+                }
+                catch (error) {
+                    if (!(error instanceof AvCallerDataError)) {
+                        throw error;
+                    }
+                    members?.refused(pathOf(memberLink), error);
+                    store(undefined);
+                }
+                continue;
+            }
             const memberShape = reflectNode(member);
             if (memberShape === undefined) {
                 store(UNREADABLE);
@@ -408,6 +422,9 @@ function mirrorControlData(value) {
     }
     return root;
 }
+export function mirrorCallerData(value, members) {
+    return mirrorControlData(value, members);
+}
 export function locateCallerDataError(error, copy) {
     const within = error.within;
     if (within === undefined) {

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

@@ -6,13 +6,19 @@ import type { AvMisuseEvent, MisuseReporter } from "./misuse-reporter.js";
  *
  * - `"caller"`: a server-side caller's own objects — copied at the door.
  * - `"owned"`: data no caller holds a reference to — a body the protocol decoder
- *   parsed with `JSON.parse` for this request alone, or a plan the typed runner
- *   assembled from copies its builders took. It is never copied again.
+ *   parsed with `JSON.parse` for this request alone, a host's parsed body the
+ *   protocol's shortcut copied at the call, or a plan the typed runner assembled
+ *   from copies its builders took. It is never copied again.
  *
- * Only core's own modules choose `"owned"`: the public `framework.execute` and
- * `executeTransaction` always pass `"caller"`.
+ * - `{ refused }`: a body the protocol's shortcut copied at the call, whose copy
+ *   failed — answered at the door as `"caller"` would answer it, never read again.
+ *
+ * Only core's own modules choose anything but `"caller"`: the public
+ * `framework.execute` and `executeTransaction` always pass `"caller"`.
  */
-export type ArgumentsSource = "caller" | "owned";
+export type ArgumentsSource = "caller" | "owned" | {
+    readonly refused: AvCallerDataError;
+};
 /** The operation identity a misuse event may name, as far as it could be read. */
 export type MisuseIdentity = Omit<AvMisuseEvent, "kind" | "path">;
 /**

package/dist/runtime/computed-read-runtime.js

@@ -1,5 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { AvComputedValueError } from "./computed-value.error.js";
+import { frozenCopy } from "./readonly-value.js";
 import { normalizeScalarFieldValue } from "./scalar-runtime.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -36,6 +37,12 @@ function appendUniqueProjection(values, value) {
         values.push(value);
     }
 }
+function adapterIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}
 function supportsProjection(request) {
     if (request.family === "upsert") {
         return true;
@@ -51,6 +58,11 @@ function addScalarProjection(core, model, active, compute, resourceName, fieldNa
     const stage = readCompute(compute?.[resourceName]?.[fieldName]?.read);
     if (stage !== undefined) {
         appendUnique(computed, fieldName);
+        if (stage.dependsOn.length === 0) {
+            for (const member of adapterIdentifier(model, resourceName)) {
+                appendUniqueProjection(adapterSelect, member);
+            }
+        }
         for (const dependency of stage.dependsOn) {
             if (storedScalar(model, resourceName, dependency)) {
                 appendUniqueProjection(adapterSelect, dependency);
@@ -307,10 +319,11 @@ async function materializeRecord(active, compute, request, plan, value, contextF
         if (field?.kind !== "scalar" || stage === undefined) {
             continue;
         }
+        const view = frozenCopy(record);
         const computedValue = await stage.compute({
             field: fieldName,
-            value: record[fieldName],
-            record,
+            value: view[fieldName],
+            record: view,
             ctx: contextFactory(),
         });
         if (computedValue === undefined) {

package/dist/runtime/computed-value.error.d.ts

@@ -1,7 +1,8 @@
 import type { AvValidationIssue } from "../operations/validation-code.js";
 /**
  * What the diagnostics channel receives when a computed value — a read or write
- * compute stage's return — is one its Contract refuses: the developer's broken code,
+ * compute stage's return — is one its Contract refuses, or a `compute.create`
+ * stage returned `undefined` for a field a create cannot do without (rc.2): the developer's broken code,
  * never the caller's. It is thrown, not a deliberate outcome, so the framework's
  * boundary answers the caller the generic `A3000` and reports this error, with the
  * issues, exactly once.
@@ -9,5 +10,5 @@ import type { AvValidationIssue } from "../operations/validation-code.js";
 export declare class AvComputedValueError extends Error {
     readonly issues: readonly AvValidationIssue[];
     readonly name = "AvComputedValueError";
-    constructor(resource: string, field: string, stage: "read" | "create" | "update", issues: readonly AvValidationIssue[]);
+    constructor(resource: string, field: string, stage: "read" | "create" | "update", issues: readonly AvValidationIssue[], message?: string);
 }

package/dist/runtime/computed-value.error.js

@@ -1,9 +1,10 @@
 export class AvComputedValueError extends Error {
     issues;
     name = "AvComputedValueError";
-    constructor(resource, field, stage, issues) {
+    constructor(resource, field, stage, issues, message) {
         const [first] = issues;
-        super(`The compute.${stage} stage of ${resource}.${field} returned a value its Contract refuses${first === undefined ? "." : ` (${first.code}: ${first.message})`}`);
+        super(message ??
+            `The compute.${stage} stage of ${resource}.${field} returned a value its Contract refuses${first === undefined ? "." : ` (${first.code}: ${first.message})`}`);
         this.issues = issues;
     }
 }

package/dist/runtime/create-requirement.d.ts

@@ -1,20 +1,32 @@
 import type { AvContract } from "../contracts/contract.js";
+import type { AvCreateRequirements } from "../contracts/create-requirements.js";
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { AvValidationIssue } from "../operations/validation-code.js";
 import type { ReferentialActionTable } from "./referential-action.js";
 type Path = readonly (string | number)[];
+/** One required field a `compute.create` stage was to fill and left missing. */
+export type ComputedRequirementGap = {
+    readonly resource: string;
+    readonly field: string;
+    readonly issue: AvValidationIssue;
+};
 /**
- * What the Adapter stated beside its model that the check reads: its
- * referential edges, for the fields that hold each reference. Read once when
- * the Framework is constructed. The requirements themselves are the active
- * Contract's.
+ * What the Adapter stated that the checks read: its referential edges, for the
+ * fields that hold each reference, and its own create requirements per
+ * Resource, before any layer projected them (what write compute must not leave
+ * missing). Read once when the Framework is constructed. The requirements the
+ * caller is held to are the active Contract's.
  */
 export type RecordWriteFacts = {
     readonly references: ReferentialActionTable;
+    readonly stated: (resource: string) => AvCreateRequirements | undefined;
 };
 /** The facts an Adapter stated, read off it once; an absent table states nothing. */
 export declare function recordWriteFactsOf(adapter: {
     readonly referentialActions?: ReferentialActionTable;
+    readonly model?: {
+        readonly resources: Readonly<Record<string, unknown>>;
+    };
 }): RecordWriteFacts;
 /**
  * The `V1000` issues for every create position in one operation's arguments
@@ -24,7 +36,31 @@ export declare function recordWriteFactsOf(adapter: {
  * reference both, in argument order. Empty when there are none. Total over
  * malformed input.
  */
-export declare function createRequirementIssues(contract: AvContract, facts: RecordWriteFacts, request: AvOperationIdentity & {
+export declare function createRequirementIssues(contract: AvContract, facts: Pick<RecordWriteFacts, "references">, request: AvOperationIdentity & {
     readonly resource: string;
 }, args: unknown, argumentsPath: Path): readonly AvValidationIssue[];
+/**
+ * The `V1000` issues for every create position of one operation's arguments
+ * that lacks a value the active Contract requires, and the `V1012` issues for
+ * every write record that sets a relation and its reference both, on the
+ * arguments as the caller sent them, before any pipeline stage runs. Empty when
+ * there are none.
+ */
+export declare function preliminaryRecordIssues(contract: AvContract, facts: Pick<RecordWriteFacts, "references">, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path): readonly AvValidationIssue[];
+/**
+ * Every required field a `compute.create` stage was to fill and that is still
+ * missing after write compute, at every create position of one operation's
+ * arguments (`create.*`'s `data`, `upsert`'s `create`, every nested create),
+ * in argument order, read against the Adapter's own statement of each
+ * Resource's create requirements; `computed` names the fields a Resource's
+ * `compute.create` stages fill.
+ * A field the parent supplies to a nested create, a group whose relation the
+ * record writes, and a value the caller sent are not missing. Empty when
+ * nothing is.
+ */
+export declare function computedRequirementGapsOf(contract: AvContract, facts: RecordWriteFacts, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path, computed: (resource: string) => ReadonlySet<string>): readonly ComputedRequirementGap[];
 export {};