@aventara/core 0.1.0-pilot.0 → 0.1.0-pilot.2

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

@@ -0,0 +1,65 @@
+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;
+};
+/**
+ * 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.
+ */
+export type CreateRequirement = {
+    readonly kind: "field";
+    readonly field: string;
+} | {
+    readonly kind: "relation";
+    readonly relation: string;
+    readonly orFields: readonly 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)[];
+/**
+ * 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.
+ */
+export declare function missingCreateValues(contract: Contract, table: CreateRequirementTable, request: OperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path): readonly ValidationIssue[];
+export {};

package/dist/runtime/create-requirement.js

@@ -0,0 +1,141 @@
+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 { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(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 creatableScalar(contract, resource, field) {
+    const found = lookupField(lookupResource(contract, resource), field);
+    return found?.kind === "scalar" && found.capabilities.create !== undefined;
+}
+function creatableRelation(contract, resource, relation, scope) {
+    const found = lookupField(lookupResource(contract, resource), relation);
+    return (found?.kind === "relation" &&
+        advertisedDirectivesAt(found.capabilities.create, scope) !== undefined);
+}
+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}.`,
+                });
+            }
+            continue;
+        }
+        if (via !== undefined &&
+            requirement.inverse?.resource === via.resource &&
+            requirement.inverse.relation === via.relation) {
+            continue;
+        }
+        const orFields = Array.isArray(requirement.orFields)
+            ? requirement.orFields
+            : [];
+        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}.`,
+            });
+        }
+    }
+    walkNestedCreates(context, resource, record, path);
+}
+function walkNestedCreates(context, resource, record, path) {
+    if (!isRecord(record)) {
+        return;
+    }
+    const owner = lookupResource(context.contract, resource);
+    for (const [key, value] of Object.entries(record)) {
+        const field = lookupField(owner, key);
+        if (field?.kind !== "relation" || !isRecord(value)) {
+            continue;
+        }
+        const via = { resource, relation: key };
+        for (const [directive, operand] of Object.entries(value)) {
+            if (!isRelationMutationDirective(directive)) {
+                continue;
+            }
+            const entries = Array.isArray(operand)
+                ? operand.map((entry, index) => ({ entry, at: [index] }))
+                : [{ entry: operand, at: [] }];
+            for (const { entry, at } of entries) {
+                const entryPath = [...path, key, directive, ...at];
+                for (const site of RELATION_MUTATION_RECORD_SITES[directive]) {
+                    const siteRecord = site.key === undefined
+                        ? entry
+                        : isRecord(entry)
+                            ? entry[site.key]
+                            : undefined;
+                    const sitePath = site.key === undefined ? entryPath : [...entryPath, site.key];
+                    if (site.stage === "create") {
+                        checkCreateRecord(context, field.target, siteRecord, sitePath, NESTED_WRITE_SCOPE, via);
+                    }
+                    else {
+                        walkNestedCreates(context, field.target, siteRecord, sitePath);
+                    }
+                }
+            }
+        }
+    }
+}
+export function missingCreateValues(contract, table, request, args, argumentsPath) {
+    if (!isRecord(args)) {
+        return [];
+    }
+    const context = { contract, table, issues: [] };
+    const scope = resolveWriteScope(lookupResource(contract, request.resource), request);
+    if (request.family === "create" && written(args, "data")) {
+        const data = args.data;
+        if (Array.isArray(data)) {
+            data.forEach((entry, index) => {
+                checkCreateRecord(context, request.resource, entry, [...argumentsPath, "data", index], scope, undefined);
+            });
+        }
+        else {
+            checkCreateRecord(context, request.resource, data, [...argumentsPath, "data"], scope, undefined);
+        }
+    }
+    if (request.family === "upsert") {
+        checkCreateRecord(context, request.resource, args.create, [...argumentsPath, "create"], scope, undefined);
+        walkNestedCreates(context, request.resource, args.update, [
+            ...argumentsPath,
+            "update",
+        ]);
+    }
+    if (request.family === "update") {
+        walkNestedCreates(context, request.resource, args.data, [
+            ...argumentsPath,
+            "data",
+        ]);
+    }
+    return context.issues;
+}

package/dist/runtime/decimal.d.ts

@@ -5,8 +5,8 @@ export declare class Decimal {
     toString(): string;
     /**
      * The decimal string, exactly as given: what `JSON.stringify` writes for a
-     * Decimal (Q16), so a result a developer serializes by hand carries its
-     * digits rather than `{}`. The protocol's encoders do not rely on it.
+     * Decimal, so a result a developer serializes by hand carries its digits rather
+     * than `{}`. The protocol's encoders do not rely on it.
      */
     toJSON(): string;
 }

package/dist/runtime/decimal.js

@@ -1,10 +1,7 @@
 import { WIRE_SCALAR_PATTERNS } from "../contracts/wire-scalar-format.js";
-/** Provider-neutral exact decimal runtime value owned by Aventara. */
 export class Decimal {
     #value;
     constructor(value) {
-        // `RegExp#test` coerces its argument, so without this guard a number from
-        // untyped code passed as `"5"` and `toString()` then returned the number.
         if (typeof value !== "string") {
             throw new TypeError("Decimal value must be a string.");
         }
@@ -16,11 +13,6 @@ export class Decimal {
     toString() {
         return this.#value;
     }
-    /**
-     * The decimal string, exactly as given: what `JSON.stringify` writes for a
-     * Decimal (Q16), so a result a developer serializes by hand carries its
-     * digits rather than `{}`. The protocol's encoders do not rely on it.
-     */
     toJSON() {
         return this.#value;
     }

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

@@ -5,12 +5,12 @@ import type { FrameworkOperationRequest } from "./operation-request.js";
 import type { OperationErrorCode } from "./operation-response.js";
 /**
  * One unplanned failure as the framework saw it before sanitization: the raw
- * value, the outcome code actually emitted, and enough identity to act on
- * it. The code is usually an internal one, because the channel fires for
- * unplanned failures; it is the thrower's own code when the framework
- * dropped something it could not vouch for from an otherwise honoured
- * deliberate outcome (ADR 0008 decision 4), which changes no outcome. Server-side only — a diagnostic is never projected
- * onto the wire, which is precisely why it may carry the raw error.
+ * value, the outcome code actually emitted, and enough identity to act on it. The
+ * code is usually an internal one, because the channel fires for unplanned
+ * failures; it is the thrower's own code when the framework dropped something it
+ * could not vouch for from an otherwise honoured deliberate outcome, which changes
+ * no outcome. Server-side only — a diagnostic is never projected onto the wire,
+ * which is precisely why it may carry the raw error.
  */
 export type OperationDiagnostic = {
     readonly kind: "operation";

package/dist/runtime/diagnostics-reporter.js

@@ -1,9 +1,4 @@
-/** The default channel: no sink configured, so nothing is observed. */
 const IGNORE_DIAGNOSTIC = () => undefined;
-/**
- * A sink may return a promise. Reading `then` off an arbitrary return value
- * can itself throw, so this runs inside the reporter's own guard.
- */
 function isThenable(value) {
     if ((typeof value !== "object" || value === null) &&
         typeof value !== "function") {
@@ -11,12 +6,6 @@ function isThenable(value) {
     }
     return typeof value.then === "function";
 }
-/**
- * The channel bound to one diagnostic identity, as the reporters below bind
- * it. Exported for `@aventara/core/protocol`, whose binding reports a failure
- * only it can meet — a result with no wire form (`A3003`) — under the
- * identity it holds; never exported from the main entry.
- */
 export function createReporter(sink, identity) {
     if (sink === undefined) {
         return IGNORE_DIAGNOSTIC;
@@ -33,38 +22,15 @@ export function createReporter(sink, identity) {
         }
     };
 }
-/**
- * The sink each constructed Framework was configured with, keyed by the
- * Framework object `createFramework` returned. The protocol's binding
- * (`AvProtocol.bind(framework)`, `@aventara/core/protocol`) reads it here, so
- * the direction stays one-way — no execution module imports `protocol/` — and
- * the public `Framework` type gains no member. A WeakMap: it keeps no
- * Framework alive. A Framework built without a sink has no entry.
- */
 const CONFIGURED_SINKS = new WeakMap();
-/** Records the sink `framework` was configured with; called once, at construction. */
 export function recordDiagnosticsSink(framework, sink) {
     if (sink !== undefined) {
         CONFIGURED_SINKS.set(framework, sink);
     }
 }
-/** The sink `framework` was configured with, or `undefined` for none. */
 export function diagnosticsSinkOf(framework) {
     return CONFIGURED_SINKS.get(framework);
 }
-/**
- * Binds the configured sink to one operation request.
- *
- * Identity is captured on entry rather than at report time: by the moment a
- * failure is reported the request may be exactly what broke, and a diagnostic
- * naming no operation is not actionable. A request whose own identity cannot
- * be read is past observing, so it silently yields the no-op channel — the
- * outermost totality guard still answers with the generic envelope.
- *
- * The response must be unaffected by observation, so the reporter neither
- * awaits the sink nor lets anything the sink does escape: a throw, a rejected
- * promise and a booby-trapped thenable all end here.
- */
 export function createDiagnosticsReporter(sink, request, operation) {
     let identity;
     try {
@@ -83,7 +49,6 @@ export function createDiagnosticsReporter(sink, request, operation) {
     }
     return createReporter(sink, identity);
 }
-/** Binds the configured sink to one transaction request and its plan operations. */
 export function createTransactionDiagnosticsChannel(sink, request) {
     let identity;
     try {

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

@@ -17,9 +17,9 @@ export declare class AdapterBoundary {
     originOf(error: unknown): FailureOrigin;
 }
 /**
- * The one result-serialization text; every A3003 carries it. Its producer is
- * the protocol's response encoder (`@aventara/core/protocol`, P1), which
- * imports it from here so the code has one text wherever it is emitted.
+ * The one result-serialization text; every A3003 carries it. Its producer is the
+ * protocol's response encoder, which imports it from here so the code has one text
+ * wherever it is emitted.
  */
 export declare const SERIALIZATION_FAILURE_MESSAGE = "Result serialization failed.";
 /** Where a standalone operation's arguments sit in a framework issue path. */

package/dist/runtime/error-boundary.js

@@ -1,16 +1,10 @@
 import { VALIDATION_CODE_MESSAGES, VALIDATION_CODES, } from "../operations/validation-code.js";
 import { FrameworkError } from "./framework-error.js";
 import { INTERNAL_FAILURE_MESSAGE, internalFailure, OPERATION_CODES, operationFailure, } from "./operation-response.js";
-/** The one generic Adapter-failure text; every unexpected A3001 carries it. */
+import { PIPE_OUTPUT_FAILURE_MESSAGE } from "./pipe-output.validator.js";
 export const ADAPTER_FAILURE_MESSAGE = "Adapter execution failed.";
-/**
- * Structurally records every value thrown across the Adapter seam so the
- * final error boundary can classify origin by identity, never by inspecting
- * error text. One boundary instance belongs to one operation execution.
- */
 export class AdapterBoundary {
     #thrown = new Set();
-    /** Runs Adapter work, remembering anything it throws before re-throwing it. */
     async execute(work) {
         try {
             return await work();
@@ -24,29 +18,17 @@ export class AdapterBoundary {
         return this.#thrown.has(error) ? "adapter" : "runtime";
     }
 }
-/**
- * The one result-serialization text; every A3003 carries it. Its producer is
- * the protocol's response encoder (`@aventara/core/protocol`, P1), which
- * imports it from here so the code has one text wherever it is emitted.
- */
 export const SERIALIZATION_FAILURE_MESSAGE = "Result serialization failed.";
-/**
- * The framework's own text for each internal-failure code. An A3xxx cause is
- * never caller-actionable, so whatever text its thrower supplied is replaced
- * by this table — the realistic thrower is a careless Adapter forwarding a
- * provider message, and spec 13.5 forbids that text on the wire.
- */
 const INTERNAL_FAILURE_MESSAGES = {
     A3000: INTERNAL_FAILURE_MESSAGE,
     A3001: ADAPTER_FAILURE_MESSAGE,
     A3002: "Transaction failed.",
     A3003: SERIALIZATION_FAILURE_MESSAGE,
+    A3004: PIPE_OUTPUT_FAILURE_MESSAGE,
 };
-/** The internal code an unexpected failure of one origin is emitted under. */
 function unexpectedCode(origin) {
     return origin === "adapter" ? "A3001" : "A3000";
 }
-/** The generic, text-free envelope for an unexpected failure of one origin. */
 function unexpectedFailure(origin) {
     return origin === "adapter"
         ? operationFailure("A3001", { message: ADAPTER_FAILURE_MESSAGE })
@@ -58,10 +40,6 @@ function isInternalCode(code) {
 function isPathSegment(value) {
     return typeof value === "string" || typeof value === "number";
 }
-/**
- * Whether an untrusted value is a list. `Array.isArray` is not itself total:
- * it throws on a revoked Proxy, and a thrown value may be one.
- */
 function isList(value) {
     try {
         return Array.isArray(value);
@@ -70,15 +48,6 @@ function isList(value) {
         return false;
     }
 }
-/**
- * Copies an untrusted list into a plain array the framework owns. Traversal,
- * not just property reads, is untrusted here: an index accessor, a Proxy
- * trap, an overridden `map` and a hijacked `Symbol.species` all run
- * thrower-supplied code, and none of it may become the boundary's own
- * failure. Elements are read one at a time through {@link readProperty}, so
- * an unreadable element is `undefined` — a value every projection below
- * already rejects. `undefined` means the value is no list at all.
- */
 function readList(value) {
     if (!isList(value)) {
         return undefined;
@@ -93,12 +62,6 @@ function readList(value) {
     }
     return items;
 }
-/**
- * Projects an issue path onto a plain array of segments the framework owns.
- * Copying rather than forwarding is the point: a planted path arrives as a
- * live handle to a caller-held array, and its non-index properties would
- * otherwise ride into the envelope for every in-memory consumer of it.
- */
 function projectPath(value) {
     const items = readList(value);
     if (items === undefined) {
@@ -113,31 +76,13 @@ function projectPath(value) {
     }
     return path;
 }
-/** Where a standalone operation's arguments sit in a framework issue path. */
 export const OPERATION_ARGUMENTS_PATH = [
     "arguments",
 ];
-/** Where one plan operation's arguments sit in a framework issue path. */
 export function planOperationArgumentsPath(index) {
     return ["operations", index, "args"];
 }
-/** A segment that named no own, data-backed member of its container. */
 const UNRESOLVED = Symbol("unresolved-path-segment");
-/**
- * Reads one own, data-backed member of an untrusted container.
- *
- * Own only: satisfying a segment from the prototype chain would let `toString`
- * or `constructor` pose as caller data. Data-backed only: the descriptor is
- * consulted and only its `value` used, so a getter never runs — running a
- * caller's accessor while sanitizing an error is a side effect in the worst
- * possible place.
- *
- * The reflection itself can throw: a revoked Proxy rejects
- * `getOwnPropertyDescriptor`. That is not caught here. The whole walk has one
- * containment point, in {@link resolvesAgainstArguments}, so there is exactly
- * one place where an unwalkable path and an unresolvable one become the same
- * answer.
- */
 function readOwnMember(container, key) {
     if (typeof container !== "object" || container === null) {
         return UNRESOLVED;
@@ -147,7 +92,6 @@ function readOwnMember(container, key) {
         ? descriptor.value
         : UNRESOLVED;
 }
-/** Resolves one path segment; a numeric segment indexes an array and nothing else. */
 function readSegment(container, segment) {
     if (typeof segment === "number") {
         return Number.isInteger(segment) && segment >= 0 && isList(container)
@@ -156,22 +100,6 @@ function readSegment(container, segment) {
     }
     return readOwnMember(container, segment);
 }
-/**
- * Whether a thrower-supplied path denotes a member of the caller's own
- * arguments — the one thing that makes it safe to emit.
- *
- * A path that resolves echoes back a key sequence the caller already holds;
- * anything else is unvouched content on the same channel spec 13.5 closes for
- * the rest of `cause` (ADR 0008 decision 4, applied to the third axis). The
- * prefix must be the framework's own address for these arguments, and every
- * remaining segment must resolve: a resolving prefix does not license the
- * rest, so a partial match is no match.
- *
- * Total, like every step the boundary takes on a thrown value. The walk runs
- * over data the framework does not own — a revoked Proxy on it throws from
- * reflection alone — so the whole walk sits inside one guard: an unresolvable
- * path and an unwalkable one are the same answer.
- */
 function resolvesAgainstArguments(path, view) {
     try {
         if (path.length < view.path.length) {
@@ -199,41 +127,16 @@ function resolvesAgainstArguments(path, view) {
         return false;
     }
 }
-/**
- * Only an allocated Validation code (spec 13.3, amended by ADR 0006 DA-4) may
- * be emitted. This is ADR 0005's rule on the axis it did not cover: the union
- * is a compile-time promise a separately compiled Adapter or a developer
- * filter never made, so the set is tested by identity before emission.
- */
 function isValidationCode(value) {
     return (typeof value === "string" &&
         VALIDATION_CODES.includes(value));
 }
-/**
- * Projects one issue onto the spec ValidationIssue shape; unknown keys drop.
- *
- * All three fields are framework-owned by the time they are emitted.
- * An unrecognised `code` drops the whole issue rather than riding onto the
- * wire in a field the spec defines as a closed set — and rather than being
- * rewritten to a plausible neighbour, which would misreport what was wrong.
- * The `message` is replaced by the framework's own published text for that
- * code, because a thrower-supplied message is the same provider-text channel
- * spec 13.5 closes for the rest of `cause`. The `path` is emitted only when
- * every segment of it resolves against the caller's own arguments; it is an
- * open-ended string channel otherwise, and spec 13.1 makes the field
- * optional, so a path that cannot be vouched for is simply absent — the
- * issue, its code and the outcome are unchanged. Each dropped value is
- * appended to `unvouched`, so the boundary can hand it to the ADR 0004
- * diagnostics channel — the only place it still exists.
- */
 function projectIssue(value, unvouched, view) {
     if (typeof value !== "object" || value === null) {
         return undefined;
     }
     const code = readProperty(value, "code");
     if (!isValidationCode(code)) {
-        // `undefined` is an unreadable or absent code, not a supplied one:
-        // reporting it would be noise, and the issue is malformed either way.
         if (code !== undefined) {
             unvouched.push(code);
         }
@@ -255,18 +158,6 @@ function projectIssue(value, unvouched, view) {
     }
     return { path, code, message: owned };
 }
-/**
- * Projects a thrower-supplied cause onto the spec 13 `Cause` shape:
- * `{ message, issues?, operation? }`. Unknown keys are dropped rather than
- * forwarded, so a provider error assigned wholesale as a cause loses its
- * `sql`, `stack`, DSN and whatever else it carried. A cause without a string
- * message is no cause at all.
- *
- * Total, like every step the boundary takes on a thrown value: a cause it
- * cannot traverse yields the parts it could read, never an exception. A
- * throw here would escape the boundary that was sanitizing it and cost the
- * thrower the very outcome it deliberately named.
- */
 function projectCause(value, unvouched, view) {
     const message = readProperty(value, "message");
     if (typeof message !== "string") {
@@ -279,29 +170,16 @@ function projectCause(value, unvouched, view) {
         .filter((issue) => issue !== undefined);
     return {
         message,
-        // An empty list is no list: dropping every issue leaves the cause
-        // without issues rather than fabricating one to fill the field.
         ...(issues !== undefined && issues.length > 0 ? { issues } : {}),
         ...(Number.isInteger(rawOperation) && rawOperation >= 0
             ? { operation: rawOperation }
             : {}),
     };
 }
-/**
- * Internal failures carry no caller-actionable diagnostics: the message is
- * the framework's own and `issues` raised while validating computed/Adapter
- * output describe server internals and stay behind the boundary (available
- * to filters, never emitted).
- */
 function internalCause(code, cause) {
     const { issues: _issues, message: _message, ...emitted } = cause;
     return { ...emitted, message: INTERNAL_FAILURE_MESSAGES[code] };
 }
-/**
- * Reads one property of a thrown value. Thrown values are untrusted: a
- * getter or Proxy trap may itself throw, and that must never become the
- * boundary's own failure.
- */
 function readProperty(value, key) {
     try {
         return value[key];
@@ -318,34 +196,16 @@ function isFrameworkErrorInstance(error) {
         return false;
     }
 }
-/**
- * A {@link FrameworkError} that fails vetting. Its thrower deliberately named
- * an outcome the framework cannot honour, so the failure is the broken
- * outcome contract itself — an internal error, whatever the origin — and the
- * offending value is replaced, never echoed.
- */
 const MALFORMED_OUTCOME = {
     code: "A3000",
     cause: { message: INTERNAL_FAILURE_MESSAGE },
     unvouched: [],
 };
-/**
- * Only a recognised error code (spec 13.2) is a deliberate outcome. An
- * unknown code, or a success code arriving on the failure path, would break
- * the ADR 0003 union on the wire.
- */
 function isOperationErrorCode(value) {
     return (typeof value === "string" &&
         OPERATION_CODES.includes(value) &&
         !value.startsWith("A1"));
 }
-/**
- * Vets a value as a deliberate {@link FrameworkError}. `undefined` means it
- * is not one at all. Passing the `instanceof` check is not enough:
- * `Object.create(FrameworkError.prototype)`, a booby-trapped accessor, an
- * unrecognised code or a cause without a message all reach here, and each
- * is {@link MALFORMED_OUTCOME} rather than something to dereference or emit.
- */
 function vetDeliberateOutcome(error, view) {
     if (!isFrameworkErrorInstance(error)) {
         return undefined;
@@ -361,31 +221,16 @@ function vetDeliberateOutcome(error, view) {
     const cause = projectCause(rawCause, unvouched, view);
     return cause === undefined ? MALFORMED_OUTCOME : { code, cause, unvouched };
 }
-/**
- * Hands every dropped issue code and issue path to the ADR 0004 channel under
- * the outcome actually emitted. Dropping something the framework cannot vouch
- * for is no grounds to escalate the thrower's chosen outcome, so the code
- * stands and the channel carries the whole consequence. Reporting cannot
- * affect the response: the reporter is total and swallows whatever the sink
- * does.
- */
 function reportUnvouched(outcome, report) {
     for (const value of outcome.unvouched) {
         report(value, outcome.code);
     }
 }
-/** A deliberate outcome: the stable code and cause its thrower chose. */
 function deliberateFailure(outcome) {
     return operationFailure(outcome.code, isInternalCode(outcome.code)
         ? internalCause(outcome.code, outcome.cause)
         : outcome.cause);
 }
-/**
- * Final framework sanitization, shared by every boundary. A deliberate
- * {@link FrameworkError} 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 function sanitizeOperationFailure(error, origin, report, view) {
     const outcome = vetDeliberateOutcome(error, view);
     if (outcome === undefined) {
@@ -398,13 +243,6 @@ export function sanitizeOperationFailure(error, origin, report, view) {
     reportUnvouched(outcome, report);
     return deliberateFailure(outcome);
 }
-/**
- * Post-validation exception flow (spec 17.3): 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.
- */
 export async function resolveOperationFailure(error, filters, context, boundary, report, view) {
     for (let index = filters.length - 1; index >= 0; index -= 1) {
         const filter = filters[index];
@@ -413,9 +251,6 @@ export async function resolveOperationFailure(error, filters, context, boundary,
         }
         const handled = await attemptFilter(filter, error, context, view);
         if (handled !== undefined) {
-            // A filter that names an outcome the framework cannot honour has
-            // swallowed the original error on the developer's behalf; the
-            // diagnostics channel is the only place it still exists.
             if (handled === MALFORMED_OUTCOME) {
                 report(error, "A3000");
             }