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

package/dist/runtime/outcome-mapper.js

@@ -21,18 +21,26 @@ function outcomeRule(operation) {
     const table = OUTCOME_TABLE;
     return table[`${operation.family}.${operation.variant}`];
 }
+function notFound() {
+    return operationFailure("A2003", {
+        message: "No record matched the unique selector.",
+    });
+}
 function absenceOutcome(absence) {
     switch (absence) {
         case "no-match":
             return operationNoMatch();
         case "not-found":
-            return operationFailure("A2003", {
-                message: "No record matched the unique selector.",
-            });
+            return notFound();
         case undefined:
             return internalFailure();
     }
 }
+export function uniqueMissFailure(operation, data) {
+    return data === null && outcomeRule(operation)?.absence === "not-found"
+        ? notFound()
+        : undefined;
+}
 export function mapOperationOutcome(operation, data) {
     const rule = outcomeRule(operation);
     if (rule === undefined) {
@@ -52,6 +60,13 @@ function namesUnavailableOperation(issue) {
     const head = stepRelativeHead(issue);
     return issue.code === "V1006" && (head === "family" || head === "variant");
 }
+export const VALIDATION_OUTCOME_MESSAGES = {
+    A2001: "The requested Resource is not available.",
+    A2002: "The requested operation is not available on this Resource.",
+    A2004: "Operation arguments failed framework validation.",
+    A2007: "Operation arguments failed framework validation.",
+    A2009: "Operation arguments failed framework validation.",
+};
 function validationCode(issues) {
     if (issues.some((issue) => issue.code !== "V1019" && stepRelativeHead(issue) === "resource")) {
         return "A2001";
@@ -68,14 +83,16 @@ function validationCode(issues) {
     }
     if (issues.some((issue) => issue.code === "V1013" ||
         issue.code === "V1014" ||
-        issue.code === "V1015")) {
+        issue.code === "V1015" ||
+        issue.code === "V1021")) {
         return "A2009";
     }
     return "A2004";
 }
 export function mapValidationOutcome(issues) {
-    return operationFailure(validationCode(issues), {
-        message: "Operation arguments failed framework validation.",
+    const code = validationCode(issues);
+    return operationFailure(code, {
+        message: VALIDATION_OUTCOME_MESSAGES[code],
         issues,
     });
 }

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,21 @@
-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 { AvCallerDataError } from "./caller-data.copier.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>;
+    /**
+     * Runs `request` uncopied; with `refused`, its arguments are a host's parsed body
+     * whose copy at the call failed, answered as the door answers that failure.
+     */
+    readonly execute: (request: RemoteOperationRequest, refused?: AvCallerDataError) => Promise<AvOperationResponse>;
+    /**
+     * Runs `request` uncopied; with `refused`, its plan is a host's parsed plan taken
+     * at the call, and these steps' arguments could not be copied there: each is
+     * answered at its turn as the door answers that failure.
+     */
+    readonly executeTransaction: (request: ClientTransactionRequest | AgentTransactionRequest, refused?: ReadonlyMap<number, AvCallerDataError>) => 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,61 @@ 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 Contract a stage's output is held to: Core's Resources plus what `active` adds. */
+export declare function serverContractFor(core: AvContractCore, active: AvContract): AvContract;
 /** 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;
+/**
+ * The `A3004` for a stage output the server's rules raised `issues` against
+ * (paths under `["arguments", …]`), the first named in the diagnostic;
+ * `undefined` when there are none.
+ */
+export declare function refusedStageOutput(request: AvOperationIdentity & {
+    readonly resource: string;
+}, issues: readonly AvValidationIssue[], subject: string): RefusedStageOutput | undefined;

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

@@ -19,7 +19,7 @@ function serverContract(core, active) {
     return { ...core, resources };
 }
 const SERVER_VIEWS = new WeakMap();
-function serverContractFor(core, active) {
+export function serverContractFor(core, active) {
     let view = SERVER_VIEWS.get(active);
     if (view === undefined) {
         view = serverContract(core, active);
@@ -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,30 @@ 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) {
+    return refusedStageOutput(request, serverIssues(serverContractFor(contracts.core, contracts.active), request, args, options), subject);
+}
+export function refusedStageOutput(request, issues, subject) {
     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,243 @@
-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 { AvPreComputeLift } from "../config/computed-fields.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, RequirementsLessComputed } 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 { ArrayForm, 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> = StageArgumentsOf<AvContractApplicationView<M>, R, F, V>;
+/** The arguments of operation `F`.`V` on `R` under the Contract view `C`. */
+type StageArgumentsOf<C extends AvContract, R extends string, F extends AvOperationFamily, V extends string> = string extends R ? unknown : R extends AvResourceKey<C> ? AvOperationArgumentsFor<C, R, Extract<AvOperationIdentity, {
+    readonly family: F;
+    readonly variant: V;
+}>, AvApplicationScalarForms, AvApplicationScalarForms> : unknown;
+/**
+ * The arguments a variant's guards, pipes and filters are told: the operation's
+ * arguments before write compute has run, so a create need not hold a field
+ * `compute.create` fills (`Lift`, as `"<Resource>.<field>"`; `string`: any).
+ */
+export type AvPreComputeStageArguments<M extends AvAdapterModel, R extends string, F extends AvOperationFamily, V extends string, Lift extends string = AvPreComputeLift<M, "root">> = F extends "find" | "delete" ? AvStageArguments<M, R, F, V> : [Lift] extends [never] ? AvStageArguments<M, R, F, V> : StageArgumentsOf<PreComputeView<AvContractApplicationView<M>, Lift>, R, F, V>;
+/** A Contract view with the create requirements `Lift` names lifted. */
+type PreComputeView<C, Lift extends string> = Extract<{
+    readonly [P in keyof C]: P extends "resources" ? string extends Lift ? {
+        readonly [R in keyof C[P]]: Omit<C[P][R], "createRequirements">;
+    } : {
+        readonly [R in keyof C[P]]: LiftedResource<C[P][R], LiftedFieldOf<Lift, R>>;
+    } : C[P];
+}, AvContract>;
+/** The fields of Resource `R` that `Lift` names. */
+type LiftedFieldOf<Lift extends string, R> = Lift extends `${R & string}.${infer Field}` ? Field : never;
+/** One Resource with the create requirements on `Fields` lifted; itself when none. */
+type LiftedResource<Resource, Fields> = [Fields] extends [never] ? Resource : {
+    readonly [P in keyof Resource]: P extends "createRequirements" ? RequirementsLessComputed<Exclude<Resource[P], undefined>, Fields> : Resource[P];
+};
+/**
+ * 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; in a guard or
+     * a filter a create may lack the fields `compute.create` fills ({@link
+     * AvPreComputeStageArguments}: write compute has not run); 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 before write compute runs
+ * ({@link AvPreComputeStageArguments}: a create may lack the fields
+ * `compute.create` fills), `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 readonly unknown[] ? ArrayForm<T> extends "array" ? readonly NoInfer<PipeArguments<Exclude<T[number], undefined>>>[] : {
+    readonly [K in keyof T]: NoInfer<PipeArguments<Exclude<T[K], undefined>>>;
+} : 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,43 @@
+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);
+/**
+ * Whether array type `T` is an open array (every length: `"array"`) or a tuple
+ * (`"tuple"`). A tuple whose only fixed positions are optional ones before a rest
+ * element (`[a?, ...b[]]`) has every length too and reads as an array.
+ */
+export type ArrayForm<T extends readonly unknown[]> = T extends readonly [] | readonly [unknown, ...unknown[]] | readonly [...unknown[], unknown] ? "tuple" : T extends {
+    readonly length: infer Length;
+} ? number extends Length ? "array" : "tuple" : "tuple";
+/**
+ * `T` with every property, element and nested property read-only: what a stage
+ * that only reads is told. Arrays become read-only arrays, tuples read-only
+ * tuples; a `Date`, a `Uint8Array`, an `AvDecimal` and functions are left as
+ * they are.
+ */
+export type AvDeepReadonly<T> = T extends AvDeepReadonlyLeaf ? T : T extends readonly unknown[] ? ArrayForm<T> extends "array" ? readonly AvDeepReadonly<T[number]>[] : {
+    readonly [K in keyof T]: AvDeepReadonly<T[K]>;
+} : 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>;