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

package/src/boot/together.ts

@@ -10,9 +10,9 @@
 import { ambient } from '#ambient';
 import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { Container } from '@fougere/container';
-import { membersOfTogetherKey, ormKeyOf, type EntityOrm, type OrmFactory } from '../orm.js';
+import { membersOfTogetherKey, storageKeyOf, entityOfStorageKey, type Storage, type StorageFactory } from '../storage.js';
 import type { Logger } from '../builtins/logger.js';
-import type { ProviderEntry } from '../scan/frond.js';
+import type { ProviderEntry } from '../descriptor/frond.js';
 import { StorageGuard } from '../dispatch/StorageGuard.js';
 import { recording, unwind, type Undo } from './frame.js';
 
@@ -23,9 +23,9 @@ export interface FrameWorld {
   /** Which frond holds an entity — the question `remotes:` turns into a refusal. */
   frondOf: Map<string, string>;
   hostedHere: (frond: string) => boolean;
-  ormFactory?: OrmFactory;
+  storageFactory?: StorageFactory;
   sourceOf?: (entityName: string) => string;
-  transacted?: <R>(source: string, fn: (ormFactory: OrmFactory) => Promise<R>) => Promise<R>;
+  transacted?: <R>(source: string, fn: (storageFactory: StorageFactory) => Promise<R>) => Promise<R>;
   log: Logger;
 }
 
@@ -74,7 +74,7 @@ function resolve(names: { entities: string[]; providers: string[] }, declared: r
 /**
  * A member that cannot write here at all — its frond is hosted elsewhere.
  *
- * Refused rather than compensated: a compensated frame still writes through a local ORM,
+ * Refused rather than compensated: a compensated frame still writes through a local storage,
  * and a remote frond registers none. There is nothing to record and nothing to undo.
  */
 function refuseRemote(members: Members, world: FrameWorld, key: string): void {
@@ -96,13 +96,12 @@ function refuseRemote(members: Members, world: FrameWorld, key: string): void {
  * The frame does not widen itself to cover it: doing so would pull an entity from another
  * source into the group without anyone writing it down. Named instead, with the one-word fix.
  */
-function refuseUncoveredWrites(members: Members, key: string): void {
+function refuseUncoveredWrites(members: Members, key: string, world: FrameWorld): void {
   const covered = new Set(members.entities.map((member) => member.name));
   for (const provider of members.providers) {
     for (const dep of provider.deps) {
-      if (!dep.endsWith('Orm')) continue;
-      const entity = lowerFirst(dep.slice(0, -'Orm'.length));
-      if (covered.has(entity)) continue;
+      const entity = entityOfStorageKey(dep, (name) => world.entityByName.has(name));
+      if (!entity || covered.has(entity)) continue;
       throw new Error(
         `Together<[…]> (${key}): ${provider.ctor.name} writes ${entity}, which is not in the ` +
         `frame's entity list — its writes would escape the unwind. Add it: ` +
@@ -115,30 +114,30 @@ function refuseUncoveredWrites(members: Members, key: string): void {
 /**
  * Open the block: build every member over `factory`, in a scope of their own.
  *
- * The scope is what makes a provider member work without a locator — its ORM keys are
+ * The scope is what makes a provider member work without a locator — its storage keys are
  * registered here, so the container hands it the framed ones through the ordinary
  * constructor. It is disposed when the block ends, whichever way it ended.
  */
 async function inScope<R>(
   parent: Container,
   members: Members,
-  factory: OrmFactory,
-  wrap: (orm: EntityOrm, name: string, schema: SchemaView) => EntityOrm,
+  factory: StorageFactory,
+  wrap: (storage: Storage, name: string, schema: SchemaView) => Storage,
   fn: (entities: unknown[], providers: unknown[]) => Promise<R>,
 ): Promise<R> {
   const scope = parent.createScope();
   try {
-    const orms = members.entities.map((member) => {
-      const orm = wrap(factory(member.schema, member.name), member.name, member.schema);
-      scope.registerValue(ormKeyOf(member.name), orm);
-      return orm;
+    const storages = members.entities.map((member) => {
+      const storage = wrap(factory(member.schema, member.name), member.name, member.schema);
+      scope.registerValue(storageKeyOf(member.name), storage);
+      return storage;
     });
-    // Providers after every ORM is in place: one may depend on another member's.
+    // Providers after every storage is in place: one may depend on another member's.
     const built = members.providers.map((provider) => {
       scope.register(provider.ctor.name, provider.ctor, { deps: provider.deps });
       return scope.resolve(provider.ctor.name);
     });
-    return await fn(orms, built);
+    return await fn(storages, built);
   } finally {
     await scope.dispose();
   }
@@ -162,17 +161,17 @@ export function registerFrames(
     const names = membersOfTogetherKey(key);
     if (!names) continue;
     registered += 1;
-    if (!world.ormFactory) {
+    if (!world.storageFactory) {
       throw new Error(`Together<[${names.entities.join(', ')}]> needs storage, and this boot declares none.`);
     }
 
     const members = resolve(names, providers, world);
     refuseRemote(members, world, key);
-    refuseUncoveredWrites(members, key);
+    refuseUncoveredWrites(members, key, world);
 
     const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
-    const judge = (orm: EntityOrm, name: string, schema: SchemaView) =>
-      new StorageGuard(schema.getFields(), name).guard(orm);
+    const judge = (storage: Storage, name: string, schema: SchemaView) =>
+      new StorageGuard(schema.getFields(), name).guard(storage);
 
     // One engine and a way into it: the engine gives the unwind AND the isolation.
     if (world.transacted && sources.size === 1) {
@@ -196,10 +195,10 @@ export function registerFrames(
     scope.registerValue(key, {
       run: <R>(fn: (entities: never, providers: never) => Promise<R>): Promise<R> => ambient.enterFrame(key, async () => {
         const journal: Undo[] = [];
-        const record = (orm: EntityOrm, name: string, schema: SchemaView) =>
-          judge(recording(orm, name, schema.getFields(), journal), name, schema);
+        const record = (storage: Storage, name: string, schema: SchemaView) =>
+          judge(recording(storage, name, schema.getFields(), journal), name, schema);
         try {
-          return await inScope(scope, members, world.ormFactory!, record, fn as never);
+          return await inScope(scope, members, world.storageFactory!, record, fn as never);
         } catch (cause) {
           return unwind(journal, cause, world.log);
         }

package/src/boot/types.ts

@@ -6,10 +6,11 @@
  * landed in it, seventeen notions deep.
  */
 import type { Container } from '@fougere/container';
-import type { Fronds } from '../scan/Fronds.js';
-import type { FrondDescriptor, ScanResult } from '../scan/frond.js';
+import type { Fronds } from '../descriptor/Fronds.js';
+import type { FrondDescriptor } from '../descriptor/frond.js';
+import type { ScanResult } from '../scan/result.js';
 import type { SchemaView } from '@fougere/schema';
-import type { OrmFactory } from '../orm.js';
+import type { StorageFactory } from '../storage.js';
 import type { AppMiddleware } from '../wire/middleware.js';
 import type { RpcAnswer, Transport } from '../wire/call.js';
 import type { Extension } from './AppLifecycle.js';
@@ -22,23 +23,23 @@ import type { DispatchPort } from '../dispatch/DispatchPort.js';
 export interface CreateAppOptions {
   /** Factory function to create the container. Required. */
   createContainer: () => Container;
-  /** Factory to auto-generate EntityOrm for each scanned entity. */
-  ormFactory?: OrmFactory;
+  /** Factory to auto-generate Storage for each scanned entity. */
+  storageFactory?: StorageFactory;
   /**
    * Which source an entity's rows live in, and how to open a transaction on one — the two
    * questions that decide whether `Together<[…]>` gets the engine's own unwind or replays
    * inverses itself.
    *
-   * Optional together, because a host may hand in a bare `ormFactory` and know neither. A
+   * Optional together, because a host may hand in a bare `storageFactory` and know neither. A
    * frame then compensates: not knowing where the rows are and promising atomicity over
    * them are two different things, and only one of them is honest.
    */
   sourceOf?: (entityName: string) => string;
-  transacted?: <R>(source: string, fn: (ormFactory: OrmFactory) => Promise<R>) => Promise<R>;
+  transacted?: <R>(source: string, fn: (storageFactory: StorageFactory) => Promise<R>) => Promise<R>;
   /**
    * Builds the cross-source reader a frond gets when it declares `reads:`.
    *
-   * A factory rather than a value, for the same reason `ormFactory` is one: core must
+   * A factory rather than a value, for the same reason `storageFactory` is one: core must
    * not name a storage package, and this one costs 71 MB of downloaded extensions and a
    * native module — nothing a first run that only wanted sqlite should carry. The host
    * decides what backs it; `@fougere/adapter-duckdb` is one answer, not the contract.
@@ -219,14 +220,14 @@ export interface App extends DispatchPort {
    * the dual of {@link facadeFor}. `undefined` when no loaded frond hosts the entity,
    * or when the app booted with no storage at all.
    *
-   * `unknown` because the port belongs to whoever wired it: narrowing it to `EntityOrm`
+   * `unknown` because the port belongs to whoever wired it: narrowing it to `Storage`
    * is the caller saying which implementation they are standing on.
    */
-  ormFor(entity: string): unknown | undefined;
+  storageFor(entity: string): unknown | undefined;
   /**
    * The presenter of an entity, resolved through its owning frond's scope.
    *
-   * Same shape as {@link ormFor}, and it exists so an adapter never spells the container
+   * Same shape as {@link storageFor}, and it exists so an adapter never spells the container
    * key itself: `schema-graphql` wrote out `${Name}Presenter` by hand, and a key respelled
    * in a second place finds nothing and reports nothing the day the convention moves.
    */

package/src/contract/CallLog.ts

@@ -1,4 +1,4 @@
-import type { DispatchEvent } from '../dispatch/DispatchEvent.js';
+import type { RouteKind } from './RouteAddress.js';
 
 /**
  * What crosses the door: the address, the route it took, and the verdict.
@@ -18,7 +18,7 @@ export interface CallRecord {
   operation: string;
   surface?: string;
   /** Known at `resolved`, so absent on a call that never found a route. */
-  route?: NonNullable<DispatchEvent['routeKind']>;
+  route?: RouteKind;
   /**
    * The traceparent the invocation carried, when one did.
    *

package/src/contract/RouteAddress.ts

@@ -1,3 +1,6 @@
+/** Which kind of destination served a call — it travels in a `CallRecord`. */
+export type RouteKind = 'local' | 'remote' | 'system';
+
 export interface RouteAddressInput {
   entity: string;
   operation: string;

package/src/{scan/declare.ts → declare.ts}

@@ -19,9 +19,9 @@ import { lowerFirst, type SchemaView } from '@fougere/schema';
 import type {
   CollectorEntry, EntityEntry, FrondDescriptor, HandlerEntry,
   PresenterEntry, ProviderEntry, SeedEntry,
-} from './frond.js';
-import { DEFAULT_CONVENTIONS } from './conventions.js';
-import { getPresenterFields } from '../prefab/presenter.js';
+} from './descriptor/frond.js';
+import { DEFAULT_CONVENTIONS } from './scan/conventions.js';
+import { getPresenterFields } from './prefab/presenter.js';
 
 /** A class, as a declaration hands it over: the constructor itself. */
 type Ctor = new (...args: never[]) => unknown;
@@ -31,7 +31,7 @@ type Ctor = new (...args: never[]) => unknown;
  *
  * `deps` is the one thing no runtime can recover: TypeScript erases the parameter types,
  * and `registerFrames` reads them to know which frames to build — asking for one IS
- * declaring it. A handler that takes only its own entity's ORM needs nothing here.
+ * declaring it. A handler that takes only its own entity's storage needs nothing here.
  */
 export interface DeclaredSubject {
   ctor: Ctor;
@@ -98,7 +98,7 @@ export interface FrondDeclaration {
  *
  * ```ts
  * createApp({
- *   scan: { fronds: Fronds.scanned([frond('blog', { entities: [Post], handlers: [PostHandler] })]), diagnostics: [] },
+ *   scan: { fronds: Fronds.hosting([frond('blog', { entities: [Post], handlers: [PostHandler] })]), diagnostics: [] },
  * })
  * ```
  */

package/src/{scan → descriptor}/Fronds.ts

@@ -2,8 +2,7 @@ import type { SchemaView } from '@fougere/schema';
 import type { EntityEntry, FrondDescriptor } from './frond.js';
 
 /**
- * What this app hosts — the scan's answer, with the questions everyone was asking it
- * by hand.
+ * What this app hosts, with the questions everyone was asking it by hand.
  *
  * The list was a bare array, so every reader re-walked it: "which frond owns this
  * entity" was spelled four times, "every entity by name" three times as three literal
@@ -20,8 +19,8 @@ export class Fronds extends Array<FrondDescriptor> {
     return Array;
   }
 
-  /** What one scan run found. The only gate in — `Array.of` is taken, and named. */
-  static scanned(fronds: readonly FrondDescriptor[]): Fronds {
+  /** The fronds an app hosts, scanned or stated. The only gate in — `Array.of` is taken. */
+  static hosting(fronds: readonly FrondDescriptor[]): Fronds {
     const held = new Fronds();
     held.push(...fronds);
     return held;
@@ -32,7 +31,7 @@ export class Fronds extends Array<FrondDescriptor> {
     return this.find((frond) => frond.entities.some((e) => e.name === entity));
   }
 
-  /** The entity of that name, wherever it was scanned. */
+  /** The entity of that name, wherever it was declared. */
   entity(name: string): EntityEntry | undefined {
     for (const frond of this) {
       const found = frond.entities.find((e) => e.name === name);
@@ -42,7 +41,7 @@ export class Fronds extends Array<FrondDescriptor> {
   }
 
   /**
-   * Every scanned entity class, by name — across all fronds and never per-frond.
+   * Every entity class, by name — across all fronds and never per-frond.
    *
    * A fact is announced in one frond and heard in another, so the subscriber's own
    * frond does not hold the shape it must judge; a `reads:` clause names entities
@@ -52,7 +51,7 @@ export class Fronds extends Array<FrondDescriptor> {
     return new Map(this.flatMap((frond) => frond.entities.map((e) => [e.name, e.entityClass] as const)));
   }
 
-  /** Every scanned entity, sorted. What was FOUND, not what answers. */
+  /** Every declared entity, sorted. What is DECLARED, not what answers. */
   entityNames(): string[] {
     return this.flatMap((frond) => frond.entities.map((e) => e.name)).sort();
   }

package/src/{scan → descriptor}/frond.ts

@@ -1,12 +1,12 @@
 /**
- * A frond as the SCAN found it — one interface per convention directory, plus what the
- * run could not read.
+ * What a frond is made of — one interface per convention directory.
  *
- * The declared side is `frond-config.ts`; this is the described one. They meet at
- * `FrondDescriptor.operationsOverrides`, where a declaration reaches the façade.
+ * Produced two ways and indistinguishable once here: the scan DERIVES it from a
+ * directory tree, `frond()` STATES it outright. `frond-config.ts` is the declared
+ * side; they meet at `FrondDescriptor.operationsOverrides`.
  */
 import type { SchemaView } from '@fougere/schema';
-import type { ParsedParam, OperationContract, OperationsMap } from '../wire/operation.js';
+import type { Param, OperationContract, OperationsMap } from '../wire/operation.js';
 import type { PresenterViews } from '../prefab/presenter.js';
 import type { Fronds } from './Fronds.js';
 
@@ -74,7 +74,7 @@ export interface HandlerEntry {
   filePath: string;
   /** Whether this handler is part of the frond's public contract. */
   exposed?: boolean;
-  /** Output schema override — when Crud(Entity, Output), restricts ORM output. */
+  /** Output schema override — when Crud(Entity, Output), restricts storage output. */
   outputOverride?: SchemaView;
   /** Surface name — subdirectory in handlers/ (e.g. 'admin', 'public'). */
   surface?: string;
@@ -104,7 +104,7 @@ export interface PresenterFieldMeta {
    * A computed field that declares `user?: User` is then fed by the collector
    * that resolves one. A presenter is not a second mechanism.
    */
-  params?: ParsedParam[];
+  params?: Param[];
 }
 
 /** A discovered presenter (computed fields for an entity's output). */
@@ -192,44 +192,3 @@ export interface FrondDescriptor {
     method?: string;
   }>;
 }
-
-/** 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.
- */
-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`.
-   */
-  severity: 'blocking' | 'warning';
-  /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */
-  code: string;
-  /** Absolute path of what could not be read. */
-  filePath: string;
-  /** The frond it belongs to, when the scan got far enough to know. */
-  frond?: string;
-  /** The declaration the diagnostic is about — e.g. `PostHandler.publish`. */
-  subject?: string;
-  /** What could not be done, and what it costs. One sentence, for a human. */
-  message: string;
-  /** The underlying failure, kept whole. */
-  cause?: unknown;
-}
-
-export interface ScanResult {
-  fronds: Fronds;
-  /** What the scan could not do. Empty is a claim, not a default — see {@link ScanDiagnostic}. */
-  diagnostics: ScanDiagnostic[];
-}

package/src/dispatch/ArgumentResolver.ts

@@ -1,9 +1,9 @@
-import {
-  resolveArgs,
-  type BindingPlan,
-  type CollectorResolver,
-} from '../boot/binding.js';
 import type { InvocationContext } from '../contract/Invocation.js';
+import type { BindingPlan } from '../wire/binding.js';
+
+export interface CollectorResolver {
+  collect(ctx: InvocationContext): Promise<unknown>;
+}
 
 export type CollectorLookup = (typeName: string) => CollectorResolver | undefined;
 
@@ -11,7 +11,53 @@ export type CollectorLookup = (typeName: string) => CollectorResolver | undefine
 export class ArgumentResolver {
   constructor(private readonly collectors?: CollectorLookup) {}
 
-  resolve(plan: BindingPlan, invocation: InvocationContext): Promise<unknown[]> {
-    return resolveArgs(plan, invocation, this.collectors);
+  async resolve(plan: BindingPlan, ctx: InvocationContext): Promise<unknown[]> {
+    const args: unknown[] = [];
+
+    for (const binding of plan) {
+      switch (binding.source.kind) {
+        case 'collector': {
+          const collector = this.collectors?.(binding.source.typeName);
+          args.push(collector ? await collector.collect(ctx) : undefined);
+          break;
+        }
+        case 'context': {
+          args.push(ctx);
+          break;
+        }
+        case 'param': {
+          // `null` is a value, not a miss. Nullish coalescing used to make an explicit
+          // nullable path/GraphQL argument fall through to query (or become undefined),
+          // collapsing `T | null` into `T | undefined`. Only undefined means absent.
+          const fromParams = ctx.params[binding.source.name];
+          let val: unknown = fromParams === undefined
+            ? ctx.query[binding.source.name]
+            : fromParams;
+          if (val != null && binding.source.coerce === 'number') val = Number(val);
+          if (val != null && binding.source.coerce === 'boolean') val = val === 'true' || val === '1' || val === true;
+          args.push(val);
+          break;
+        }
+        case 'fact': {
+          // A fact IS the payload — the whole of what happened, never a piece of it.
+          // Identical to `body` today, and deliberately not sharing its branch: the two
+          // agree by coincidence, not by rule, and the day `body` learns to look up a
+          // value by parameter name a subscriber would receive ONE FIELD of the fact it
+          // subscribed to. Splitting it costs nothing and removes that trap.
+          args.push(ctx.body);
+          break;
+        }
+        case 'body': {
+          args.push(ctx.body);
+          break;
+        }
+        case 'query': {
+          args.push(ctx.query);
+          break;
+        }
+      }
+    }
+
+    return args;
   }
 }

package/src/dispatch/DispatchEvent.ts

@@ -1,5 +1,5 @@
 import type { Call } from '../contract/Call.js';
-import type { RouteKind } from './Route.js';
+import type { RouteKind } from '../contract/RouteAddress.js';
 
 export type DispatchStage = 'received' | 'resolved' | 'completed' | 'failed' | 'settled';
 

package/src/dispatch/PresenterArgumentResolver.ts

@@ -1,6 +1,6 @@
-import { computeBindingPlan } from '../boot/binding.js';
+import { computeBindingPlan } from '../wire/binding.js';
 import type { InvocationContext } from '../contract/Invocation.js';
-import type { PresenterEntry } from '../scan/frond.js';
+import type { PresenterEntry } from '../descriptor/frond.js';
 import type { ArgumentResolver } from './ArgumentResolver.js';
 import type { PresenterArgs } from './PresenterExecutor.js';
 

package/src/dispatch/Route.ts

@@ -1,7 +1,5 @@
 import type { Call } from '../contract/Call.js';
-import type { RouteAddress } from '../contract/RouteAddress.js';
-
-export type RouteKind = 'local' | 'remote' | 'system';
+import type { RouteAddress, RouteKind } from '../contract/RouteAddress.js';
 
 /** Executable destination known by the dispatcher. */
 export interface Route {

package/src/dispatch/StorageGuard.ts

@@ -1,5 +1,5 @@
 import { ValueJudge, type Fields } from '@fougere/schema';
-import { assertListOptions } from '../orm.js';
+import { assertListOptions } from '../storage.js';
 import { ErrorCode, FougereError } from '../wire/errors.js';
 
 interface Writer {
@@ -8,7 +8,7 @@ interface Writer {
 }
 
 /**
- * Judges storage writes and list options without narrowing the ORM interface.
+ * Judges storage writes and list options without narrowing the storage interface.
  *
  * Storage is a way out like the client surface, so what goes to it is judged too — the
  * same rule `OutputProjector` applies on the other exit.
@@ -19,12 +19,12 @@ export class StorageGuard {
     private readonly entity: string,
   ) {}
 
-  guard<T extends object>(orm: T): T {
-    const writer = orm as unknown as Writer;
-    if (typeof writer.create !== 'function' || typeof writer.update !== 'function') return orm;
+  guard<T extends object>(storage: T): T {
+    const writer = storage as unknown as Writer;
+    if (typeof writer.create !== 'function' || typeof writer.update !== 'function') return storage;
 
     const validation = this;
-    const guarded = Object.create(orm) as T & Writer;
+    const guarded = Object.create(storage) as T & Writer;
 
     guarded.create = async function (...args) {
       validation.judge(args[0], 'create');
@@ -36,7 +36,7 @@ export class StorageGuard {
       return writer.update.apply(this, args);
     };
 
-    const reader = orm as unknown as { list?: (...args: unknown[]) => unknown };
+    const reader = storage as unknown as { list?: (...args: unknown[]) => unknown };
     if (typeof reader.list === 'function') {
       (guarded as unknown as typeof reader).list = async function (...args: unknown[]) {
         assertListOptions(args[0] as object | undefined, validation.entity);

package/src/effective-operation.ts

@@ -7,21 +7,17 @@
  */
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 import { statementDrift } from './boot/statement-drift.js';
-import type { BindingPlan } from './boot/binding.js';
+import { computeBindingPlan, type BindingPlan } from './wire/binding.js';
 import { targetOf } from './prefab/prefab.js';
-import type {
-  CollectorEntry,
-  FrondDescriptor,
-  HandlerEntry,
-  ScanDiagnostic,
-} from './scan/frond.js';
+import type { CollectorEntry, FrondDescriptor, HandlerEntry } from './descriptor/frond.js';
+import type { ScanDiagnostic } from './scan/result.js';
 import { verify } from './verify.js';
 import {
   inferOperationKind,
-  resolveContracts,
   type OperationContract,
   type OperationKind,
-  type ParsedType,
+  type OperationsMap,
+  type TypeRef,
   knownVerbs,
 } from './wire/operation.js';
 
@@ -491,11 +487,11 @@ function validateProvenance(
   return valid;
 }
 
-function structural(type: ParsedType | undefined): boolean {
+function structural(type: TypeRef | undefined): boolean {
   return type !== undefined && type.raw.includes('{');
 }
 
-function schemaMatches(schema: SchemaView, type: ParsedType | undefined): boolean {
+function schemaMatches(schema: SchemaView, type: TypeRef | undefined): boolean {
   const names = new Set([schema.name, schema.derivation?.sourceName].filter(Boolean));
   if (type?.name && names.has(type.name)) return true;
   return type?.generics?.some((generic) => generic.name && names.has(generic.name)) ?? false;
@@ -599,3 +595,59 @@ function uniqueDiagnostics(diagnostics: readonly ScanDiagnostic[]): ScanDiagnost
     return true;
   });
 }
+
+/**
+ * The contract of every operation a handler serves — the three producers, merged once.
+ *
+ * This lived inline in `buildFacade`, which made the façade the only thing that could
+ * answer "what is this op's contract, really?". Anything else asking — a checker, a
+ * client generator, a descriptor — had to redo the merge, and a second opinion that
+ * drifts reports nothing wrong while looking at the wrong thing.
+ *
+ * The order is a claim about authority, not a convenience:
+ *
+ *   1. a prefab DECLARES what it built (`Crud(E).__ops`) — runtime, so it survives a
+ *      scan that resolved nothing;
+ *   2. the scan DERIVES from source — a method written in this very file is the
+ *      author's own word and beats everything; a method it merely READ on a base
+ *      class is a guess about someone else's code, and yields to that code's own
+ *      declaration;
+ *   3. `frond.config.ts` STATES — the most explicit statement, made by whoever
+ *      assembles the app, and the only answer for an op inherited from an installed
+ *      base class the workspace-only scan cannot see. Merged per key, so stating a
+ *      `binding` alone does not erase an `input` the scan found.
+ *
+ * Pure: no container, no instance, no disk. The binding plan is resolved here, so
+ * nothing downstream ever meets an AST.
+ */
+export function resolveContracts(
+  handler: Pick<HandlerEntry, 'ctor' | 'operations'>,
+  overrides: FrondDescriptor['operationsOverrides'],
+  collectorTypeNames: Set<string>,
+): OperationsMap {
+  const declared = (handler.ctor as { __ops?: Record<string, OperationContract> }).__ops ?? {};
+  const contracts: OperationsMap = new Map(Object.entries(declared));
+
+  for (const [opName, scanned] of handler.operations) {
+    if (scanned.signature?.inherited && opName in declared) continue;
+    contracts.set(opName, {
+      ...scanned,
+      binding: scanned.binding
+        ?? (scanned.signature ? computeBindingPlan(scanned.signature.params, collectorTypeNames) : undefined),
+    });
+  }
+
+  for (const [opName, override] of Object.entries(overrides ?? {})) {
+    const { input, output, binding, description } = override;
+    if (input === undefined && output === undefined && binding === undefined && description === undefined) continue;
+    contracts.set(opName, {
+      ...contracts.get(opName),
+      ...(input !== undefined && { input }),
+      ...(output !== undefined && { output }),
+      ...(binding !== undefined && { binding }),
+      ...(description !== undefined && { description }),
+    });
+  }
+
+  return contracts;
+}

package/src/emit.ts

@@ -22,7 +22,7 @@
 import { lowerFirst } from '@fougere/schema';
 
 /**
- * What an emitter injects. Resolved by type, like `EntityOrm<Post>` and `Facade<T>`.
+ * What an emitter injects. Resolved by type, like `Storage<Post>` and `Facade<T>`.
  *
  * The returned promise settles when the fact has been **dispatched**, never when it has
  * been handled: a subscriber's failure is its own. The `EventBus` this replaces did

package/src/frond-config.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 import type { EntityConstructor, SchemaView } from '@fougere/schema';
-import type { BindingPlan } from './boot/binding.js';
+import type { BindingPlan } from './wire/binding.js';
 
 // ── Types ────────────────────────────────────────
 
@@ -91,7 +91,7 @@ export interface FrondConfig {
    * door on purpose ("it would publish the auth tables to anyone who asks"), and a SQL
    * door at app scope would hand them over; this is what keeps it shut.
    *
-   * Declaring it is what makes `Sources` injectable here. A frond that declares none
+   * Declaring it is what makes `Reads` injectable here. A frond that declares none
    * asks for none, and nothing is attached on its behalf.
    */
   reads?: string[];

package/src/graph.ts

@@ -3,7 +3,7 @@ import { Role } from '@fougere/schema';
  * Entity dependency graph — analyzes ref() links between entities
  * to suggest domain boundaries for splitting fronds.
  */
-import type { FrondDescriptor } from './scan/frond.js';
+import type { FrondDescriptor } from './descriptor/frond.js';
 
 export interface EntityNode {
   name: string;