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

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

@@ -0,0 +1,60 @@
+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)) {
+        return undefined;
+    }
+    const bytes = text.slice(opening.length, text.length - CARRIER_SUFFIX.length);
+    let body;
+    try {
+        body = JSON.parse(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    const acceptance = await acceptClientContract(body);
+    if (!acceptance.accepted) {
+        return undefined;
+    }
+    return canonicalizeContract(acceptance.contract) === bytes
+        ? acceptance.contract
+        : undefined;
+}

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

@@ -0,0 +1,45 @@
+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`:
+ *
+ * - 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).
+ */
+export declare const DERIVATION_ROOTS: readonly string[];
+/**
+ * Reads one declaration file by its path relative to core's `dist`
+ * (POSIX-separated); `undefined` when there is none.
+ */
+export type DeclarationReader = (relative: string) => string | undefined;
+/** The published declarations of the `@aventara/core` this package resolves. */
+export declare function publishedCoreDeclarations(): DeclarationReader;
+/**
+ * Core's declaration closure from {@link DERIVATION_ROOTS}, as modules under
+ * `derivation/`, in UTF-16 code-unit order of their path.
+ *
+ * @throws Error when the closure cannot be transported — a defect of the
+ *   installed `@aventara/core`, never of the consumer's input.
+ */
+export declare function emitDerivationModules(read?: DeclarationReader): readonly EmittedModule[];

package/dist/emit/derivation.emitter.js

@@ -0,0 +1,233 @@
+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).
+ */
+export const DERIVATION_ROOTS = [
+    "contracts/contract",
+    "contracts/scalar-value-type",
+    "operations/operation-arguments",
+    "operations/operation-call",
+    "operations/operation-identity",
+    "operations/operation-result",
+    "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) => {
+        try {
+            return readFileSync(path.join(dist, relative), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * 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`);
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (copied.has(file)) {
+            continue;
+        }
+        const text = read(file);
+        if (text === undefined) {
+            throw new Error(`@aventara/core's declaration closure names ${file}, which it does not publish.`);
+        }
+        const scanned = scanDeclaration(text);
+        if (scanned.references) {
+            throw untransportable(`${file} carries a triple-slash reference, which the emitted tree cannot satisfy`);
+        }
+        for (const specifier of scanned.specifiers) {
+            queue.push(declarationTarget(file, specifier));
+        }
+        copied.set(file, withoutSourceMapTrailer(text));
+    }
+    return [...copied.keys()]
+        .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+        .map((file) => ({
+        path: `derivation/${file}`,
+        source: copied.get(file),
+    }));
+}
+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("../")) ||
+        !specifier.endsWith(".js")) {
+        throw leaves();
+    }
+    const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), specifier));
+    if (target.startsWith("../")) {
+        throw leaves();
+    }
+    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 };
+}

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

@@ -0,0 +1,4 @@
+import { type ClientContract } from "@aventara/core";
+import type { EmittedModule } from "./emitted-tree.interface.js";
+/** `generated/runtime/descriptor.ts`, before the banner. */
+export declare function emitDescriptorModule(contract: ClientContract): EmittedModule;

package/dist/emit/descriptor.emitter.js

@@ -0,0 +1,97 @@
+import { isOperationVariantAvailable, } from "@aventara/core";
+import { ownPropertyKey } from "./name.deriver.js";
+/**
+ * `generated/runtime/descriptor.ts` — what the RUNTIME needs of the ClientContract,
+ * as data (P1, P4). A projection of the same accepted contract the carrier
+ * (`generated/contract.ts`) holds, derived in the same run, so it is not a second
+ * source: `descriptor.emitter.spec.ts` regenerates it from the parsed carrier and
+ * compares.
+ *
+ * - **The decode table (P1).** Encoding is decidable by a value's runtime class;
+ *   decoding is not — a wire `"12"` is a `string`, a `bigint` or a `decimal`
+ *   depending only on the field (M13). So per Resource the table names each
+ *   result field whose wire string is revived (`bigint`, `decimal`, `datetime`,
+ *   `bytes`, §6.2) and each relation with its target and whether it is to-many,
+ *   which the decode walk recurses into (S5 added `many`: a to-one record may
+ *   itself hold a `data` and a `count` field, so the shape alone cannot say). Every other key passes through untouched; `json` is never
+ *   revived.
+ * - **The advertised operations (P4).** Read here through core's
+ *   `isOperationVariantAvailable`, emitted as `[resource, family, variant]`; the
+ *   type grammar reads the carrier's `operations` keys. They agree while present
+ *   ⇔ advertised (Phase 10 A3), and a gate asserts it over both pilots.
+ *
+ * Every registry is walked in UTF-16 code-unit order, so the key order a
+ * contract arrives in never reaches the bytes (C-843).
+ */
+/** The scalars whose wire form a decoder revives into another runtime class (§6.2). */
+const REVIVED_SCALARS = new Set([
+    "bigint",
+    "bytes",
+    "datetime",
+    "decimal",
+]);
+/** `generated/runtime/descriptor.ts`, before the banner. */
+export function emitDescriptorModule(contract) {
+    const resources = codeUnitOrder(Object.keys(contract.resources));
+    const table = resources.map((name) => {
+        const fields = contract.resources[name]?.fields ?? {};
+        const entries = codeUnitOrder(Object.keys(fields)).flatMap((field) => {
+            const decoding = decodingOf(fields[field]);
+            return decoding === undefined
+                ? []
+                : [`${ownPropertyKey(field)}: ${decoding}`];
+        });
+        return `\t${ownPropertyKey(name)}: {${entries.length === 0 ? "" : ` ${entries.join(", ")} `}},\n`;
+    });
+    const advertised = resources.flatMap((name) => {
+        const operations = contract.resources[name]?.operations ?? {};
+        return codeUnitOrder(Object.keys(operations)).flatMap((family) => {
+            const variants = (operations[family] ?? {});
+            return codeUnitOrder(Object.keys(variants))
+                .filter((variant) => isOperationVariantAvailable(variants[variant]))
+                .map((variant) => `\t[${[name, family, variant].map((part) => JSON.stringify(part)).join(", ")}],\n`);
+        });
+    });
+    return {
+        path: "runtime/descriptor.ts",
+        source: "/**\n" +
+            " * A result field the decoder revives from its wire string (§6.2), or a relation\n" +
+            " * it recurses into, read as the relation's target Resource — `many` saying the\n" +
+            " * value is a list, `{ data, count }` or `{ count }` rather than one record (P1).\n" +
+            " */\n" +
+            "export type FieldDecoding =\n" +
+            '\t| "bigint"\n' +
+            '\t| "bytes"\n' +
+            '\t| "datetime"\n' +
+            '\t| "decimal"\n' +
+            "\t| { readonly relation: string; readonly many: boolean };\n" +
+            "\n" +
+            "/** Per Resource, the result fields that need decoding; any other key passes through. */\n" +
+            "export const DECODE_TABLE: {\n" +
+            "\treadonly [resource: string]: { readonly [field: string]: FieldDecoding };\n" +
+            `} = {${table.length === 0 ? "" : `\n${table.join("")}`}};\n` +
+            "\n" +
+            "/** The operations the ClientContract advertises, as `[resource, family, variant]`. */\n" +
+            "export const ADVERTISED_OPERATIONS: readonly (readonly [\n" +
+            "\tresource: string,\n" +
+            "\tfamily: string,\n" +
+            "\tvariant: string,\n" +
+            `])[] = [${advertised.length === 0 ? "" : `\n${advertised.join("")}`}];\n`,
+    };
+}
+/** The table entry a field needs, as source, or `undefined` when it passes through. */
+function decodingOf(field) {
+    if (field === undefined) {
+        return undefined;
+    }
+    if (field.kind === "relation") {
+        return `{ relation: ${JSON.stringify(field.target)}, many: ${field.cardinality === "many"} }`;
+    }
+    return "scalar" in field.type &&
+        REVIVED_SCALARS.has(field.type.scalar)
+        ? JSON.stringify(field.type.scalar)
+        : undefined;
+}
+function codeUnitOrder(values) {
+    return [...values].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+}

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

@@ -0,0 +1,61 @@
+/**
+ * The generator's output as a VALUE before it is a filesystem effect (plan §7,
+ * group 3). Byte-equality is therefore testable without touching disk, and
+ * temp → validate → replace (S7) is a property of the writer alone rather than of
+ * every emitter.
+ */
+/**
+ * The output layout (architect, 2026-10-04): the consumer names a directory,
+ * `generateAt`, which is SHARED — they may keep their own files there. The
+ * generator owns exactly two entries in it:
+ *
+ * - `AvClient.ts`, the entry point a consumer imports;
+ * - `generated/`, every other module, owned and replaced whole.
+ */
+/** The entry point, at the root of `generateAt`. */
+export declare const CLIENT_ENTRY_FILE = "AvClient.ts";
+/** The directory holding every other emitted module, under `generateAt`. */
+export declare const GENERATED_DIRECTORY = "generated";
+/**
+ * One of core's published declaration files, copied under `generated/derivation/`
+ * at its path relative to core's `dist` (Q1 = A, `derivation.emitter.ts`).
+ */
+export type DerivationModulePath = `derivation/${string}.d.ts`;
+/**
+ * The modules under `generated/`: the emitted sources, the carrier
+ * (`contract.ts`, Q4), the typed surface (`client.ts`) and named types
+ * (`types.d.ts`, S4 — a declaration file, architect 2026-10-05), and core's declarations under `derivation/`. §15.4's
+ * `runtime/transaction.ts` and `runtime/fingerprint.ts` exist iff transactions
+ * are interactive (S6, P3); `resources/` and `runtime/projection.ts` are not
+ * emitted (plan §7).
+ *
+ * Relative to `generated/`, POSIX-separated.
+ */
+export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/fingerprint.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
+/** A path in the emitted tree: relative to `generateAt`, POSIX-separated. */
+export type EmittedFilePath = typeof CLIENT_ENTRY_FILE | `${typeof GENERATED_DIRECTORY}/${GeneratedModulePath}`;
+/** One module's TypeScript source under `generated/`, before the banner and before encoding. */
+export interface EmittedModule {
+    readonly path: GeneratedModulePath;
+    readonly source: string;
+}
+/** One emitted file: its path and its exact bytes, banner included, UTF-8. */
+export interface EmittedFile {
+    readonly path: EmittedFilePath;
+    readonly bytes: Uint8Array;
+}
+/**
+ * Every file one generation emits, in UTF-16 code-unit order of `path`, each path
+ * once — `AvClient.ts` first, then `generated/**`. Replaced, never merged
+ * (§15.3): `generated/` whole, `AvClient.ts` as one file.
+ */
+export type EmittedTree = readonly EmittedFile[];
+/**
+ * What emission yields: the tree, and the diagnostics a run raised without
+ * failing — today, one line per renamed name (`name.deriver.ts`). Returned rather
+ * than printed, so the code that owns the terminal decides where they go.
+ */
+export interface ClientEmission {
+    readonly tree: EmittedTree;
+    readonly warnings: readonly string[];
+}

package/dist/emit/emitted-tree.interface.js

@@ -0,0 +1,18 @@
+/**
+ * The generator's output as a VALUE before it is a filesystem effect (plan §7,
+ * group 3). Byte-equality is therefore testable without touching disk, and
+ * temp → validate → replace (S7) is a property of the writer alone rather than of
+ * every emitter.
+ */
+/**
+ * The output layout (architect, 2026-10-04): the consumer names a directory,
+ * `generateAt`, which is SHARED — they may keep their own files there. The
+ * generator owns exactly two entries in it:
+ *
+ * - `AvClient.ts`, the entry point a consumer imports;
+ * - `generated/`, every other module, owned and replaced whole.
+ */
+/** The entry point, at the root of `generateAt`. */
+export const CLIENT_ENTRY_FILE = "AvClient.ts";
+/** The directory holding every other emitted module, under `generateAt`. */
+export const GENERATED_DIRECTORY = "generated";

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

@@ -0,0 +1,24 @@
+import type { ClientContract } from "@aventara/core";
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type EmittedNames } from "./name.deriver.js";
+/**
+ * `enums.ts`: per enum, a string-literal union type and a same-named `as const`
+ * object (§15.4's "enum types"; architect decision, 2026-10-04):
+ *
+ * ```ts
+ * export type Role = "ADMIN" | "USER";
+ * export const Role = { ADMIN: "ADMIN", USER: "USER" } as const;
+ * ```
+ *
+ * The type is what every later emitter references; the object gives a consumer a
+ * value to name a member by and to enumerate. Both are declared under the enum's
+ * emitted identifier, which differs from its contract name only when the name was
+ * renamed (`name.deriver.ts`). The values are the wire values and are never
+ * renamed.
+ *
+ * Enums come in the order `names` gives them — UTF-16 code units of the contract
+ * name — so the key order a contract arrives in never reaches the bytes (C-843).
+ * An enum's VALUES keep their declared order, in the type and in the object: that
+ * order is meaning, and canonical form keeps it too.
+ */
+export declare function emitEnumsModule(contract: Pick<ClientContract, "enums">, names: EmittedNames): EmittedModule;

package/dist/emit/enum.emitter.js

@@ -0,0 +1,42 @@
+import { ownPropertyKey } from "./name.deriver.js";
+/**
+ * `enums.ts`: per enum, a string-literal union type and a same-named `as const`
+ * object (§15.4's "enum types"; architect decision, 2026-10-04):
+ *
+ * ```ts
+ * export type Role = "ADMIN" | "USER";
+ * export const Role = { ADMIN: "ADMIN", USER: "USER" } as const;
+ * ```
+ *
+ * The type is what every later emitter references; the object gives a consumer a
+ * value to name a member by and to enumerate. Both are declared under the enum's
+ * emitted identifier, which differs from its contract name only when the name was
+ * renamed (`name.deriver.ts`). The values are the wire values and are never
+ * renamed.
+ *
+ * Enums come in the order `names` gives them — UTF-16 code units of the contract
+ * name — so the key order a contract arrives in never reaches the bytes (C-843).
+ * An enum's VALUES keep their declared order, in the type and in the object: that
+ * order is meaning, and canonical form keeps it too.
+ */
+export function emitEnumsModule(contract, names) {
+    const declarations = names.enums.map(({ contractName, identifier }) => {
+        const values = contract.enums[contractName]?.values ?? [];
+        const union = values.length === 0
+            ? "never"
+            : values.map((value) => JSON.stringify(value)).join(" | ");
+        const members = values.length === 0
+            ? "{}"
+            : `{ ${values.map((value) => `${ownPropertyKey(value)}: ${JSON.stringify(value)}`).join(", ")} }`;
+        return (`export type ${identifier} = ${union};\n` +
+            `export const ${identifier} = ${members} as const;\n`);
+    });
+    return {
+        path: "enums.ts",
+        // Without an import or export, a consumer whose config treats such a file
+        // as a script (`moduleResolution: "bundler"` outside a `"type": "module"`
+        // package, measured) fails `AvClient.ts`'s `export *` with TS2306 — so a
+        // contract without enums still emits a module.
+        source: declarations.length === 0 ? "export {};\n" : declarations.join("\n"),
+    };
+}