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

package/src/{source.ts → Source.ts}

@@ -1,8 +1,8 @@
 import { Registry, Role, type SchemaView } from '@fougere/schema';
-import type { StorageFactory } from './storage/port.js';
-
-/** A promise the judge at the door cannot keep, because it is about rows it never sees. */
-export type Constraint = 'unique';
+import type { StorageFactory } from './storage/StorageFactory.js';
+import type { Constraint } from './Constraint.js';
+import type { SourceView } from './SourceView.js';
+import type { SourceConfig } from './SourceConfig.js';
 
 /** Whether an entity asks for one, anywhere but on its key. */
 export function declares(schema: SchemaView, constraint: Constraint): boolean {
@@ -36,23 +36,6 @@ export interface Source {
   name?: string;
 }
 
-/** The app as ONE source sees it. */
-export interface SourceView {
-  fronds: readonly { readonly name: string; readonly entities: readonly { readonly name: string }[] }[];
-  /** The auth provider's own entities, when they ride with this source. */
-  auth?: unknown;
-  elsewhere: readonly string[];
-}
-
-/** What a config file can carry about a source — values, never a live driver. */
-export interface SourceConfig {
-  /** The adapter that realizes it. Absent means the conventional one. */
-  source?: string;
-  /** The entities whose rows live here. Absent on the default source: it holds the rest. */
-  entities?: string[];
-  [key: string]: unknown;
-}
-
 /** Which adapter answers a source name — one per process, no subject to hold. */
 class SourceRegistry extends Registry<(conf: SourceConfig) => Source> {
   /** The source this name stands for, built from the config entry that named it. */

package/src/SourceConfig.ts

@@ -0,0 +1,10 @@
+import type { NameOf } from './NameOf.js';
+
+/** What a config file can carry about a source — values, never a live driver. */
+export interface SourceConfig {
+  /** The adapter that realizes it. Absent means the conventional one. */
+  source?: NameOf<'source'>;
+  /** The entities whose rows live here. Absent on the default source: it holds the rest. */
+  entities?: string[];
+  [key: string]: unknown;
+}

package/src/SourceView.ts

@@ -0,0 +1,7 @@
+/** The app as ONE source sees it. */
+export interface SourceView {
+  fronds: readonly { readonly name: string; readonly entities: readonly { readonly name: string }[] }[];
+  /** The auth provider's own entities, when they ride with this source. */
+  auth?: unknown;
+  elsewhere: readonly string[];
+}

package/src/VerifiedCall.ts

@@ -0,0 +1,7 @@
+/** What `verifyEnvelope` establishes — never what the caller asked for. */
+export interface VerifiedCall {
+  /** The frond that signed, as the root named it. */
+  caller: string;
+  /** The state it asserted, now proven to come from `caller`. */
+  state: Record<string, unknown>;
+}

package/src/boot/App.ts

@@ -0,0 +1,71 @@
+import type { Container } from '@fougere/container';
+import type { Fronds } from '../descriptor/Fronds.js';
+import type { SchemaView } from '@fougere/schema';
+import type { AppMiddleware } from '../wire/AppMiddleware.js';
+import type { RpcAnswer } from '../wire/RpcAnswer.js';
+import type { AuthRuntime } from './AuthRuntime.js';
+import type { EffectiveOperationsMap } from '../EffectiveOperationsMap.js';
+import type { DispatchObserver } from '../dispatch/DispatchObserver.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+
+/** The App object returned by createApp(). */
+export interface App extends DispatchPort {
+  /** Process-only dispatch capability used by incoming transports. */
+  local: DispatchPort;
+  /** Root container with builtins + frond scopes. */
+  container: Container;
+  /** Which protocol adapters this app declared, from `fougere.config.ts`. */
+  adapters: Record<string, boolean | undefined>;
+  /** Where a call goes, as the config declared it — frond name to address. */
+  remotes: Readonly<Record<string, string>>;
+  /** Discovered fronds metadata. */
+  fronds: Fronds;
+  /** Resolve from root container (shortcut). */
+  resolve<T>(name: string): T;
+  /**
+   * Resolve an entity's schema — the local `entityClass` when it's hosted or scanned here, else
+   * reconstructed from the remote's identity card (`rpc.discover` to `Card.toSchema`).
+   */
+  schemaFor(entity: string): Promise<SchemaView>;
+  /** The facade a name exposes to one audience, or `undefined` when it exposes none. */
+  facadeFor(entity: string, surface?: string): Record<string, Function> | undefined;
+  /**
+   * The canonical contracts served beside a facade, after prefab + scan + config, binding, kind,
+   * topology and surface resolution.
+   */
+  operationsFor(entity: string, surface?: string): EffectiveOperationsMap | undefined;
+  /** The facts this app has a listener for — what a carrier must subscribe to on its behalf. */
+  listensTo(): string[];
+  /** Hand a fact that came from OUTSIDE to the listeners in this process — and stop there. */
+  deliver(fact: string, payload: unknown): Promise<void>;
+  /**
+   * The storage an entity is backed by, resolved through its owning frond's scope — the dual of
+   * {@link facadeFor}.
+   */
+  storageFor(entity: string): unknown | undefined;
+  /** The presenter of an entity, resolved through its owning frond's scope. */
+  presenterFor(entity: string): unknown | undefined;
+  /** Dispose the root container. */
+  dispose(): Promise<void>;
+  /** Stop taking calls, and resolve once the running ones are done. */
+  drain(timeoutMs?: number): Promise<void>;
+  /** How many calls are running right now — one count for all three facades and the wire. */
+  inFlight(): number;
+  /** The same disposal, spelled so the language does it: `await using app = await createApp(…)`. */
+  [Symbol.asyncDispose](): Promise<void>;
+  /**
+   * What this app took on, in the order it will release them. The reading of
+   * `CreateAppOptions.extensions` after the boot resolved it.
+   */
+  extensions(): string[];
+  /** Declare one `rpc` op — what the app says about ITSELF, beside the card. */
+  serveRpc(operationName: string, answer: RpcAnswer): void;
+  /** Watch every dispatch transition; the returned function unsubscribes. */
+  observe(observer: DispatchObserver): () => void;
+  /** Register a global app middleware (runs on every operation). */
+  use(middleware: AppMiddleware): void;
+  /** Register an app middleware scoped to a specific entity. */
+  use(entity: string, middleware: AppMiddleware): void;
+  /** Auth runtime, present when fougere.config.ts declares `auth`. */
+  auth?: AuthRuntime;
+}

package/src/boot/AppLifecycle.ts

@@ -1,23 +1,5 @@
-import type { App } from './types.js';
-import type { FrondDescriptor } from '../descriptor/frond.js';
-
-/**
- * One process-level extension and its reversible lifecycle.
- *
- * Documented: [lifecycle](https://fougere.dev/docs/infra/lifecycle).
- */
-export interface Extension {
-  name: string;
-  /**
-   * Fronds it brings — read BEFORE the ascent, since a frond is installed while the app is
-   * still being made and `up` receives one that already exists. This is how an optional
-   * package accepts a fact: `calls` and `observability` both want every `LogLine`, and a
-   * signature is the only way to ask for one.
-   */
-  fronds?: readonly FrondDescriptor[];
-  up?(app: App): void | Promise<void>;
-  down?(app: App): void | Promise<void>;
-}
+import type { App } from './App.js';
+import type { Extension } from './Extension.js';
 
 /** Runs application extensions up in order and down in reverse order. */
 export class AppLifecycle {

package/src/boot/AuthConfig.ts

@@ -0,0 +1,14 @@
+import type { SchemaView } from '@fougere/schema';
+import type { AuthContext } from './AuthContext.js';
+import type { AuthRuntime } from './AuthRuntime.js';
+
+/** Lazy auth declaration written in fougere.config.ts. */
+export interface AuthConfig {
+  /** Build the runtime — invoked by createApp at boot with the resolved storage handles. */
+  create(ctx: AuthContext): AuthRuntime | Promise<AuthRuntime>;
+  /**
+   * Entities the provider will use. Optional metadata — useful for the core's
+   * future migration registry to know which tables auth needs.
+   */
+  entities?: Record<string, SchemaView>;
+}

package/src/boot/AuthContext.ts

@@ -0,0 +1,12 @@
+import type { StorageFactory } from '../storage/StorageFactory.js';
+
+/**
+ * Context passed by the core to an auth provider's create() function.
+ * Provides the resources the provider needs to integrate with the app.
+ */
+export interface AuthContext {
+  /** Storage handle (Kysely DB instance, Prisma client, etc.) — opaque to core. */
+  db: unknown;
+  /** Per-entity storage factory — auth provider uses this to back its adapter. */
+  storageFactory: StorageFactory;
+}

package/src/boot/AuthRuntime.ts

@@ -0,0 +1,19 @@
+import type { SchemaView } from '@fougere/schema';
+import type { Storage } from '../storage/Storage.js';
+
+/**
+ * Runtime returned by an auth provider's create(config, ctx) function.
+ * The core mounts this on the App and the HTTP layer (Nuxt module / router) uses it.
+ */
+export interface AuthRuntime {
+  /** Entities used by the provider, including any defaults it filled in. */
+  entities: Record<string, SchemaView>;
+  /** Per-entity ORMs the provider built for itself. */
+  storages: Record<string, Storage>;
+  /** Web Standard handler that processes /auth/* requests. */
+  handler: (request: Request) => Promise<Response>;
+  /** Programmatic API exposed by the provider (getSession, signOut, ...). */
+  api: Record<string, unknown>;
+  /** Effective mount path (echoes config.basePath or the provider's default). */
+  basePath: string;
+}

package/src/boot/CreateAppOptions.ts

@@ -0,0 +1,81 @@
+import type { Container } from '@fougere/container';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import type { ScanResult } from '../scan.js';
+import type { StorageFactory } from '../storage/StorageFactory.js';
+import type { Constraint } from '../Constraint.js';
+import type { Transport } from '../wire/Transport.js';
+import type { Extension } from './Extension.js';
+import type { AuthConfig } from './AuthConfig.js';
+import type { DispatchObserver } from '../dispatch/DispatchObserver.js';
+import type { App } from './App.js';
+
+/** Options for createApp(). */
+export interface CreateAppOptions {
+  /** Factory function to create the container. Required. */
+  createContainer: () => Container;
+  /** Factory to auto-generate Storage for each scanned entity. */
+  storageFactory?: StorageFactory;
+  /**
+   * Which source an entity's rows live in, and how to open a transaction on one — the two
+   * questions that decide whether `Together<[…]>` gets the engine's own unwind or replays inverses
+   * itself.
+   */
+  sourceOf?: (entityName: string) => string;
+  transacts?: (source: string) => boolean;
+  transacted?: <R>(source: string, fn: (storageFactory: StorageFactory) => Promise<R>) => Promise<R>;
+  /**
+   * Bring the shape of what lives here up to date — a source's own gesture, declared on
+   * `Source.migrate` and handed over whole.
+   *
+   * Handed here rather than assembled by the host: four of them wrote
+   * `migrating(storage.migrate)` themselves, one of them as a string inside generated
+   * code, and eight demos wrote nothing — so they had no migration and nothing said it.
+   * The ASCENT is core's to order, since rows after tables is not a host's preference.
+   */
+  migrate?: (app: App) => Promise<void> | void;
+  /** Whether that source refuses a constraint at the rows — the boot says so when it does not. */
+  enforces?: (source: string, constraint: Constraint) => boolean;
+  /** Builds the cross-source reader a frond gets when it declares `reads:`. */
+  sourcesFactory?: (reads: unknown[], frond: string) => Promise<unknown> | unknown;
+  /** What this app is built from — required, because producing it is what reads a disk. */
+  scan?: ScanResult | (() => Promise<ScanResult> | ScanResult);
+  /** What this app STATES it hosts — `frond('blog', { entities: [Post] })`. */
+  fronds?: readonly FrondDescriptor[];
+  /**
+   * Remote fronds — label → address. What each remote hosts is discovered
+   * at the first miss (rpc.discover), never declared here.
+   */
+  remotes?: Record<string, string>;
+  /** Builds the transport used to reach `remotes` addresses. */
+  remoteTransport?: (url: string) => Transport;
+  /**
+   * Which realization answers which port — see `FougereConfig.ports`. Needed only
+   * when two classes extend the same port; one is resolved by convention.
+   */
+  /**
+   * What answers a port. A string names the realization; a LIST is the chain, from the
+   * outside in — `['Retrying', 'Stripe']` puts `Retrying` in front of `Stripe`, and the
+   * last name is what actually charges.
+   */
+  ports?: Record<string, string | readonly string[]>;
+  /** What this app takes on beyond its fronds, each stating what it does and what it undoes. */
+  extensions?: readonly (Extension | undefined)[];
+  /**
+   * Released by `app.dispose()` AFTER the container, for a resource handed in rather than built
+   * here — a storage connection is the one case today.
+   */
+  onDispose?: () => Promise<void> | void;
+  /** Which protocol adapters this app serves — see `FougereConfig.adapters`. */
+  adapters?: Record<string, boolean | undefined>;
+  /** Carries an announced fact out of this process — a broker, a queue, a log. */
+  onEmit?: (fact: string, payload: unknown) => void | Promise<void>;
+  /** Passive observers of every dispatch transition. */
+  dispatchObservers?: readonly DispatchObserver[];
+  /**
+   * Storage handle to expose to the auth provider via AuthContext.db.
+   * Required when `auth` is set.
+   */
+  db?: unknown;
+  /** Auth declaration to wire into the app at boot. */
+  auth?: AuthConfig;
+}

package/src/boot/Emissions.ts

@@ -1,16 +1,17 @@
 import { applyCreate, dotted, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { Container } from '@fougere/container';
-import { validationErrorsOf } from '../wire/errors.js';
-import { awaitKeyOf, emitKeyOf, factsAnnouncedBy, factsAwaitedBy } from '../wire/emit.js';
+import { validationErrorsOf } from '../wire/FougereError.js';
+import { awaitKeyOf, emitKeyOf, factsAnnouncedBy, factsAwaitedBy } from '../wire/Emit.js';
 import { ambient } from '#ambient';
+import type { Diagnostic } from '../diagnostic.js';
 import { Invocation } from '../wire/Invocation.js';
-import type { Logger } from '../builtin/logger.js';
+import type { Logger } from '../builtin/Logger.js';
 import type { Fronds } from '../descriptor/Fronds.js';
-import type { OperationsMap } from '../wire/operation.js';
+import type { OperationsMap } from '../wire/OperationsMap.js';
 
-/** A door and the op on it that accepts a fact. */
+/** A facade and the op on it that accepts a fact. */
 interface Listener {
-  door: string;
+  facade: string;
   op: string;
 }
 
@@ -19,7 +20,7 @@ type Carrier = (fact: string, payload: unknown) => void | Promise<void>;
 
 /** Emissions — the only place in Fougere where an initiator names a SUBJECT. */
 export class Emissions {
-  /** Who listens to what. Filled as each door's contracts are resolved. */
+  /** Who listens to what. Filled as each facade's contracts are resolved. */
   private readonly subscribers = new Map<string, Listener[]>();
 
   /** Who FINISHES a fact, in the order they run — see `orderPipes`. */
@@ -38,13 +39,21 @@ export class Emissions {
   /** What is announced AND waited for — `Emit<T, A>`, where the second type says so. */
   private readonly awaited: Set<string>;
 
+  /** Where each facade and each frond was written, so a refusal here names a file to open. */
+  private readonly fileOf = new Map<string, string>();
+
   constructor(
     fronds: Fronds,
     private readonly shapes: Map<string, SchemaView>,
     private readonly container: Container,
     private readonly log: Logger,
+    private readonly refused: Diagnostic[],
     private readonly carry?: Carrier,
   ) {
+    for (const frond of fronds) {
+      this.fileOf.set(frond.name, frond.source.path);
+      for (const handler of frond.handlers) this.fileOf.set(facadeOf(handler.name), handler.filePath);
+    }
     this.announced = new Set(fronds.flatMap((frond) => factsAnnouncedBy(frond.handlers)));
     this.awaited = new Set(fronds.flatMap((frond) => factsAwaitedBy(frond.handlers)));
     // Read from the frond that OWNS the fact: ordering is a decision about the fact, and
@@ -54,10 +63,15 @@ export class Emissions {
 
       return Object.entries(frond.pipes ?? {}).map(([fact, order]) => {
         if (!owned.has(lowerFirst(fact))) {
-          throw new Error(
-            `Frond '${frond.name}' orders the links of '${fact}', which it does not own.\n`
-            + '  The order belongs to the frond that declares the entity — state `pipes:` there.',
-          );
+          this.refused.push({
+            severity: 'blocking',
+            code: 'pipes-not-owned',
+            filePath: frond.source.path,
+            frond: frond.name,
+            subject: fact,
+            message: `Frond '${frond.name}' orders the links of '${fact}', which it does not own. `
+              + 'The order belongs to the frond that declares the entity — state `pipes:` there.',
+          });
         }
 
         return [lowerFirst(fact), order] as const;
@@ -69,16 +83,16 @@ export class Emissions {
    * Who listens to what — read from the PLAN, where `{ kind: 'fact' }` is a sentence
    * `computeBindingPlan` already wrote, so nothing re-derives what a parameter is.
    */
-  note(contracts: OperationsMap, door: string): void {
+  note(contracts: OperationsMap, facade: string): void {
     for (const [op, contract] of contracts) {
       for (const bound of contract.binding ?? []) {
         if (bound.source.kind === 'pipe') {
-          this.claimPipe(bound.source.factName, { door, op });
+          this.claimPipe(bound.source.factName, { facade, op });
           continue;
         }
         if (bound.source.kind !== 'fact') continue;
         const listeners = this.subscribers.get(bound.source.factName) ?? [];
-        listeners.push({ door, op });
+        listeners.push({ facade, op });
         this.subscribers.set(bound.source.factName, listeners);
       }
     }
@@ -87,7 +101,7 @@ export class Emissions {
   /** One more op that finishes this fact. What ORDER they run in is settled at `register`. */
   private claimPipe(fact: string, taking: Listener): void {
     const held = this.pipes.get(fact) ?? [];
-    if (held.some((one) => `${one.door}.${one.op}` === `${taking.door}.${taking.op}`)) return;
+    if (held.some((one) => `${one.facade}.${one.op}` === `${taking.facade}.${taking.op}`)) return;
     held.push(taking);
     this.pipes.set(fact, held);
   }
@@ -102,27 +116,37 @@ export class Emissions {
   private orderPipes(): void {
     for (const [fact, links] of this.pipes) {
       const declared = this.ordered.get(fact);
-      const named = (one: Listener) => `${one.door}.${one.op}`;
+      const named = (one: Listener) => `${one.facade}.${one.op}`;
 
       if (!declared) {
         if (links.length < 2) continue;
-        throw new Error(
-          `${links.length} ops finish the fact '${fact}': ${links.map(named).join(', ')}.\n`
-          + '  They run one after another and nothing says in which order. State it on the '
-          + `frond that owns '${fact}':\n`
-          + `    export default { pipes: { ${fact}: ['FirstHandler', 'SecondHandler'] } };\n`
-          + '  Or make all but one accept `Fact<…>`, which changes nothing and reads it.',
-        );
+        this.refused.push({
+          severity: 'blocking',
+          code: 'pipes-unordered',
+          filePath: this.fileOf.get(links[0]!.facade) ?? '',
+          subject: fact,
+          message: `${links.length} ops finish the fact '${fact}': ${links.map(named).join(', ')}. `
+            + 'They run one after another and nothing says in which order. State it on the frond '
+            + `that owns '${fact}': export default { pipes: { ${fact}: ['FirstHandler', `
+            + "'SecondHandler'] } }; — or make all but one accept `Fact<…>`, which changes nothing "
+            + 'and reads it.',
+        });
+        continue;
       }
 
-      const at = (one: Listener) => declared.findIndex((name) => doorOf(name) === one.door);
+      const at = (one: Listener) => declared.findIndex((name) => facadeOf(name) === one.facade);
       const unlisted = links.filter((one) => at(one) < 0);
       if (unlisted.length > 0) {
-        throw new Error(
-          `${unlisted.map(named).join(', ')} finish${unlisted.length > 1 ? '' : 'es'} the fact `
-          + `'${fact}', and '${fact}' orders ${declared.join(', ')} — so where it runs is not said.\n`
-          + '  Add it to `pipes:`, or make it accept `Fact<…>`.',
-        );
+        this.refused.push({
+          severity: 'blocking',
+          code: 'pipes-unlisted',
+          filePath: this.fileOf.get(unlisted[0]!.facade) ?? '',
+          subject: fact,
+          message: `${unlisted.map(named).join(', ')} finish${unlisted.length > 1 ? '' : 'es'} the `
+            + `fact '${fact}', and '${fact}' orders ${declared.join(', ')} — so where it runs is `
+            + 'not said. Add it to `pipes:`, or make it accept `Fact<…>`.',
+        });
+        continue;
       }
 
       this.pipes.set(fact, [...links].sort((one, other) => at(one) - at(other)));
@@ -139,9 +163,9 @@ export class Emissions {
     return [...this.subscribers.keys()];
   }
 
-  /** The doors that accept one fact — the addresses a middleware must leave alone. */
-  doorsFor(fact: string): string[] {
-    return (this.subscribers.get(fact) ?? []).map(({ door }) => door);
+  /** The facades that accept one fact — the addresses a middleware must leave alone. */
+  facadesFor(fact: string): string[] {
+    return (this.subscribers.get(fact) ?? []).map(({ facade }) => facade);
   }
 
   /** Register one emission value per fact — announced here, or merely listened to. */
@@ -156,12 +180,17 @@ export class Emissions {
       // subscribers only, and say nothing about it. Refused here rather than half-answered
       // at the first call: the second type is in a signature, so a boot can read it.
       if (this.carry) {
-        throw new Error(
-          `'${fact}' is announced with an answer type, and this app has a carrier (\`onEmit\`).\n`
-          + '  Waiting means knowing who answers; a carrier reaches whoever subscribed '
-          + 'elsewhere and brings nothing back.\n'
-          + `  Name the subscribers in \`remotes:\`, or drop the second type of \`Emit<${fact}, …>\`.`,
-        );
+        this.refused.push({
+          severity: 'blocking',
+          code: 'emit-await-with-carrier',
+          filePath: this.fileOf.get(facadeOf(fact)) ?? '',
+          subject: fact,
+          message: `'${fact}' is announced with an answer type, and this app has a carrier `
+            + '(`onEmit`). Waiting means knowing who answers; a carrier reaches whoever subscribed '
+            + `elsewhere and brings nothing back. Name the subscribers in \`remotes:\`, or drop the `
+            + `second type of \`Emit<${fact}, …>\`.`,
+        });
+        continue;
       }
       this.container.registerValue(awaitKeyOf(fact), (raw: unknown) => this.announce(fact, raw, true));
     }
@@ -187,8 +216,8 @@ export class Emissions {
 
     const handed = this.handToListeners(fact, payload);
     if (!waiting) {
-      for (const { door, op, done } of handed) {
-        void done.catch((cause) => this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, cause) ?? cause));
+      for (const { facade, op, done } of handed) {
+        void done.catch((cause) => this.log.error(`${fact} → ${facade}.${op}`, this.describeRefusal(fact, cause) ?? cause));
       }
 
       return [];
@@ -202,13 +231,13 @@ export class Emissions {
     const missing = settled.flatMap((result, at) =>
       (result.status === 'rejected' ? [{ ...handed[at]!, reason: result.reason as unknown }] : []));
     if (missing.length > 0) {
-      for (const { door, op, reason } of missing) {
-        this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, reason) ?? reason);
+      for (const { facade, op, reason } of missing) {
+        this.log.error(`${fact} → ${facade}.${op}`, this.describeRefusal(fact, reason) ?? reason);
       }
       throw new AggregateError(
         missing.map((one) => one.reason),
         `${fact} — ${missing.length} of ${handed.length} subscriber(s) did not answer`
-        + ` (${missing.map((one) => `${one.door}.${one.op}`).join(', ')}).`
+        + ` (${missing.map((one) => `${one.facade}.${one.op}`).join(', ')}).`
         + ' An announcement with an answer type waits for everyone: a partial answer would'
         + ' look like a complete one.',
       );
@@ -227,14 +256,14 @@ export class Emissions {
 
     const refused = settled.flatMap((result, i) =>
       result.status === 'rejected' ? [{ ...handed[i], reason: result.reason as unknown }] : []);
-    for (const { door, op, reason } of refused) {
-      this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, reason) ?? reason);
+    for (const { facade, op, reason } of refused) {
+      this.log.error(`${fact} → ${facade}.${op}`, this.describeRefusal(fact, reason) ?? reason);
     }
     if (refused.length > 0) {
       throw new AggregateError(
         refused.map((r) => r.reason),
         `${fact} — ${refused.length} of ${handed.length} listener(s) refused it`
-        + ` (${refused.map((r) => `${r.door}.${r.op}`).join(', ')}).`
+        + ` (${refused.map((r) => `${r.facade}.${r.op}`).join(', ')}).`
         + ` Nothing here holds it: the carrier decides whether it comes back.`,
       );
     }
@@ -250,7 +279,7 @@ export class Emissions {
   private async finished(fact: string, payload: unknown): Promise<unknown> {
     let carried = payload;
     for (const link of this.pipes.get(fact) ?? []) {
-      const facade = this.container.resolve<Record<string, Function>>(link.door);
+      const facade = this.container.resolve<Record<string, Function>>(link.facade);
       const answered = await facade[link.op]({ ...Invocation.empty, input: carried });
 
       // A link that answers nothing SUPPRESSES the fact — every subscriber was then handed
@@ -260,7 +289,7 @@ export class Emissions {
       // each reader; it is not a link's to decide for everyone.
       if (answered === null || answered === undefined) {
         throw new Error(
-          `${link.door}.${link.op} finishes the fact '${fact}' and answered nothing.\n`
+          `${link.facade}.${link.op} finishes the fact '${fact}' and answered nothing.\n`
           + '  A link says what the fact IS, it does not take it back — the announcer has '
           + 'already said it happened, and nothing can tell it otherwise.\n'
           + '  Return the fact, amended or as it stands.',
@@ -289,7 +318,8 @@ export class Emissions {
     if (walked.includes(fact)) {
       throw new Error(
         `Emission cycle: ${[...walked, fact].join(' → ')}.\n`
-        + `  A fact cannot cause itself. One of the subscribers above announces a fact that leads back here.`,
+        + '  A fact cannot cause itself. One of the subscribers above announces a fact that leads back here.\n'
+        + '  Make it accept `Fact<…>` and read, or announce outside the subscriber.',
       );
     }
 
@@ -299,17 +329,17 @@ export class Emissions {
       return [];
     }
 
-    return listeners.map(({ door, op }) => ({
-      door,
+    return listeners.map(({ facade, op }) => ({
+      facade,
       op,
       done: ambient.enterChain(fact, async () => {
-        let facade: Record<string, Function>;
+        let handler: Record<string, Function>;
         try {
-          facade = this.container.resolve<Record<string, Function>>(door);
+          handler = this.container.resolve<Record<string, Function>>(facade);
         } catch (cause) {
-          throw new Error(`${fact} → ${door} could not be reached`, { cause });
+          throw new Error(`${fact} → ${facade} could not be reached`, { cause });
         }
-        return facade[op]({ ...Invocation.empty, input: payload });
+        return handler[op]({ ...Invocation.empty, input: payload });
       }),
     }));
   }
@@ -327,7 +357,7 @@ export class Emissions {
  * The container key a declared CLASS NAME answers under — `RedactHandler` → `redactHandler`,
  * the same key `facadeKeyOf` builds from an address.
  */
-function doorOf(declared: string): string {
+function facadeOf(declared: string): string {
   const key = lowerFirst(declared);
 
   return key.endsWith('Handler') ? key : `${key}Handler`;

package/src/boot/Extension.ts

@@ -0,0 +1,20 @@
+import type { App } from './App.js';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+
+/**
+ * One process-level extension and its reversible lifecycle.
+ *
+ * Documented: [lifecycle](https://fougere.dev/docs/infra/lifecycle).
+ */
+export interface Extension {
+  name: string;
+  /**
+   * Fronds it brings — read BEFORE the ascent, since a frond is installed while the app is
+   * still being made and `up` receives one that already exists. This is how an optional
+   * package accepts a fact: `calls` and `observability` both want every `LogLine`, and a
+   * signature is the only way to ask for one.
+   */
+  fronds?: readonly FrondDescriptor[];
+  up?(app: App): void | Promise<void>;
+  down?(app: App): void | Promise<void>;
+}

package/src/boot/apply.ts

@@ -1,5 +1,5 @@
-import type { FougereConfig } from '../config-loader.js';
-import { setLogLevel, logLevel, envLevel } from '../builtin/logger.js';
+import type { FougereConfig } from '../FougereConfig.js';
+import { envLevel, logLevel, setLogLevel } from '../builtin/Logger.js';
 import { dequal } from 'dequal';
 
 export interface ConfigApplication {