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

package/dist/transactions/sql-statement.validator.js

@@ -0,0 +1,134 @@
+import { validationIssue } from "../operations/validation-code.js";
+import { refuseCallerData } from "../runtime/caller-data.door.js";
+import { AvDecimal } from "../runtime/decimal.js";
+import { planStepPath } from "../runtime/error-boundary.js";
+import { operationFailure } from "../runtime/operation-response.js";
+import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
+import { isPlainRecord, normalizeJsonValue, } from "../runtime/scalar-runtime.js";
+import { invalidSourceIndexIssue, referenceSourceAt, referenceSourceField, } from "./transaction-reference-validator.js";
+import { transactionOperationFailure } from "./transaction-response.js";
+function refused(issue, index) {
+    return {
+        ok: false,
+        response: transactionOperationFailure(mapValidationOutcome([issue]), index),
+    };
+}
+export function normalizeSqlValue(value, path) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint" ||
+        value instanceof AvDecimal ||
+        value instanceof Uint8Array) {
+        return { ok: true, value };
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value)
+            ? { ok: true, value }
+            : {
+                ok: false,
+                issues: [
+                    validationIssue("V1004", path, "Value must be a finite number."),
+                ],
+            };
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime())
+            ? {
+                ok: false,
+                issues: [
+                    validationIssue("V1003", path, "Value must use a valid Date value."),
+                ],
+            }
+            : { ok: true, value };
+    }
+    if (Array.isArray(value) || isPlainRecord(value)) {
+        const json = normalizeJsonValue(value, path, new Set());
+        return json.ok
+            ? { ok: true, value: json.value }
+            : { ok: false, issues: json.issues };
+    }
+    return {
+        ok: false,
+        issues: [
+            validationIssue("V1001", path, "Value must be a string, number, boolean, bigint, null, Date, Decimal, Uint8Array or JSON value."),
+        ],
+    };
+}
+export function validateSqlStatement(statement, context) {
+    const { index, earlier } = context;
+    if (!context.available) {
+        const message = "SQL statements are not available on this Adapter.";
+        return {
+            ok: false,
+            response: transactionOperationFailure(operationFailure("A2002", {
+                message,
+                issues: [validationIssue("V1006", [], message)],
+            }), index),
+        };
+    }
+    if (statement.strings === undefined) {
+        return refused(validationIssue("V1001", ["strings"], "SQL must be written as a tagged template: framework.appTx.$sql`…`."), index);
+    }
+    if (statement.refused !== undefined) {
+        return refused(refuseCallerData(statement.refused, [...planStepPath(index), "values"], { origin: "application", operation: index }, context.misuse), index);
+    }
+    const values = [];
+    const issues = [];
+    for (const [position, planned] of statement.values.entries()) {
+        const path = ["values", position];
+        switch (planned.kind) {
+            case "misplaced-reference":
+                return refused(validationIssue("V1010", [...path, ...planned.path, "$ref"], "A transaction reference in a SQL step must be a whole value."), index);
+            case "reference": {
+                const source = referenceSourceAt(earlier, planned.operation, index);
+                if (source === undefined) {
+                    return refused(invalidSourceIndexIssue([...path, "$ref", "operation"]), index);
+                }
+                const read = referenceSourceField(source, planned.field, [
+                    ...path,
+                    "$ref",
+                    "path",
+                ]);
+                if (!read.ok) {
+                    return refused(read.issue, index);
+                }
+                if (read.field.kind !== "scalar" || read.field.list) {
+                    return refused(validationIssue("V1011", [...path, "$ref", "path"], "Transaction reference source is not a single scalar field."), index);
+                }
+                values.push({
+                    kind: "reference",
+                    operation: planned.operation,
+                    field: planned.field,
+                    source: read.field,
+                });
+                break;
+            }
+            case "value": {
+                const normalized = normalizeSqlValue(planned.value, path);
+                if (normalized.ok) {
+                    values.push({ kind: "value", value: normalized.value });
+                }
+                else {
+                    issues.push(...normalized.issues);
+                }
+                break;
+            }
+        }
+    }
+    if (issues.length > 0) {
+        return {
+            ok: false,
+            response: transactionOperationFailure(mapValidationOutcome(issues), index),
+        };
+    }
+    return {
+        ok: true,
+        statement: {
+            kind: "sql",
+            index,
+            strings: statement.strings,
+            values,
+        },
+    };
+}

package/dist/transactions/transaction-envelope.d.ts

@@ -1,4 +1,4 @@
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 export type TransactionEnvelopeSchema = {
     readonly required: readonly string[];
     readonly optional?: readonly string[];
@@ -10,7 +10,7 @@ export type TransactionEnvelopeInspection = {
     readonly values: ReadonlyMap<string, unknown>;
 } | {
     readonly ok: false;
-    readonly issue: ValidationIssue;
+    readonly issue: AvValidationIssue;
 };
 export type TransactionOperationsInspection = {
     readonly ok: true;
@@ -18,14 +18,14 @@ export type TransactionOperationsInspection = {
     readonly length: number;
 } | {
     readonly ok: false;
-    readonly issue: ValidationIssue;
+    readonly issue: AvValidationIssue;
 };
 export type TransactionOperationEntryInspection = {
     readonly ok: true;
     readonly value: unknown;
 } | {
     readonly ok: false;
-    readonly issue: ValidationIssue;
+    readonly issue: AvValidationIssue;
 };
 /**
  * The caller uses the returned length and per-index inspector rather than

package/dist/transactions/transaction-integrity-error.d.ts

@@ -1,13 +1,13 @@
 /**
- * The ways an Adapter transaction can break the framework's transaction
- * contract. Each is answered `A3002`.
+ * The ways an Adapter transaction, or a stage running inside it, can break the
+ * framework's transaction contract. Each is answered `A3002` and rolls back.
  */
-export type TransactionIntegrityViolation = "transaction-unavailable" | "resolved-after-abort" | "resolved-incomplete" | "foreign-abort";
+export type AvTransactionIntegrityViolation = "transaction-unavailable" | "resolved-after-abort" | "resolved-incomplete" | "foreign-abort" | "statement-unavailable" | "next-called-twice" | "steps-not-run";
 /**
  * Reported to diagnostics when an Adapter transaction breaks the framework's
  * transaction contract. The caller receives `A3002`.
  */
-export declare class TransactionIntegrityError extends Error {
-    readonly violation: TransactionIntegrityViolation;
-    constructor(violation: TransactionIntegrityViolation);
+export declare class AvTransactionIntegrityError extends Error {
+    readonly violation: AvTransactionIntegrityViolation;
+    constructor(violation: AvTransactionIntegrityViolation);
 }

package/dist/transactions/transaction-integrity-error.js

@@ -3,12 +3,15 @@ const TRANSACTION_INTEGRITY_MESSAGES = {
     "resolved-after-abort": "Adapter transaction resolved after the framework requested rollback.",
     "resolved-incomplete": "Adapter transaction resolved before the plan completed.",
     "foreign-abort": "Adapter transaction rejected with a rollback request this plan never made.",
+    "statement-unavailable": "Adapter declares sqlStatements but its transaction executor has no executeSql.",
+    "next-called-twice": "A transaction interceptor called next() more than once; next() runs the plan's steps once.",
+    "steps-not-run": "A transaction interceptor resolved without calling next(); the plan's steps never ran.",
 };
-export class TransactionIntegrityError extends Error {
+export class AvTransactionIntegrityError extends Error {
     violation;
     constructor(violation) {
         super(TRANSACTION_INTEGRITY_MESSAGES[violation]);
-        this.name = "TransactionIntegrityError";
+        this.name = "AvTransactionIntegrityError";
         this.violation = violation;
     }
 }

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

@@ -1,12 +1,14 @@
-import type { FrameworkContracts } from "../compiler/contract.compiler.js";
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { CallerDataError } from "../runtime/caller-data.copier.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvCallerDataError } from "../runtime/caller-data.copier.js";
 import type { MisuseReporter } from "../runtime/misuse-reporter.js";
 import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
-import type { Operation, OperationFingerprint } from "./deferred-operation.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { AvOperation, OperationFingerprint } from "./deferred-operation.js";
+import type { PlannedSqlStatement } from "./sql-statement.js";
 import type { TransactionOperationOrigin } from "./transaction-request.js";
+/** The origin a handle's builder gives it. */
+type HandleOrigin = "application" | "client";
 /** One wire node, exactly as the transaction runtime receives it. */
 type WireOperationNode = {
     readonly resource: string;
@@ -15,22 +17,30 @@ type WireOperationNode = {
     readonly args: unknown;
     readonly fingerprint: OperationFingerprint | null;
 };
+declare const SQL_STEP_NODE: Readonly<{
+    fingerprint: null;
+}>;
+type PlanNode = WireOperationNode | typeof SQL_STEP_NODE;
 export type AssembledTransactionPlan = {
     readonly ok: true;
     readonly plan: {
-        readonly operations: readonly WireOperationNode[];
+        readonly operations: readonly PlanNode[];
     };
     /** Each operation's own origin, by index (mixed plans). */
     readonly origins: readonly TransactionOperationOrigin[];
     /** The steps whose arguments their builder could not copy, by index. */
-    readonly refused: ReadonlyMap<number, CallerDataError>;
+    readonly refused: ReadonlyMap<number, AvCallerDataError>;
+    /** The `appTx.$sql` steps, by index, with each `$ref` bound to its source's position. */
+    readonly statements: ReadonlyMap<number, PlannedSqlStatement>;
 } | {
     readonly ok: false;
-    readonly response: OperationFailureResponse;
+    readonly response: AvOperationFailureResponse;
 };
 export type TransactionPlanAssembler = {
     /** Defers one operation into a handle; nothing runs. */
-    defer(origin: RequestOrigin, resource: string, identity: OperationIdentity, args: unknown): Operation<unknown>;
+    defer(origin: HandleOrigin, resource: string, identity: AvOperationIdentity, args: unknown): AvOperation<unknown>;
+    /** Defers one `appTx.$sql` statement into a handle; nothing runs. */
+    deferSql(strings: unknown, values: readonly unknown[]): AvOperation<unknown>;
     /** Binds a list of handles into the passive plan, or refuses it. */
     assemble(operations: unknown): Promise<AssembledTransactionPlan>;
 };
@@ -39,5 +49,5 @@ export type TransactionPlanAssembler = {
  * handle, so a handle another instance built — typed against another model,
  * bound to other Contracts — is refused rather than run.
  */
-export declare function createTransactionPlanAssembler(contracts: FrameworkContracts, protocol: ClientProtocolIdentity, misuse: MisuseReporter): TransactionPlanAssembler;
+export declare function createTransactionPlanAssembler(contracts: AvContracts, protocol: ClientProtocolIdentity, misuse: MisuseReporter): TransactionPlanAssembler;
 export {};

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

@@ -1,10 +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;
@@ -13,26 +15,73 @@ 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 (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", {
@@ -57,19 +106,19 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
     };
     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,14 +128,48 @@ export function createTransactionPlanAssembler(contracts, protocol, misuse) {
                 return placeholder;
             },
         });
-        handles.set(handle, {
-            origin,
-            resource,
-            identity,
-            ...snapshot(args),
-        });
+        handles.set(handle, record);
         return handle;
     };
+    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) {
@@ -131,12 +214,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 +258,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 +269,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 +301,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,29 @@ 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>;
 };
 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 +56,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 +81,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>;