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

package/dist/runtime/output-validator.d.ts

@@ -1,14 +1,14 @@
-import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 import type { ReadProjectionPlan } from "./computed-read-runtime.js";
 export type OutputValidationResult = {
     readonly ok: true;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
-type OutputOperation = OperationIdentity & {
+type OutputOperation = AvOperationIdentity & {
     readonly resource: string;
 };
 /**
@@ -16,11 +16,11 @@ type OutputOperation = OperationIdentity & {
  * validation: whose result it was and what the validator found. The caller
  * receives the generic `A3000` and never this.
  */
-export declare class OutputValidationError extends Error {
-    readonly issues: readonly ValidationIssue[];
-    readonly name = "OutputValidationError";
-    constructor(operation: OutputOperation, issues: readonly ValidationIssue[]);
+export declare class AvOutputValidationError extends Error {
+    readonly issues: readonly AvValidationIssue[];
+    readonly name = "AvOutputValidationError";
+    constructor(operation: OutputOperation, issues: readonly AvValidationIssue[]);
 }
 /** Validate final operation output against fixed cardinality and executed projection. */
-export declare function validateOperationOutput(contract: Contract, operation: OutputOperation, projection: ReadProjectionPlan | undefined, value: unknown): OutputValidationResult;
+export declare function validateOperationOutput(contract: AvContract, operation: OutputOperation, projection: ReadProjectionPlan | undefined, value: unknown): OutputValidationResult;
 export {};

package/dist/runtime/output-validator.js

@@ -1,5 +1,5 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
-import { advertisedReducers } from "../contracts/field.js";
+import { advertisedReducers, } from "../contracts/field.js";
 import { normalizeScalarFieldValue } from "./scalar-runtime.js";
 function issue(message, path = ["data"]) {
     return { ok: false, issues: [{ path, code: "V1001", message }] };
@@ -168,9 +168,9 @@ function validateProjection(contract, operation, projection, value) {
         ? validateExactRecord(contract, value, projection, ["data"])
         : { ok: true };
 }
-export class OutputValidationError extends Error {
+export class AvOutputValidationError extends Error {
     issues;
-    name = "OutputValidationError";
+    name = "AvOutputValidationError";
     constructor(operation, issues) {
         const [first] = issues;
         super(`The result of ${operation.resource}.${operation.family}.${operation.variant} does not satisfy its Contract${first === undefined

package/dist/runtime/owned-execution.registry.d.ts

@@ -1,11 +1,11 @@
-import type { ClientTransactionRequest } from "../transactions/transaction-request.js";
-import type { TransactionResponse } from "../transactions/transaction-response.js";
-import type { ClientOperationRequest } from "./operation-request.js";
-import type { OperationResponse } from "./operation-response.js";
+import type { AgentTransactionRequest, ClientTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvTransactionResponse } from "../transactions/transaction-response.js";
+import type { RemoteOperationRequest } from "./operation-request.js";
+import type { AvOperationResponse } from "./operation-response.js";
 /** The two entries that run a request the protocol decoded itself, uncopied. */
 export type OwnedExecution = {
-    readonly execute: (request: ClientOperationRequest) => Promise<OperationResponse>;
-    readonly executeTransaction: (request: ClientTransactionRequest) => Promise<TransactionResponse>;
+    readonly execute: (request: RemoteOperationRequest) => Promise<AvOperationResponse>;
+    readonly executeTransaction: (request: ClientTransactionRequest | AgentTransactionRequest) => Promise<AvTransactionResponse>;
 };
 /** Records `framework`'s owned entries; called once, at construction. */
 export declare function recordOwnedExecution(framework: object, execution: OwnedExecution): void;

package/dist/runtime/pipe-output.validator.d.ts

@@ -1,7 +1,8 @@
-import type { Contract, CoreContract } from "../contracts/contract.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
-import type { OperationFailureResponse } from "./operation-response.js";
+import type { AvContract, AvContractCore } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { OperationValidationOptions } from "../operations/operation-validator.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import type { AvOperationFailureResponse } from "./operation-response.js";
 /**
  * The check a pipe's output passes before it can reach the Adapter.
  *
@@ -12,37 +13,51 @@ import type { OperationFailureResponse } from "./operation-response.js";
  * are held to the **server's** rules — the Core Contract, plus the fields the
  * active scope itself adds (they are virtual: computed, then stripped before
  * the Adapter call) — in the values' runtime forms (`bigint`, `Date`,
- * `Decimal`, `Uint8Array`), which is what every pipe receives.
+ * `AvDecimal`, `Uint8Array`), which is what every pipe receives.
  *
  * A refusal is the server's defect, not the caller's: `A3004
  * PIPE_OUTPUT_INVALID`, a 500 that tells the caller no more than any internal
  * failure does — {@link PIPE_OUTPUT_FAILURE_MESSAGE}, and the step in a plan.
  * The pipe, the operation, the first offending field and its V-code go to the
- * diagnostics channel only, as a {@link PipeOutputError}: they name server
+ * diagnostics channel only, as a {@link AvPipeOutputError}: they name server
  * internals — a pipe's function name, a field the caller's Contract hides.
  */
 /** The one text every `A3004` carries on the wire. */
 export declare const PIPE_OUTPUT_FAILURE_MESSAGE = "A server pipeline produced invalid arguments.";
 /** The error the diagnostics channel receives for a refused pipe output. */
-export declare class PipeOutputError extends Error {
-    readonly issues: readonly ValidationIssue[];
-    readonly name = "PipeOutputError";
-    constructor(message: string, issues: readonly ValidationIssue[]);
+export declare class AvPipeOutputError extends Error {
+    readonly issues: readonly AvValidationIssue[];
+    readonly name = "AvPipeOutputError";
+    constructor(message: string, issues: readonly AvValidationIssue[]);
 }
+/** A refused stage output: the `A3004` answer and what diagnostics are told. */
+export type RefusedStageOutput = {
+    readonly response: AvOperationFailureResponse;
+    readonly error: AvPipeOutputError;
+};
 /**
  * `undefined` when the pipe's output passes the server's rules; otherwise the
  * `A3004` failure, and the error the diagnostics channel is told.
  */
 export declare function refusePipeOutput(contracts: {
-    readonly core: CoreContract;
-    readonly active: Contract;
-}, request: OperationIdentity & {
+    readonly core: AvContractCore;
+    readonly active: AvContract;
+}, request: AvOperationIdentity & {
     readonly resource: string;
 }, args: unknown, 
 /** The pipe that produced `args`, named in the message by its function name. */
 pipe: unknown, 
-/** Its position in the effective pipe list (root pipes first). */
-index: number): {
-    readonly response: OperationFailureResponse;
-    readonly error: PipeOutputError;
-} | undefined;
+/** Its position in the effective pipe list (outer levels first). */
+index: number, 
+/** A plan step's pipes run before BEGIN, its `$ref` slots unresolved: these admit them. */
+options?: OperationValidationOptions): RefusedStageOutput | undefined;
+/**
+ * {@link refusePipeOutput} for any stage that changed the arguments; `subject`
+ * names it in the diagnostic (`Field pipes`, `Transaction pipes`).
+ */
+export declare function refuseStageOutput(contracts: {
+    readonly core: AvContractCore;
+    readonly active: AvContract;
+}, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, subject: string, options?: OperationValidationOptions): RefusedStageOutput | undefined;

package/dist/runtime/pipe-output.validator.js

@@ -27,15 +27,12 @@ function serverContractFor(core, active) {
     }
     return view;
 }
-function serverIssues(contract, request, args) {
-    const validation = validateOperationArguments(contract, {
-        ...request,
-        arguments: args,
-    });
+function serverIssues(contract, request, args, options) {
+    const validation = validateOperationArguments(contract, { ...request, arguments: args }, options);
     if (!validation.ok) {
         return validation.issues;
     }
-    const normalization = normalizeOperationScalarValues(contract, { ...request, arguments: validation.arguments }, "application");
+    const normalization = normalizeOperationScalarValues(contract, { ...request, arguments: validation.arguments }, "application", options);
     return normalization.ok ? [] : normalization.issues;
 }
 function pipeLabel(pipe, index) {
@@ -55,25 +52,28 @@ function fieldOf(issue) {
     const relative = path[0] === "arguments" ? path.slice(1) : path;
     return relative.length === 0 ? "(arguments)" : relative.join(".");
 }
-export class PipeOutputError extends Error {
+export class AvPipeOutputError extends Error {
     issues;
-    name = "PipeOutputError";
+    name = "AvPipeOutputError";
     constructor(message, issues) {
         super(message);
         this.issues = issues;
     }
 }
-export function refusePipeOutput(contracts, request, args, pipe, index) {
-    const issues = serverIssues(serverContractFor(contracts.core, contracts.active), request, args);
+export function refusePipeOutput(contracts, request, args, pipe, index, options) {
+    return refuseStageOutput(contracts, request, args, `Pipe ${pipeLabel(pipe, index)}`, options);
+}
+export function refuseStageOutput(contracts, request, args, subject, options) {
+    const issues = serverIssues(serverContractFor(contracts.core, contracts.active), request, args, options);
     const [first] = issues;
     if (first === undefined) {
         return undefined;
     }
-    const message = `Pipe ${pipeLabel(pipe, index)} returned arguments for ${request.resource}.${request.family}.${request.variant} that the server contract refuses at "${fieldOf(first)}" (${first.code}: ${first.message})`;
+    const message = `${subject} returned arguments for ${request.resource}.${request.family}.${request.variant} that the server contract refuses at "${fieldOf(first)}" (${first.code}: ${first.message})`;
     return {
         response: operationFailure("A3004", {
             message: PIPE_OUTPUT_FAILURE_MESSAGE,
         }),
-        error: new PipeOutputError(message, issues),
+        error: new AvPipeOutputError(message, issues),
     };
 }

package/dist/runtime/pipeline.d.ts

@@ -1,54 +1,216 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { FrameworkResourceKey } from "../config/framework-fields-config.js";
-import type { Contract } from "../contracts/contract.js";
-import type { OperationFamily } from "../operations/operation-identity.js";
-import type { FrameworkError } from "./framework-error.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterSqlValue } from "../adapters/adapter-sql-statement.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvConfigResourceKey } from "../config/framework-field-definition.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvApplicationScalarForms } from "../contracts/scalar-value-type.js";
+import type { AvContractApplicationView } from "../framework/contract-view.js";
+import type { AvContextOperations } from "../framework/operation-facade.js";
+import type { AvOperationArgumentsFor, AvResourceKey } from "../operations/operation-arguments.js";
+import type { AvOperationFamily, AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvTransactionReference } from "../transactions/transaction-reference.js";
+import type { AvError } from "./framework-error.js";
+import type { AvDeepReadonly, AvDeepReadonlyLeaf } from "./readonly-value.js";
+import type { AvState } from "./request-state.js";
 /**
  * What a pipeline is told about the HTTP request a client-origin operation arrived on.
  */
-export type PipelineTransportContext = {
+export type AvTransportContext = {
     readonly method: "POST";
     readonly headers: Readonly<Record<string, string>>;
 };
-/** What a pipeline callback is told about the operation it is wrapping. */
-export type PipelineContext<M extends AdapterModel = AdapterModel> = {
-    readonly contract: Contract;
-    readonly origin: RequestOrigin;
-    readonly resource: FrameworkResourceKey<M>;
-    readonly family: OperationFamily;
-    readonly variant: string;
-    readonly args: unknown;
-    readonly requestId: string;
-    readonly transport?: PipelineTransportContext;
+/** What a pipeline ctx states about the request, whatever the stage. */
+type AvContextFacts = {
+    /** `"application"` for server code and ctx calls, `"client"` for a remote caller. */
+    readonly $origin: AvRequestOrigin;
+    readonly $requestId: string;
+    /** The HTTP request a client-origin operation arrived on, when it did. */
+    readonly $transport?: AvTransportContext;
+    /** The active Contract: the Application or the Client Contract. */
+    readonly $contract: AvContract;
+    /**
+     * The request's state: the one writable per-request space. Every stage of the
+     * request, a transaction's steps and transaction stages, and the ctx calls they
+     * make share this object. Seeded by the caller or the host; `{}` otherwise. Its
+     * members are the application's, declared by augmenting {@link AvState}.
+     */
+    readonly $state: AvState;
+};
+/**
+ * `ctx.$sql`: a developer SQL statement, written only as a tagged template —
+ * ``await ctx.$sql<Row>`insert into audit (actor) values (${actorId})` `` — run at
+ * once. Every interpolated value is bound as a parameter, never spliced into the
+ * text. It runs in the current transaction; outside one, as a plain statement,
+ * with no transaction opened around it. Resolves the rows the statement returned.
+ */
+export type AvContextSql = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly AvAdapterSqlValue[]) => Promise<Row[]>;
+/**
+ * The arguments a variant-level stage is told: the operation's arguments under
+ * the model's Application Contract view, in the application forms, a reference
+ * position admitting an unresolved `$ref`. `unknown` for a model whose Resource
+ * names are not literal.
+ */
+export type AvStageArguments<M extends AvAdapterModel, R extends string, F extends AvOperationFamily, V extends string> = string extends R ? unknown : R extends AvResourceKey<AvContractApplicationView<M>> ? AvOperationArgumentsFor<AvContractApplicationView<M>, R, Extract<AvOperationIdentity, {
+    readonly family: F;
+    readonly variant: V;
+}>, AvApplicationScalarForms, AvApplicationScalarForms> : unknown;
+/**
+ * What a pipeline callback is told about the operation it is wrapping, and the
+ * framework's executor: `ctx.<Resource>.<family>.<variant>(args)`, `ctx.$sql` and
+ * `ctx.$transaction`. Every framework member is `$`-prefixed.
+ *
+ * A ctx call is raw and application-origin: it runs the Framework Validation
+ * Layer, field pipes, field validators and compute, and no developer stage
+ * (guards, pipes, hooks, interceptors, filters, field write guards, transaction
+ * stages), so a hook's call never re-enters the hook. It joins the current
+ * transaction when there is one, and resolves the operation's data or throws an
+ * `AvError`.
+ */
+export type AvContext<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = AvContextOperations<M> & AvContextFacts & {
+    /**
+     * The operation the stage wraps. For a nested write's target `resource` is the
+     * target, `family` the family its directive maps to, `variant` is `"one"` and
+     * `nested` is `true`.
+     */
+    readonly $operation: {
+        readonly resource: R;
+        readonly family: F;
+        readonly variant: V;
+        readonly nested?: true;
+    };
+    /**
+     * The arguments, deep-frozen: as the caller sent them in a guard, as the pipes
+     * returned them in a pipe, and the validated arguments the operation executes in
+     * an interceptor, a hook or a filter. Only a pipe changes them, by returning new
+     * ones; writing to them throws a `TypeError`. At a variant, typed as that
+     * operation's arguments ({@link AvStageArguments}), deep read-only; above it,
+     * `unknown`.
+     */
+    readonly $args: AvDeepReadonly<A>;
+    readonly $sql: AvContextSql;
+    /**
+     * Runs `work` in a transaction, `tx` being this ctx bound to it, and resolves
+     * what `work` resolved; a throw rolls it back. Inside an open transaction it
+     * opens nothing and joins it.
+     */
+    $transaction<T>(work: (tx: AvContext<M, R, F, V, A>) => Promise<T>): Promise<T>;
 };
 /** Allows or denies an operation; returning `false` answers `A4001`. */
-export type Guard<M extends AdapterModel = AdapterModel> = {
-    guard(context: PipelineContext<M>): boolean | undefined | Promise<boolean | undefined>;
+export type AvGuard<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+    guard(context: AvContext<M, R, F, V, A>): boolean | undefined | Promise<boolean | undefined>;
 }["guard"];
 /**
- * Transforms the arguments before the operation runs; returning `undefined`
- * keeps them as they are.
+ * Transforms the arguments before the validators judge them: the only stage
+ * that changes them. `args` is deep-frozen, so a pipe returns new arguments;
+ * returning `undefined` keeps them as they are. At a variant, `args` and the
+ * return are typed as that operation's arguments ({@link AvStageArguments}),
+ * `args` deep read-only.
  */
-export type Pipe<M extends AdapterModel = AdapterModel> = {
-    pipe(args: unknown, context: PipelineContext<M>): unknown | Promise<unknown>;
+export type AvPipe<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+    pipe(args: PipeArguments<A>, context: AvContext<M, R, F, V, A>): PipeResult<PipeArguments<A>>;
 }["pipe"];
-/** Runs just before the operation executes. */
-export type BeforeHook<M extends AdapterModel = AdapterModel> = {
-    before(context: PipelineContext<M>): void | Promise<void>;
+/**
+ * A variant pipe's arguments and return: the operation's arguments, deep
+ * read-only, each member closed to inference.
+ */
+type PipeArguments<T> = T extends AvDeepReadonlyLeaf | AvTransactionReference ? T : T extends object ? {
+    readonly [K in keyof T]: NoInfer<PipeArguments<Exclude<T[K], undefined>>>;
+} : T;
+/** What a pipe returns: arguments of type `A`, or `undefined` to keep them. */
+type PipeResult<A> = unknown extends A ? any : // biome-ignore lint/suspicious/noConfusingVoidType: a pipe written as `() => void sideEffect()` keeps the arguments, as `undefined` does
+A | undefined | void | Promise<A | undefined | void>;
+/** Runs just before the operation executes, inside every interceptor; `ctx.$args` is deep-frozen. */
+export type AvBeforeHook<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+    before(context: AvContext<M, R, F, V, A>): void | Promise<void>;
 }["before"];
-/** Runs after the operation succeeds, with its result. */
-export type AfterHook<M extends AdapterModel = AdapterModel> = {
-    after(result: unknown, context: PipelineContext<M>): void | Promise<void>;
+/**
+ * Runs after the operation succeeds, with its result, deep-frozen; an
+ * interceptor may still answer a different one.
+ */
+export type AvAfterHook<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+    after(result: unknown, context: AvContext<M, R, F, V, A>): void | Promise<void>;
 }["after"];
 /** Wraps the operation's execution; call `next()` to run it and get its result. */
-export type Interceptor<M extends AdapterModel = AdapterModel> = {
-    intercept(context: PipelineContext<M>, next: () => Promise<unknown>): Promise<unknown>;
+export type AvInterceptor<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+    intercept(context: AvContext<M, R, F, V, A>, next: () => Promise<unknown>): Promise<unknown>;
 }["intercept"];
 /**
- * Turns a thrown error into a {@link FrameworkError} to answer with; returning
+ * Turns a thrown error into a {@link AvError} to answer with; returning
  * `undefined` passes the error on.
  */
-export type Filter<M extends AdapterModel = AdapterModel> = {
-    filter(error: unknown, context: PipelineContext<M>): FrameworkError | undefined | Promise<FrameworkError | undefined>;
+export type AvFilter<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+    filter(error: unknown, context: AvContext<M, R, F, V, A>): AvError | undefined | Promise<AvError | undefined>;
+}["filter"];
+/**
+ * A pure transform of the value the caller sent for one scalar field: value in,
+ * value out, no context. Returning `undefined` keeps the value.
+ */
+export type AvFieldPipe = (value: unknown) => unknown | Promise<unknown>;
+/**
+ * Write-only admission for one field: refuses the operation when the caller sends
+ * the field. Returning `false` answers `A4001`.
+ */
+export type AvFieldGuard<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>> = {
+    guard(value: unknown, context: AvContext<M, R, "create" | "update" | "upsert">): boolean | undefined | Promise<boolean | undefined>;
+}["guard"];
+/**
+ * One plan step as a transaction stage reads it: an operation step with its
+ * `$ref`s unresolved, or a SQL step, which names no Resource.
+ */
+export type AvTransactionStep<M extends AvAdapterModel = AvAdapterModel> = {
+    readonly resource: AvConfigResourceKey<M>;
+    readonly family: AvOperationFamily;
+    readonly variant: string;
+    readonly args: unknown;
+    readonly sql?: never;
+} | {
+    readonly sql: {
+        readonly strings: readonly string[] | undefined;
+        readonly values: readonly unknown[];
+    };
+    readonly resource?: never;
+    readonly family?: never;
+    readonly variant?: never;
+    readonly args?: never;
+};
+/**
+ * What a Resource's transaction stage is told: the plan, not one operation
+ * (`$operation` is absent), and the executor, bound to the transaction.
+ */
+export type AvTransactionContext<M extends AvAdapterModel = AvAdapterModel> = AvContextOperations<M> & AvContextFacts & {
+    /** The plan, in step order, `$ref`s unresolved, deep-frozen. */
+    readonly $args: readonly AvTransactionStep<M>[];
+    readonly $sql: AvContextSql;
+    /** Runs `work` inside this transaction (it opens nothing): `tx` is this ctx. */
+    $transaction<T>(work: (tx: AvTransactionContext<M>) => Promise<T>): Promise<T>;
+};
+/** Allows or denies a whole transaction; returning `false` answers `A4001`. */
+export type AvTransactionGuard<M extends AvAdapterModel = AvAdapterModel> = {
+    guard(context: AvTransactionContext<M>): boolean | undefined | Promise<boolean | undefined>;
+}["guard"];
+/**
+ * Transforms the plan before any step runs; returning `undefined` keeps it. The
+ * plan it is given is deep-frozen, so it returns a new one. A
+ * returned plan keeps its steps (the same number, each on the same operation,
+ * each SQL step as it was); only an operation step's `args` may change.
+ */
+export type AvTransactionPipe<M extends AvAdapterModel = AvAdapterModel> = {
+    pipe(plan: readonly AvTransactionStep<M>[], context: AvTransactionContext<M>): readonly AvTransactionStep[] | undefined | Promise<readonly AvTransactionStep[] | undefined>;
+}["pipe"];
+/** Runs inside the transaction before its steps. */
+export type AvTransactionBeforeHook<M extends AvAdapterModel = AvAdapterModel> = {
+    before(context: AvTransactionContext<M>): void | Promise<void>;
+}["before"];
+/** Runs inside the transaction after its steps, with every step's result, deep-frozen. */
+export type AvTransactionAfterHook<M extends AvAdapterModel = AvAdapterModel> = {
+    after(results: unknown, context: AvTransactionContext<M>): void | Promise<void>;
+}["after"];
+/** Wraps the transaction's steps; call `next()` to run them. */
+export type AvTransactionInterceptor<M extends AvAdapterModel = AvAdapterModel> = {
+    intercept(context: AvTransactionContext<M>, next: () => Promise<unknown>): Promise<unknown>;
+}["intercept"];
+/** Turns an error thrown inside the transaction into a {@link AvError}. */
+export type AvTransactionFilter<M extends AvAdapterModel = AvAdapterModel> = {
+    filter(error: unknown, context: AvTransactionContext<M>): AvError | undefined | Promise<AvError | undefined>;
 }["filter"];
+export {};

package/dist/runtime/readonly-value.d.ts

@@ -0,0 +1,32 @@
+import { AvDecimal } from "./decimal.js";
+/** A value `AvDeepReadonly` leaves as it is: a primitive, a function, or a scalar instance. */
+export type AvDeepReadonlyLeaf = string | number | boolean | bigint | symbol | null | undefined | Date | Uint8Array | AvDecimal | ((...args: never[]) => unknown);
+/**
+ * `T` with every property, element and nested property read-only: what a stage
+ * that only reads is told. Arrays become read-only arrays; a `Date`, a
+ * `Uint8Array`, an `AvDecimal` and functions are left as they are.
+ */
+export type AvDeepReadonly<T> = T extends AvDeepReadonlyLeaf ? T : T extends object ? {
+    readonly [K in keyof T]: AvDeepReadonly<T[K]>;
+} : T;
+/**
+ * Freezes `value` in place, every nested plain object and array included, and
+ * returns it. Accessor properties are not read. For data the framework owns: the
+ * copy taken at the door, a body parsed for this request alone, a pipe's output.
+ */
+export declare function deepFreeze<T>(value: T): T;
+/**
+ * A deep-frozen copy of `value`'s plain objects and arrays, every `Date` and
+ * `Uint8Array` in it copied too, the original left as it is: what a stage that
+ * only reads is told — the validated arguments after validation, a result in an
+ * after hook — so neither what is written nor the result the caller receives can
+ * be changed through it.
+ */
+export declare function frozenCopy<T>(value: T): AvDeepReadonly<T>;
+/**
+ * A read-only view of `value`: reads see the live value, nested plain objects
+ * and arrays as views too, and any write, definition or deletion throws a
+ * `TypeError` naming `subject` (one subject per value: the first view's). The
+ * value itself stays writable for its owner.
+ */
+export declare function readonlyView<T>(value: T, subject: string): AvDeepReadonly<T>;

package/dist/runtime/readonly-value.js

@@ -0,0 +1,141 @@
+import { AvDecimal } from "./decimal.js";
+function isContainer(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return true;
+    }
+    if (value instanceof AvDecimal) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const DEEP_FROZEN = new WeakSet();
+export function deepFreeze(value) {
+    if (!isContainer(value) || DEEP_FROZEN.has(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    DEEP_FROZEN.add(value);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor !== undefined && "value" in descriptor) {
+            deepFreeze(descriptor.value);
+        }
+    }
+    return value;
+}
+function scalarCopy(value) {
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+    if (value instanceof Uint8Array) {
+        return value.slice();
+    }
+    return undefined;
+}
+export function frozenCopy(value) {
+    const copies = new Map();
+    const copy = (current) => {
+        const scalar = scalarCopy(current);
+        if (scalar !== undefined) {
+            return scalar;
+        }
+        if (!isContainer(current)) {
+            return current;
+        }
+        if (copies.has(current)) {
+            return copies.get(current);
+        }
+        copies.set(current, current);
+        const entries = [];
+        let changed = !DEEP_FROZEN.has(current);
+        for (const key of Reflect.ownKeys(current)) {
+            const descriptor = Object.getOwnPropertyDescriptor(current, key);
+            if (descriptor === undefined ||
+                !("value" in descriptor) ||
+                (Array.isArray(current) && key === "length")) {
+                continue;
+            }
+            const next = copy(descriptor.value);
+            changed ||= next !== descriptor.value;
+            entries.push([key, descriptor, next]);
+        }
+        if (!changed) {
+            copies.set(current, current);
+            return current;
+        }
+        const target = Array.isArray(current)
+            ? new Array(current.length)
+            : Object.create(Object.getPrototypeOf(current));
+        for (const [key, descriptor, next] of entries) {
+            Object.defineProperty(target, key, {
+                value: next,
+                enumerable: descriptor.enumerable ?? false,
+                writable: true,
+                configurable: true,
+            });
+        }
+        const frozen = deepFreeze(target);
+        copies.set(current, frozen);
+        return frozen;
+    };
+    return copy(value);
+}
+function readOnlyWrite(subject) {
+    return new TypeError(`${subject} is read-only here.`);
+}
+const VIEWS = new WeakMap();
+export function readonlyView(value, subject) {
+    if (!isContainer(value)) {
+        return value;
+    }
+    const known = VIEWS.get(value);
+    if (known !== undefined) {
+        return known;
+    }
+    const real = value;
+    const standIn = Array.isArray(value)
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    const refuse = () => {
+        throw readOnlyWrite(subject);
+    };
+    const view = new Proxy(standIn, {
+        get: (_target, key) => readonlyView(real[key], subject),
+        has: (_target, key) => key in real,
+        ownKeys: () => Reflect.ownKeys(real),
+        getOwnPropertyDescriptor: (target, key) => {
+            const descriptor = Reflect.getOwnPropertyDescriptor(real, key);
+            if (descriptor === undefined) {
+                return undefined;
+            }
+            if (Reflect.getOwnPropertyDescriptor(target, key)?.configurable === false) {
+                return {
+                    value: descriptor.value,
+                    enumerable: false,
+                    writable: true,
+                    configurable: false,
+                };
+            }
+            return "value" in descriptor
+                ? {
+                    value: readonlyView(descriptor.value, subject),
+                    enumerable: descriptor.enumerable ?? false,
+                    writable: false,
+                    configurable: true,
+                }
+                : { ...descriptor, configurable: true };
+        },
+        getPrototypeOf: () => Object.getPrototypeOf(real),
+        set: refuse,
+        defineProperty: refuse,
+        deleteProperty: refuse,
+        setPrototypeOf: refuse,
+        preventExtensions: refuse,
+    });
+    VIEWS.set(value, view);
+    return view;
+}

package/dist/runtime/request-envelope.validator.d.ts

@@ -1,5 +1,5 @@
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 /** The issues of one malformed operation request envelope; empty when well formed. */
-export declare function validateOperationEnvelope(request: unknown): readonly ValidationIssue[];
+export declare function validateOperationEnvelope(request: unknown): readonly AvValidationIssue[];
 /** The issues of one malformed transaction request envelope; empty when well formed. */
-export declare function validateTransactionEnvelope(request: unknown): readonly ValidationIssue[];
+export declare function validateTransactionEnvelope(request: unknown): readonly AvValidationIssue[];