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

package/dist/runtime/create-requirement.d.ts

@@ -1,101 +1,30 @@
-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 { ReferentialActionTable } from "./referential-action.js";
-/**
- * Core's create-requirement vocabulary, and the check that reads it.
- *
- * **The facts are an Adapter's.** Which values a store cannot create a row
- * without is a property of the store's schema — a column with no default, a
- * reference that must point somewhere — and only the Adapter can read it. The
- * words are Aventara's, so an Adapter translates its provider's facts into them,
- * and the reasoning over them is core's, so no Adapter re-implements it.
- *
- * None of this enters a Contract. A Contract carries no foreign-key detail and
- * no knowledge of which relation is the other end of which, and a requirement
- * needs both; it is a server-side fact, read once when the Framework is
- * constructed, like the referential actions.
- *
- * **When the check runs.** After guards, pipes and computed write behaviours —
- * the moment the arguments are what the Adapter will be handed — and before
- * any `before` hook or Adapter work. Earlier would refuse a value a pipe or a
- * computed behaviour was about to supply; later is the store's own refusal,
- * which reaches the caller as an internal failure. A missing value is the
- * caller's to fix, so it answers `A2004` with a `V1000` issue at the path where
- * the value belongs.
- *
- * **One value, two spellings.** A relation that holds a reference has scalar
- * fields that hold it too — the Adapter states which, on the relation's
- * referential edge (`ReferentialEdge.references`), for every such relation,
- * required or optional. A write that sets both — `authorId` and
- * `author: { $connect: … }` in one record, at create or update — names the
- * reference twice. No store can honour both, and which one the caller meant is
- * not the framework's to guess, so it is the caller's `A2004` too: a `V1012`
- * issue at the relation, in every record the check walks, before any Adapter
- * work. The same edge is what a required relation may instead be written
- * through, so the pairing has one source.
- *
- * **One store, one spelling per record.** A store may take a record's
- * references only one way at a time — every relation that holds one written as
- * a relation, or every one through its fields — and state it as the Contract's
- * `referenceWrites: "uniform"`. Under it, a record that writes a relation
- * holding a reference beside another relation's reference field is the caller's
- * `A2004` as well: a `V1012` issue at the relation write.
- */
-/** A relation edge, named by the Resource that holds it and its field there. */
-export type CreateRequirementEdge = {
-    readonly resource: string;
-    readonly relation: string;
-};
-/**
- * One value a create of a Resource cannot do without.
- *
- * - `field` — a scalar with no default, generated value or other source: it
- *   must be written.
- * - `relation` — a required to-one relation: it must be written (connected or
- *   created), or every field that holds its reference must be — the
- *   `references` of the relation's referential edge, less any the store fills
- *   itself (`DEFAULTED` or `GENERATED_ON_CREATE`). When the row is created
- *   **through** the relation's other end (`inverse`), the parent supplies it,
- *   and it is not required.
- */
-export type CreateRequirement = {
-    readonly kind: "field";
-    readonly field: string;
-} | {
-    readonly kind: "relation";
-    readonly relation: string;
-    readonly inverse?: CreateRequirementEdge;
-};
-/**
- * Every Resource's create requirements, keyed by Resource. A Resource that is
- * absent, or carries an empty list, requires nothing core can check.
- */
-export type CreateRequirementTable = Readonly<Record<string, readonly CreateRequirement[]>>;
 type Path = readonly (string | number)[];
 /**
- * What the Adapter stated that the check reads: its create requirements, and
- * its referential edges for the fields that hold each reference. Read once when
- * the Framework is constructed.
+ * What the Adapter stated beside its model that the check reads: its
+ * referential edges, for the fields that hold each reference. Read once when
+ * the Framework is constructed. The requirements themselves are the active
+ * Contract's.
  */
 export type RecordWriteFacts = {
-    readonly requirements: CreateRequirementTable;
     readonly references: ReferentialActionTable;
 };
 /** The facts an Adapter stated, read off it once; an absent table states nothing. */
 export declare function recordWriteFactsOf(adapter: {
-    readonly createRequirements?: CreateRequirementTable;
     readonly referentialActions?: ReferentialActionTable;
 }): RecordWriteFacts;
 /**
  * The `V1000` issues for every create position in one operation's arguments
- * that lacks a value the Adapter requires — `create.*`'s `data`, `upsert`'s
+ * that lacks a value the active Contract requires — `create.*`'s `data`, `upsert`'s
  * `create`, and every nested create under any write — and the `V1012` issues
  * for every write record, create or update, that sets a relation and its
  * reference both, in argument order. Empty when there are none. Total over
  * malformed input.
  */
-export declare function createRequirementIssues(contract: Contract, facts: RecordWriteFacts, request: OperationIdentity & {
+export declare function createRequirementIssues(contract: AvContract, facts: RecordWriteFacts, request: AvOperationIdentity & {
     readonly resource: string;
-}, args: unknown, argumentsPath: Path): readonly ValidationIssue[];
+}, args: unknown, argumentsPath: Path): readonly AvValidationIssue[];
 export {};

package/dist/runtime/create-requirement.js

@@ -8,10 +8,6 @@ function isRecord(value) {
 function written(record, key) {
     return Object.hasOwn(record, key) && record[key] !== undefined;
 }
-function requirementsOf(table, resource) {
-    const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
-    return Array.isArray(listed) ? listed : [];
-}
 function edgesOf(table, resource) {
     const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
     return Array.isArray(listed) ? listed : [];
@@ -19,16 +15,6 @@ function edgesOf(table, resource) {
 function referencesOf(edge) {
     return Array.isArray(edge.references) ? edge.references : [];
 }
-function referenceFieldsOf(table, resource, relation) {
-    const edge = edgesOf(table, resource).find((candidate) => candidate.field === relation);
-    return edge === undefined ? [] : referencesOf(edge);
-}
-function storeSupplied(contract, resource, field) {
-    const found = lookupField(lookupResource(contract, resource), field);
-    return (found?.kind === "scalar" &&
-        (found.lifecycle.includes("DEFAULTED") ||
-            found.lifecycle.includes("GENERATED_ON_CREATE")));
-}
 function creatableScalar(contract, resource, field) {
     const found = lookupField(lookupResource(contract, resource), field);
     return found?.kind === "scalar" && found.capabilities.create !== undefined;
@@ -38,6 +24,41 @@ function creatableRelation(contract, resource, relation, scope) {
     return (found?.kind === "relation" &&
         advertisedDirectivesAt(found.capabilities.create, scope) !== undefined);
 }
+function blockedByPosition(contract, resource, relation, scope) {
+    return (scope !== NESTED_WRITE_SCOPE &&
+        creatableRelation(contract, resource, relation, NESTED_WRITE_SCOPE) &&
+        !creatableRelation(contract, resource, relation, scope));
+}
+function requirementsOf(contract, resource) {
+    const found = lookupResource(contract, resource)?.createRequirements;
+    return isRecord(found) ? found : undefined;
+}
+function namesOf(value) {
+    return Array.isArray(value)
+        ? value.filter((name) => typeof name === "string")
+        : [];
+}
+function suppliedThrough(requirements, via) {
+    if (via === undefined || !isRecord(requirements.parentSupplies)) {
+        return new Set();
+    }
+    const byRelation = Object.hasOwn(requirements.parentSupplies, via.resource)
+        ? requirements.parentSupplies[via.resource]
+        : undefined;
+    if (!isRecord(byRelation) || !Object.hasOwn(byRelation, via.relation)) {
+        return new Set();
+    }
+    return new Set(namesOf(byRelation[via.relation]));
+}
+function missingIssue(path, resource, field, relation, or = []) {
+    return {
+        code: "V1000",
+        path: [...path, field],
+        message: relation
+            ? `Relation "${field}" is required to create ${resource}${or.length > 0 ? `: write it, or ${or.map((name) => `"${name}"`).join(" and ")}` : ""}.`
+            : `Field "${field}" is required to create ${resource}.`,
+    };
+}
 function checkCreateRecord(context, resource, record, path, scope, via) {
     if (!isRecord(record)) {
         return;
@@ -45,46 +66,52 @@ function checkCreateRecord(context, resource, record, path, scope, via) {
     const { contract, issues } = context;
     const conflicted = referenceConflicts(context, resource, record, path);
     mixedReferenceWrites(context, resource, record, path, conflicted);
-    for (const requirement of requirementsOf(context.requirements, resource)) {
-        if (requirement.kind === "field") {
-            if (!written(record, requirement.field) &&
-                creatableScalar(contract, resource, requirement.field)) {
-                issues.push({
-                    code: "V1000",
-                    path: [...path, requirement.field],
-                    message: `Field "${requirement.field}" is required to create ${resource}.`,
-                });
+    const requirements = requirementsOf(contract, resource);
+    if (requirements !== undefined) {
+        const supplied = suppliedThrough(requirements, via);
+        for (const field of namesOf(requirements.required)) {
+            if (supplied.has(field) || written(record, field)) {
+                continue;
+            }
+            if (creatableScalar(contract, resource, field)) {
+                issues.push(missingIssue(path, resource, field, false));
+            }
+            else if (!conflicted.has(field) &&
+                creatableRelation(contract, resource, field, scope)) {
+                issues.push(missingIssue(path, resource, field, true));
+            }
+            else if (blockedByPosition(contract, resource, field, scope)) {
+                const edge = edgesOf(context.references, resource).find((candidate) => candidate.field === field);
+                const references = edge === undefined ? [] : referencesOf(edge);
+                if (!references.some((name) => written(record, name))) {
+                    issues.push(missingIssue(path, resource, references[0] ?? field, false));
+                }
             }
-            continue;
-        }
-        if (conflicted.has(requirement.relation)) {
-            continue;
-        }
-        if (via !== undefined &&
-            requirement.inverse?.resource === via.resource &&
-            requirement.inverse.relation === via.relation) {
-            continue;
-        }
-        const orFields = referenceFieldsOf(context.references, resource, requirement.relation).filter((field) => !storeSupplied(contract, resource, field));
-        if (written(record, requirement.relation) ||
-            (orFields.length > 0 && orFields.every((field) => written(record, field)))) {
-            continue;
-        }
-        if (creatableRelation(contract, resource, requirement.relation, scope)) {
-            issues.push({
-                code: "V1000",
-                path: [...path, requirement.relation],
-                message: `Relation "${requirement.relation}" is required to create ${resource}${orFields.length > 0 ? `: write it, or ${orFields.map((field) => `"${field}"`).join(" and ")}` : ""}.`,
-            });
-            continue;
         }
-        const missing = orFields.find((field) => !written(record, field) && creatableScalar(contract, resource, field));
-        if (missing !== undefined) {
-            issues.push({
-                code: "V1000",
-                path: [...path, missing],
-                message: `Field "${missing}" is required to create ${resource}.`,
-            });
+        const groups = Array.isArray(requirements.oneOf) ? requirements.oneOf : [];
+        for (const group of groups) {
+            const [relation, ...references] = namesOf(group);
+            if (relation === undefined ||
+                references.length === 0 ||
+                conflicted.has(relation) ||
+                supplied.has(relation) ||
+                references.some((field) => supplied.has(field)) ||
+                written(record, relation) ||
+                references.every((field) => written(record, field))) {
+                continue;
+            }
+            if (creatableRelation(contract, resource, relation, scope)) {
+                issues.push(missingIssue(path, resource, relation, true, references));
+                continue;
+            }
+            const missing = references.find((field) => !written(record, field) &&
+                creatableScalar(contract, resource, field)) ??
+                (blockedByPosition(contract, resource, relation, scope)
+                    ? references.find((field) => !written(record, field))
+                    : undefined);
+            if (missing !== undefined) {
+                issues.push(missingIssue(path, resource, missing, false));
+            }
         }
     }
     walkNestedCreates(context, resource, record, path);
@@ -177,10 +204,7 @@ function walkNestedCreates(context, resource, record, path) {
     }
 }
 export function recordWriteFactsOf(adapter) {
-    return {
-        requirements: adapter.createRequirements ?? {},
-        references: adapter.referentialActions ?? {},
-    };
+    return { references: adapter.referentialActions ?? {} };
 }
 export function createRequirementIssues(contract, facts, request, args, argumentsPath) {
     if (!isRecord(args)) {
@@ -188,7 +212,6 @@ export function createRequirementIssues(contract, facts, request, args, argument
     }
     const context = {
         contract,
-        requirements: facts.requirements,
         references: facts.references,
         issues: [],
     };

package/dist/runtime/decimal.d.ts

@@ -1,8 +1,8 @@
 /**
  * An exact decimal value, independent of any database driver's decimal class.
- * Results carry `decimal` fields as `Decimal`.
+ * Results carry `decimal` fields as `AvDecimal`.
  */
-export declare class Decimal {
+export declare class AvDecimal {
     #private;
     constructor(value: string);
     toString(): string;

package/dist/runtime/decimal.js

@@ -1,5 +1,5 @@
 import { WIRE_SCALAR_PATTERNS } from "../contracts/wire-scalar-format.js";
-export class Decimal {
+export class AvDecimal {
     #value;
     constructor(value) {
         if (typeof value !== "string") {

package/dist/runtime/diagnostics-reporter.d.ts

@@ -1,27 +1,27 @@
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { OperationFamily } from "../operations/operation-identity.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
 import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
 import type { FrameworkOperationRequest } from "./operation-request.js";
-import type { OperationErrorCode } from "./operation-response.js";
+import { type AvOperationErrorCode, type AvOperationFailureResponse } from "./operation-response.js";
 /**
  * One unplanned failure of an operation: the raw error, the code the caller
- * received, and the operation and request it happened in — or a developer's
- * deliberate internal failure, marked `deliberate`. Server-side only:
+ * received, and the operation and request it happened in. It can also be a
+ * developer's deliberate internal failure, marked `deliberate`. Server-side only:
  * diagnostics are never sent to the caller.
  */
-export type OperationDiagnostic = {
+export type AvOperationDiagnostic = {
     readonly kind: "operation";
     readonly error: unknown;
-    readonly code: OperationErrorCode;
-    readonly origin: RequestOrigin;
+    readonly code: AvOperationErrorCode;
+    readonly origin: AvRequestOrigin;
     readonly resource: string;
-    readonly family: OperationFamily;
+    readonly family: AvOperationFamily;
     readonly variant: string;
     readonly requestId: string;
     readonly operation?: number;
     /**
-     * `true` when `error` is a `FrameworkError` its thrower — a pipeline
-     * callback, a behavior, a filter or an Adapter — raised deliberately with an
+     * `true` when `error` is an `AvError` its thrower (a pipeline
+     * callback, a compute stage, a filter or an Adapter) raised deliberately with an
      * internal (`A3xxx`) code: the developer's own failure, whose message and
      * issues the caller never receives. Absent for a failure the framework did not
      * expect.
@@ -32,48 +32,74 @@ export type OperationDiagnostic = {
  * One unplanned failure of a transaction: the raw error, the code the caller
  * received, and the step it is blamed on (`operation`) when there is one.
  */
-export type TransactionDiagnostic = {
+export type AvTransactionDiagnostic = {
     readonly kind: "transaction";
     readonly error: unknown;
-    readonly code: OperationErrorCode;
-    readonly origin: RequestOrigin;
+    readonly code: AvOperationErrorCode;
+    readonly origin: AvRequestOrigin;
     readonly requestId: string;
     readonly operation?: number;
     /**
      * Never present: only an operation diagnostic is marked `deliberate`. Declared
-     * so the mark can be read on any {@link FrameworkDiagnostic}.
+     * so the mark can be read on any {@link AvDiagnostic}.
      */
     readonly deliberate?: never;
 };
-/** One diagnostic: of an operation, or of a transaction as a whole. */
-export type FrameworkDiagnostic = OperationDiagnostic | TransactionDiagnostic;
+/**
+ * One unplanned failure of the MCP endpoint itself, outside any tool call's
+ * operation: the raw error, answered `500` with no detail.
+ */
+export type AvMcpDiagnostic = {
+    readonly kind: "mcp";
+    readonly error: unknown;
+    /** Always `A3000`: an internal failure, with nothing more specific to say. */
+    readonly code: "A3000";
+    readonly origin: "agent";
+    /** Minted for the report: the MCP request carries no Aventara request id. */
+    readonly requestId: string;
+    /** Never present: no operation of a plan is involved. */
+    readonly operation?: never;
+    /** Never present: only an operation diagnostic is marked `deliberate`. */
+    readonly deliberate?: never;
+};
+/** One diagnostic: of an operation, of a transaction as a whole, or of the MCP endpoint. */
+export type AvDiagnostic = AvOperationDiagnostic | AvTransactionDiagnostic | AvMcpDiagnostic;
 /**
  * Receives a diagnostic for every unplanned failure. Set once, as the root
  * configuration's `diagnostics`.
  */
-export type FrameworkDiagnosticsSink = (diagnostic: FrameworkDiagnostic) => void | Promise<void>;
+export type AvDiagnosticsSink = (diagnostic: AvDiagnostic) => void | Promise<void>;
 /**
  * The channel as the runtime holds it: bound to one request, told the raw
  * error and the code being emitted. Total by construction — it returns
  * before the sink has finished and swallows everything the sink does.
  */
-export type DiagnosticsReporter = (error: unknown, code: OperationErrorCode, marks?: DiagnosticMarks) => void;
+export type DiagnosticsReporter = (error: unknown, code: AvOperationErrorCode, marks?: DiagnosticMarks) => void;
 /** What a report states about its error beyond the code: today, whether it was deliberate. */
-export type DiagnosticMarks = Pick<OperationDiagnostic, "deliberate">;
+export type DiagnosticMarks = Pick<AvOperationDiagnostic, "deliberate">;
 /** The identifying half of a diagnostic, captured once per request. */
-type OperationDiagnosticIdentity = Omit<OperationDiagnostic, "error" | "code">;
-type TransactionDiagnosticIdentity = Omit<TransactionDiagnostic, "error" | "code">;
+type OperationDiagnosticIdentity = Omit<AvOperationDiagnostic, "error" | "code">;
+type TransactionDiagnosticIdentity = Omit<AvTransactionDiagnostic, "error" | "code">;
 /** The diagnostics channel bound to one diagnostic identity. */
-export declare function createReporter(sink: FrameworkDiagnosticsSink | undefined, identity: OperationDiagnosticIdentity | TransactionDiagnosticIdentity): DiagnosticsReporter;
+export declare function createReporter(sink: AvDiagnosticsSink | undefined, identity: OperationDiagnosticIdentity | TransactionDiagnosticIdentity): DiagnosticsReporter;
+/**
+ * The MCP endpoint's failure channel for `framework`: each call reports one
+ * {@link AvMcpDiagnostic} to its configured sink, under a minted request id, and
+ * answers the response the caller receives instead: the generic `A3000`, which
+ * carries nothing of the error. Total: it returns before the sink has finished
+ * and swallows everything the sink does. A Framework without a sink gets a
+ * channel that observes nothing and still answers the `A3000`.
+ */
+export declare function mcpFailureReporterOf(framework: object): (error: unknown) => AvOperationFailureResponse;
 /** Records the sink `framework` was configured with; called once, at construction. */
-export declare function recordDiagnosticsSink(framework: object, sink: FrameworkDiagnosticsSink | undefined): void;
+export declare function recordDiagnosticsSink(framework: object, sink: AvDiagnosticsSink | undefined): void;
 /** The sink `framework` was configured with, or `undefined` for none. */
-export declare function diagnosticsSinkOf(framework: object): FrameworkDiagnosticsSink | undefined;
+export declare function diagnosticsSinkOf(framework: object): AvDiagnosticsSink | undefined;
 /**
  * Binds the configured sink to one operation request. The sink is not awaited,
  * and nothing it throws or rejects with reaches the response.
  */
-export declare function createDiagnosticsReporter(sink: FrameworkDiagnosticsSink | undefined, request: FrameworkOperationRequest, operation?: number): DiagnosticsReporter;
+export declare function createDiagnosticsReporter(sink: AvDiagnosticsSink | undefined, request: FrameworkOperationRequest, operation?: number): DiagnosticsReporter;
 /** The diagnostics channel of one transaction request. */
 export type TransactionDiagnosticsChannel = {
     /** A plan-level report; `operation` attributes it to a recorded failing index. */
@@ -82,5 +108,5 @@ export type TransactionDiagnosticsChannel = {
     readonly operation: (request: FrameworkOperationRequest, operation: number) => DiagnosticsReporter;
 };
 /** Binds the configured sink to one transaction request and its plan operations. */
-export declare function createTransactionDiagnosticsChannel(sink: FrameworkDiagnosticsSink | undefined, request: FrameworkTransactionRequest): TransactionDiagnosticsChannel;
+export declare function createTransactionDiagnosticsChannel(sink: AvDiagnosticsSink | undefined, request: FrameworkTransactionRequest): TransactionDiagnosticsChannel;
 export {};

package/dist/runtime/diagnostics-reporter.js

@@ -1,3 +1,5 @@
+import { internalFailure, } from "./operation-response.js";
+import { requestIdOf } from "./request-id.js";
 const IGNORE_DIAGNOSTIC = () => undefined;
 function isThenable(value) {
     if ((typeof value !== "object" || value === null) &&
@@ -30,6 +32,28 @@ export function createReporter(sink, identity) {
     };
 }
 const CONFIGURED_SINKS = new WeakMap();
+export function mcpFailureReporterOf(framework) {
+    const sink = CONFIGURED_SINKS.get(framework);
+    return (error) => {
+        if (sink !== undefined) {
+            try {
+                const settled = sink({
+                    kind: "mcp",
+                    error,
+                    code: "A3000",
+                    origin: "agent",
+                    requestId: requestIdOf(undefined),
+                });
+                if (isThenable(settled)) {
+                    settled.then(undefined, () => undefined);
+                }
+            }
+            catch {
+            }
+        }
+        return internalFailure();
+    };
+}
 export function recordDiagnosticsSink(framework, sink) {
     if (sink !== undefined) {
         CONFIGURED_SINKS.set(framework, sink);

package/dist/runtime/error-boundary.d.ts

@@ -1,6 +1,7 @@
 import type { DiagnosticsReporter } from "./diagnostics-reporter.js";
-import type { OperationFailureResponse } from "./operation-response.js";
-import type { Filter, PipelineContext } from "./pipeline.js";
+import { AvError } from "./framework-error.js";
+import type { AvCause, AvOperationErrorCode, AvOperationFailureResponse } from "./operation-response.js";
+import type { AvContext } from "./pipeline.js";
 /** Where an unexpected post-validation exception originated. */
 export type FailureOrigin = "adapter" | "runtime";
 /** The one generic Adapter-failure text; every unexpected A3001 carries it. */
@@ -39,18 +40,74 @@ export type CallerArgumentsView = {
  * framework's text for its code and reported to the diagnostics channel.
  */
 export declare const MAX_DEVELOPER_ISSUE_MESSAGE_LENGTH = 1000;
+/** The stable outcome a thrower chose, once the boundary has vetted it. */
+type DeliberateOutcome = {
+    readonly code: AvOperationErrorCode;
+    readonly cause: AvCause;
+    /**
+     * Every issue code, issue path and developer issue message the boundary could
+     * not vouch for, raw and in supplied order.
+     */
+    readonly unvouched: readonly unknown[];
+};
 /**
  * Final framework sanitization, shared by every boundary. A deliberate
- * {@link FrameworkError} carries its own stable outcome; anything else is
+ * {@link AvError} carries its own stable outcome; anything else is
  * replaced by a generic cause so no provider text, stack, path, or secret
  * can cross the response boundary. Total: it never throws.
  */
-export declare function sanitizeOperationFailure(error: unknown, origin: FailureOrigin, report: DiagnosticsReporter, view: CallerArgumentsView): OperationFailureResponse;
+export declare function sanitizeOperationFailure(error: unknown, origin: FailureOrigin, report: DiagnosticsReporter, view: CallerArgumentsView): AvOperationFailureResponse;
+/**
+ * A filter over the context its stage is told: an operation's `AvFilter`,
+ * or a Resource transaction filter, whose context is the plan.
+ */
+type FilterOf<Context> = (error: unknown, context: Context) => AvError | undefined | Promise<AvError | undefined>;
 /**
  * Post-validation exception flow: effective filters are stored as `[root...,
  * scoped...]`, so reverse iteration tries scoped filters in reverse registration
- * order, then root filters in reverse, then final sanitization. A filter handles an
- * error only by returning a {@link FrameworkError}; returning `undefined` or throwing
- * leaves the original error unhandled.
+ * order, then root filters in reverse. An error they leave unhandled goes to
+ * `outer` when there is one (a transaction step's: its Resource transaction
+ * filters, run once the transaction interceptors have unwound), else to final
+ * sanitization. A filter handles an error only by returning a {@link AvError};
+ * returning `undefined` or throwing leaves the original error unhandled.
+ */
+export declare function resolveOperationFailure<Context = AvContext>(error: unknown, filters: readonly FilterOf<Context>[], context: Context, boundary: AdapterBoundary, report: DiagnosticsReporter, view: CallerArgumentsView, outer?: OuterFailureLayer): Promise<AvOperationFailureResponse>;
+/**
+ * An error a step's own filters left unhandled, with what answering it later
+ * needs: the caller's arguments as the step held them, the step's Adapter
+ * boundary (whose identity says whose words the error is) and its reporter.
+ */
+export type UnhandledFailure = {
+    readonly error: unknown;
+    readonly view: CallerArgumentsView;
+    readonly boundary: AdapterBoundary;
+    readonly report: DiagnosticsReporter;
+};
+/**
+ * Where a transaction step hands an error its own filters left unhandled. It
+ * records the error and answers a provisional failure, which fails the step; the
+ * transaction replaces it with the transaction filters' answer.
  */
-export declare function resolveOperationFailure(error: unknown, filters: readonly Filter[], context: PipelineContext, boundary: AdapterBoundary, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<OperationFailureResponse>;
+export type OuterFailureLayer = {
+    readonly defer: (failure: UnhandledFailure) => AvOperationFailureResponse;
+};
+/**
+ * An unhandled step error through `chain` (the transaction filters, the first
+ * that handles it wins), then final sanitization.
+ */
+export declare function resolveUnhandledFailure(failure: UnhandledFailure, chain: FilterChain): Promise<AvOperationFailureResponse>;
+/**
+ * A chain of filters and the context they are told, tried in reverse: the first
+ * that returns an {@link AvError} handles the error.
+ */
+export type FilterChain = {
+    readonly attempt: (error: unknown, view: CallerArgumentsView, boundary: AdapterBoundary) => Promise<FilteredOutcome | undefined>;
+};
+/** The chain of `filters` (stored outer to inner, tried in reverse), told `context`. */
+export declare function filterChain<Context>(filters: readonly FilterOf<Context>[], context: Context): FilterChain;
+/** What a filter returned, and the deliberate outcome it vets as. */
+type FilteredOutcome = {
+    readonly returned: unknown;
+    readonly outcome: DeliberateOutcome;
+};
+export {};