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

package/dist/emit/scalar.codec.js

@@ -1,4 +1,4 @@
-import { BUILT_IN_SCALARS } from "@aventara/core";
+import { BUILT_IN_SCALARS } from "@aventara/core/internal";
 import { AvProtocol } from "@aventara/core/protocol";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
 export function wireGrammarLiteral(scalar) {
@@ -29,7 +29,7 @@ const SCALAR_CODEC_SOURCES = {
 				: refuse("bigint", "wire", "a base-10 integer string")`,
     },
     decimal: {
-        encode: `(value) => (value instanceof Decimal ? value.toString() : refuse("decimal", "runtime", "a Decimal"))`,
+        encode: `(value) => (value instanceof AvDecimal ? value.toString() : refuse("decimal", "runtime", "an AvDecimal"))`,
         decode: "decodeDecimal",
     },
     datetime: {
@@ -48,13 +48,13 @@ const SCALAR_CODEC_SOURCES = {
     },
 };
 function codecModuleHead(from) {
-    return `import { Decimal } from ${from("./decimal")};
+    return `import { AvDecimal } from ${from("./decimal")};
 import type { FieldDecoding } from ${from("./descriptor")};
 
 /**
  * The scalar codecs of Aventara protocol version 1: one per built-in
  * scalar, converting between the generated runtime value and the JSON wire value.
- * A value is never wrapped per field — the Contract names the scalar, so the
+ * A value is never wrapped per field: the Contract names the scalar, so the
  * caller says which scalar a value is.
  *
  * null is explicit in both directions and passes through; whether a field admits
@@ -82,7 +82,7 @@ const DATETIME_WIRE = ${wireGrammarLiteral("datetime")};
 const BASE64_WIRE = ${wireGrammarLiteral("bytes")};
 const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
-function refuse(scalar: BuiltInScalar, side: Side, expected: string): never {
+function refuse(scalar: AvBuiltInScalar, side: Side, expected: string): never {
 	throw new TypeError('A "' + scalar + '" ' + side + " value must be " + expected + ".");
 }
 
@@ -94,10 +94,10 @@ function isFiniteNumber(value: unknown): value is number {
 	return typeof value === "number" && Number.isFinite(value);
 }
 
-function decodeDecimal(wire: unknown): Decimal {
+function decodeDecimal(wire: unknown): AvDecimal {
 	if (typeof wire === "string") {
 		try {
-			return new Decimal(wire);
+			return new AvDecimal(wire);
 		} catch {
 			// Refused below, naming the scalar.
 		}
@@ -195,8 +195,8 @@ function kindOf(value: unknown): string {
 	if (value instanceof Uint8Array) {
 		return "a Uint8Array";
 	}
-	if (value instanceof Decimal) {
-		return "a Decimal";
+	if (value instanceof AvDecimal) {
+		return "an AvDecimal";
 	}
 	if (typeof value === "object" && value !== null && isPlainRecord(value)) {
 		return "a symbol-keyed property";
@@ -288,7 +288,7 @@ function writeWireJson(value: unknown, path: Path, ancestors: Set<object>): stri
 	return text;
 }
 
-function codecOf(scalar: BuiltInScalar): ScalarCodec {
+function codecOf(scalar: AvBuiltInScalar): ScalarCodec {
 	if (!Object.hasOwn(SCALAR_CODECS, scalar)) {
 		throw new TypeError('"' + String(scalar) + '" is not a built-in scalar of this protocol version.');
 	}
@@ -296,21 +296,21 @@ function codecOf(scalar: BuiltInScalar): ScalarCodec {
 }
 
 /** The JSON wire value of a scalar's runtime value; null passes through. */
-export function encodeScalar(scalar: BuiltInScalar, value: unknown): unknown {
+export function encodeScalar(scalar: AvBuiltInScalar, value: unknown): unknown {
 	const codec = codecOf(scalar);
 	return value === null ? null : codec.encode(value);
 }
 
 /** The runtime value of a scalar's JSON wire value; null passes through. */
-export function decodeScalar(scalar: BuiltInScalar, wire: unknown): unknown {
+export function decodeScalar(scalar: AvBuiltInScalar, wire: unknown): unknown {
 	const codec = codecOf(scalar);
 	return wire === null ? null : codec.decode(wire);
 }
 
 /**
  * The JSON text of a request body whose scalars are already encoded. Every
- * undefined property is stripped, at every depth — an optional property is
- * omitted, never sent — and null is kept as the explicit value it is.
+ * undefined property is stripped, at every depth (an optional property is
+ * omitted, never sent), and null is kept as the explicit value it is.
  * Anything else that is not JSON-safe is refused rather than coerced: it means a
  * value escaped its scalar codec.
  */
@@ -321,8 +321,8 @@ export function serializeWireBody(body: unknown): string {
 /**
  * An operation's arguments with every scalar in its wire form, read off each
  * value's runtime class: a
- * bigint, a Date, a Decimal or a Uint8Array is encoded wherever it stands — a
- * filter operand, a data value, a cursor — and plain objects and arrays are
+ * bigint, a Date, an AvDecimal or a Uint8Array is encoded wherever it stands (a
+ * filter operand, a data value, a cursor), and plain objects and arrays are
  * walked. Every other value is left for serializeWireBody, which refuses what is
  * not JSON-safe. A json value cannot hold one of the four classes (the types
  * exclude them), so nothing inside one is ever re-read as a scalar.
@@ -331,31 +331,74 @@ export function encodeArguments(value: unknown): unknown {
 	return encodeValue(value, [], new Set());
 }
 
-function encodeValue(value: unknown, path: Path, ancestors: Set<object>): unknown {
-	if (typeof value === "bigint") {
-		return encodeScalar("bigint", value);
+/**
+ * One read of a caller's arguments. Every native read on them happens through it,
+ * here and in the transaction builder, so a value that cannot be read (a revoked
+ * Proxy such as an Immer draft after produce, a throwing getter or trap) is refused at its
+ * path with a TypeError before anything is sent, never with the engine's own error.
+ */
+export function readArgument<T>(path: Path, read: () => T): T {
+	try {
+		return read();
+	} catch {
+		throw new TypeError(
+			"An operation's arguments must be readable plain data, and the value at " + pointerOf(path) + " could not be read.",
+		);
 	}
+}
+
+/** How encodeValue treats an object: a scalar's runtime class, a container, or neither. */
+function objectKind(value: object): "datetime" | "decimal" | "bytes" | "container" | "other" {
 	if (value instanceof Date) {
-		return encodeScalar("datetime", value);
+		return "datetime";
 	}
-	if (value instanceof Decimal) {
-		return encodeScalar("decimal", value);
+	if (value instanceof AvDecimal) {
+		return "decimal";
 	}
 	if (value instanceof Uint8Array) {
-		return encodeScalar("bytes", value);
+		return "bytes";
 	}
-	if (typeof value !== "object" || value === null || !isJsonContainer(value)) {
+	return isJsonContainer(value) ? "container" : "other";
+}
+
+function encodeValue(value: unknown, path: Path, ancestors: Set<object>): unknown {
+	if (typeof value === "bigint") {
+		return encodeScalar("bigint", value);
+	}
+	if (typeof value !== "object" || value === null) {
+		return value;
+	}
+	const kind = readArgument(path, () => objectKind(value));
+	if (kind === "other") {
 		return value;
 	}
+	if (kind !== "container") {
+		return encodeScalar(kind, value);
+	}
 	if (ancestors.has(value)) {
 		return refuseBody(path, "a cycle");
 	}
 	ancestors.add(value);
-	const copy = Array.isArray(value)
-		? value.map((item, index) => encodeValue(item, [...path, index], ancestors))
-		: Object.fromEntries(
-				Object.entries(value).map(([key, member]) => [key, encodeValue(member, [...path, key], ancestors)]),
-			);
+	let copy: unknown;
+	if (readArgument(path, () => Array.isArray(value))) {
+		const items = value as readonly unknown[];
+		const length = readArgument(path, () => items.length);
+		const list: unknown[] = [];
+		for (let index = 0; index < length; index += 1) {
+			const itemPath = [...path, index];
+			list.push(encodeValue(readArgument(itemPath, () => items[index]), itemPath, ancestors));
+		}
+		copy = list;
+	} else {
+		const record = value as Readonly<Record<string, unknown>>;
+		const members: [string, unknown][] = [];
+		for (const key of readArgument(path, () => Object.keys(record))) {
+			const memberPath = [...path, key];
+			members.push([key, encodeValue(readArgument(memberPath, () => record[key]), memberPath, ancestors)]);
+		}
+		// fromEntries defines each key, so "__proto__" stays an own key.
+		copy = Object.fromEntries(members);
+	}
 	ancestors.delete(value);
 	return copy;
 }
@@ -370,13 +413,13 @@ export type DecodeTable = {
  * table: a number (a count), null, and the data of a Resource the table
  * does not name pass through; a list is a list of
  * records, anything else is one record of \`resource\`. In a record, a field the
- * table names is revived — each item of a list field — a relation recurses with
+ * table names is revived (each item of a list field), a relation recurses with
  * its target, and every other key passes through untouched: json is never
  * revived. A to-many relation's value is a list, \`{ data, count }\` or
- * \`{ count }\` — the three shapes the derivation gives it.
+ * \`{ count }\`, the three shapes the derivation gives it.
  *
- * @throws TypeError when a value is not the wire form its field's scalar takes —
- *   which the transport answers as a TransportError.
+ * @throws TypeError when a value is not the wire form its field's scalar takes,
+ *   which the transport answers as an AvTransportError.
  */
 export function decodeResult(table: DecodeTable, resource: string, value: unknown): unknown {
 	// A Resource the table does not name has nothing to revive: its data passes.
@@ -434,9 +477,9 @@ export function emitScalarCodecModule(style) {
         path: "runtime/codec.ts",
         source: codecModuleHead(moduleSpecifierWriter(style)) +
             "\n/** The built-in scalars of the protocol. */\n" +
-            `export type BuiltInScalar =\n${union};\n` +
+            `export type AvBuiltInScalar =\n${union};\n` +
             CODEC_MODULE_BODY +
-            "\nconst SCALAR_CODECS: { readonly [S in BuiltInScalar]: ScalarCodec } = {\n" +
+            "\nconst SCALAR_CODECS: { readonly [S in AvBuiltInScalar]: ScalarCodec } = {\n" +
             `${table}\n};\n`,
     };
 }

package/dist/emit/transaction.emitter.js

@@ -24,8 +24,8 @@ export interface FingerprintNode {
 }
 
 /**
- * The node's fingerprint, or null when its arguments are not canonical JSON — a
- * lone surrogate, a non-finite number — exactly when core cannot compute one
+ * The node's fingerprint, or null when its arguments are not canonical JSON (a
+ * lone surrogate, a non-finite number), exactly when core cannot compute one
  * either; the server then answers the operation itself.
  */
 export function fingerprintOf(node: FingerprintNode): string | null {
@@ -209,25 +209,29 @@ function base64Url(bytes: Uint8Array): string {
 }
 `;
 function transactionModuleSource(from) {
-    return `import { encodeArguments, serializeWireBody } from ${from("./codec")};
-import { type Cause, type FrameworkError, frameworkErrorOf } from ${from("./errors")};
+    return `import { encodeArguments, readArgument, serializeWireBody } from ${from("./codec")};
+import { type AvCause, type AvError, frameworkErrorOf } from ${from("./errors")};
 import { fingerprintOf } from ${from("./fingerprint")};
-import { type CallOptions, executePlan, type TransportConnection } from ${from("./transport")};
+import { type AvCallOptions, executePlan, type TransportConnection } from ${from("./transport")};
 
 /**
  * The deferred transaction builder and runner: \`avClient.tx\` defers an operation
- * into a handle — pure data, no request — and \`avClient.transaction\` binds a
+ * into a handle (pure data, no request), and \`avClient.transaction\` binds a
  * list of handles into one transaction plan, sends it once, and resolves one
  * result per handle in list order. A handle has no connection, so any client of
  * this generated tree may run it.
  */
 
-/** What a handle defers. */
+/**
+ * What a handle defers, or why its arguments could not be read: the builder
+ * never throws into app code, and running the handle refuses it instead.
+ */
 interface DeferredRecord {
 	readonly resource: string;
 	readonly family: string;
 	readonly variant: string;
 	readonly args: unknown;
+	readonly unreadable?: TypeError;
 }
 
 /** What a \`$ref\` placeholder stands for until the plan is assembled. */
@@ -236,8 +240,6 @@ interface Placeholder {
 	readonly field: string;
 }
 
-type MutableRecord = Record<string, unknown>;
-
 /** One wire node of a transaction plan, its arguments in wire form. */
 interface PlanNode {
 	readonly resource: string;
@@ -247,10 +249,11 @@ interface PlanNode {
 	readonly fingerprint: string | null;
 }
 
-/** One reference container: a mutation-data record and its path inside the arguments. */
-interface Container {
+/** One placeholder an argument tree holds: where, the object itself, and its meaning. */
+interface PlaceholderSite {
 	readonly path: readonly (string | number)[];
-	readonly record: Readonly<Record<string, unknown>>;
+	readonly object: object;
+	readonly placeholder: Placeholder;
 }
 
 const HANDLES = new WeakMap<object, DeferredRecord>();
@@ -264,45 +267,73 @@ function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown
 	return prototype === Object.prototype || prototype === null;
 }
 
-/** The argument keys holding reference positions: the top-level mutation data. */
-function referenceKeys(family: string): readonly string[] {
-	return family === "create" || family === "update" ? ["data"] : family === "upsert" ? ["create", "update"] : [];
-}
+const KEEP: unique symbol = Symbol("keep");
 
-function containers(family: string, args: unknown): readonly Container[] {
-	if (!isPlainRecord(args)) {
-		return [];
+/**
+ * Rebuilds an argument tree: every plain record and array is copied, every other
+ * value kept, and \`leaf\` may replace any value first (a placeholder, by identity).
+ * A placeholder is bound wherever the arguments hold one; the server answers a
+ * position that takes no reference. A container met again on its own ancestry is
+ * kept as it is; the codec refuses it.
+ */
+function rebuild(
+	value: unknown,
+	path: readonly (string | number)[],
+	leaf: (value: unknown, path: readonly (string | number)[]) => unknown,
+	ancestors: Set<object> = new Set(),
+): unknown {
+	const replaced = leaf(value, path);
+	if (replaced !== KEEP || typeof value !== "object" || value === null) {
+		return replaced === KEEP ? value : replaced;
+	}
+	const array = readArgument(path, () => Array.isArray(value));
+	if ((!array && !readArgument(path, () => isPlainRecord(value))) || ancestors.has(value)) {
+		return value;
 	}
-	return referenceKeys(family).flatMap((key): Container[] => {
-		const value = args[key];
-		if (Array.isArray(value)) {
-			return value.flatMap((entry: unknown, index) => (isPlainRecord(entry) ? [{ path: [key, index], record: entry }] : []));
+	ancestors.add(value);
+	let copy: unknown;
+	if (array) {
+		const items = value as readonly unknown[];
+		const length = readArgument(path, () => items.length);
+		const list: unknown[] = [];
+		for (let index = 0; index < length; index += 1) {
+			const itemPath = [...path, index];
+			list.push(rebuild(readArgument(itemPath, () => items[index]), itemPath, leaf, ancestors));
 		}
-		return isPlainRecord(value) ? [{ path: [key], record: value }] : [];
-	});
+		copy = list;
+	} else {
+		const record = value as Readonly<Record<string, unknown>>;
+		const members: [string, unknown][] = [];
+		for (const key of readArgument(path, () => Object.keys(record))) {
+			const memberPath = [...path, key];
+			members.push([key, rebuild(readArgument(memberPath, () => record[key]), memberPath, leaf, ancestors)]);
+		}
+		copy = Object.fromEntries(members);
+	}
+	ancestors.delete(value);
+	return copy;
 }
 
-/** \`args\` with each reference container replaced by \`rebuild\`, cloning only the containing path. */
-function replaceContainers(family: string, args: unknown, rebuild: (container: Container) => MutableRecord): unknown {
-	if (!isPlainRecord(args)) {
-		return args;
-	}
-	const result: MutableRecord = { ...args };
-	for (const key of referenceKeys(family)) {
-		const value = args[key];
-		if (Array.isArray(value)) {
-			result[key] = value.map((entry: unknown, index) => (isPlainRecord(entry) ? rebuild({ path: [key, index], record: entry }) : entry));
-		} else if (isPlainRecord(value)) {
-			result[key] = rebuild({ path: [key], record: value });
+/** Every placeholder \`args\` holds, with its path inside the arguments. */
+function placeholderSites(args: unknown): readonly PlaceholderSite[] {
+	const sites: PlaceholderSite[] = [];
+	rebuild(args, [], (value, path) => {
+		const placeholder = typeof value === "object" && value !== null ? PLACEHOLDERS.get(value) : undefined;
+		if (placeholder === undefined) {
+			return KEEP;
 		}
-	}
-	return result;
+		sites.push({ path, object: value as object, placeholder });
+		return value;
+	});
+	return sites;
 }
 
 /**
- * Defers one operation into a handle: nothing is sent. Its reference
- * containers are copied now, so a later change to the caller's data cannot move
- * a reference — and a handle can reference only handles built before it.
+ * Defers one operation into a handle: nothing is sent, and nothing is thrown.
+ * Its arguments are copied now, so a later change to the caller's data cannot
+ * move a reference, and a handle can reference only handles built before it.
+ * Arguments that cannot be read are kept as their refusal, which running the
+ * handle rejects with.
  */
 export function deferOperation(resource: string, family: string, variant: string, args: unknown): object {
 	const handle: object = Object.freeze({
@@ -312,37 +343,55 @@ export function deferOperation(resource: string, family: string, variant: string
 			return placeholder;
 		},
 	});
-	HANDLES.set(handle, {
-		resource,
-		family,
-		variant,
-		args: replaceContainers(family, args, ({ record }) => ({ ...record })),
-	});
+	let record: DeferredRecord;
+	try {
+		record = {
+			resource,
+			family,
+			variant,
+			args: rebuild(args, [], (value) => (typeof value === "object" && value !== null && PLACEHOLDERS.has(value) ? value : KEEP)),
+		};
+	} catch (error) {
+		// Only readArgument throws here: an argument that could not be read.
+		record = { resource, family, variant, args: {}, unreadable: error as TypeError };
+	}
+	HANDLES.set(handle, record);
 	return handle;
 }
 
 /** What core answers in process for a plan entry it cannot run (A2004 / V1001). */
-function entryRefusal(operation: number, message: string): FrameworkError {
-	const cause: Cause = {
+function entryRefusal(operation: number, message: string): AvError {
+	const cause: AvCause = {
 		message: "Transaction plan failed framework validation.",
-		issues: [{ path: ["operation"], code: "V1001", message }],
+		issues: [{ path: ["operations", operation], code: "V1001", message }],
 		operation,
 	};
 	return frameworkErrorOf("A2004", cause);
 }
 
+/**
+ * The checks a plan's steps run before it is sent (the ClientContract's field
+ * validators, when it has any). Throws the AvError the server would answer.
+ */
+export type PlanCheck = (
+	steps: readonly { readonly resource: string; readonly family: string; readonly args: unknown }[],
+) => void;
+
 /**
  * Binds \`steps\` into the plan, sends it once, and resolves one decoded result per
  * step. Refused before anything is sent, with what core answers in
  * process: a list that is not one, an entry that is not a handle of this
- * generated client, one handle twice (ValidationError A2004 / V1001 at
- * ["operation"]); a reference to a handle not in the list (ValidationError A2007 /
- * V1010 at its \`$ref\`).
+ * generated client, one handle twice (AvValidationError A2004 / V1001 at
+ * ["operations", i]: the entry itself); a reference to a handle not in the list (AvValidationError A2007 /
+ * V1010 at its \`$ref\`); a handle whose arguments could not be read when it was
+ * built (the TypeError naming where); and, when \`check\` is given, a step whose
+ * values break a field check (AvValidationError A2004, as the server answers it).
  */
 export async function runTransaction(
 	connection: TransportConnection,
 	steps: unknown,
-	options: CallOptions = {},
+	options: AvCallOptions = {},
+	check?: PlanCheck,
 ): Promise<unknown[]> {
 	if (!Array.isArray(steps)) {
 		throw frameworkErrorOf("A2004", {
@@ -364,29 +413,31 @@ export async function runTransaction(
 		records.push(record);
 	}
 	for (const [index, record] of records.entries()) {
-		for (const { path, record: container } of containers(record.family, record.args)) {
-			for (const [field, value] of Object.entries(container)) {
-				const placeholder = typeof value === "object" && value !== null ? PLACEHOLDERS.get(value) : undefined;
-				if (placeholder !== undefined && !positions.has(placeholder.source)) {
-					throw frameworkErrorOf("A2007", {
-						message: "Operation arguments failed framework validation.",
-						issues: [
-							{
-								path: ["operations", index, "args", ...path, field, "$ref"],
-								code: "V1010",
-								message: "Transaction reference names an operation that is not in this transaction.",
-							},
-						],
-						operation: index,
-					});
-				}
+		if (record.unreadable !== undefined) {
+			throw record.unreadable;
+		}
+		for (const { path, placeholder } of placeholderSites(record.args)) {
+			if (!positions.has(placeholder.source)) {
+				throw frameworkErrorOf("A2007", {
+					message: "Operation arguments failed framework validation.",
+					issues: [
+						{
+							path: ["operations", index, "args", ...path, "$ref"],
+							code: "V1010",
+							message: "Transaction reference names an operation that is not in this transaction.",
+						},
+					],
+					operation: index,
+				});
 			}
 		}
 	}
 
+	check?.(records);
+
 	// Bound lazily: a node's references need their source's
 	// fingerprint, so each node is built once, on first need, wherever its source
-	// stands in the list — the server, not this client, refuses a later one.
+	// stands in the list. The server, not this client, refuses a later one.
 	const nodes = new Map<number, PlanNode>();
 	const nodeAt = (index: number): PlanNode => {
 		const built = nodes.get(index);
@@ -394,17 +445,14 @@ export async function runTransaction(
 			return built;
 		}
 		const record = records[index] as DeferredRecord;
-		const bound = replaceContainers(record.family, record.args, ({ record: container }) => {
-			const copy: MutableRecord = { ...container };
-			for (const [field, value] of Object.entries(container)) {
-				const placeholder = typeof value === "object" && value !== null ? PLACEHOLDERS.get(value) : undefined;
-				if (placeholder !== undefined) {
-					const operation = positions.get(placeholder.source) as number;
-					copy[field] = { $ref: { operation, fingerprint: nodeAt(operation).fingerprint, path: [placeholder.field] } };
-				}
-			}
-			return copy;
-		});
+		const references = new Map<object, unknown>();
+		for (const { object, placeholder } of placeholderSites(record.args)) {
+			const operation = positions.get(placeholder.source) as number;
+			references.set(object, { $ref: { operation, fingerprint: nodeAt(operation).fingerprint, path: [placeholder.field] } });
+		}
+		const bound = rebuild(record.args, [], (value) =>
+			typeof value === "object" && value !== null && references.has(value) ? references.get(value) : KEEP,
+		);
 		const args: unknown = JSON.parse(serializeWireBody(encodeArguments(bound)));
 		const node: PlanNode = {
 			resource: record.resource,

package/dist/generate.d.ts

@@ -1,6 +1,6 @@
 import type { AbsolutePath } from "./config/client-config.interface.js";
 import { type ProcessEnvInput } from "./config/env.cascade.js";
-import type { ContractFetch } from "./contract/contract.fetcher.js";
+import { type ContractFetch } from "./contract/contract.fetcher.js";
 import { type EmittedFilePath } from "./emit/emitted-tree.interface.js";
 import type { OutputCheck, TypeScriptResolver } from "./output/output.validator.js";
 export interface ClientGenerationInput {
@@ -17,7 +17,15 @@ export interface ClientGenerationInput {
     readonly overrideForeign?: boolean;
     readonly fetch?: ContractFetch;
     readonly resolveTypeScript?: TypeScriptResolver;
+    /**
+     * Runs each of the run's four phases — the config, the contract, the
+     * emission, the write — under a title, so whoever owns the terminal can show
+     * them (`cli/step.reporter.ts`); each phase simply runs when omitted.
+     */
+    readonly step?: GenerationStep;
 }
+/** Runs one phase of a generation under its title, resolving to what it returns. */
+export type GenerationStep = <T>(title: string, body: () => Promise<T> | T) => Promise<T>;
 export interface ClientGenerated {
     readonly kind: "generated";
     /** The shared directory the client was generated into. */
@@ -65,8 +73,8 @@ export type ClientGenerationOutcome = ClientGenerated | ClientUpToDate | Foreign
  * generator did not produce stands in its way and `overrideForeign` is not set,
  * says what it is and writes nothing.
  *
- * @throws a refusal (`EnvFileError`, `ClientConfigError`, `ContractTransportError`,
- *   `ContractProtocolError`, `GeneratedNameError`, `OutputWriteError`) whose
+ * @throws a refusal (`AvEnvFileError`, `AvClientConfigError`, `AvContractTransportError`,
+ *   `AvContractProtocolError`, `AvGeneratedNameError`, `AvOutputWriteError`) whose
  *   message is the whole diagnosis; the previous output is intact. Anything else
  *   is a defect.
  */