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

package/dist/transactions/deferred-operation.d.ts

@@ -1,12 +1,10 @@
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ExecutionOptions } from "../runtime/execution-options.js";
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
-import type { TransactionReference } from "./transaction-reference.js";
-import type { TransactionCommittedResponse } from "./transaction-response.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvExecutionOptions } from "../runtime/execution-options.js";
+import type { AvTransactionReference } from "./transaction-reference.js";
 /** An operation fingerprint: `fp1:` and a hash of the operation and its arguments. */
 export type OperationFingerprint = `fp1:${string}`;
 /** One serializable transaction-plan operation node. */
-export type DeferredOperation = OperationIdentity & {
+export type DeferredOperation = AvOperationIdentity & {
     readonly resource: string;
     readonly args: unknown;
     readonly fingerprint: OperationFingerprint;
@@ -17,34 +15,51 @@ export type TransactionPlan = {
 };
 declare const OPERATION_RESULT: unique symbol;
 declare const OPERATION_HANDLE: unique symbol;
+/** The origin a handle's builder gives it: `appTx`'s or `clientTx`'s. */
+type HandleOrigin = "application" | "client";
+type AnyOrigin = any;
 /** Standard-library shapes that are objects but never a projected result row. */
 export type BuiltinNonRow = Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | PromiseLike<unknown> | ArrayBufferView;
 /**
  * The single row behind a result type, or `never` when the result is not one
  * referenceable row.
  */
-export type SingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
+export type AvSingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
 /** The field names a result row can be referenced by. */
-export type ReferenceableField<T> = Extract<keyof SingleRowResult<T>, string>;
+export type AvReferenceableField<T> = Extract<keyof AvSingleRowResult<T>, string>;
 /** Builds a `$ref` to one field of this handle's row, typed as that field. */
-export type ReferenceBuilder<T> = <F extends ReferenceableField<T>>(field: F) => TransactionReference<SingleRowResult<T>[F]>;
+export type AvReferenceBuilder<T> = <F extends AvReferenceableField<T>>(field: F) => AvTransactionReference<AvSingleRowResult<T>[F]>;
 /** Contributes `$ref` only where the result is a referenceable single row. */
-export type OperationReferenceSurface<T> = [SingleRowResult<T>] extends [never] ? {} : {
-    readonly $ref: ReferenceBuilder<T>;
+export type AvOperationReferenceSurface<T> = [AvSingleRowResult<T>] extends [
+    never
+] ? {} : {
+    readonly $ref: AvReferenceBuilder<T>;
 };
-/** An opaque deferred-operation handle. */
-export type Operation<T> = {
-    readonly [OPERATION_HANDLE]: true;
+/**
+ * The opaque part of every deferred-operation handle: the result type `T` its
+ * transaction slot resolves to, and the origin of the builder that made it
+ * (`appTx` is `"application"`, `clientTx` is `"client"`; left out, either).
+ * Type-level only: a handle holds neither at runtime.
+ */
+export interface AvOperationHandle<T, Origin extends HandleOrigin = AnyOrigin> {
+    readonly [OPERATION_HANDLE]: Origin;
     readonly [OPERATION_RESULT]?: T;
-} & OperationReferenceSurface<T>;
+}
+/**
+ * An opaque deferred-operation handle: its result type and origin
+ * ({@link AvOperationHandle}), and `$ref` where the result is one row.
+ */
+export type AvOperation<T, Origin extends HandleOrigin = AnyOrigin> = AvOperationHandle<T, Origin> & AvOperationReferenceSurface<T>;
 /** Ordered results of a tuple of handles, positionally typed. */
-export type TransactionResults<Ops extends readonly Operation<unknown>[]> = {
-    readonly [I in keyof Ops]: Ops[I] extends Operation<infer R> ? R : never;
+export type AvTransactionResults<Ops extends readonly AvOperation<unknown>[]> = {
+    readonly [I in keyof Ops]: Ops[I] extends AvOperation<infer R> ? R : never;
 };
 /**
  * `framework.transaction`'s type. It infers the handle tuple without `as const`
- * and resolves the committed response (`A1009`) with each handle's result in
- * plan order, or the failure response.
+ * and resolves each handle's result in plan order once the transaction
+ * committed, or throws its failure as the `AvError` subclass of the code's class
+ * (`cause.operation` names the failing step). The handles are all `appTx`
+ * handles or all `clientTx` handles: a list that mixes them is a type error.
  */
-export type TransactionRunner = <const Ops extends readonly Operation<unknown>[]>(operations: Ops, options?: ExecutionOptions) => Promise<TransactionCommittedResponse<TransactionResults<Ops>> | OperationFailureResponse>;
+export type AvTransactionRunner = <const Ops extends readonly AvOperation<unknown, "application">[] | readonly AvOperation<unknown, "client">[]>(operations: Ops, options?: AvExecutionOptions) => Promise<AvTransactionResults<Ops>>;
 export {};

package/dist/transactions/operation-arguments-encoder.d.ts

@@ -1,7 +1,7 @@
-import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 /** Encodes validated application arguments into the wire scalar form. */
-export declare function encodeOperationArgumentsForWire(contract: Contract, operation: OperationIdentity & {
+export declare function encodeOperationArgumentsForWire(contract: AvContract, operation: AvOperationIdentity & {
     readonly resource: string;
 }, args: SemanticOperationArguments): unknown;

package/dist/transactions/operation-arguments-encoder.js

@@ -1,6 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { encodeBase64 } from "../contracts/wire-scalar-format.js";
-import { Decimal } from "../runtime/decimal.js";
+import { AvDecimal } from "../runtime/decimal.js";
 import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "../runtime/mutation-planner.js";
 import { isTransactionReferenceCandidate } from "./transaction-reference.js";
 function isPlainRecord(value) {
@@ -27,7 +27,7 @@ function encodeScalarAtom(field, value) {
         case "bigint":
             return typeof value === "bigint" ? value.toString(10) : value;
         case "decimal":
-            return value instanceof Decimal ? value.toString() : value;
+            return value instanceof AvDecimal ? value.toString() : value;
         case "datetime":
             return value instanceof Date ? value.toISOString() : value;
         case "bytes":

package/dist/transactions/sql-statement.d.ts

@@ -0,0 +1,77 @@
+import type { AvAdapterSqlValue } from "../adapters/adapter-sql-statement.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { AvCallerDataError } from "../runtime/caller-data.copier.js";
+import type { AvOperation } from "./deferred-operation.js";
+import type { AvTransactionReference } from "./transaction-reference.js";
+/**
+ * One value an `appTx.$sql` template binds: a primitive, a `Date`, an `AvDecimal`, a
+ * `Uint8Array`, a JSON value (a plain object or array, bound as JSON text — cast it,
+ * `${value}::jsonb`), or a `$ref` to an earlier step's field, resolved when the
+ * earlier steps have run and then bound like any other value.
+ */
+export type SqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
+/**
+ * `framework.appTx.$sql`: a developer SQL step, written only as a tagged template —
+ * ``framework.appTx.$sql`select pgmq.send('jobs', jsonb_build_object('id', ${ref}))` ``.
+ * Every interpolated value is bound as a parameter, never spliced into the text, so
+ * the text is static: a table or column name cannot come from a value.
+ *
+ * The step runs in plan order inside the same database transaction as the other
+ * steps; its entry in the committed `data` is the rows the statement returned,
+ * typed `Row[]` (`unknown[]` unless `Row` is given). A later step cannot `$ref` a
+ * SQL step's rows. No guard, pipe, hook, interceptor or filter runs around it: it
+ * has no Resource or operation for one to wrap.
+ */
+export type SqlStatementBuilder = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly SqlStatementValue[]) => AvOperation<Row[], "application">;
+/** One value of a planned SQL step, as the typed runner bound it. */
+export type PlannedSqlValue = {
+    readonly kind: "value";
+    readonly value: unknown;
+}
+/** A `$ref` placeholder standing as the whole value: the source's position and field. */
+ | {
+    readonly kind: "reference";
+    readonly operation: number;
+    readonly field: string;
+}
+/** A `$ref` placeholder found inside a value, at `path` within it: refused. */
+ | {
+    readonly kind: "misplaced-reference";
+    readonly path: readonly (string | number)[];
+};
+/**
+ * A SQL step as the typed runner hands it to the validator, unvalidated: the
+ * template's static text (`undefined` when the call was no genuine tagged
+ * template), its values with each `$ref` bound to its source's position, or why the
+ * builder could not copy the values.
+ */
+export type PlannedSqlStatement = {
+    readonly strings: readonly string[] | undefined;
+    readonly values: readonly PlannedSqlValue[];
+    readonly refused?: AvCallerDataError;
+};
+/** One validated value of a SQL step: bound as it is, or resolved from a `$ref`. */
+export type ValidatedSqlValue = {
+    readonly kind: "value";
+    readonly value: AvAdapterSqlValue;
+} | {
+    readonly kind: "reference";
+    readonly operation: number;
+    readonly field: string;
+    /** The source field, under its own step's Contract: what the value is read as. */
+    readonly source: AvScalarField<AvContract>;
+};
+/** A SQL step the Framework Validation Layer accepted. */
+export type ValidatedSqlStatement = {
+    readonly kind: "sql";
+    readonly index: number;
+    readonly strings: readonly string[];
+    readonly values: readonly ValidatedSqlValue[];
+};
+/**
+ * The static text of a genuine tagged template, read once and copied, or
+ * `undefined` when `strings` is not one or does not fit `valueCount` values.
+ * Total: a hostile value is `undefined`, never a throw.
+ */
+export declare function readSqlTemplate(strings: unknown, valueCount: number): readonly string[] | undefined;

package/dist/transactions/sql-statement.js

@@ -0,0 +1,47 @@
+function ownData(target, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    return descriptor !== undefined && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+}
+function frozenStrings(value, length) {
+    if (!Array.isArray(value) || !Object.isFrozen(value)) {
+        return undefined;
+    }
+    const size = ownData(value, "length");
+    if (typeof size !== "number" ||
+        size < 1 ||
+        (length !== undefined && size !== length)) {
+        return undefined;
+    }
+    const strings = [];
+    for (let index = 0; index < size; index += 1) {
+        const entry = ownData(value, String(index));
+        if (typeof entry !== "string") {
+            return undefined;
+        }
+        strings.push(entry);
+    }
+    return strings;
+}
+export function readSqlTemplate(strings, valueCount) {
+    try {
+        if (typeof strings !== "object" || strings === null) {
+            return undefined;
+        }
+        const raw = Object.getOwnPropertyDescriptor(strings, "raw");
+        if (raw === undefined || raw.enumerable || !("value" in raw)) {
+            return undefined;
+        }
+        const cooked = frozenStrings(strings, valueCount + 1);
+        if (cooked === undefined) {
+            return undefined;
+        }
+        return frozenStrings(raw.value, cooked.length) === undefined
+            ? undefined
+            : Object.freeze(cooked);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/transactions/sql-statement.validator.d.ts

@@ -0,0 +1,44 @@
+import type { AvAdapterSqlValue } from "../adapters/adapter-sql-statement.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import type { MisuseReporter } from "../runtime/misuse-reporter.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { PlannedSqlStatement, ValidatedSqlStatement } from "./sql-statement.js";
+import type { ValidatedTransactionStep } from "./transaction-plan-validator.js";
+type Path = readonly (string | number)[];
+export type SqlStatementValidation = {
+    readonly ok: true;
+    readonly statement: ValidatedSqlStatement;
+} | {
+    readonly ok: false;
+    readonly response: AvOperationFailureResponse;
+};
+/** What validating a SQL step needs from the plan around it. */
+export type SqlStatementValidationContext = {
+    /** The step's position in the plan. */
+    readonly index: number;
+    /** The steps validated before it, by position. */
+    readonly earlier: readonly ValidatedTransactionStep[];
+    /** Whether the Adapter declares `sqlStatements`. */
+    readonly available: boolean;
+    readonly misuse: MisuseReporter;
+};
+/**
+ * One bindable value of a SQL step, in its runtime form, or the issues that refuse
+ * it: a primitive (a `number` only when finite), a valid `Date`, an `AvDecimal`, a
+ * `Uint8Array`, or a JSON value — a plain object or array, held to the same rules
+ * as a `json` field's value. `undefined` and anything else are no value to bind.
+ */
+export declare function normalizeSqlValue(value: unknown, path: Path): {
+    readonly ok: true;
+    readonly value: AvAdapterSqlValue;
+} | {
+    readonly ok: false;
+    readonly issues: readonly AvValidationIssue[];
+};
+/**
+ * Validates one SQL step: the Adapter runs SQL statements, the call was a genuine
+ * tagged template, its values could be copied, every value is bindable, and every
+ * `$ref` stands as a whole value and reads one field of an earlier single-row step.
+ */
+export declare function validateSqlStatement(statement: PlannedSqlStatement, context: SqlStatementValidationContext): SqlStatementValidation;
+export {};

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,10 +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 { 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;
@@ -13,20 +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, 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>;
 };
@@ -35,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): TransactionPlanAssembler;
+export declare function createTransactionPlanAssembler(contracts: AvContracts, protocol: ClientProtocolIdentity, misuse: MisuseReporter): TransactionPlanAssembler;
 export {};