@aventara/client 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/emit/runtime.emitter.js

@@ -1,6 +1,7 @@
-import { OPERATION_CODES, VALIDATION_CODES } from "@aventara/core/internal";
+import { FRAMEWORK_ERROR_CLASS_OF, OPERATION_CODES, VALIDATION_CODES, } from "@aventara/core/internal";
 import { AvProtocol } from "@aventara/core/protocol";
 import { entrypointHref } from "../config/config.resolver.js";
+import { AVCLIENT_REGENERATE, } from "./banner.emitter.js";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
 import { wireGrammarLiteral } from "./scalar.codec.js";
 export function emitDecimalModule() {
@@ -14,7 +15,7 @@ export function emitDecimalModule() {
  * It holds the decimal string it was made from, digit for digit, and is sent as
  * that string. It does no arithmetic.
  */
-export class Decimal {
+export class AvDecimal {
 	readonly #value: string;
 
 	/** @throws TypeError when the value is not a decimal string. */
@@ -30,7 +31,7 @@ export class Decimal {
 		return this.#value;
 	}
 
-	/** The decimal string, exactly as given: what JSON.stringify writes for a Decimal. */
+	/** The decimal string, exactly as given: what JSON.stringify writes for an AvDecimal. */
 	toJSON(): string {
 		return this.#value;
 	}
@@ -51,51 +52,29 @@ export function emitMetadataModule(protocol, entrypoint) {
             `export const DEFAULT_ENTRYPOINT = ${JSON.stringify(entrypointHref(entrypoint))};\n`,
     };
 }
+function contractMismatchSummary(regenerate) {
+    return `This client was generated against a ClientContract other than the one the server serves. Regenerate it with ${regenerate}.`;
+}
 const FRAMEWORK_ERROR_CLASSES = {
-    AuthError: "The caller is not authenticated, or is not permitted to run the operation.",
-    ConflictError: "The operation conflicted with stored state, and nothing was written. A2008 fails the same way if sent again; A2013 and A2014 may succeed if sent again, and no retry is automatic.",
-    ContractMismatchError: "This client was generated against a ClientContract other than the one the server serves. Regenerate it with `avclient generate`.",
-    InternalError: "The server failed. Nothing in its cause is actionable; the diagnostics are in the server's logs.",
-    NotFoundError: "A strict unique target does not exist.",
-    ProtocolError: "The request was not one the server could route or interpret: an unknown Resource or operation, a protocol version it does not speak, or a body, media type, size or method it refuses.",
-    ValidationError: "The request broke a Contract rule: a field, type, capability, projection, reference or limit. The cause's issues say which, by code and path.",
-};
-const FRAMEWORK_ERROR_CLASS_OF = {
-    A2000: "ProtocolError",
-    A2001: "ProtocolError",
-    A2002: "ProtocolError",
-    A2003: "NotFoundError",
-    A2004: "ValidationError",
-    A2005: "ContractMismatchError",
-    A2006: "ProtocolError",
-    A2007: "ValidationError",
-    A2008: "ConflictError",
-    A2009: "ValidationError",
-    A2010: "ProtocolError",
-    A2011: "ProtocolError",
-    A2012: "ProtocolError",
-    A2013: "ConflictError",
-    A2014: "ConflictError",
-    A3000: "InternalError",
-    A3001: "InternalError",
-    A3002: "InternalError",
-    A3003: "InternalError",
-    A3004: "InternalError",
-    A4000: "AuthError",
-    A4001: "AuthError",
-    A4002: "AuthError",
+    AvAuthError: "The caller is not authenticated, or is not permitted to run the operation.",
+    AvConflictError: "The operation conflicted with stored state, and nothing was written. A2008 fails the same way if sent again; A2013 and A2014 may succeed if sent again, and no retry is automatic.",
+    AvContractMismatchError: contractMismatchSummary(AVCLIENT_REGENERATE),
+    AvInternalError: "The server failed. Nothing in its cause is actionable; the diagnostics are in the server's logs.",
+    AvNotFoundError: "A strict unique target does not exist.",
+    AvProtocolError: "The request was not one the server could route or interpret: an unknown Resource or operation, a protocol version it does not speak, or a body, media type, size or method it refuses.",
+    AvValidationError: "The request broke a Contract rule: a field, type, capability, projection, reference or limit. The cause's issues say which, by code and path.",
 };
-export const FRAMEWORK_ERROR_CLASS_NAMES = Object.keys(FRAMEWORK_ERROR_CLASSES);
+export const FRAMEWORK_ERROR_CLASS_NAMES = Object.keys(FRAMEWORK_ERROR_CLASSES).sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
 const ERROR_CODES = OPERATION_CODES.filter((code) => !code.startsWith("A1"));
 export function errorsModuleExports() {
     return [
         ...FRAMEWORK_ERROR_CLASS_NAMES,
-        "FrameworkError",
-        "TransportError",
-        "type Cause",
-        "type OperationCode",
-        "type ValidationCode",
-        "type ValidationIssue",
+        "AvError",
+        "AvTransportError",
+        "type AvCause",
+        "type AvOperationCode",
+        "type AvValidationCode",
+        "type AvValidationIssue",
     ].sort((left, right) => {
         const a = left.replace(/^type /, "");
         const b = right.replace(/^type /, "");
@@ -108,17 +87,24 @@ function codeArray(codes) {
 const ERRORS_MODULE_HEAD = `/**
  * The outcome codes and error classes of Aventara protocol version 1.
  *
- * A1xxx resolves; every other code throws the FrameworkError subclass of its
+ * A1xxx resolves; every other code throws the AvError subclass of its
  * class; a response that is not a framework envelope throws
- * TransportError. Branch on the class or on \`code\`, never on the message.
+ * AvTransportError. Branch on the class or on \`code\`, never on the message.
  */
 `;
 const ERRORS_MODULE_TYPES = `
 /** One actionable validation issue; \`path\` locates it in the request. */
-export interface ValidationIssue {
+export interface AvValidationIssue {
 	readonly path?: readonly (string | number)[];
-	readonly code: ValidationCode;
+	readonly code: AvValidationCode;
 	readonly message: string;
+	/**
+	 * The failed check's name (max_length, string_format, …): present, with
+	 * \`params\`, only on the issue of a failed field validator or Json Shape check.
+	 */
+	readonly check?: string;
+	/** That check's parameters, as the ClientContract states them ({ maximum: 80 }). */
+	readonly params?: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -126,26 +112,26 @@ export interface ValidationIssue {
  * a member the protocol does not define is never carried, so no stack, SQL or
  * server path the server should not have sent reaches it.
  */
-export interface Cause {
+export interface AvCause {
 	readonly message: string;
-	readonly issues?: readonly ValidationIssue[];
+	readonly issues?: readonly AvValidationIssue[];
 	/** The index of the failing operation in a transaction plan. */
 	readonly operation?: number;
 }
 
 /**
  * A framework outcome that throws: every code outside A1xxx. It is
- * always thrown as the subclass of its code's class; catch FrameworkError to
+ * always thrown as the subclass of its code's class; catch AvError to
  * catch them all.
  */
-export class FrameworkError<C extends OperationErrorCode = OperationErrorCode> extends Error {
-	override readonly name: string = "FrameworkError";
+export class AvError<C extends AvOperationErrorCode = AvOperationErrorCode> extends Error {
+	override readonly name: string = "AvError";
 	/** The outcome code. Branch on this, never on the message. */
 	readonly code: C;
 	/** The server's cause: its message, and its issues or failing operation when it gave them. */
-	override readonly cause: Cause;
+	override readonly cause: AvCause;
 
-	constructor(code: C, cause: Cause) {
+	constructor(code: C, cause: AvCause) {
 		super(cause.message);
 		this.code = code;
 		this.cause = cause;
@@ -155,12 +141,12 @@ export class FrameworkError<C extends OperationErrorCode = OperationErrorCode> e
 const ERRORS_MODULE_TAIL = `
 /**
  * A failure that never produced a framework envelope: no response
- * arrived, or the one that did is not an Aventara response envelope — a proxy's
- * HTML error page, a truncated body, JSON of another shape. It carries no
+ * arrived, or the one that did is not an Aventara response envelope (a proxy's
+ * HTML error page, a truncated body, JSON of another shape). It carries no
  * cause: nothing in such a response is the framework's to report.
  */
-export class TransportError extends Error {
-	override readonly name: string = "TransportError";
+export class AvTransportError extends Error {
+	override readonly name: string = "AvTransportError";
 	/** The HTTP status that arrived, or null when no response arrived at all. */
 	readonly status: number | null;
 
@@ -170,11 +156,15 @@ export class TransportError extends Error {
 	}
 }
 `;
-export function emitErrorsModule() {
-    const classes = Object.entries(FRAMEWORK_ERROR_CLASSES).map(([name, summary]) => {
+export function emitErrorsModule(regenerate = AVCLIENT_REGENERATE) {
+    const summaries = {
+        ...FRAMEWORK_ERROR_CLASSES,
+        AvContractMismatchError: contractMismatchSummary(regenerate),
+    };
+    const classes = Object.entries(summaries).map(([name, summary]) => {
         const codes = ERROR_CODES.filter((code) => FRAMEWORK_ERROR_CLASS_OF[code] === name);
         return (`\n/** ${summary} Thrown for ${codes.join(", ")}. */\n` +
-            `export class ${name} extends FrameworkError<${codes.map((code) => JSON.stringify(code)).join(" | ")}> {\n` +
+            `export class ${name} extends AvError<${codes.map((code) => JSON.stringify(code)).join(" | ")}> {\n` +
             `\toverride readonly name: string = ${JSON.stringify(name)};\n}\n`);
     });
     const table = ERROR_CODES.map((code) => `\t${code}: ${FRAMEWORK_ERROR_CLASS_OF[code]},\n`).join("");
@@ -184,32 +174,69 @@ export function emitErrorsModule() {
             "\n/** The outcome codes of the protocol, in allocation order. */\n" +
             `export const OPERATION_CODES = ${codeArray(OPERATION_CODES)};\n` +
             "\n/** An outcome code. */\n" +
-            "export type OperationCode = (typeof OPERATION_CODES)[number];\n" +
+            "export type AvOperationCode = (typeof OPERATION_CODES)[number];\n" +
             "\n/** An outcome code that throws: every code outside A1xxx. */\n" +
-            `export type OperationErrorCode = Exclude<OperationCode, \`A1\${string}\`>;\n` +
+            `export type AvOperationErrorCode = Exclude<AvOperationCode, \`A1\${string}\`>;\n` +
             "\n/** The validation codes of the protocol, in allocation order. */\n" +
             `export const VALIDATION_CODES = ${codeArray(VALIDATION_CODES)};\n` +
             "\n/** A validation code: what one issue in a cause is about. */\n" +
-            "export type ValidationCode = (typeof VALIDATION_CODES)[number];\n" +
+            "export type AvValidationCode = (typeof VALIDATION_CODES)[number];\n" +
             ERRORS_MODULE_TYPES +
             classes.join("") +
             ERRORS_MODULE_TAIL +
             "\nconst ERROR_CLASS_OF: {\n" +
-            "\treadonly [C in OperationErrorCode]: new (code: C, cause: Cause) => FrameworkError;\n" +
+            "\treadonly [C in AvOperationErrorCode]: new (code: C, cause: AvCause) => AvError;\n" +
             `} = {\n${table}};\n` +
-            "\n/** The FrameworkError subclass a failure envelope's code throws. */\n" +
-            "export function frameworkErrorOf<C extends OperationErrorCode>(code: C, cause: Cause): FrameworkError {\n" +
+            "\n/** The AvError subclass a failure envelope's code throws. */\n" +
+            "export function frameworkErrorOf<C extends AvOperationErrorCode>(code: C, cause: AvCause): AvError {\n" +
             "\tconst ErrorClass = ERROR_CLASS_OF[code];\n" +
             "\treturn new ErrorClass(code, cause);\n" +
             "}\n",
     };
 }
-export function emitTransportModule(style) {
+export function emitTransportModule(style, access = false) {
     return {
         path: "runtime/transport.ts",
-        source: transportModuleSource(moduleSpecifierWriter(style)),
+        source: transportModuleSource(moduleSpecifierWriter(style)) +
+            (access ? ASK_CAN_SOURCE : ""),
     };
 }
+const ASK_CAN_SOURCE = `
+/**
+ * Asks the policy every question in one request (\`POST /_access/can\`), each
+ * question's \`where\` in its wire forms, and resolves one boolean each, in order.
+ *
+ * @throws as {@link execute} does: the AvError subclass of a refusal (A2001 for a
+ *   Resource this client cannot reach, A2004 for a malformed question, A2009 past
+ *   the batch limit), AvTransportError when no framework envelope arrived.
+ */
+export async function askCan(
+	connection: TransportConnection,
+	questions: readonly unknown[],
+	options: AvCallOptions = {},
+): Promise<boolean[]> {
+	const operation = "$access.can";
+	if (!Array.isArray(questions)) {
+		throw new TypeError("$access.can takes a list of questions.");
+	}
+	const headers = requestHeaders(options);
+	const body = serializeWireBody({
+		questions: questions.map((question: unknown) =>
+			isRecord(question) && Object.hasOwn(question, "where")
+				? { ...question, where: encodeArguments(question["where"]) }
+				: question,
+		),
+	});
+	const response = await post(connection, "/_access/can", operation, headers, body, options);
+	return decoded(operation, response.status, () => {
+		const data: unknown = response.data;
+		if (!Array.isArray(data) || data.length !== questions.length || !data.every((answer) => typeof answer === "boolean")) {
+			throw new TypeError("The answer must hold one boolean per question.");
+		}
+		return data as boolean[];
+	});
+}
+`;
 const IDENTITY_HEADERS = (() => {
     const { protocolVersion, contractHash, requestId } = AvProtocol.headers;
     const prefix = protocolVersion.slice(0, protocolVersion.indexOf("-"));
@@ -227,26 +254,26 @@ const IDENTITY_HEADERS = (() => {
 })();
 function transportModuleSource(from) {
     return `import { CLIENT_CONTRACT_HASH, PROTOCOL_VERSION } from ${from("../metadata")};
-import { decodeResult, encodeArguments, readArgument, serializeWireBody } from ${from("./codec")};
+import { decodeResult, encodeArguments, readArgument, serializeWireBody, unsentValues } from ${from("./codec")};
 import { DECODE_TABLE } from ${from("./descriptor")};
 import {
-	type Cause,
+	type AvCause,
 	frameworkErrorOf,
 	OPERATION_CODES,
-	type OperationCode,
-	type OperationErrorCode,
-	TransportError,
+	type AvOperationCode,
+	type AvOperationErrorCode,
+	AvTransportError,
 	VALIDATION_CODES,
-	type ValidationCode,
-	type ValidationIssue,
+	type AvValidationCode,
+	type AvValidationIssue,
 } from ${from("./errors")};
 
 /**
  * The transport of Aventara protocol version 1: one POST per operation,
  * sent with the protocol version and ClientContract hash, its response
- * read by the protocol's rule — A1xxx resolves with the envelope's data, every other
- * code throws its FrameworkError subclass, and anything that is not a framework
- * envelope throws TransportError. No request is ever retried.
+ * read by the protocol's rule: A1xxx resolves with the envelope's data, every other
+ * code throws its AvError subclass, and anything that is not a framework
+ * envelope throws AvTransportError. No request is ever retried.
  *
  * # A stale client
  *
@@ -254,9 +281,9 @@ import {
  * regenerate. The server checks the identity this transport sends before it
  * routes, so a request under a stale hash, to an operation the deployment still
  * advertises or to one it no longer does, is answered 409 A2005, which throws
- * ContractMismatchError naming the remedy. A response that is not a framework
+ * AvContractMismatchError naming the remedy. A response that is not a framework
  * envelope, such as a host's own 404 for a path it does not mount, is a
- * TransportError and names no remedy, because nothing in it says this client is
+ * AvTransportError and names no remedy, because nothing in it says this client is
  * stale.
  */
 
@@ -270,7 +297,7 @@ const FRAMEWORK_HEADERS: Readonly<Record<string, string>> = {
 	[WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.contractHash)}]: CLIENT_CONTRACT_HASH,
 };
 
-/** The request id header: CallOptions.requestId sends it. */
+/** The request id header: AvCallOptions.requestId sends it. */
 const REQUEST_ID_HEADER = WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.requestId)};
 
 /** What the transport reads of an AbortSignal, where the consumer's lib declares none. */
@@ -292,16 +319,16 @@ export interface FetchResponse {
 	text(): Promise<string>;
 }
 
-/** The Fetch API as far as the transport calls it, where the consumer's lib declares none. */
+/** The AvFetch API as far as the transport calls it, where the consumer's lib declares none. */
 export type StructuralFetch = (url: string, init: FetchInit) => Promise<FetchResponse>;
 
 /**
  * The fetch this client calls: the consumer's own platform fetch type when
- * their lib declares one — DOM's, Node's — so the platform fetch is accepted
+ * their lib declares one (DOM's, Node's), so the platform fetch is accepted
  * without a cast, and the structural fetch above where it declares none. Read
  * through typeof globalThis, so this module names neither lib.
  */
-export type Fetch = typeof globalThis extends { readonly fetch: infer F } ? F : StructuralFetch;
+export type AvFetch = typeof globalThis extends { readonly fetch: infer F } ? F : StructuralFetch;
 
 /** The consumer's AbortSignal type when their lib declares one, else the structural signal. */
 export type PlatformSignal = typeof globalThis extends {
@@ -314,11 +341,11 @@ export type PlatformSignal = typeof globalThis extends {
 export interface TransportConnection {
 	/** The framework entrypoint, an absolute URL without a trailing slash. */
 	readonly entrypoint: string;
-	readonly fetch: Fetch;
+	readonly fetch: AvFetch;
 }
 
 /** Per-call options. Never serialized into the operation body. */
-export interface CallOptions {
+export interface AvCallOptions {
 	/** Aborts the request; the call rejects with what fetch rejected with. */
 	readonly signal?: PlatformSignal;
 	/** Extra request headers. The framework's own headers cannot be set here. */
@@ -330,19 +357,65 @@ export interface CallOptions {
 	readonly requestId?: string;
 }
 
-type SuccessCode = Exclude<OperationCode, OperationErrorCode>;
+type SuccessCode = Exclude<AvOperationCode, AvOperationErrorCode>;
 
 /** A framework envelope, read and checked, told apart by \`outcome\`. */
 type Envelope =
 	| { readonly outcome: "data"; readonly code: SuccessCode; readonly data: unknown }
-	| { readonly outcome: "failure"; readonly code: OperationErrorCode; readonly cause: Cause };
+	| { readonly outcome: "failure"; readonly code: AvOperationErrorCode; readonly cause: AvCause };
+
+/** What a refusal of an operation's arguments says. */
+const REFUSAL_MESSAGE = "Operation arguments failed framework validation.";
+
+/** What an undefined value the request would leave out is told. */
+const UNSENT_MESSAGE =
+	"Value must not be undefined: sent as JSON it would be left out, and the request would reach more rows.";
+
+/**
+ * Refuses arguments that hold an undefined value whose leaving out would reach more
+ * rows than the caller wrote (in a filter, a unique selector or a cursor, or a where,
+ * cursor, limit or offset left undefined), before anything is sent: JSON would drop
+ * it. Throws the AvValidationError (A2004) the server answers when it is handed such
+ * a value: one issue at each, with the server's code, its path under \`at\`
+ * (["arguments"] for a call, ["operations", i, "args"] for a plan step, whose index
+ * the cause names).
+ */
+export function refuseUnsentValues(
+	resource: string,
+	family: string,
+	variant: string,
+	args: unknown,
+	at: readonly (string | number)[],
+	operation?: number,
+): void {
+	const unsent = unsentValues(DECODE_TABLE, resource, family, variant, args);
+	if (unsent.length === 0) {
+		return;
+	}
+	const issues: readonly AvValidationIssue[] = Object.freeze(
+		unsent.map(({ path, code }) =>
+			Object.freeze({ path: Object.freeze([...at, ...path]), code, message: UNSENT_MESSAGE }),
+		),
+	);
+	throw frameworkErrorOf(
+		"A2004",
+		Object.freeze(
+			operation === undefined ? { message: REFUSAL_MESSAGE, issues } : { message: REFUSAL_MESSAGE, issues, operation },
+		),
+	);
+}
 
 /**
  * Runs one operation: POSTs its arguments and settles its envelope.
  *
- * @returns the envelope's data when the code is A1xxx — null for A1001.
- * @throws the FrameworkError subclass of any other code; TransportError when no
- *   framework envelope arrived; TypeError, before anything is sent, when the
+ * @param check the client's own checks of the arguments, run before anything is sent
+ *   (the ClientContract's field validators, when it has any).
+ * @returns the envelope's data when the code is A1xxx; null for A1001.
+ * @throws the AvError subclass of any other code; AvTransportError when no
+ *   framework envelope arrived; AvValidationError (A2004), before anything is sent,
+ *   when the arguments hold an undefined value JSON would leave out to widen the
+ *   request (see refuseUnsentValues), or when
+ *   \`check\` refuses the arguments; TypeError, before anything is sent, when the
  *   arguments are not a JSON-safe object or a request header is the framework's.
  *   A caller's abort rejects with what fetch rejected with.
  */
@@ -352,8 +425,11 @@ export async function execute(
 	family: string,
 	variant: string,
 	args: Readonly<Record<string, unknown>>,
-	options: CallOptions = {},
+	options: AvCallOptions = {},
+	check?: (resource: string, family: string, args: unknown) => void,
 ): Promise<unknown> {
+	refuseUnsentValues(resource, family, variant, args, ["arguments"]);
+	check?.(resource, family, args);
 	const operation = JSON.stringify(resource) + " " + family + "." + variant;
 	const headers = requestHeaders(options);
 	const body = serializeWireBody(encodeArguments(argumentObject(args)));
@@ -368,13 +444,13 @@ export async function execute(
  * by its own operation's Resource (\`resources\`, in plan order).
  *
  * @throws as {@link execute} does; a rolled-back plan throws its failing
- *   operation's FrameworkError subclass, its cause naming the operation.
+ *   operation's AvError subclass, its cause naming the operation.
  */
 export async function executePlan(
 	connection: TransportConnection,
 	plan: { readonly operations: readonly unknown[] },
 	resources: readonly string[],
-	options: CallOptions = {},
+	options: AvCallOptions = {},
 ): Promise<unknown[]> {
 	const operation = "the transaction";
 	const headers = requestHeaders(options);
@@ -395,7 +471,7 @@ async function post(
 	operation: string,
 	headers: Readonly<Record<string, string>>,
 	body: string,
-	options: CallOptions,
+	options: AvCallOptions,
 ): Promise<{ readonly status: number; readonly data: unknown }> {
 	const url = connection.entrypoint + path;
 	const init: FetchInit =
@@ -412,7 +488,7 @@ async function post(
 		if (options.signal?.aborted === true) {
 			throw error;
 		}
-		throw new TransportError("The request for " + operation + " failed before any response arrived.", null);
+		throw new AvTransportError("The request for " + operation + " failed before any response arrived.", null);
 	}
 	let text: string;
 	try {
@@ -421,7 +497,7 @@ async function post(
 		if (options.signal?.aborted === true) {
 			throw error;
 		}
-		throw new TransportError(
+		throw new AvTransportError(
 			"The response to " + operation + " (HTTP " + response.status + ") could not be read.",
 			response.status,
 		);
@@ -430,14 +506,14 @@ async function post(
 }
 
 /**
- * The decoded data, or — a scalar in \`data\` that does not decode, inside an
- * otherwise valid envelope — a TransportError.
+ * The decoded data, or an AvTransportError when a scalar in \`data\` does not
+ * decode inside an otherwise valid envelope.
  */
 function decoded<T>(operation: string, status: number, decode: () => T): T {
 	try {
 		return decode();
 	} catch (error) {
-		throw new TransportError(
+		throw new AvTransportError(
 			"The response to " + operation + " (HTTP " + status + ") holds a value this client cannot read: " +
 				(error instanceof Error ? error.message : String(error)),
 			status,
@@ -448,14 +524,14 @@ function decoded<T>(operation: string, status: number, decode: () => T): T {
 /**
  * Settles one response by the protocol's rule: the envelope's data, still in wire form,
  * which the caller decodes by the decode table.
- * A scalar in \`data\` that fails to decode, inside an otherwise valid envelope, throws TransportError
- * — not a FrameworkError, because the server reported no failure; the response is
- * one this client cannot read, which is what TransportError means.
+ * A scalar in \`data\` that fails to decode, inside an otherwise valid envelope, throws AvTransportError.
+ * It is no AvError, because the server reported no failure: the response is one
+ * this client cannot read, which is what AvTransportError means.
  */
 function settle(operation: string, status: number, text: string): unknown {
 	const envelope = envelopeOf(parseJson(text));
 	if (envelope === undefined) {
-		throw new TransportError(
+		throw new AvTransportError(
 			"The response to " + operation + " (HTTP " + status + ") is not an Aventara response envelope.",
 			status,
 		);
@@ -466,7 +542,7 @@ function settle(operation: string, status: number, text: string): unknown {
 	return envelope.data;
 }
 
-/** The parsed body, or undefined — which no envelope is — when it is not JSON. */
+/** The parsed body, or undefined (which no envelope is) when it is not JSON. */
 function parseJson(text: string): unknown {
 	try {
 		return JSON.parse(text);
@@ -479,15 +555,15 @@ function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function isOperationCode(value: unknown): value is OperationCode {
+function isOperationCode(value: unknown): value is AvOperationCode {
 	return OPERATION_CODES.some((code) => code === value);
 }
 
-function isValidationCode(value: unknown): value is ValidationCode {
+function isValidationCode(value: unknown): value is AvValidationCode {
 	return VALIDATION_CODES.some((code) => code === value);
 }
 
-function isSuccessCode(code: OperationCode): code is SuccessCode {
+function isSuccessCode(code: AvOperationCode): code is SuccessCode {
 	return code.startsWith("A1");
 }
 
@@ -511,9 +587,9 @@ function envelopeOf(body: unknown): Envelope | undefined {
 /**
  * The cause rebuilt from the members the protocol defines, or undefined when one of them
  * is malformed. Every other member is dropped, so whatever else a server put in
- * its cause — a stack, SQL, a file path — is never carried into a thrown error.
+ * its cause (a stack, SQL, a file path) is never carried into a thrown error.
  */
-function causeOf(value: unknown): Cause | undefined {
+function causeOf(value: unknown): AvCause | undefined {
 	if (!isRecord(value)) {
 		return undefined;
 	}
@@ -523,12 +599,12 @@ function causeOf(value: unknown): Cause | undefined {
 	if (typeof message !== "string") {
 		return undefined;
 	}
-	let cause: Cause = { message };
+	let cause: AvCause = { message };
 	if (issues !== undefined) {
 		if (!Array.isArray(issues)) {
 			return undefined;
 		}
-		const rebuilt: ValidationIssue[] = [];
+		const rebuilt: AvValidationIssue[] = [];
 		for (const issue of issues) {
 			const copy = issueOf(issue);
 			if (copy === undefined) {
@@ -547,18 +623,30 @@ function causeOf(value: unknown): Cause | undefined {
 	return Object.freeze(cause);
 }
 
-function issueOf(value: unknown): ValidationIssue | undefined {
+/**
+ * One issue rebuilt from the members the protocol defines (its path, code and
+ * message, and a failed check's name and parameters), or undefined when one of
+ * them is malformed.
+ */
+function issueOf(value: unknown): AvValidationIssue | undefined {
 	if (!isRecord(value)) {
 		return undefined;
 	}
 	const path = value["path"];
 	const code = value["code"];
 	const message = value["message"];
+	const check = value["check"];
+	const params = value["params"];
 	if (!isValidationCode(code) || typeof message !== "string") {
 		return undefined;
 	}
+	const checked = check === undefined && params === undefined;
+	if (!checked && (typeof check !== "string" || !isRecord(params))) {
+		return undefined;
+	}
+	const failed = checked ? {} : { check: check as string, params: frozen(params) as Readonly<Record<string, unknown>> };
 	if (path === undefined) {
-		return Object.freeze({ code, message });
+		return Object.freeze({ code, message, ...failed });
 	}
 	if (!Array.isArray(path)) {
 		return undefined;
@@ -570,7 +658,18 @@ function issueOf(value: unknown): ValidationIssue | undefined {
 		}
 		segments.push(segment);
 	}
-	return Object.freeze({ path: Object.freeze(segments), code, message });
+	return Object.freeze({ path: Object.freeze(segments), code, message, ...failed });
+}
+
+/** A parsed JSON value, frozen at every depth. */
+function frozen(value: unknown): unknown {
+	if (typeof value === "object" && value !== null) {
+		for (const member of Object.values(value)) {
+			frozen(member);
+		}
+		Object.freeze(value);
+	}
+	return value;
 }
 
 /** The arguments, refused unless they are an object: the body is always one. */
@@ -586,7 +685,7 @@ function argumentObject(args: unknown): unknown {
  * the framework's; then requestId, which overwrites any request id header the
  * caller set.
  */
-function requestHeaders(options: CallOptions): Record<string, string> {
+function requestHeaders(options: AvCallOptions): Record<string, string> {
 	const headers: Record<string, string> = { ...FRAMEWORK_HEADERS };
 	const owned = new Set(Object.keys(FRAMEWORK_HEADERS).map((name) => name.toLowerCase()));
 	for (const [name, value] of Object.entries(options.headers ?? {})) {

package/dist/emit/scalar.codec.d.ts

@@ -3,7 +3,7 @@ import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 export declare function wireGrammarLiteral(scalar: keyof typeof AvProtocol.scalarFormats): string;
 /**
- * `runtime/codec.ts`: the `BuiltInScalar` union and the codec table in core's
+ * `runtime/codec.ts`: the `AvBuiltInScalar` union and the codec table in core's
  * `BUILT_IN_SCALARS` order, the helpers the codecs share, and the three
  * functions the generated transport calls. Nothing here is re-exported from the
  * tree's `AvClient.ts`: the codec is the runtime's, not the consumer's.