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

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

@@ -1,4 +1,5 @@
 import { validationIssue } from "../operations/validation-code.js";
+import { copyAtDoor, refuseCallerData } from "../runtime/caller-data.door.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
 import { encodeOperationArgumentsForWire } from "./operation-arguments-encoder.js";
@@ -11,63 +12,63 @@ function isPlainRecord(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-function referenceKeys(identity) {
-    switch (identity.family) {
-        case "create":
-        case "update":
-            return ["data"];
-        case "upsert":
-            return ["create", "update"];
-        default:
-            return [];
+const KEEP = Symbol("keep");
+function rebuildArguments(value, path, leaf, ancestors = new Set()) {
+    const replaced = leaf(value, path);
+    if (replaced !== KEEP) {
+        return replaced;
     }
-}
-function referenceContainers(identity, args) {
-    if (!isPlainRecord(args)) {
-        return [];
-    }
-    return referenceKeys(identity).flatMap((key) => {
-        const value = args[key];
-        if (Array.isArray(value)) {
-            return value.flatMap((entry, index) => isPlainRecord(entry) ? [{ path: [key, index], record: entry }] : []);
-        }
-        return isPlainRecord(value) ? [{ path: [key], record: value }] : [];
-    });
-}
-function replaceContainers(identity, args, rebuild) {
-    if (!isPlainRecord(args)) {
-        return args;
+    if (!Array.isArray(value) && !isPlainRecord(value)) {
+        return value;
     }
-    const result = { ...args };
-    for (const key of referenceKeys(identity)) {
-        const value = args[key];
-        if (Array.isArray(value)) {
-            result[key] = value.map((entry, index) => isPlainRecord(entry)
-                ? rebuild({ path: [key, index], record: entry })
-                : entry);
-        }
-        else if (isPlainRecord(value)) {
-            result[key] = rebuild({ path: [key], record: value });
-        }
+    if (ancestors.has(value)) {
+        return value;
     }
-    return result;
+    ancestors.add(value);
+    const rebuilt = Array.isArray(value)
+        ? value.map((entry, index) => rebuildArguments(entry, [...path, index], leaf, ancestors))
+        : Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            rebuildArguments(entry, [...path, key], leaf, ancestors),
+        ]));
+    ancestors.delete(value);
+    return rebuilt;
 }
 function operationEntryFailure(operation, message) {
     return transactionOperationFailure(operationFailure("A2004", {
         message: "Transaction plan failed framework validation.",
-        issues: [validationIssue("V1001", ["operation"], message)],
+        issues: [validationIssue("V1001", [], message)],
     }), operation);
 }
 function referenceFailure(issue, operation) {
     return transactionOperationFailure(mapValidationOutcome([issue]), operation);
 }
-export function createTransactionPlanAssembler(contracts, protocol) {
+export function createTransactionPlanAssembler(contracts, protocol, misuse) {
     const handles = new WeakMap();
     const placeholders = new WeakMap();
     const originOf = (origin) => origin === "application"
-        ? { scope: "application" }
-        : { scope: "client", protocol };
-    const snapshot = (identity, args) => replaceContainers(identity, args, ({ record }) => ({ ...record }));
+        ? { origin: "application" }
+        : { origin: "client", protocol };
+    const snapshot = (args) => {
+        const copy = copyAtDoor(args, {
+            keep: (value) => placeholders.has(value),
+        });
+        return copy.ok ? { args: copy.value } : { args: {}, refused: copy.error };
+    };
+    const placeholderSites = (args) => {
+        const sites = [];
+        rebuildArguments(args, [], (value, path) => {
+            const placeholder = typeof value === "object" && value !== null
+                ? placeholders.get(value)
+                : undefined;
+            if (placeholder === undefined) {
+                return KEEP;
+            }
+            sites.push({ path, object: value, placeholder });
+            return value;
+        });
+        return sites;
+    };
     const defer = (origin, resource, identity, args) => {
         const handle = Object.freeze({
             $ref: (field) => {
@@ -82,11 +83,22 @@ export function createTransactionPlanAssembler(contracts, protocol) {
             origin,
             resource,
             identity,
-            args: snapshot(identity, args),
+            ...snapshot(args),
         });
         return handle;
     };
-    const assemble = async (operations) => {
+    const assemble = async (input) => {
+        const list = copyAtDoor(input, { keep: (value) => value !== input });
+        if (!list.ok) {
+            return {
+                ok: false,
+                response: operationFailure("A2004", {
+                    message: "Transaction plan failed framework validation.",
+                    issues: [refuseCallerData(list.error, ["operations"], {}, misuse)],
+                }),
+            };
+        }
+        const operations = list.value;
         if (!Array.isArray(operations)) {
             return {
                 ok: false,
@@ -120,17 +132,12 @@ export function createTransactionPlanAssembler(contracts, protocol) {
             records.push(record);
         }
         for (const [index, record] of records.entries()) {
-            for (const { path, record: container } of referenceContainers(record.identity, record.args)) {
-                for (const [field, value] of Object.entries(container)) {
-                    const placeholder = typeof value === "object" && value !== null
-                        ? placeholders.get(value)
-                        : undefined;
-                    if (placeholder !== undefined && !positions.has(placeholder.source)) {
-                        return {
-                            ok: false,
-                            response: referenceFailure(validationIssue("V1010", ["operations", index, "args", ...path, field, "$ref"], "Transaction reference names an operation that is not in this transaction."), index),
-                        };
-                    }
+            for (const { path, placeholder } of placeholderSites(record.args)) {
+                if (!positions.has(placeholder.source)) {
+                    return {
+                        ok: false,
+                        response: referenceFailure(validationIssue("V1010", ["operations", index, "args", ...path, "$ref"], "Transaction reference names an operation that is not in this transaction."), index),
+                    };
                 }
             }
         }
@@ -145,26 +152,17 @@ export function createTransactionPlanAssembler(contracts, protocol) {
         };
         const materialize = async (index) => {
             const record = records[index];
-            const references = [];
-            const args = replaceContainers(record.identity, record.args, ({ record: container }) => {
-                const bound = { ...container };
-                for (const [field, value] of Object.entries(container)) {
-                    const placeholder = typeof value === "object" && value !== null
-                        ? placeholders.get(value)
-                        : undefined;
-                    if (placeholder === undefined) {
-                        continue;
-                    }
-                    const operation = positions.get(placeholder.source);
-                    references.push(nodeAt(operation).then(({ fingerprint }) => {
-                        bound[field] = {
-                            $ref: { operation, fingerprint, path: [placeholder.field] },
-                        };
-                    }));
-                }
-                return bound;
-            });
-            await Promise.all(references);
+            const bound = new Map();
+            await Promise.all(placeholderSites(record.args).map(async ({ object, placeholder }) => {
+                const operation = positions.get(placeholder.source);
+                const { fingerprint } = await nodeAt(operation);
+                bound.set(object, {
+                    $ref: { operation, fingerprint, path: [placeholder.field] },
+                });
+            }));
+            const args = rebuildArguments(record.args, [], (value) => typeof value === "object" && value !== null && bound.has(value)
+                ? bound.get(value)
+                : KEEP);
             return {
                 resource: record.resource,
                 family: record.identity.family,
@@ -195,6 +193,7 @@ export function createTransactionPlanAssembler(contracts, protocol) {
                 operations: await Promise.all(records.map((_, index) => nodeAt(index))),
             },
             origins: records.map((record) => originOf(record.origin)),
+            refused: new Map(records.flatMap((record, index) => record.refused === undefined ? [] : [[index, record.refused]])),
         };
     };
     return { defer, assemble };

package/dist/transactions/transaction-plan-validator.d.ts

@@ -2,6 +2,7 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { Contract } from "../contracts/contract.js";
 import type { ScalarField } from "../contracts/field.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
+import { CallerDataError } from "../runtime/caller-data.copier.js";
 import { type ReadProjectionPlan } from "../runtime/computed-read-runtime.js";
 import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
@@ -9,15 +10,37 @@ import type { OperationPipelineDependencies } from "../runtime/operation-runtime
 import type { CascadeClosure } from "../runtime/referential-action.js";
 import type { OperationFingerprint } from "./deferred-operation.js";
 import type { TransactionReference } from "./transaction-reference.js";
+import { type TransactionSlotShape } from "./transaction-reference.js";
+import { type TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
 import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
-export type TransactionReferenceCandidateSlot = {
-    readonly path: readonly (string | number)[];
-    readonly field: ScalarField<Contract>;
-    readonly candidate: unknown;
+/**
+ * Where a plan's step arguments came from, so the validator knows whether to copy
+ * them at the door (see `ArgumentsSource`):
+ *
+ * - `"caller"` — `framework.executeTransaction`'s caller's own objects: every step's
+ *   arguments are copied when the plan is handed in, before the validator's first
+ *   await, so a step revoked or changed after the call is never read again;
+ * - `"owned"` — a plan the protocol decoder parsed, or the typed runner assembled
+ *   from its builders' copies; `refused` names the steps whose arguments a builder
+ *   could not copy, answered at their turn.
+ */
+export type PlanArguments = {
+    readonly source: "caller";
+} | {
+    readonly source: "owned";
+    readonly refused?: ReadonlyMap<number, CallerDataError>;
 };
+export type { TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
+/** One validated Transaction Slot: where it is, what it holds, and its reference. */
 export type TransactionReferenceSlot = {
     readonly path: readonly (string | number)[];
+    /** The destination field. */
     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;
+    /** The source field, under its own step's Contract: what the slot receives. */
+    readonly source: ScalarField<Contract>;
     readonly reference: TransactionReference;
 };
 export type CandidateTransactionOperation = {
@@ -48,10 +71,10 @@ export type ValidatedTransactionPlan = {
 /**
  * What validating a plan needs beyond one operation's pipeline: the cascade
  * closure over the Adapter's referential actions, resolved once when the
- * Framework is constructed. The create requirements are not among them: they
+ * Framework is constructed. The record-write facts are not among them: they
  * are checked when each operation runs, after its pipes.
  */
-export type TransactionPlanDependencies<M extends AdapterModel> = Omit<OperationPipelineDependencies<M>, "createRequirements"> & {
+export type TransactionPlanDependencies<M extends AdapterModel> = Omit<OperationPipelineDependencies<M>, "recordWrites"> & {
     readonly cascades: CascadeClosure;
 };
 export type TransactionPlanValidationResult = {
@@ -70,4 +93,4 @@ export declare function transactionsUnavailableFailure(): OperationFailureRespon
 /**
  * Whole-plan Framework Validation Layer for transaction structure and identity.
  */
-export declare function validateTransactionPlan<M extends AdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[]): Promise<TransactionPlanValidationResult>;
+export declare function validateTransactionPlan<M extends AdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;