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

package/dist/transactions/transaction-runtime.js

@@ -1,81 +1,249 @@
-import { recordWriteFactsOf } from "../runtime/create-requirement.js";
-import { planOperationArgumentsPath } from "../runtime/error-boundary.js";
-import { internalFailure } from "../runtime/operation-response.js";
-import { executeValidatedOperation } from "../runtime/operation-runtime.js";
+import { transactionLevelsOf } from "../config/pipeline-tree.resolver.js";
+import { openRequestPolicy, } from "../policy/policy-request.js";
+import { AdapterBoundary, planOperationArgumentsPath, planStepPath, sanitizeOperationFailure, } from "../runtime/error-boundary.js";
+import { internalFailure, operationSuccess, } from "../runtime/operation-response.js";
+import { admitOperation, EVERY_FIELD, executeAdmittedOperation, prepareStep, STEP_PIPES, withRequestState, } from "../runtime/operation-runtime.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
+import { refusedStageOutput, serverContractFor, } from "../runtime/pipe-output.validator.js";
 import { resolveCascadeClosure } from "../runtime/referential-action.js";
-import { TransactionIntegrityError } from "./transaction-integrity-error.js";
+import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
 import { validateTransactionPlan } from "./transaction-plan-validator.js";
-import { resolveTransactionReferences } from "./transaction-reference-resolver.js";
+import { collectTransactionReferenceCandidates } from "./transaction-reference-collector.js";
+import { resolveSqlStatement, resolveTransactionReferences, } from "./transaction-reference-resolver.js";
+import { validateReferenceSlots } from "./transaction-reference-validator.js";
 import { transactionCommitted, transactionInfrastructureFailure, transactionOperationFailure, } from "./transaction-response.js";
-const TRANSACTION_ABORT = Object.freeze({ reason: "aventara-transaction-abort" });
-export function createTransactionRuntime(dependencies) {
-    const { adapter, ...runtimeDependencies } = dependencies;
-    const pipelineDependencies = {
-        ...runtimeDependencies,
-        recordWrites: recordWriteFactsOf(adapter),
-    };
+import { settleTransaction } from "./transaction-settlement.runtime.js";
+import { TRANSACTION_PIPES, touchedTransactionLevels, transactionFacts, } from "./transaction-stage.runtime.js";
+export function createTransactionRuntime(dependencies, pipelineDependencies) {
+    const { adapter } = dependencies;
     const planDependencies = {
         ...pipelineDependencies,
         cascades: resolveCascadeClosure(adapter.referentialActions),
+        sqlStatements: adapter.sqlStatements === true,
     };
-    return async (request, diagnostics, origins, planArguments) => {
+    return async (seeded, diagnostics, origins, planArguments, caller) => {
+        const request = withRequestState(seeded);
         const validation = await validateTransactionPlan(planDependencies, request, origins, planArguments);
         if (!validation.ok) {
             return validation.response;
         }
-        return executeTransactionPlan(adapter, pipelineDependencies, validation.plan, diagnostics);
+        return executeTransactionPlan(dependencies, pipelineDependencies, request, validation.plan, request.state, diagnostics, caller);
     };
 }
-async function executeTransactionPlan(adapter, dependencies, plan, diagnostics) {
-    const ledger = { results: [], failure: undefined };
-    const infrastructureFailure = (error) => {
-        const operation = ledger.failure?.operation;
-        diagnostics.transaction(operation)(error, "A3002");
-        return transactionInfrastructureFailure(operation);
+function planOrigin(request, plan) {
+    for (const step of plan.operations) {
+        if (step.kind === "operation") {
+            return step.request;
+        }
+    }
+    return request;
+}
+function stepView(step, args) {
+    if (step.kind === "sql") {
+        return {
+            sql: {
+                strings: step.strings,
+                values: step.values.map((value) => value.kind === "value"
+                    ? value.value
+                    : { $ref: { operation: value.operation, path: [value.field] } }),
+            },
+        };
+    }
+    return {
+        resource: step.request.resource,
+        family: step.request.family,
+        variant: step.request.variant,
+        args,
+    };
+}
+function pathKey(path) {
+    return JSON.stringify(path);
+}
+function relativeSlotPath(operation, path) {
+    return path.slice(planOperationArgumentsPath(operation.index).length);
+}
+function standingReferences(core, operation, args, steps, subject) {
+    const candidates = collectTransactionReferenceCandidates(serverContractFor(core, operation.contract), operation.request, operation.index, args);
+    const validation = validateReferenceSlots(candidates, steps, operation.index);
+    if (validation.ok) {
+        return validation;
+    }
+    const { issue } = validation;
+    const refused = refusedStageOutput(operation.request, [
+        {
+            ...issue,
+            path: ["arguments", ...relativeSlotPath(operation, issue.path ?? [])],
+        },
+    ], subject);
+    if (refused === undefined) {
+        throw new TypeError("A refused reference produced no refusal.");
+    }
+    return { ok: false, ...refused };
+}
+async function executeTransactionPlan(runtime, dependencies, request, plan, state, diagnostics, caller) {
+    const { adapter } = runtime;
+    const steps = new Map();
+    const stateful = (operation) => {
+        const known = steps.get(operation);
+        if (known !== undefined) {
+            return known;
+        }
+        const settle = (policy) => {
+            const step = policy === undefined
+                ? { ...operation.request, state }
+                : { ...operation.request, state, policy };
+            steps.set(operation, step);
+            return step;
+        };
+        const policy = openRequestPolicy(runtime.config.policy, runtime.contracts.core, { origin: operation.request.origin, state }, caller, adapter);
+        return policy instanceof Promise ? policy.then(settle) : settle(policy);
     };
-    if (typeof adapter.transaction !== "function") {
-        return infrastructureFailure(new TransactionIntegrityError("transaction-unavailable"));
+    const admitted = [];
+    const standing = [];
+    for (const step of plan.operations) {
+        if (step.kind === "sql") {
+            admitted.push({ ok: true, args: undefined, piped: false });
+            standing.push([]);
+            continue;
+        }
+        const report = diagnostics.operation(step.request, step.index);
+        let stepRequest;
+        try {
+            const opened = stateful(step);
+            stepRequest = opened instanceof Promise ? await opened : opened;
+        }
+        catch (error) {
+            report(error, "A3000");
+            return transactionOperationFailure(internalFailure(), step.index);
+        }
+        const admission = await admitOperation(dependencies, stepRequest, step.contract, step.arguments, planOperationArgumentsPath(step.index), report, { requestId: request.requestId, transaction: undefined, state }, {
+            select: EVERY_FIELD,
+            validation: { transactionReferences: true },
+            beforeBegin: true,
+        });
+        if (!admission.ok) {
+            return transactionOperationFailure(admission.response, step.index);
+        }
+        if (!admission.piped) {
+            standing.push(step.references);
+        }
+        else {
+            const references = standingReferences(dependencies.contracts.core, step, admission.args, plan.operations, STEP_PIPES);
+            if (!references.ok) {
+                report(references.error, "A3004");
+                return transactionOperationFailure(references.response, step.index);
+            }
+            standing.push(references.references);
+        }
+        admitted.push(admission);
     }
-    const runPlanOperation = async (operation, executor) => {
+    const origin = planOrigin(request, plan);
+    const contract = dependencies.contracts[origin.origin];
+    const tree = dependencies.config[origin.origin].pipelines;
+    const view = plan.operations.map((step, index) => stepView(step, admitted[index]?.args));
+    const runPlanOperation = async (operation, args, transactionPiped, executor, results, outer) => {
         const report = diagnostics.operation(operation.request, operation.index);
+        const argumentsPath = planOperationArgumentsPath(operation.index);
+        const opened = stateful(operation);
+        const stepRequest = opened instanceof Promise ? await opened : opened;
         try {
-            const resolved = resolveTransactionReferences(operation, ledger.results);
+            let live = standing[operation.index] ?? operation.references;
+            if (transactionPiped) {
+                const references = standingReferences(dependencies.contracts.core, operation, args, plan.operations, TRANSACTION_PIPES);
+                if (!references.ok) {
+                    report(references.error, "A3004");
+                    return references.response;
+                }
+                live = references.references;
+            }
+            const resolved = resolveTransactionReferences({
+                ...operation,
+                arguments: args,
+                references: live,
+            }, results);
             if (!resolved.ok) {
                 return mapValidationOutcome(resolved.issues);
             }
-            return await executeValidatedOperation(dependencies, operation.request, operation.contract, resolved.arguments, planOperationArgumentsPath(operation.index), executor, report);
+            const written = new Set(live
+                .filter((slot) => slot.written)
+                .map((slot) => pathKey(relativeSlotPath(operation, slot.path))));
+            const prepared = await prepareStep(dependencies, stepRequest, operation.contract, resolved.arguments, argumentsPath, report, executor, {
+                written: (path) => written.has(pathKey(path)),
+                transactionPiped,
+                pipedAroundReferences: admitted[operation.index]?.piped === true &&
+                    (live.length > 0 || operation.references.length > 0),
+            }, outer);
+            if (!prepared.ok) {
+                return prepared.response;
+            }
+            return await executeAdmittedOperation(dependencies, stepRequest, operation.contract, prepared.args, argumentsPath, { kind: "transaction", executor, outer }, report);
         }
         catch (error) {
             report(error, "A3000");
             return internalFailure();
         }
     };
-    try {
-        await adapter.transaction(async (executor) => {
-            for (const operation of plan.operations) {
-                const response = await runPlanOperation(operation, executor);
-                if (response.cause !== null) {
-                    ledger.failure = { response, operation: operation.index };
-                    throw TRANSACTION_ABORT;
-                }
-                ledger.results.push(response.data);
+    const runSqlStatement = async (step, executor, results) => {
+        const report = diagnostics.transaction(step.index);
+        const boundary = new AdapterBoundary();
+        try {
+            const resolved = resolveSqlStatement(step, results);
+            if (!resolved.ok) {
+                return mapValidationOutcome(resolved.issues);
+            }
+            if (typeof executor.executeSql !== "function") {
+                report(new AvTransactionIntegrityError("statement-unavailable"), "A3002");
+                return transactionInfrastructureFailure();
+            }
+            const executeSql = executor.executeSql.bind(executor);
+            try {
+                const rows = await boundary.execute(async () => {
+                    const answer = await executeSql(resolved.statement);
+                    if (!Array.isArray(answer)) {
+                        throw new TypeError("Adapter executeSql must resolve the statement's rows as an array.");
+                    }
+                    return answer;
+                });
+                return operationSuccess([...rows], "A1000");
+            }
+            catch (error) {
+                return sanitizeOperationFailure(error, boundary.originOf(error), report, {
+                    path: [...planStepPath(step.index), "values"],
+                    arguments: resolved.statement.values,
+                });
             }
-        });
-    }
-    catch (error) {
-        if (error !== TRANSACTION_ABORT) {
-            return infrastructureFailure(error);
         }
-        return ledger.failure === undefined
-            ? infrastructureFailure(new TransactionIntegrityError("foreign-abort"))
-            : transactionOperationFailure(ledger.failure.response, ledger.failure.operation);
-    }
-    if (ledger.failure !== undefined) {
-        return infrastructureFailure(new TransactionIntegrityError("resolved-after-abort"));
-    }
-    if (ledger.results.length !== plan.operations.length) {
-        return infrastructureFailure(new TransactionIntegrityError("resolved-incomplete"));
+        catch (error) {
+            report(error, "A3000");
+            return internalFailure();
+        }
+    };
+    const settled = await settleTransaction({
+        adapter,
+        levels: touchedTransactionLevels(view, (resource) => transactionLevelsOf(tree, resource)),
+        plan: view,
+        contextOf: (current, executor) => dependencies.contexts.transaction({ requestId: origin.requestId, transaction: executor, state }, transactionFacts(contract, origin, current)),
+        failureView: { path: ["operations"], arguments: view },
+        report: diagnostics.transaction(),
+        runStep: (index, step, piped, executor, results, outer) => {
+            const operation = plan.operations[index];
+            if (operation === undefined) {
+                throw new TypeError(`Transaction step ${index} is not in the plan.`);
+            }
+            return operation.kind === "sql"
+                ? runSqlStatement(operation, executor, results)
+                : runPlanOperation(operation, step.args, piped, executor, results, outer);
+        },
+    });
+    switch (settled.kind) {
+        case "committed":
+            return transactionCommitted(settled.responses.map((response) => response.data));
+        case "rolled-back":
+            return settled.operation === undefined
+                ? settled.response
+                : transactionOperationFailure(settled.response, settled.operation);
+        case "broken":
+            diagnostics.transaction(settled.operation)(settled.error, "A3002");
+            return transactionInfrastructureFailure(settled.operation);
     }
-    return transactionCommitted([...ledger.results]);
 }

package/dist/transactions/transaction-settlement.runtime.d.ts

@@ -0,0 +1,52 @@
+import type { AvAdapter } from "../adapters/adapter.interface.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterTransactionExecutor } from "../adapters/adapter-transaction-executor.interface.js";
+import type { ResolvedTransactionPipelineConfig } from "../config/pipeline-config.js";
+import type { DiagnosticsReporter } from "../runtime/diagnostics-reporter.js";
+import { type CallerArgumentsView, type OuterFailureLayer } from "../runtime/error-boundary.js";
+import type { AvOperationFailureResponse, AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvTransactionContext } from "../runtime/pipeline.js";
+import { type TransactionStepView } from "./transaction-stage.runtime.js";
+/**
+ * Runs one step inside the open transaction: `step` as the transaction pipes
+ * left it, `piped` whether one ran, `results` the completed steps' data in plan
+ * order, `outer` where an error the step's own filters leave unhandled is handed:
+ * the touched Resources' transaction filters answer it once the transaction
+ * interceptors have unwound. Its answer is the step's own outcome.
+ */
+type TransactionStepRunner<M extends AvAdapterModel> = (index: number, step: TransactionStepView, piped: boolean, executor: AvAdapterTransactionExecutor<M>, results: readonly unknown[], outer: OuterFailureLayer) => Promise<AvOperationResponse>;
+/** How one transaction settled. */
+type TransactionSettlement = 
+/** Committed: every step's own outcome, in plan order. */
+{
+    readonly kind: "committed";
+    readonly responses: readonly AvOperationResponse[];
+}
+/** Rolled back on a deliberate outcome: a step's (with its index) or a stage's. */
+ | {
+    readonly kind: "rolled-back";
+    readonly response: AvOperationFailureResponse;
+    readonly operation: number | undefined;
+}
+/** The transaction contract broke: `A3002`, the error for diagnostics. */
+ | {
+    readonly kind: "broken";
+    readonly error: unknown;
+    readonly operation: number | undefined;
+};
+type TransactionSettlementInput<M extends AvAdapterModel> = {
+    readonly adapter: AvAdapter<M>;
+    /** The touched Resources' transaction levels, outer to inner. */
+    readonly levels: readonly ResolvedTransactionPipelineConfig[];
+    readonly plan: readonly TransactionStepView[];
+    /** The ctx a transaction stage is told, bound to the open transaction. */
+    readonly contextOf: (plan: readonly TransactionStepView[], executor: AvAdapterTransactionExecutor<M>) => AvTransactionContext;
+    /** What a stage failure's filters may read as the caller's arguments. */
+    readonly failureView: CallerArgumentsView;
+    /** The channel a transaction stage's own failure is reported on. */
+    readonly report: DiagnosticsReporter;
+    readonly runStep: TransactionStepRunner<M>;
+};
+/** Runs `plan` inside one Adapter transaction, its stages around its steps, and settles it. */
+export declare function settleTransaction<M extends AvAdapterModel>(input: TransactionSettlementInput<M>): Promise<TransactionSettlement>;
+export {};

package/dist/transactions/transaction-settlement.runtime.js

@@ -0,0 +1,120 @@
+import { filterChain, resolveUnhandledFailure, sanitizeOperationFailure, } from "../runtime/error-boundary.js";
+import { thrownFailure } from "../runtime/framework-error.factory.js";
+import { operationFailure } from "../runtime/operation-response.js";
+import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
+import { resolveTransactionStageFailure, runTransactionStages, TRANSACTION_ABORT, } from "./transaction-stage.runtime.js";
+export async function settleTransaction(input) {
+    const { adapter, levels, plan, contextOf } = input;
+    if (typeof adapter.transaction !== "function") {
+        return {
+            kind: "broken",
+            error: new AvTransactionIntegrityError("transaction-unavailable"),
+            operation: undefined,
+        };
+    }
+    const ledger = { results: [], responses: [], failure: undefined, deferred: undefined };
+    const { results, responses } = ledger;
+    const failedOperation = () => ledger.failure?.kind === "rolled-back"
+        ? ledger.failure.operation
+        : undefined;
+    try {
+        await adapter.transaction(async (executor) => {
+            const staged = await runTransactionStages(levels, plan, (current) => contextOf(current, executor), async ({ plan: current, piped }) => {
+                const outer = {
+                    defer: (failure) => {
+                        ledger.deferred = { failure, plan: current };
+                        return sanitizeOperationFailure(failure.error, failure.boundary.originOf(failure.error), () => { }, failure.view);
+                    },
+                };
+                for (const [index, step] of current.entries()) {
+                    const response = await input.runStep(index, step, piped, executor, results, outer);
+                    if (response.cause !== null) {
+                        ledger.failure = {
+                            kind: "rolled-back",
+                            response,
+                            operation: index,
+                        };
+                        throw thrownFailure(response);
+                    }
+                    results.push(response.data);
+                    responses.push(response);
+                }
+                return [...results];
+            });
+            if (staged.kind === "broken") {
+                ledger.failure = { kind: "broken", error: staged.error };
+                throw TRANSACTION_ABORT;
+            }
+            const deferred = ledger.deferred;
+            if (deferred !== undefined && ledger.failure?.kind === "rolled-back") {
+                ledger.failure = {
+                    ...ledger.failure,
+                    response: await resolveUnhandledFailure(deferred.failure, filterChain(levels.flatMap((level) => level.filters), contextOf(deferred.plan, executor))),
+                };
+            }
+            if (staged.kind === "ran") {
+                if (ledger.failure === undefined && results.length !== plan.length) {
+                    ledger.failure = {
+                        kind: "broken",
+                        error: new AvTransactionIntegrityError("steps-not-run"),
+                    };
+                }
+                if (ledger.failure !== undefined) {
+                    throw TRANSACTION_ABORT;
+                }
+                return;
+            }
+            if (ledger.failure === undefined) {
+                let response;
+                if (staged.kind === "denied") {
+                    response = operationFailure("A4001", {
+                        message: "Operation denied by a framework guard.",
+                    });
+                }
+                else if (staged.kind === "refused") {
+                    input.report(staged.refusal.error, "A3004");
+                    response = staged.refusal.response;
+                }
+                else {
+                    response = await resolveTransactionStageFailure(staged.error, levels, contextOf(plan, executor), input.report, input.failureView);
+                }
+                ledger.failure = {
+                    kind: "rolled-back",
+                    response,
+                    operation: undefined,
+                };
+            }
+            throw TRANSACTION_ABORT;
+        });
+    }
+    catch (error) {
+        if (error !== TRANSACTION_ABORT) {
+            return { kind: "broken", error, operation: failedOperation() };
+        }
+        if (ledger.failure === undefined) {
+            return {
+                kind: "broken",
+                error: new AvTransactionIntegrityError("foreign-abort"),
+                operation: undefined,
+            };
+        }
+        return ledger.failure.kind === "broken"
+            ? { kind: "broken", error: ledger.failure.error, operation: undefined }
+            : ledger.failure;
+    }
+    if (ledger.failure !== undefined) {
+        return {
+            kind: "broken",
+            error: new AvTransactionIntegrityError("resolved-after-abort"),
+            operation: failedOperation(),
+        };
+    }
+    if (responses.length !== plan.length) {
+        return {
+            kind: "broken",
+            error: new AvTransactionIntegrityError("resolved-incomplete"),
+            operation: undefined,
+        };
+    }
+    return { kind: "committed", responses };
+}

package/dist/transactions/transaction-slot-path-error.d.ts

@@ -2,13 +2,13 @@
  * The ways a transaction slot path can fail to name a member of its argument
  * view. Each is a framework defect, not a caller error.
  */
-export type TransactionSlotPathViolation = "slot-prefix" | "absent-member" | "non-object-ancestor";
+export type AvTransactionSlotPathViolation = "slot-prefix" | "absent-member" | "non-object-ancestor";
 /**
  * Thrown internally when a slot path does not name a member of its argument
  * view; the caller receives `A3000`, and the diagnostics sink receives this
  * error.
  */
-export declare class TransactionSlotPathError extends Error {
-    readonly violation: TransactionSlotPathViolation;
-    constructor(violation: TransactionSlotPathViolation);
+export declare class AvTransactionSlotPathError extends Error {
+    readonly violation: AvTransactionSlotPathViolation;
+    constructor(violation: AvTransactionSlotPathViolation);
 }

package/dist/transactions/transaction-slot-path-error.js

@@ -1,13 +1,15 @@
+import { brandCoreClass } from "../runtime/core-class.brand.js";
 const TRANSACTION_SLOT_PATH_MESSAGES = {
     "slot-prefix": "Transaction slot path does not name a member below the operation's arguments.",
     "absent-member": "Transaction slot path names an absent member of the operation arguments.",
     "non-object-ancestor": "Transaction slot path descends through a non-object value.",
 };
-export class TransactionSlotPathError extends Error {
+export class AvTransactionSlotPathError extends Error {
     violation;
     constructor(violation) {
         super(TRANSACTION_SLOT_PATH_MESSAGES[violation]);
-        this.name = "TransactionSlotPathError";
+        this.name = "AvTransactionSlotPathError";
         this.violation = violation;
     }
 }
+brandCoreClass(AvTransactionSlotPathError, "AvTransactionSlotPathError");

package/dist/transactions/transaction-slot-writer.js

@@ -1,6 +1,6 @@
-import { TransactionSlotPathError } from "./transaction-slot-path-error.js";
+import { AvTransactionSlotPathError } from "./transaction-slot-path-error.js";
 function slotPathMismatch(violation) {
-    throw new TransactionSlotPathError(violation);
+    throw new AvTransactionSlotPathError(violation);
 }
 function cloneContainerWithReplacement(container, property, replacement) {
     const array = Array.isArray(container);

package/dist/transactions/transaction-stage.runtime.d.ts

@@ -0,0 +1,83 @@
+import type { ResolvedTransactionPipelineConfig } from "../config/pipeline-config.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { ContextFacts } from "../runtime/context-executor.runtime.js";
+import type { DiagnosticsReporter } from "../runtime/diagnostics-reporter.js";
+import { type CallerArgumentsView } from "../runtime/error-boundary.js";
+import type { OperationExecutionRequest } from "../runtime/operation-request.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type RefusedStageOutput } from "../runtime/pipe-output.validator.js";
+import type { AvTransactionContext, AvTransactionStep } from "../runtime/pipeline.js";
+import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
+/**
+ * The framework-owned rollback request. It is thrown out of the Adapter transaction
+ * callback only after a failure is recorded, and a rejection is recognized as it
+ * solely by identity — never by message, shape or class. It is a control signal,
+ * not a failure, so it never reaches diagnostics.
+ */
+export declare const TRANSACTION_ABORT: Readonly<{
+    readonly reason: "aventara-transaction-abort";
+}>;
+/** One plan step as a transaction stage reads it (the erased {@link AvTransactionStep}). */
+export type TransactionStepView = AvTransactionStep;
+/** The subject a refused transaction pipe output is reported under. */
+export declare const TRANSACTION_PIPES = "Transaction pipes";
+/**
+ * The `$` facts a transaction stage is told: the plan as `$args`, not one
+ * operation (`$operation` is absent). Each ctx holds its own frozen copy of the
+ * plan, a `Date` or a `Uint8Array` in a step's arguments fresh.
+ */
+export declare function transactionFacts(contract: AvContract, request: Pick<OperationExecutionRequest, "origin" | "requestId" | "transport">, plan: readonly TransactionStepView[]): ContextFacts;
+/** How the transaction stages around a plan's steps ended. */
+type TransactionStagesOutcome = 
+/** Every stage and step ran; the steps' results, as the stages left them. */
+{
+    readonly kind: "ran";
+}
+/** A transaction guard returned `false`: `A4001`. */
+ | {
+    readonly kind: "denied";
+}
+/** A transaction pipe returned something that is not the plan: `A3004`. */
+ | {
+    readonly kind: "refused";
+    readonly refusal: RefusedStageOutput;
+}
+/** A stage or a step threw (the rollback request included). */
+ | {
+    readonly kind: "failed";
+    readonly error: unknown;
+}
+/**
+ * A transaction interceptor broke the stages' contract: it called `next()`
+ * twice (whatever it then did with the refusal). Answered `A3002`, past every
+ * filter, and the transaction rolls back.
+ */
+ | {
+    readonly kind: "broken";
+    readonly error: AvTransactionIntegrityError;
+};
+/**
+ * What the steps see after the stages: the plan, and whether a transaction pipe
+ * changed it, in which case every operation step's arguments are held to the
+ * server's rules and its validators again before it runs.
+ */
+type StagedPlan = {
+    readonly plan: readonly TransactionStepView[];
+    readonly piped: boolean;
+};
+/**
+ * Each touched Resource's transaction levels, root then overlay, Resources in the
+ * order their first top-level operation step appears. A SQL step touches nothing.
+ */
+export declare function touchedTransactionLevels(plan: readonly TransactionStepView[], levelsOf: (resource: string) => readonly ResolvedTransactionPipelineConfig[]): readonly ResolvedTransactionPipelineConfig[];
+/**
+ * Runs the transaction stages of `levels` around `runSteps`, inside an open
+ * transaction. Never throws: every way the stages can end is the outcome.
+ */
+export declare function runTransactionStages(levels: readonly ResolvedTransactionPipelineConfig[], plan: readonly TransactionStepView[], contextOf: (plan: readonly TransactionStepView[]) => AvTransactionContext, runSteps: (staged: StagedPlan) => Promise<readonly unknown[]>): Promise<TransactionStagesOutcome>;
+/**
+ * An error a transaction stage threw, through the touched Resources' filters in
+ * exact reverse (the first that handles it wins), then final sanitization.
+ */
+export declare function resolveTransactionStageFailure(error: unknown, levels: readonly ResolvedTransactionPipelineConfig[], context: AvTransactionContext, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<AvOperationFailureResponse>;
+export {};