@fougere/core 0.10.0-alpha.0 → 0.12.0-alpha.0

package/src/boot/bootstrap.ts

@@ -1,10 +1,18 @@
-import type { Container } from '@fougere/container';
+import { createContainer, type Container } from '@fougere/container';
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 
 import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
 import type { PresenterEntry } from '../descriptor/PresenterEntry.js';
 import { hostedBy } from './hosted.js';
+import { nestingOf, parentsFirst } from './nesting.js';
+import type { Fronds } from '../descriptor/Fronds.js';
 import { installFrond, type Assembly } from './install.js';
+import { dependentsOf, releasing, unfinishable, unheldAmong } from './relations.js';
+import { release as releaseRow } from '../dispatch/Release.js';
+import type { Hosting } from './Hosting.js';
+import { peerOver } from './peerOver.js';
+import { JOURNAL, type Journal } from '../dispatch/Journal.js';
+import type { RelationCheck } from '../dispatch/RelationCheck.js';
 import { refusalOf, type Diagnostic } from '../diagnostic.js';
 import type { AuthRuntime } from './AuthRuntime.js';
 import type { App } from './App.js';
@@ -19,18 +27,20 @@ import { emitKeyOf, type Emit } from '../wire/Emit.js';
 /** The fact the boot announces, spelled once. */
 const LOG_LINE = lowerFirst(LogLine.name);
 import { Config } from '../builtin/config.js';
-import { createRemoteRouter, createRemoteFacade } from './remote.js';
+import { createRemoteRouter, createRemoteFacade, type RemoteRouter } from './remote.js';
+import type { Peer } from './Peer.js';
 
 import { Emissions } from './Emissions.js';
 
 import type { OperationContract } from '../wire/OperationContract.js';
 import type { OperationsMap } from '../wire/OperationsMap.js';
-import { resolveEffectiveOperations } from '../EffectiveOperationModel.js';
+import { resolveEffectiveOperations, type EffectiveOperationModel } from '../EffectiveOperationModel.js';
 import { type EffectiveOperationsMap } from '../EffectiveOperationsMap.js';
 
 import { InFlight } from '../dispatch/InFlight.js';
 // The keys, each read from where its concept is declared — never respelled here.
-import { type RpcAnswer } from '../wire/RpcAnswer.js';
+import { RPC_ENTITY, type RpcAnswer } from '../wire/RpcAnswer.js';
+import { Invocation } from '../wire/Invocation.js';
 import { facadeKeyOf } from '../wire/Facade.js';
 import { identityCardOf } from './card.js';
 import { AppLifecycle, migrating } from './AppLifecycle.js';
@@ -93,9 +103,463 @@ function keyClaims(
   }
 }
 
+/**
+ * What this app hosts, and what its operations effectively are.
+ *
+ * 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.
+ */
+async function readFronds(
+  options: CreateAppOptions,
+  log: Logger,
+): Promise<{ fronds: Fronds; operationModel: EffectiveOperationModel }> {
+  const scanStart = performance.now();
+  // An extension's fronds sit beside the app's own: it is installed like any other, and
+  // its handlers resolve at call time — by which point the extension's `up` has put what
+  // they ask for in the container.
+  const brought = (options.extensions ?? [])
+    .flatMap((extension) => extension?.fronds ?? [])
+    .map((frond) => ({ ...frond, brought: true as const }));
+  const { fronds, diagnostics } = await hostedBy(
+    brought.length > 0 ? { ...options, fronds: [...(options.fronds ?? []), ...brought] } : 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 && brought.length === 0) {
+    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.\n'
+      + '    createApp({ fronds: [blog] })\n'
+      + '    createApp({ scan: await scanProject(root) })',
+    );
+  }
+
+  const { under, refused } = nestingOf(options.under, fronds, options.remotes, options.narrowed);
+  const refusal = refusalOf(refused, 'thing(s) the frond tree does not allow');
+  if (refusal) throw refusal;
+
+  for (const frond of fronds) {
+    const parent = under.get(frond.name);
+    if (parent !== undefined) frond.extends = parent;
+  }
+  const ordered = parentsFirst(fronds, under);
+
+  const operationModel = resolveEffectiveOperations(ordered, {
+    diagnostics,
+    remotes: options.remotes,
+    adapters: options.adapters,
+  });
+  const scanMs = (performance.now() - scanStart).toFixed(0);
+  log.info(`read ${ordered.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 diagnostics.filter((one) => one.severity === '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 unresolved = refusalOf(operationModel.resolutionDiagnostics, 'unresolved operation contract(s)');
+  if (unresolved) throw unresolved;
+
+  return { fronds: ordered, operationModel };
+}
+
+/**
+ * What core answers under `rpc`, in every process, whatever fronds it carries.
+ *
+ * All four read the STORAGE and never a facade: a facade answers what its handler chose to show,
+ * so `PostHandler.list` hiding drafts would hide exactly the row the question exists to find.
+ */
+function serveCoreRpc(
+  app: App,
+  hosting: Hosting,
+  storageFor: (entity: string) => unknown | undefined,
+): void {
+  app.serveRpc('discover', (_invocation, surface) => identityCardOf(app, surface));
+
+  app.serveRpc('holds', async (invocation) => {
+    const named = String(invocation.params.entity);
+    const keys = (invocation.params.keys ?? []) as readonly unknown[];
+    const rows = storageFor(named) as { findByKeys(k: readonly string[]): Promise<Map<string, unknown>> } | undefined;
+    if (!rows) return { missing: [] };
+    const found = await rows.findByKeys(keys.map(String));
+
+    return { missing: keys.filter((key) => !found.has(String(key))) };
+  });
+
+  app.serveRpc('dependents', (invocation) => dependentsOf(String(invocation.params.entity), hosting));
+
+  app.serveRpc('release', async (invocation) => {
+    await releaseRow(String(invocation.params.entity), invocation.params.key, releasing(hosting),
+      (invocation.params.visited ?? []) as readonly string[]);
+
+    return { released: true };
+  });
+}
+
+/**
+ * What no single frond can see about a `ref()`, so it is said once every frond is installed.
+ *
+ * A target belongs to another frond, and a journal arrives with an extension, which rises last.
+ */
+function warnAboutRelations(relations: RelationCheck[], hosting: Hosting, log: Logger): void {
+  const unfinished = unfinishable(hosting);
+  if (unfinished.length > 0) {
+    log.warn(
+      `[relations] ${unfinished.join(', ')} — declared, and this process keeps nothing on `
+      + 'restart: a release interrupted here is not resumed. Install @fougere/workflow, or '
+      + 'expect to finish one by hand.',
+    );
+  }
+
+  const unheld = unheldAmong(relations, hosting);
+  if (unheld.length > 0) {
+    log.warn(
+      `[relations] ${unheld.join(', ')} — declared, and nothing in this process holds them: `
+      + 'no foreign key, and the target answers elsewhere. A row may name one that is gone.',
+    );
+  }
+}
+
+/** The process that serves an entity, asked the three questions a release travels on. */
+function peerBehind(entity: string, router: RemoteRouter): Peer {
+  const ask = async (op: string, params: Record<string, unknown>): Promise<unknown> =>
+    (await router.route(entity)).transport(
+      { entity: RPC_ENTITY, op },
+      { ...Invocation.empty, params: params as never },
+    );
+
+  return {
+    dependents: async (named) => await ask('dependents', { entity: named }) as never,
+    missing: async (named, keys) =>
+      (await ask('holds', { entity: named, keys }) as { missing: readonly unknown[] }).missing,
+    release: async (named, key) => { await ask('release', { entity: named, key }); },
+  };
+}
+
+/** Close the door, and answer once the calls already running are done. */
+async function drainCalls(inflight: InFlight, 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,
+      );
+    }),
+  ]);
+}
+
+/** What a call goes through in this process, before any frond is installed into it. */
+interface Dispatching {
+  /** Counted at the one facade every caller goes through, so releasing can wait for the work. */
+  inflight: InFlight;
+  /** Where a late observer is added — `App.observe` is its only caller. */
+  dispatchLifecycle: DispatchLifecycle;
+  routeRegistry: RouteRegistry;
+  /** Follows the topology — a local façade and a remote doublure alike. */
+  dispatcher: Dispatcher;
+  /** Stays home: what this process serves, and nothing else. */
+  localDispatcher: Dispatcher;
+  getMiddlewares(entity: string): AppMiddleware[];
+  /** The one place a middleware is taken on — `App.use` is its late form, a frond's directory its early one. */
+  use(middleware: AppMiddleware, entity?: string): void;
+}
+
+function dispatching(
+  options: CreateAppOptions,
+  log: Logger,
+  fronds: Fronds,
+  journalOf: () => Journal | undefined,
+): Dispatching {
+  const inflight = new InFlight();
+  const globalMiddlewares: AppMiddleware[] = [];
+  const scopedMiddlewares = new Map<string, AppMiddleware[]>();
+  const routeRegistry = new RouteRegistry();
+  const dispatchLifecycle = new DispatchLifecycle(
+    options.dispatchObservers,
+    (error, event) => log.error(
+      `[dispatch-observer] ${event.stage} ${event.call.address.toString()}`,
+      error,
+    ),
+  );
+
+  return {
+    inflight,
+    routeRegistry,
+    dispatchLifecycle,
+    // Resolved at the call and never here: a journal is a provider of a brought frond, and the
+    // extension that registers it rises long after this line.
+    dispatcher: new Dispatcher(routeRegistry, inflight, dispatchLifecycle, undefined, journalOf),
+    localDispatcher: new Dispatcher(
+      routeRegistry,
+      inflight,
+      dispatchLifecycle,
+      new LocalRoutePolicy((surface) => fronds.servedNames(surface)),
+      journalOf,
+    ),
+    getMiddlewares: (entity) => [...globalMiddlewares, ...(scopedMiddlewares.get(entity) ?? [])],
+    use(middleware, entity) {
+      if (entity === undefined) {
+        globalMiddlewares.push(middleware);
+
+        return;
+      }
+
+      scopedMiddlewares.set(entity, [...(scopedMiddlewares.get(entity) ?? []), middleware]);
+    },
+  };
+}
+
+/** Every entity of every frond, who holds it, and the door a fact goes through. */
+function whatTheAppKnows(
+  fronds: Fronds,
+  container: Container,
+  options: CreateAppOptions,
+  refused: Diagnostic[],
+): { entityByName: Map<string, SchemaView>; frondOf: Map<string, string>; emissions: Emissions } {
+  // By name, so a fact can be validated where it LANDS and a `reads:` clause can name a
+  // neighbour's entity.
+  const entityByName = fronds.schemas();
+  // The line is core's, so its SHAPE is too: a destination that declares only a handler would
+  // otherwise be handed a line with no `at` — the announcement stamps `created()` off the shape,
+  // and the strict judge refuses what it did not stamp. Measured on `demos/observability`, where
+  // the ring held 11 calls and 0 lines.
+  if (!entityByName.has(LOG_LINE)) entityByName.set(LOG_LINE, LogLine);
+
+  return {
+    entityByName,
+    // What turns "a member is remote" into a refusal that names the FROND rather than the
+    // entity, since `remotes:` is declared per frond.
+    frondOf: new Map(fronds.flatMap((one) => one.entities.map((entity) => [entity.name, one.name] as const))),
+    emissions: new Emissions(
+      fronds, entityByName, container,
+      // No carry: this is what CARRIES a fact, and a line about carrying one comes back here.
+      new Logger('boot:app'),
+      refused,
+      options.onEmit,
+    ),
+  };
+}
+
+/** What every check of the boot asks about where a row lives, and who else might hold one. */
+interface Hosted {
+  fronds: Fronds;
+  container: Container;
+  options: CreateAppOptions;
+  declaredRemotes: [string, string][];
+  remoteRouter: RemoteRouter | undefined;
+  entityByName: Map<string, SchemaView>;
+  frondOf: Map<string, string>;
+  storageOf: (entity: string) => unknown | undefined;
+}
+
+function hostingFor(
+  { fronds, container, options, declaredRemotes, remoteRouter, entityByName, frondOf, storageOf }: Hosted,
+): { hosting: Hosting; journalOf: () => Journal | undefined } {
+  // What carries a release writes none: an instrumentation frond's own rows are kept while a
+  // release happens, and journalling them would begin one inside the one being written down.
+  const carriesRelease = new Set(
+    fronds.filter((one) => one.brought).flatMap((one) => one.entities.map((entity) => entity.name)),
+  );
+
+  /**
+   * The journal a package registered, found where its own frond put it — a provider lands in its
+   * frond's scope, and the app container sees none of them. Resolved per call and never at boot:
+   * the package that registers it rises in the ascent, long after this answer is built.
+   */
+  const journalOf = (): Journal | undefined => {
+    for (const frond of fronds) {
+      if (!frond.brought) continue;
+      const scope = container.resolve<Container>(`frond:${frond.name}`);
+      if (scope.has(JOURNAL)) return scope.resolve<Journal>(JOURNAL);
+    }
+
+    return undefined;
+  };
+
+  const hosting: Hosting = {
+    hostedHere: (entity) => !(options.remotes && (frondOf.get(entity) ?? '') in options.remotes),
+    sourceOf: (name) => options.sourceOf?.(name) ?? 'db',
+    enforces: (source, constraint) => options.enforces?.(source, constraint) ?? false,
+    storageOf,
+    entities: () => entityByName,
+    journal: (entity) => (carriesRelease.has(entity) ? undefined : journalOf()),
+    // Built from `remotes:` itself and not from the router: the router indexes by ENTITY, read
+    // off a card, while the question here is asked of a PROCESS about rows it may be alone in
+    // knowing about. Nothing is cached — a peer that was down at boot answers the next call.
+    peers: () => (options.remoteTransport
+      ? declaredRemotes.map(([, url]) => peerOver(options.remoteTransport!(url)))
+      : []),
+    peerOf: (entity) => (remoteRouter ? peerBehind(entity, remoteRouter) : undefined),
+  };
+
+  return { hosting, journalOf };
+}
+
+/** What the readings below are built from — every one of them answers about a SERVED entity. */
+interface Serving {
+  container: Container;
+  fronds: Fronds;
+  remoteRouter: RemoteRouter | undefined;
+  localDispatcher: Dispatcher;
+  routeRegistry: RouteRegistry;
+  effectiveByKey: Map<string, EffectiveOperationsMap>;
+  log: Logger;
+}
+
+/**
+ * What an app answers about what it serves — the membership rule and its neighbours.
+ *
+ * `facadeFor` is THE rule, stated once: every projection reads it and nothing else.
+ */
+function readings(
+  { container, fronds, remoteRouter, localDispatcher, routeRegistry, effectiveByKey, log }: Serving,
+): Pick<App, 'resolve' | 'schemaFor' | 'facadeFor' | 'operationsFor' | 'presenterFor'> {
+  /** Stop taking calls, and resolve once the ones already running are done. */
+  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 facade 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 facade 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 facades, 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 facades at the first call, not at boot. '
+      + 'The default facade 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;
+  };
+
+  /** The terms beside a facade, 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 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;
+    }
+  };
+
+  return { resolve, schemaFor, facadeFor, operationsFor, presenterFor };
+}
+
+/**
+ * Built once from the lazy `AuthConfig` a provider factory produced (`betterAuth({…})` in
+ * fougere.config.ts). The provider receives our db and storage factory, so every auth write
+ * flows through `Storage` like any other.
+ */
+async function authFor(options: CreateAppOptions, log: Logger): Promise<AuthRuntime | undefined> {
+  if (!options.auth) return undefined;
+
+  if (!options.storageFactory) {
+    throw new Error('createApp: `auth` is set but `storageFactory` is missing — auth providers need it to back their adapter. Pass one through CreateAppOptions.storageFactory.');
+  }
+  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');
+  const runtime = await options.auth.create({ db: options.db, storageFactory: options.storageFactory });
+  log.info(`auth ready — mounted at ${runtime.basePath}`);
+
+  return runtime;
+}
+
 /** Bootstrap a fougere application. */
 export async function createApp(options: CreateAppOptions): Promise<App> {
-  const container = options.createContainer();
+  const container = (options.createContainer ?? createContainer)();
 
   // 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.
@@ -160,67 +624,9 @@ export async function createApp(options: CreateAppOptions): Promise<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();
-    // An extension's fronds sit beside the app's own: it is installed like any other, and
-    // its handlers resolve at call time — by which point the extension's `up` has put what
-    // they ask for in the container.
-    const brought = (options.extensions ?? [])
-      .flatMap((extension) => extension?.fronds ?? [])
-      .map((frond) => ({ ...frond, brought: true as const }));
-    const { fronds, diagnostics } = await hostedBy(
-      brought.length > 0 ? { ...options, fronds: [...(options.fronds ?? []), ...brought] } : 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 && brought.length === 0) {
-      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.\n'
-        + '    createApp({ fronds: [blog] })\n'
-        + '    createApp({ scan: await scanProject(root) })',
-      );
-    }
-    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 unresolved = refusalOf(operationModel.resolutionDiagnostics, 'unresolved operation contract(s)');
-    if (unresolved) throw unresolved;
-
-    // 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. Pass one through CreateAppOptions.storageFactory.');
-      }
-      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}`);
-    }
+    const { fronds, operationModel } = await readFronds(options, log);
+
+    const authRuntime = await authFor(options, log);
 
     // 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
@@ -235,77 +641,20 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       ? createRemoteRouter(Object.fromEntries(declaredRemotes), options.remoteTransport)
       : undefined;
 
-    // What is running on this app — counted at the one facade 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)),
-    );
-
-    function getMiddlewares(entity: string): AppMiddleware[] {
-      const scoped = scopedMiddlewares.get(entity) ?? [];
-      return [...globalMiddlewares, ...scoped];
-    }
-
-    /**
-     * The one place a middleware is taken on. `App.use` is its late form, and a frond's
-     * `middlewares/` its early one — the app does not exist yet while fronds install.
-     */
-    function use(middleware: AppMiddleware, entity?: string): void {
-      if (entity === undefined) {
-        globalMiddlewares.push(middleware);
-        return;
-      }
-      const scoped = scopedMiddlewares.get(entity) ?? [];
-      scoped.push(middleware);
-      scopedMiddlewares.set(entity, scoped);
-    }
+    const { inflight, routeRegistry, dispatchLifecycle, dispatcher, localDispatcher, getMiddlewares, use } =
+      dispatching(options, log, fronds, () => journalOf());
 
     /** What every check of this boot writes into — refused together, once they have all run. */
     const refused: Diagnostic[] = [];
+    const relations: RelationCheck[] = [];
     keyClaims(fronds, options.remotes, refused);
     // Said before anything is installed: a key claimed twice makes every later error worse —
     // the route registry collides first, and names a route instead of the two fronds.
     const claimed = refusalOf(refused, 'declaration(s) that do not hold');
     if (claimed) throw claimed;
 
-    // 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();
-    // The line is core's, so its SHAPE is too: a destination that declares only a handler
-    // would otherwise be handed a line with no `at` — the announcement stamps `created()`
-    // off the shape, and the strict judge refuses what it did not stamp. Measured on
-    // `demos/observability`, where the ring held 11 calls and 0 lines.
-    if (!entityByName.has(LOG_LINE)) entityByName.set(LOG_LINE, LogLine);
-    // 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)));
-    // Its own writer, which does NOT announce: this is what carries a fact, and a line
-    // about carrying one would come back here. See `LoggerOptions.carries`.
-    const emissions = new Emissions(
-      fronds, entityByName, container,
-      // No carry: this is what CARRIES a fact, and a line about carrying one comes back.
-      new Logger('boot:app'),
-      refused,
-      options.onEmit,
-    );
+    const { entityByName, frondOf, emissions } = whatTheAppKnows(fronds, container, options, refused);
+
     /** Canonical operation tables, indexed by the same audience key as their facades. */
     const effectiveByKey = new Map<string, EffectiveOperationsMap>();
 
@@ -313,6 +662,28 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       [...operations].map(([name, operation]) => [name, operation as OperationContract] as const),
     );
 
+    /**
+     * The storage an entity is backed by — the dual of `facadeFor`, which serves its client-facing
+     * facade.
+     */
+    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;
+      }
+    };
+
+    // What carries a release writes none: an instrumentation frond's own rows are kept while a
+    // release happens, and journalling them would begin one inside the one being written down.
+    const { hosting, journalOf } = hostingFor({
+      fronds, container, options, declaredRemotes, remoteRouter, entityByName, frondOf, storageOf: storageFor,
+    });
+
     // 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>();
@@ -322,11 +693,13 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     // 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, refused, operationModel, entityByName, frondOf, contractsOf, getMiddlewares, use,
-      log, options,
+      boundPorts, refused, relations, hosting, operationModel, entityByName, frondOf, contractsOf,
+      getMiddlewares, use, middlewaresOf: new Map(), seamsOf: new Map(), log, options,
     };
     for (const frond of fronds) await installFrond(frond, assembly);
 
+    warnAboutRelations(relations, hosting, log);
+
     // Every check of the install, said at once — a boot that stops at the first makes the
     // next one visible only after a fix and a restart.
     const bootRefusal = refusalOf(refused, 'declaration(s) that do not hold');
@@ -372,106 +745,6 @@ 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;
-      }
-    };
-
-    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 facade 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 facade 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 facades, 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 facades at the first call, not at boot. '
-        + 'The default facade 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) => {
@@ -483,45 +756,9 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       }));
     }
 
-    /** The terms beside a facade, 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
-     * facade.
-     */
-    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;
-      }
-    };
-
-    /** 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;
-      }
-    };
+    const { resolve, schemaFor, facadeFor, operationsFor, presenterFor } = readings({
+      container, fronds, remoteRouter, localDispatcher, routeRegistry, effectiveByKey, log,
+    });
 
     const app: App = {
       container,
@@ -544,7 +781,7 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       storageFor,
       presenterFor,
       dispose: release,
-      drain,
+      drain: (timeoutMs?: number) => drainCalls(inflight, timeoutMs),
       inFlight: () => inflight.count,
       [Symbol.asyncDispose]: release,
       serveRpc(op: string, answer: RpcAnswer): void {
@@ -577,7 +814,11 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
 
     // 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));
+    // What a release is, resolved once and registered: a package that drives one asks for it
+    // by type, the way every other dependency is asked for.
+    container.registerValue('Releasing', releasing(hosting));
+
+    serveCoreRpc(app, hosting, storageFor);
 
     // 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.