@fougere/core 0.8.3-alpha.0 → 0.8.4-alpha.0

package/src/boot/bootstrap.ts

@@ -3,6 +3,7 @@ import { lowerFirst, type Fields, type SchemaView } from '@fougere/schema';
 import { nameOf } from '../descriptor/frond.js';
 import type { EntityEntry, HandlerEntry, PresenterEntry } from '../descriptor/frond.js';
 import { hostedBy } from './hosted.js';
+import { installFrond, type Assembly } from './install.js';
 import type { AuthRuntime } from './auth.js';
 import type { CreateAppOptions, App } from './types.js';
 import type { AppMiddleware } from '../wire/middleware.js';
@@ -28,7 +29,7 @@ import { identityCardOf } from './card.js';
 import { AppLifecycle } from './AppLifecycle.js';
 import { inheritsCrud, subjectOf } from '../prefab/crud.js';
 import { repositoryKeyOf } from '../prefab/repository.js';
-import { storageKeyOf } from '../storage.js';
+import { storageKeyOf } from '../storage/port.js';
 import { declares } from '../source.js';
 import { presenterKeyOf } from '../prefab/presenter.js';
 import { collectorKeyOf } from '../prefab/collector.js';
@@ -36,6 +37,7 @@ 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 { servedSurfaces } from '../descriptor/surface.js';
 import { OperationRoute } from '../dispatch/OperationRoute.js';
 import { remoteRoutes } from '../dispatch/remoteRoutes.js';
 import { RouteRegistry } from '../dispatch/RouteRegistry.js';
@@ -78,506 +80,12 @@ function assertOneOwnerPerKey(
 /** Bootstrap a fougere application. */
 export async function createApp(options: CreateAppOptions): Promise<App> {
   const container = options.createContainer();
-  // Boot chatter is debug by default; a host (e.g. the CLI) can quiet it.
-  const log = new Logger('boot:app');
-
-  // Builtins — registered under class name (PascalCase) for type-based DI.
-  // No level here and none anywhere: a logger consults `setLogLevel`'s value at each
-  // emission, so this instance survives a level change and so does every handler that
-  // was handed it. A frond declaring `class X extends Logger` takes this key over,
-  // like any other port.
-  container.registerValue('Logger', new Logger('app'));
-  container.register('Config', Config, { lifetime: 'singleton' });
-  log.debug('builtins registered (Logger, Config)');
-
-  // What this app hosts is HANDED IN — stated, scanned, or both (`hostedBy`). Producing
-  // it may read a disk; consuming it never does, which is the whole reason this file names
-  // 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,
-    adapters: options.adapters,
-  });
-  const scanMs = (performance.now() - scanStart).toFixed(0);
-  const blocking = diagnostics.filter((d) => d.severity === 'blocking');
-  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. */
-  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. */
-  const invalidOperations = operationModel.resolutionDiagnostics
-    .filter((diagnostic) => diagnostic.severity === 'blocking');
-  if (invalidOperations.length > 0) {
-    const details = invalidOperations.map((d) =>
-      `  [${d.code}]${d.subject ? ` ${d.subject}` : ''}\n    ${d.message}\n    ${d.filePath}`,
-    );
-    throw new Error(
-      `Fougere boot refused: ${invalidOperations.length} unresolved operation contract(s):\n`
-      + details.join('\n'),
-    );
-  }
 
-  // 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 +
-  // storageFactory so all auth writes flow through Storage.
-  let authRuntime: AuthRuntime | undefined;
-  if (options.auth) {
-    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.');
-    }
-    log.info('initializing auth runtime');
-    authRuntime = await options.auth.create({
-      db: options.db,
-      storageFactory: options.storageFactory,
-    });
-    log.info(`auth ready — mounted at ${authRuntime.basePath}`);
-  }
-
-  // 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 ?? {});
-  if (declaredRemotes.length > 0 && !options.remoteTransport) {
-    throw new Error(
-      'createApp: `remotes` is declared but `remoteTransport` is missing — pass one (e.g. from @fougere/transport-http).',
-    );
-  }
-  const remoteRouter = declaredRemotes.length > 0 && options.remoteTransport
-    ? createRemoteRouter(Object.fromEntries(declaredRemotes), options.remoteTransport)
-    : undefined;
-
-  // What is running on this app — counted at the one door every caller goes through,
-  // so releasing it can wait for the work instead of pulling the floor out.
-  const inflight = new InFlight();
-
-  // Middleware storage — read at call time, not at boot time
-  const globalMiddlewares: AppMiddleware[] = [];
-  const scopedMiddlewares = new Map<string, AppMiddleware[]>();
-  /** What this app took on beyond its fronds. Its `up` is the last thing the boot does. */
+  // Held out here, and not where the ascent reads it, because releasing needs it and
+  // releasing has to work from the first line the boot takes something.
   const appLifecycle = new AppLifecycle().add(...(options.extensions ?? []));
-  const routeRegistry = new RouteRegistry();
-  const dispatchLifecycle = new DispatchLifecycle(
-    options.dispatchObservers,
-    (error, event) => log.error(
-      `[dispatch-observer] ${event.stage} ${event.call.address.toString()}`,
-      error,
-    ),
-  );
-  const dispatcher = new Dispatcher(routeRegistry, inflight, dispatchLifecycle);
-  const localDispatcher = new Dispatcher(
-    routeRegistry,
-    inflight,
-    dispatchLifecycle,
-    new LocalRoutePolicy((surface) => fronds.servedNames(surface)),
-  );
-
-  function getMiddlewares(entity: string): AppMiddleware[] {
-    const scoped = scopedMiddlewares.get(entity) ?? [];
-    return [...globalMiddlewares, ...scoped];
-  }
-
-  assertOneOwnerPerKey(fronds, options.remotes);
-
-  // 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
-  // names the frond rather than the entity, since `remotes:` is declared per frond.
-  const frondOf = new Map(fronds.flatMap((f) => f.entities.map((e) => [e.name, f.name] as const)));
-  const emissions = new Emissions(fronds, entityByName, container, log, options.onEmit);
-  /** Canonical operation tables, indexed by the same audience key as their facades. */
-  const effectiveByKey = new Map<string, EffectiveOperationsMap>();
-
-  const contractsOf = (operations: EffectiveOperationsMap): OperationsMap => new Map(
-    [...operations].map(([name, operation]) => [name, operation as OperationContract] as const),
-  );
-
-  // Every port an implementation was bound to, so a `ports:` entry that named none
-  // can say so rather than look obeyed.
-  const boundPorts = new Set<string>();
-
-  // Register frond scopes
-  for (const frond of fronds) {
-    // Declared remote: keep the scanned metadata (bridges route with it),
-    // register nothing locally — resolve() falls through to the remote façade.
-    if (options.remotes && frond.name in options.remotes) {
-      log.child(frond.name).info('declared remote — not hosted locally');
-      // Its doors answer elsewhere, but what they LISTEN to was read here.
-      for (const handler of frond.handlers) {
-        const key = facadeKeyOf(handler.address, handler.surface);
-        const operations = operationModel.forHandler(handler);
-        effectiveByKey.set(key, operations);
-        emissions.note(contractsOf(operations), key);
-
-      }
-      continue;
-    }
-    const scope = container.createScope();
-    const frondLog = log.child(frond.name);
-
-    // `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 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 `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 `Reads` will fail '
-        + 'at its first call. Pass one (`@fougere/adapter-duckdb`), or drop the clause.',
-      );
-    }
-    if (frond.reads?.length && options.sourcesFactory) {
-      // Resolved across the WHOLE app, not this frond's own entities: a cross-source
-      // query joins entities from different fronds by definition — `Progress` here,
-      // `Book` next door — so restricting the list to its own would make it useless.
-      // Naming one IS the authorization; that is what the declaration is for.
-      const named = frond.reads
-        .map((name) => entityByName.get(lowerFirst(name)))
-        .filter((entity): entity is NonNullable<typeof entity> => entity !== undefined);
-      if (named.length !== frond.reads.length) {
-        const missing = frond.reads.filter((name) => !entityByName.has(lowerFirst(name)));
-        frondLog.warn(
-          `[reads] ${missing.join(', ')} — named in frond.config.ts but scanned nowhere in this app, `
-          + 'so a query naming one would find no table. Check the spelling, or the entity file.',
-        );
-      }
-      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);
-    refuseStorageInUserCode(frond, owners, (entity) => entityByName.has(entity));
-    refuseCrudOnOwned(frond, owners);
-
-    for (const provider of frond.providers) {
-      scope.register(nameOf(provider), provider.ctor, { deps: provider.deps });
-    }
-    // …and again under the port each one extends, so `private payment: Payment`
-    // reaches the realization instead of the base class it is declared against.
-    // Registered AFTER the loop above so a port key always wins over the base's
-    // own registration — same precedence as a declared repository over its default.
-    for (const [port, impl] of portBindings(frond.providers, (n) => scope.has(n), options.ports)) {
-      scope.register(port, impl.ctor, { deps: impl.deps });
-      boundPorts.add(port);
-      frondLog.debug(`port ${port} → ${impl.ctor.name}`);
-    }
-    if (frond.providers.length > 0) {
-      frondLog.debug(`${frond.providers.length} provider(s): ${frond.providers.map(nameOf).join(', ')}`);
-    }
-
-    // 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) {
-      const unenforced: string[] = [];
-      for (const entity of frond.entities) {
-        const key = storageKeyOf(entity.name);
-        const source = options.sourceOf?.(entity.name) ?? 'db';
-        if (declares(entity.entityClass, 'unique') && options.enforces?.(source, 'unique') === false) {
-          unenforced.push(`${entity.name} in '${source}'`);
-        }
-        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
-          ? 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(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 (`{ 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
-        // can spell. Every member is skipped, not just the one the key is named after —
-        // that asymmetry was the whole hole.
-        const repoKey = repositoryKeyOf(entity.name);
-        const owner = owners.get(entity.name);
-        if (owner) {
-          frondLog.debug(`${entity.name} — owned by ${owner}, no default repository`);
-        } else if (!scope.has(repoKey)) {
-          scope.registerValue(repoKey, guarded);
-        }
-      }
-      if (frond.entities.length > 0) {
-        frondLog.debug(`${frond.entities.length} entity storage(s): ${frond.entities.map((e) => e.name).join(', ')}`);
-      }
-      // The judge refuses a duplicate it can SEE — the row already stored. Two writes arriving
-      // together see the same absence, and only the place they land can refuse the second.
-      if (unenforced.length > 0) {
-        frondLog.warn(
-          `unique declared, and the source does not enforce it: ${unenforced.join(', ')} — `
-          + 'two concurrent writes can both pass',
-        );
-      }
-    }
-
-    // Frames, after the ORMs and before anything that may ask for one. A frame is read
-    // from the same `deps` every other port is read from — asking for it IS declaring it,
-    // so nothing is registered for a frame nobody wants.
-    registerFrames(
-      scope,
-      [...frond.handlers, ...frond.providers, ...frond.presenters, ...frond.collectors].flatMap((d) => d.deps),
-      frond.providers,
-      {
-        entityByName,
-        frondOf,
-        hostedHere: (name) => !(options.remotes && name in options.remotes),
-        storageFactory: options.storageFactory,
-        sourceOf: options.sourceOf,
-        transacts: options.transacts,
-        transacted: options.transacted,
-        log: frondLog,
-      },
-    );
-
-    // Register presenters in scope — PascalCase type name (e.g. 'PostPresenter')
-    const presenterMap = new Map(frond.presenters.map((p) => [p.entityName, p]));
-    for (const presenter of frond.presenters) {
-      scope.register(presenterKeyOf(presenter.entityName), presenter.ctor, { deps: presenter.deps });
-    }
-    if (frond.presenters.length > 0) {
-      frondLog.debug(`${frond.presenters.length} presenter(s): ${frond.presenters.map((p) => p.entityName).join(', ')}`);
-    }
-
-    // Register collectors in scope — PascalCase type name (e.g. 'UserCollector')
-    const collectorTypeNames = new Set(frond.collectors.map((c) => c.typeName));
-    for (const collector of frond.collectors) {
-      const key = collectorKeyOf(collector.typeName);
-      scope.register(key, collector.ctor, { deps: collector.deps });
-    }
-    if (frond.collectors.length > 0) {
-      frondLog.debug(`${frond.collectors.length} collector(s): ${frond.collectors.map((c) => c.typeName).join(', ')}`);
-    }
-
-    // Build handler facades → registered in ROOT container (public contract)
-    const defaultHandlers = frond.handlers.filter((h) => !h.surface);
-    const surfaceHandlers = frond.handlers.filter((h) => h.surface);
-    const defaultHandlerMap = new Map(defaultHandlers.map((h) => [h.address, h]));
-
-    /** Build the door of a handler and register it under the audience it serves. */
-    const buildFacade = (
-      entity: EntityEntry | undefined,
-      handler: HandlerEntry,
-      targetScope: Container,
-      facadeKey: string,
-    ) => {
-      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);
-      effectiveByKey.set(facadeKey, facade.effectiveOperations);
-
-      const surfaces = new Set<string | undefined>([handler.surface]);
-      if (!handler.surface) {
-        for (const [surface, names] of Object.entries(frond.surfaces ?? {})) {
-          const isDeclared = names.some((name) =>
-            name.toLowerCase() === handler.address.toLowerCase());
-          const hasOwnDoor = surfaceHandlers.some((candidate) =>
-            candidate.surface === surface && candidate.address === handler.address);
-          if (isDeclared && !hasOwnDoor) surfaces.add(surface);
-        }
-      }
-
-      for (const operation of facade.contracts.keys()) {
-        for (const surface of surfaces) {
-          const address = new RouteAddress({
-            entity: handler.address,
-            operation,
-            ...(surface !== undefined ? { surface } : {}),
-          });
-          routeRegistry.register(new OperationRoute(
-            'local',
-            address,
-            (call) => facade.execute(operation, call.invocation),
-          ));
-        }
-      }
-
-      const operations = facadeOperations(
-        handler.surface ? localDispatcher : dispatcher,
-        handler.address,
-        routeRegistry.operationNames(handler.address, handler.surface),
-        handler.surface,
-      );
-      container.registerValue(facadeKey, operations);
-    };
-
-    // A presenter is about an entity — computed fields sit on a shape — so this walks
-    // entities. Exposing the instance lazily; the bridge resolves it on first access.
-    for (const entity of frond.entities) {
-      if (!presenterMap.has(entity.name)) continue;
-      const presenterKey = presenterKeyOf(entity.name);
-      let presenterInstance: any;
-      container.registerValue(presenterKey, new Proxy({} as any, {
-        get(_target, prop) {
-          if (!presenterInstance) presenterInstance = scope.resolve(presenterKey);
-          return presenterInstance[prop];
-        },
-      }));
-    }
-
-    // A facade is about a handler, so this walks HANDLERS. It walked entities before,
-    // which made an entity a precondition for being callable at all: a handler naming
-    // none was scanned, then never built, and nothing said so.
-    for (const handler of defaultHandlers) {
-      // Two ways to know the subject, and the explicit one wins: `Crud(Item)` names the
-      // entity it was built on, whatever the handler is called. Otherwise the handler's
-      // own name is the only thing pointing at one — and pointing at nothing is legal.
-      //
-      // By NAME, not by identity: the scanner loads an entity through its own loader and
-      // the handler imports it through the runtime's, so the same class arrives as two
-      // objects. `===` compares module instances, which is not the question being asked.
-      const crudTarget = targetOf(handler.ctor);
-      const subject = crudTarget?.name ? lowerFirst(crudTarget.name) : handler.address;
-      const entity = frond.entities.find((e) => e.name === subject);
-      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 storage, no projection, no presenter'));
-    }
-
-    // The dual, and it stays: a shape that declares no operation answers nothing. Said
-    // once per entity rather than deduced from a silence.
-    for (const entity of frond.entities) {
-      if (!defaultHandlerMap.has(entity.name)) {
-        frondLog.debug(`${entity.name} — entity only, no handler: exposes nothing`);
-      }
-    }
-
-    // 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`
-    // entity got no door at all and no line saying why — while the very same handler at
-    // the default surface is built and logged. One rule, both surfaces.
-    for (const handler of surfaceHandlers) {
-      const entity = frond.entities.find((e) => e.name === handler.address);
-      const surfaceScope = scope.createScope();
-
-      // 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.storageFactory) {
-        const baseStorage = options.storageFactory(entity.entityClass, entity.name);
-        const outputSchema = handler.outputOverride ?? (handler.ctor as any).__output;
-        const scoped = outputSchema && outputSchema !== entity.entityClass
-          ? baseStorage.output(outputSchema)
-          : baseStorage;
-        // The view is handed over so a filter on a field this door hides is SAID. The
-        // guard holds no logger — a warning is the boot's to voice, as a seed's report is.
-        const guarded = new StorageGuard(entity.entityClass.getFields(), entity.name, {
-          ...(outputSchema && outputSchema !== entity.entityClass
-            ? { view: (outputSchema as { getFields(): Fields }).getFields() }
-            : {}),
-          outOfView: (message) => frondLog.warn(message),
-        }).guard(scoped);
-        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 storage, no projection, no presenter'));
-    }
-
-    // A named surface is closed, so what it contains is a fact worth stating.
-    // Saying it at boot is the difference between a rule and a rule you can
-    // check: an entity you meant to serve and never wrote a handler for is
-    // absent HERE, in one line, instead of being discovered missing later.
-    const surfaceNames = [...new Set(surfaceHandlers.map((h) => h.surface as string))].sort();
-    for (const surfaceName of surfaceNames) {
-      const served = surfaceHandlers
-        .filter((h) => h.surface === surfaceName)
-        .map((h) => h.address)
-        .sort();
-      const absent = frond.entities.map((e) => e.name).filter((n) => !served.includes(n));
-      frondLog.info(
-        `surface '${surfaceName}' — ${served.length} entit${served.length === 1 ? 'y' : 'ies'}: ${served.join(', ')}` +
-        (absent.length > 0 ? ` (not served: ${absent.join(', ')})` : ''),
-      );
-    }
-
-    container.registerValue(`frond:${frond.name}`, scope);
-    frondLog.info(`registered — ${frond.entities.length} entities, ${frond.handlers.length} handlers, ${frond.seeds.length} seeds`);
-  }
-
-  // A `ports:` key that matched no port anywhere reads as a choice that was made, and
-  // was not. Said once, at the end, because the entry is app-wide while a port is a
-  // frond's — no single frond can tell whether a key is a typo or a neighbour's.
-  const unused = Object.keys(options.ports ?? {}).filter((port) => !boundPorts.has(port));
-  if (unused.length > 0) {
-    log.warn(
-      `[ports] ${unused.join(', ')} — named in fougere.config.ts, but no scanned class extends `
-      + 'them, so nothing was chosen. Check the spelling, or drop the entry.',
-    );
-  }
-
-  // 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. */
-  container.setFallback?.((name) => {
-    if (!remoteRouter) return undefined;
-    if (!name.endsWith('Handler') || name.includes(':')) return undefined;
-    // Façade-shaped stand-in; routing happens lazily at the first call. Through
-    // `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 facadeOperations(
-      dispatcher,
-      lowerFirst(name.replace(/Handler$/, '')),
-    );
-  });
+  /** The app once it exists — a refusal before that releases the two levels that do. */
+  let built: App | undefined;
 
   /**
    * Everything this app holds, let go in reverse of how it was taken: what an extension took on
@@ -589,7 +97,12 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     // there and broken here, a refusing extension took the container and the connection
     // down with it, which is the leak this gesture exists to prevent.
     const refused: unknown[] = [];
-    for (const level of [() => appLifecycle.down(app), () => container.dispose(), () => options.onDispose?.()]) {
+    const levels = [
+      ...(built ? [() => appLifecycle.down(built!)] : []),
+      () => container.dispose(),
+      () => options.onDispose?.(),
+    ];
+    for (const level of levels) {
       try {
         await level();
       } catch (error) {
@@ -604,200 +117,401 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     }
   };
 
-  /** 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();
-    let timer: ReturnType<typeof setTimeout>;
-    await Promise.race([
-      inflight.whenIdle().then(() => clearTimeout(timer)),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(
-          () => reject(new Error(`[drain] ${inflight.count} call(s) still running after ${timeoutMs}ms`)),
-          timeoutMs,
-        );
-      }),
-    ]);
-  };
-
-  const resolve = <T>(name: string): T => {
-    try {
-      return container.resolve<T>(name);
-    } catch (err) {
-      if (name.endsWith('Handler') && !name.includes(':') && !remoteRouter) {
-        throw new Error(notLoaded(name.replace(/Handler$/, '')));
-      }
-      throw err;
+  try {
+    // Boot chatter is debug by default; a host (e.g. the CLI) can quiet it.
+    const log = new Logger('boot:app');
+
+    // Builtins — registered under class name (PascalCase) for type-based DI.
+    // No level here and none anywhere: a logger consults `setLogLevel`'s value at each
+    // emission, so this instance survives a level change and so does every handler that
+    // was handed it. A frond declaring `class X extends Logger` takes this key over,
+    // like any other port.
+    container.registerValue('Logger', new Logger('app'));
+    container.register('Config', Config, { lifetime: 'singleton' });
+    log.debug('builtins registered (Logger, Config)');
+
+    // What this app hosts is HANDED IN — stated, scanned, or both (`hostedBy`). Producing
+    // it may read a disk; consuming it never does, which is the whole reason this file names
+    // 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,
+      adapters: options.adapters,
+    });
+    const scanMs = (performance.now() - scanStart).toFixed(0);
+    const blocking = diagnostics.filter((d) => d.severity === 'blocking');
+    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. */
+    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. */
+    const invalidOperations = operationModel.resolutionDiagnostics
+      .filter((diagnostic) => diagnostic.severity === 'blocking');
+    if (invalidOperations.length > 0) {
+      const details = invalidOperations.map((d) =>
+        `  [${d.code}]${d.subject ? ` ${d.subject}` : ''}\n    ${d.message}\n    ${d.filePath}`,
+      );
+      throw new Error(
+        `Fougere boot refused: ${invalidOperations.length} unresolved operation contract(s):\n`
+        + details.join('\n'),
+      );
     }
-  };
 
-  const schemaFor = async (entity: string): Promise<SchemaView> => {
-    const found = fronds.entity(entity);
-    if (found) return found.entityClass;
-    if (remoteRouter) {
-      const route = await remoteRouter.route(entity);
-      // A remote door that stores nothing publishes ops and no shape. Saying so beats
-      // handing back an empty schema, which would validate every input it was given.
-      if (!route.schema) {
-        throw new Error(
-          `'${entity}' is served by frond '${route.frond}' but stores no rows, so it has no schema. `
-          + `Call its operations through the façade instead.`,
-        );
+    // 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 +
+    // storageFactory so all auth writes flow through Storage.
+    let authRuntime: AuthRuntime | undefined;
+    if (options.auth) {
+      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.');
       }
-      return route.schema;
+      log.info('initializing auth runtime');
+      authRuntime = await options.auth.create({
+        db: options.db,
+        storageFactory: options.storageFactory,
+      });
+      log.info(`auth ready — mounted at ${authRuntime.basePath}`);
     }
-    throw new Error(notLoaded(entity));
-  };
 
-  const facadeAt = (key: string, topology: boolean): Record<string, Function> | undefined => {
-    try {
-      return topology
-        ? resolve<Record<string, Function>>(key)
-        : container.resolve<Record<string, Function>>(key);
-    } catch {
-      return undefined;
+    // 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 ?? {});
+    if (declaredRemotes.length > 0 && !options.remoteTransport) {
+      throw new Error(
+        'createApp: `remotes` is declared but `remoteTransport` is missing — pass one (e.g. from @fougere/transport-http).',
+      );
     }
-  };
-
-  /** 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);
-
-    const own = facadeAt(facadeKeyOf(entity, surface), false);
-    const declared = fronds.owner(entity)?.surfaces?.[surface];
-    if (!declared) return own;
-    if (!declared.some((n) => n.toLowerCase() === entity.toLowerCase())) return undefined;
-    if (own) return own;
-
-    const fallback = facadeAt(facadeKeyOf(entity), false);
-    return fallback
-      ? facadeOperations(
-          localDispatcher,
-          entity,
-          routeRegistry.operationNames(entity, surface),
-          surface,
-        )
+    const remoteRouter = declaredRemotes.length > 0 && options.remoteTransport
+      ? createRemoteRouter(Object.fromEntries(declaredRemotes), options.remoteTransport)
       : undefined;
-  };
 
-  if (remoteRouter) {
-    const remoteFacades = new Map<string, Record<string, Function>>();
-    routeRegistry.addResolver(remoteRoutes((entity) => {
-      const known = remoteFacades.get(entity);
-      if (known) return known;
-      const facade = createRemoteFacade(entity, remoteRouter, getMiddlewares);
-      remoteFacades.set(entity, facade);
-      return facade;
-    }));
-  }
+    // What is running on this app — counted at the one door every caller goes through,
+    // so releasing it can wait for the work instead of pulling the floor out.
+    const inflight = new InFlight();
+
+    // Middleware storage — read at call time, not at boot time
+    const globalMiddlewares: AppMiddleware[] = [];
+    const scopedMiddlewares = new Map<string, AppMiddleware[]>();
+    /** What this app took on beyond its fronds. Its `up` is the last thing the boot does. */
+    const routeRegistry = new RouteRegistry();
+    const dispatchLifecycle = new DispatchLifecycle(
+      options.dispatchObservers,
+      (error, event) => log.error(
+        `[dispatch-observer] ${event.stage} ${event.call.address.toString()}`,
+        error,
+      ),
+    );
+    const dispatcher = new Dispatcher(routeRegistry, inflight, dispatchLifecycle);
+    const localDispatcher = new Dispatcher(
+      routeRegistry,
+      inflight,
+      dispatchLifecycle,
+      new LocalRoutePolicy((surface) => fronds.servedNames(surface)),
+    );
 
-  /** The terms beside a door, with the exact same named-surface fallback rule. */
-  const operationsFor = (entity: string, surface?: string): EffectiveOperationsMap | undefined => {
-    if (!surface) return effectiveByKey.get(facadeKeyOf(entity));
+    function getMiddlewares(entity: string): AppMiddleware[] {
+      const scoped = scopedMiddlewares.get(entity) ?? [];
+      return [...globalMiddlewares, ...scoped];
+    }
 
-    const own = effectiveByKey.get(facadeKeyOf(entity, surface));
-    const declared = fronds.owner(entity)?.surfaces?.[surface];
-    if (!declared) return own;
-    return declared.some((name) => name.toLowerCase() === entity.toLowerCase())
-      ? (own ?? effectiveByKey.get(facadeKeyOf(entity)))
-      : undefined;
-  };
+    assertOneOwnerPerKey(fronds, options.remotes);
 
-  /**
-   * The storage an entity is backed by — the dual of `facadeFor`, which serves its client-facing
-   * door.
-   */
-  const storageFor = (entity: string): unknown | undefined => {
-    const owner = fronds.owner(entity);
-    if (!owner) return undefined;
+    // 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
+    // names the frond rather than the entity, since `remotes:` is declared per frond.
+    const frondOf = new Map(fronds.flatMap((f) => f.entities.map((e) => [e.name, f.name] as const)));
+    const emissions = new Emissions(fronds, entityByName, container, log, options.onEmit);
+    /** Canonical operation tables, indexed by the same audience key as their facades. */
+    const effectiveByKey = new Map<string, EffectiveOperationsMap>();
 
-    const key = storageKeyOf(entity);
-    try {
-      return container.resolve<Container>(`frond:${owner.name}`).resolve(key);
-    } catch {
-      return undefined;
+    const contractsOf = (operations: EffectiveOperationsMap): OperationsMap => new Map(
+      [...operations].map(([name, operation]) => [name, operation as OperationContract] as const),
+    );
+
+    // Every port an implementation was bound to, so a `ports:` entry that named none
+    // can say so rather than look obeyed.
+    const boundPorts = new Set<string>();
+
+    // Register frond scopes
+    // What every frond is installed into, and reads while it is: one container, one route
+    // table, one emission list — so what a frond serves is there for the next one to find.
+    const assembly: Assembly = {
+      container, routeRegistry, emissions, dispatcher, localDispatcher, effectiveByKey,
+      boundPorts, operationModel, entityByName, frondOf, contractsOf, getMiddlewares,
+      log, options,
+    };
+    for (const frond of fronds) await installFrond(frond, assembly);
+
+    // A `ports:` key that matched no port anywhere reads as a choice that was made, and
+    // was not. Said once, at the end, because the entry is app-wide while a port is a
+    // frond's — no single frond can tell whether a key is a typo or a neighbour's.
+    const unused = Object.keys(options.ports ?? {}).filter((port) => !boundPorts.has(port));
+    if (unused.length > 0) {
+      log.warn(
+        `[ports] ${unused.join(', ')} — named in fougere.config.ts, but no scanned class extends `
+        + 'them, so nothing was chosen. Check the spelling, or drop the entry.',
+      );
     }
-  };
 
-  /** 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;
+    // 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. */
+    container.setFallback?.((name) => {
+      if (!remoteRouter) return undefined;
+      if (!name.endsWith('Handler') || name.includes(':')) return undefined;
+      // Façade-shaped stand-in; routing happens lazily at the first call. Through
+      // `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 facadeOperations(
+        dispatcher,
+        lowerFirst(name.replace(/Handler$/, '')),
+      );
+    });
 
-    try {
-      return container.resolve<Container>(`frond:${owner.name}`).resolve(presenterKeyOf(entity));
-    } catch {
-      return undefined;
+
+    /** 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();
+      let timer: ReturnType<typeof setTimeout>;
+      await Promise.race([
+        inflight.whenIdle().then(() => clearTimeout(timer)),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`[drain] ${inflight.count} call(s) still running after ${timeoutMs}ms`)),
+            timeoutMs,
+          );
+        }),
+      ]);
+    };
+
+    const resolve = <T>(name: string): T => {
+      try {
+        return container.resolve<T>(name);
+      } catch (err) {
+        if (name.endsWith('Handler') && !name.includes(':') && !remoteRouter) {
+          throw new Error(notLoaded(name.replace(/Handler$/, '')));
+        }
+        throw err;
+      }
+    };
+
+    const schemaFor = async (entity: string): Promise<SchemaView> => {
+      const found = fronds.entity(entity);
+      if (found) return found.entityClass;
+      if (remoteRouter) {
+        const route = await remoteRouter.route(entity);
+        // A remote door that stores nothing publishes ops and no shape. Saying so beats
+        // handing back an empty schema, which would validate every input it was given.
+        if (!route.schema) {
+          throw new Error(
+            `'${entity}' is served by frond '${route.frond}' but stores no rows, so it has no schema. `
+            + `Call its operations through the façade instead.`,
+          );
+        }
+        return route.schema;
+      }
+      throw new Error(notLoaded(entity));
+    };
+
+    const facadeAt = (key: string, topology: boolean): Record<string, Function> | undefined => {
+      try {
+        return topology
+          ? resolve<Record<string, Function>>(key)
+          : container.resolve<Record<string, Function>>(key);
+      } catch {
+        return undefined;
+      }
+    };
+
+    /** Said once per pair, so a door that registers in a loop says it once. */
+    const saidAbsent = new Set<string>();
+
+    /**
+     * A surface is declared in the frond that serves it. When that frond runs in another
+     * process, this one never asked for its doors, and answering 'no' is the only thing a
+     * synchronous rule can do — so it says so rather than registering nothing in silence.
+     */
+    const sayNoSurfaceAcross = (entity: string, surface: string): void => {
+      if (!remoteRouter || saidAbsent.has(`${surface}:${entity}`)) return;
+      saidAbsent.add(`${surface}:${entity}`);
+      log.warn(
+        `surface '${surface}' serves nothing for '${entity}' — the frond that declares it runs `
+        + 'elsewhere, and a remote is asked for its doors at the first call, not at boot. '
+        + 'The default door answers.',
+      );
+    };
+
+    /** 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);
+
+      const own = facadeAt(facadeKeyOf(entity, surface), false);
+      const owner = fronds.owner(entity);
+      if (!owner) {
+        sayNoSurfaceAcross(entity, surface);
+        return own;
+      }
+
+      const declared = owner.surfaces?.[surface];
+      if (!declared) return own;
+      if (!declared.some((n) => n.toLowerCase() === entity.toLowerCase())) return undefined;
+      if (own) return own;
+
+      const fallback = facadeAt(facadeKeyOf(entity), false);
+      return fallback
+        ? facadeOperations(
+            localDispatcher,
+            entity,
+            routeRegistry.operationNames(entity, surface),
+            surface,
+          )
+        : undefined;
+    };
+
+    if (remoteRouter) {
+      const remoteFacades = new Map<string, Record<string, Function>>();
+      routeRegistry.addResolver(remoteRoutes((entity) => {
+        const known = remoteFacades.get(entity);
+        if (known) return known;
+        const facade = createRemoteFacade(entity, remoteRouter, getMiddlewares);
+        remoteFacades.set(entity, facade);
+        return facade;
+      }));
     }
-  };
 
-  const app: App = {
-    container,
-    fronds,
-    // What this app publishes, straight from fougere.config.ts — the doors read it,
-    // so an undeclared adapter serves nothing whatever a host mounted.
-    adapters: options.adapters ?? {},
-    // Where a call goes, as DECLARED. Kept because a reader needs it beside what the
-    // runtime OBSERVED — `rpc.topology` calls a frond remote because it answered, never
-    // because a key said so, and the two disagree exactly when something is misconfigured.
-    remotes: Object.freeze({ ...(options.remotes ?? {}) }),
-    dispatch: (call) => dispatcher.dispatch(call),
-    local: localDispatcher,
-    resolve,
-    schemaFor,
-    facadeFor,
-    operationsFor,
-    listensTo: () => emissions.listensTo(),
-    deliver: (fact, payload) => emissions.deliver(fact, payload),
-    storageFor,
-    presenterFor,
-    dispose: release,
-    drain,
-    inFlight: () => inflight.count,
-    [Symbol.asyncDispose]: release,
-    serveRpc(op: string, answer: RpcAnswer): void {
-      // Refused rather than replaced: two declarations of one name would make the answer
-      // depend on wiring order, and `discover` is in here precisely so it cannot be taken.
-      const address = new RouteAddress({ entity: 'rpc', operation: op });
-      if (routeRegistry.find(address)) {
-        throw new Error(`rpc operation '${op}' is already served; a second declaration would depend on wiring order`);
+    /** The terms beside a door, with the exact same named-surface fallback rule. */
+    const operationsFor = (entity: string, surface?: string): EffectiveOperationsMap | undefined => {
+      if (!surface) return effectiveByKey.get(facadeKeyOf(entity));
+
+      const own = effectiveByKey.get(facadeKeyOf(entity, surface));
+      const declared = fronds.owner(entity)?.surfaces?.[surface];
+      if (!declared) return own;
+      return declared.some((name) => name.toLowerCase() === entity.toLowerCase())
+        ? (own ?? effectiveByKey.get(facadeKeyOf(entity)))
+        : undefined;
+    };
+
+    /**
+     * The storage an entity is backed by — the dual of `facadeFor`, which serves its client-facing
+     * door.
+     */
+    const storageFor = (entity: string): unknown | undefined => {
+      const owner = fronds.owner(entity);
+      if (!owner) return undefined;
+
+      const key = storageKeyOf(entity);
+      try {
+        return container.resolve<Container>(`frond:${owner.name}`).resolve(key);
+      } catch {
+        return undefined;
       }
-      routeRegistry.register(new OperationRoute(
-        'system',
-        address,
-        (call) => answer(call.invocation, call.address.surface),
-      ));
-    },
-    extensions: () => appLifecycle.names(),
-    observe(observer) {
-      return dispatchLifecycle.add(observer);
-    },
-    use(...args: [AppMiddleware] | [string, AppMiddleware]): void {
-      if (typeof args[0] === 'string') {
-        const [entity, mw] = args as [string, AppMiddleware];
-        const list = scopedMiddlewares.get(entity) ?? [];
-        list.push(mw);
-        scopedMiddlewares.set(entity, list);
-      } else {
-        globalMiddlewares.push(args[0] as AppMiddleware);
+    };
+
+    /** 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;
+
+      try {
+        return container.resolve<Container>(`frond:${owner.name}`).resolve(presenterKeyOf(entity));
+      } catch {
+        return undefined;
       }
-    },
-    auth: authRuntime,
-  };
+    };
 
-  // The card is an rpc op like any other, so one registry answers and one refusal names
-  // what is served. A package's op is declared the same way, from outside.
-  app.serveRpc('discover', (_invocation, surface) => identityCardOf(app, surface));
+    const app: App = {
+      container,
+      fronds,
+      // What this app publishes, straight from fougere.config.ts — the doors read it,
+      // so an undeclared adapter serves nothing whatever a host mounted.
+      adapters: options.adapters ?? {},
+      // Where a call goes, as DECLARED. Kept because a reader needs it beside what the
+      // runtime OBSERVED — `rpc.topology` calls a frond remote because it answered, never
+      // because a key said so, and the two disagree exactly when something is misconfigured.
+      remotes: Object.freeze({ ...(options.remotes ?? {}) }),
+      dispatch: (call) => dispatcher.dispatch(call),
+      local: localDispatcher,
+      resolve,
+      schemaFor,
+      facadeFor,
+      operationsFor,
+      listensTo: () => emissions.listensTo(),
+      deliver: (fact, payload) => emissions.deliver(fact, payload),
+      storageFor,
+      presenterFor,
+      dispose: release,
+      drain,
+      inFlight: () => inflight.count,
+      [Symbol.asyncDispose]: release,
+      serveRpc(op: string, answer: RpcAnswer): void {
+        // Refused rather than replaced: two declarations of one name would make the answer
+        // depend on wiring order, and `discover` is in here precisely so it cannot be taken.
+        const address = new RouteAddress({ entity: 'rpc', operation: op });
+        if (routeRegistry.find(address)) {
+          throw new Error(`rpc operation '${op}' is already served; a second declaration would depend on wiring order`);
+        }
+        routeRegistry.register(new OperationRoute(
+          'system',
+          address,
+          (call) => answer(call.invocation, call.address.surface),
+        ));
+      },
+      extensions: () => appLifecycle.names(),
+      observe(observer) {
+        return dispatchLifecycle.add(observer);
+      },
+      use(...args: [AppMiddleware] | [string, AppMiddleware]): void {
+        if (typeof args[0] === 'string') {
+          const [entity, mw] = args as [string, AppMiddleware];
+          const list = scopedMiddlewares.get(entity) ?? [];
+          list.push(mw);
+          scopedMiddlewares.set(entity, list);
+        } else {
+          globalMiddlewares.push(args[0] as AppMiddleware);
+        }
+      },
+      auth: authRuntime,
+    };
 
-  // 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.
-  //
-  // 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 {
+    // The card is an rpc op like any other, so one registry answers and one refusal names
+    // what is served. A package's op is declared the same way, from outside.
+    app.serveRpc('discover', (_invocation, surface) => identityCardOf(app, surface));
+
+    // 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.
+    built = app;
     await appLifecycle.up(app);
+
+    return app;
   } catch (cause) {
+    // The caller cannot release what a failed boot took: it handed `onDispose` over before
+    // this call and never receives the app that would carry it back. Whoever opened a
+    // connection to give us would otherwise leak it on every refusal — a source, a scan
+    // that threw, a port bound twice, and not only an extension that refused to rise.
     try {
       await release();
     } catch (refused) {
@@ -808,6 +522,4 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     }
     throw cause;
   }
-
-  return app;
-}
+}