@aventara/client 0.0.0-stage → 0.1.0-pilot.1

package/dist/emit/runtime.emitter.js

@@ -0,0 +1,707 @@
+import { OPERATION_CODES, VALIDATION_CODES, } from "@aventara/core";
+import { AvProtocol } from "@aventara/core/protocol";
+import { entrypointHref } from "../config/config.resolver.js";
+import { wireGrammarLiteral } from "./scalar.codec.js";
+/**
+ * The runtime modules the generated client carries: `metadata.ts`, the
+ * framework `Decimal`, the outcome codes and error classes, and the transport
+ * here; the scalar codec in `scalar.codec.ts`.
+ */
+/**
+ * `runtime/decimal.ts` — the framework-owned `Decimal` of §6.2, the generated
+ * runtime value of the `decimal` scalar. Bundled with the client and imported
+ * from nothing: its public type is its own, never an ORM's (§6.2, C-801).
+ *
+ * It holds the decimal string it was made from, digit for digit, and does no
+ * arithmetic — the surface is core's `Decimal` (a string constructor and
+ * `toString`) plus `toJSON`, so a value means the same on both sides of the wire.
+ * A proven decimal library may later sit behind it (§6.2); none is needed to
+ * carry digits.
+ *
+ * `toJSON` is the architect's (2026-10-04, S6 answers): it returns the decimal
+ * string, so a Decimal in a consumer's own JSON — a log line, a cache entry — is
+ * its digits rather than `{}`. No `equals`, no arithmetic. The request body never
+ * relies on it: `serializeWireBody` refuses an unencoded Decimal regardless, so a
+ * value the codec did not encode cannot slip onto the wire through `toJSON`.
+ *
+ * The grammar is core's `Decimal` grammar, read from `AvProtocol.scalarFormats`
+ * and emitted by value (C2, R7; `protocol-parity.spec.ts`). Unlike
+ * core's, the constructor refuses a non-string outright: a pattern test coerces
+ * its argument, so `5` would otherwise pass as `"5"` and be kept as a number.
+ */
+export function emitDecimalModule() {
+    return {
+        path: "runtime/decimal.ts",
+        source: `const DECIMAL_STRING = ${wireGrammarLiteral("decimal")};
+
+/**
+ * An exact decimal: the runtime value of the "decimal" scalar (§6.2).
+ *
+ * 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 {
+	readonly #value: string;
+
+	/** @throws TypeError when the value is not a decimal string. */
+	constructor(value: string) {
+		if (typeof value !== "string" || !DECIMAL_STRING.test(value)) {
+			throw new TypeError("Decimal value must be a valid decimal string.");
+		}
+		this.#value = value;
+	}
+
+	/** The decimal string, exactly as given. */
+	toString(): string {
+		return this.#value;
+	}
+
+	/** The decimal string, exactly as given: what JSON.stringify writes for a Decimal. */
+	toJSON(): string {
+		return this.#value;
+	}
+}
+`,
+    };
+}
+/**
+ * `metadata.ts` — what this client was generated against: the ClientContract
+ * hash and the protocol version (Phase 12-partial Q4 = A), and the resolved
+ * entrypoint as the client's default (§15.2; Phase 12-rest Q5 = A). Nothing else:
+ * no driver, no timestamp, no generator version, no host path — anything a re-run
+ * over the same inputs could change breaks byte-equality (§19.3's spirit). The
+ * entrypoint is an input like the contract: changing it regenerates different
+ * bytes and leaves the hash alone (§15.2), and it never carries credentials
+ * (refused at resolution, Q5).
+ *
+ * The hash and the version are what every operation request sends (§12.4), from
+ * `runtime/transport.ts`; all three are internal — `AvClient.ts` exports none.
+ */
+export function emitMetadataModule(protocol, entrypoint) {
+    return {
+        path: "metadata.ts",
+        source: "/** The hash of the ClientContract this client was generated against (§19.2). */\n" +
+            `export const CLIENT_CONTRACT_HASH = ${JSON.stringify(protocol.hash)};\n` +
+            "\n" +
+            "/** The Aventara protocol version that ClientContract speaks (§19.1). */\n" +
+            `export const PROTOCOL_VERSION = ${JSON.stringify(protocol.version)};\n` +
+            "\n" +
+            "/** The entrypoint the client was generated from: its default deployment (§15.2). */\n" +
+            `export const DEFAULT_ENTRYPOINT = ${JSON.stringify(entrypointHref(entrypoint))};\n`,
+    };
+}
+/**
+ * # The FrameworkError subclass set (Q2 = B)
+ *
+ * One subclass per code CLASS, plus the two the specification names by
+ * behaviour: `NotFoundError` (§13.4, A2003) and the contract-mismatch error
+ * (invariant 15, A2005). Each class's doc line is emitted above it.
+ *
+ * The keys are the emitted class names, in UTF-16 code-unit order.
+ */
+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 (§13.5).",
+    ContractMismatchError: "This client was generated against a ClientContract other than the one the server serves (invariant 15). Regenerate it with `avclient generate`.",
+    InternalError: "The server failed. Nothing in its cause is actionable; the diagnostics are in the server's logs (§13.5).",
+    NotFoundError: "A strict unique target does not exist (§13.4).",
+    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.",
+};
+/**
+ * The class every error code throws. A mapped type over core's
+ * `OperationErrorCode`, so a code core adds is a compile error here until it is
+ * classified — the classification is total by construction, never by care.
+ */
+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",
+    A4000: "AuthError",
+    A4001: "AuthError",
+    A4002: "AuthError",
+};
+/**
+ * The `FrameworkError` subclasses the generated runtime declares, in UTF-16
+ * code-unit order — names the root namespace reserves (`name.deriver.ts`).
+ */
+export const FRAMEWORK_ERROR_CLASS_NAMES = Object.keys(FRAMEWORK_ERROR_CLASSES);
+/** The error codes, in core's allocation order. */
+const ERROR_CODES = OPERATION_CODES.filter((code) => !code.startsWith("A1"));
+/**
+ * The names `AvClient.ts` re-exports from `generated/runtime/errors.ts`: the classes and the
+ * two code unions §15.4 requires, and `Cause` and `ValidationIssue` — the types a
+ * thrown FrameworkError carries, public by the architect's decision of
+ * 2026-10-04 — in UTF-16 code-unit order.
+ */
+export function errorsModuleExports() {
+    return [
+        ...FRAMEWORK_ERROR_CLASS_NAMES,
+        "FrameworkError",
+        "TransportError",
+        "type Cause",
+        "type OperationCode",
+        "type ValidationCode",
+        "type ValidationIssue",
+    ].sort((left, right) => {
+        const a = left.replace(/^type /, "");
+        const b = right.replace(/^type /, "");
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+}
+/** One code array as emitted source: a `const` tuple, one code per line. */
+function codeArray(codes) {
+    return `[\n${codes.map((code) => `\t${JSON.stringify(code)},\n`).join("")}] as const`;
+}
+const ERRORS_MODULE_HEAD = `/**
+ * The outcome codes and error classes of Aventara protocol version 1 (§13).
+ *
+ * A1xxx resolves; every other code throws the FrameworkError subclass of its
+ * class (§13.5); a response that is not a framework envelope throws
+ * TransportError. Branch on the class or on \`code\`, never on the message.
+ */
+`;
+const ERRORS_MODULE_TYPES = `
+/** One actionable validation issue (§13.1); \`path\` locates it in the request. */
+export interface ValidationIssue {
+	readonly path?: readonly (string | number)[];
+	readonly code: ValidationCode;
+	readonly message: string;
+}
+
+/**
+ * Why an operation failed (§13.1). Rebuilt member by member from the envelope:
+ * 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 (§13.5).
+ */
+export interface Cause {
+	readonly message: string;
+	readonly issues?: readonly ValidationIssue[];
+	/** The index of the failing operation in a transaction plan. */
+	readonly operation?: number;
+}
+
+/**
+ * A framework outcome that throws (§13.5): every code outside A1xxx. It is
+ * always thrown as the subclass of its code's class; catch FrameworkError to
+ * catch them all.
+ */
+export class FrameworkError<C extends OperationErrorCode = OperationErrorCode> extends Error {
+	override readonly name: string = "FrameworkError";
+	/** 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;
+
+	constructor(code: C, cause: Cause) {
+		super(cause.message);
+		this.code = code;
+		this.cause = cause;
+	}
+}
+`;
+const ERRORS_MODULE_TAIL = `
+/**
+ * A failure that never produced a framework envelope (§13.5): 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
+ * cause: nothing in such a response is the framework's to report.
+ */
+export class TransportError extends Error {
+	override readonly name: string = "TransportError";
+	/** The HTTP status that arrived, or null when no response arrived at all. */
+	readonly status: number | null;
+
+	constructor(message: string, status: number | null) {
+		super(message);
+		this.status = status;
+	}
+}
+`;
+/**
+ * `runtime/errors.ts` — §13's vocabulary as the generated client carries it.
+ *
+ * Both code unions are emitted from core's exported arrays (Q3), so the emitted
+ * tree states each code exactly once and core stays their one source; the
+ * subclass set and the code each one throws are Q2's (above), accepted as-is by
+ * the architect on 2026-10-04. Exported beyond what `AvClient.ts` re-exports: the
+ * two arrays, `OperationErrorCode` and `frameworkErrorOf`, which
+ * `runtime/transport.ts` reads.
+ */
+export function emitErrorsModule() {
+    const classes = Object.entries(FRAMEWORK_ERROR_CLASSES).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` +
+            `\toverride readonly name: string = ${JSON.stringify(name)};\n}\n`);
+    });
+    const table = ERROR_CODES.map((code) => `\t${code}: ${FRAMEWORK_ERROR_CLASS_OF[code]},\n`).join("");
+    return {
+        path: "runtime/errors.ts",
+        source: ERRORS_MODULE_HEAD +
+            "\n/** The outcome codes of the protocol, in allocation order (§13.2). */\n" +
+            `export const OPERATION_CODES = ${codeArray(OPERATION_CODES)};\n` +
+            "\n/** An outcome code (§13.2). */\n" +
+            "export type OperationCode = (typeof OPERATION_CODES)[number];\n" +
+            "\n/** An outcome code that throws: every code outside A1xxx (§13.5). */\n" +
+            `export type OperationErrorCode = Exclude<OperationCode, \`A1\${string}\`>;\n` +
+            "\n/** The validation codes of the protocol, in allocation order (§13.3). */\n" +
+            `export const VALIDATION_CODES = ${codeArray(VALIDATION_CODES)};\n` +
+            "\n/** A validation code (§13.3): what one issue in a cause is about. */\n" +
+            "export type ValidationCode = (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" +
+            `} = {\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" +
+            "\tconst ErrorClass = ERROR_CLASS_OF[code];\n" +
+            "\treturn new ErrorClass(code, cause);\n" +
+            "}\n",
+    };
+}
+/**
+ * `runtime/transport.ts` — the happy path of §12 and §13.5, above Phase
+ * 12-partial's boundary: one POST per operation to
+ * `<entrypoint>/_resources/<resource>/<family>/<variant>` (§12.1–§12.3), the
+ * identity headers on every request (§12.4), per-request options that are never
+ * serialized (§15.7), and the envelope read back by §13.5's rule.
+ *
+ * `execute` is Q1 = B's primitive: exported from this module for the
+ * per-variant methods to wrap, and re-exported from nowhere — it is not public
+ * surface. It reads no capability and no operation descriptor; the caller names
+ * the operation.
+ *
+ * Fetch and AbortSignal are the platform's, reached through the structural types
+ * below so the module compiles with neither DOM nor Node types (§15.7, U5).
+ *
+ * Stale-route recovery is not here: it is F-716, Phase 10's, and the emitted
+ * module documents it as a hole in its own doc comment (S9).
+ */
+export function emitTransportModule() {
+    return { path: "runtime/transport.ts", source: TRANSPORT_MODULE };
+}
+/**
+ * Core's identity header names (`AvProtocol.headers`, §12.4), split back into
+ * the one wire prefix and each header's own part, so the emitted transport
+ * spells both from one constant — its freeze stays a one-line change in the
+ * generated code — and from core's values rather than restated text.
+ *
+ * @throws Error at load when core's names stop sharing one `<prefix>-` head:
+ *   the emitted spelling could no longer be the names core sends.
+ */
+const IDENTITY_HEADERS = (() => {
+    const { protocolVersion, contractHash, requestId } = AvProtocol.headers;
+    const prefix = protocolVersion.slice(0, protocolVersion.indexOf("-"));
+    for (const name of [protocolVersion, contractHash, requestId]) {
+        if (prefix === "" || !name.startsWith(`${prefix}-`)) {
+            throw new Error(`AvProtocol.headers no longer share one wire prefix: ${name}`);
+        }
+    }
+    return {
+        prefix,
+        protocolVersion: protocolVersion.slice(prefix.length),
+        contractHash: contractHash.slice(prefix.length),
+        requestId: requestId.slice(prefix.length),
+    };
+})();
+const TRANSPORT_MODULE = `import { CLIENT_CONTRACT_HASH, PROTOCOL_VERSION } from "../metadata.js";
+import { decodeResult, encodeArguments, serializeWireBody } from "./codec.js";
+import { DECODE_TABLE } from "./descriptor.js";
+import {
+	type Cause,
+	frameworkErrorOf,
+	OPERATION_CODES,
+	type OperationCode,
+	type OperationErrorCode,
+	TransportError,
+	VALIDATION_CODES,
+	type ValidationCode,
+	type ValidationIssue,
+} from "./errors.js";
+
+/**
+ * The transport of Aventara protocol version 1: one POST per operation (§12.2),
+ * sent with the protocol version and ClientContract hash (§12.4), its response
+ * read by §13.5'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 (§13.5).
+ *
+ * # A stale client (F-716)
+ *
+ * A client generated against an older ClientContract must fail hard and say to
+ * regenerate (cross-phase invariant 15). The server is what knows: it checks the
+ * identity this transport sends BEFORE it routes (Phase 10, Q3), 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. Nothing here guesses: a response that
+ * is not a framework envelope — 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 stale.
+ */
+
+/** The wire prefix of the identity headers, in one place: its freeze (§12.4) is a one-line change. */
+const WIRE_PREFIX = ${JSON.stringify(IDENTITY_HEADERS.prefix)};
+
+/** The headers the framework owns on every operation request (§12.3, §12.4). */
+const FRAMEWORK_HEADERS: Readonly<Record<string, string>> = {
+	"Content-Type": "application/json",
+	[WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.protocolVersion)}]: String(PROTOCOL_VERSION),
+	[WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.contractHash)}]: CLIENT_CONTRACT_HASH,
+};
+
+/** The request id header (§12.4, Phase 10 Q13): CallOptions.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. */
+export interface StructuralSignal {
+	readonly aborted: boolean;
+}
+
+/** The request the transport hands to fetch. */
+export interface FetchInit {
+	readonly method: "POST";
+	readonly headers: Readonly<Record<string, string>>;
+	readonly body: string;
+	readonly signal?: PlatformSignal;
+}
+
+/** What the transport reads of a fetch Response. */
+export interface FetchResponse {
+	readonly status: number;
+	text(): Promise<string>;
+}
+
+/** The Fetch 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 (§15.7): the consumer's own platform fetch type when
+ * 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;
+
+/** The consumer's AbortSignal type when their lib declares one, else the structural signal. */
+export type PlatformSignal = typeof globalThis extends {
+	readonly AbortSignal: { readonly prototype: infer S };
+}
+	? S
+	: StructuralSignal;
+
+/** Where operations go: the framework entrypoint, and the fetch that reaches it. */
+export interface TransportConnection {
+	/** The framework entrypoint, an absolute URL without a trailing slash (§12.1). */
+	readonly entrypoint: string;
+	readonly fetch: Fetch;
+}
+
+/** Per-call options (§15.7). Never serialized into the operation body. */
+export interface CallOptions {
+	/** 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. */
+	readonly headers?: Readonly<Record<string, string>>;
+	/**
+	 * Sent as the request id header (Aventara-Request-Id); the empty string is
+	 * absent. It wins over that header in headers, which it overwrites.
+	 */
+	readonly requestId?: string;
+}
+
+type SuccessCode = Exclude<OperationCode, OperationErrorCode>;
+
+/** A framework envelope (§13.1), read and checked. */
+type Envelope =
+	| { readonly code: SuccessCode; readonly data: unknown; readonly cause: null }
+	| { readonly code: OperationErrorCode; readonly data: null; readonly cause: Cause };
+
+/**
+ * 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
+ *   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.
+ */
+export async function execute(
+	connection: TransportConnection,
+	resource: string,
+	family: string,
+	variant: string,
+	args: Readonly<Record<string, unknown>>,
+	options: CallOptions = {},
+): Promise<unknown> {
+	const operation = JSON.stringify(resource) + " " + family + "." + variant;
+	const headers = requestHeaders(options);
+	const body = serializeWireBody(encodeArguments(argumentObject(args)));
+	const path = "/_resources/" + [resource, family, variant].map(encodeURIComponent).join("/");
+	const response = await post(connection, path, operation, headers, body, options);
+	return decoded(operation, response.status, () => decodeResult(DECODE_TABLE, resource, response.data));
+}
+
+/**
+ * Runs one transaction plan (§14.2): POSTs it to \`/_transactions\` and settles
+ * its envelope; a committed plan's data is one result per operation, each decoded
+ * 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.
+ */
+export async function executePlan(
+	connection: TransportConnection,
+	plan: { readonly operations: readonly unknown[] },
+	resources: readonly string[],
+	options: CallOptions = {},
+): Promise<unknown[]> {
+	const operation = "the transaction";
+	const headers = requestHeaders(options);
+	const body = serializeWireBody(plan);
+	const response = await post(connection, "/_transactions", operation, headers, body, options);
+	return decoded(operation, response.status, () => {
+		if (!Array.isArray(response.data) || response.data.length !== resources.length) {
+			throw new TypeError("A committed plan's data must hold one result per operation.");
+		}
+		return response.data.map((slot, index) => decodeResult(DECODE_TABLE, resources[index] ?? "", slot));
+	});
+}
+
+/** One POST and its settled envelope data, still in wire form. */
+async function post(
+	connection: TransportConnection,
+	path: string,
+	operation: string,
+	headers: Readonly<Record<string, string>>,
+	body: string,
+	options: CallOptions,
+): Promise<{ readonly status: number; readonly data: unknown }> {
+	const url = connection.entrypoint + path;
+	const init: FetchInit =
+		options.signal === undefined
+			? { method: "POST", headers, body }
+			: { method: "POST", headers, body, signal: options.signal };
+
+	// Called unbound: a browser's fetch refuses a this that is not the global.
+	const fetch = connection.fetch as StructuralFetch;
+	let response: FetchResponse;
+	try {
+		response = await fetch(url, init);
+	} catch (error) {
+		if (options.signal?.aborted === true) {
+			throw error;
+		}
+		throw new TransportError("The request for " + operation + " failed before any response arrived.", null);
+	}
+	let text: string;
+	try {
+		text = await response.text();
+	} catch (error) {
+		if (options.signal?.aborted === true) {
+			throw error;
+		}
+		throw new TransportError(
+			"The response to " + operation + " (HTTP " + response.status + ") could not be read.",
+			response.status,
+		);
+	}
+	return { status: response.status, data: settle(operation, response.status, text) };
+}
+
+/**
+ * The decoded data, or — a scalar in \`data\` that does not decode, inside an
+ * otherwise valid envelope — a TransportError (architect, 2026-10-04).
+ */
+function decoded<T>(operation: string, status: number, decode: () => T): T {
+	try {
+		return decode();
+	} catch (error) {
+		throw new TransportError(
+			"The response to " + operation + " (HTTP " + status + ") holds a value this client cannot read: " +
+				(error instanceof Error ? error.message : String(error)),
+			status,
+		);
+	}
+}
+
+/**
+ * Settles one response by §13.5's rule: the envelope's data, still in wire form,
+ * which the caller decodes by the decode table (P1). A decode failure's mode is
+ * decided (architect, 2026-10-04):
+ * 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.
+ */
+function settle(operation: string, status: number, text: string): unknown {
+	const envelope = envelopeOf(parseJson(text));
+	if (envelope === undefined) {
+		throw new TransportError(
+			"The response to " + operation + " (HTTP " + status + ") is not an Aventara response envelope.",
+			status,
+		);
+	}
+	if (envelope.cause === null) {
+		return envelope.data;
+	}
+	throw frameworkErrorOf(envelope.code, envelope.cause);
+}
+
+/** The parsed body, or undefined — which no envelope is — when it is not JSON. */
+function parseJson(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+}
+
+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 {
+	return OPERATION_CODES.some((code) => code === value);
+}
+
+function isValidationCode(value: unknown): value is ValidationCode {
+	return VALIDATION_CODES.some((code) => code === value);
+}
+
+function isSuccessCode(code: OperationCode): code is SuccessCode {
+	return code.startsWith("A1");
+}
+
+/** The envelope in a parsed body, or undefined when the body is not one (§13.1). */
+function envelopeOf(body: unknown): Envelope | undefined {
+	if (!isRecord(body) || !Object.hasOwn(body, "data")) {
+		return undefined;
+	}
+	const code = body["code"];
+	const data = body["data"];
+	if (!isOperationCode(code)) {
+		return undefined;
+	}
+	if (isSuccessCode(code)) {
+		return body["cause"] === null && (code !== "A1001" || data === null) ? { code, data, cause: null } : undefined;
+	}
+	const cause = causeOf(body["cause"]);
+	return data === null && cause !== undefined ? { code, data, cause } : undefined;
+}
+
+/**
+ * The cause rebuilt from the members §13.1 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.
+ */
+function causeOf(value: unknown): Cause | undefined {
+	if (!isRecord(value)) {
+		return undefined;
+	}
+	const message = value["message"];
+	const issues = value["issues"];
+	const operation = value["operation"];
+	if (typeof message !== "string") {
+		return undefined;
+	}
+	let cause: Cause = { message };
+	if (issues !== undefined) {
+		if (!Array.isArray(issues)) {
+			return undefined;
+		}
+		const rebuilt: ValidationIssue[] = [];
+		for (const issue of issues) {
+			const copy = issueOf(issue);
+			if (copy === undefined) {
+				return undefined;
+			}
+			rebuilt.push(copy);
+		}
+		cause = { ...cause, issues: Object.freeze(rebuilt) };
+	}
+	if (operation !== undefined) {
+		if (typeof operation !== "number" || !Number.isInteger(operation) || operation < 0) {
+			return undefined;
+		}
+		cause = { ...cause, operation };
+	}
+	return Object.freeze(cause);
+}
+
+function issueOf(value: unknown): ValidationIssue | undefined {
+	if (!isRecord(value)) {
+		return undefined;
+	}
+	const path = value["path"];
+	const code = value["code"];
+	const message = value["message"];
+	if (!isValidationCode(code) || typeof message !== "string") {
+		return undefined;
+	}
+	if (path === undefined) {
+		return Object.freeze({ code, message });
+	}
+	if (!Array.isArray(path)) {
+		return undefined;
+	}
+	const segments: (string | number)[] = [];
+	for (const segment of path) {
+		if (typeof segment !== "string" && !Number.isInteger(segment)) {
+			return undefined;
+		}
+		segments.push(segment);
+	}
+	return Object.freeze({ path: Object.freeze(segments), code, message });
+}
+
+/** The arguments, refused unless they are an object: the body is always one (§12.6). */
+function argumentObject(args: unknown): unknown {
+	if (!isRecord(args)) {
+		throw new TypeError("An operation's arguments must be an object; send {} when there are none (§12.3).");
+	}
+	return args;
+}
+
+/**
+ * The framework's headers plus the caller's, refusing a caller's that names one of
+ * the framework's; then requestId, which overwrites any request id header the
+ * caller set (architect, 2026-10-05).
+ */
+function requestHeaders(options: CallOptions): 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 ?? {})) {
+		if (owned.has(name.toLowerCase())) {
+			throw new TypeError('The "' + name + '" header is the framework\\'s own; a request cannot set it (§12.4).');
+		}
+		headers[name] = value;
+	}
+	if (options.requestId !== undefined && options.requestId !== "") {
+		for (const name of Object.keys(headers)) {
+			if (name.toLowerCase() === REQUEST_ID_HEADER.toLowerCase()) {
+				delete headers[name];
+			}
+		}
+		headers[REQUEST_ID_HEADER] = options.requestId;
+	}
+	return headers;
+}
+`;