@aventara/client 0.1.0-pilot.1 → 0.1.0-pilot.2

package/dist/contract/contract.acceptance.d.ts

@@ -1,9 +1,5 @@
 import { type ClientContract } from "@aventara/core";
 /**
- * §15.3's validation steps over a fetched body, in the specification's order, as
- * one decision (plan §7, group 2): protocol support (§19.1), then ClientContract
- * structure, then the advertised hash recomputed and compared (§19.2).
- *
  * # The structure check is core's, never a second implementation
  *
  * What a ClientContract IS belongs to core, so the structure step is core's
@@ -22,39 +18,29 @@ import { type ClientContract } from "@aventara/core";
  *
  * # A value, not a throw site
  *
- * M3's rule — failure is a message and an exit code, never a stack — needs both to
- * be typed members, so a rejection is the `ContractRejected` arm carrying its
- * sentence and its exit code, and `ContractProtocolError` is built from it only
- * where generation stops.
- *
  * # The hash is core's, never a second implementation
  *
  * The advertised `protocol.hash` is recomputed with `computeClientContractHash` —
- * the function the compiler stamps it with (M6a) — and compared. A hash computed
- * here would be a second source of the Contract's identity.
- *
- * # Bodies the hash cannot be recomputed over (S0)
+ * the function the compiler stamps it with — and compared. A hash computed here
+ * would be a second source of the Contract's identity.
  *
  * The ClientContract type admits values RFC 8785 cannot encode, and a valid JSON
- * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses to
- * a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can have
- * stamped a hash over such a body — its own canonicalizer would have refused — so it
- * is refused at THIS step, as `hash-mismatch` with its own sentence and core's path,
- * never let escape as a stack. Both values are ones the ClientContract TYPE admits
- * (`number`, `string`), so core's structure check accepts them by design; what
- * fails is §19.2's recompute. ONLY that class is caught: anything else thrown while
- * hashing is not a known property of the input, and keeps its stack as a defect.
+ * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses
+ * to a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can
+ * have stamped a hash over such a body — its own canonicalizer would have refused
+ * — so it is refused at THIS step, as `hash-mismatch` with its own sentence and
+ * core's path, never let escape as a stack. ONLY that class is caught: anything
+ * else thrown while hashing is not a known property of the input, and keeps its
+ * stack as a defect.
  */
-/** The protocol versions this generator speaks (§19.1: support is explicit). */
+/** The protocol versions this generator speaks. */
 export declare const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet<number>;
-/** Closed at three (plan §7): §19.1, §19.2, and §15.3's structure step. */
 export type ContractRejectionReason = "protocol-unsupported" | "hash-mismatch" | "structure-invalid";
 export type ContractAccepted = {
     readonly accepted: true;
     /**
-     * Trusted to the depth this step checks: core's structure check and the hash.
-     * It is the erased ClientContract (ADR 0009): no capability is interpreted here
-     * (plan §1).
+     * Trusted to the depth this step checks: core's structure check and the hash. It
+     * is the erased ClientContract: no capability is interpreted here.
      */
     readonly contract: ClientContract;
 };

package/dist/contract/contract.acceptance.js

@@ -1,55 +1,7 @@
 import { AVENTARA_PROTOCOL_VERSION, CanonicalJsonError, computeClientContractHash, validateClientContractStructure, } from "@aventara/core";
-/**
- * §15.3's validation steps over a fetched body, in the specification's order, as
- * one decision (plan §7, group 2): protocol support (§19.1), then ClientContract
- * structure, then the advertised hash recomputed and compared (§19.2).
- *
- * # The structure check is core's, never a second implementation
- *
- * What a ClientContract IS belongs to core, so the structure step is core's
- * `validateClientContractStructure` and nothing here restates a member, a kind or
- * a vocabulary. Before it, a body with a valid envelope and a malformed member —
- * `resources: { Spell: 5 }` — reached core's canonicalizer, which reads members
- * without validating them, and escaped as a plain `TypeError` and a stack.
- *
- * # Protocol support is judged first, from a read rather than a rule
- *
- * A body from a protocol this generator does not speak may have a different
- * structure, and "unsupported" is then the true and useful answer. So the
- * advertised version is READ — leniently, never judged — and judged against the
- * supported set before any structure is. A body whose version cannot be read at
- * all goes on to the structure step, which names what is wrong with it.
- *
- * # A value, not a throw site
- *
- * M3's rule — failure is a message and an exit code, never a stack — needs both to
- * be typed members, so a rejection is the `ContractRejected` arm carrying its
- * sentence and its exit code, and `ContractProtocolError` is built from it only
- * where generation stops.
- *
- * # The hash is core's, never a second implementation
- *
- * The advertised `protocol.hash` is recomputed with `computeClientContractHash` —
- * the function the compiler stamps it with (M6a) — and compared. A hash computed
- * here would be a second source of the Contract's identity.
- *
- * # Bodies the hash cannot be recomputed over (S0)
- *
- * The ClientContract type admits values RFC 8785 cannot encode, and a valid JSON
- * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses to
- * a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can have
- * stamped a hash over such a body — its own canonicalizer would have refused — so it
- * is refused at THIS step, as `hash-mismatch` with its own sentence and core's path,
- * never let escape as a stack. Both values are ones the ClientContract TYPE admits
- * (`number`, `string`), so core's structure check accepts them by design; what
- * fails is §19.2's recompute. ONLY that class is caught: anything else thrown while
- * hashing is not a known property of the input, and keeps its stack as a defect.
- */
-/** The protocol versions this generator speaks (§19.1: support is explicit). */
 export const SUPPORTED_PROTOCOL_VERSIONS = new Set([
     AVENTARA_PROTOCOL_VERSION,
 ]);
-/** A refused contract stops generation; the adapter CLI's precedent is 1 (M3). */
 const REFUSED_EXIT_CODE = 1;
 const CHECK_ENTRYPOINT = "Check that the entrypoint is the deployed Aventara entrypoint (origin plus mount path).";
 export async function acceptClientContract(body) {
@@ -84,7 +36,6 @@ export async function acceptClientContract(body) {
     }
     return { accepted: true, contract };
 }
-/** The refusal that stops generation, carrying the rejection's reason and sentence. */
 export class ContractProtocolError extends Error {
     name = "ContractProtocolError";
     reason;
@@ -95,11 +46,6 @@ export class ContractProtocolError extends Error {
         this.exitCode = rejection.exitCode;
     }
 }
-/**
- * `protocol.version` where the body states a number there, `undefined` otherwise.
- * A read, not a rule: it judges nothing, and a body it cannot read a version from
- * is left for the structure step to describe.
- */
 function advertisedProtocolVersion(body) {
     if (!isJsonObject(body) || !Object.hasOwn(body, "protocol")) {
         return undefined;

package/dist/contract/contract.fetcher.d.ts

@@ -1,19 +1,14 @@
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 /**
- * §12.5's discovery request: one `GET <entrypoint>/_contract`, with no headers —
- * §12.4: *"The contract GET itself requires neither header because it is the
- * discovery mechanism."* The entrypoint is the CLIENT config's URL (§15.2,
- * resolved in S2), not the server's mount-path setting.
- *
  * # Transport, and only transport
  *
  * This file's success is "a JSON value arrived". It does not judge the value: a
  * body that is a JSON array is still a successful fetch, and refusing it is
- * `contract.acceptance.ts`'s job. Every way of failing to produce a JSON value is a
- * `ContractTransportError`, a different class from `ContractProtocolError`,
- * because the two have different remedies — reach the deployment, versus regenerate
- * or upgrade against what it served — and a message that blurs them sends the
- * developer to the wrong one.
+ * `contract.acceptance.ts`'s job. Every way of failing to produce a JSON value is
+ * a `ContractTransportError`, a different class from `ContractProtocolError`,
+ * because the two have different remedies — reach the deployment, versus
+ * regenerate or upgrade against what it served — and a message that blurs them
+ * sends the developer to the wrong one.
  *
  * `fetch` is injected, so the transport is tested without a server; the default is
  * the platform's.
@@ -26,8 +21,8 @@ export type ContractFetch = (url: URL, init: {
     readonly headers?: Readonly<Record<string, string>>;
 }) => Promise<ContractResponse>;
 /**
- * What a conditional GET answers when the served ClientContract is the one named
- * (`304 Not Modified`, Phase 10 Q8): no body, nothing to judge.
+ * What a conditional GET answers when the served ClientContract is the one named:
+ * no body, nothing to judge.
  */
 export declare const CONTRACT_NOT_MODIFIED: unique symbol;
 export type ContractTransportFailureReason = 
@@ -46,9 +41,9 @@ export declare class ContractTransportError extends Error {
 }
 /**
  * `<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`.
+ * The path's canonical form is resolution's — 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 declare function contractUrlOf(entrypoint: ClientEntrypoint): URL;
 /** The URL as it may be printed: credentials in the entrypoint never are. */
@@ -56,8 +51,8 @@ export declare function displayUrl(url: URL): string;
 /**
  * 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.
+ * the deployment answers `304`, {@link CONTRACT_NOT_MODIFIED}. A `304` to a
+ * request that sent none is no answer, like any other non-2xx.
  *
  * @throws ContractTransportError when no JSON value arrives.
  */

package/dist/contract/contract.fetcher.js

@@ -1,7 +1,3 @@
-/**
- * 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;
@@ -11,32 +7,17 @@ export class ContractTransportError extends Error {
         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);
@@ -67,14 +48,9 @@ export async function fetchClientContractBody(entrypoint, fetch = globalThis.fet
         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);

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

@@ -2,12 +2,11 @@ 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`.
+ * 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). */
+    /** The client config's resolved entrypoint. */
     readonly entrypoint: ClientEntrypoint;
     /** Injected for tests; the platform `fetch` otherwise. */
     readonly fetch?: ContractFetch;
@@ -17,7 +16,7 @@ export interface ClientContractLoadInput {
  * @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). */
+/** A ClientContract loaded against one the caller already holds. */
 export interface ClientContractSince {
     readonly contract: ClientContract;
     /** The deployment answered `304`: `contract` is the one the caller held. */

package/dist/contract/contract.loader.js

@@ -1,18 +1,8 @@
 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 };

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

@@ -1,22 +1,21 @@
 /**
- * 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.
+ * 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 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 ownership banner every emitted file opens with.
  *
- * 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.
+ * The Biome suppressions are EMITTED rather than configured, 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).
+ * generator version, no host, no path — any of them would break the exit gate's
+ * byte-equality on the first re-run. And no driver prose.
  */
 export declare const GENERATED_BANNER: readonly string[];
 /** `source` with the banner before it and one blank line between. */

package/dist/emit/banner.emitter.js

@@ -1,40 +1,14 @@
-/**
- * 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)

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

@@ -1,32 +1,28 @@
 import type { ClientContract } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.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).
+ * `generated/client.ts` — the typed surface: the class `AvClient`, its options
+ * `AvClientOptions` and the per-call `CallOptions`, and the ready instance
+ * `avClient`, this module's default export.
  *
  * 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`.
+ * copied under `generated/derivation/`: the call grammar over the carrier's
+ * contract, in the client's forms. Nothing here re-spells a rule. A call resolves
+ * to the 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.
+ * Each surface is one mapped alias over the one contract. A Resource is reached by
+ * its contract name, except where that name is one of the client's own members,
+ * which renames the property only. `tx` and `transaction` exist iff the contract
+ * advertises `interactive` transactions, 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`.
+ * aliases of: `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.
+ * At runtime the class builds one frozen object per Resource from the advertised
+ * operations — 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 unless the options name another.
  */
-export declare function emitClientSurfaceModule(contract: ClientContract, names: EmittedNames): EmittedModule;
+export declare function emitClientSurfaceModule(contract: ClientContract, names: EmittedNames, style: ClientModuleStyle): EmittedModule;

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

@@ -1,33 +1,7 @@
+import { importSpecifier, } from "./module-style.interface.js";
 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) {
+export function emitClientSurfaceModule(contract, names, style) {
+    const from = (module) => JSON.stringify(importSpecifier(module, style));
     const renamed = names.properties.filter((property) => property.property !== property.contractName);
     const propertyOf = renamed.length === 0
         ? "R"
@@ -48,34 +22,34 @@ export function emitClientSurfaceModule(contract, names) {
         "};\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' +
+        source: `import type { ClientContractShape } from ${from("./contract")};\n` +
+            `import type { ApplicationScalarForms } from ${from("./derivation/contracts/scalar-value-type")};\n` +
+            `import type { OperationArgumentsFor, ResourceKey } from ${from("./derivation/operations/operation-arguments")};\n` +
+            `import type { ${interactive ? "DeferredOperationCall, " : ""}OperationCall, OperationGrammar } from ${from("./derivation/operations/operation-call")};\n` +
+            `import type { OperationFamily, OperationIdentity } from ${from("./derivation/operations/operation-identity")};\n` +
+            `import type { AdmittedOperationResult } from ${from("./derivation/operations/operation-result")};\n` +
             (interactive
-                ? 'import type { Operation, TransactionResults } from "./derivation/transactions/deferred-operation.js";\n'
+                ? `import type { Operation, TransactionResults } from ${from("./derivation/transactions/deferred-operation")};\n`
                 : "") +
-            'import { DEFAULT_ENTRYPOINT } from "./metadata.js";\n' +
-            'import type { Decimal } from "./runtime/decimal.js";\n' +
-            'import { ADVERTISED_OPERATIONS } from "./runtime/descriptor.js";\n' +
+            `import { DEFAULT_ENTRYPOINT } from ${from("./metadata")};\n` +
+            `import type { Decimal } from ${from("./runtime/decimal")};\n` +
+            `import { ADVERTISED_OPERATIONS } from ${from("./runtime/descriptor")};\n` +
             (interactive
-                ? 'import { deferOperation, runTransaction } from "./runtime/transaction.js";\n'
+                ? `import { deferOperation, runTransaction } from ${from("./runtime/transaction")};\n`
                 : "") +
-            'import { type CallOptions, execute, type Fetch, type TransportConnection } from "./runtime/transport.js";\n' +
+            `import { type CallOptions, execute, type Fetch, type TransportConnection } from ${from("./runtime/transport")};\n` +
             "\n" +
-            'export type { CallOptions } from "./runtime/transport.js";\n' +
+            `export type { CallOptions } from ${from("./runtime/transport")};\n` +
             "\n" +
             "/**\n" +
-            " * The forms this client reads and writes (§6.2, Q3): core's application forms —\n" +
+            " * The forms this client reads and writes: 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" +
+            "/** How an `AvClient` reaches its deployment. */\n" +
             "export interface AvClientOptions {\n" +
             "\t/** Another deployment serving exactly the same ClientContract; the generated default otherwise. */\n" +
             "\treadonly entrypoint?: string;\n" +
@@ -98,7 +72,7 @@ export function emitClientSurfaceModule(contract, names) {
                 "\t\t\t>") +
             (interactive
                 ? "\n" +
-                    "/** `avClient.tx.<resource>.<family>.<variant>(args)`: a deferred handle; no request (§14.1). */\n" +
+                    "/** `avClient.tx.<resource>.<family>.<variant>(args)`: a deferred handle; no request. */\n" +
                     surface("AvTxSurface", "DeferredOperationCall<\n" +
                         "\t\t\t\tClientContractShape,\n" +
                         "\t\t\t\tR,\n" +
@@ -107,7 +81,7 @@ export function emitClientSurfaceModule(contract, names) {
                         "\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" +
+                    "/** Sends the handles as one plan and resolves their results as a typed tuple. */\n" +
                     "type TransactionCall = <const Steps extends readonly Operation<unknown>[]>(\n" +
                     "\tsteps: Steps,\n" +
                     "\toptions?: CallOptions,\n" +
@@ -117,12 +91,12 @@ export function emitClientSurfaceModule(contract, names) {
             "/** 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" +
+            "/** The generated client. */\n" +
             "export class AvClient {\n" +
             (interactive
-                ? "\t/** Deferred operations, for `transaction` (§14.1). */\n" +
+                ? "\t/** Deferred operations, for `transaction`. */\n" +
                     "\tdeclare readonly tx: AvTxSurface;\n" +
-                    "\t/** Runs deferred operations as one transaction (§14.1). */\n" +
+                    "\t/** Runs deferred operations as one transaction. */\n" +
                     "\tdeclare readonly transaction: TransactionCall;\n" +
                     "\n"
                 : "") +
@@ -157,7 +131,7 @@ export function emitClientSurfaceModule(contract, names) {
             "\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" +
+            " * advertised variant — 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" +
@@ -179,7 +153,7 @@ export function emitClientSurfaceModule(contract, names) {
             "/** 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" +
+            "/** The Resources reached by a property other than their wire name. */\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" +
@@ -188,14 +162,14 @@ export function emitClientSurfaceModule(contract, names) {
             "}\n" +
             "\n" +
             "/**\n" +
-            " * The fetch a call uses (§15.7): the one the client was given, else the\n" +
+            " * The fetch a call uses: 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\tthrow new TypeError("No fetch is available here; pass one: new AvClient({ fetch }).");\n' +
             "\t}\n" +
             "\treturn found;\n" +
             "}\n" +
@@ -209,7 +183,7 @@ export function emitClientSurfaceModule(contract, names) {
             "\t{ readonly family: F; readonly variant: V }\n" +
             ">;\n" +
             "\n" +
-            "/** A Resource's default record — `find.unique` with no projection (§15.6, Q10). */\n" +
+            "/** A Resource's default record — `find.unique` with no projection. */\n" +
             "export type ResourceRecord<R extends Resource> = AdmittedOperationResult<\n" +
             "\tClientContractShape,\n" +
             "\tR,\n" +
@@ -218,7 +192,7 @@ export function emitClientSurfaceModule(contract, names) {
             "\tClientScalarForms\n" +
             ">;\n" +
             "\n" +
-            "/** One argument of one of a Resource's operations, present (§15.6, Q10). */\n" +
+            "/** One argument of one of a Resource's operations, present. */\n" +
             "export type ResourceArgument<\n" +
             "\tR extends Resource,\n" +
             "\tF extends OperationFamily,\n" +