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

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,25 @@ 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; by default the project's own, resolved from
+     * `generateAt`.
+     */
     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 +138,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>;

package/dist/output/output.writer.js

@@ -2,24 +2,17 @@ import { randomBytes } from "node:crypto";
 import * as fsPromises from "node:fs/promises";
 import path from "node:path";
 import { carriesGeneratedOwnership, GENERATED_OWNERSHIP_HEAD_BYTES, } from "../emit/banner.emitter.js";
-import { CLIENT_ENTRY_FILE, GENERATED_DIRECTORY, } from "../emit/emitted-tree.interface.js";
-import { resolveInstalledTypeScript, validateOutputTree, } from "./output.validator.js";
-/** A write that stopped; the previous output is intact unless it says otherwise. */
+import { CLIENT_ENTRY_FILES, GENERATED_DIRECTORY, LEGACY_CLIENT_ENTRY_FILES, } from "../emit/emitted-tree.interface.js";
+import { projectTypeScriptResolver, validateOutputTree, } from "./output.validator.js";
 export class OutputWriteError extends Error {
     stage;
     name = "OutputWriteError";
-    /**
-     * What the run said before it stopped, in the order a success returns its
-     * warnings: the emission's, the validator's, the writer's. Printed before the
-     * refusal's sentence.
-     */
     warnings;
     constructor(stage, message, options) {
         super(message, options);
         this.stage = stage;
         this.warnings = options?.warnings ?? [];
     }
-    /** The same refusal, with `earlier` said before the warnings it already carries. */
     precededBy(earlier) {
         return new OutputWriteError(this.stage, this.message, {
             cause: this.cause,
@@ -27,18 +20,7 @@ export class OutputWriteError extends Error {
         });
     }
 }
-/**
- * What a run said before a defect stopped it, kept beside the defect rather than
- * on a wrapper: a defect propagates as the very error thrown, with its own stack,
- * so a caller matching it by identity or type still can. Keyed weakly, so it
- * lives exactly as long as the error does. A thrown primitive cannot be a key;
- * what was said before one is not kept.
- */
 const WARNINGS_BEFORE_DEFECT = new WeakMap();
-/**
- * Records `earlier` as said before `defect`, ahead of anything already recorded,
- * and returns `defect` unchanged so the caller rethrows the same error.
- */
 export function precedeDefect(defect, earlier) {
     if (earlier.length > 0 && typeof defect === "object" && defect !== null) {
         WARNINGS_BEFORE_DEFECT.set(defect, [
@@ -48,10 +30,6 @@ export function precedeDefect(defect, earlier) {
     }
     return defect;
 }
-/**
- * What the run said before `defect` stopped it, in the order a success returns
- * its warnings; empty when nothing was, or for an error no run threw.
- */
 export function warningsRaisedBeforeDefect(defect) {
     return typeof defect === "object" && defect !== null
         ? (WARNINGS_BEFORE_DEFECT.get(defect) ?? [])
@@ -60,23 +38,20 @@ export function warningsRaisedBeforeDefect(defect) {
 const NEXT_PREFIX = ".aventara-next-";
 const READY_PREFIX = ".aventara-ready-";
 const PREVIOUS_GENERATED = `.${GENERATED_DIRECTORY}.aventara-previous`;
-/**
- * Writes `emission.tree` as `<generateAt>/AvClient.ts` and `<generateAt>/generated/`.
- *
- * @throws OutputWriteError when the write stops; the previous output is intact.
- */
-export async function writeClientOutput(input) {
-    const fs = input.fileSystem ?? fsPromises;
-    const generateAt = path.resolve(input.generateAt);
-    const paths = {
+const PREVIOUS_ENTRIES = ".previous-entries";
+function outputPathsOf(generateAt) {
+    return {
         generateAt,
         generated: path.join(generateAt, GENERATED_DIRECTORY),
-        entry: path.join(generateAt, CLIENT_ENTRY_FILE),
         previous: path.join(generateAt, PREVIOUS_GENERATED),
     };
+}
+export async function writeClientOutput(input) {
+    const fs = input.fileSystem ?? fsPromises;
+    const generateAt = path.resolve(input.generateAt);
+    const paths = outputPathsOf(generateAt);
     const writerWarnings = [];
     let validationWarnings = [];
-    /** The outermost directory this run created on the way to `generateAt`, if any. */
     let created;
     try {
         return await writeStagedOutput();
@@ -95,7 +70,6 @@ export async function writeClientOutput(input) {
             : precedeDefect(error, said);
     }
     async function writeStagedOutput() {
-        // prepare — recover a killed run, then decide whether the two entries are ours.
         const state = await stage("prepare", paths, async () => {
             created = await ensureDirectory(fs, generateAt);
             writerWarnings.push(...(await recoverInterruptedRun(fs, paths)));
@@ -107,14 +81,11 @@ export async function writeClientOutput(input) {
             }
             return inspection;
         });
-        // temp — the whole tree, AvClient.ts and generated/ together, staged in generateAt.
         const suffix = randomBytes(6).toString("hex");
         let staging = path.join(generateAt, `${NEXT_PREFIX}${suffix}`);
         let stagingExists = false;
         try {
             await stage("temp", paths, async () => {
-                // `mkdir`, not `mkdtemp`: generated/ is moved out of this directory and
-                // takes the mode any directory the user creates takes (`mkdtemp` makes 0700).
                 await fs.mkdir(staging);
                 stagingExists = true;
                 for (const file of input.emission.tree) {
@@ -123,8 +94,7 @@ export async function writeClientOutput(input) {
                     await fs.writeFile(target, file.bytes);
                 }
             });
-            // validate — Q6, over AvClient.ts and generated/ as one program.
-            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission.tree, input.resolveTypeScript ?? resolveInstalledTypeScript));
+            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission, input.resolveTypeScript ?? projectTypeScriptResolver(generateAt)));
             if (validation.accepted) {
                 validationWarnings = validation.warnings;
             }
@@ -133,7 +103,6 @@ export async function writeClientOutput(input) {
                     "This is a defect in @aventara/client; please report it with these findings:\n" +
                     validation.findings.map((finding) => `  ${finding}`).join("\n"));
             }
-            // replace — the order and its rollbacks are the module doc's.
             await stage("replace", paths, async () => {
                 const ready = path.join(generateAt, `${READY_PREFIX}${suffix}`);
                 await fs.rename(staging, ready);
@@ -151,11 +120,28 @@ export async function writeClientOutput(input) {
                     }
                     throw error;
                 }
+                const aside = path.join(staging, PREVIOUS_ENTRIES);
+                const movedOut = [];
+                const movedIn = [];
                 try {
-                    await fs.rename(path.join(staging, CLIENT_ENTRY_FILE), paths.entry);
+                    await fs.mkdir(aside);
+                    for (const name of [...state.entries, ...state.legacy]) {
+                        await fs.rename(path.join(generateAt, name), path.join(aside, name));
+                        movedOut.push(name);
+                    }
+                    for (const name of CLIENT_ENTRY_FILES) {
+                        await fs.rename(path.join(staging, name), path.join(generateAt, name));
+                        movedIn.push(name);
+                    }
                 }
                 catch (error) {
                     await rollBack(paths, error, async () => {
+                        for (const name of movedIn.reverse()) {
+                            await fs.rename(path.join(generateAt, name), path.join(staging, name));
+                        }
+                        for (const name of movedOut.reverse()) {
+                            await fs.rename(path.join(aside, name), path.join(generateAt, name));
+                        }
                         await fs.rename(paths.generated, path.join(staging, GENERATED_DIRECTORY));
                         if (movedAside) {
                             await fs.rename(paths.previous, paths.generated);
@@ -186,23 +172,14 @@ export async function writeClientOutput(input) {
         finally {
             if (stagingExists) {
                 await fs.rm(staging, { recursive: true, force: true }).catch(() => {
-                    // The next run removes it by name; the error being thrown matters more.
                 });
             }
         }
     }
 }
-/** The sentence's ending when the previous output was not changed. */
 function LEFT_AS_THEY_WERE(paths) {
-    return `${CLIENT_ENTRY_FILE} and ${GENERATED_DIRECTORY}/ in ${paths.generateAt} were left exactly as they were.`;
+    return `${CLIENT_ENTRY_FILES.join(", ")} and ${GENERATED_DIRECTORY}/ in ${paths.generateAt} were left exactly as they were.`;
 }
-/**
- * Creates `generateAt` when missing; refuses when something other than a
- * directory is there.
- *
- * @returns the outermost directory it created — `generateAt` or an ancestor —
- *   or `undefined` when `generateAt` already existed.
- */
 async function ensureDirectory(fs, generateAt) {
     const stats = await lstatOrUndefined(fs, generateAt);
     if (stats === undefined) {
@@ -213,12 +190,6 @@ async function ensureDirectory(fs, generateAt) {
     }
     return undefined;
 }
-/**
- * Removes, after a failed run, the directories it created: `generateAt` and each
- * parent up to `outermost`, innermost first. `rmdir` removes only an empty
- * directory, so nothing anyone else put there meanwhile is lost; the first one
- * that cannot be removed ends the walk, and is named in the warning returned.
- */
 async function removeCreatedDirectories(fs, generateAt, outermost) {
     for (let directory = generateAt;; directory = path.dirname(directory)) {
         try {
@@ -235,29 +206,23 @@ async function removeCreatedDirectories(fs, generateAt, outermost) {
         }
     }
 }
-/**
- * Leftovers of a run that was killed, recognised only by the names this writer
- * gives them:
- *
- * - a staging directory that never became ready was not validated: removed;
- * - a ready one whose `generated/` was already moved in but whose `AvClient.ts`
- *   was not: its `AvClient.ts` is moved in, completing the new pair;
- * - any other ready one: removed;
- * - a previous `generated/` moved aside: put back when nothing replaced it,
- *   removed when something did.
- */
 async function recoverInterruptedRun(fs, paths) {
     const warnings = [];
     for (const entry of (await fs.readdir(paths.generateAt)).sort()) {
         const leftover = path.join(paths.generateAt, entry);
         if (entry.startsWith(READY_PREFIX)) {
-            const stagedEntry = path.join(leftover, CLIENT_ENTRY_FILE);
             const generatedMovedIn = (await lstatOrUndefined(fs, path.join(leftover, GENERATED_DIRECTORY))) === undefined;
-            if (generatedMovedIn &&
-                (await lstatOrUndefined(fs, stagedEntry)) !== undefined) {
-                await fs.rename(stagedEntry, paths.entry);
-                warnings.push(`an interrupted run had moved its generated/ in but not its AvClient.ts; ` +
-                    `the validated AvClient.ts was moved in at ${paths.entry} before generating.`);
+            const completed = [];
+            for (const name of generatedMovedIn ? CLIENT_ENTRY_FILES : []) {
+                const staged = path.join(leftover, name);
+                if ((await lstatOrUndefined(fs, staged)) !== undefined) {
+                    await fs.rename(staged, path.join(paths.generateAt, name));
+                    completed.push(name);
+                }
+            }
+            if (completed.length > 0) {
+                warnings.push(`an interrupted run had moved its generated/ in but not all of its entry files; ` +
+                    `the validated ${completed.join(", ")} ${completed.length === 1 ? "was" : "were"} moved in at ${paths.generateAt} before generating.`);
             }
             await fs.rm(leftover, { recursive: true, force: true });
         }
@@ -277,35 +242,12 @@ async function recoverInterruptedRun(fs, paths) {
     }
     return warnings;
 }
-/**
- * Where the `generated/` a run works with comes from once a killed run is
- * recovered: the previous one moved aside when nothing replaced it — recovery
- * puts it back — and `generated/` otherwise. One answer for the recovery and for
- * the read-only look ahead of it, so the two cannot disagree.
- */
 async function generatedAfterRecovery(fs, paths) {
     return (await lstatOrUndefined(fs, paths.generated)) === undefined &&
         (await lstatOrUndefined(fs, paths.previous)) !== undefined
         ? paths.previous
         : paths.generated;
 }
-/**
- * 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.
- *
- * 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.
- *
- * @throws OutputWriteError when `generateAt` is not a directory, `generated` is
- *   not a directory or `AvClient.ts` is not a file: no confirmation repairs that.
- */
 export async function findForeignOutputContent(generateAt, fileSystem = fsPromises) {
     const root = path.resolve(generateAt);
     const stats = await lstatOrUndefined(fileSystem, root);
@@ -315,21 +257,10 @@ export async function findForeignOutputContent(generateAt, fileSystem = fsPromis
     if (!stats.isDirectory()) {
         throw notADirectory(root);
     }
-    const paths = {
-        generateAt: root,
-        generated: path.join(root, GENERATED_DIRECTORY),
-        entry: path.join(root, CLIENT_ENTRY_FILE),
-        previous: path.join(root, PREVIOUS_GENERATED),
-    };
+    const paths = outputPathsOf(root);
     const inspection = await inspectOwnedEntries(fileSystem, paths, await generatedAfterRecovery(fileSystem, paths));
     return inspection.foreign;
 }
-/**
- * What stands at the two owned entries. `generatedSource` is the directory read
- * as `generated/` — `generated/` itself, or the previous one a killed run moved
- * aside, which recovery will put back there — and its files are named as
- * `generated/…` either way.
- */
 async function inspectOwnedEntries(fs, paths, generatedSource = paths.generated) {
     const foreign = [];
     const relative = (file) => path.relative(paths.generateAt, file).split(path.sep).join("/");
@@ -353,23 +284,37 @@ async function inspectOwnedEntries(fs, paths, generatedSource = paths.generated)
             }
         }
     }
-    const entryStats = await lstatOrUndefined(fs, paths.entry);
-    if (entryStats !== undefined) {
-        if (!entryStats.isFile()) {
-            throw new OutputWriteError("prepare", `refusing to replace ${paths.entry}: it is not a file, and the generator owns ${CLIENT_ENTRY_FILE} ` +
+    const entries = [];
+    for (const name of CLIENT_ENTRY_FILES) {
+        const file = path.join(paths.generateAt, name);
+        const stats = await lstatOrUndefined(fs, file);
+        if (stats === undefined) {
+            continue;
+        }
+        if (!stats.isFile()) {
+            throw new OutputWriteError("prepare", `refusing to replace ${file}: it is not a file, and the generator owns ${name} ` +
                 "as one; move it, or choose another `generateAt`. Nothing was written.");
         }
-        if (!(await carriesOwnershipLine(fs, paths.entry))) {
-            foreign.push(relative(paths.entry));
+        entries.push(name);
+        if (!(await carriesOwnershipLine(fs, file))) {
+            foreign.push(relative(file));
+        }
+    }
+    const legacy = [];
+    for (const name of LEGACY_CLIENT_ENTRY_FILES) {
+        const file = path.join(paths.generateAt, name);
+        if ((await lstatOrUndefined(fs, file))?.isFile() === true &&
+            (await carriesOwnershipLine(fs, file))) {
+            legacy.push(name);
         }
     }
     return {
         generated: generatedStats === undefined ? "absent" : "present",
-        entry: entryStats === undefined ? "absent" : "present",
+        entries,
+        legacy,
         foreign: foreign.sort(),
     };
 }
-/** Foreign content nobody confirmed may be overwritten. */
 function foreignContentRefusal(paths, foreign) {
     const them = foreign.length === 1 ? "it" : "them";
     return new OutputWriteError("prepare", `refusing to generate into ${paths.generateAt}: ${foreign.join(", ")} ${foreign.length === 1 ? "was" : "were"} ` +
@@ -391,10 +336,6 @@ async function carriesOwnershipLine(fs, file) {
         await handle.close();
     }
 }
-/**
- * Undoes a replace that stopped part-way. When the undo itself fails, the
- * sentence says where the previous `generated/` is: the next run puts it back.
- */
 async function rollBack(paths, cause, undo) {
     try {
         await undo();
@@ -405,11 +346,6 @@ async function rollBack(paths, cause, undo) {
             `${GENERATED_DIRECTORY}/ is intact at ${paths.previous}; the next run puts it back.`, { cause });
     }
 }
-/**
- * Runs one stage, turning a filesystem error into that stage's sentence. An
- * `OutputWriteError` passes through; anything without a `code` is a defect and
- * keeps its stack.
- */
 async function stage(name, paths, run) {
     try {
         return await run();
@@ -447,16 +383,18 @@ function describe(error) {
         ? `${error.code}: ${error.message}`
         : String(error);
 }
-/**
- * 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").
- */
 export async function ownedOutputMatches(generateAt, tree) {
     const root = path.resolve(generateAt);
     if ((await lstatOrUndefined(fsPromises, path.join(root, PREVIOUS_GENERATED))) !== undefined) {
         return false;
     }
+    for (const name of LEGACY_CLIENT_ENTRY_FILES) {
+        const file = path.join(root, name);
+        if ((await lstatOrUndefined(fsPromises, file))?.isFile() === true &&
+            (await carriesOwnershipLine(fsPromises, file))) {
+            return false;
+        }
+    }
     let present;
     try {
         present = (await fsPromises.readdir(path.join(root, GENERATED_DIRECTORY), {
@@ -476,7 +414,7 @@ export async function ownedOutputMatches(generateAt, tree) {
         throw error;
     }
     const expected = new Set(tree.map((file) => file.path));
-    if (present.length + 1 !== expected.size ||
+    if (present.length + CLIENT_ENTRY_FILES.length !== expected.size ||
         present.some((file) => !expected.has(file))) {
         return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "0.1.0-pilot.1",
+  "version": "0.1.0-pilot.3",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Development-time generator for Aventara typed remote clients.",
   "type": "module",
@@ -23,7 +23,9 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.1"
+    "@aventara/core": "0.1.0-pilot.3",
+    "c12": "3.3.4",
+    "get-tsconfig": "4.10.0"
   },
   "peerDependencies": {
     "typescript": ">=5.5.0"
@@ -37,12 +39,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "0.1.0-pilot.1",
+    "@aventara/testing": "0.1.0-pilot.3",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
     "lint": "biome lint src"