@fougere/core 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/boot/bootstrap.ts

@@ -1,18 +1,18 @@
 import type { Container } from '@fougere/container';
 import { lowerFirst, type SchemaView } from '@fougere/schema';
-import type { EntityEntry, HandlerEntry, PresenterEntry } from '../scan/frond.js';
+import type { EntityEntry, HandlerEntry, PresenterEntry } from '../descriptor/frond.js';
 import { hostedBy } from './hosted.js';
 import type { AuthRuntime } from './auth.js';
 import type { CreateAppOptions, App } from './types.js';
 import type { AppMiddleware } from '../wire/middleware.js';
-import { Logger } from '../builtins/logger.js';
-import { Config } from '../builtins/config.js';
+import { Logger } from '../builtin/logger.js';
+import { Config } from '../builtin/config.js';
 import { createRemoteRouter, createRemoteFacade } from './remote.js';
 import { registerFrames } from './together.js';
 import { Emissions } from './Emissions.js';
-import { HandlerFacade } from './HandlerFacade.js';
+import { HandlerFacade } from '../dispatch/HandlerFacade.js';
 import { targetOf } from '../prefab/prefab.js';
-import { ownersOf, refuseOrmInUserCode, refuseCrudOnOwned } from './ownership.js';
+import { ownersOf, refuseStorageInUserCode, refuseCrudOnOwned } from './ownership.js';
 import type { OperationContract, OperationsMap } from '../wire/operation.js';
 import {
   resolveEffectiveOperations,
@@ -22,50 +22,31 @@ import { StorageGuard } from '../dispatch/StorageGuard.js';
 import { portBindings } from './ports.js';
 import { InFlight } from '../dispatch/InFlight.js';
 // The keys, each read from where its concept is declared — never respelled here.
-import { facadeKeyOf, contractsKeyOf, identityCardOf, type RpcAnswer } from '../wire/call.js';
+import { facadeKeyOf, contractsKeyOf, type RpcAnswer } from '../wire/call.js';
+import { identityCardOf } from './card.js';
 import { AppLifecycle } from './AppLifecycle.js';
+import { inheritsCrud, subjectOf } from '../prefab/crud.js';
 import { repositoryKeyOf } from '../prefab/repository.js';
-import { ormKeyOf } from '../orm.js';
+import { storageKeyOf } from '../storage.js';
 import { presenterKeyOf } from '../prefab/presenter.js';
 import { collectorKeyOf } from '../prefab/collector.js';
-import { RouteAddress } from '../contract/RouteAddress.js';
+import { RouteAddress } from '../wire/RouteAddress.js';
 import { DispatchLifecycle } from '../dispatch/DispatchLifecycle.js';
 import { Dispatcher } from '../dispatch/Dispatcher.js';
 import { LocalRoutePolicy } from '../dispatch/LocalRoutePolicy.js';
 import { OperationRoute } from '../dispatch/OperationRoute.js';
-import { RemoteRouteResolver } from '../dispatch/RemoteRouteResolver.js';
+import { remoteRoutes } from '../dispatch/remoteRoutes.js';
 import { RouteRegistry } from '../dispatch/RouteRegistry.js';
-import { FacadeEntry } from '../entry/FacadeEntry.js';
+import { facadeOperations } from '../entry/facade.js';
 
 
-/**
- * The one wording for "nobody hosts this here", with both ways out. Said twice, and the
- * second copy (`schemaFor`) had lost the two remedies — the same dead end, strictly less
- * useful, for no reason.
- */
+/** The one wording for "nobody hosts this here", with both ways out. */
 const notLoaded = (entity: string) =>
   `Frond for '${entity}' is not loaded.\n` +
   `  - Add '${entity}' to --fronds flag\n` +
   `  - Or declare a remote: remotes: { ${entity}: 'http://...' }`;
 
-/**
- * Two fronds cannot claim one name — said at boot, because nothing else says it.
- *
- * A door lands on the ROOT container under `facadeKeyOf(address)`, and that key carries
- * no frond; a presenter lands there too. `registerValue` is a `Map.set`, so the second
- * frond loaded simply replaced the first and every call meant for one went to the other.
- * Silent in-process, and worse than silent under a split: `createRemoteRouter` guards its
- * index with `if (!byEntity.has(...))`, so THERE the first frond discovered wins. The same
- * application answered differently depending on how it was deployed.
- *
- * Refusing is the honest answer while a key cannot say which frond owns it. It is not the
- * last word: qualify the key and this boot can accept both. ORMs and repositories are not
- * checked because they are registered in the frond's own scope, where two fronds do not meet.
- *
- * A frond declared remote registers nothing locally, so it cannot collide here. Two REMOTE
- * fronds publishing one entity still shadow each other inside the router — a hole this
- * check does not reach.
- */
+/** Two fronds cannot claim one name — said at boot, because nothing else says it. */
 function assertOneOwnerPerKey(
   fronds: { name: string; handlers: HandlerEntry[]; presenters: PresenterEntry[] }[],
   remotes: Record<string, string> | undefined,
@@ -73,10 +54,10 @@ function assertOneOwnerPerKey(
   const owner = new Map<string, string>();
 
   const claim = (key: string, frond: string, what: string) => {
-    const held = owner.get(key);
-    if (held !== undefined && held !== frond) {
+    const first = owner.get(key);
+    if (first !== undefined && first !== frond) {
       throw new Error(
-        `Two fronds claim the key '${key}': '${held}' and '${frond}'.\n`
+        `Two fronds claim the key '${key}': '${first}' and '${frond}'.\n`
         + `  A ${what} is registered under a key that names no frond, so one would silently replace the other.\n`
         + `  - Rename one of the two classes, or\n`
         + `  - keep one of the two fronds out of this process (--fronds), or declare it in remotes:`,
@@ -112,6 +93,16 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
   // no builtin and a Worker can run what it builds.
   const scanStart = performance.now();
   const { fronds, diagnostics } = await hostedBy(options);
+  // An app that states nothing AND scans nothing is a mistake — unless something else it
+  // declares brings its own entities, which an auth provider does. Refused here and not in
+  // `hostedBy`, which is handed the frond sources and cannot see the rest of the app. The
+  // condition is the KEYS, not the count: a scan that found nothing is an ordinary answer.
+  if (!options.fronds && !options.scan && !options.auth) {
+    throw new Error(
+      'createApp needs `fronds:` (what this app states) or `scan:` (what a scanner found). '
+      + 'Neither was given, and nothing else declares entities of its own.',
+    );
+  }
   const operationModel = resolveEffectiveOperations(fronds, {
     diagnostics,
     remotes: options.remotes,
@@ -122,22 +113,11 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
   log.info(`read ${fronds.length} frond(s) in ${scanMs}ms`
     + (diagnostics.length ? ` — ${diagnostics.length} thing(s) the scan could not do` : ''));
 
-  /**
-   * Say what could not be read, at the one line everyone already watches.
-   *
-   * Not a refusal: an app whose `presenters/` is unreadable still serves its
-   * entities, and stopping the boot would trade a partial app for none. But it is
-   * an ERROR, not a debug line — the app now serves less than its source declares,
-   * and nothing downstream can tell that from a source that declares less.
-   */
+  /** Say what could not be read, at the one line everyone already watches. */
   for (const d of blocking) log.error(`[${d.code}] ${d.message}`, d.cause);
   for (const d of diagnostics) if (d.severity === 'warning') log.warn(`[${d.code}] ${d.message}`);
 
-  /**
-   * An ambiguous convention is not a partial scan. Every relevant declaration was read,
-   * but more than one executable contract can be built from it. Refuse before auth,
-   * storage, migrations or seeds make the boot observable.
-   */
+  /** An ambiguous convention is not a partial scan. */
   const invalidOperations = operationModel.resolutionDiagnostics
     .filter((diagnostic) => diagnostic.severity === 'blocking');
   if (invalidOperations.length > 0) {
@@ -152,11 +132,11 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
 
   // Auth runtime — built once from the lazy AuthConfig produced by a provider factory
   // (e.g. betterAuth({...})) in fougere.config.ts. The provider receives our db +
-  // ormFactory so all auth writes flow through EntityOrm.
+  // storageFactory so all auth writes flow through Storage.
   let authRuntime: AuthRuntime | undefined;
   if (options.auth) {
-    if (!options.ormFactory) {
-      throw new Error('createApp: `auth` is set but `ormFactory` is missing — auth providers need it to back their adapter.');
+    if (!options.storageFactory) {
+      throw new Error('createApp: `auth` is set but `storageFactory` is missing — auth providers need it to back their adapter.');
     }
     if (options.db === undefined) {
       throw new Error('createApp: `auth` is set but `db` is missing — pass the storage handle through CreateAppOptions.db.');
@@ -164,12 +144,12 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     log.info('initializing auth runtime');
     authRuntime = await options.auth.create({
       db: options.db,
-      ormFactory: options.ormFactory,
+      storageFactory: options.storageFactory,
     });
     log.info(`auth ready — mounted at ${authRuntime.basePath}`);
   }
 
-  // Remote routing — judged at boot: declaring remotes without a transport is a config error.
+  // Remote routing — validated at boot: declaring remotes without a transport is a config error.
   // A remote declaration wins over local presence: `remotes: { blog: url }` IS
   // the topology statement — the frond's code may sit in fronds/**, it runs elsewhere.
   const declaredRemotes = Object.entries(options.remotes ?? {});
@@ -214,7 +194,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
 
   assertOneOwnerPerKey(fronds, options.remotes);
 
-  // Every entity of every frond, by name — so a fact can be judged where it LANDS, and
+  // Every entity of every frond, by name — so a fact can be validated where it LANDS, and
   // so a `reads:` clause can name a neighbour's.
   const entityByName = fronds.schemas();
   // Which frond holds an entity — what turns "a member is remote" into a refusal that
@@ -254,14 +234,14 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     // `reads:` is what makes a cross-source reader exist here, and the list IS its
     // environment — a source holding none of these is never opened. Registered under
     // the type's own name, which is the key `depKeyOf` already derives for a plain
-    // parameter: `constructor(private sources: Sources)` and nothing else to say.
+    // parameter: `constructor(private reads: Reads)` and nothing else to say.
     // Declaring `reads:` with nothing to build the reader is a boot that ignores a
-    // clause: the handler asking for `Sources` then dies at its first call, on a
+    // clause: the handler asking for `Reads` then dies at its first call, on a
     // container message that names neither the clause nor what is missing.
     if (frond.reads?.length && !options.sourcesFactory) {
       frondLog.warn(
         `[reads] ${frond.reads.join(', ')} — declared in frond.config.ts, but this boot passes no `
-        + '`sourcesFactory`, so no reader is registered and a handler asking for `Sources` will fail '
+        + '`sourcesFactory`, so no reader is registered and a handler asking for `Reads` will fail '
         + 'at its first call. Pass one (`@fougere/adapter-duckdb`), or drop the clause.',
       );
     }
@@ -280,14 +260,14 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
           + 'so a query naming one would find no table. Check the spelling, or the entity file.',
         );
       }
-      scope.registerValue('Sources', await options.sourcesFactory(named, frond.name));
+      scope.registerValue('Reads', await options.sourcesFactory(named, frond.name));
       frondLog.debug(`cross-source reader over ${named.length} entit(ies)`);
     }
 
     // Who owns what, and the rule that makes owning mean something. Before anything is
     // registered, so a bad line is named by this refusal rather than by the container's.
     const owners = ownersOf(frond.providers);
-    refuseOrmInUserCode(frond, owners);
+    refuseStorageInUserCode(frond, owners, (entity) => entityByName.has(entity));
     refuseCrudOnOwned(frond, owners);
 
     for (const provider of frond.providers) {
@@ -306,28 +286,28 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       frondLog.debug(`${frond.providers.length} provider(s): ${frond.providers.map((p) => p.ctor.name).join(', ')}`);
     }
 
-    // Register EntityOrm for each entity — PascalCase type name (e.g. 'PostOrm')
-    // When a handler declares Crud(Entity, Output), scope the ORM via .output(Output)
-    if (options.ormFactory) {
+    // Register Storage for each entity — PascalCase type name (e.g. 'PostStorage')
+    // When a handler declares Crud(Entity, Output), scope the storage via .output(Output)
+    if (options.storageFactory) {
       for (const entity of frond.entities) {
-        const ormName = ormKeyOf(entity.name);
-        const baseOrm = options.ormFactory(entity.entityClass, entity.name);
+        const key = storageKeyOf(entity.name);
+        const baseStorage = options.storageFactory(entity.entityClass, entity.name);
 
         // Check if the default handler (no surface) declares an output override
         const defaultHandler = frond.handlers.find((h) => h.address === entity.name && !h.surface);
         const outputSchema = defaultHandler?.outputOverride ?? (defaultHandler?.ctor as any)?.__output;
         const scoped = outputSchema && outputSchema !== entity.entityClass
-          ? baseOrm.output(outputSchema)
-          : baseOrm;
+          ? baseStorage.output(outputSchema)
+          : baseStorage;
 
         // Storage is a way out like the client surface — see `StorageGuard`.
         const guarded = new StorageGuard(entity.entityClass.getFields(), entity.name).guard(scoped);
-        scope.registerValue(ormName, guarded);
+        scope.registerValue(key, guarded);
 
         // The default repository IS the guarded port — it already answers every gesture a
         // declared one forwards, so the two forms have the same shape and a handler reads
-        // `repo.list()` either way. The wrapper that used to sit here (`{ orm: guarded }`)
-        // existed to make `repo.orm` true in both, back when `.orm` was the way in.
+        // `repo.list()` either way. The wrapper that used to sit here (`{ storage: guarded }`)
+        // existed to make `repo.storage` true in both, back when `.storage` was the way in.
         //
         // Not registered for an OWNED entity: an aggregate's members are reached through it
         // and nowhere else, and the default would be a second door under a name a handler
@@ -342,7 +322,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
         }
       }
       if (frond.entities.length > 0) {
-        frondLog.debug(`${frond.entities.length} entity ORM(s): ${frond.entities.map((e) => e.name).join(', ')}`);
+        frondLog.debug(`${frond.entities.length} entity storage(s): ${frond.entities.map((e) => e.name).join(', ')}`);
       }
     }
 
@@ -357,8 +337,9 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
         entityByName,
         frondOf,
         hostedHere: (name) => !(options.remotes && name in options.remotes),
-        ormFactory: options.ormFactory,
+        storageFactory: options.storageFactory,
         sourceOf: options.sourceOf,
+        transacts: options.transacts,
         transacted: options.transacted,
         log: frondLog,
       },
@@ -395,25 +376,25 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       targetScope: Container,
       facadeKey: string,
     ) => {
-      const facade = new HandlerFacade(
-        {
-          handler,
-          handlers: frond.handlers,
-          entity,
-          scope: targetScope,
-          key: facadeKey,
-          operations: operationModel.forHandler(handler),
-        },
-        {
-          frond: frond.name,
-          frondScope: scope,
-          log: frondLog,
-          collectors: collectorTypeNames,
-          presenters: presenterMap,
-          middlewaresFor: getMiddlewares,
-          emissions,
-        },
-      );
+      if (inheritsCrud(handler.ctor) && !entity) {
+        // An installed Crud subject may be absent from the local scan.
+        frondLog.debug(`${handler.ctor.name} extends Crud() and no scanned entity is named `
+          + `'${subjectOf(handler.ctor, handler.address)}' — installed entity, or a missing `
+          + `one: no storage will be injected`);
+      }
+
+      const facade = new HandlerFacade(handler, targetScope, {
+        key: facadeKey,
+        frond: frond.name,
+        handlers: frond.handlers,
+        operations: operationModel.forHandler(handler),
+        collectors: collectorTypeNames,
+        presenter: presenterMap.get(handler.address),
+        presenterScope: scope,
+        middlewares: () => getMiddlewares(handler.address),
+      });
+      // Emissions use the same contracts and execution path as direct calls.
+      emissions.note(facade.contracts, facadeKey);
       // The terms alongside the door, under the same audience — a surface that serves
       // fewer ops describes fewer ops.
       container.registerValue(contractsKeyOf(handler.address, handler.surface), facade.contracts);
@@ -440,18 +421,18 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
           routeRegistry.register(new OperationRoute(
             'local',
             address,
-            (call) => facade.ops[operation](call.invocation),
+            (call) => facade.execute(operation, call.invocation),
           ));
         }
       }
 
-      const entry = new FacadeEntry(
+      const operations = facadeOperations(
         handler.surface ? localDispatcher : dispatcher,
         handler.address,
         routeRegistry.operationNames(handler.address, handler.surface),
         handler.surface,
       );
-      container.registerValue(facadeKey, entry.operations);
+      container.registerValue(facadeKey, operations);
     };
 
     // A presenter is about an entity — computed fields sit on a shape — so this walks
@@ -485,7 +466,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       const facadeKey = facadeKeyOf(handler.address);
       buildFacade(entity, handler, scope, facadeKey);
       frondLog.debug(`${facadeKey} [${Object.keys(container.resolve(facadeKey) as any).join(', ')}]`
-        + (entity ? '' : ' — no entity of that name: no ORM, no projection, no presenter'));
+        + (entity ? '' : ' — no entity of that name: no storage, no projection, no presenter'));
     }
 
     // The dual, and it stays: a shape that declares no operation answers nothing. Said
@@ -496,7 +477,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       }
     }
 
-    // Surface handlers — create sub-scope per surface handler with scoped ORM
+    // Surface handlers — create sub-scope per surface handler with scoped storage
     //
     // Pointing at nothing is legal HERE TOO. This loop used to `continue` when no entity
     // carried the handler's name, so `handlers/public/SearchHandler.ts` with no `Search`
@@ -506,25 +487,25 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       const entity = frond.entities.find((e) => e.name === handler.address);
       const surfaceScope = scope.createScope();
 
-      // Register scoped ORM if output override differs from entity — under the REPOSITORY
+      // Register scoped storage if output override differs from entity — under the REPOSITORY
       // key, which is what a Crud handler asks for, and under the port's own for a holder
       // that legitimately names it. Registering only the latter left a named surface with
       // no door at all once the façade stopped spelling the storage.
-      if (entity && options.ormFactory) {
-        const baseOrm = options.ormFactory(entity.entityClass, entity.name);
+      if (entity && options.storageFactory) {
+        const baseStorage = options.storageFactory(entity.entityClass, entity.name);
         const outputSchema = handler.outputOverride ?? (handler.ctor as any).__output;
         const scoped = outputSchema && outputSchema !== entity.entityClass
-          ? baseOrm.output(outputSchema)
-          : baseOrm;
+          ? baseStorage.output(outputSchema)
+          : baseStorage;
         const guarded = new StorageGuard(entity.entityClass.getFields(), entity.name).guard(scoped);
-        surfaceScope.registerValue(ormKeyOf(entity.name), guarded);
+        surfaceScope.registerValue(storageKeyOf(entity.name), guarded);
         surfaceScope.registerValue(repositoryKeyOf(entity.name), guarded);
       }
 
       const facadeKey = facadeKeyOf(handler.address, handler.surface);
       buildFacade(entity, handler, surfaceScope, facadeKey);
       frondLog.debug(`${facadeKey} [${Object.keys(container.resolve(facadeKey) as any).join(', ')}]`
-        + (entity ? '' : ' — no entity of that name: no ORM, no projection, no presenter'));
+        + (entity ? '' : ' — no entity of that name: no storage, no projection, no presenter'));
     }
 
     // A named surface is closed, so what it contains is a fact worth stating.
@@ -562,17 +543,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
   // Once every door exists: what is announced here and what is listened to are both known.
   emissions.register();
 
-  /**
-   * The last resort, held by the container so every resolution path shares it.
-   *
-   * It used to live on `app.resolve` alone, which meant the runner found a remote façade
-   * and dependency injection did not — a handler asking for a neighbour that had moved
-   * got `is not registered` while the very same call over the wire worked. One door now.
-   *
-   * Surface-scoped keys ('admin:productHandler') stay local: a named surface resolves in
-   * this container only, so fabricating one for a remote frond would answer NOT_FOUND on
-   * everything (see Known issues).
-   */
+  /** The last resort, held by the container so every resolution path shares it. */
   container.setFallback?.((name) => {
     if (!remoteRouter) return undefined;
     if (!name.endsWith('Handler') || name.includes(':')) return undefined;
@@ -580,19 +551,15 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     // `lowerFirst` because a DEPENDENCY names the type as written — `ProductHandler`,
     // PascalCase — while a card declares `product`, so the raw strip asked the router for
     // 'Product' and every by-type dependency on a remote handler answered NOT_FOUND.
-    return new FacadeEntry(
+    return facadeOperations(
       dispatcher,
       lowerFirst(name.replace(/Handler$/, '')),
-    ).operations;
+    );
   });
 
   /**
-   * Everything this app holds, let go in reverse of how it was taken: what an extension
-   * took on last, then the container's own, then whoever handed a resource in.
-   *
-   * It does NOT wait for running calls — `drain()` is that, and it is a separate gesture
-   * because waiting and releasing do not have the same owner: a test releases at once, a
-   * host turning the ring wants the work finished first.
+   * Everything this app holds, let go in reverse of how it was taken: what an extension took on
+   * last, then the container's own, then whoever handed a resource in.
    */
   const release = async (): Promise<void> => {
     // Every level is told to close even when one refuses, and the refusals leave together —
@@ -615,13 +582,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     }
   };
 
-  /**
-   * Stop taking calls, and resolve once the ones already running are done.
-   *
-   * Refuses on `timeoutMs` rather than resolving anyway: a drain that gives up quietly
-   * reads exactly like a drain that succeeded, and the caller — who is about to release
-   * a storage connection under whatever is left — is the one who must decide.
-   */
+  /** Stop taking calls, and resolve once the ones already running are done. */
   const drain = async (timeoutMs?: number): Promise<void> => {
     inflight.close();
     if (timeoutMs === undefined) return inflight.whenIdle();
@@ -676,28 +637,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     }
   };
 
-  /**
-   * THE membership rule, stated once — every projection reads this and nothing
-   * else. It used to live twice, verbatim, in the REST and GraphQL adapters,
-   * and two other readers invented their own answer.
-   *
-   * Naming an audience closes it. Two ways to name an entity into a surface,
-   * in precedence order:
-   *   - `surfaces:` in frond.config.ts — when the list exists, it IS the list;
-   *   - a handler under `handlers/<surface>/` — which also restricts the façade.
-   * `@expose` is a THIRD way and this rule does not read it: the scan sets a
-   * boolean, read by the two adapters and by `exposedAdapters` — never here.
-   * What neither of the two names is not served. It used to be the reverse: no
-   * `public:categoryHandler` meant the FULL CategoryHandler rode the public
-   * door, create/update/delete included (measured on demos/nuxt-blog).
-   *
-   * A named entity with no façade of its own falls back to the default one —
-   * that is not the old widening, it is the author saying "this one, as it is".
-   * The leak was exposure with no statement behind it.
-   *
-   * A surface key stays local: a doublure serves whatever the remote's own door
-   * serves, which is the remote's business and not ours to re-audience.
-   */
+  /** THE membership rule, stated once — every projection reads this and nothing else. */
   const facadeFor = (entity: string, surface?: string): Record<string, Function> | undefined => {
     if (!surface) return facadeAt(facadeKeyOf(entity), true);
 
@@ -709,18 +649,18 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
 
     const fallback = facadeAt(facadeKeyOf(entity), false);
     return fallback
-      ? new FacadeEntry(
+      ? facadeOperations(
           localDispatcher,
           entity,
           routeRegistry.operationNames(entity, surface),
           surface,
-        ).operations
+        )
       : undefined;
   };
 
   if (remoteRouter) {
     const remoteFacades = new Map<string, Record<string, Function>>();
-    routeRegistry.addResolver(new RemoteRouteResolver((entity) => {
+    routeRegistry.addResolver(remoteRoutes((entity) => {
       const known = remoteFacades.get(entity);
       if (known) return known;
       const facade = createRemoteFacade(entity, remoteRouter, getMiddlewares);
@@ -742,19 +682,14 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
   };
 
   /**
-   * The storage an entity is backed by — the dual of `facadeFor`, which serves its
-   * client-facing door. Both are ways in; an entity that opens none of them still has rows.
-   *
-   * It resolves through the owning frond's scope, because that is where entity ORMs live:
-   * `resolve('UserOrm')` reads the ROOT container and never finds one, so callers outside
-   * the frond concluded there was no storage. The seed loop did exactly that, and skipped
-   * every entity with no façade — the one case its own fallback existed for.
+   * The storage an entity is backed by — the dual of `facadeFor`, which serves its client-facing
+   * door.
    */
-  const ormFor = (entity: string): unknown | undefined => {
+  const storageFor = (entity: string): unknown | undefined => {
     const owner = fronds.owner(entity);
     if (!owner) return undefined;
 
-    const key = ormKeyOf(entity);
+    const key = storageKeyOf(entity);
     try {
       return container.resolve<Container>(`frond:${owner.name}`).resolve(key);
     } catch {
@@ -762,14 +697,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     }
   };
 
-  /**
-   * The presenter of an entity, resolved through its owning frond's scope.
-   *
-   * Same shape as `ormFor`, and it exists for the same reason: without it an adapter
-   * has to spell the container key itself. `schema-graphql` did — a hand-written
-   * `${Name}Presenter` — and a key respelled elsewhere finds nothing and says nothing
-   * the day the convention moves, which is exactly the failure `verify.ts` refuses.
-   */
+  /** The presenter of an entity, resolved through its owning frond's scope. */
   const presenterFor = (entity: string): unknown | undefined => {
     const owner = fronds.owner(entity);
     if (!owner) return undefined;
@@ -799,7 +727,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     operationsFor,
     listensTo: () => emissions.listensTo(),
     deliver: (fact, payload) => emissions.deliver(fact, payload),
-    ormFor,
+    storageFor,
     presenterFor,
     dispose: release,
     drain,
@@ -841,7 +769,23 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
 
   // The last thing the boot does, and the first thing a release undoes. An extension may
   // await here — which is what a provider needing to OPEN something could never do.
-  await appLifecycle.up(app);
+  //
+  // A refusal here has to release what the boot took, because the caller cannot: it handed
+  // `onDispose` over BEFORE this line and never receives the app that would carry it back.
+  // Whoever opened a connection to give it to us would otherwise leak it on every failed boot.
+  try {
+    await appLifecycle.up(app);
+  } catch (cause) {
+    try {
+      await release();
+    } catch (refused) {
+      throw new AggregateError(
+        [cause, ...(refused instanceof AggregateError ? refused.errors : [refused])],
+        `The boot failed and could not release everything it had taken: ${(cause as Error)?.message ?? String(cause)}`,
+      );
+    }
+    throw cause;
+  }
 
   return app;
 }

package/src/boot/card.ts

@@ -0,0 +1,84 @@
+/** What an app says about ITSELF — the `rpc.discover` answer, built from the app. */
+import { Card } from '@fougere/schema';
+import type { App } from './types.js';
+import { factsAnnouncedBy } from '../emit.js';
+import type { InvocationContext } from '../wire/Invocation.js';
+import { facadeKeyOf, contractsKeyOf, type CardOp, type IdentityCard } from '../wire/call.js';
+import type { OperationContract } from '../wire/operation.js';
+
+type AnyFacade = Record<string, (invocation?: InvocationContext) => Promise<unknown>>;
+
+/** Serialize what the app hosts, for one audience. */
+export function identityCardOf(app: App, surface?: string): IdentityCard {
+  const declared = app.fronds.schemas();
+
+  return {
+    fronds: app.fronds.map((frond) => {
+      // What the frond answers to, not what it stores. This walked `frond.entities`, so a
+      // handler carrying no entity — a health check, a search across shapes — was built,
+      // served, and absent from the card: `sync` could not generate its door and a remote
+      // consumer had no way to know it existed. The boot has said "pointing at nothing is
+      // legal" since handlers became the subject; the card had not caught up.
+      const byEntity = new Map(frond.entities.map((entity) => [entity.name, entity]));
+      const addresses = [...new Set([
+        ...frond.entities.map((entity) => entity.name),
+        ...frond.handlers.map((handler) => handler.address),
+      ])];
+
+      return {
+        name: frond.name,
+        doors: addresses.flatMap((address) => {
+          const ops = facadeOps(app, address, surface);
+          if (ops.length === 0) return [];
+          const entity = byEntity.get(address);
+          return [{
+            name: address,
+            ops,
+            // Absent when nothing of that name is stored. A door is still a door.
+            ...(entity ? { schema: Card.fromSchema(entity.entityClass, address).descriptor } : {}),
+          }];
+        }),
+        /** What leaves on its own — the same list on every surface, deliberately. */
+        facts: factsAnnouncedBy(frond.handlers).map((name) => {
+          const entityClass = declared.get(name);
+          return { name, ...(entityClass ? { schema: Card.fromSchema(entityClass, name).descriptor } : {}) };
+        }),
+      };
+    }),
+  };
+}
+
+function facadeOps(app: App, entityName: string, surface?: string): CardOp[] {
+  let facade: AnyFacade;
+  try {
+    facade = app.container.resolve<AnyFacade>(facadeKeyOf(entityName, surface));
+  } catch {
+    return [];
+  }
+
+  // The façade is the list of names; the model is the resolved terms.
+  const effective = app.operationsFor(entityName, surface);
+  if (!effective) {
+    throw new Error(
+      `Facade '${facadeKeyOf(entityName, surface)}' exists without an effective operation table.`,
+    );
+  }
+
+  return Object.keys(facade).map((name) => {
+    const contract = effective.get(name);
+    if (!contract) {
+      throw new Error(
+        `Facade '${facadeKeyOf(entityName, surface)}' serves '${name}' without an effective contract.`,
+      );
+    }
+
+    return {
+      name,
+      ...(contract?.description && { description: contract.description }),
+      ...(contract?.input && { input: Card.fromSchema(contract.input, name).descriptor }),
+      ...(contract?.output && { output: Card.fromSchema(contract.output, name).descriptor }),
+      ...(contract?.cardinality && { cardinality: contract.cardinality }),
+      kind: contract.kind,
+    };
+  });
+}