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

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" +

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

@@ -1,17 +1,14 @@
 import type { ClientContract } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import { type ClientEmission } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.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):
+ * module — so no emitter can forget the banner, and byte-equality is a property of
+ * this function rather than of each emitter's care:
  *
- * - every module opens with the generated banner (M17);
+ * - every module opens with the generated banner;
  * - 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
@@ -19,19 +16,13 @@ import { type ClientEmission } from "./emitted-tree.interface.js";
  *
  * 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.
+ * declarations: read from the installed `@aventara/core`, never from the Contract.
+ * The contract itself reaches the tree as three projections of the one accepted
+ * contract: the carrier `generated/contract.ts`, the runtime's decode table and
+ * advertised operations `generated/runtime/descriptor.ts`, and `metadata.ts`'s
+ * hash, version and default entrypoint — the entrypoint being the run's other
+ * input.
  *
  * @throws GeneratedNameError when a name cannot be emitted, even renamed.
  */
-export declare function emitClientTree(contract: ClientContract, entrypoint: ClientEntrypoint): ClientEmission;
+export declare function emitClientTree(contract: ClientContract, entrypoint: ClientEntrypoint, style: ClientModuleStyle): ClientEmission;

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

@@ -5,65 +5,32 @@ 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 { moduleSpecifierWriter, } from "./module-style.interface.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) {
+export function emitClientTree(contract, entrypoint, style) {
     const names = deriveEmittedNames(contract);
     const generated = [
         ...emitDerivationModules(),
-        emitClientSurfaceModule(contract, names),
+        emitClientSurfaceModule(contract, names, style),
         emitContractCarrierModule(contract),
         emitDescriptorModule(contract),
         emitEnumsModule(contract, names),
         emitMetadataModule(contract.protocol, entrypoint),
-        emitScalarCodecModule(),
+        emitScalarCodecModule(style),
         emitDecimalModule(),
         emitErrorsModule(),
-        emitTransportModule(),
-        emitNamedTypesModule(contract, names),
-        // P3: the builder and runner exist iff transactions are interactive.
+        emitTransportModule(style),
+        emitNamedTypesModule(contract, names, style),
         ...(contract.transactions === "interactive"
-            ? emitTransactionModules()
+            ? emitTransactionModules(style)
             : []),
     ];
     const files = [
-        { path: CLIENT_ENTRY_FILE, source: clientEntrySource() },
+        { path: CLIENT_ENTRY_FILE, source: clientEntrySource(style) },
         ...generated.map((module) => ({
             path: `${GENERATED_DIRECTORY}/${module.path}`,
             source: module.source,
@@ -76,20 +43,11 @@ export function emitClientTree(contract, entrypoint) {
         path: file.path,
         bytes: encoder.encode(withGeneratedBanner(file.source)),
     }));
-    return { tree, warnings: names.warnings };
+    return { tree, style, 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")}`);
+function clientEntrySource(style) {
+    const specifier = moduleSpecifierWriter(style);
+    const from = (module) => specifier(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
     return (`export { default } from ${from("client.ts")};\n` +
         `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype CallOptions,\n} from ${from("client.ts")};\n` +
         `export type { Fetch } from ${from("runtime/transport.ts")};\n` +

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

@@ -3,11 +3,10 @@ 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).
+ * 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.
  */
 export declare function parseContractCarrier(text: string): Promise<ClientContract | undefined>;

package/dist/emit/contract-carrier.emitter.js

@@ -1,42 +1,14 @@
 import { canonicalizeContract } from "@aventara/core";
 import { acceptClientContract } from "../contract/contract.acceptance.js";
 import { withGeneratedBanner } from "./banner.emitter.js";
-/**
- * The carrier (Q4 = A): `generated/contract.ts` holds the ClientContract the
- * client was generated against, as its served canonical bytes (RFC 8785, §19.2)
- * verbatim — which are a valid TypeScript type literal (plan M4):
- *
- * ```ts
- * export type ClientContractShape = {"enums":{},…};
- * ```
- *
- * One artefact, three readers: the derivation's `C` (S4); the generator on a
- * `304` (Q6, S7), which parses it back with {@link parseContractCarrier}; and a
- * person auditing what the client was generated against. It costs no runtime
- * byte — nothing imports it as a value.
- *
- * The bytes are `canonicalizeContract`'s over the ACCEPTED contract: the body a
- * deployment serves is those bytes (`_contract` serves `canonicalizeContract`'s
- * output, and acceptance verified the hash over the same canonical form), and a
- * contract that arrives in another key order still emits them (C-843).
- */
 const CARRIER_PREFIX = "export type ClientContractShape = ";
 const CARRIER_SUFFIX = ";\n";
-/** `generated/contract.ts`, before the banner. */
 export function emitContractCarrierModule(contract) {
     return {
         path: "contract.ts",
         source: `${CARRIER_PREFIX}${canonicalizeContract(contract)}${CARRIER_SUFFIX}`,
     };
 }
-/**
- * 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 async function parseContractCarrier(text) {
     const opening = withGeneratedBanner(CARRIER_PREFIX);
     if (!text.startsWith(opening) || !text.endsWith(CARRIER_SUFFIX)) {

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

@@ -1,14 +1,14 @@
 import type { EmittedModule } from "./emitted-tree.interface.js";
 /**
- * The derivation, transported (Phase 12-rest S2, Q1 = A). A generated client's
- * argument and result types are core's own `OperationArgumentsFor`,
- * `OperationResultFor` and the call grammar (`OperationCall`, …) — never a second
- * spelling. They reach the emitted tree as core's PUBLISHED DECLARATIONS, copied
- * under `generated/derivation/` at their path relative to core's `dist`:
+ * The derivation, transported. A generated client's argument and result types are
+ * core's own `OperationArgumentsFor`, `OperationResultFor` and the call grammar
+ * (`OperationCall`, …) — never a second spelling. They reach the emitted tree as
+ * core's PUBLISHED DECLARATIONS, copied under `generated/derivation/` at their
+ * path relative to core's `dist`:
  *
  * - declarations, not sources: the sources' closure carries value imports (the
- *   canonicaliser, the wire grammars), the declarations' carries none (plan M1);
- *   a `.d.ts` cannot carry runtime, so a bundler never sees one;
+ *   canonicaliser, the wire grammars), the declarations' carries none; a `.d.ts`
+ *   cannot carry runtime, so a bundler never sees one;
  * - under their own directory, so core's `runtime/decimal.d.ts` cannot shadow the
  *   emitted `generated/runtime/decimal.ts`;
  * - byte for byte, except the trailing `//# sourceMappingURL=…` line, which names

package/dist/emit/derivation.emitter.js

@@ -1,34 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-/**
- * The derivation, transported (Phase 12-rest S2, Q1 = A). A generated client's
- * argument and result types are core's own `OperationArgumentsFor`,
- * `OperationResultFor` and the call grammar (`OperationCall`, …) — never a second
- * spelling. They reach the emitted tree as core's PUBLISHED DECLARATIONS, copied
- * under `generated/derivation/` at their path relative to core's `dist`:
- *
- * - declarations, not sources: the sources' closure carries value imports (the
- *   canonicaliser, the wire grammars), the declarations' carries none (plan M1);
- *   a `.d.ts` cannot carry runtime, so a bundler never sees one;
- * - under their own directory, so core's `runtime/decimal.d.ts` cannot shadow the
- *   emitted `generated/runtime/decimal.ts`;
- * - byte for byte, except the trailing `//# sourceMappingURL=…` line, which names
- *   a map the tree does not hold.
- *
- * The closure is walked here, at generation time, from {@link DERIVATION_ROOTS}
- * over whichever `@aventara/core` this package resolves — so the output is a
- * function of the core version the generator depends on, as the rest of it is a
- * function of the generator. A closure that names a package, carries a
- * triple-slash reference, or leaves core's declarations is refused: it cannot be
- * transported, and core's own gate (`emittable-closure.gate.spec.ts`) exists so
- * that it never is.
- */
-/**
- * The modules whose declarations the generated client copies — the roots of core's
- * `emittable-closure.gate.spec.ts`, mirrored (core cannot export a test constant,
- * and this package cannot read core's tests).
- */
+import { scanModuleSpecifiers } from "./module-specifier.scanner.js";
 export const DERIVATION_ROOTS = [
     "contracts/contract",
     "contracts/scalar-value-type",
@@ -39,7 +12,6 @@ export const DERIVATION_ROOTS = [
     "transactions/deferred-operation",
     "transactions/transaction-reference",
 ];
-/** The published declarations of the `@aventara/core` this package resolves. */
 export function publishedCoreDeclarations() {
     const dist = path.dirname(fileURLToPath(import.meta.resolve("@aventara/core")));
     return (relative) => {
@@ -54,13 +26,6 @@ export function publishedCoreDeclarations() {
         }
     };
 }
-/**
- * Core's declaration closure from {@link DERIVATION_ROOTS}, as modules under
- * `derivation/`, in UTF-16 code-unit order of their path.
- *
- * @throws Error when the closure cannot be transported — a defect of the
- *   installed `@aventara/core`, never of the consumer's input.
- */
 export function emitDerivationModules(read = publishedCoreDeclarations()) {
     const copied = new Map();
     const queue = DERIVATION_ROOTS.map((root) => `${root}.d.ts`);
@@ -73,7 +38,7 @@ export function emitDerivationModules(read = publishedCoreDeclarations()) {
         if (text === undefined) {
             throw new Error(`@aventara/core's declaration closure names ${file}, which it does not publish.`);
         }
-        const scanned = scanDeclaration(text);
+        const scanned = scanModuleSpecifiers(text);
         if (scanned.references) {
             throw untransportable(`${file} carries a triple-slash reference, which the emitted tree cannot satisfy`);
         }
@@ -92,10 +57,6 @@ export function emitDerivationModules(read = publishedCoreDeclarations()) {
 function untransportable(reason) {
     return new Error(`@aventara/core's declarations cannot be copied into the generated client: ${reason}.`);
 }
-/**
- * The declaration file a specifier names, relative to core's `dist`: a relative
- * `.js` specifier inside it, as NodeNext resolves an emitted declaration's import.
- */
 function declarationTarget(file, specifier) {
     const leaves = () => untransportable(`${file} names ${JSON.stringify(specifier)}, which is not a declaration file beside it`);
     if (!(specifier.startsWith("./") || specifier.startsWith("../")) ||
@@ -108,126 +69,6 @@ function declarationTarget(file, specifier) {
     }
     return target.replace(/\.js$/, ".d.ts");
 }
-/** `text` without its final `//# sourceMappingURL=…` line, when it ends with one. */
 function withoutSourceMapTrailer(text) {
     return text.replace(/(^|\n)\/\/# sourceMappingURL=[^\n]*\n?$/, "$1");
 }
-/**
- * A word followed directly by a string literal names a module. A pattern, not two
- * string comparisons: the packaging gate reads shipped JavaScript lexically, and
- * a keyword spelled as a quoted literal would read to it as an import.
- */
-const SPECIFIER_KEYWORD = /^(?:from|import)$/;
-/**
- * The specifiers one declaration file names, read by a small lexer rather than
- * by `typescript` (an optional peer, absent from a consumer's install): comments,
- * string literals and template literals are skipped as units, so text inside them
- * is never mistaken for an import. Agrees with TypeScript's own pre-processor
- * over core's closure (`derivation.emitter.spec.ts`).
- */
-function scanDeclaration(text) {
-    const tokens = [];
-    let references = false;
-    let index = 0;
-    const readQuoted = (quote) => {
-        let value = "";
-        index += 1;
-        while (index < text.length && text[index] !== quote) {
-            if (text[index] === "\\") {
-                value += text[index + 1] ?? "";
-                index += 2;
-                continue;
-            }
-            value += text[index];
-            index += 1;
-        }
-        index += 1;
-        return value;
-    };
-    /** Scans code until the end, or until the `}` closing a `${` when `inPlaceholder`. */
-    const scanCode = (inPlaceholder) => {
-        let depth = 0;
-        while (index < text.length) {
-            const character = text[index];
-            const next = text[index + 1];
-            if (character === "/" && next === "/") {
-                const end = text.indexOf("\n", index);
-                const line = text.slice(index, end === -1 ? text.length : end);
-                if (/^\/\/\/\s*<reference\b/.test(line)) {
-                    references = true;
-                }
-                index = end === -1 ? text.length : end + 1;
-            }
-            else if (character === "/" && next === "*") {
-                const end = text.indexOf("*/", index + 2);
-                index = end === -1 ? text.length : end + 2;
-            }
-            else if (character === '"' || character === "'") {
-                tokens.push({ kind: "string", value: readQuoted(character) });
-            }
-            else if (character === "`") {
-                scanTemplate();
-            }
-            else if (/[A-Za-z_$]/.test(character)) {
-                const start = index;
-                while (index < text.length && /[\w$]/.test(text[index])) {
-                    index += 1;
-                }
-                tokens.push({ kind: "word", value: text.slice(start, index) });
-            }
-            else if (/\s/.test(character)) {
-                index += 1;
-            }
-            else {
-                if (inPlaceholder && character === "{") {
-                    depth += 1;
-                }
-                else if (inPlaceholder && character === "}") {
-                    if (depth === 0) {
-                        index += 1;
-                        return;
-                    }
-                    depth -= 1;
-                }
-                tokens.push({ kind: "punctuation", value: character });
-                index += 1;
-            }
-        }
-    };
-    const scanTemplate = () => {
-        index += 1;
-        while (index < text.length && text[index] !== "`") {
-            if (text[index] === "\\") {
-                index += 2;
-            }
-            else if (text[index] === "$" && text[index + 1] === "{") {
-                index += 2;
-                scanCode(true);
-            }
-            else {
-                index += 1;
-            }
-        }
-        index += 1;
-        // A template is one opaque token: nothing before it pairs with it.
-        tokens.push({ kind: "punctuation", value: "`" });
-    };
-    scanCode(false);
-    const specifiers = [];
-    tokens.forEach((token, at) => {
-        const following = tokens[at + 1];
-        if (token.kind !== "word") {
-            return;
-        }
-        if (SPECIFIER_KEYWORD.test(token.value) && following?.kind === "string") {
-            specifiers.push(following.value);
-        }
-        else if (token.value === "import" &&
-            following?.kind === "punctuation" &&
-            following.value === "(" &&
-            tokens[at + 2]?.kind === "string") {
-            specifiers.push(tokens[at + 2].value);
-        }
-    });
-    return { specifiers, references };
-}