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

package/dist/init/client-init.questions.d.ts

@@ -1,18 +1,11 @@
-/**
- * R4, R5, Q16 rows 12–15 — `avclient init`'s questions in one table: each
- * question's flag, label and default, from which the command line, the prompt,
- * `--yes`'s defaults and the non-interactive refusal are derived — the rule
- * `@aventara/cli`'s wizard follows, implemented here because the two packages
- * never import each other (P7).
- */
 export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm"];
 export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 export type ClientInitAnswers = {
-    /** The deployment's entrypoint (Q16-12: `--entrypoint`, `defineClientConfig`'s key). */
+    /** The deployment's entrypoint. */
     readonly entrypoint: string;
-    /** The variable `framework.client.ts` reads it from, or `undefined` for a literal (Q16-13). */
+    /** The variable `framework.client.ts` reads it from, or `undefined` for a literal. */
     readonly envVar: string | undefined;
-    /** Where the client is generated (Q16-14: `--generate-at`, the config key). */
+    /** Where the client is generated. */
     readonly generateAt: string;
     readonly packageManager: PackageManager;
 };
@@ -34,7 +27,7 @@ export type ClientInitQuestion = {
     /** @throws ClientInitAnswerError */
     readonly parse: (raw: string) => string;
 };
-/** The project convention for the variable (spec §15.2). */
+/** The project convention for the variable. */
 export declare const DEFAULT_ENV_VAR = "AVENTARA_API_URL";
 export declare const CLIENT_INIT_QUESTIONS: readonly ClientInitQuestion[];
 export type ClientInitSources = {
@@ -47,6 +40,9 @@ export type ClientInitSources = {
     readonly say: (line: string) => void;
     readonly detectedPackageManager: PackageManager;
 };
-/** Flag → `--yes`'s default → the prompt → the refusal naming exactly the unanswered flags (R5). */
+/**
+ * Flag → `--yes`'s default → the prompt → the refusal naming exactly the
+ * unanswered flags.
+ */
 export declare function resolveClientInitAnswers(sources: ClientInitSources): Promise<ClientInitAnswers>;
 export {};

package/dist/init/client-init.questions.js

@@ -1,21 +1,11 @@
 import { resolveEntrypoint } from "../config/config.resolver.js";
-/**
- * R4, R5, Q16 rows 12–15 — `avclient init`'s questions in one table: each
- * question's flag, label and default, from which the command line, the prompt,
- * `--yes`'s defaults and the non-interactive refusal are derived — the rule
- * `@aventara/cli`'s wizard follows, implemented here because the two packages
- * never import each other (P7).
- */
 export const PACKAGE_MANAGERS = ["npm", "pnpm"];
-/** An answer the question cannot take. A refusal: one sentence. */
 export class ClientInitAnswerError extends Error {
     name = "ClientInitAnswerError";
 }
-/** Nobody can answer and some questions are unanswered. A refusal: one sentence. */
 export class ClientInitUnansweredError extends Error {
     name = "ClientInitUnansweredError";
 }
-/** The project convention for the variable (spec §15.2). */
 export const DEFAULT_ENV_VAR = "AVENTARA_API_URL";
 export const CLIENT_INIT_QUESTIONS = [
     {
@@ -77,7 +67,6 @@ export const CLIENT_INIT_QUESTIONS = [
         },
     },
 ];
-/** Flag → `--yes`'s default → the prompt → the refusal naming exactly the unanswered flags (R5). */
 export async function resolveClientInitAnswers(sources) {
     const answered = {};
     const missing = [];

package/dist/init/client-project.inspector.d.ts

@@ -7,6 +7,12 @@ export declare class ClientProjectRefusedError extends Error {
 export type ClientProject = {
     readonly directory: string;
     readonly manifestText: string;
+    /**
+     * Its `framework.client.<ext>`, by name, when it has one — `undefined` when it
+     * has none. Two or more are refused while inspecting, as `avclient generate`
+     * refuses them.
+     */
+    readonly configFile: string | undefined;
     /** The package manager its lockfile names, if exactly one does. */
     readonly lockfile: PackageManager | undefined;
     /** The current text of a project file, or `undefined`. */

package/dist/init/client-project.inspector.js

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-/** The frontend `avclient init` serves, read before anything is asked or written. */
-/** The directory is not a project `avclient init` can set up. A refusal: nothing written. */
+import { findClientConfigFile } from "../config/config.loader.js";
 export class ClientProjectRefusedError extends Error {
     name = "ClientProjectRefusedError";
 }
@@ -19,6 +18,7 @@ export function inspectClientProject(directory) {
     return {
         directory,
         manifestText: readFileSync(manifest, "utf8"),
+        configFile: findClientConfigFile(directory),
         lockfile: lockfiles.length === 1 ? lockfiles[0] : undefined,
         read: (file) => {
             try {

package/dist/node-version.guard.js

@@ -1,4 +1,3 @@
-// biome-ignore lint/style/useNodejsImportProtocol: Node 14.0–14.13.0 resolves no "node:" specifier in an ES module, and this module runs on the Nodes the packages do not support.
 import { readFileSync } from "fs";
 function versionOf(text) {
     const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text);
@@ -16,11 +15,6 @@ function compareVersions(left, right) {
     }
     return 0;
 }
-/**
- * Whether `range` admits `version`. Reads `^x.y.z` (the same major, from the
- * floor; majors ≥ 1) and `>=x.y.z`, joined by `||`; anything else throws rather
- * than admit or refuse by guess.
- */
 function admits(range, version) {
     return range.split("||").some((part) => {
         const comparator = /^\s*(\^|>=)(\d+\.\d+\.\d+)\s*$/.exec(part);
@@ -32,17 +26,11 @@ function admits(range, version) {
             (comparator[1] === ">=" || version[0] === floor[0]));
     });
 }
-/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
 export function nodeVersionRefusal(bin, packageName, range, version) {
     return admits(range, versionOf(version))
         ? undefined
         : `${bin}: Node ${version} is not supported; ${packageName} needs Node ${range}.`;
 }
-/**
- * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
- * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
- * the bin then loads nothing else.
- */
 export function refuseUnsupportedNode(bin, manifestUrl) {
     const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
     const range = manifest.engines === undefined ? undefined : manifest.engines.node;

package/dist/output/output.validator.d.ts

@@ -1,30 +1,30 @@
 import type * as ts from "typescript";
-import type { EmittedTree } from "../emit/emitted-tree.interface.js";
+import type { ClientEmission } from "../emit/emitted-tree.interface.js";
 /**
- * §15.3's "type/sanity validation" step, between emit-to-temp and the replace:
- * the gate that makes the atomicity worth having (plan §4 Q6). It judges a
- * directory the writer has just filled with `tree`, and answers with a value — the
- * writer decides what a rejection means for the previous output.
+ * It judges a directory the writer has just filled with `tree`, and answers with a
+ * value — the writer decides what a rejection means for the previous output.
  *
  * # Three checks, the strongest available first
  *
  * - **Shape**, always: the directory holds exactly `tree` — no file missing, none
- *   extra, every one byte-for-byte what was emitted — and every file carries the
- *   ownership line. That last is not decoration: the NEXT run reads it to decide
- *   that this directory is a previous generation it may replace whole, so a file
- *   without it would make the next run refuse.
- * - **Types**, when the `typescript` optional peer resolves (Q5, Q6): a real
- *   program over the tree under a consumer's strictest plausible settings. The
- *   tree is judged ALONE — the compiler host serves nothing outside the directory
- *   but TypeScript's own `lib` files, so an import the tree cannot satisfy itself
- *   fails here even when a `node_modules` beside the output could satisfy it
- *   (§15.5).
+ *   extra, every one byte-for-byte what was emitted — every file carries the
+ *   ownership line, and every module a file names is a file of the tree, spelled
+ *   the project's way. The ownership line is not decoration: the NEXT run reads it
+ *   to decide that this directory is a previous generation it may replace whole,
+ *   so a file without it would make the next run refuse. The imports are read
+ *   lexically (`module-specifier.scanner.ts`), with no compiler — so a wrongly
+ *   spelled import is refused even where the type check cannot run (TypeScript 7).
+ * - **Types**, when the `typescript` optional peer resolves: a real program over
+ *   the tree under a consumer's strictest plausible settings, in the project's
+ *   module resolution and format (`compilerOptionsFor`). The tree is judged ALONE
+ *   — the compiler host serves nothing outside the directory but TypeScript's own
+ *   `lib` files, so an import the tree cannot satisfy itself fails here even when
+ *   a `node_modules` beside the output could satisfy it.
  * - **Syntax**, when it does not — or when the `typescript` that resolves has no
- *   classic compiler API (TypeScript 7, plan B3; pilot.1): each file through
- *   Node's own TypeScript parser (`node:module`'s `stripTypeScriptTypes`), with a
- *   loud warning that the output was NOT type-checked. Degraded, never skipped
- *   (S7), and never a refusal: the developer's own `tsc` still checks the tree
- *   when their project compiles.
+ *   classic compiler API: each file through Node's own TypeScript parser
+ *   (`node:module`'s `stripTypeScriptTypes`), with a loud warning that the output
+ *   was NOT type-checked. Degraded, never skipped, and never a refusal: the
+ *   developer's own `tsc` still checks the tree when their project compiles.
  */
 /** The `typescript` module, as the validator uses it. */
 export type TypeScriptCompiler = typeof ts;
@@ -39,7 +39,7 @@ export type TypeScriptResolver = () => Promise<TypeScriptCompiler | undefined>;
  * it up: an optional peer is linked beside the package that declares it.
  */
 export declare function typeScriptResolverFor(specifier: string): TypeScriptResolver;
-/** The `typescript` this package's optional peer names (Q5). */
+/** The `typescript` this package's optional peer names. */
 export declare const resolveInstalledTypeScript: TypeScriptResolver;
 /** How deeply the tree was judged. */
 export type OutputCheck = "types" | "syntax" | "shape";
@@ -72,4 +72,4 @@ export declare function typeScriptWithoutCompilerApiWarning(version: string, che
 /**
  * Judges `directory`, which the caller has just filled with `tree`.
  */
-export declare function validateOutputTree(directory: string, tree: EmittedTree, resolveTypeScript?: TypeScriptResolver): Promise<OutputValidation>;
+export declare function validateOutputTree(directory: string, emission: Pick<ClientEmission, "style" | "tree">, resolveTypeScript?: TypeScriptResolver): Promise<OutputValidation>;

package/dist/output/output.validator.js

@@ -4,10 +4,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { carriesGeneratedOwnership } from "../emit/banner.emitter.js";
-/**
- * A resolver for `specifier`, looked up from this package the way Node would look
- * it up: an optional peer is linked beside the package that declares it.
- */
+import { scanModuleSpecifiers } from "../emit/module-specifier.scanner.js";
 export function typeScriptResolverFor(specifier) {
     return async () => {
         let resolved;
@@ -24,58 +21,35 @@ export function typeScriptResolverFor(specifier) {
         return loaded.default ?? loaded;
     };
 }
-/** The `typescript` this package's optional peer names (Q5). */
 export const resolveInstalledTypeScript = typeScriptResolverFor("typescript");
-/**
- * Whether `compiler` has the classic compiler API {@link typeFindingsOf} uses.
- * TypeScript 7 does not (plan B3: its package exports its version and nothing
- * else); before pilot.1 the generator refused it, and its peer range stopped
- * below it — which made `npm i` fail with ERESOLVE in any frontend whose
- * `typescript` is the current `latest`.
- */
 function hasClassicCompilerApi(compiler) {
-    // One member, not `Partial<typeof ts>`: a mapped type over the whole
-    // compiler namespace costs thousands of instantiations to ask one question.
     return (typeof compiler.createProgram ===
         "function");
 }
-/** The version a resolved `typescript` names, whatever its API. */
 function versionOf(compiler) {
     const { version } = compiler;
     return typeof version === "string" ? version : "(no version)";
 }
-/**
- * The warning a run without `typescript` carries. Loud on purpose, in its words:
- * the prefix is the CLI's one `warning:`, so the text carries none of its own.
- */
 export const TYPESCRIPT_UNRESOLVED_WARNING = "`typescript` could not be resolved, so the generated output was NOT type-checked — " +
     "only its shape and syntax were. Install `typescript` (an optional peer of @aventara/client) " +
     "in this project to restore the type check.";
-/** The warning a run with neither `typescript` nor Node's parser carries. */
 export const SYNTAX_CHECK_UNAVAILABLE_WARNING = "neither `typescript` nor Node's TypeScript parser is available, so the generated " +
     "output was NOT type-checked or parsed — only its shape was. Install `typescript` (an " +
     "optional peer of @aventara/client) in this project to restore the type check.";
-/**
- * The warning a run carries when the `typescript` that resolves is one the
- * generator cannot type-check with (TypeScript 7): what was checked instead,
- * and where the type check still happens.
- */
 export function typeScriptWithoutCompilerApiWarning(version, checked) {
     return (`the installed \`typescript\` ${version} has no classic compiler API (\`createProgram\`), so the generated ` +
         `output was NOT type-checked${checked === "shape" ? " or parsed — only its shape was" : " — only its shape and syntax were"}. ` +
         "Your project's own `tsc` checks it when it compiles; a `typescript` 5.5 to 6 restores the generator's own type check.");
 }
-/**
- * Judges `directory`, which the caller has just filled with `tree`.
- */
-export async function validateOutputTree(directory, tree, resolveTypeScript = resolveInstalledTypeScript) {
-    const shapeFindings = await shapeFindingsOf(directory, tree);
+export async function validateOutputTree(directory, emission, resolveTypeScript = resolveInstalledTypeScript) {
+    const { tree, style } = emission;
+    const shapeFindings = await shapeFindingsOf(directory, tree, style);
     if (shapeFindings.length > 0) {
         return { accepted: false, checked: "shape", findings: shapeFindings };
     }
     const compiler = await resolveTypeScript();
     if (compiler !== undefined && hasClassicCompilerApi(compiler)) {
-        const findings = typeFindingsOf(compiler, directory, tree);
+        const findings = typeFindingsOf(compiler, directory, tree, style);
         return findings.length > 0
             ? { accepted: false, checked: "types", findings }
             : { accepted: true, checked: "types", warnings: [] };
@@ -105,10 +79,7 @@ export async function validateOutputTree(directory, tree, resolveTypeScript = re
             ],
         };
 }
-/* ------------------------------------------------------------------ *
- * Shape                                                                *
- * ------------------------------------------------------------------ */
-async function shapeFindingsOf(directory, tree) {
+async function shapeFindingsOf(directory, tree, style) {
     const findings = [];
     const expected = new Map(tree.map((file) => [file.path, file.bytes]));
     const entries = await readdir(directory, {
@@ -151,29 +122,50 @@ async function shapeFindingsOf(directory, tree) {
         if (!carriesGeneratedOwnership(text)) {
             findings.push(`${relative}: does not carry the generated banner`);
         }
+        for (const specifier of scanModuleSpecifiers(text).specifiers) {
+            if (!namesTreeFile(relative, specifier, style, expected)) {
+                findings.push(`${relative}: imports ${JSON.stringify(specifier)}, which is not a file of the emitted tree spelled with ${JSON.stringify(style.importFileExtension)}`);
+            }
+        }
     }
     return findings.sort();
 }
-/* ------------------------------------------------------------------ *
- * Types: a real program over the tree, and nothing outside it          *
- * ------------------------------------------------------------------ */
-/**
- * The emitted-tree fixture's settings (`__fixtures__/emitted-tree.fixture.ts`),
- * restated here because production code does not import a test fixture: a
- * consumer's strictest plausible configuration, with no DOM and no Node (§15.7:
- * both are first-class targets, so the tree may assume neither).
- */
-function compilerOptionsFor(compiler) {
+function namesTreeFile(file, specifier, style, tree) {
+    if (!specifier.startsWith("./") && !specifier.startsWith("../")) {
+        return false;
+    }
+    const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), specifier));
+    const extension = file.startsWith("generated/derivation/")
+        ? ".js"
+        : style.importFileExtension === ""
+            ? ""
+            : `.${style.importFileExtension}`;
+    const spelled = extension === ""
+        ? !/\.[cm]?[jt]s$/.test(target)
+        : target.endsWith(extension);
+    if (!spelled) {
+        return false;
+    }
+    const stem = target.slice(0, target.length - extension.length);
+    return tree.has(`${stem}.ts`) || tree.has(`${stem}.d.ts`);
+}
+function compilerOptionsFor(compiler, style) {
+    const bundler = style.importFileExtension === "" && style.moduleFormat === "esm";
     return {
         target: compiler.ScriptTarget.ES2022,
-        module: compiler.ModuleKind.NodeNext,
-        moduleResolution: compiler.ModuleResolutionKind.NodeNext,
+        module: bundler ? compiler.ModuleKind.ESNext : compiler.ModuleKind.NodeNext,
+        moduleResolution: bundler
+            ? compiler.ModuleResolutionKind.Bundler
+            : compiler.ModuleResolutionKind.NodeNext,
+        ...(style.importFileExtension === "ts"
+            ? { allowImportingTsExtensions: true }
+            : {}),
         lib: ["lib.es2022.d.ts"],
         types: [],
         strict: true,
         noUncheckedIndexedAccess: true,
         exactOptionalPropertyTypes: true,
-        verbatimModuleSyntax: true,
+        verbatimModuleSyntax: style.moduleFormat === "esm",
         isolatedModules: true,
         erasableSyntaxOnly: true,
         noUnusedLocals: true,
@@ -186,15 +178,12 @@ function compilerOptionsFor(compiler) {
         noEmit: true,
     };
 }
-/**
- * The tree is served as an ES module package of its own: NodeNext reads the
- * nearest `package.json` to decide a `.ts` file's module format, and the one a
- * consumer's project happens to have must not decide this verdict.
- */
-const VIRTUAL_PACKAGE_JSON = '{ "type": "module" }';
-function typeFindingsOf(compiler, directory, tree) {
+function virtualPackageManifest(style) {
+    return `{ "type": "${style.moduleFormat === "esm" ? "module" : "commonjs"}" }`;
+}
+function typeFindingsOf(compiler, directory, tree, style) {
     const root = path.resolve(directory);
-    const options = compilerOptionsFor(compiler);
+    const options = compilerOptionsFor(compiler, style);
     const libraryDirectory = path.dirname(compiler.getDefaultLibFilePath(options));
     const virtualPackageJson = path.join(root, "package.json");
     const servable = (file) => isInside(root, file) || isInside(libraryDirectory, file);
@@ -205,7 +194,7 @@ function typeFindingsOf(compiler, directory, tree) {
     host.fileExists = (file) => path.resolve(file) === virtualPackageJson ||
         (servable(path.resolve(file)) && baseFileExists(file));
     host.readFile = (file) => path.resolve(file) === virtualPackageJson
-        ? VIRTUAL_PACKAGE_JSON
+        ? virtualPackageManifest(style)
         : servable(path.resolve(file))
             ? baseReadFile(file)
             : undefined;
@@ -229,13 +218,11 @@ function typeFindingsOf(compiler, directory, tree) {
     })
         .trimEnd());
 }
-/** Whether `file` is `directory` or lies beneath it. */
 function isInside(directory, file) {
     const relative = path.relative(directory, file);
     return (relative === "" ||
         (!relative.startsWith("..") && !path.isAbsolute(relative)));
 }
-/** Node's TypeScript parser, where this Node has one. */
 function nodeTypeScriptParser() {
     const candidate = nodeModule.stripTypeScriptTypes;
     return typeof candidate === "function" ? candidate : undefined;

package/dist/output/output.writer.d.ts

@@ -3,29 +3,30 @@ import type { AbsolutePath } from "../config/client-config.interface.js";
 import { type ClientEmission, type EmittedTree } from "../emit/emitted-tree.interface.js";
 import { type OutputCheck, type TypeScriptResolver } from "./output.validator.js";
 /**
- * §15.3's last two steps as one call — emit into a temporary directory, validate
- * it, atomically replace the generated output — and the property that makes them
- * one: **a failed generation leaves the previous valid output intact**, byte for
- * byte.
- *
- * # What it owns (architect, 2026-10-04)
- *
  * The output is written into `generateAt`, a directory the developer SHARES: it
- * may hold their own files. The generator owns exactly two entries in it —
- * `AvClient.ts` and `generated/` — and reads, refuses on, moves or deletes
- * nothing else there, apart from the transient entries it names itself
- * (`.aventara-next-*`, `.aventara-ready-*`, `.generated.aventara-previous`).
+ * may hold their own files. The generator owns exactly these entries in it — the
+ * entry file `AvClient.ts` and `generated/` — and reads, refuses on, moves or
+ * deletes nothing else there, apart from the transient entries it names itself
+ * (`.aventara-next-*`, `.aventara-ready-*`, `.generated.aventara-previous`) and an
+ * unreleased build's entry files, `AvClient.mjs` and `AvClient.d.mts`, which it
+ * removes only while they carry the ownership line.
  *
  * - `generated/` is replaced WHOLE, never merged: a file the previous run emitted
- *   and this one does not is gone. It is replaced only when every file in it
- *   carries the generated banner's ownership line (an empty directory owns
- *   nothing and is fine); otherwise the run is refused, naming the foreign files.
- * - `AvClient.ts` is replaced only when it is absent or carries the ownership
+ *   and this one does not is gone — an unreleased build's `.mjs` modules included.
+ *   It is replaced only when every file in it carries the generated banner's
+ *   ownership line (an empty directory owns nothing and is fine); otherwise the
+ *   run is refused, naming the foreign files.
+ * - Each entry file is replaced only when it is absent or carries the ownership
  *   line; otherwise the run is refused, naming it.
+ * - `AvClient.mjs` and `AvClient.d.mts` — an unreleased build's entry — are
+ *   removed when they carry the ownership line, so no stale JavaScript is left
+ *   beside `AvClient.ts`. Without the line each is the developer's own file: never
+ *   read beyond its head, never named, never removed. (pilot.0's and pilot.1's
+ *   `AvClient.ts` is the entry file itself, replaced in place.)
  *
  * # The order, and its one window
  *
- * The whole tree — `AvClient.ts` and `generated/` together — is written into a
+ * The whole tree — the entry files and `generated/` together — is written into a
  * staging directory inside `generateAt` (same filesystem, so every move is one
  * atomic `rename`) and validated there as one program. Then:
  *
@@ -33,19 +34,22 @@ import { type OutputCheck, type TypeScriptResolver } from "./output.validator.js
  *    to be validated;
  * 2. the previous `generated/` → `.generated.aventara-previous`;
  * 3. the staged `generated/` → `generated/`;
- * 4. the staged `AvClient.ts` → `AvClient.ts`, one rename over the old file;
+ * 4. the previous entry files, and an owned earlier entry, move aside into the
+ *    ready directory; then each staged entry file moves in;
  * 5. the previous `generated/` and the staging directory are removed.
  *
- * A failed step 3 renames the previous `generated/` straight back; a failed step
- * 4 moves the new `generated/` out again and the previous back, so a failure at
- * any step leaves the previous pair. Node has no atomic exchange of two entries,
- * so two windows remain for a process KILLED mid-replace, and the next run's
- * recovery closes each before it does anything else:
+ * A failed step 3 renames the previous `generated/` straight back; a failed step 4
+ * moves what it moved back — the new entry files out, the previous ones in — then
+ * the new `generated/` out and the previous back, so a failure at any step leaves
+ * the previous output. Node has no atomic exchange of two entries, so two windows
+ * remain for a process KILLED mid-replace, and the next run's recovery closes each
+ * before it does anything else:
  *
  * - between 2 and 3, `generated/` does not exist: the previous one is put back;
- * - between 3 and 4, the new `generated/` sits beside the old `AvClient.ts`: the
- *   validated `AvClient.ts` is still staged in `.aventara-ready-*`, so it is
- *   moved in, completing the new pair rather than leaving a mismatched one.
+ * - between 3 and the end of 4, the new `generated/` sits beside the old entry
+ *   files, or beside only some new ones: the validated entry files still staged in
+ *   `.aventara-ready-*` are moved in, completing the new output rather than
+ *   leaving a mismatched one.
  *
  * Staging directories that never reached step 1 were not validated and are
  * removed.
@@ -54,16 +58,16 @@ import { type OutputCheck, type TypeScriptResolver } from "./output.validator.js
  *
  * A refusal, a rejected tree or a filesystem error (an `Error` with a `code`) is
  * an `OutputWriteError` naming its stage — the person running the generator can
- * act on it (M3). Any other error is a defect and propagates with its stack —
- * the very error thrown, not a wrapper — and what the run said before it is
- * kept beside it, read by `warningsRaisedBeforeDefect`.
+ * act on it. Any other error is a defect and propagates with its stack — the very
+ * error thrown, not a wrapper — and what the run said before it is kept beside it,
+ * read by `warningsRaisedBeforeDefect`.
  *
- * A refusal carries every warning the run raised before it stopped, in the order
- * a success would have returned them: a crash recovered in `prepare` changed the
+ * A refusal carries every warning the run raised before it stopped, in the order a
+ * success would have returned them: a crash recovered in `prepare` changed the
  * disk, and the person has to hear that even when the run then fails.
  *
- * A failed run removes the directories it created to reach `generateAt` — and
- * only those, and only while empty — so a first run that fails leaves no empty
+ * A failed run removes the directories it created to reach `generateAt` — and only
+ * those, and only while empty — so a first run that fails leaves no empty
  * `generateAt` behind.
  */
 /** The four stages a write passes through, in order. */
@@ -105,22 +109,22 @@ export type OutputFileSystem = Pick<typeof fsPromises, "lstat" | "mkdir" | "open
 export interface ClientOutputWriteInput {
     /** What `emitClientTree` returned: the tree, and the warnings it raised. */
     readonly emission: ClientEmission;
-    /** The resolved `generateAt` (§15.2, architect 2026-10-04). Created when missing. */
+    /** The resolved `generateAt`. Created when missing. */
     readonly generateAt: AbsolutePath;
     /**
-     * Content in `AvClient.ts` or `generated/` the generator did not produce, which
-     * the person running it confirmed may be overwritten or removed (architect,
-     * 2026-10-04) — the paths `findForeignOutputContent` listed. Anything foreign
-     * that is not listed here is refused.
+     * Content in the entry files or `generated/` the generator did not produce, which
+     * the person running it confirmed may be overwritten or removed — the paths
+     * `findForeignOutputContent` listed. Anything foreign that is not listed here is
+     * refused.
      */
     readonly overrideForeign?: readonly string[];
-    /** The `typescript` optional peer; the installed one by default (Q6). */
+    /** The `typescript` optional peer; the installed one by default. */
     readonly resolveTypeScript?: TypeScriptResolver;
     readonly fileSystem?: OutputFileSystem;
 }
 export interface ClientOutputWritten {
     readonly generateAt: AbsolutePath;
-    /** How deeply the tree was validated before it replaced the output (Q6). */
+    /** How deeply the tree was validated before it replaced the output. */
     readonly checked: OutputCheck;
     /**
      * Everything the run has to say without failing, in order: the emission's own
@@ -131,32 +135,32 @@ export interface ClientOutputWritten {
     readonly warnings: readonly string[];
 }
 /**
- * Writes `emission.tree` as `<generateAt>/AvClient.ts` and `<generateAt>/generated/`.
+ * Writes `emission.tree` as `<generateAt>/AvClient.ts` and
+ * `<generateAt>/generated/`.
  *
  * @throws OutputWriteError when the write stops; the previous output is intact.
  */
 export declare function writeClientOutput(input: ClientOutputWriteInput): Promise<ClientOutputWritten>;
 /**
- * Lists what in `<generateAt>/AvClient.ts` and `<generateAt>/generated/` the
- * generator did not produce — a file without the ownership line, a symbolic link,
- * anything that is not a regular file — so the person running it can be asked
- * before a generation overwrites or removes it (architect, 2026-10-04). Reads
- * only; looks at nothing else in `generateAt`. Empty when `generateAt` does not
- * exist yet.
+ * Lists what in the entry files and `<generateAt>/generated/` the generator did
+ * not produce — a file without the ownership line, a symbolic link, anything that
+ * is not a regular file — so the person running it can be asked before a
+ * generation overwrites or removes it. Reads only; looks at nothing else in
+ * `generateAt`. Empty when `generateAt` does not exist yet.
  *
  * It sees what the write will see once it has recovered a killed run, without
  * recovering it: a `generated/` the killed run moved aside with nothing in its
  * place is read where it lies and its files named where recovery puts them back
- * (`generated/…`). So the question asked, and `--yes`, cover them too — and a
- * run that stops here has still touched nothing.
+ * (`generated/…`). So the question asked, and `--yes`, cover them too — and a run
+ * that stops here has still touched nothing.
  *
  * @throws OutputWriteError when `generateAt` is not a directory, `generated` is
- *   not a directory or `AvClient.ts` is not a file: no confirmation repairs that.
+ * not a directory or an entry file is not a file: no confirmation repairs that.
  */
 export declare function findForeignOutputContent(generateAt: AbsolutePath, fileSystem?: OutputFileSystem): Promise<readonly string[]>;
 /**
- * Whether `AvClient.ts` and `generated/` in `generateAt` hold exactly `tree` —
- * every file byte for byte, no other file, and nothing a killed run moved aside —
- * so that writing `tree` would change nothing (Phase 12-rest Q6: "up to date").
+ * Whether the entry files and `generated/` in `generateAt` hold exactly `tree` —
+ * every file byte for byte, no other file, no owned entry of an earlier build, and
+ * nothing a killed run moved aside — so that writing `tree` would change nothing.
  */
 export declare function ownedOutputMatches(generateAt: AbsolutePath, tree: EmittedTree): Promise<boolean>;