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

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

@@ -1,9 +1,12 @@
-import { validationIssue } from "../operations/validation-code.js";
+import { VALIDATION_CODE_MESSAGES, 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";
 import { computeOperationFingerprint } from "./operation-fingerprint.js";
+import { readSqlTemplate } from "./sql-statement.js";
 import { transactionOperationFailure } from "./transaction-response.js";
+const SQL_STEP_NODE = Object.freeze({ fingerprint: null });
 function isPlainRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         return false;
@@ -11,64 +14,111 @@ 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 [];
-    }
-}
-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 }] : []);
+const KEEP = Symbol("keep");
+function rebuildArguments(root, leaf) {
+    const pathOf = (parent, key) => () => {
+        const segments = [];
+        if (key !== undefined) {
+            segments.push(key);
         }
-        return isPlainRecord(value) ? [{ path: [key], record: value }] : [];
-    });
-}
-function replaceContainers(identity, args, rebuild) {
-    if (!isPlainRecord(args)) {
-        return args;
+        for (let frame = parent; frame?.key !== undefined; frame = frame.parent) {
+            segments.push(frame.key);
+        }
+        return segments.reverse();
+    };
+    const ancestors = new Set();
+    const finish = (frame) => {
+        ancestors.delete(frame.source);
+        if (!Array.isArray(frame.source)) {
+            return Object.fromEntries(frame.built);
+        }
+        const rebuilt = new Array(frame.source.length);
+        for (const [index, value] of frame.built) {
+            rebuilt[index] = value;
+        }
+        return rebuilt;
+    };
+    const enter = (value, parent, key) => {
+        const replaced = leaf(value, pathOf(parent, key));
+        if (replaced !== KEEP) {
+            return { value: replaced };
+        }
+        if (!Array.isArray(value) && !isPlainRecord(value)) {
+            return { value };
+        }
+        if (ancestors.has(value)) {
+            return { value };
+        }
+        ancestors.add(value);
+        const keys = Array.isArray(value)
+            ? Object.keys(value).map(Number)
+            : Object.keys(value);
+        return { source: value, keys, built: [], parent, key, next: 0 };
+    };
+    const first = enter(root, undefined, undefined);
+    if (!("source" in first)) {
+        return first.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);
+    let frame = first;
+    for (;;) {
+        if (frame.next < frame.keys.length) {
+            const key = frame.keys[frame.next];
+            frame.next += 1;
+            const entry = frame.source[key];
+            const child = enter(entry, frame, key);
+            if ("source" in child) {
+                frame = child;
+            }
+            else {
+                frame.built.push([key, child.value]);
+            }
+            continue;
         }
-        else if (isPlainRecord(value)) {
-            result[key] = rebuild({ path: [key], record: value });
+        const rebuilt = finish(frame);
+        const parent = frame.parent;
+        if (parent === undefined) {
+            return rebuilt;
         }
+        parent.built.push([frame.key, rebuilt]);
+        frame = parent;
     }
-    return result;
 }
 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 }));
-    const defer = (origin, resource, identity, args) => {
+        ? { 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, pathOf) => {
+            const placeholder = typeof value === "object" && value !== null
+                ? placeholders.get(value)
+                : undefined;
+            if (placeholder === undefined) {
+                return KEEP;
+            }
+            sites.push({ path: pathOf(), object: value, placeholder });
+            return value;
+        });
+        return sites;
+    };
+    const createHandle = (record) => {
         const handle = Object.freeze({
             $ref: (field) => {
                 const placeholder = Object.freeze({
@@ -78,15 +128,60 @@ export function createTransactionPlanAssembler(contracts, protocol) {
                 return placeholder;
             },
         });
-        handles.set(handle, {
-            origin,
-            resource,
-            identity,
-            args: snapshot(identity, args),
-        });
+        handles.set(handle, record);
         return handle;
     };
-    const assemble = async (operations) => {
+    const defer = (origin, resource, identity, args) => createHandle({
+        kind: "operation",
+        origin,
+        resource,
+        identity,
+        ...snapshot(args),
+    });
+    const deferSql = (strings, values) => {
+        const copy = snapshot(values);
+        return createHandle({
+            kind: "sql",
+            strings: readSqlTemplate(strings, values.length),
+            values: Array.isArray(copy.args) ? copy.args : [],
+            ...(copy.refused === undefined ? {} : { refused: copy.refused }),
+        });
+    };
+    const recordPlaceholderSites = (record) => placeholderSites(record.kind === "sql" ? record.values : record.args);
+    const planSqlStatement = (record, positions) => {
+        const values = record.values.map((value) => {
+            const sites = placeholderSites(value);
+            const [site] = sites;
+            if (site === undefined) {
+                return { kind: "value", value };
+            }
+            if (site.path.length > 0) {
+                return { kind: "misplaced-reference", path: site.path };
+            }
+            return {
+                kind: "reference",
+                operation: positions.get(site.placeholder.source),
+                field: site.placeholder.field,
+            };
+        });
+        return {
+            strings: record.strings,
+            values,
+            ...(record.refused === undefined ? {} : { refused: record.refused }),
+        };
+    };
+    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,
@@ -119,18 +214,36 @@ export function createTransactionPlanAssembler(contracts, protocol) {
             positions.set(entry, index);
             records.push(record);
         }
+        const originOfRecord = (record) => record.kind === "sql" ? "application" : record.origin;
+        const [first] = records;
+        if (first !== undefined) {
+            const planOrigin = originOfRecord(first);
+            const other = records.findIndex((record) => originOfRecord(record) !== planOrigin);
+            if (other !== -1) {
+                return {
+                    ok: false,
+                    response: transactionOperationFailure(operationFailure("A2004", {
+                        message: "Transaction plan failed framework validation.",
+                        issues: [
+                            validationIssue("V1020", [], VALIDATION_CODE_MESSAGES.V1020),
+                        ],
+                    }), other),
+                };
+            }
+        }
         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 recordPlaceholderSites(record)) {
+                if (!positions.has(placeholder.source)) {
+                    return {
+                        ok: false,
+                        response: referenceFailure(validationIssue("V1010", [
+                            "operations",
+                            index,
+                            record.kind === "sql" ? "values" : "args",
+                            ...path,
+                            "$ref",
+                        ], "Transaction reference names an operation that is not in this transaction."), index),
+                    };
                 }
             }
         }
@@ -145,26 +258,20 @@ 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);
+            if (record.kind === "sql") {
+                return SQL_STEP_NODE;
+            }
+            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,
@@ -194,8 +301,14 @@ export function createTransactionPlanAssembler(contracts, protocol) {
             plan: {
                 operations: await Promise.all(records.map((_, index) => nodeAt(index))),
             },
-            origins: records.map((record) => originOf(record.origin)),
+            origins: records.map((record) => originOf(record.kind === "sql" ? "application" : record.origin)),
+            refused: new Map(records.flatMap((record, index) => record.kind === "sql" || record.refused === undefined
+                ? []
+                : [[index, record.refused]])),
+            statements: new Map(records.flatMap((record, index) => record.kind === "sql"
+                ? [[index, planSqlStatement(record, positions)]]
+                : [])),
         };
     };
-    return { defer, assemble };
+    return { defer, deferSql, assemble };
 }

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

@@ -1,24 +1,51 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { Contract } from "../contracts/contract.js";
-import type { ScalarField } from "../contracts/field.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
+import { AvCallerDataError } 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";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
 import type { OperationPipelineDependencies } from "../runtime/operation-runtime.js";
 import type { CascadeClosure } from "../runtime/referential-action.js";
 import type { OperationFingerprint } from "./deferred-operation.js";
-import type { TransactionReference } from "./transaction-reference.js";
+import type { PlannedSqlStatement, ValidatedSqlStatement } from "./sql-statement.js";
+import type { AvTransactionReference } 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, and `statements` the steps that are
+ *   `appTx.$sql` statements, which only the typed runner builds: they have no wire
+ *   form, so no plan a caller or a remote client hands in can hold one.
+ */
+export type PlanArguments = {
+    readonly source: "caller";
+} | {
+    readonly source: "owned";
+    readonly refused?: ReadonlyMap<number, AvCallerDataError>;
+    readonly statements?: ReadonlyMap<number, PlannedSqlStatement>;
 };
+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)[];
-    readonly field: ScalarField<Contract>;
-    readonly reference: TransactionReference;
+    /** The destination field. */
+    readonly field: AvScalarField<AvContract>;
+    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: AvScalarField<AvContract>;
+    readonly reference: AvTransactionReference;
 };
 export type CandidateTransactionOperation = {
     readonly index: number;
@@ -29,45 +56,50 @@ export type CandidateTransactionOperation = {
     readonly candidates: readonly TransactionReferenceCandidateSlot[];
 };
 export type ValidatedTransactionOperation = {
+    readonly kind: "operation";
     readonly index: number;
     readonly request: FrameworkOperationRequest;
     /**
-     * The Contract of this operation's own origin: the one it was validated
-     * against, the one it runs under, and the one a later `$ref` reads its source
-     * field from. One plan may carry steps of both origins.
+     * The Contract of this operation's origin, which is the plan's: the one it was
+     * validated against, the one it runs under, and the one a later `$ref` reads its
+     * source field from.
      */
-    readonly contract: Contract;
+    readonly contract: AvContract;
     readonly arguments: SemanticOperationArguments;
     readonly projection: ReadProjectionPlan | undefined;
     readonly fingerprint: OperationFingerprint;
     readonly references: readonly TransactionReferenceSlot[];
 };
+/** One validated plan step: a standard operation, or an `appTx.$sql` statement. */
+export type ValidatedTransactionStep = ValidatedTransactionOperation | ValidatedSqlStatement;
 export type ValidatedTransactionPlan = {
-    readonly operations: readonly ValidatedTransactionOperation[];
+    readonly operations: readonly ValidatedTransactionStep[];
 };
 /**
  * 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 AvAdapterModel> = Omit<OperationPipelineDependencies<M>, "recordWrites" | "contexts" | "fieldStages"> & {
     readonly cascades: CascadeClosure;
+    /** Whether the Adapter declares `sqlStatements`: read once, at construction. */
+    readonly sqlStatements: boolean;
 };
 export type TransactionPlanValidationResult = {
     readonly ok: true;
     readonly plan: ValidatedTransactionPlan;
 } | {
     readonly ok: false;
-    readonly response: OperationFailureResponse;
+    readonly response: AvOperationFailureResponse;
 };
 /**
  * The refusal of a plan on a Contract without transaction plans (`A2002`, one `V1006`
  * at `["operations"]`). The one spelling — the protocol's absence answer for
  * `/_transactions` is this envelope too.
  */
-export declare function transactionsUnavailableFailure(): OperationFailureResponse;
+export declare function transactionsUnavailableFailure(): AvOperationFailureResponse;
 /**
  * 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 AvAdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;