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

package/dist/contract/contract.fetcher.js

@@ -0,0 +1,85 @@
+/**
+ * What a conditional GET answers when the served ClientContract is the one named
+ * (`304 Not Modified`, Phase 10 Q8): no body, nothing to judge.
+ */
+export const CONTRACT_NOT_MODIFIED = Symbol("aventara.contract-not-modified");
+export class ContractTransportError extends Error {
+    reason;
+    name = "ContractTransportError";
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+    }
+}
+/**
+ * `<entrypoint>/_contract`: the canonical mount path and the route, concatenated.
+ * The path's canonical form is resolution's (F-822) — root is `""` — so the join
+ * repairs nothing and special-cases nothing. URL resolution would be wrong here:
+ * `new URL("_contract", "https://h/api")` replaces `api`.
+ */
+export function contractUrlOf(entrypoint) {
+    const url = new URL(entrypoint.deployment.href);
+    url.pathname = `${entrypoint.path}/_contract`;
+    return url;
+}
+/** The URL as it may be printed: credentials in the entrypoint never are. */
+export function displayUrl(url) {
+    const shown = new URL(url.href);
+    shown.username = "";
+    shown.password = "";
+    return shown.href;
+}
+/**
+ * GETs the ClientContract and returns the parsed body, unjudged — or, when
+ * `ifNoneMatch` (a quoted contract hash, the deployment's entity tag) is sent and
+ * the deployment answers `304`, {@link CONTRACT_NOT_MODIFIED} (Phase 12-rest Q6).
+ * A `304` to a request that sent none is no answer, like any other non-2xx.
+ *
+ * @throws ContractTransportError when no JSON value arrives.
+ */
+export async function fetchClientContractBody(entrypoint, fetch = globalThis.fetch, ifNoneMatch) {
+    const url = contractUrlOf(entrypoint);
+    const shown = displayUrl(url);
+    const remedy = "Check that the deployment is running and that the entrypoint is its origin plus mount path.";
+    let response;
+    try {
+        response = await fetch(url, ifNoneMatch === undefined
+            ? { method: "GET" }
+            : { method: "GET", headers: { "If-None-Match": ifNoneMatch } });
+    }
+    catch (error) {
+        throw new ContractTransportError("request-failed", `Could not fetch the ClientContract from ${shown}: ${describeCause(error)}. ${remedy}`, { cause: error });
+    }
+    if (response.status === 304 && ifNoneMatch !== undefined) {
+        return CONTRACT_NOT_MODIFIED;
+    }
+    if (!response.ok) {
+        throw new ContractTransportError("http-status", `GET ${shown} answered HTTP ${response.status}, not the ClientContract. ${remedy}`);
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        throw new ContractTransportError("body-unreadable", `The response from ${shown} could not be read: ${describeCause(error)}. ${remedy}`, { cause: error });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        // The body itself is not printed: it may be a whole HTML page.
+        throw new ContractTransportError("body-not-json", `The response from ${shown} is not JSON, so it is not a ClientContract. ${remedy}`, { cause: error });
+    }
+}
+/**
+ * A failure's own words and, for Node's `fetch failed`, its cause's — the part
+ * that says ECONNREFUSED or ENOTFOUND. Messages only, never a stack.
+ */
+function describeCause(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    return error.cause instanceof Error
+        ? `${error.message} (${error.cause.message})`
+        : error.message;
+}

package/dist/contract/contract.loader.d.ts

@@ -0,0 +1,32 @@
+import type { ClientContract } from "@aventara/core";
+import type { ClientEntrypoint } from "../config/client-config.interface.js";
+import { type ContractFetch } from "./contract.fetcher.js";
+/**
+ * §15.3's first steps as one call: GET the ClientContract, then accept it — protocol
+ * support, structure, hash. Where the pipeline stops on a rejection, so it is where
+ * the `ContractRejected` value becomes a thrown `ContractProtocolError`.
+ */
+export interface ClientContractLoadInput {
+    /** The client config's resolved entrypoint (§15.2, S2). */
+    readonly entrypoint: ClientEntrypoint;
+    /** Injected for tests; the platform `fetch` otherwise. */
+    readonly fetch?: ContractFetch;
+}
+/**
+ * @throws ContractTransportError when no JSON value arrives.
+ * @throws ContractProtocolError when what arrived is refused.
+ */
+export declare function loadClientContract(input: ClientContractLoadInput): Promise<ClientContract>;
+/** A ClientContract loaded against one the caller already holds (Phase 12-rest Q6). */
+export interface ClientContractSince {
+    readonly contract: ClientContract;
+    /** The deployment answered `304`: `contract` is the one the caller held. */
+    readonly notModified: boolean;
+}
+/**
+ * {@link loadClientContract}, conditional on `stored` — a ClientContract the
+ * caller holds, already verified (its parsed carrier): the GET sends
+ * `If-None-Match: "<its hash>"`, and a `304` answers with `stored` itself. Without
+ * `stored` the GET is unconditional.
+ */
+export declare function loadClientContractSince(input: ClientContractLoadInput, stored: ClientContract | undefined): Promise<ClientContractSince>;

package/dist/contract/contract.loader.js

@@ -0,0 +1,32 @@
+import { acceptClientContract, ContractProtocolError, } from "./contract.acceptance.js";
+import { CONTRACT_NOT_MODIFIED, contractUrlOf, displayUrl, fetchClientContractBody, } from "./contract.fetcher.js";
+/**
+ * @throws ContractTransportError when no JSON value arrives.
+ * @throws ContractProtocolError when what arrived is refused.
+ */
+export async function loadClientContract(input) {
+    return accepted(await fetchClientContractBody(input.entrypoint, input.fetch), input);
+}
+/**
+ * {@link loadClientContract}, conditional on `stored` — a ClientContract the
+ * caller holds, already verified (its parsed carrier): the GET sends
+ * `If-None-Match: "<its hash>"`, and a `304` answers with `stored` itself. Without
+ * `stored` the GET is unconditional.
+ */
+export async function loadClientContractSince(input, stored) {
+    if (stored === undefined) {
+        return { contract: await loadClientContract(input), notModified: false };
+    }
+    const body = await fetchClientContractBody(input.entrypoint, input.fetch, `"${stored.protocol.hash}"`);
+    if (body === CONTRACT_NOT_MODIFIED) {
+        return { contract: stored, notModified: true };
+    }
+    return { contract: await accepted(body, input), notModified: false };
+}
+async function accepted(body, input) {
+    const acceptance = await acceptClientContract(body);
+    if (!acceptance.accepted) {
+        throw new ContractProtocolError(acceptance, displayUrl(contractUrlOf(input.entrypoint)));
+    }
+    return acceptance.contract;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * The banner line that says who owns a file. It is what the output writer reads
+ * to decide that a directory is a previous generation it may replace whole
+ * (§15.3) rather than someone's files it would delete — so it is its own
+ * constant, and must not change between generator versions: an output written
+ * by an older generator has to stay recognisable to a newer one.
+ */
+export declare const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
+/**
+ * The ownership banner every emitted file opens with (§15.3: "Files are stamped as
+ * generated/do-not-edit").
+ *
+ * The Biome suppressions are EMITTED rather than configured (M17, the adapter's
+ * `artifact.emitter.ts` precedent), so the output stays correct wherever a
+ * consumer drops it, including a repository whose formatter nobody here chose.
+ *
+ * Nothing in it can change between two runs over one contract: no timestamp, no
+ * generator version, no host, no path (Q4, §19.3) — any of them would break the
+ * exit gate's byte-equality on the first re-run. And no driver prose (Q4 = A).
+ */
+export declare const GENERATED_BANNER: readonly string[];
+/** `source` with the banner before it and one blank line between. */
+export declare function withGeneratedBanner(source: string): string;
+/**
+ * How far into a file the ownership line is looked for. The banner opens every
+ * emitted file, so the line sits well inside this; a reader never has to read a
+ * whole file to learn it is foreign.
+ */
+export declare const GENERATED_OWNERSHIP_HEAD_BYTES = 1024;
+/** Whether `head` — a file's first bytes, as text — carries the ownership line. */
+export declare function carriesGeneratedOwnership(head: string): boolean;

package/dist/emit/banner.emitter.js

@@ -0,0 +1,42 @@
+/**
+ * The banner line that says who owns a file. It is what the output writer reads
+ * to decide that a directory is a previous generation it may replace whole
+ * (§15.3) rather than someone's files it would delete — so it is its own
+ * constant, and must not change between generator versions: an output written
+ * by an older generator has to stay recognisable to a newer one.
+ */
+export const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
+/**
+ * The ownership banner every emitted file opens with (§15.3: "Files are stamped as
+ * generated/do-not-edit").
+ *
+ * The Biome suppressions are EMITTED rather than configured (M17, the adapter's
+ * `artifact.emitter.ts` precedent), so the output stays correct wherever a
+ * consumer drops it, including a repository whose formatter nobody here chose.
+ *
+ * Nothing in it can change between two runs over one contract: no timestamp, no
+ * generator version, no host, no path (Q4, §19.3) — any of them would break the
+ * exit gate's byte-equality on the first re-run. And no driver prose (Q4 = A).
+ */
+export const GENERATED_BANNER = [
+    "// biome-ignore-all format: generated output; these bytes are the artifact",
+    "// biome-ignore-all lint: generated output",
+    GENERATED_OWNERSHIP_LINE,
+    "/* Regenerate with `avclient generate`. */",
+];
+/** `source` with the banner before it and one blank line between. */
+export function withGeneratedBanner(source) {
+    return `${GENERATED_BANNER.join("\n")}\n\n${source}`;
+}
+/**
+ * How far into a file the ownership line is looked for. The banner opens every
+ * emitted file, so the line sits well inside this; a reader never has to read a
+ * whole file to learn it is foreign.
+ */
+export const GENERATED_OWNERSHIP_HEAD_BYTES = 1024;
+/** Whether `head` — a file's first bytes, as text — carries the ownership line. */
+export function carriesGeneratedOwnership(head) {
+    return head
+        .slice(0, GENERATED_OWNERSHIP_HEAD_BYTES)
+        .includes(GENERATED_OWNERSHIP_LINE);
+}

package/dist/emit/client-surface.emitter.d.ts

@@ -0,0 +1,32 @@
+import type { ClientContract } from "@aventara/core";
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type EmittedNames } from "./name.deriver.js";
+/**
+ * `generated/client.ts` — the typed surface (Phase 12-rest S4; plan §6): the class
+ * `AvClient` (Q8), its options `AvClientOptions` and the per-call `CallOptions`
+ * (Q9, Q17), and the ready instance `avClient`, this module's default export
+ * (Q7).
+ *
+ * Every argument and result type is an instantiation of core's own derivation,
+ * copied under `generated/derivation/` (Q1 = A): the call grammar
+ * (`OperationGrammar`, `OperationCall`, `DeferredOperationCall`, S1) over the
+ * carrier's contract (`ClientContractShape`, Q4), in the client's forms (Q3 = A:
+ * core's application forms, with this tree's own `Decimal`). Nothing here
+ * re-spells a rule. A call resolves to the data (Q11 = a: `"data"`), a
+ * first-style miss to `null`.
+ *
+ * Each surface is one mapped alias over the one contract (Phase 9's variance
+ * lesson). A Resource is reached by its contract name, except where that name is
+ * one of the client's own members (Q12), which renames the property only.
+ * `tx` and `transaction` exist iff the contract advertises `interactive`
+ * transactions (P3), in the type as in the runtime.
+ *
+ * Also declared here, for `types.d.ts` alone, the two helpers the named types are
+ * aliases of (Q10): `ResourceRecord` and `ResourceArgument`.
+ *
+ * At runtime (S5) the class builds one frozen object per Resource from the
+ * advertised operations (P4) — each variant a function that runs the operation
+ * through the transport, reading the fetch when it is called — and the default
+ * entrypoint is the generated one (§15.2, Q5) unless the options name another.
+ */
+export declare function emitClientSurfaceModule(contract: ClientContract, names: EmittedNames): EmittedModule;

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

@@ -0,0 +1,236 @@
+import { ownPropertyKey } from "./name.deriver.js";
+/**
+ * `generated/client.ts` — the typed surface (Phase 12-rest S4; plan §6): the class
+ * `AvClient` (Q8), its options `AvClientOptions` and the per-call `CallOptions`
+ * (Q9, Q17), and the ready instance `avClient`, this module's default export
+ * (Q7).
+ *
+ * Every argument and result type is an instantiation of core's own derivation,
+ * copied under `generated/derivation/` (Q1 = A): the call grammar
+ * (`OperationGrammar`, `OperationCall`, `DeferredOperationCall`, S1) over the
+ * carrier's contract (`ClientContractShape`, Q4), in the client's forms (Q3 = A:
+ * core's application forms, with this tree's own `Decimal`). Nothing here
+ * re-spells a rule. A call resolves to the data (Q11 = a: `"data"`), a
+ * first-style miss to `null`.
+ *
+ * Each surface is one mapped alias over the one contract (Phase 9's variance
+ * lesson). A Resource is reached by its contract name, except where that name is
+ * one of the client's own members (Q12), which renames the property only.
+ * `tx` and `transaction` exist iff the contract advertises `interactive`
+ * transactions (P3), in the type as in the runtime.
+ *
+ * Also declared here, for `types.d.ts` alone, the two helpers the named types are
+ * aliases of (Q10): `ResourceRecord` and `ResourceArgument`.
+ *
+ * At runtime (S5) the class builds one frozen object per Resource from the
+ * advertised operations (P4) — each variant a function that runs the operation
+ * through the transport, reading the fetch when it is called — and the default
+ * entrypoint is the generated one (§15.2, Q5) unless the options name another.
+ */
+export function emitClientSurfaceModule(contract, names) {
+    const renamed = names.properties.filter((property) => property.property !== property.contractName);
+    const propertyOf = renamed.length === 0
+        ? "R"
+        : `${renamed
+            .map((property) => `R extends ${JSON.stringify(property.contractName)} ? ${JSON.stringify(property.property)} : `)
+            .join("")}R`;
+    const resourceKey = renamed.length === 0 ? "R in Resource" : `R in Resource as ${propertyOf}`;
+    const interactive = contract.transactions === "interactive";
+    const renamedEntries = renamed.length === 0
+        ? ""
+        : ` ${renamed.map((property) => `${ownPropertyKey(property.contractName)}: ${JSON.stringify(property.property)}`).join(", ")} `;
+    const surface = (name, call) => `type ${name} = {\n` +
+        `\treadonly [${resourceKey}]: {\n` +
+        "\t\treadonly [F in keyof Grammar[R]]: {\n" +
+        `\t\t\treadonly [V in keyof Grammar[R][F]]: ${call};\n` +
+        "\t\t};\n" +
+        "\t};\n" +
+        "};\n";
+    return {
+        path: "client.ts",
+        source: 'import type { ClientContractShape } from "./contract.js";\n' +
+            'import type { ApplicationScalarForms } from "./derivation/contracts/scalar-value-type.js";\n' +
+            'import type { OperationArgumentsFor, ResourceKey } from "./derivation/operations/operation-arguments.js";\n' +
+            `import type { ${interactive ? "DeferredOperationCall, " : ""}OperationCall, OperationGrammar } from "./derivation/operations/operation-call.js";\n` +
+            'import type { OperationFamily, OperationIdentity } from "./derivation/operations/operation-identity.js";\n' +
+            'import type { AdmittedOperationResult } from "./derivation/operations/operation-result.js";\n' +
+            (interactive
+                ? 'import type { Operation, TransactionResults } from "./derivation/transactions/deferred-operation.js";\n'
+                : "") +
+            'import { DEFAULT_ENTRYPOINT } from "./metadata.js";\n' +
+            'import type { Decimal } from "./runtime/decimal.js";\n' +
+            'import { ADVERTISED_OPERATIONS } from "./runtime/descriptor.js";\n' +
+            (interactive
+                ? 'import { deferOperation, runTransaction } from "./runtime/transaction.js";\n'
+                : "") +
+            'import { type CallOptions, execute, type Fetch, type TransportConnection } from "./runtime/transport.js";\n' +
+            "\n" +
+            'export type { CallOptions } from "./runtime/transport.js";\n' +
+            "\n" +
+            "/**\n" +
+            " * The forms this client reads and writes (§6.2, Q3): core's application forms —\n" +
+            " * `bigint`, `Date`, `Uint8Array` — with this client's own `Decimal`.\n" +
+            " */\n" +
+            'export type ClientScalarForms = Omit<ApplicationScalarForms, "decimal"> & {\n' +
+            "\treadonly decimal: Decimal;\n" +
+            "};\n" +
+            "\n" +
+            "/** How an `AvClient` reaches its deployment (§15.2, §15.7). */\n" +
+            "export interface AvClientOptions {\n" +
+            "\t/** Another deployment serving exactly the same ClientContract; the generated default otherwise. */\n" +
+            "\treadonly entrypoint?: string;\n" +
+            "\t/** A custom fetch — authentication, tests; the platform's otherwise. */\n" +
+            "\treadonly fetch?: Fetch;\n" +
+            "}\n" +
+            "\n" +
+            "type Grammar = OperationGrammar<ClientContractShape>;\n" +
+            "type Resource = ResourceKey<ClientContractShape>;\n" +
+            "\n" +
+            "/** `avClient.<resource>.<family>.<variant>(args, options?)`: one call per advertised operation. */\n" +
+            surface("AvClientSurface", "OperationCall<\n" +
+                "\t\t\t\tClientContractShape,\n" +
+                "\t\t\t\tR,\n" +
+                "\t\t\t\tGrammar[R][F][V] & OperationIdentity,\n" +
+                "\t\t\t\tClientScalarForms,\n" +
+                "\t\t\t\tClientScalarForms,\n" +
+                '\t\t\t\t"data",\n' +
+                "\t\t\t\tCallOptions\n" +
+                "\t\t\t>") +
+            (interactive
+                ? "\n" +
+                    "/** `avClient.tx.<resource>.<family>.<variant>(args)`: a deferred handle; no request (§14.1). */\n" +
+                    surface("AvTxSurface", "DeferredOperationCall<\n" +
+                        "\t\t\t\tClientContractShape,\n" +
+                        "\t\t\t\tR,\n" +
+                        "\t\t\t\tGrammar[R][F][V] & OperationIdentity,\n" +
+                        "\t\t\t\tClientScalarForms,\n" +
+                        "\t\t\t\tClientScalarForms\n" +
+                        "\t\t\t>") +
+                    "\n" +
+                    "/** Sends the handles as one plan and resolves their results as a typed tuple (§14.1). */\n" +
+                    "type TransactionCall = <const Steps extends readonly Operation<unknown>[]>(\n" +
+                    "\tsteps: Steps,\n" +
+                    "\toptions?: CallOptions,\n" +
+                    ") => Promise<TransactionResults<Steps>>;\n"
+                : "") +
+            "\n" +
+            "/** The generated client: one property per Resource this deployment's ClientContract advertises. */\n" +
+            "export interface AvClient extends AvClientSurface {}\n" +
+            "\n" +
+            "/** The generated client (§15.4). */\n" +
+            "export class AvClient {\n" +
+            (interactive
+                ? "\t/** Deferred operations, for `transaction` (§14.1). */\n" +
+                    "\tdeclare readonly tx: AvTxSurface;\n" +
+                    "\t/** Runs deferred operations as one transaction (§14.1). */\n" +
+                    "\tdeclare readonly transaction: TransactionCall;\n" +
+                    "\n"
+                : "") +
+            "\tconstructor(options: AvClientOptions = {}) {\n" +
+            '\t\tconst entrypoint = (options.entrypoint ?? DEFAULT_ENTRYPOINT).replace(/\\/+$/, "");\n' +
+            "\t\tconst given = options.fetch;\n" +
+            "\t\tconst connect = (): TransportConnection => ({ entrypoint, fetch: platformFetch(given) });\n" +
+            "\t\tfor (const [resource, families] of operationTree(\n" +
+            "\t\t\t(resource, family, variant): OperationMethod =>\n" +
+            "\t\t\t\tasync (args = {}, callOptions = {}) =>\n" +
+            "\t\t\t\t\texecute(connect(), resource, family, variant, args, callOptions),\n" +
+            "\t\t)) {\n" +
+            "\t\t\tObject.defineProperty(this, propertyOf(resource), { value: families, enumerable: true });\n" +
+            "\t\t}\n" +
+            (interactive
+                ? "\t\tconst deferred: object = Object.create(null);\n" +
+                    "\t\tfor (const [resource, families] of operationTree(\n" +
+                    "\t\t\t(resource, family, variant) =>\n" +
+                    "\t\t\t\t(args: unknown = {}): object =>\n" +
+                    "\t\t\t\t\tdeferOperation(resource, family, variant, args),\n" +
+                    "\t\t)) {\n" +
+                    "\t\t\tObject.defineProperty(deferred, propertyOf(resource), { value: families, enumerable: true });\n" +
+                    "\t\t}\n" +
+                    '\t\tObject.defineProperty(this, "tx", { value: Object.freeze(deferred) });\n' +
+                    '\t\tObject.defineProperty(this, "transaction", {\n' +
+                    "\t\t\tvalue: async (steps: unknown, callOptions: CallOptions = {}) =>\n" +
+                    "\t\t\t\trunTransaction(connect(), steps, callOptions),\n" +
+                    "\t\t});\n"
+                : "") +
+            "\t}\n" +
+            "}\n" +
+            "\n" +
+            "/**\n" +
+            " * One frozen object per Resource, one per family under it, one member per\n" +
+            " * advertised variant (P4) — by wire name; the caller places each Resource.\n" +
+            " */\n" +
+            "function operationTree<M>(member: (resource: string, family: string, variant: string) => M): Map<string, object> {\n" +
+            "\tconst resources = new Map<string, Map<string, Record<string, M>>>();\n" +
+            "\tfor (const [resource, family, variant] of ADVERTISED_OPERATIONS) {\n" +
+            "\t\tconst families = resources.get(resource) ?? new Map<string, Record<string, M>>();\n" +
+            "\t\tresources.set(resource, families);\n" +
+            "\t\tconst variants = families.get(family) ?? (Object.create(null) as Record<string, M>);\n" +
+            "\t\tfamilies.set(family, variants);\n" +
+            "\t\tvariants[variant] = member(resource, family, variant);\n" +
+            "\t}\n" +
+            "\treturn new Map(\n" +
+            "\t\t[...resources].map(([resource, families]) => [\n" +
+            "\t\t\tresource,\n" +
+            "\t\t\tObject.freeze(Object.fromEntries([...families].map(([family, variants]) => [family, Object.freeze(variants)]))),\n" +
+            "\t\t]),\n" +
+            "\t);\n" +
+            "}\n" +
+            "\n" +
+            "/** One advertised operation, as the runtime calls it: the types are the surface's. */\n" +
+            "type OperationMethod = (args?: Readonly<Record<string, unknown>>, options?: CallOptions) => Promise<unknown>;\n" +
+            "\n" +
+            "/** The Resources reached by a property other than their wire name (Q12). */\n" +
+            `const RENAMED_PROPERTIES: Readonly<Record<string, string>> = {${renamedEntries}};\n` +
+            "\n" +
+            "/** The client's property for a Resource: its wire name, unless that is one of the client's own members. */\n" +
+            "function propertyOf(resource: string): string {\n" +
+            "\treturn Object.hasOwn(RENAMED_PROPERTIES, resource) ? (RENAMED_PROPERTIES[resource] ?? resource) : resource;\n" +
+            "}\n" +
+            "\n" +
+            "/**\n" +
+            " * The fetch a call uses (§15.7): the one the client was given, else the\n" +
+            " * platform's, read when the call is made — so importing the client never\n" +
+            " * fails where there is no fetch, and a call does, saying why.\n" +
+            " */\n" +
+            "function platformFetch(given: Fetch | undefined): Fetch {\n" +
+            "\tconst found = given ?? (globalThis as { readonly fetch?: Fetch }).fetch;\n" +
+            '\tif (typeof found !== "function") {\n' +
+            '\t\tthrow new TypeError("No fetch is available here; pass one: new AvClient({ fetch }) (§15.7).");\n' +
+            "\t}\n" +
+            "\treturn found;\n" +
+            "}\n" +
+            "\n" +
+            "/** The client of the deployment this tree was generated from. */\n" +
+            "const avClient: AvClient = new AvClient();\n" +
+            "export default avClient;\n" +
+            "\n" +
+            "type Identity<F extends OperationFamily, V extends string> = Extract<\n" +
+            "\tOperationIdentity,\n" +
+            "\t{ readonly family: F; readonly variant: V }\n" +
+            ">;\n" +
+            "\n" +
+            "/** A Resource's default record — `find.unique` with no projection (§15.6, Q10). */\n" +
+            "export type ResourceRecord<R extends Resource> = AdmittedOperationResult<\n" +
+            "\tClientContractShape,\n" +
+            "\tR,\n" +
+            '\tIdentity<"find", "unique">,\n' +
+            "\tunknown,\n" +
+            "\tClientScalarForms\n" +
+            ">;\n" +
+            "\n" +
+            "/** One argument of one of a Resource's operations, present (§15.6, Q10). */\n" +
+            "export type ResourceArgument<\n" +
+            "\tR extends Resource,\n" +
+            "\tF extends OperationFamily,\n" +
+            "\tV extends string,\n" +
+            "\tK extends string,\n" +
+            "> = ArgumentOf<\n" +
+            "\tOperationArgumentsFor<ClientContractShape, R, Identity<F, V>, ClientScalarForms>,\n" +
+            "\tK\n" +
+            ">;\n" +
+            "\n" +
+            "type ArgumentOf<Args, K extends string> = K extends keyof Args\n" +
+            "\t? Exclude<Args[K], undefined>\n" +
+            "\t: never;\n",
+    };
+}

package/dist/emit/client-tree.emitter.d.ts

@@ -0,0 +1,37 @@
+import type { ClientContract } from "@aventara/core";
+import type { ClientEntrypoint } from "../config/client-config.interface.js";
+import { type ClientEmission } from "./emitted-tree.interface.js";
+/**
+ * §15.3's emit steps over an accepted ClientContract, as one value (plan §7).
+ *
+ * The banner, the encoding and the file order are applied HERE, once, over every
+ * module — so no emitter can forget the banner, and byte-equality is a property
+ * of this function rather than of each emitter's care (C-843):
+ *
+ * - every module opens with the generated banner (M17);
+ * - every file is UTF-8;
+ * - the layout is the architect's (2026-10-04): `AvClient.ts` at the root of
+ *   `generateAt`, every other module under `generated/`;
+ * - files come in UTF-16 code-unit order of their path, each path once.
+ *
+ * The name derivation's rename warnings ride on the result beside the tree; this
+ * function prints nothing.
+ *
+ * The names and enums read the enum registry, registry NAMES and `protocol`.
+ * Core's derivation is copied under `generated/derivation/` as its published
+ * declarations (Q1 = A, `derivation.emitter.ts`): read from the installed
+ * `@aventara/core`, never from the Contract. The contract itself reaches the
+ * tree as three projections of the one accepted contract (plan §6): the carrier
+ * `generated/contract.ts` (Q4), the runtime's decode table and advertised
+ * operations `generated/runtime/descriptor.ts` (P1, P4), and `metadata.ts`'s
+ * hash, version and default entrypoint (Q5) — the entrypoint being the run's
+ * other input.
+ *
+ * The runtime (`generated/runtime/codec.ts`, `decimal.ts`, `errors.ts`,
+ * `transport.ts`) reads nothing of the Contract at all: §6.2's codecs and
+ * §13's codes are fixed by protocol version (M10, Q3), and the transport sends
+ * the operation its caller names.
+ *
+ * @throws GeneratedNameError when a name cannot be emitted, even renamed.
+ */
+export declare function emitClientTree(contract: ClientContract, entrypoint: ClientEntrypoint): ClientEmission;

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

@@ -0,0 +1,103 @@
+import { 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 { emitDescriptorModule } from "./descriptor.emitter.js";
+import { CLIENT_ENTRY_FILE, GENERATED_DIRECTORY, } from "./emitted-tree.interface.js";
+import { emitEnumsModule } from "./enum.emitter.js";
+import { deriveEmittedNames } from "./name.deriver.js";
+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";
+/**
+ * §15.3's emit steps over an accepted ClientContract, as one value (plan §7).
+ *
+ * The banner, the encoding and the file order are applied HERE, once, over every
+ * module — so no emitter can forget the banner, and byte-equality is a property
+ * of this function rather than of each emitter's care (C-843):
+ *
+ * - every module opens with the generated banner (M17);
+ * - every file is UTF-8;
+ * - the layout is the architect's (2026-10-04): `AvClient.ts` at the root of
+ *   `generateAt`, every other module under `generated/`;
+ * - files come in UTF-16 code-unit order of their path, each path once.
+ *
+ * The name derivation's rename warnings ride on the result beside the tree; this
+ * function prints nothing.
+ *
+ * The names and enums read the enum registry, registry NAMES and `protocol`.
+ * Core's derivation is copied under `generated/derivation/` as its published
+ * declarations (Q1 = A, `derivation.emitter.ts`): read from the installed
+ * `@aventara/core`, never from the Contract. The contract itself reaches the
+ * tree as three projections of the one accepted contract (plan §6): the carrier
+ * `generated/contract.ts` (Q4), the runtime's decode table and advertised
+ * operations `generated/runtime/descriptor.ts` (P1, P4), and `metadata.ts`'s
+ * hash, version and default entrypoint (Q5) — the entrypoint being the run's
+ * other input.
+ *
+ * The runtime (`generated/runtime/codec.ts`, `decimal.ts`, `errors.ts`,
+ * `transport.ts`) reads nothing of the Contract at all: §6.2's codecs and
+ * §13's codes are fixed by protocol version (M10, Q3), and the transport sends
+ * the operation its caller names.
+ *
+ * @throws GeneratedNameError when a name cannot be emitted, even renamed.
+ */
+export function emitClientTree(contract, entrypoint) {
+    const names = deriveEmittedNames(contract);
+    const generated = [
+        ...emitDerivationModules(),
+        emitClientSurfaceModule(contract, names),
+        emitContractCarrierModule(contract),
+        emitDescriptorModule(contract),
+        emitEnumsModule(contract, names),
+        emitMetadataModule(contract.protocol, entrypoint),
+        emitScalarCodecModule(),
+        emitDecimalModule(),
+        emitErrorsModule(),
+        emitTransportModule(),
+        emitNamedTypesModule(contract, names),
+        // P3: the builder and runner exist iff transactions are interactive.
+        ...(contract.transactions === "interactive"
+            ? emitTransactionModules()
+            : []),
+    ];
+    const files = [
+        { path: CLIENT_ENTRY_FILE, source: clientEntrySource() },
+        ...generated.map((module) => ({
+            path: `${GENERATED_DIRECTORY}/${module.path}`,
+            source: module.source,
+        })),
+    ];
+    const encoder = new TextEncoder();
+    const tree = [...files]
+        .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)),
+    }));
+    return { tree, warnings: names.warnings };
+}
+/**
+ * `AvClient.ts`, the entry point a consumer imports (§15.4; Phase 12-rest Q7):
+ * the ready client `avClient` as the DEFAULT export, and as named exports the
+ * class `AvClient`, `AvClientOptions`, `CallOptions`, `Fetch`, `Operation<T>`,
+ * the named Resource types, the enums, `Decimal`, the errors and the code unions —
+ * re-exported from `generated/`. Never the transport's primitive (Q1 = B), never
+ * the derived forms map (Q3: internal).
+ *
+ *     import avClient, { AvClient, User, UserWhere } from "./AvClient";
+ */
+function clientEntrySource() {
+    const from = (module) => JSON.stringify(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, ".js")}`);
+    return (`export { default } from ${from("client.ts")};\n` +
+        `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype CallOptions,\n} from ${from("client.ts")};\n` +
+        `export type { Fetch } from ${from("runtime/transport.ts")};\n` +
+        `export type { Operation } from ${from("derivation/transactions/deferred-operation.d.ts")};\n` +
+        `export type * from ${from("types.d.ts")};\n` +
+        `export * from ${from("enums.ts")};\n` +
+        `export { Decimal } from ${from("runtime/decimal.ts")};\n` +
+        `export {\n${errorsModuleExports()
+            .map((name) => `\t${name},\n`)
+            .join("")}} from ${from("runtime/errors.ts")};\n`);
+}

package/dist/emit/contract-carrier.emitter.d.ts

@@ -0,0 +1,13 @@
+import { type ClientContract } from "@aventara/core";
+import type { EmittedModule } from "./emitted-tree.interface.js";
+/** `generated/contract.ts`, before the banner. */
+export declare function emitContractCarrierModule(contract: ClientContract): EmittedModule;
+/**
+ * The ClientContract a carrier file holds — its whole text, banner included —
+ * or `undefined` when it is not one this generator wrote over a contract that
+ * still verifies: a foreign prefix or suffix, bytes that are not JSON, a body
+ * that is not a ClientContract or whose hash does not re-verify, or bytes that
+ * are not that contract's canonical form. Never trusted otherwise (Q6: a carrier
+ * that does not re-hash is treated as absent).
+ */
+export declare function parseContractCarrier(text: string): Promise<ClientContract | undefined>;