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

package/README.md

@@ -6,7 +6,7 @@ client is the product: it imports nothing from this package, or from `@aventara/
 
 Every argument and result type in the generated client is core's own derivation — `@aventara/core`'s published
 declarations, copied into the tree and instantiated over the deployment's ClientContract — so the client agrees with the
-server by construction, and that agreement is gated over both pilot schemas.
+server by construction.
 
 ## Setting up a frontend: `avclient init`
 
@@ -91,8 +91,9 @@ supported yet.
 - **A failed run leaves the previous output exactly as it was.** The whole tree is written to a staging directory inside
   `generateAt`, validated there as one program, and only then moved into place. A run killed part-way is repaired by the
   next run that writes, before it writes anything. A first run that fails removes the directories it created.
-- **The validate step is a real type check** when the optional peer `typescript` (5.5 to 6) is installed, under a
-  consumer's strictest plausible settings and with nothing outside the tree resolvable. Without it — or under
+- **The validate step is a real type check** when your project has the optional peer `typescript` (5.5 to 6) — it is
+  resolved from your project, so `npx @aventara/client@pilot init` type-checks too — under a consumer's strictest plausible
+  settings and with nothing outside the tree resolvable. Without it — or under
   TypeScript 7, which has no classic compiler API to check with — the check degrades to a parse with Node's own
   TypeScript parser, and says so loudly in one warning; it is never skipped, and the client is still written. The peer
   range has no upper bound, so a frontend on TypeScript 7 installs it; your own `tsc` checks the tree when it compiles.
@@ -209,11 +210,9 @@ chose. The `.d.ts` files are core's copied declarations under `generated/derivat
   `UserUniqueWhere`, `UserOrderBy`, `UserCreateData`, `UserUpdateData`, `UserSelect`, `UserInclude`), each only when
   its operation is advertised.
 
-The tree is self-contained: every import in it names a file in it. That is gated twice in this package's tests — once
-lexically, once by compiling the tree alone where nothing outside it can resolve — and each gate catches a planted
-import of `@aventara/core` or `@aventara/client` on its own. Names a TypeScript declaration cannot carry as-is (a
-reserved word, a name the runtime owns, an enum sharing a Resource's name) are renamed, with one warning each; the wire
-name is kept.
+The tree is self-contained: every import in it names a file in it, so it compiles with nothing else installed. Names a TypeScript
+declaration cannot carry as-is (a reserved word, a name the runtime owns, an enum sharing a Resource's name) are
+renamed, with one warning each; the wire name is kept.
 
 ## What a generated client is bound to
 
@@ -236,11 +235,10 @@ doing so re-binds nothing — the ClientContract hash still decides whether that
 
 ## Type-checking cost in a consumer
 
-A consumer pays for the calls it type-checks, not for the schema — under `skipLibCheck: true` (the common default),
-where the named types (`generated/types.d.ts`) and core's derivation are declaration files checked only where read:
-about 33,000 instantiations for a 50-Resource schema and seven typed calls. Under `skipLibCheck: false` every named type
-is resolved where it is declared, about 2,900 instantiations per Resource: about 204,000 for the same
-program, the 500,000 line near 150 Resources.
+A consumer pays for the calls it type-checks, not for the schema, under `skipLibCheck: true` (the common default):
+the named types (`generated/types.d.ts`) and core's derivation are declaration files checked only where read. Under
+`skipLibCheck: false` every named type is resolved where it is declared, so the cost grows with the number of
+Resources.
 
 ## Before 1.0
 

package/dist/cli/command.parser.d.ts

@@ -1,16 +1,6 @@
-/**
- * The `avclient` command line: one command, its one flag, and help. Everything the
- * generator needs is in `framework.client.ts` and the `.env` cascade, so
- * `generate` takes no flag that would duplicate a config member — a second source
- * of the same fact. `--yes` is not one: it answers the one question the generator
- * asks.
- */
 export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.ts (or .js, .mjs, .cjs, .mts,\n                              .cts) in the current directory, fetch\n                              <entrypoint>/_contract, and write AvClient.ts and\n                              generated/ into its generateAt directory, its imports\n                              spelled as the project's tsconfig.json says.\n  avclient init [options]     Set up this frontend: write framework.client.ts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.ts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n  avclient --version, -v      Print this generator's version and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.ts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
-/** `avclient generate --help` (pilot.1): that command's usage alone. */
 export declare const GENERATE_USAGE = "Usage: avclient generate [--yes]\n\nRead framework.client.ts (or .js, .mjs, .cjs, .mts, .cts) in the current directory,\nfetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its\ngenerateAt directory, its imports spelled as the project's tsconfig.json says.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed.\n\nBefore the config is evaluated, the .env cascade is read from the current\ndirectory, highest precedence first: the process environment, .env.<mode>.local,\n.env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or \"development\".\n";
-/** `avclient init --help` (pilot.1): that command's usage alone. */
 export declare const INIT_USAGE = "Usage: avclient init [options]\n\nSet up this frontend: write framework.client.ts, the .env entry, the avclient:generate\nscript and the @aventara/client devDependency; install; generate.\n\nOptions:\n  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].\n  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].\n  --no-env-var                   Write it into framework.client.ts as a literal.\n  --generate-at <dir>            Where the client goes [./src/api].\n  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n  --skip-install                 Print the install instead of running it.\n  --skip-generate                Do not generate now.\n  -y, --yes                      Accept every default, and replace differing content.\n\nOn a terminal every unanswered question is asked; anywhere else, pass its flag\nor --yes, or the run stops before writing anything.\n";
-/** `avclient init`'s command line. */
 export type ClientInitCommand = {
     readonly command: "init";
     readonly given: Readonly<Partial<Record<"entrypoint" | "envVar" | "generateAt" | "packageManager", string>>>;
@@ -20,9 +10,7 @@ export type ClientInitCommand = {
     readonly yes: boolean;
 };
 /** What the command line asked for. */
-export type CliCommand = 
-/** `--help`; with `topic`, `avclient <topic> --help` (pilot.1). */
-{
+export type CliCommand = {
     readonly command: "help";
     readonly topic?: "generate" | "init";
 } | {

package/dist/cli/generation-success.renderer.d.ts

@@ -13,10 +13,6 @@ export interface GenerationSuccessReport {
     readonly stderr: string;
 }
 export declare function renderGenerationSuccess(result: ClientGenerated): GenerationSuccessReport;
-/**
- * Nothing written: the deployment's ClientContract and these bytes are what is
- * there.
- */
 export declare function renderUpToDate(result: ClientUpToDate): GenerationSuccessReport;
 /**
  * What the person running the generator is told before being asked: every path

package/dist/cli/terminal.prompter.d.ts

@@ -1,9 +1,3 @@
-/**
- * The terminal's questions — `generate`'s yes/no and `init`'s wizard — over one
- * `node:readline` interface whose lines are **queued**: a line typed (or piped
- * into a pseudo-terminal) before its question is kept for it, where a fresh
- * interface per question, or `readline/promises`' `question`, drops it.
- */
 export type TerminalPrompter = {
     readonly ask: (prompt: string) => Promise<string>;
     readonly confirm: (question: string) => Promise<boolean>;

package/dist/cli/warning.renderer.d.ts

@@ -1,9 +1,3 @@
-/**
- * How one warning reaches the person running the generator: its own stderr line,
- * under the CLI's one prefix. Warnings carry no prefix of their own, so the line
- * says "warning" once. Shared by a success and a refusal, so a warning reads the
- * same either way.
- */
 /** The prefix every warning line opens with. */
 export declare const WARNING_LINE_PREFIX = "avclient: warning: ";
 /** One newline-terminated line per warning, in the order given; empty for none. */

package/dist/cli.d.ts

@@ -1,21 +1,5 @@
 import { type CliIo } from "./cli/generate.command.js";
 export type { CliIo } from "./cli/generate.command.js";
-/**
- * It is also the one place that ASKS: when content the generator did not produce
- * stands in `AvClient.ts` or `generated/`, the paths are listed and the person is
- * asked whether to overwrite them. `--yes` answers for them. Where nobody can
- * answer — stdin is not a terminal — it never asks and never overrides: it
- * refuses, naming `--yes`. Cancelled or refused, nothing was touched, the run's
- * warnings are printed before the sentence, and the exit code is 1. A killed run's
- * leftovers are looked at before the question, so the answer — and `--yes` —
- * covers what it hid as well.
- */
 /** Runs one command line; resolves to the exit code. Never throws. */
 export declare function runCli(argv: readonly string[], io: CliIo): Promise<number>;
-/**
- * Runs `avclient` over this process — its arguments, its terminal, its exit
- * code. Called by the bin's entry (`avclient.bin.ts`) once the Node guard has
- * admitted this Node; importing this module runs nothing, which is what lets
- * `runCli` be tested in process.
- */
 export declare function runFromProcess(): Promise<void>;

package/dist/config/client-config.interface.d.ts

@@ -1,33 +1,31 @@
-/**
- * The generator's configuration, in its two states.
- *
- * `ClientConfigInput` is what a `framework.client.ts` default-exports through
- * `defineClientConfig`. It is passive data: an environment variable appears as an
- * `EnvReference`, a NAME to look up, so the file can be evaluated without the
- * environment having been loaded into the global and resolution stays a pure
- * function of the input and an `EnvRecord`.
- */
 /** A deferred read of one environment variable from the resolved cascade. */
 export interface EnvReference {
+    /** Always `"env"`. */
     readonly kind: "env";
+    /** The environment variable's name. */
     readonly name: string;
 }
 /** A value written literally, or read from the resolved environment. */
 export type ConfigValue = string | EnvReference;
+/**
+ * What a `framework.client.ts` default-exports through `defineClientConfig`.
+ * Plain data: an environment variable appears as an `EnvReference` (`env("NAME")`),
+ * a name to look up, so the file can be evaluated before the environment is loaded.
+ */
 export interface ClientConfigInput {
     /** The full deployed framework entrypoint: origin plus mount path. */
     readonly entrypoint: ConfigValue;
     /**
      * The directory the client is generated into, relative to the config file's
-     * directory. It is SHARED: the generator owns only `AvClient.ts` and `generated/`
-     * in it, and never touches anything else there.
+     * directory. It is shared: the generator writes only `AvClient.ts` and
+     * `generated/` in it, and never touches anything else there.
      */
     readonly generateAt: ConfigValue;
     /**
      * The `tsconfig.json` the generated client is written for, relative to the
      * config file's directory — only for a layout the discovery gets wrong (a
      * monorepo, a non-standard name). Absent, the nearest `tsconfig.json` above
-     * `generateAt` (`tsconfig.locator.ts`).
+     * `generateAt` is used.
      */
     readonly tsconfigFile?: string;
 }
@@ -35,17 +33,9 @@ export interface ClientConfigInput {
 export type AbsolutePath = string & {
     readonly __absolutePath: true;
 };
-/**
- * Root is the empty string, not `"/"`, so every route is `path + "/<route>"` with
- * no special case. Only resolution makes one.
- */
 export type EntrypointPath = ("" | `/${string}`) & {
     readonly __entrypointPath: true;
 };
-/**
- * The deployed entrypoint, normalised once at resolution so every consumer reads
- * one canonical form. Joining a route onto it is concatenation.
- */
 export interface ClientEntrypoint {
     /**
      * The deployment the entrypoint addresses: scheme, credentials, host and port.

package/dist/config/config.loader.d.ts

@@ -1,25 +1,4 @@
 import type { ClientConfigInput } from "./client-config.interface.js";
-/**
- * Finds and evaluates the client config, `framework.client.<ext>`, the way
- * Prisma 7 loads `prisma.config.ts` (`@prisma/config` 7.10's
- * `loadConfigFromFile`): through `c12`, which evaluates it with `jiti`
- * (`interopDefault`, no module cache), with no `.env` loading, no rc file, no
- * remote or `extends` layers and no `package.json` key. So any of
- * {@link CLIENT_CONFIG_FILE_EXTENSIONS} — Prisma's own list — in ES module or
- * CommonJS syntax, whatever the project's `"type"`, TypeScript included, with
- * no compiler of the project's needed (pilot.1's `.mts` rule is gone: jiti, not
- * Node, decides how the file is read).
- *
- * One file, looked up in one directory — no search up the tree — and when more
- * than one is present the run refuses rather than choose: two files would be
- * two sources of the same fact. What the file imports — `@aventara/client` for
- * `defineClientConfig` and `env` — resolves from the consumer's project, as any
- * import of theirs would.
- *
- * The evaluated value is checked against `ClientConfigInput`'s shape before it
- * is trusted: the config is the consumer's code, and a typo there should be a
- * sentence naming the member, not a `TypeError` from deep inside resolution.
- */
 /** Prisma's `SUPPORTED_EXTENSIONS`, in its order. */
 export declare const CLIENT_CONFIG_FILE_EXTENSIONS: readonly [".js", ".ts", ".mjs", ".cjs", ".mts", ".cts"];
 /** The config's name, before its extension. */

package/dist/config/config.resolver.d.ts

@@ -1,8 +1,8 @@
 import type { ClientConfigInput, ClientEntrypoint, EnvReference, ResolvedClientConfig } from "./client-config.interface.js";
 import type { EnvCascadeResolution } from "./env.cascade.js";
-/** The identity function that gives a `framework.client.ts` its type. */
+/** Gives a `framework.client.ts` its type: returns `config` unchanged. */
 export declare function defineClientConfig(config: ClientConfigInput): ClientConfigInput;
-/** Names an environment variable to be read from the resolved cascade. */
+/** Names an environment variable to be read from the resolved environment. */
 export declare function env(name: string): EnvReference;
 /**
  * The configuration cannot be resolved. The message is the whole diagnosis — the
@@ -23,22 +23,7 @@ export interface ClientConfigResolutionInput {
  */
 export declare function resolveClientConfig(input: ClientConfigResolutionInput): ResolvedClientConfig;
 /**
- * An entrypoint value resolved to its canonical form. The URL half is this
- * function's: whitespace (which the URL parser would trim or drop unseen), a value
- * that is not an absolute URL, a scheme other than http(s), credentials, a query
- * or fragment (even an empty one, which the parser forgets), and a `..` segment
- * (which the parser would resolve away) are refused here, reading the value as
- * written.
- *
- * Only its slash spelling is coerced — `api`, `/api/` and `//api//` are one
- * intent, `/api` — and root is `""`.
- *
  * @throws ClientConfigError in one sentence that does not echo the value.
  */
 export declare function resolveEntrypoint(value: string): ClientEntrypoint;
-/**
- * The entrypoint as one absolute URL with no trailing slash — the form the emitted
- * transport joins its routes to, and the default a generated client embeds. Root
- * is the bare origin.
- */
 export declare function entrypointHref(entrypoint: ClientEntrypoint): string;

package/dist/config/env.cascade.d.ts

@@ -1,39 +1,9 @@
-/**
- * Precedence, highest first: the existing process environment >
- * `.env.<mode>.local` > `.env.<mode>` > `.env.local` > `.env`.
- *
- * # Why a returned record, and not `process.loadEnvFile`
- *
- * Measured on Node v24.20.0, `process.loadEnvFile` is first-write-wins and never
- * overrides an existing value — the right semantics — but it is the wrong
- * mechanism here, for three reasons that were measured rather than argued:
- *
- * 1. It writes into the live `process.env`. A resolution that mutates the global
- *    leaks across tests and across invocations in one process; a suite that passes
- *    alone and fails in sequence is exactly that leak.
- * 2. It reports an unreadable file (`EACCES`) as `ENOENT`. Catching `ENOENT` from
- *    it would treat a `.env` the user cannot read as a `.env` that is not there —
- *    a silent wrong answer.
- * 3. It silently drops lines that are not assignments. So does `util.parseEnv`;
- *    neither has a notion of a malformed file.
- *
- * So each file is read with `readFileSync` (whose error code is the truth), parsed
- * with `util.parseEnv` (the same parser `loadEnvFile` uses — pinned by a parity
- * test), checked for lines the parser would discard, and folded first-write-wins
- * over the candidates in priority order. Nothing global is read or written: the
- * process environment is an INPUT.
- */
 /** A resolved environment: names to values, never `undefined`. */
 export type EnvRecord = Readonly<Record<string, string>>;
 /** The process environment as Node types it: values may be `undefined`. */
 export type ProcessEnvInput = Readonly<Record<string, string | undefined>>;
 /** The mode used when neither an explicit mode nor `NODE_ENV` supplies one. */
 export declare const DEFAULT_ENV_MODE = "development";
-/**
- * Reads one candidate file. Returns `undefined` only when the file does not
- * exist; any other failure throws. The seam exists so resolution can be tested
- * without a filesystem — the default reads from disk.
- */
 export type EnvFileReader = (filePath: string) => string | undefined;
 export interface EnvCascadeInput {
     /** The directory the five candidates are looked up in. */

package/dist/config/module-style.resolver.d.ts

@@ -1,31 +1,6 @@
 import type { TsConfigJsonResolved } from "get-tsconfig";
 import type { ClientModuleStyle, ImportFileExtension, ModuleFormat } from "../emit/module-style.interface.js";
 import { type LocatedTsconfig } from "./tsconfig.locator.js";
-/**
- * How the generated client is spelled for the project that compiles it: inferred
- * from the project's `tsconfig.json` (`tsconfig.locator.ts`) and, under
- * `node16`/`nodenext`, the nearest `package.json`, by Prisma 7.10's
- * `prisma-client` rules, mirrored from its CLI with the generated extension fixed
- * at `ts`:
- *
- * importFileExtension
- *   1. `allowImportingTsExtensions` or `rewriteRelativeImportExtensions` → `ts`;
- *   2. `module` is `commonjs`, or `moduleResolution` is `bundler` (either case) →
- *      `""`;
- *   3. otherwise → `js` (Prisma's `ts → js`).
- *
- * moduleFormat
- *   1. `module` is `commonjs` → `cjs`;
- *   2. `module` is `node16` or `nodenext` → the nearest `package.json` above
- *      `generateAt`: `"type": "module"` → `esm`; no `package.json`, an unparseable
- *      one, or any other `type` → `cjs`;
- *   3. any other `module` → `esm`; no `module` → `esm` (Prisma's fallback, whose
- *      `cjs` arm needs a generated `.cts`).
- *
- * Prisma falls back to the generated extension when there is no tsconfig; this
- * generator refuses instead: its client is TypeScript, and a project without a
- * tsconfig is a JavaScript project, not supported yet.
- */
 /** What the run follows, and where it read it from. */
 export interface ResolvedModuleStyle extends ClientModuleStyle {
     /** The tsconfig the style was inferred from. */

package/dist/config/tsconfig.locator.d.ts

@@ -1,28 +1,4 @@
 import { type TsConfigJsonResolved } from "get-tsconfig";
-/**
- * Which `tsconfig.json` the generated client is spelled for
- * (`module-style.resolver.ts`): the project's own, found the way Prisma 7's
- * `prisma-client` generator finds it — `get-tsconfig`'s `getTsconfig`, the very
- * library and version Prisma 7.10 bundles, searching from the output directory
- * up, `extends` chains merged — with one step Prisma does not take.
- *
- * # A solution-style root (Vite's layout)
- *
- * `npm create vite` writes a `tsconfig.json` that compiles nothing — `"files":
- * []` and `references` to `tsconfig.app.json` and `tsconfig.node.json` — so the
- * nearest config names no compiler option at all. When the config found does
- * not include the generated entry file and has `references`, the referenced
- * project that does include it is the one used, the first in `references`
- * order — how TypeScript's own language service picks a file's project. With
- * none including it, the root stays the answer, as it is Prisma's.
- *
- * # `tsconfigFile`
- *
- * The escape hatch for a layout this discovery gets wrong (a monorepo, a
- * non-standard name): the config's `tsconfigFile`, resolved against the config
- * file's directory, used as named — no search, no reference step. A missing or
- * unreadable one is refused, naming the path it resolved to.
- */
 /** The tsconfig a run follows: its path and its resolved content (`extends` merged). */
 export interface LocatedTsconfig {
     readonly path: string;

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

@@ -1,47 +1,8 @@
 import { type ClientContract } from "@aventara/core";
-/**
- * # 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
- *
- * # The hash is core's, never a second implementation
- *
- * The advertised `protocol.hash` is recomputed with `computeClientContractHash` —
- * 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. 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. */
 export declare const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet<number>;
 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: no capability is interpreted here.
-     */
     readonly contract: ClientContract;
 };
 export type ContractRejected = {

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

@@ -1,18 +1,4 @@
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
-/**
- * # 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.
- *
- * `fetch` is injected, so the transport is tested without a server; the default is
- * the platform's.
- */
 /** The part of a `Response` the fetcher reads. */
 export type ContractResponse = Pick<Response, "ok" | "status" | "text">;
 /** The `fetch` the fetcher calls. `globalThis.fetch` satisfies it. */
@@ -20,10 +6,6 @@ export type ContractFetch = (url: URL, init: {
     readonly method: "GET";
     readonly headers?: Readonly<Record<string, string>>;
 }) => Promise<ContractResponse>;
-/**
- * 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 = 
 /** No response at all: DNS, refused connection, TLS, abort. */
@@ -39,21 +21,10 @@ export declare class ContractTransportError extends Error {
     readonly name = "ContractTransportError";
     constructor(reason: ContractTransportFailureReason, message: string, options?: ErrorOptions);
 }
-/**
- * `<entrypoint>/_contract`: the canonical mount path and the route, concatenated.
- * 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. */
 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}. A `304` to a
- * request that sent none is no answer, like any other non-2xx.
- *
  * @throws ContractTransportError when no JSON value arrives.
  */
 export declare function fetchClientContractBody(entrypoint: ClientEntrypoint, fetch?: ContractFetch, ifNoneMatch?: string): Promise<unknown>;

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

@@ -1,14 +1,8 @@
 import type { ClientContract } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import { type ContractFetch } from "./contract.fetcher.js";
-/**
- * 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. */
     readonly entrypoint: ClientEntrypoint;
-    /** Injected for tests; the platform `fetch` otherwise. */
     readonly fetch?: ContractFetch;
 }
 /**
@@ -16,7 +10,6 @@ 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. */
 export interface ClientContractSince {
     readonly contract: ClientContract;
     /** The deployment answered `304`: `contract` is the one the caller held. */

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

@@ -1,22 +1,4 @@
-/**
- * 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.
- *
- * 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 — 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. */
 export declare function withGeneratedBanner(source: string): string;

package/dist/emit/banner.emitter.js

@@ -1,6 +1,6 @@
 export const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
 export const GENERATED_BANNER = [
-    "// biome-ignore-all format: generated output; these bytes are the artifact",
+    "// biome-ignore-all format: generated output",
     "// biome-ignore-all lint: generated output",
     GENERATED_OWNERSHIP_LINE,
     "/* Regenerate with `avclient generate`. */",

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

@@ -2,27 +2,4 @@ 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: 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/`: 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. 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: `ResourceRecord` and `ResourceArgument`.
- *
- * 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, style: ClientModuleStyle): EmittedModule;

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

@@ -3,26 +3,6 @@ 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";
 /**
- * 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:
- *
- * - every module opens with the generated banner;
- * - every file is UTF-8;
- * - 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: 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, style: ClientModuleStyle): ClientEmission;

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

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

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

@@ -1,32 +1,4 @@
 import type { EmittedModule } from "./emitted-tree.interface.js";
-/**
- * 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; 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`