@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.0

package/dist/transactions/transaction-plan-validator.js

@@ -1,17 +1,67 @@
 import { CanonicalJsonError } from "../contracts/contract-canonicalizer.js";
-import { lookupField, lookupOwn, lookupResource, } from "../contracts/contract-lookup.js";
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { parseOperationIdentity } from "../operations/operation-identity.js";
+import { findOperationAvailabilityIssue, unavailableOperationKey, } from "../operations/operation-validator.js";
 import { VALIDATION_CODE_MESSAGES, validationIssue, } from "../operations/validation-code.js";
+import { CallerDataError, locateCallerDataError, } from "../runtime/caller-data.copier.js";
+import { copyAtDoor, misuseIdentityOf, refuseCallerData, } from "../runtime/caller-data.door.js";
 import { planReadOperation, } from "../runtime/computed-read-runtime.js";
-import { OPERATION_ARGUMENTS_PATH, planOperationArgumentsPath, } from "../runtime/error-boundary.js";
+import { planOperationArgumentsPath, planStepPath, } from "../runtime/error-boundary.js";
+import { createMisuseReporter } from "../runtime/misuse-reporter.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { activeContract, validateOperationRequest, validateProtocolIdentity, } from "../runtime/operation-runtime.js";
+import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
 import { encodeOperationArgumentsForWire } from "./operation-arguments-encoder.js";
 import { computeOperationFingerprint, isOperationFingerprint, } from "./operation-fingerprint.js";
 import { inspectTransactionEnvelope, inspectTransactionOperationEntry, inspectTransactionOperations, } from "./transaction-envelope.js";
-import { routeTransactionReferenceCandidate } from "./transaction-reference.js";
+import { routeTransactionReferenceCandidate, } from "./transaction-reference.js";
+import { collectTransactionReferenceCandidates, } from "./transaction-reference-collector.js";
 import { validateTransactionReferences } from "./transaction-reference-validator.js";
 import { transactionOperationFailure } from "./transaction-response.js";
+const CALLER_PLAN = { source: "caller" };
+const STEP_ARGUMENTS_POLICY = {
+    mirror: (value) => Object.hasOwn(value, "$ref"),
+};
+function captureSteps(operations, operationCount, planArguments) {
+    const steps = [];
+    for (let index = 0; index < operationCount; index += 1) {
+        const operationEntry = inspectTransactionOperationEntry(operations, index);
+        if (!operationEntry.ok) {
+            steps.push({
+                ok: false,
+                response: structuralFailure(operationEntry.issue),
+            });
+            break;
+        }
+        const nodeEnvelope = inspectTransactionEnvelope(operationEntry.value, {
+            required: OPERATION_KEYS,
+            invalidContainerPath: [],
+            invalidContainerMessage: "Operation node must be an object.",
+        });
+        if (!nodeEnvelope.ok) {
+            steps.push({
+                ok: false,
+                response: structuralFailure(nodeEnvelope.issue, index),
+            });
+            break;
+        }
+        const node = nodeEnvelope.values;
+        const args = node.get("args");
+        const refused = planArguments.source === "owned"
+            ? planArguments.refused?.get(index)
+            : undefined;
+        const copy = refused !== undefined
+            ? { ok: false, error: refused }
+            : planArguments.source === "owned"
+                ? { ok: true, value: args }
+                : copyAtDoor(args, STEP_ARGUMENTS_POLICY);
+        steps.push({ ok: true, node, args: copy });
+        if (!copy.ok) {
+            break;
+        }
+    }
+    return steps;
+}
 const PLAN_KEYS = ["operations"];
 const OPERATION_KEYS = [
     "resource",
@@ -23,10 +73,23 @@ const OPERATION_KEYS = [
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function operationKeyFailure(key, message, operation) {
+    return transactionOperationFailure(operationFailure("A2002", {
+        message: "Operation arguments failed framework validation.",
+        issues: [validationIssue("V1006", [key], message)],
+    }), operation);
+}
 function structuralFailure(rejection, operation) {
     return operationFailure("A2004", {
         message: "Transaction plan failed framework validation.",
-        issues: [rejection],
+        issues: [
+            operation === undefined || rejection.path === undefined
+                ? rejection
+                : {
+                    ...rejection,
+                    path: [...planStepPath(operation), ...rejection.path],
+                },
+        ],
         ...(operation === undefined ? {} : { operation }),
     });
 }
@@ -37,11 +100,11 @@ function syntheticRequest(origin, requestId, resource, identity, args) {
         ...identity,
         arguments: args,
     };
-    return origin.scope === "application"
-        ? { ...common, scope: "application" }
+    return origin.origin === "application"
+        ? { ...common, origin: "application" }
         : {
             ...common,
-            scope: "client",
+            origin: "client",
             protocol: origin.protocol,
             ...(origin.transport === undefined
                 ? {}
@@ -49,10 +112,10 @@ function syntheticRequest(origin, requestId, resource, identity, args) {
         };
 }
 function requestOrigin(request) {
-    return request.scope === "application"
-        ? { scope: "application" }
+    return request.origin === "application"
+        ? { origin: "application" }
         : {
-            scope: "client",
+            origin: "client",
             protocol: request.protocol,
             ...(request.transport === undefined
                 ? {}
@@ -60,55 +123,13 @@ function requestOrigin(request) {
         };
 }
 function originContracts(contracts, origins) {
-    const layers = new Set(origins.map((origin) => origin.scope));
-    return [...layers].map((scope) => scope === "application" ? contracts.application : contracts.client);
-}
-function collectDataCandidates(contract, resourceName, data, path, candidates) {
-    if (!isObject(data)) {
-        return;
-    }
-    const resource = lookupResource(contract, resourceName);
-    for (const [fieldName, value] of Object.entries(data)) {
-        const field = lookupField(resource, fieldName);
-        const route = routeTransactionReferenceCandidate(value);
-        if (field?.kind === "scalar" && route.kind !== "ordinary") {
-            candidates.push({
-                path: [...path, fieldName],
-                field,
-                candidate: route.candidate,
-            });
-        }
-    }
-}
-function collectCandidates(contract, request, index, args) {
-    const candidates = [];
-    const root = planOperationArgumentsPath(index);
-    if (request.family === "create") {
-        const data = lookupOwn(args, "data");
-        if (request.variant === "many" || request.variant === "count") {
-            if (Array.isArray(data)) {
-                data.forEach((entry, dataIndex) => {
-                    collectDataCandidates(contract, request.resource, entry, [...root, "data", dataIndex], candidates);
-                });
-            }
-        }
-        else {
-            collectDataCandidates(contract, request.resource, data, [...root, "data"], candidates);
-        }
-    }
-    else if (request.family === "update") {
-        collectDataCandidates(contract, request.resource, lookupOwn(args, "data"), [...root, "data"], candidates);
-    }
-    else if (request.family === "upsert") {
-        for (const stage of ["create", "update"]) {
-            collectDataCandidates(contract, request.resource, lookupOwn(args, stage), [...root, stage], candidates);
-        }
-    }
-    return candidates;
+    const layers = new Set(origins.map(({ origin }) => origin));
+    return [...layers].map((origin) => origin === "application" ? contracts.application : contracts.client);
 }
 function* relationTraversals(contract, resourceName, value, path) {
     const resource = lookupResource(contract, resourceName);
-    if (resource === undefined) {
+    if (resource === undefined ||
+        routeTransactionReferenceCandidate(value).kind !== "ordinary") {
         return;
     }
     if (Array.isArray(value)) {
@@ -182,7 +203,7 @@ export function transactionsUnavailableFailure() {
         issues: [validationIssue("V1006", ["operations"], message)],
     });
 }
-export async function validateTransactionPlan(dependencies, request, origins) {
+export async function validateTransactionPlan(dependencies, request, origins, planArguments = CALLER_PLAN) {
     const protocolFailure = validateProtocolIdentity(dependencies.contracts, request);
     if (protocolFailure !== undefined) {
         return { ok: false, response: protocolFailure };
@@ -229,30 +250,18 @@ export async function validateTransactionPlan(dependencies, request, origins) {
             }),
         };
     }
+    const steps = captureSteps(operations, operationCount, planArguments);
+    const misuse = createMisuseReporter(dependencies.config.misuse);
     const validated = [];
     const cascaded = new Set();
     for (let index = 0; index < operationCount; index += 1) {
-        const operationEntry = inspectTransactionOperationEntry(operations, index);
-        if (!operationEntry.ok) {
-            return {
-                ok: false,
-                response: structuralFailure(operationEntry.issue),
-            };
-        }
-        const nodeEnvelope = inspectTransactionEnvelope(operationEntry.value, {
-            required: OPERATION_KEYS,
-            invalidContainerPath: ["operation"],
-            invalidContainerMessage: "Operation node must be an object.",
-        });
-        if (!nodeEnvelope.ok) {
-            return {
-                ok: false,
-                response: structuralFailure(nodeEnvelope.issue, index),
-            };
+        const step = steps[index];
+        if (!step.ok) {
+            return { ok: false, response: step.response };
         }
-        const node = nodeEnvelope.values;
+        const node = step.node;
         const origin = originOf(index);
-        const contract = origin.scope === "application"
+        const contract = origin.origin === "application"
             ? dependencies.contracts.application
             : dependencies.contracts.client;
         const resourceValue = node.get("resource");
@@ -286,100 +295,142 @@ export async function validateTransactionPlan(dependencies, request, origins) {
         if (identity === undefined) {
             return {
                 ok: false,
-                response: transactionOperationFailure(operationFailure("A2002", {
-                    message: "Operation arguments failed framework validation.",
-                    issues: [
-                        validationIssue("V1006", ["operation"], "Operation is not part of the standard operation grammar."),
-                    ],
-                }), index),
+                response: operationKeyFailure(typeof family === "string"
+                    ? unavailableOperationKey(contract, {
+                        resource: resourceValue,
+                        family,
+                    })
+                    : "family", "Operation is not part of the standard operation grammar.", index),
             };
         }
-        const operationRequest = syntheticRequest(origin, request.requestId, resourceValue, identity, node.get("args"));
-        const operationValidation = validateOperationRequest(contract, operationRequest, { transactionReferences: true });
-        if (!operationValidation.ok) {
+        const stepRequest = { resource: resourceValue, ...identity };
+        const unavailable = findOperationAvailabilityIssue(contract, stepRequest);
+        if (unavailable !== undefined) {
             return {
                 ok: false,
-                response: transactionOperationFailure(operationValidation.response, index),
+                response: transactionOperationFailure(mapValidationOutcome([unavailable]), index),
             };
         }
-        const candidate = {
-            index,
-            request: operationRequest,
-            arguments: operationValidation.arguments,
-            projection: planReadOperation(dependencies.contracts.core, contract, (origin.scope === "application"
-                ? dependencies.config.application
-                : dependencies.config.client).behaviors, operationRequest, operationValidation.arguments).projection,
-            declaredFingerprint: node.get("fingerprint"),
-            candidates: collectCandidates(contract, operationRequest, index, operationValidation.arguments),
-        };
-        const referenceValidation = validateTransactionReferences(candidate, validated);
-        if (!referenceValidation.ok) {
-            return referenceValidation;
+        if (!step.args.ok) {
+            return {
+                ok: false,
+                response: transactionOperationFailure(mapValidationOutcome([
+                    refuseCallerData(step.args.error, planOperationArgumentsPath(index), {
+                        ...misuseIdentityOf({
+                            ...stepRequest,
+                            origin: origin.origin,
+                        }),
+                        operation: index,
+                    }, misuse),
+                ]), index),
+            };
         }
-        const validatedRequest = {
-            ...candidate.request,
-            arguments: referenceValidation.requestArguments,
-        };
-        const validatedArguments = referenceValidation.arguments;
-        const wireArguments = origin.scope === "client"
-            ? validatedRequest.arguments
-            : encodeOperationArgumentsForWire(contract, validatedRequest, validatedArguments);
-        let fingerprint;
         try {
-            fingerprint = await computeOperationFingerprint({
-                resource: validatedRequest.resource,
-                family: validatedRequest.family,
-                variant: validatedRequest.variant,
-                args: wireArguments,
+            const operationRequest = syntheticRequest(origin, request.requestId, resourceValue, identity, step.args.value);
+            const operationValidation = validateOperationRequest(contract, operationRequest, { transactionReferences: true });
+            if (!operationValidation.ok) {
+                return {
+                    ok: false,
+                    response: transactionOperationFailure(operationValidation.response, index),
+                };
+            }
+            const candidate = {
+                index,
+                request: operationRequest,
+                arguments: operationValidation.arguments,
+                projection: planReadOperation(dependencies.contracts.core, contract, (origin.origin === "application"
+                    ? dependencies.config.application
+                    : dependencies.config.client).behaviors, operationRequest, operationValidation.arguments).projection,
+                declaredFingerprint: node.get("fingerprint"),
+                candidates: collectTransactionReferenceCandidates(contract, operationRequest, index, operationValidation.arguments),
+            };
+            const referenceValidation = validateTransactionReferences(candidate, validated);
+            if (!referenceValidation.ok) {
+                return referenceValidation;
+            }
+            const validatedRequest = {
+                ...candidate.request,
+                arguments: referenceValidation.requestArguments,
+            };
+            const validatedArguments = referenceValidation.arguments;
+            const wireArguments = origin.origin === "client"
+                ? validatedRequest.arguments
+                : encodeOperationArgumentsForWire(contract, validatedRequest, validatedArguments);
+            let fingerprint;
+            try {
+                fingerprint = await computeOperationFingerprint({
+                    resource: validatedRequest.resource,
+                    family: validatedRequest.family,
+                    variant: validatedRequest.variant,
+                    args: wireArguments,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof CanonicalJsonError)) {
+                    throw error;
+                }
+                return {
+                    ok: false,
+                    response: structuralFailure(validationIssue("V1001", ["args"], "Invalid runtime/wire type."), index),
+                };
+            }
+            if (!isOperationFingerprint(candidate.declaredFingerprint) ||
+                candidate.declaredFingerprint !== fingerprint) {
+                return {
+                    ok: false,
+                    response: transactionOperationFailure(operationFailure("A2007", {
+                        message: "Operation fingerprint does not match its arguments.",
+                        issues: [
+                            validationIssue("V1017", ["fingerprint"], "Operation fingerprint does not match its arguments."),
+                        ],
+                    }), index),
+                };
+            }
+            const dependency = cascadeDependency(contract, validatedRequest, index, cascaded);
+            if (dependency !== undefined) {
+                return {
+                    ok: false,
+                    response: transactionOperationFailure(operationFailure("A2004", {
+                        message: "Transaction plan failed framework validation.",
+                        issues: [
+                            validationIssue("V1019", dependency, VALIDATION_CODE_MESSAGES.V1019),
+                        ],
+                    }), index),
+                };
+            }
+            for (const resource of deletedResources(contract, validatedRequest, index)) {
+                for (const removed of dependencies.cascades(resource)) {
+                    cascaded.add(removed);
+                }
+            }
+            validated.push({
+                index: candidate.index,
+                request: validatedRequest,
+                contract,
+                arguments: validatedArguments,
+                projection: candidate.projection,
+                fingerprint,
+                references: referenceValidation.references,
             });
         }
         catch (error) {
-            if (!(error instanceof CanonicalJsonError)) {
+            if (!(error instanceof CallerDataError)) {
                 throw error;
             }
             return {
                 ok: false,
-                response: structuralFailure(validationIssue("V1001", OPERATION_ARGUMENTS_PATH, "Invalid runtime/wire type."), index),
+                response: transactionOperationFailure(mapValidationOutcome([
+                    refuseCallerData(locateCallerDataError(error, step.args.value), planOperationArgumentsPath(index), {
+                        ...misuseIdentityOf({
+                            resource: resourceValue,
+                            ...identity,
+                            origin: origin.origin,
+                        }),
+                        operation: index,
+                    }, misuse),
+                ]), index),
             };
         }
-        if (!isOperationFingerprint(candidate.declaredFingerprint) ||
-            candidate.declaredFingerprint !== fingerprint) {
-            return {
-                ok: false,
-                response: transactionOperationFailure(operationFailure("A2007", {
-                    message: "Operation fingerprint does not match its arguments.",
-                    issues: [
-                        validationIssue("V1017", ["fingerprint"], "Operation fingerprint does not match its arguments."),
-                    ],
-                }), index),
-            };
-        }
-        const dependency = cascadeDependency(contract, validatedRequest, index, cascaded);
-        if (dependency !== undefined) {
-            return {
-                ok: false,
-                response: transactionOperationFailure(operationFailure("A2004", {
-                    message: "Transaction plan failed framework validation.",
-                    issues: [
-                        validationIssue("V1019", dependency, VALIDATION_CODE_MESSAGES.V1019),
-                    ],
-                }), index),
-            };
-        }
-        for (const resource of deletedResources(contract, validatedRequest, index)) {
-            for (const removed of dependencies.cascades(resource)) {
-                cascaded.add(removed);
-            }
-        }
-        validated.push({
-            index: candidate.index,
-            request: validatedRequest,
-            contract,
-            arguments: validatedArguments,
-            projection: candidate.projection,
-            fingerprint,
-            references: referenceValidation.references,
-        });
     }
     return { ok: true, plan: { operations: validated } };
 }

package/dist/transactions/transaction-reference-collector.d.ts

@@ -0,0 +1,30 @@
+import type { Contract } from "../contracts/contract.js";
+import type { ScalarField } from "../contracts/field.js";
+import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { SemanticOperationArguments } from "../operations/operation-validator.js";
+import { type TransactionSlotShape } from "./transaction-reference.js";
+type Path = readonly (string | number)[];
+/** One `$ref` candidate found at a reference position, before it is validated. */
+export type TransactionReferenceCandidateSlot = {
+    readonly path: Path;
+    readonly field: ScalarField<Contract>;
+    readonly shape: TransactionSlotShape;
+    /** The slot is a scalar value of mutation data: what it resolves to is written. */
+    readonly written: boolean;
+    readonly candidate: unknown;
+};
+/**
+ * Every `$ref` candidate at a reference position of one validated operation, with the
+ * full wire path, the destination field and the slot's shape. The positions: mutation
+ * data (`create`'s `data`, each `data[]` entry of a bulk create, `update`'s `data`,
+ * `upsert`'s `create`/`update`) at any depth — its scalar values, the unique keys its
+ * relation directives name, the `where` of `$update`/`$delete`/`$upsert`, and the data
+ * they nest — the `cursor`, and the step's own `where` at any depth.
+ *
+ * It reads the validated argument view, whose normalization keeps every key where
+ * the caller wrote it, so a slot path names the same member of the wire view.
+ */
+export declare function collectTransactionReferenceCandidates(contract: Contract, request: OperationIdentity & {
+    readonly resource: string;
+}, index: number, args: SemanticOperationArguments): readonly TransactionReferenceCandidateSlot[];
+export {};