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

package/dist/emit/client-tree.emitter.js

@@ -1,7 +1,9 @@
-import { withGeneratedBanner } from "./banner.emitter.js";
+import { AvClientConfigError } from "../config/config.resolver.js";
+import { accessVerbsOf, emitAccessModules } from "./access.emitter.js";
+import { AVCLIENT_REGENERATE, withGeneratedBanner, } from "./banner.emitter.js";
 import { emitClientSurfaceModule } from "./client-surface.emitter.js";
 import { emitContractCarrierModule } from "./contract-carrier.emitter.js";
-import { emitDerivationModules } from "./derivation.emitter.js";
+import { ACCESS_DERIVATION_ROOTS, DERIVATION_ROOTS, emitDerivationModules, } from "./derivation.emitter.js";
 import { emitDescriptorModule } from "./descriptor.emitter.js";
 import { CLIENT_ENTRY_FILE, GENERATED_DIRECTORY, } from "./emitted-tree.interface.js";
 import { emitEnumsModule } from "./enum.emitter.js";
@@ -12,9 +14,12 @@ import { emitNamedTypesModule } from "./named-type.emitter.js";
 import { emitDecimalModule, emitErrorsModule, emitMetadataModule, emitTransportModule, errorsModuleExports, } from "./runtime.emitter.js";
 import { emitScalarCodecModule } from "./scalar.codec.js";
 import { emitTransactionModules } from "./transaction.emitter.js";
-export function emitClientTree(contract, entrypoint, style) {
+export function emitClientTree(contract, entrypoint, style, regenerate = AVCLIENT_REGENERATE, accessOrigins = []) {
+    refuseForeignAccessOrigin(contract, entrypoint, accessOrigins);
     const names = deriveEmittedNames(contract);
-    const derivation = emitDerivationModules();
+    const derivation = emitDerivationModules(undefined, contract.access === undefined
+        ? DERIVATION_ROOTS
+        : [...DERIVATION_ROOTS, ...ACCESS_DERIVATION_ROOTS]);
     const generated = [
         ...derivation,
         emitClientSurfaceModule(contract, names, style),
@@ -24,8 +29,9 @@ export function emitClientTree(contract, entrypoint, style) {
         emitMetadataModule(contract.protocol, entrypoint),
         emitScalarCodecModule(style),
         emitDecimalModule(),
-        emitErrorsModule(),
-        emitTransportModule(style),
+        emitErrorsModule(regenerate),
+        emitTransportModule(style, contract.access !== undefined),
+        ...emitAccessModules(contract, style),
         emitNamedTypesModule(contract, names, style),
         ...(contract.transactions === "interactive"
             ? emitTransactionModules(style)
@@ -33,7 +39,10 @@ export function emitClientTree(contract, entrypoint, style) {
         ...emitFieldCheckModules(contract, style, new Set(derivation.map((module) => module.path))),
     ];
     const files = [
-        { path: CLIENT_ENTRY_FILE, source: clientEntrySource(style) },
+        {
+            path: CLIENT_ENTRY_FILE,
+            source: clientEntrySource(style, accessVerbsOf(contract).length > 0),
+        },
         ...generated.map((module) => ({
             path: `${GENERATED_DIRECTORY}/${module.path}`,
             source: module.source,
@@ -44,15 +53,22 @@ export function emitClientTree(contract, entrypoint, style) {
         .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
         .map((file) => ({
         path: file.path,
-        bytes: encoder.encode(withGeneratedBanner(file.source)),
+        bytes: encoder.encode(withGeneratedBanner(file.source, regenerate)),
     }));
     return { tree, style, warnings: names.warnings };
 }
-function clientEntrySource(style) {
-    const specifier = moduleSpecifierWriter(style);
-    const from = (module) => specifier(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
-    return (`export { default } from ${from("client.ts")};\n` +
-        `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n} from ${from("client.ts")};\n` +
+function clientEntrySource(style, accessVerbs) {
+    return (`export { default } from ${generatedModuleSpecifier(style, "client.ts")};\n` +
+        clientEntryReExports(style, "value", accessVerbs));
+}
+function generatedModuleSpecifier(style, module) {
+    return moduleSpecifierWriter(style)(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
+}
+export function clientEntryReExports(style, clientClass = "value", accessVerbs = false) {
+    const from = (module) => generatedModuleSpecifier(style, module);
+    return ((clientClass === "value"
+        ? `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n} from ${from("client.ts")};\n`
+        : `export type { AvClient, AvClientOptions, AvCallOptions } from ${from("client.ts")};\n`) +
         `export type { AvFetch } from ${from("runtime/transport.ts")};\n` +
         `export type { AvOperation } from ${from("derivation/transactions/deferred-operation.d.ts")};\n` +
         `export type * from ${from("types.d.ts")};\n` +
@@ -60,5 +76,20 @@ function clientEntrySource(style) {
         `export { AvDecimal } from ${from("runtime/decimal.ts")};\n` +
         `export {\n${errorsModuleExports()
             .map((name) => `\t${name},\n`)
-            .join("")}} from ${from("runtime/errors.ts")};\n`);
+            .join("")}} from ${from("runtime/errors.ts")};\n` +
+        (accessVerbs
+            ? `export { AvAccessError } from ${from("runtime/access.ts")};\n`
+            : ""));
+}
+function refuseForeignAccessOrigin(contract, entrypoint, accessOrigins) {
+    const url = contract.access?.url;
+    if (url === undefined || url.startsWith("/")) {
+        return;
+    }
+    const origin = new URL(url).origin;
+    if (origin === entrypoint.deployment?.origin ||
+        accessOrigins.includes(origin)) {
+        return;
+    }
+    throw new AvClientConfigError(`the ClientContract's Aventara Access URL is on ${origin}, not on the entrypoint's origin; $access sends sign-in credentials there, so it is emitted only when avclient's framework.client.ts lists that origin in accessOrigins (a same-origin client from aventara-build --client takes none: mount Access on the app's own origin).`);
 }

package/dist/emit/derivation.emitter.d.ts

@@ -5,8 +5,6 @@ export declare const DERIVATION_ROOTS: readonly string[];
  * (POSIX-separated); `undefined` when there is none.
  */
 export type DeclarationReader = (relative: string) => string | undefined;
-/** The published declarations of the `@aventara/core` this package resolves. */
-export declare function publishedCoreDeclarations(): DeclarationReader;
 /**
  * Core's declaration closure from {@link DERIVATION_ROOTS}, as modules under
  * `derivation/`, in UTF-16 code-unit order of their path.
@@ -14,4 +12,6 @@ export declare function publishedCoreDeclarations(): DeclarationReader;
  * @throws Error when the closure cannot be transported — a defect of the
  *   installed `@aventara/core`, never of the consumer's input.
  */
-export declare function emitDerivationModules(read?: DeclarationReader): readonly EmittedModule[];
+/** The roots a client with the `access` section copies besides {@link DERIVATION_ROOTS}. */
+export declare const ACCESS_DERIVATION_ROOTS: readonly string[];
+export declare function emitDerivationModules(read?: DeclarationReader, roots?: readonly string[]): readonly EmittedModule[];

package/dist/emit/derivation.emitter.js

@@ -13,7 +13,7 @@ export const DERIVATION_ROOTS = [
     "transactions/deferred-operation",
     "transactions/transaction-reference",
 ];
-export function publishedCoreDeclarations() {
+function publishedCoreDeclarations() {
     const dist = path.dirname(fileURLToPath(import.meta.resolve("@aventara/core")));
     return (relative) => {
         try {
@@ -27,9 +27,12 @@ export function publishedCoreDeclarations() {
         }
     };
 }
-export function emitDerivationModules(read = publishedCoreDeclarations()) {
+export const ACCESS_DERIVATION_ROOTS = [
+    "policy/access-verbs",
+];
+export function emitDerivationModules(read = publishedCoreDeclarations(), roots = DERIVATION_ROOTS) {
     const copied = new Map();
-    const queue = DERIVATION_ROOTS.map((root) => `${root}.d.ts`);
+    const queue = roots.map((root) => `${root}.d.ts`);
     while (queue.length > 0) {
         const file = queue.shift();
         if (copied.has(file)) {

package/dist/emit/emitted-tree.interface.d.ts

@@ -8,7 +8,7 @@ export declare const LEGACY_CLIENT_ENTRY_FILES: readonly string[];
 /** The directory holding every other emitted module, under `generateAt`. */
 export declare const GENERATED_DIRECTORY = "generated";
 export type DerivationModulePath = `derivation/${string}.d.ts`;
-export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/field-check.evaluator.ts" | "runtime/field-validators.ts" | "runtime/fingerprint.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
+export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/access.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/field-check.evaluator.ts" | "runtime/field-validators.ts" | "runtime/fingerprint.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
 export declare const CONTRACT_CARRIER_MODULE = "contract.ts";
 /** A path in the emitted tree: relative to `generateAt`, POSIX-separated. */
 export type EmittedFilePath = typeof CLIENT_ENTRY_FILE | `${typeof GENERATED_DIRECTORY}/${GeneratedModulePath}`;

package/dist/emit/field-check.emitter.d.ts

@@ -4,7 +4,7 @@ import { type ClientModuleStyle } from "./module-style.interface.js";
 /** Where `@aventara/core` publishes the evaluator's source, relative to its package root. */
 export declare const EVALUATOR_SOURCE = "src/runtime/field-check.evaluator.ts";
 /** Reads the evaluator's published source; `undefined` when core publishes none. */
-export type EvaluatorSourceReader = () => string | undefined;
+type EvaluatorSourceReader = () => string | undefined;
 /** The evaluator's source as the `@aventara/core` this package resolves publishes it. */
 export declare function publishedCoreEvaluator(): EvaluatorSourceReader;
 /** Whether the ClientContract carries any check: a field's validators or a Json Shape node's. */
@@ -19,3 +19,4 @@ export declare function contractHasFieldChecks(contract: AvContractClient): bool
  *   `@aventara/core`, never of the consumer's input.
  */
 export declare function emitFieldCheckModules(contract: AvContractClient, style: ClientModuleStyle, derivation: ReadonlySet<string>, read?: EvaluatorSourceReader): readonly EmittedModule[];
+export {};

package/dist/emit/field-check.emitter.js

@@ -141,6 +141,7 @@ function rulesTableSource(contract) {
 function fieldValidatorsSource(contract, from) {
     return `import type { AvFieldCheck } from ${from("../derivation/contracts/field-check")};
 import type { JsonSchema } from ${from("../derivation/contracts/json-shape")};
+import { RECORD_SITES, writeKeysOf } from ${from("./codec")};
 import { DECODE_TABLE } from ${from("./descriptor")};
 import { type AvCause, type AvValidationIssue, frameworkErrorOf } from ${from("./errors")};
 import {
@@ -456,21 +457,9 @@ function shapedValueIssues(schema: JsonSchema, list: boolean, value: unknown, pa
 
 // ---- field validators, judged as the server judges them after its field pipes ----
 
-/** Where each relation directive holds the records its target writes. */
-const RECORD_SITES: { readonly [directive: string]: readonly (string | undefined)[] } = {
-	$create: [undefined],
-	$connect: [],
-	$connectOrCreate: ["create"],
-	$disconnect: [],
-	$set: [],
-	$update: ["data"],
-	$delete: [],
-	$upsert: ["create", "update"],
-};
-
 /** The top-level data records of a create, update or upsert. */
 function writeRecordPaths(family: string, args: unknown): Path[] {
-	const keys = family === "create" || family === "update" ? ["data"] : family === "upsert" ? ["create", "update"] : [];
+	const keys = writeKeysOf(family);
 	const records: Path[] = [];
 	if (!isPlainRecord(args)) {
 		return records;

package/dist/emit/module-specifier.scanner.d.ts

@@ -1,4 +1,4 @@
-export interface ScannedModule {
+interface ScannedModule {
     /**
      * Every module specifier: a `from` clause's, a side-effect `import`'s, and an
      * `import()` type query's.
@@ -8,3 +8,4 @@ export interface ScannedModule {
     readonly references: boolean;
 }
 export declare function scanModuleSpecifiers(text: string): ScannedModule;
+export {};

package/dist/emit/name.deriver.d.ts

@@ -3,7 +3,7 @@ import type { AvContractClient, AvOperationFamily } from "@aventara/core";
  * Name derivation and the rename ladder for the emitted tree.
  */
 export declare const RESERVED_EMITTED_NAMES: readonly string[];
-export interface ResourceNamedType {
+interface ResourceNamedType {
     readonly suffix: string;
     readonly family: AvOperationFamily;
     readonly variant: string;
@@ -37,8 +37,6 @@ export interface EmittedNames {
     readonly properties: readonly EmittedProperty[];
     readonly warnings: readonly string[];
 }
-/** Whether `text` is an IdentifierName — the rule above, for every emitter. */
-export declare function isIdentifierName(text: string): boolean;
 /**
  * The emitted names of a Contract's enums and Resources, renamed where a name
  * cannot be declared as-is.
@@ -52,3 +50,4 @@ export declare class AvGeneratedNameError extends Error {
     constructor(problems: readonly string[]);
 }
 export declare function ownPropertyKey(value: string): string;
+export {};

package/dist/emit/name.deriver.js

@@ -2,6 +2,8 @@ import { isOperationVariantAvailable } from "@aventara/core/internal";
 import { FRAMEWORK_ERROR_CLASS_NAMES } from "./runtime.emitter.js";
 export const RESERVED_EMITTED_NAMES = [
     ...new Set([
+        "AvAccessError",
+        "AvAccessMe",
         "AvClient",
         "AvClientOptions",
         "AvCallOptions",
@@ -46,6 +48,7 @@ export function namedTypesOf(operations) {
     return RESOURCE_NAMED_TYPES.filter((named) => isOperationVariantAvailable(families[named.family]?.[named.variant]));
 }
 export const CLIENT_MEMBER_NAMES = [
+    "$access",
     "__defineGetter__",
     "__defineSetter__",
     "__lookupGetter__",
@@ -63,7 +66,7 @@ export const CLIENT_MEMBER_NAMES = [
     "valueOf",
 ];
 const IDENTIFIER = /^[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*$/u;
-export function isIdentifierName(text) {
+function isIdentifierName(text) {
     return IDENTIFIER.test(text);
 }
 const RESERVED_WORDS = new Set([

package/dist/emit/named-type.emitter.js

@@ -1,3 +1,4 @@
+import { jsonSchemaType } from "./json-shape.emitter.js";
 import { importSpecifier, } from "./module-style.interface.js";
 import { namedTypesOf } from "./name.deriver.js";
 export function emitNamedTypesModule(contract, names, style) {
@@ -12,12 +13,21 @@ export function emitNamedTypesModule(contract, names, style) {
                     `export type ${identifier}${named.suffix} = ResourceArgument<${resource}, ${JSON.stringify(named.family)}, ${JSON.stringify(named.variant)}, ${JSON.stringify(named.argument)}>;\n`;
         });
     });
+    const me = contract.access?.verbs?.me?.result;
+    const identity = me === undefined
+        ? []
+        : [
+            "/** What `avClient.$access.me()` resolves when someone is signed in: the token identity. */\n" +
+                `export type AvAccessMe = ${jsonSchemaType(me)};\n`,
+        ];
     const uses = (helper) => declarations.some((declaration) => declaration.includes(` = ${helper}<`));
     const imported = ["ResourceArgument", "ResourceRecord"].filter(uses);
     return {
         path: "types.d.ts",
         source: declarations.length === 0
-            ? "export {};\n"
-            : `import type { ${imported.join(", ")} } from ${JSON.stringify(importSpecifier("./client", style))};\n\n${declarations.join("")}`,
+            ? identity.length === 0
+                ? "export {};\n"
+                : identity.join("")
+            : `import type { ${imported.join(", ")} } from ${JSON.stringify(importSpecifier("./client", style))};\n\n${declarations.join("")}${identity.join("")}`,
     };
 }

package/dist/emit/runtime.emitter.d.ts

@@ -1,10 +1,11 @@
 import type { AvContractClient } from "@aventara/core";
-import type { ClientEntrypoint } from "../config/client-config.interface.js";
+import type { EmittedEntrypoint } from "../config/client-config.interface.js";
+import { type RegenerateCommand } from "./banner.emitter.js";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 export declare function emitDecimalModule(): EmittedModule;
-export declare function emitMetadataModule(protocol: AvContractClient["protocol"], entrypoint: ClientEntrypoint): EmittedModule;
+export declare function emitMetadataModule(protocol: AvContractClient["protocol"], entrypoint: EmittedEntrypoint): EmittedModule;
 export declare const FRAMEWORK_ERROR_CLASS_NAMES: readonly string[];
 export declare function errorsModuleExports(): readonly string[];
-export declare function emitErrorsModule(): EmittedModule;
-export declare function emitTransportModule(style: ClientModuleStyle): EmittedModule;
+export declare function emitErrorsModule(regenerate?: RegenerateCommand): EmittedModule;
+export declare function emitTransportModule(style: ClientModuleStyle, access?: boolean): EmittedModule;

package/dist/emit/runtime.emitter.js

@@ -1,6 +1,7 @@
 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() {
@@ -51,10 +52,13 @@ 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 = {
     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: "This client was generated against a ClientContract other than the one the server serves. Regenerate it with `avclient generate`.",
+    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.",
@@ -152,8 +156,12 @@ export class AvTransportError 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 AvError<${codes.map((code) => JSON.stringify(code)).join(" | ")}> {\n` +
@@ -186,12 +194,49 @@ export function emitErrorsModule() {
             "}\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("-"));
@@ -209,7 +254,7 @@ 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 AvCause,
@@ -319,12 +364,58 @@ type Envelope =
 	| { readonly outcome: "data"; readonly code: SuccessCode; readonly data: unknown }
 	| { 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.
  *
+ * @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; TypeError, before anything is sent, when the
+ *   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.
  */
@@ -335,7 +426,10 @@ export async function execute(
 	variant: string,
 	args: Readonly<Record<string, unknown>>,
 	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)));