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

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

@@ -1,10 +1,15 @@
-import { validationIssue } from "../operations/validation-code.js";
+import { VALIDATION_CODE_MESSAGES, validationIssue, } from "../operations/validation-code.js";
+import { AvCallerDataError, } from "../runtime/caller-data.copier.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 { withoutUnsentWriteValues } from "../runtime/unsent-value.normalizer.js";
 import { encodeOperationArgumentsForWire } from "./operation-arguments-encoder.js";
 import { computeOperationFingerprint } from "./operation-fingerprint.js";
+import { readSqlTemplate } from "./sql-statement.js";
+import { routeTransactionReferenceCandidate } from "./transaction-reference.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;
@@ -13,26 +18,76 @@ function isPlainRecord(value) {
     return prototype === Object.prototype || prototype === null;
 }
 const KEEP = Symbol("keep");
-function rebuildArguments(value, path, leaf, ancestors = new Set()) {
-    const replaced = leaf(value, path);
-    if (replaced !== KEEP) {
-        return replaced;
-    }
-    if (!Array.isArray(value) && !isPlainRecord(value)) {
-        return value;
+function rebuildArguments(root, leaf) {
+    const pathOf = (parent, key) => () => {
+        const segments = [];
+        if (key !== undefined) {
+            segments.push(key);
+        }
+        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 (Object.hasOwn(value, "$ref")) {
+            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;
     }
-    if (ancestors.has(value)) {
-        return value;
+    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;
+        }
+        const rebuilt = finish(frame);
+        const parent = frame.parent;
+        if (parent === undefined) {
+            return rebuilt;
+        }
+        parent.built.push([frame.key, rebuilt]);
+        frame = parent;
     }
-    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", {
@@ -43,33 +98,35 @@ function operationEntryFailure(operation, message) {
 function referenceFailure(issue, operation) {
     return transactionOperationFailure(mapValidationOutcome([issue]), operation);
 }
+const STEP_REFERENCE_MIRROR = (value) => Object.hasOwn(value, "$ref");
 export function createTransactionPlanAssembler(contracts, protocol, misuse) {
     const handles = new WeakMap();
     const placeholders = new WeakMap();
     const originOf = (origin) => origin === "application"
         ? { origin: "application" }
         : { origin: "client", protocol };
-    const snapshot = (args) => {
+    const snapshot = (args, mirror) => {
         const copy = copyAtDoor(args, {
             keep: (value) => placeholders.has(value),
+            ...(mirror === undefined ? {} : { mirror }),
         });
         return copy.ok ? { args: copy.value } : { args: {}, refused: copy.error };
     };
     const placeholderSites = (args) => {
         const sites = [];
-        rebuildArguments(args, [], (value, path) => {
+        rebuildArguments(args, (value, pathOf) => {
             const placeholder = typeof value === "object" && value !== null
                 ? placeholders.get(value)
                 : undefined;
             if (placeholder === undefined) {
                 return KEEP;
             }
-            sites.push({ path, object: value, placeholder });
+            sites.push({ path: pathOf(), object: value, placeholder });
             return value;
         });
         return sites;
     };
-    const defer = (origin, resource, identity, args) => {
+    const createHandle = (record) => {
         const handle = Object.freeze({
             $ref: (field) => {
                 const placeholder = Object.freeze({
@@ -79,13 +136,62 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
                 return placeholder;
             },
         });
-        handles.set(handle, {
+        handles.set(handle, record);
+        return handle;
+    };
+    const defer = (origin, resource, identity, args) => {
+        const copy = snapshot(args, STEP_REFERENCE_MIRROR);
+        let sent = copy.args;
+        try {
+            sent = withoutUnsentWriteValues(origin === "application" ? contracts.application : contracts.client, { resource, family: identity.family }, copy.args);
+        }
+        catch (error) {
+            if (!(error instanceof AvCallerDataError)) {
+                throw error;
+            }
+        }
+        return createHandle({
+            kind: "operation",
             origin,
             resource,
             identity,
-            ...snapshot(args),
+            ...copy,
+            args: sent,
         });
-        return handle;
+    };
+    const deferSql = (strings, values) => {
+        const copy = snapshot(values, STEP_REFERENCE_MIRROR);
+        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 routeTransactionReferenceCandidate(value).kind === "ordinary"
+                    ? { kind: "value", value }
+                    : { kind: "candidate", candidate: 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 });
@@ -131,12 +237,35 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
             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, placeholder } of placeholderSites(record.args)) {
+            for (const { path, placeholder } of recordPlaceholderSites(record)) {
                 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),
+                        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),
                     };
                 }
             }
@@ -152,6 +281,9 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
         };
         const materialize = async (index) => {
             const record = records[index];
+            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);
@@ -160,7 +292,7 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
                     $ref: { operation, fingerprint, path: [placeholder.field] },
                 });
             }));
-            const args = rebuildArguments(record.args, [], (value) => typeof value === "object" && value !== null && bound.has(value)
+            const args = rebuildArguments(record.args, (value) => typeof value === "object" && value !== null && bound.has(value)
                 ? bound.get(value)
                 : KEEP);
             return {
@@ -192,9 +324,14 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
             plan: {
                 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]])),
+            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,15 +1,16 @@
-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 { CallerDataError } from "../runtime/caller-data.copier.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";
@@ -22,26 +23,45 @@ import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./
  *   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.
+ *   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, CallerDataError>;
+    readonly refused?: ReadonlyMap<number, AvCallerDataError>;
+    readonly statements?: ReadonlyMap<number, PlannedSqlStatement>;
 };
+/** A plan taken at a call, and the steps whose arguments could not be copied. */
+export type CapturedPlan = {
+    readonly plan: unknown;
+    readonly refused: ReadonlyMap<number, AvCallerDataError>;
+};
+/**
+ * A host's parsed plan taken at `protocol.handleTransaction`'s call, before its first
+ * await (rc.2, e2e batch 2): its structure mirrored by descriptors, which is how this
+ * validator inspects it — so no getter it refuses runs, and every accessor stays one
+ * for it to refuse — and each step's `args` copied as {@link captureSteps} copies a
+ * caller's, its `$ref` control objects mirrored. Run as an `"owned"` plan with
+ * `refused`, it is answered exactly as the plan the host held at the call. A plan
+ * that is no object, or cannot be reflected, is returned as it is: nothing in it can
+ * change.
+ */
+export declare function capturePlanAtCall(plan: unknown): CapturedPlan;
 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 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: ScalarField<Contract>;
-    readonly reference: TransactionReference;
+    readonly source: AvScalarField<AvContract>;
+    readonly reference: AvTransactionReference;
 };
 export type CandidateTransactionOperation = {
     readonly index: number;
@@ -52,21 +72,24 @@ 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
@@ -74,23 +97,25 @@ export type ValidatedTransactionPlan = {
  * 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>, "recordWrites"> & {
+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[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;
+export declare function validateTransactionPlan<M extends AvAdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;