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

package/dist/boot/bootstrap.js

@@ -1,28 +1,18 @@
 import { lowerFirst } from '@fougere/schema';
-import { nameOf } from '../descriptor/frond.js';
 import { hostedBy } from './hosted.js';
+import { installFrond } from './install.js';
 import { Logger } from '../builtin/logger.js';
 import { Config } from '../builtin/config.js';
 import { createRemoteRouter, createRemoteFacade } from './remote.js';
-import { registerFrames } from './together.js';
 import { Emissions } from './Emissions.js';
-import { HandlerFacade } from '../dispatch/HandlerFacade.js';
-import { targetOf } from '../prefab/prefab.js';
-import { ownersOf, refuseStorageInUserCode, refuseCrudOnOwned } from './ownership.js';
 import { resolveEffectiveOperations, } from '../effective-operation.js';
-import { StorageGuard } from '../dispatch/StorageGuard.js';
-import { portBindings } from './ports.js';
 import { InFlight } from '../dispatch/InFlight.js';
 // The keys, each read from where its concept is declared — never respelled here.
-import { facadeKeyOf, contractsKeyOf } from '../wire/call.js';
+import { facadeKeyOf } from '../wire/call.js';
 import { identityCardOf } from './card.js';
 import { AppLifecycle } from './AppLifecycle.js';
-import { inheritsCrud, subjectOf } from '../prefab/crud.js';
-import { repositoryKeyOf } from '../prefab/repository.js';
-import { storageKeyOf } from '../storage.js';
-import { declares } from '../source.js';
+import { storageKeyOf } from '../storage/port.js';
 import { presenterKeyOf } from '../prefab/presenter.js';
-import { collectorKeyOf } from '../prefab/collector.js';
 import { RouteAddress } from '../wire/RouteAddress.js';
 import { DispatchLifecycle } from '../dispatch/DispatchLifecycle.js';
 import { Dispatcher } from '../dispatch/Dispatcher.js';
@@ -60,418 +50,11 @@ function assertOneOwnerPerKey(fronds, remotes) {
 /** Bootstrap a fougere application. */
 export async function createApp(options) {
     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;
-    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 = [];
-    const scopedMiddlewares = new Map();
-    /** 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) {
-        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])));
-    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();
-    const contractsOf = (operations) => new Map([...operations].map(([name, operation]) => [name, operation]));
-    // 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();
-    // 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 !== 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 = [];
-            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?.__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, handler, targetScope, facadeKey) => {
-            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([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;
-            container.registerValue(presenterKey, new Proxy({}, {
-                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)).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.__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.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)).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))].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;
     /**
      * Everything this app holds, let go in reverse of how it was taken: what an extension took on
      * last, then the container's own, then whoever handed a resource in.
@@ -482,7 +65,12 @@ export async function createApp(options) {
         // 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 = [];
-        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();
             }
@@ -499,187 +87,344 @@ export async function createApp(options) {
             throw new AggregateError(refused, `${refused.length} refusal(s) while releasing the app`);
         }
     };
-    /** Stop taking calls, and resolve once the ones already running are done. */
-    const drain = async (timeoutMs) => {
-        inflight.close();
-        if (timeoutMs === undefined)
-            return inflight.whenIdle();
-        let timer;
-        await Promise.race([
-            inflight.whenIdle().then(() => clearTimeout(timer)),
-            new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`[drain] ${inflight.count} call(s) still running after ${timeoutMs}ms`)), timeoutMs);
-            }),
-        ]);
-    };
-    const resolve = (name) => {
-        try {
-            return container.resolve(name);
-        }
-        catch (err) {
-            if (name.endsWith('Handler') && !name.includes(':') && !remoteRouter) {
-                throw new Error(notLoaded(name.replace(/Handler$/, '')));
+    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'));
+        }
+        // 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;
+        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.');
             }
-            throw err;
-        }
-    };
-    const schemaFor = async (entity) => {
-        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.`);
+            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;
-        }
-        throw new Error(notLoaded(entity));
-    };
-    const facadeAt = (key, topology) => {
-        try {
-            return topology
-                ? resolve(key)
-                : container.resolve(key);
+            log.info('initializing auth runtime');
+            authRuntime = await options.auth.create({
+                db: options.db,
+                storageFactory: options.storageFactory,
+            });
+            log.info(`auth ready — mounted at ${authRuntime.basePath}`);
         }
-        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, surface) => {
-        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();
-        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;
-        }));
-    }
-    /** The terms beside a door, with the exact same named-surface fallback rule. */
-    const operationsFor = (entity, surface) => {
-        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) => {
-        const owner = fronds.owner(entity);
-        if (!owner)
-            return undefined;
-        const key = storageKeyOf(entity);
-        try {
-            return container.resolve(`frond:${owner.name}`).resolve(key);
-        }
-        catch {
-            return undefined;
-        }
-    };
-    /** The presenter of an entity, resolved through its owning frond's scope. */
-    const presenterFor = (entity) => {
-        const owner = fronds.owner(entity);
-        if (!owner)
-            return undefined;
-        try {
-            return container.resolve(`frond:${owner.name}`).resolve(presenterKeyOf(entity));
-        }
-        catch {
-            return 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 = [];
+        const scopedMiddlewares = new Map();
+        /** 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) {
+            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])));
+        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();
+        const contractsOf = (operations) => new Map([...operations].map(([name, operation]) => [name, operation]));
+        // 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();
+        // 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 = {
+            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.');
+        }
+        // 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$/, '')));
+        });
+        /** Stop taking calls, and resolve once the ones already running are done. */
+        const drain = async (timeoutMs) => {
+            inflight.close();
+            if (timeoutMs === undefined)
+                return inflight.whenIdle();
+            let timer;
+            await Promise.race([
+                inflight.whenIdle().then(() => clearTimeout(timer)),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`[drain] ${inflight.count} call(s) still running after ${timeoutMs}ms`)), timeoutMs);
+                }),
+            ]);
+        };
+        const resolve = (name) => {
+            try {
+                return container.resolve(name);
+            }
+            catch (err) {
+                if (name.endsWith('Handler') && !name.includes(':') && !remoteRouter) {
+                    throw new Error(notLoaded(name.replace(/Handler$/, '')));
+                }
+                throw err;
+            }
+        };
+        const schemaFor = async (entity) => {
+            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, topology) => {
+            try {
+                return topology
+                    ? resolve(key)
+                    : container.resolve(key);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        /** Said once per pair, so a door that registers in a loop says it once. */
+        const saidAbsent = new Set();
+        /**
+         * 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, surface) => {
+            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, surface) => {
+            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();
+            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 = {
-        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, answer) {
-            // 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, surface) => {
+            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) => {
+            const owner = fronds.owner(entity);
+            if (!owner)
+                return undefined;
+            const key = storageKeyOf(entity);
+            try {
+                return container.resolve(`frond:${owner.name}`).resolve(key);
             }
-            routeRegistry.register(new OperationRoute('system', address, (call) => answer(call.invocation, call.address.surface)));
-        },
-        extensions: () => appLifecycle.names(),
-        observe(observer) {
-            return dispatchLifecycle.add(observer);
-        },
-        use(...args) {
-            if (typeof args[0] === 'string') {
-                const [entity, mw] = args;
-                const list = scopedMiddlewares.get(entity) ?? [];
-                list.push(mw);
-                scopedMiddlewares.set(entity, list);
+            catch {
+                return undefined;
             }
-            else {
-                globalMiddlewares.push(args[0]);
+        };
+        /** The presenter of an entity, resolved through its owning frond's scope. */
+        const presenterFor = (entity) => {
+            const owner = fronds.owner(entity);
+            if (!owner)
+                return undefined;
+            try {
+                return container.resolve(`frond:${owner.name}`).resolve(presenterKeyOf(entity));
             }
-        },
-        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));
-    // 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 {
+            catch {
+                return undefined;
+            }
+        };
+        const 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, answer) {
+                // 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) {
+                if (typeof args[0] === 'string') {
+                    const [entity, mw] = args;
+                    const list = scopedMiddlewares.get(entity) ?? [];
+                    list.push(mw);
+                    scopedMiddlewares.set(entity, list);
+                }
+                else {
+                    globalMiddlewares.push(args[0]);
+                }
+            },
+            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));
+        // 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();
         }
@@ -688,6 +433,5 @@ export async function createApp(options) {
         }
         throw cause;
     }
-    return app;
 }
 //# sourceMappingURL=bootstrap.js.map