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

package/dist/runtime/create-requirement.js

@@ -1,6 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { advertisedDirectivesAt } from "../contracts/field.js";
-import { NESTED_WRITE_SCOPE, resolveWriteScope, } from "../operations/write-scope.resolver.js";
+import { LOOPBACK_WRITE_SCOPE, NESTED_WRITE_SCOPE, resolveWriteScope, } from "../operations/write-scope.resolver.js";
 import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -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,53 +24,104 @@ 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;
     }
+    if (context.computed !== undefined) {
+        computedRequirementGaps(context, resource, record, path, via);
+        walkNestedCreates(context, resource, record, path);
+        return;
+    }
     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 looped = loopbackWrites(context, resource, record, path, via, "create");
+    const conflicted = looped.size > 0
+        ? looped
+        : referenceConflicts(context, resource, record, path);
+    if (looped.size === 0) {
+        mixedReferenceWrites(context, resource, record, path, conflicted);
+    }
+    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);
@@ -130,14 +167,93 @@ function mixedReferenceWrites(context, resource, record, path, conflicted) {
         });
     }
 }
-function checkUpdateRecord(context, resource, record, path) {
+function checkUpdateRecord(context, resource, record, path, via) {
     if (!isRecord(record)) {
         return;
     }
-    const conflicted = referenceConflicts(context, resource, record, path);
-    mixedReferenceWrites(context, resource, record, path, conflicted);
+    if (context.computed === undefined &&
+        loopbackWrites(context, resource, record, path, via, "update").size === 0) {
+        const conflicted = referenceConflicts(context, resource, record, path);
+        mixedReferenceWrites(context, resource, record, path, conflicted);
+    }
     walkNestedCreates(context, resource, record, path);
 }
+function loopbackWrites(context, resource, record, path, via, stage) {
+    const refused = new Set();
+    if (via === undefined) {
+        return refused;
+    }
+    const { contract } = context;
+    const edge = lookupField(lookupResource(contract, via.resource), via.relation);
+    if (edge?.kind !== "relation" || typeof edge.inverse !== "string") {
+        return refused;
+    }
+    const inverse = edge.inverse;
+    const other = lookupField(lookupResource(contract, resource), inverse);
+    if (other?.kind === "relation" &&
+        advertisedDirectivesAt(other.capabilities[stage], LOOPBACK_WRITE_SCOPE) !==
+            undefined) {
+        return refused;
+    }
+    const references = edgesOf(context.references, resource).find((candidate) => candidate.field === inverse) ?? undefined;
+    for (const field of [
+        inverse,
+        ...(references === undefined ? [] : referencesOf(references)),
+    ]) {
+        if (!written(record, field)) {
+            continue;
+        }
+        refused.add(field);
+        context.issues.push({
+            code: "V1012",
+            path: [...path, field],
+            message: field === inverse
+                ? `Relation "${field}" is the relation this ${resource} is written through, from its other end ("${via.resource}.${via.relation}"): the write it sits in supplies it.`
+                : `Field "${field}" holds the reference of "${inverse}", the relation this ${resource} is written through ("${via.resource}.${via.relation}"): the write it sits in supplies it.`,
+        });
+    }
+    return refused;
+}
+function computedRequirementGaps(context, resource, record, path, via) {
+    const reader = context.computed;
+    const computed = reader?.computed(resource);
+    const stated = reader?.stated(resource);
+    if (computed === undefined || computed.size === 0 || stated === undefined) {
+        return;
+    }
+    const supplied = suppliedThrough(stated, via);
+    const gap = (field) => {
+        context.gaps?.push({
+            resource,
+            field,
+            issue: {
+                code: "V1000",
+                path: [...path, field],
+                message: `compute.create on ${resource}.${field} returned undefined for a required field.`,
+            },
+        });
+    };
+    for (const field of namesOf(stated.required)) {
+        if (computed.has(field) &&
+            !supplied.has(field) &&
+            !written(record, field)) {
+            gap(field);
+        }
+    }
+    const groups = Array.isArray(stated.oneOf) ? stated.oneOf : [];
+    for (const group of groups) {
+        const [relation, ...references] = namesOf(group);
+        const left = references.find((field) => computed.has(field) && !written(record, field));
+        if (relation === undefined ||
+            left === undefined ||
+            supplied.has(relation) ||
+            references.some((field) => supplied.has(field)) ||
+            written(record, relation)) {
+            continue;
+        }
+        gap(left);
+    }
+}
 function walkNestedCreates(context, resource, record, path) {
     if (!isRecord(record)) {
         return;
@@ -169,7 +285,7 @@ function walkNestedCreates(context, resource, record, path) {
                         checkCreateRecord(context, field.target, siteRecord, sitePath, NESTED_WRITE_SCOPE, via);
                     }
                     else {
-                        checkUpdateRecord(context, field.target, siteRecord, sitePath);
+                        checkUpdateRecord(context, field.target, siteRecord, sitePath, via);
                     }
                 }
             }
@@ -177,21 +293,52 @@ function walkNestedCreates(context, resource, record, path) {
     }
 }
 export function recordWriteFactsOf(adapter) {
+    const resources = adapter.model?.resources ?? {};
     return {
-        requirements: adapter.createRequirements ?? {},
         references: adapter.referentialActions ?? {},
+        stated: (resource) => {
+            const found = Object.hasOwn(resources, resource)
+                ? resources[resource]
+                : undefined;
+            const stated = isRecord(found) ? found.createRequirements : undefined;
+            return isRecord(stated) ? stated : undefined;
+        },
     };
 }
 export function createRequirementIssues(contract, facts, request, args, argumentsPath) {
-    if (!isRecord(args)) {
-        return [];
-    }
     const context = {
         contract,
-        requirements: facts.requirements,
         references: facts.references,
         issues: [],
     };
+    walkOperation(context, request, args, argumentsPath);
+    return context.issues;
+}
+export function preliminaryRecordIssues(contract, facts, request, args, argumentsPath) {
+    const context = {
+        contract,
+        references: facts.references,
+        issues: [],
+    };
+    walkOperation(context, request, args, argumentsPath);
+    return context.issues;
+}
+export function computedRequirementGapsOf(contract, facts, request, args, argumentsPath, computed) {
+    const gaps = [];
+    walkOperation({
+        contract,
+        references: facts.references,
+        issues: [],
+        computed: { stated: facts.stated, computed },
+        gaps,
+    }, request, args, argumentsPath);
+    return gaps;
+}
+function walkOperation(context, request, args, argumentsPath) {
+    if (!isRecord(args)) {
+        return;
+    }
+    const contract = context.contract;
     const scope = resolveWriteScope(lookupResource(contract, request.resource), request);
     if (request.family === "create" && written(args, "data")) {
         const data = args.data;
@@ -206,16 +353,9 @@ export function createRequirementIssues(contract, facts, request, args, argument
     }
     if (request.family === "upsert") {
         checkCreateRecord(context, request.resource, args.create, [...argumentsPath, "create"], scope, undefined);
-        checkUpdateRecord(context, request.resource, args.update, [
-            ...argumentsPath,
-            "update",
-        ]);
+        checkUpdateRecord(context, request.resource, args.update, [...argumentsPath, "update"], undefined);
     }
     if (request.family === "update") {
-        checkUpdateRecord(context, request.resource, args.data, [
-            ...argumentsPath,
-            "data",
-        ]);
+        checkUpdateRecord(context, request.resource, args.data, [...argumentsPath, "data"], undefined);
     }
-    return context.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,75 @@ 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, or `401` when it is
+ * the throw of `mcp.authorization.verify`.
+ */
+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 +109,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 {};