@fougere/core 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/scan/conventions.ts

@@ -1,19 +1,7 @@
-/**
- * The names the scan READS instead of deriving them.
- *
- * Everything else a frond states, it states by its shape; these seven directories and the
- * import prefix are the one place where a name is the declaration. They were spelled as
- * literals in five packages, so a project could not move any of them and `frondsDir` was
- * a declared key with no reader.
- */
+/** The names the scan READS instead of deriving them. */
 
 export interface Conventions {
-  /**
-   * The scope a frond's package name carries — `@fronds/blog`.
-   *
-   * A real package name, not only an alias: the CLI writes it as `name` in a scaffolded
-   * frond and as a `workspace:*` dependency in the app that consumes it.
-   */
+  /** The scope a frond's package name carries — `@fronds/blog`. */
   scope: string;
   /** The directory holding fronds, below the project root. */
   fronds: string;
@@ -31,12 +19,7 @@ export interface Conventions {
   };
 }
 
-/**
- * What a project means when it declares nothing — the convention itself.
- *
- * `@fronds` and not `@frond`: the npm org for the singular belongs to someone else, and a
- * scope is a name that must be ownable.
- */
+/** What a project means when it declares nothing — the convention itself. */
 export const DEFAULT_CONVENTIONS: Conventions = {
   scope: '@fronds',
   fronds: 'fronds',
@@ -59,13 +42,7 @@ export type ConventionsInput = {
   dirs?: Partial<Conventions['dirs']>;
 };
 
-/**
- * The convention, with a project's exceptions folded in.
- *
- * Merged one level into `dirs` so renaming one directory does not require restating the
- * other six — the same reading `sources:` and `ports:` get, where only the exception is
- * declared.
- */
+/** The convention, with a project's exceptions folded in. */
 export function resolveConventions(input?: ConventionsInput): Conventions {
   return {
     scope: input?.scope ?? DEFAULT_CONVENTIONS.scope,
@@ -79,23 +56,12 @@ export function frondPackage(name: string, conventions: Conventions): string {
   return `${conventions.scope}/${name}`;
 }
 
-/**
- * Directories whose classes register as providers — two spellings, one behaviour.
- *
- * A project may point both roles at one directory; the scan must then read it once, or
- * every provider would be registered twice.
- */
+/** Directories whose classes register as providers — two spellings, one behaviour. */
 export function providerDirsOf(conventions: Conventions): string[] {
   return [...new Set([conventions.dirs.services, conventions.dirs.repositories])];
 }
 
-/**
- * The frond vocabulary — every directory the scan reads.
- *
- * What a reader needs to bound a frond: the Nuxt module watches these for the root frond
- * (watching the root itself would match every write), and a flat app's tsconfig lists
- * them instead of `["."]`, which would swallow `app/` and `nuxt.config.ts`.
- */
+/** The frond vocabulary — every directory the scan reads. */
 export function frondDirsOf(conventions: Conventions): string[] {
   const { entities, handlers, presenters, collectors, seeds, versions } = conventions.dirs;
   return [...new Set([

package/src/scan/emit.ts

@@ -1,19 +1,4 @@
-/**
- * The scan, written down as a module — what `createApp` is handed where there is no disk.
- *
- * It RE-RESOLVES NOTHING. By the time this runs the scan has already decided what every
- * slot holds, and `resolveSchema` put the entity's own class in `contract.output` — the
- * very object `EntityEntry.entityClass` holds. So the emitter keeps a table from object
- * to import alias and writes the alias. Identity is preserved because it is the same
- * object that becomes the same import, which is what three call sites depend on
- * (`adapter/graphql`'s `view === entity.entityClass` and its WeakMap, and `bootstrap`'s
- * `outputSchema !== entity.entityClass`). An emitter that re-resolved instead would build
- * a second class for `Post` and those three would silently take the other branch.
- *
- * Measured on three real projects: every live reference is either a class the descriptor
- * already names by `filePath`, a named export of the file that declared the signature, or
- * `Partial<X>` — the one derivation `resolveSchema` fabricates.
- */
+/** The scan, written down as a module — what `createApp` is handed where there is no disk. */
 import { dirname, relative } from 'node:path';
 import { ANONYMOUS_SCHEMA_NAME, Card, type SchemaView } from '@fougere/schema';
 import type { FrondDescriptor, EntityEntry, HandlerEntry, PresenterEntry, CollectorEntry, ProviderEntry, SeedEntry } from '../descriptor/frond.js';
@@ -32,14 +17,7 @@ type Live = object;
 /** Is a TypeScript compiler going to read this module? Its name is the only thing that says. */
 const isTypeScript = (outFile: string): boolean => /\.tsx?$/.test(outFile);
 
-/**
- * A source file becomes a specifier its reader can follow — and the two readers differ.
- *
- * A `.ts` destination is compiled by tsc under Node16 resolution, which spells a
- * TypeScript source with `.js`. A `.mjs` destination is read by a bundler, which resolves
- * the path AS IT IS ON DISK — measured, Nitro's rollup refused `Post.seed.js` because no
- * such file exists. One rule, read off the destination, exactly like the type annotation.
- */
+/** A source file becomes a specifier its reader can follow — and the two readers differ. */
 function specifierOf(filePath: string, outFile: string): string {
   const path = relative(dirname(outFile), filePath);
   const rel = isTypeScript(outFile) ? path.replace(/\.tsx?$/, '.js') : path;
@@ -81,15 +59,7 @@ class Imports {
   render(): string { return this.lines.join('\n'); }
 }
 
-/**
- * What a schema slot becomes in the generated module.
- *
- * Three answers, and the third is the only rule: a class already imported is its alias; a
- * named export of the file that declared the signature is imported by its own name — it
- * IS exported there, because that is where `resolveSchema` found it; and an anonymous
- * schema is `Partial<X>`, the one derivation `resolveSchema` builds, so it is written as
- * the derivation rather than as a value.
- */
+/** What a schema slot becomes in the generated module. */
 function schemaRef(schema: SchemaView | undefined, declaredIn: string, imports: Imports): string | undefined {
   if (!schema) return undefined;
   const known = imports.aliasOf(schema as Live);
@@ -178,11 +148,7 @@ function frondOf(f: FrondDescriptor, imports: Imports): string {
   ].filter(Boolean).join('\n');
 }
 
-/**
- * Write a scan down. The result is a TypeScript module whose only imports are the classes
- * the scan found — static, so a bundler traces them — and whose only value is the
- * descriptor `createApp` asks for.
- */
+/** Write a scan down. */
 export function emitScan(result: ScanResult, options: EmitOptions): string {
   const imports = new Imports(options.outFile);
   const core = options.core ?? '@fougere/core';

package/src/scan/handler-parser.ts

@@ -1,9 +1,4 @@
-/**
- * Handler signature parser — extracts method signatures from handler source files.
- *
- * The AST says what the author declared; TypeScript's checker says what those types mean.
- * TypeScript is lazy-loaded to avoid bundling the compiler in production builds.
- */
+/** Handler signature parser — extracts method signatures from handler source files. */
 import type { TypeRef, Param, Signature } from '../wire/signature.js';
 import type ts from '@typescript/typescript6';
 import { readFileSync, existsSync, statSync } from 'node:fs';
@@ -26,26 +21,11 @@ interface TypeProject {
   program: ts.Program;
 }
 
-/**
- * One checked program per project/configuration during a scan.
- *
- * A checker is a project reader, not a file parser: creating one per handler would reopen
- * the standard library and every imported declaration for each method. `scanProject`
- * resets this map at the start of a run, so an edited source can never meet a program from
- * the previous run.
- */
+/** One checked program per project/configuration during a scan. */
 const typeProjects = new Map<string, TypeProject>();
 const compilerProjects = new Map<string, { key: string; roots: string[]; options: ts.CompilerOptions }>();
 
-/**
- * What survives a run: the parsed declarations, and the program built over them.
- *
- * Rebuilding a program re-reads `lib.d.ts` and every imported `.d.ts`, and that is FIXED
- * work — measured, a second scan in one process cost the same at 16 frond files as at 406.
- * The mtime is the guard, so a run still cannot see a stale type: a file that moved is
- * re-read and TypeScript invalidates it and everything depending on it, which is a
- * narrower rule than discarding the program and not a weaker one.
- */
+/** What survives a run. */
 const sourceFiles = new Map<string, { mtime: number; file: ts.SourceFile }>();
 const retained = new Map<string, { host: ts.CompilerHost; program: ts.Program }>();
 
@@ -61,8 +41,8 @@ export function forgetParsedSources(): void {
 }
 
 function keptHost(key: string, options: ts.CompilerOptions): ts.CompilerHost {
-  const held = retained.get(key);
-  if (held) return held.host;
+  const cached = retained.get(key);
+  if (cached) return cached.host;
   const typescript = getTS();
   const base = typescript.createCompilerHost(options);
   const host: ts.CompilerHost = {
@@ -138,13 +118,7 @@ function compilerProjectOf(filePath: string, projectRoot?: string): { key: strin
   return configured;
 }
 
-/**
- * Declare every file a run will read, so one program covers it.
- *
- * `checkedSourceOf` rebuilds whenever it meets a root it has not seen, and a frond lives
- * outside its project's tsconfig `include`, so every declaration was a new root: 44 files
- * cost 7.3 s that way against 0.34 s for one program.
- */
+/** Declare every file a run will read, so one program covers it. */
 export async function seedTypeProgram(filePaths: readonly string[], projectRoot?: string): Promise<void> {
   const typescript = await loadTS();
   const grouped = new Map<string, { options: ts.CompilerOptions; paths: string[] }>();
@@ -152,9 +126,9 @@ export async function seedTypeProgram(filePaths: readonly string[], projectRoot?
   for (const filePath of filePaths) {
     const absolute = resolvePath(filePath);
     const configured = compilerProjectOf(absolute, projectRoot);
-    const held = grouped.get(configured.key) ?? { options: configured.options, paths: [] };
-    held.paths.push(absolute);
-    grouped.set(configured.key, held);
+    const group = grouped.get(configured.key) ?? { options: configured.options, paths: [] };
+    group.paths.push(absolute);
+    grouped.set(configured.key, group);
   }
 
   for (const [key, { options, paths }] of grouped) {
@@ -168,25 +142,25 @@ function checkedSourceOf(filePath: string, projectRoot?: string): { source: ts.S
   const typescript = getTS();
   const absolute = resolvePath(filePath);
   const configured = compilerProjectOf(absolute, projectRoot);
-  let held = typeProjects.get(configured.key);
+  let project = typeProjects.get(configured.key);
 
-  if (!held) {
+  if (!project) {
     // `path.resolve` is variadic, so handing it directly to `map` also passed the
     // index and the whole roots array as path segments. A fixture without a warm scan
     // cache exposed that first-run-only failure.
     const roots = new Set(configured.roots.map((root) => resolvePath(root)));
     roots.add(absolute);
     const program = builtProgram(configured.key, [...roots], configured.options);
-    held = { roots, options: configured.options, program };
-    typeProjects.set(configured.key, held);
-  } else if (!held.roots.has(absolute)) {
-    held.roots.add(absolute);
-    held.program = builtProgram(configured.key, [...held.roots], held.options);
+    project = { roots, options: configured.options, program };
+    typeProjects.set(configured.key, project);
+  } else if (!project.roots.has(absolute)) {
+    project.roots.add(absolute);
+    project.program = builtProgram(configured.key, [...project.roots], project.options);
   }
 
-  const source = held.program.getSourceFile(absolute);
+  const source = project.program.getSourceFile(absolute);
   if (!source) throw new Error(`TypeScript did not include '${absolute}' in its program.`);
-  return { source, checker: held.program.getTypeChecker() };
+  return { source, checker: project.program.getTypeChecker() };
 }
 
 /** A file, opened. Five places read and parsed one, each spelling the same two calls. */
@@ -428,20 +402,7 @@ function resolveSpecifier(specifier: string, fromFile: string, projectRoot: stri
 
 // ── Mixin / heritage parsing ─────────────────
 
-/**
- * The class a returned expression carries, however it is wrapped.
- *
- * A mixin does not always hand its class back bare. `Crud` returns
- * `asCrudConstructor(class CrudHandler { … })` — one assertion helper standing between
- * `return` and the class — and a parser accepting only a bare `return class` found
- * nothing there, silently: the five inherited CRUD ops stopped being derived, and a warm
- * scan cache kept answering the old parse for weeks (`scan-cache.ts` keys on source, not
- * on parser version).
- *
- * So unwrap rather than match one shape: descend through call arguments, `as` and
- * `satisfies` assertions, and parentheses. What is looked for is a class; where the
- * author put it is their business.
- */
+/** The class a returned expression carries, however it is wrapped. */
 function classInExpression(expr: ts.Node, depth = 0): ts.ClassExpression | undefined {
   const ts = getTS();
   if (depth > 8) return undefined;
@@ -502,7 +463,7 @@ function extractClassMethods(
     // `private`/`protected` is a statement about the surface, and the AST carries it —
     // it was read past. Every helper a handler names by intent (`mustOwn`, `readMany`,
     // `refuse`) became a callable op: measured on the bench, `list.readMany` executed
-    // and `list.mayPublish` judged its argument. A door is what the author declares
+    // and `list.mayPublish` validated its argument. A door is what the author declares
     // public, and TypeScript already has the word for it. `#name` is private too, but
     // it is not an identifier, so it never reached here in the first place.
     if (member.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword)) continue;
@@ -521,14 +482,7 @@ function extractClassMethods(
   return results;
 }
 
-/**
- * The first sentence of a member's doc comment, or nothing.
- *
- * One sentence on purpose: what a caller needs to choose an operation is a claim,
- * not an essay, and the rest of the comment addresses whoever edits the method.
- * Reads the leading trivia rather than `ts.getJSDocTags` — the comment is what the
- * author wrote, tags are a schema they never agreed to.
- */
+/** The first sentence of a member's doc comment, or nothing. */
 function docSentenceOf(member: ts.Node, source: ts.SourceFile): string | undefined {
   const ts = getTS();
   const ranges = ts.getLeadingCommentRanges(source.text, member.pos) ?? [];
@@ -551,11 +505,7 @@ function docSentenceOf(member: ts.Node, source: ts.SourceFile): string | undefin
  * Parse inherited methods from a class's heritage clause.
  * Handles both `extends Crud(Entity)` (mixin) and `extends BaseClass` patterns.
  */
-/**
- * Where a name used here is declared. The checker follows the import, the re-export chain
- * and an installed package's types — the three cases three hand-rolled functions treated
- * separately.
- */
+/** Where a name used here is declared. */
 function declarationFileOf(node: ts.Node, checker: ts.TypeChecker): string | undefined {
   const typescript = getTS();
   let symbol = checker.getSymbolAtLocation(node);
@@ -564,13 +514,7 @@ function declarationFileOf(node: ts.Node, checker: ts.TypeChecker): string | und
   return symbol.declarations?.[0]?.getSourceFile().fileName;
 }
 
-/**
- * The methods a base class contributes, read from the INSTANTIATED type.
- *
- * `extends Crud(Post)` gives `create(input: Partial<Post>)` directly: the checker has
- * already substituted the mixin's type parameter. The three functions this replaces
- * detected the generic names and mapped them to the mixin's arguments by position.
- */
+/** The methods a base class contributes, read from the INSTANTIATED type. */
 function inheritedFromBase(
   base: ts.ExpressionWithTypeArguments,
   checker: ts.TypeChecker,
@@ -617,10 +561,8 @@ function parseInheritedMethods(
   checker: ts.TypeChecker,
   skip: Set<string>,
   /**
-   * Base classes this pass could not open — an INSTALLED one, typically, whose
-   * source is not in the workspace. Reported rather than treated as "no inherited
-   * method": the two used to be the same answer, so an op inherited from a
-   * published base class was absent from the façade without a word.
+   * Base classes this pass could not open — an INSTALLED one, typically, whose source is not in
+   * the workspace.
    */
   unresolved: string[],
 ): Signature[] {
@@ -685,14 +627,7 @@ function findDefaultClass(source: ts.SourceFile): ts.ClassDeclaration | undefine
   return undefined;
 }
 
-/**
- * What a handler file yielded — its methods, AND what the pass could not open.
- *
- * The second half is why this is a pair rather than an array: an unresolvable base
- * class used to give the same answer as a base class with no method, so an op
- * inherited from an installed package was missing from the façade in silence. The
- * pair travels through the scan cache, which is why {@link PARSER_VERSION} moved.
- */
+/** What a handler file yielded — its methods, AND what the pass could not open. */
 export interface HandlerParse {
   methods: Signature[];
   /** Base classes whose source this pass could not open. Empty is a claim. */
@@ -708,11 +643,7 @@ export async function parseAllHandlerMethods(filePath: string, projectRoot?: str
   return parseClassMethods(filePath, CONSTRUCTOR_ONLY, projectRoot);
 }
 
-/**
- * Parse a presenter source file and extract all method signatures.
- *
- * Returns all methods (no CRUD filtering) — each method is a computed field.
- */
+/** Parse a presenter source file and extract all method signatures. */
 export async function parsePresenterMethods(filePath: string, projectRoot?: string): Promise<Signature[]> {
   await loadTS();
   // No `projectRoot`, so no heritage pass and nothing to report: a presenter's

package/src/scan/result.ts

@@ -1,24 +1,11 @@
 import type { Fronds } from '../descriptor/Fronds.js';
 
 /** Result of scanning a project directory. */
-/**
- * Something the scan could NOT do — recorded instead of swallowed.
- *
- * The scan answers with what it found. Until now it answered the same way whether
- * a directory held nothing or could not be read, and whether a handler declared no
- * operation or failed to parse: `catch → empty`. So every downstream reader — the
- * façade, the identity card, anything asking "what does this app serve?" — could
- * not tell **"there is nothing"** from **"I could not look"**.
- *
- * That distinction is what makes a rule about an ABSENCE sound. Without it, a check
- * derived from the scan reports "nothing wrong" precisely when it read nothing.
- */
+/** Something the scan could NOT do — recorded instead of swallowed. */
 export interface ScanDiagnostic {
   /**
-   * `blocking` — the app now serves less than its source declares, and no caller
-   * can know it: a handler that failed to parse contributes zero operations.
-   * `warning` — something may be missing and the scan cannot decide, e.g. a base
-   * class it is not allowed to resolve. Statable in `frond.config.ts`.
+   * `blocking` — the app now serves less than its source declares, and no caller can know it: a
+   * handler that failed to parse contributes zero operations.
    */
   severity: 'blocking' | 'warning';
   /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */

package/src/scan/scanner.ts

@@ -31,13 +31,7 @@ import {
 
 // FS
 
-/**
- * What this scan run could not do. Reset by {@link scanProject}, which owns a run.
- *
- * Module-scoped like the loader and the cache root above: the scanner already has a
- * notion of "the current run". Three sites record — measured — so a per-run object
- * would carry twenty methods to spare one line of reset.
- */
+/** What this scan run could not do. */
 let diagnostics: ScanDiagnostic[] = [];
 
 function record(d: ScanDiagnostic): void {
@@ -45,10 +39,8 @@ function record(d: ScanDiagnostic): void {
 }
 
 /**
- * An absent convention directory is the ordinary case — a frond without
- * `presenters/` is not a defect. Anything else (permissions, an I/O error, a path
- * that is not a directory) means the scan did not look, and answering `[]` says
- * it did. One `catch` used to conflate the two.
+ * An absent convention directory is the ordinary case — a frond without `presenters/` is not a
+ * defect.
  */
 async function readEntries(path: string): Promise<Dirent[]> {
   try {
@@ -115,13 +107,7 @@ function findWorkspaceRoot(from: string): string {
   return resolvePath(from); // fallback: use project root itself
 }
 
-/**
- * Strip the 'Handler' suffix → the name the handler answers to. 'PostHandler' → 'post'.
- *
- * Nothing here checks that an entity carries the result, and nothing should: a handler
- * about no stored row is ordinary. The old name of this function — `toEntityName` — is
- * what let "one façade per entity" be repeated until it read as a rule.
- */
+/** Strip the 'Handler' suffix → the name the handler answers to. */
 function toAddress(className: string): string {
   const base = className.endsWith('Handler') ? className.slice(0, -7) : className;
   return lowerFirst(base);
@@ -130,18 +116,8 @@ function toAddress(className: string): string {
 // Scan
 
 /**
- * The container key a constructor parameter asks for — derived from its TYPE, not from
- * how the type was spelled.
- *
- * `deps` used to be `p.type.name`, so the key WAS the alias's name: `type ListStorage =
- * Storage<List>` resolved only because someone had spelled it exactly like the
- * registration key (`ListStorage`), while `type ListRepo = Storage<List>` — the same type —
- * typechecked and died at boot on `'ListRepo' is not registered`. And `Storage<List>`
- * written out in full asked for `'Storage'`, which nothing registers.
- *
- * `Storage<X>` names X's storage, so that is the key. The generic argument was already
- * parsed (`TypeRef.generics`) and thrown away. Anything else keeps its own name: a
- * plain service IS designated by its class name.
+ * The container key a constructor parameter asks for — derived from its TYPE, not from how the
+ * type was spelled.
  */
 function depKeyOf(type: TypeRef): string {
   // `Facade<PostHandler>` — the second port, read exactly like the first. The type names
@@ -166,32 +142,25 @@ function depKeyOf(type: TypeRef): string {
   // `RepositoryOf<Post>` — what an author writes when no repository file exists. The dual
   // of the line below: one names the port, the other the holder, and both resolve to a key
   // rather than to a class the author would have to invent.
-  const held = type.name === 'RepositoryOf' ? type.generics?.[0]?.name : undefined;
-  if (held) return repositoryKeyOf(held);
+  const subject = type.name === 'RepositoryOf' ? type.generics?.[0]?.name : undefined;
+  if (subject) return repositoryKeyOf(subject);
 
-  const target = type.name === 'Storage' ? type.generics?.[0]?.name : undefined;
+  // The GENERIC names the subject, so a prefix does not change the key — `MeiliStorage<Card>`
+  // is `Card`'s storage. A class named `FileStorage` is untouched: it carries no generic.
+  const target = type.name.endsWith('Storage') && type.generics?.length === 1
+    ? type.generics[0]?.name
+    : undefined;
   if (!target) return type.name;
 
   return storageKeyOf(target);
 }
 
-/**
- * `'[Account, Ledger]'` → `['Account', 'Ledger']`.
- *
- * The tuple was chosen over the variadic form the parser reads more cleanly, because the
- * variadic one costs arities-with-defaults and a `never` filter on the TypeScript side
- * while the tuple maps to `[Storage<Account>, Storage<Ledger>]` in one line. The
- * parser does not get to decide alone; this split is what that choice costs.
- */
+/** `'[Account, Ledger]'` → `['Account', 'Ledger']`. */
 function tupleMembers(raw: string): string[] {
   return raw.replace(/^\[|\]$/g, '').split(',').map((member) => member.trim()).filter(Boolean);
 }
 
-/**
- * These readings are semantic: an unchanged file can mean something different after an
- * imported alias changes. The parser's TypeScript Program is the cache for one scan; a
- * cache keyed only by this file's bytes would be unsound.
- */
+/** These readings are semantic. */
 const ctorParamsOf = (filePath: string) =>
   parseConstructorParams(filePath);
 
@@ -272,12 +241,7 @@ function resolveSchema(type: TypeRef, moduleExports: Record<string, unknown>): S
   return undefined;
 }
 
-/**
- * Parse ALL method signatures for unified binding.
- *
- * Resolves schemas for all params (not just the first) and stores
- * full signatures for the binding algorithm.
- */
+/** Parse ALL method signatures for unified binding. */
 async function inferOperations(
   filePath: string,
   handlerName: string,
@@ -308,15 +272,8 @@ async function inferOperations(
   }
 
   /**
-   * A base class the parse could not open — an installed package, typically, whose
-   * source is not in the workspace. Its operations are missing from this façade, and
-   * the scan cannot tell whether there were any.
-   *
-   * A warning, not a refusal: an installed base class with no operation is perfectly
-   * ordinary, and the boot has no way to decide between the two. So it names the
-   * clause and stops there. Stating the contract in `frond.config.ts` is the answer
-   * — the third producer, which creates an op neither other producer found — and it
-   * silences this by making the op exist.
+   * A base class the parse could not open — an installed package, typically, whose source is not
+   * in the workspace.
    */
   for (const base of parsed.unresolvedHeritage) {
     record({
@@ -342,10 +299,10 @@ async function inferOperations(
     // caller supplies through the body are candidates: a schema-typed collector, fact or
     // context parameter is not input merely because it names an entity. The old loop
     // ignored provenance and assigned the first schema it met, so swapping two parameters
-    // silently changed the contract the façade used to judge the request body.
+    // silently changed the contract the façade used to validate the request body.
     const binding = computeBindingPlan(method.params, collectorTypeNames);
     const candidates = method.params.flatMap((param, index) => {
-      if (binding[index]?.source.kind !== 'body') return [];
+      if (binding[index]?.source.kind !== 'input') return [];
       const schema = resolveSchema(param.type, moduleExports);
       return schema ? [{ param, schema }] : [];
     });
@@ -522,13 +479,7 @@ async function scanFrond(frondPath: string, name: string, source: FrondDescripto
     entities: entitiesDir, handlers: handlersDir,
     presenters: presentersDir, collectors: collectorsDir, seeds: seedsDir,
   } = conventions.dirs;
-  /**
-   * A convention directory, read by whoever knows the shape it holds.
-   *
-   * The same three lines were written six times — list, read in parallel, drop what the
-   * reader refused — which is what made `handlers/` quietly special: it grew a second
-   * pass for its surfaces and nothing else could.
-   */
+  /** A convention directory, read by whoever knows the shape it holds. */
   const collect = async <T extends object>(
     dir: string,
     read: (filePath: string) => Promise<T | null>,
@@ -615,15 +566,7 @@ async function scanFrond(frondPath: string, name: string, source: FrondDescripto
   };
 }
 
-/**
- * The frond's name — the directory, unless its `package.json` renames it. One rule for a
- * frond under `fronds/` and for the root frond alike, so the root needs no second spelling.
- *
- * Carrying the convention is what makes a frond; the key never marked anything and
- * nothing read it. It earns its keep as the one thing the directory cannot say: that
- * `fronds/blog-v2/` serves the frond still called `blog` — so a rename on disk does not
- * rename the entity keys, the `@fronds/*` import or a `remotes:` entry.
- */
+/** The frond's name — the directory, unless its `package.json` renames it. */
 async function frondNameOf(frondPath: string, dirName: string): Promise<string> {
   try {
     const pkg = JSON.parse(await readFile(join(frondPath, 'package.json'), 'utf8')) as {
@@ -637,15 +580,8 @@ async function frondNameOf(frondPath: string, dirName: string): Promise<string>
 }
 
 /**
- * A frond is a directory carrying the convention, and the project root is one such
- * directory — so a single-domain app writes `entities/` next to `app/` and never names
- * anything. `fronds/` is not the definition, it is where the OTHERS live: the root frond
- * stays put when a second domain appears, which is what makes flattening free instead of
- * a deferred move.
- *
- * `entities/` is the test, not "any convention directory". `services/` and `repositories/`
- * are ordinary top-level names in projects that never heard of Fougere, and a domain
- * without a single entity is not a domain.
+ * A frond is a directory carrying the convention, and the project root is one such directory — so
+ * a single-domain app writes `entities/` next to `app/` and never names anything.
  */
 async function rootFrondOf(root: string, workspaceRoot: string, conventions: Conventions): Promise<FrondDescriptor | null> {
   if ((await files(join(root, conventions.dirs.entities))).length === 0) return null;
@@ -653,21 +589,7 @@ async function rootFrondOf(root: string, workspaceRoot: string, conventions: Con
   return scanFrond(root, name, { path: root, package: frondPackage(name, conventions) }, conventions, workspaceRoot);
 }
 
-/**
- * `@fronds/<name>` → the directory it names, for every frond of a project.
- *
- * The framework states this convention — `FrondSource.package` has always spelled it, and
- * `fougere sync` writes it into a consumer's tsconfig — and until now its own reader could
- * not resolve it. The Nuxt module registered a Vite alias, so a `.vue` page could import
- * `@fronds/blog/entities/Post`, while the SCAN loaded sources through a bare jiti: a frond
- * naming its neighbour got `Cannot find module '@fronds/user/entities/User.js'`. So the one
- * form that survives a split was the one form that did not run.
- *
- * Hand it to the module loader — `createJiti(url, { alias: await frondAliases(root) })` —
- * and the named form resolves everywhere the framework reads. A directory listing and a
- * `package.json` read, no parsing: it is deliberately callable BEFORE the loader exists,
- * which is what makes the chicken-and-egg go away.
- */
+/** `@fronds/<name>` → the directory it names, for every frond of a project. */
 export async function frondAliases(root: string, conventions: Conventions = DEFAULT_CONVENTIONS): Promise<Record<string, string>> {
   const frondsDir = join(root, conventions.fronds);
   const aliases: Record<string, string> = {};
@@ -681,17 +603,7 @@ export async function frondAliases(root: string, conventions: Conventions = DEFA
     aliases[frondPackage(await frondNameOf(path, dir), conventions)] = resolvePath(path);
   }
 
-  /**
-   * A SYNCED frond answers to the same name.
-   *
-   * `fougere sync` writes `.fougere/remotes/<name>/` and registers it in `remotes.json`,
-   * which the Nuxt module already reads to alias `@fronds/<name>`. Doing it here too is
-   * what makes the convention mean ONE thing: a consumer writes `@fronds/blog/entities/Post`
-   * and never learns whether that frond is on this disk or was fetched from a card.
-   *
-   * A local frond wins a name collision — its source is the truth, a synced copy is a
-   * mirror of somebody else's.
-   */
+  /** A SYNCED frond answers to the same name. */
   try {
     const registry = JSON.parse(
       await readFile(join(root, '.fougere', 'remotes.json'), 'utf8'),
@@ -757,18 +669,7 @@ export async function scanProject(
   return { fronds, diagnostics };
 }
 
-/**
- * What changes when a frond's domain changes — the paths a dev loop watches.
- *
- * It lives beside the scan rather than beside the conventions it reads, because it turns
- * names into DISK paths: `join` is `node:path`, and `conventions.ts` is reached from
- * `index` through `frond()`, which an edge bundle imports. Measured — esbuild refused the
- * Worker with `Could not resolve "node:path"`.
- *
- * The root frond IS the scan root, so watching its path would match every write in the
- * project: `.nuxt/`, `node_modules/`, the build output. Its convention directories are
- * the frond, and they are what a scan re-reads.
- */
+/** What changes when a frond's domain changes — the paths a dev loop watches. */
 export function watchPathsOf(
   frond: { source: { path: string } },
   scanRoot: string,