@aventara/core 0.1.0-pilot.3 → 1.0.0-rc.0

package/dist/runtime/error-boundary.js

@@ -79,8 +79,11 @@ function projectPath(value) {
 export const OPERATION_ARGUMENTS_PATH = [
     "arguments",
 ];
+export function planStepPath(index) {
+    return ["operations", index];
+}
 export function planOperationArgumentsPath(index) {
-    return ["operations", index, "args"];
+    return [...planStepPath(index), "args"];
 }
 const UNRESOLVED = Symbol("unresolved-path-segment");
 function readOwnMember(container, key) {
@@ -100,38 +103,43 @@ function readSegment(container, segment) {
     }
     return readOwnMember(container, segment);
 }
-function resolvesAgainstArguments(path, view) {
+function vouchPath(path, view) {
     try {
-        if (path.length < view.path.length) {
-            return false;
-        }
-        for (let index = 0; index < view.path.length; index += 1) {
-            if (path[index] !== view.path[index]) {
-                return false;
-            }
+        const root = [view.path, OPERATION_ARGUMENTS_PATH].find((prefix) => startsWith(path, prefix));
+        if (root === undefined) {
+            return undefined;
         }
         let current = view.arguments;
-        for (let index = view.path.length; index < path.length; index += 1) {
+        for (let index = root.length; index < path.length; index += 1) {
             const segment = path[index];
             if (segment === undefined) {
-                return false;
+                return undefined;
             }
             current = readSegment(current, segment);
             if (current === UNRESOLVED) {
-                return false;
+                return undefined;
             }
         }
-        return true;
+        return [...view.path, ...path.slice(root.length)];
     }
     catch {
-        return false;
+        return undefined;
     }
 }
+function startsWith(path, prefix) {
+    return (path.length >= prefix.length &&
+        prefix.every((segment, index) => path[index] === segment));
+}
 function isValidationCode(value) {
     return (typeof value === "string" &&
         VALIDATION_CODES.includes(value));
 }
-function projectIssue(value, unvouched, view) {
+export const MAX_DEVELOPER_ISSUE_MESSAGE_LENGTH = 1_000;
+function isDeveloperMessage(message) {
+    return (message.length <= MAX_DEVELOPER_ISSUE_MESSAGE_LENGTH &&
+        message.trim().length > 0);
+}
+function projectIssue(value, unvouched, view, author) {
     if (typeof value !== "object" || value === null) {
         return undefined;
     }
@@ -142,23 +150,32 @@ function projectIssue(value, unvouched, view) {
         }
         return undefined;
     }
-    const message = readProperty(value, "message");
+    const supplied = readProperty(value, "message");
     const rawPath = readProperty(value, "path");
-    if (typeof message !== "string") {
+    if (typeof supplied !== "string") {
         return undefined;
     }
-    const owned = VALIDATION_CODE_MESSAGES[code];
+    let message = VALIDATION_CODE_MESSAGES[code];
+    if (author === "developer") {
+        if (isDeveloperMessage(supplied)) {
+            message = supplied;
+        }
+        else {
+            unvouched.push(supplied);
+        }
+    }
     if (rawPath === undefined) {
-        return { code, message: owned };
+        return { code, message };
     }
-    const path = projectPath(rawPath);
-    if (path === undefined || !resolvesAgainstArguments(path, view)) {
+    const projected = projectPath(rawPath);
+    const path = projected === undefined ? undefined : vouchPath(projected, view);
+    if (path === undefined) {
         unvouched.push(rawPath);
-        return { code, message: owned };
+        return { code, message };
     }
-    return { path, code, message: owned };
+    return { path, code, message };
 }
-function projectCause(value, unvouched, view) {
+function projectCause(value, unvouched, view, author) {
     const message = readProperty(value, "message");
     if (typeof message !== "string") {
         return undefined;
@@ -166,7 +183,7 @@ function projectCause(value, unvouched, view) {
     const rawIssues = readList(readProperty(value, "issues"));
     const rawOperation = readProperty(value, "operation");
     const issues = rawIssues
-        ?.map((issue) => projectIssue(issue, unvouched, view))
+        ?.map((issue) => projectIssue(issue, unvouched, view, author))
         .filter((issue) => issue !== undefined);
     return {
         message,
@@ -206,7 +223,7 @@ function isOperationErrorCode(value) {
         OPERATION_CODES.includes(value) &&
         !value.startsWith("A1"));
 }
-function vetDeliberateOutcome(error, view) {
+function vetDeliberateOutcome(error, view, author) {
     if (!isFrameworkErrorInstance(error)) {
         return undefined;
     }
@@ -218,7 +235,7 @@ function vetDeliberateOutcome(error, view) {
         return MALFORMED_OUTCOME;
     }
     const unvouched = [];
-    const cause = projectCause(rawCause, unvouched, view);
+    const cause = projectCause(rawCause, unvouched, view, author);
     return cause === undefined ? MALFORMED_OUTCOME : { code, cause, unvouched };
 }
 function reportUnvouched(outcome, report) {
@@ -226,13 +243,20 @@ function reportUnvouched(outcome, report) {
         report(value, outcome.code);
     }
 }
+function reportDeliberate(thrown, outcome, report) {
+    if (isInternalCode(outcome.code)) {
+        report(thrown, outcome.code, { deliberate: true });
+        return;
+    }
+    reportUnvouched(outcome, report);
+}
 function deliberateFailure(outcome) {
     return operationFailure(outcome.code, isInternalCode(outcome.code)
         ? internalCause(outcome.code, outcome.cause)
         : outcome.cause);
 }
 export function sanitizeOperationFailure(error, origin, report, view) {
-    const outcome = vetDeliberateOutcome(error, view);
+    const outcome = vetDeliberateOutcome(error, view, origin === "adapter" ? "adapter" : "developer");
     if (outcome === undefined) {
         report(error, unexpectedCode(origin));
         return unexpectedFailure(origin);
@@ -240,7 +264,9 @@ export function sanitizeOperationFailure(error, origin, report, view) {
     if (outcome === MALFORMED_OUTCOME) {
         report(error, "A3000");
     }
-    reportUnvouched(outcome, report);
+    else {
+        reportDeliberate(error, outcome, report);
+    }
     return deliberateFailure(outcome);
 }
 export async function resolveOperationFailure(error, filters, context, boundary, report, view) {
@@ -249,20 +275,24 @@ export async function resolveOperationFailure(error, filters, context, boundary,
         if (filter === undefined) {
             continue;
         }
-        const handled = await attemptFilter(filter, error, context, view);
+        const handled = await attemptFilter(filter, error, context, view, boundary);
         if (handled !== undefined) {
-            if (handled === MALFORMED_OUTCOME) {
+            if (handled.outcome === MALFORMED_OUTCOME) {
                 report(error, "A3000");
             }
-            reportUnvouched(handled, report);
-            return deliberateFailure(handled);
+            else {
+                reportDeliberate(handled.returned, handled.outcome, report);
+            }
+            return deliberateFailure(handled.outcome);
         }
     }
     return sanitizeOperationFailure(error, boundary.originOf(error), report, view);
 }
-async function attemptFilter(filter, error, context, view) {
+async function attemptFilter(filter, error, context, view, boundary) {
     try {
-        return vetDeliberateOutcome(await filter(error, context), view);
+        const returned = await filter(error, context);
+        const outcome = vetDeliberateOutcome(returned, view, boundary.originOf(returned) === "adapter" ? "adapter" : "developer");
+        return outcome === undefined ? undefined : { returned, outcome };
     }
     catch {
         return undefined;

package/dist/runtime/execution-options.d.ts

@@ -1,11 +1,7 @@
 /**
- * The caller's say over an in-process request it does not write by hand: the
- * second argument of every `framework.application.*` / `framework.client.*` call
- * and of `framework.transaction`.
- *
- * Not "transport options": an in-process call has no transport. A deferred handle
- * (`framework.appTx.*` / `framework.clientTx.*`) takes none — a handle is not a
- * request, and the id belongs to the run that executes it.
+ * Options for one in-process call: the optional second argument of every
+ * `framework.application.*` / `framework.client.*` call and of
+ * `framework.transaction`.
  */
 export type ExecutionOptions = {
     /**

package/dist/runtime/field-behavior.d.ts

@@ -6,34 +6,31 @@ import type { FrameworkResourceKey } from "../config/framework-fields-config.js"
 import type { PipelineContext } from "./pipeline.js";
 /**
  * What a write-stage compute callback is told about the field it is computing.
- *
- * `R` is the Resource the behavior is bound to and `Cfg` the authored
- * configuration literal, so `resource` is the literal Resource name and `field` —
- * like every other field-key position in the framework — is {@link
- * EffectiveFieldKey}: what the adapter discovered plus what the configuration
- * added.
- *
- * `data` is keyed on the same set and stays `unknown`-valued.
- *
- * Under the default `Cfg` the key set degenerates to `string` and this is
- * byte-for-byte the shape it was before `Cfg` existed.
  */
 type ComputedWriteContext<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = {
-    readonly scope: RequestOrigin;
+    readonly origin: RequestOrigin;
     readonly resource: R;
     readonly field: EffectiveFieldKey<M, Cfg, R>;
     readonly value: unknown;
     readonly data: Readonly<Record<EffectiveFieldKey<M, Cfg, R>, unknown>>;
     readonly operation: PipelineContext;
 };
+/**
+ * Computes a field's value when a row is created. It receives the incoming
+ * `data` and returns the value to store.
+ */
 export type ComputeOnCreate<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = (context: ComputedWriteContext<M, Cfg, R>) => unknown | Promise<unknown>;
+/**
+ * Computes a field's value when a row is updated. It receives the incoming
+ * `data` and returns the value to store.
+ */
 export type ComputeOnUpdate<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = (context: ComputedWriteContext<M, Cfg, R>) => unknown | Promise<unknown>;
 /**
- * The read-stage counterpart. It sees the persisted `record` rather than the
- * inbound `data`, keyed on the same effective field set.
+ * Computes a field's value when a row is read. It receives the stored `record`
+ * and returns the value to return.
  */
 export type ComputeOnRead<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = (context: {
-    readonly scope: RequestOrigin;
+    readonly origin: RequestOrigin;
     readonly resource: R;
     readonly field: EffectiveFieldKey<M, Cfg, R>;
     readonly value: unknown;
@@ -41,12 +38,8 @@ export type ComputeOnRead<M extends AdapterModel = AdapterModel, Cfg = AnyFramew
     readonly operation: PipelineContext;
 }) => unknown | Promise<unknown>;
 /**
- * A computed read, optionally declaring the fields it reads.
- *
- * `dependsOn` is a field-key position and therefore keys on
- * {@link EffectiveFieldKey} like every other one. A name outside that set is
- * an array-element assignability failure (`TS2322`), not an excess property:
- * the author wrote a `string` where a member of the key union was required.
+ * A computed read: a compute function, or `{ compute, dependsOn }` naming the
+ * fields it reads.
  */
 export type ComputedReadBehavior<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = ComputeOnRead<M, Cfg, R> | {
     readonly dependsOn?: readonly EffectiveFieldKey<M, Cfg, R>[];

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

@@ -1,7 +1,19 @@
 import type { Cause, OperationErrorCode } from "./operation-response.js";
 /**
- * Stable typed error used by server-side pipelines, behaviors and Adapters to
- * deliberately surface one framework error outcome.
+ * Throw from a pipeline, behavior or Adapter to answer the request with one
+ * framework error code and cause.
+ *
+ * For any code outside `A3xxx`, `cause.message` is sent to the caller exactly as
+ * written: put nothing in it you would not show the caller (no database text,
+ * SQL, stack, path or secret). So is each issue's `message`, when your own code
+ * (a pipe, guard, hook, interceptor, filter or behavior) throws it and it is not
+ * blank and at most 1,000 characters; otherwise, and for an issue an Adapter
+ * throws, the caller receives the framework's own text for the issue's code. An
+ * issue's `code` must be a validation code (`V1000` and up) and its `path` must
+ * name a member of the request's own arguments, or the issue, or the path, is
+ * not sent. For an `A3xxx` code the caller receives the framework's generic
+ * message instead, and nothing of the cause; the error itself reaches the root
+ * `diagnostics` sink once, marked `deliberate: true`.
  */
 export declare class FrameworkError extends Error {
     readonly code: OperationErrorCode;

package/dist/runtime/json-value.d.ts

@@ -1,22 +1,14 @@
 /**
- * A JSON value: the runtime form of the `json` scalar, inside and out.
+ * A JSON value: the form of the `json` scalar, in arguments and results.
  *
- * It is exactly what `normalizeJsonValue` (`runtime/scalar-runtime.ts`) admits,
- * and that traversal emits only this type, so the runtime and the type are one
- * fact rather than two that agree. Measured in all three scopes alike: a `Date`,
- * a `bigint`, a `Uint8Array`, core's `Decimal`, any other class instance and an
- * `undefined` property are refused (`V1001`), and none of them is a member here.
+ * A `Date`, a `bigint`, a `Uint8Array`, a {@link Decimal}, any other class
+ * instance and an `undefined` property are refused (`V1001`), as are a
+ * non-finite `number` (`V1004`) and a cycle (`V1001`).
  *
- * Two runtime refusals a type cannot carry: a non-finite `number` (`V1004`) and
- * a cycle (`V1001`).
+ * Results are fresh plain copies, so mutating one is safe.
  *
- * The containers are `readonly`, which an input accepts in either form and a
- * result under-claims: the framework hands back a fresh plain copy, so mutating
- * one is safe, but nothing is promised about it.
- *
- * A `json` FIELD's form is this without its top-level `null`
- * (`ApplicationScalarForms["json"]`): a field-level `null` is the field's
- * absence, which only `nullable: true` admits.
+ * A `json` field's value is this without its top-level `null`: a field-level
+ * `null` is the field's absence, which only `nullable: true` admits.
  */
 export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;

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

@@ -0,0 +1,32 @@
+import type { RequestOrigin } from "../config/config-layer.js";
+import type { OperationFamily } from "../operations/operation-identity.js";
+/**
+ * One caller value the framework refused because it could not be read
+ * (`"unreadable-value"`: a revoked Proxy, a throwing getter or trap) or is not plain
+ * data (`"non-plain-value"`: a class instance other than `Date`, `Decimal` or
+ * `Uint8Array`). The caller received `A2004` with one `V1001` at `path`.
+ *
+ * The operation's identity is present when the framework could read it — absent for
+ * a request whose own envelope could not be read — and `operation` is the step's
+ * index in a transaction plan.
+ */
+export type FrameworkMisuseEvent = {
+    readonly kind: "unreadable-value" | "non-plain-value";
+    /** The issue path the caller received. */
+    readonly path: readonly (string | number)[];
+    readonly origin?: RequestOrigin;
+    readonly resource?: string;
+    readonly family?: OperationFamily;
+    readonly variant?: string;
+    readonly operation?: number;
+};
+/**
+ * Receives a {@link FrameworkMisuseEvent} for every caller value the framework
+ * refused as unreadable or not plain data. Set once, as the root configuration's
+ * `misuse`. What it returns, throws or rejects with never reaches the response.
+ */
+export type FrameworkMisuseSink = (event: FrameworkMisuseEvent) => void | Promise<void>;
+/** The channel as the runtime holds it: total, never awaited. */
+export type MisuseReporter = (event: FrameworkMisuseEvent) => void;
+/** Binds the configured sink; without one, nothing is observed. */
+export declare function createMisuseReporter(sink: FrameworkMisuseSink | undefined): MisuseReporter;

package/dist/runtime/misuse-reporter.js

@@ -0,0 +1,19 @@
+const IGNORE_MISUSE = () => undefined;
+export function createMisuseReporter(sink) {
+    if (sink === undefined) {
+        return IGNORE_MISUSE;
+    }
+    return (event) => {
+        try {
+            const settled = sink(event);
+            if (typeof settled === "object" &&
+                settled !== null &&
+                typeof settled.then === "function") {
+                settled.then(undefined, () => undefined);
+            }
+        }
+        catch {
+            return;
+        }
+    };
+}

package/dist/runtime/mutation-planner.d.ts

@@ -4,11 +4,10 @@ import type { Contract, CoreContract } from "../contracts/contract.js";
 import type { OperationExecutionRequest } from "./operation-request.js";
 import type { PipelineContext } from "./pipeline.js";
 /**
- * The two Contracts a write reads. The **Core** Contract decides what the Adapter
- * is asked to store; the **active** Contract adds the fields its scope declared
- * under `application.fields` / `client.fields`, which Core does not carry. Such a
- * field is VIRTUAL by construction (`contract.compiler.ts`), so its behaviours run
- * and its value is stripped before the Adapter call — never sent.
+ * The two Contracts a write reads. The Core Contract decides what the Adapter is asked
+ * to store; the active Contract adds the fields its scope declared under
+ * `application.fields` / `client.fields`, which Core does not carry. Such a field is
+ * virtual: its behaviours run and its value is stripped before the Adapter call.
  */
 export type WriteContracts = {
     readonly core: CoreContract;
@@ -21,13 +20,8 @@ export type RelationRecordSite = {
     readonly stage: WriteStage;
 };
 /**
- * The sole grammar for relation-mutation record operands. Every write pass
- * maps these sites with its own record leaf, leaving identifier-only
- * directives untouched. The identifier operands this table deliberately leaves
- * empty are described by `RELATION_MUTATION_SELECTOR_SITES` in
- * `transactions/operation-arguments-encoder.ts`, the only pass that has to
- * encode them; both tables are keyed by `RelationMutationDirective`, so a new
- * directive fails to compile in both places.
+ * The sole grammar for relation-mutation record operands. Every write pass maps these
+ * sites with its own record leaf, leaving identifier-only directives untouched.
  */
 export declare const RELATION_MUTATION_RECORD_SITES: {
     readonly $create: readonly [{

package/dist/runtime/mutation-planner.js

@@ -1,7 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
-import { FrameworkError } from "./framework-error.js";
-import { INTERNAL_FAILURE_MESSAGE } from "./operation-response.js";
-import { normalizeScalarFieldValue } from "./scalar-runtime.js";
+import { ComputedValueError } from "./computed-value.error.js";
+import { jsonShapeIssues, normalizeScalarFieldValue, } from "./scalar-runtime.js";
 function writeScalarField(contracts, resourceName, fieldName) {
     const field = lookupField(lookupResource(contracts.core, resourceName), fieldName) ??
         lookupField(lookupResource(contracts.active, resourceName), fieldName);
@@ -34,12 +33,6 @@ function cloneRecord(value) {
 function relationEntries(value) {
     return Array.isArray(value) ? value : [value];
 }
-function behaviorFailure(issues) {
-    throw new FrameworkError("A3000", {
-        message: INTERNAL_FAILURE_MESSAGE,
-        issues,
-    });
-}
 async function computeRecord(contracts, behaviors, request, resourceName, stage, data, contextFactory) {
     if (!isRecord(data)) {
         return data;
@@ -64,7 +57,7 @@ async function computeRecord(contracts, behaviors, request, resourceName, stage,
                 continue;
             }
             const computed = await callback({
-                scope: request.scope,
+                origin: request.origin,
                 resource: resourceName,
                 field: fieldName,
                 value: logicalData[fieldName],
@@ -76,7 +69,16 @@ async function computeRecord(contracts, behaviors, request, resourceName, stage,
             }
             const validation = normalizeScalarFieldValue(contracts.core, field, computed, "runtime", ["behaviors", resourceName, fieldName, stage]);
             if (!validation.ok) {
-                behaviorFailure(validation.issues);
+                throw new ComputedValueError(resourceName, fieldName, stage, validation.issues);
+            }
+            const shapeIssues = jsonShapeIssues(field, validation.value, [
+                "behaviors",
+                resourceName,
+                fieldName,
+                stage,
+            ]);
+            if (shapeIssues.length > 0) {
+                throw new ComputedValueError(resourceName, fieldName, stage, shapeIssues);
             }
             logicalData[fieldName] = validation.value;
         }

package/dist/runtime/operation-request.d.ts

@@ -1,12 +1,6 @@
-import type { RequestOrigin } from "../config/config-layer.js";
 import type { OperationIdentity } from "../operations/operation-identity.js";
 import type { PipelineTransportContext } from "./pipeline.js";
-/**
- * @deprecated Use {@link RequestOrigin}. The set it names is not a property of
- * an operation but the origin layer a request belongs to, derived from
- * `ConfigLayer`; kept as an alias so existing consumers keep compiling.
- */
-export type OperationScope = RequestOrigin;
+/** The protocol version and ClientContract hash a client says it was built for. */
 export type ClientProtocolIdentity = {
     readonly version: number;
     readonly hash: string;
@@ -16,24 +10,30 @@ type RuntimeOperationBase = OperationIdentity & {
     readonly arguments: unknown;
     readonly requestId: string;
 };
+/** An in-process request, run under the Application Contract. */
 export type ApplicationOperationRequest = RuntimeOperationBase & {
-    readonly scope: "application";
+    readonly origin: "application";
     readonly protocol?: never;
     readonly transport?: never;
 };
+/**
+ * A remote request, run under the Client Contract; `protocol` is the identity
+ * the client sent.
+ */
 export type ClientOperationRequest = RuntimeOperationBase & {
-    readonly scope: "client";
+    readonly origin: "client";
     readonly protocol: ClientProtocolIdentity;
     readonly transport?: PipelineTransportContext;
 };
+/** One operation request, as `framework.execute` takes it. */
 export type FrameworkOperationRequest = ApplicationOperationRequest | ClientOperationRequest;
 type WithoutArguments<Request> = Request extends unknown ? Omit<Request, "arguments"> : never;
 /**
  * A request as every stage after the Framework Validation Layer sees it:
- * identity, scope, request id and transport, but never `arguments`. Those
+ * identity, origin, request id and transport, but never `arguments`. Those
  * stages act on the validated arguments passed beside it; the unvalidated
  * view — inside a transaction plan still carrying `$ref` placeholders — is
- * unreachable by type. Distributive, so the scope and family/variant
+ * unreachable by type. Distributive, so the origin and family/variant
  * correlations survive the omission.
  */
 export type OperationExecutionRequest = WithoutArguments<FrameworkOperationRequest>;

package/dist/runtime/operation-response.d.ts

@@ -1,21 +1,24 @@
 import type { ValidationIssue } from "../operations/validation-code.js";
+/** Every outcome code, as a runtime list. */
 export declare const OPERATION_CODES: readonly ["A1000", "A1001", "A1002", "A1003", "A1004", "A1005", "A1006", "A1007", "A1008", "A1009", "A2000", "A2001", "A2002", "A2003", "A2004", "A2005", "A2006", "A2007", "A2008", "A2009", "A2010", "A2011", "A2012", "A2013", "A2014", "A3000", "A3001", "A3002", "A3003", "A3004", "A4000", "A4001", "A4002"];
+/**
+ * Every outcome code: `A1xxx` success, `A2xxx` caller error, `A3xxx` internal
+ * failure, `A4xxx` authentication or permission denial.
+ */
 export type OperationCode = (typeof OPERATION_CODES)[number];
+/** The success codes, `A1xxx`. */
 export type OperationSuccessCode = Extract<OperationCode, `A1${string}`>;
+/** Every outcome code that is not a success. */
 export type OperationErrorCode = Exclude<OperationCode, OperationSuccessCode>;
 /** Internal-failure family: nothing in the cause is caller-actionable. */
 export type OperationInternalErrorCode = Extract<OperationErrorCode, `A3${string}`>;
+/** Why a request failed: a message, and the validation issues when there are any. */
 export type Cause = {
     readonly message: string;
     readonly issues?: readonly ValidationIssue[];
     readonly operation?: number;
 };
-/**
- * The canonical wire envelope (spec section 13): a flat `{ data, code,
- * cause }` shape. `OperationResponse<T>` below is a discriminated union
- * derived from this one shape — every arm is a differently-constrained
- * projection of the same three fields, never an independent structure.
- */
+/** The response envelope: `{ data, code, cause }`. */
 type OperationResponseEnvelope<TData, TCode extends OperationCode, TCause extends Cause | null> = {
     readonly data: TData;
     readonly code: TCode;
@@ -23,33 +26,25 @@ type OperationResponseEnvelope<TData, TCode extends OperationCode, TCause extend
 };
 /** Success codes that carry response data (every success code but A1001). */
 export type OperationSuccessDataCode = Exclude<OperationSuccessCode, "A1001">;
-/** Arm (a): success with data — non-null data, null cause. */
+/** A success with data: `cause` is `null`. */
 export type OperationSuccessResponse<T> = OperationResponseEnvelope<T, OperationSuccessDataCode, null>;
-/** Arm (b): no-match success (A1001) — null data, null cause. */
+/** A success with no matching row (`A1001`): `data` and `cause` are `null`. */
 export type OperationNoMatchResponse = OperationResponseEnvelope<null, "A1001", null>;
-/** Arm (c): failure — null data, non-null cause. */
+/** A failure: `data` is `null` and `cause` says why. */
 export type OperationFailureResponse = OperationResponseEnvelope<null, OperationErrorCode, Cause>;
-export type OperationResponse<T = unknown> = OperationSuccessResponse<T> | OperationNoMatchResponse | OperationFailureResponse;
 /**
- * Builds the success-with-data arm. The only sanctioned way to construct
- * one: a runtime-computed `code` (e.g. from a table-driven outcome mapper)
- * still yields a well-typed {@link OperationSuccessResponse}.
+ * What an operation answers: success with data, a no-match success (`A1001`),
+ * or a failure with a cause.
  */
+export type OperationResponse<T = unknown> = OperationSuccessResponse<T> | OperationNoMatchResponse | OperationFailureResponse;
+/** Builds a success response with data. */
 export declare function operationSuccess<T>(data: T, code: OperationSuccessDataCode): OperationSuccessResponse<T>;
 /** Builds the no-match success arm (A1001). */
 export declare function operationNoMatch(): OperationNoMatchResponse;
-/**
- * Builds the failure arm. The only sanctioned way to construct one: a
- * runtime-computed error `code` still yields a well-typed
- * {@link OperationFailureResponse}.
- */
+/** Builds a failure response. */
 export declare function operationFailure(code: OperationErrorCode, cause: Cause): OperationFailureResponse;
 /** The one generic internal-failure text; every A3000 carries it. */
 export declare const INTERNAL_FAILURE_MESSAGE = "Internal framework error.";
-/**
- * The generic internal-failure envelope. Nothing about an internal failure is
- * caller-actionable, so every A3000 the framework emits is this exact value -
- * one constant rather than one restatement per boundary.
- */
+/** The response every internal failure (`A3000`) answers with. */
 export declare function internalFailure(): OperationFailureResponse;
 export {};