@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

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

@@ -1,65 +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";
-/**
- * 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.
- */
-/** A relation edge, named by the Resource that holds it and its field there. */
-export type CreateRequirementEdge = {
-    readonly resource: string;
-    readonly relation: string;
-};
+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";
+type Path = readonly (string | number)[];
 /**
- * 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 one of `orFields` must be — the scalar fields that hold
- *   the reference. When the row is created **through** the relation's other end
- *   (`inverse`), the parent supplies it, and it is not required.
+ * 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 CreateRequirement = {
-    readonly kind: "field";
-    readonly field: string;
-} | {
-    readonly kind: "relation";
-    readonly relation: string;
-    readonly orFields: readonly string[];
-    readonly inverse?: CreateRequirementEdge;
+export type RecordWriteFacts = {
+    readonly references: ReferentialActionTable;
 };
-/**
- * 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)[];
+/** The facts an Adapter stated, read off it once; an absent table states nothing. */
+export declare function recordWriteFactsOf(adapter: {
+    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
- * `create`, and every nested create under any write — in argument order.
- * Empty when nothing is missing. Total over malformed input.
+ * 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 missingCreateValues(contract: Contract, table: CreateRequirementTable, 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,13 @@ function isRecord(value) {
 function written(record, key) {
     return Object.hasOwn(record, key) && record[key] !== undefined;
 }
-function requirementsOf(table, resource) {
+function edgesOf(table, resource) {
     const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
     return Array.isArray(listed) ? listed : [];
 }
+function referencesOf(edge) {
+    return Array.isArray(edge.references) ? edge.references : [];
+}
 function creatableScalar(contract, resource, field) {
     const found = lookupField(lookupResource(contract, resource), field);
     return found?.kind === "scalar" && found.capabilities.create !== undefined;
@@ -21,52 +24,145 @@ 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;
     }
     const { contract, issues } = context;
-    for (const requirement of requirementsOf(context.table, 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 conflicted = referenceConflicts(context, resource, record, path);
+    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 (via !== undefined &&
-            requirement.inverse?.resource === via.resource &&
-            requirement.inverse.relation === via.relation) {
+        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);
+}
+function referenceConflicts(context, resource, record, path) {
+    const conflicted = new Set();
+    for (const edge of edgesOf(context.references, resource)) {
+        if (!written(record, edge.field)) {
             continue;
         }
-        const orFields = Array.isArray(requirement.orFields)
-            ? requirement.orFields
-            : [];
-        if (written(record, requirement.relation) ||
-            (orFields.length > 0 && orFields.every((field) => written(record, field)))) {
+        const fields = referencesOf(edge).filter((field) => written(record, field));
+        if (fields.length === 0) {
             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 ")}` : ""}.`,
-            });
+        conflicted.add(edge.field);
+        context.issues.push({
+            code: "V1012",
+            path: [...path, edge.field],
+            message: `Set ${fields.map((field) => `"${field}"`).join(" and ")} or "${edge.field}", not both.`,
+        });
+    }
+    return conflicted;
+}
+function mixedReferenceWrites(context, resource, record, path, conflicted) {
+    if (context.contract.referenceWrites !== "uniform") {
+        return;
+    }
+    const edges = edgesOf(context.references, resource);
+    const referenceFields = [...new Set(edges.flatMap(referencesOf))];
+    for (const edge of edges) {
+        if (!written(record, edge.field) || conflicted.has(edge.field)) {
             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 fields = referenceFields.filter((field) => written(record, field));
+        if (fields.length === 0) {
+            continue;
         }
+        const named = fields.map((field) => `"${field}"`).join(" and ");
+        context.issues.push({
+            code: "V1012",
+            path: [...path, edge.field],
+            message: `Use relation fields only, or reference fields only, in one record: ${named} ${fields.length === 1 ? "is a reference field" : "are reference fields"} and "${edge.field}" is a relation.`,
+        });
+    }
+}
+function checkUpdateRecord(context, resource, record, path) {
+    if (!isRecord(record)) {
+        return;
     }
+    const conflicted = referenceConflicts(context, resource, record, path);
+    mixedReferenceWrites(context, resource, record, path, conflicted);
     walkNestedCreates(context, resource, record, path);
 }
 function walkNestedCreates(context, resource, record, path) {
@@ -100,18 +196,25 @@ function walkNestedCreates(context, resource, record, path) {
                         checkCreateRecord(context, field.target, siteRecord, sitePath, NESTED_WRITE_SCOPE, via);
                     }
                     else {
-                        walkNestedCreates(context, field.target, siteRecord, sitePath);
+                        checkUpdateRecord(context, field.target, siteRecord, sitePath);
                     }
                 }
             }
         }
     }
 }
-export function missingCreateValues(contract, table, request, args, argumentsPath) {
+export function recordWriteFactsOf(adapter) {
+    return { references: adapter.referentialActions ?? {} };
+}
+export function createRequirementIssues(contract, facts, request, args, argumentsPath) {
     if (!isRecord(args)) {
         return [];
     }
-    const context = { contract, table, issues: [] };
+    const context = {
+        contract,
+        references: facts.references,
+        issues: [],
+    };
     const scope = resolveWriteScope(lookupResource(contract, request.resource), request);
     if (request.family === "create" && written(args, "data")) {
         const data = args.data;
@@ -126,13 +229,13 @@ export function missingCreateValues(contract, table, request, args, argumentsPat
     }
     if (request.family === "upsert") {
         checkCreateRecord(context, request.resource, args.create, [...argumentsPath, "create"], scope, undefined);
-        walkNestedCreates(context, request.resource, args.update, [
+        checkUpdateRecord(context, request.resource, args.update, [
             ...argumentsPath,
             "update",
         ]);
     }
     if (request.family === "update") {
-        walkNestedCreates(context, request.resource, args.data, [
+        checkUpdateRecord(context, request.resource, args.data, [
             ...argumentsPath,
             "data",
         ]);

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,63 +1,105 @@
-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. 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 scope: 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 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.
+     */
+    readonly deliberate?: true;
 };
 /**
  * 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 scope: 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 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) => 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<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. */
@@ -66,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) &&
@@ -10,9 +12,16 @@ export function createReporter(sink, identity) {
     if (sink === undefined) {
         return IGNORE_DIAGNOSTIC;
     }
-    return (error, code) => {
+    return (error, code, marks) => {
         try {
-            const settled = sink({ ...identity, error, code });
+            const settled = sink(identity.kind === "operation"
+                ? {
+                    ...identity,
+                    error,
+                    code,
+                    ...(marks?.deliberate === true ? { deliberate: true } : {}),
+                }
+                : { ...identity, error, code });
             if (isThenable(settled)) {
                 settled.then(undefined, () => undefined);
             }
@@ -23,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);
@@ -36,7 +67,7 @@ export function createDiagnosticsReporter(sink, request, operation) {
     try {
         identity = {
             kind: "operation",
-            scope: request.scope,
+            origin: request.origin,
             resource: request.resource,
             family: request.family,
             variant: request.variant,
@@ -54,7 +85,7 @@ export function createTransactionDiagnosticsChannel(sink, request) {
     try {
         identity = {
             kind: "transaction",
-            scope: request.scope,
+            origin: request.origin,
             requestId: request.requestId,
         };
     }

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. */
@@ -20,6 +21,8 @@ export declare class AdapterBoundary {
 export declare const SERIALIZATION_FAILURE_MESSAGE = "Result serialization failed.";
 /** Where a standalone operation's arguments sit in a framework issue path. */
 export declare const OPERATION_ARGUMENTS_PATH: readonly (string | number)[];
+/** Where one plan step sits in a framework issue path: its node in the request. */
+export declare function planStepPath(index: number): readonly (string | number)[];
 /** Where one plan operation's arguments sit in a framework issue path. */
 export declare function planOperationArgumentsPath(index: number): readonly (string | number)[];
 /**
@@ -31,18 +34,80 @@ export type CallerArgumentsView = {
     readonly path: readonly (string | number)[];
     readonly arguments: unknown;
 };
+/**
+ * The longest issue message a developer's code may send to the caller, in UTF-16
+ * code units. A longer one, or one with no visible character, is replaced by the
+ * 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(error: unknown, filters: readonly Filter[], context: PipelineContext, boundary: AdapterBoundary, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<OperationFailureResponse>;
+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 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 {};