@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/boot/seed.ts

@@ -0,0 +1,158 @@
+import { Role } from '@fougere/schema';
+import { facadeKeyOf } from '../wire/call.js';
+import type { FrondDescriptor, SeedEntry, SeedFactory } from '../scan/frond.js';
+import type { App } from './types.js';
+import type { Extension } from './AppLifecycle.js';
+
+/**
+ * Seeds in dependency order — a `ref()` target is planted before its referrer.
+ *
+ * The order is a fact about the entity graph, not about the surface running the seeds,
+ * so it is stated once here. The Nuxt module read it off a pairwise comparator (which
+ * `Array.sort` cannot make transitive: `a` before `b` and `b` before `c` never implies
+ * `a` before `c`), and `boot()` had no order at all — the same fact, told twice and
+ * wrong both times. A list seeded before its owner failed on the foreign key, and the
+ * driver's error named neither the entity nor the file.
+ *
+ * Kahn, like `orderTables` in `@fougere/adapter-sql` — the same shape one level up: there
+ * the nodes are tables and the edges FK columns, here they are seeds and the edges the
+ * `one` relations of the entities they target. A cycle cannot be satisfied by ordering,
+ * so its remaining seeds keep their scan order and land last: the driver refuses what is
+ * genuinely impossible, and everything acyclic around it still gets planted.
+ */
+export function orderSeeds(fronds: FrondDescriptor[]): SeedEntry[] {
+  const refs = new Map<string, Set<string>>();
+  for (const frond of fronds) {
+    for (const entity of frond.entities) {
+      const targets = new Set<string>();
+      for (const field of Object.values(entity.entityClass.getFields())) {
+        if (!Role.of(field).isReference) continue;
+        const target = (Role.of(field).target as { name?: string }).name?.toLowerCase();
+        if (target && target !== entity.name.toLowerCase()) targets.add(target);
+      }
+      refs.set(entity.name.toLowerCase(), targets);
+    }
+  }
+
+  const seeds = fronds.flatMap((frond) => frond.seeds);
+  const seeded = new Set(seeds.map((seed) => seed.entityName.toLowerCase()));
+
+  // Only what is actually seeded can be waited for: a relation to an entity with no seed
+  // is already satisfied by whatever put its rows there.
+  const waiting = new Map(
+    seeds.map((seed) => {
+      const own = seed.entityName.toLowerCase();
+      const targets = [...(refs.get(own) ?? [])].filter((target) => seeded.has(target) && target !== own);
+
+      return [seed, new Set(targets)] as const;
+    }),
+  );
+
+  const ordered: SeedEntry[] = [];
+  const planted = new Set<string>();
+
+  while (waiting.size > 0) {
+    const ready = [...waiting.keys()].find((seed) => [...waiting.get(seed)!].every((dep) => planted.has(dep)));
+    if (!ready) break;
+
+    ordered.push(ready);
+    planted.add(ready.entityName.toLowerCase());
+    waiting.delete(ready);
+  }
+
+  return [...ordered, ...waiting.keys()];
+}
+
+/** Where a seed writes, and what it may skip — resolved per entity. */
+interface SeedDoor {
+  list(): Promise<unknown[]>;
+  write(item: unknown): Promise<unknown>;
+}
+
+/**
+ * Plant a set of seeds, in the order given. Reports what it did, one line per entity.
+ *
+ * The one seeding loop. `boot()` had one and the Nuxt module generated a second into its
+ * Nitro plugin, which had drifted: no ORM fallback, so an entity with no façade was
+ * skipped there and planted here. Two answers to "how does a row get in at boot" is one
+ * too many, and the second was the one running in the browser.
+ */
+export async function runSeeds(
+  app: App,
+  seeds: SeedEntry[],
+  report: (message: string) => void = () => {},
+): Promise<void> {
+  for (const seed of seeds) {
+    const resolve = <T>(name: string) => app.resolve<T>(name + 'Handler');
+    const data = typeof seed.data === 'function' ? await (seed.data as SeedFactory)(resolve) : seed.data;
+
+    const door = doorFor(app, seed.entityName);
+    if (!door) {
+      report(`  ${seed.entityName}: no handler façade nor ORM — skipping seed`);
+      continue;
+    }
+
+    const existing = await door.list();
+    if (existing.length > 0) {
+      report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
+      continue;
+    }
+
+    // The driver's error alone names neither the entity nor the row — and a foreign
+    // key is exactly what a seed gets wrong.
+    for (const item of data) {
+      try {
+        await door.write(item);
+      } catch (cause) {
+        throw new Error(
+          `Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${(cause as Error)?.message ?? cause}`,
+          { cause },
+        );
+      }
+    }
+    report(`  ${seed.entityName}: ${data.length} records`);
+  }
+}
+
+/**
+ * A seed is not a client: it writes at boot, from inside. The façade is used when the
+ * entity declares one (its judge catches a bad seed early), the storage when it does
+ * not — an entity that exposes nothing is still an entity whose reference rows must land.
+ */
+function doorFor(app: App, entityName: string): SeedDoor | undefined {
+  let handler: Record<string, Function> | undefined;
+  try { handler = app.resolve<Record<string, Function>>(facadeKeyOf(entityName)); } catch {}
+
+  if (typeof handler?.list === 'function' && typeof handler.create === 'function') {
+    return {
+      list: () => handler!.list() as Promise<unknown[]>,
+      write: (item) => handler!.create({ params: {}, query: {}, body: item, state: {} }),
+    };
+  }
+
+  const orm = app.ormFor(entityName) as
+    | { list: () => Promise<unknown[]>; create: (input: unknown) => Promise<unknown> }
+    | undefined;
+  if (!orm) return undefined;
+
+  return { list: () => orm.list(), write: (item) => orm.create(item) };
+}
+
+/**
+ * The framework's own ascent for rows, named — so a host can REPLACE it rather than take
+ * over the whole post-boot to get its own.
+ *
+ * That is what Nuxt's Nitro plugin had to do: a bundler needs its seed modules spelled out
+ * as static imports, so the plugin claimed everything after the boot and its copy of the
+ * loop drifted. It now declares an extension under this same name instead, and the delta
+ * is one member of a list.
+ */
+export function seeding(report?: (message: string) => void): Extension {
+  return {
+    name: 'seeds',
+    up: async (app: App) => {
+      const seeds = orderSeeds(app.fronds);
+      if (seeds.length > 0) await runSeeds(app, seeds, report);
+    },
+  };
+}

package/src/boot/together.ts

@@ -0,0 +1,215 @@
+/**
+ * Building a frame — what a handler asking for `Together<[…]>` receives.
+ *
+ * The declaration names its members and nothing else; where they live, and therefore
+ * which of the two realizations they get, is read HERE and stated at boot. A frame whose
+ * members share an engine is a transaction; one whose members are split replays its own
+ * inverses (`frame.ts`). Same user code, two guarantees, and the boot says which — the
+ * one thing a gradient must never leave to assumption.
+ */
+import { ambient } from '#ambient';
+import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
+import type { Container } from '@fougere/container';
+import { membersOfTogetherKey, ormKeyOf, type EntityOrm, type OrmFactory } from '../orm.js';
+import type { Logger } from '../builtins/logger.js';
+import type { ProviderEntry } from '../scan/frond.js';
+import { StorageGuard } from '../dispatch/StorageGuard.js';
+import { recording, unwind, type Undo } from './frame.js';
+
+/** Everything the boot knows that a frame needs, gathered once for every frond. */
+export interface FrameWorld {
+  /** Every entity of every frond, by registration key. A frame crosses fronds by design. */
+  entityByName: Map<string, SchemaView>;
+  /** Which frond holds an entity — the question `remotes:` turns into a refusal. */
+  frondOf: Map<string, string>;
+  hostedHere: (frond: string) => boolean;
+  ormFactory?: OrmFactory;
+  sourceOf?: (entityName: string) => string;
+  transacted?: <R>(source: string, fn: (ormFactory: OrmFactory) => Promise<R>) => Promise<R>;
+  log: Logger;
+}
+
+/** An entity the block writes through, and a provider rebuilt so that its writes count too. */
+interface Members {
+  entities: { name: string; schema: SchemaView }[];
+  providers: ProviderEntry[];
+}
+
+/**
+ * Each declared name, resolved to what it designates.
+ *
+ * A name that resolves to nothing is refused rather than skipped: `Together<[Account,
+ * Ledgre]>` is a typo whose only other symptom is a frame quietly one member short. The
+ * two lists are checked against different registries, which is exactly why the declaration
+ * separates them — nothing here has to guess what kind a name is.
+ */
+function resolve(names: { entities: string[]; providers: string[] }, declared: readonly ProviderEntry[], world: FrameWorld): Members {
+  const entities = names.entities.map((member) => {
+    const name = lowerFirst(member);
+    const schema = world.entityByName.get(name);
+    if (!schema) {
+      throw new Error(
+        `Together<[…${member}…]>: no entity named '${member}' is scanned in this app. ` +
+        `The first list names entities; a class of this frond goes in the second.`,
+      );
+    }
+    return { name, schema };
+  });
+
+  const providers = names.providers.map((member) => {
+    const entry = declared.find((provider) => provider.ctor.name === member);
+    if (!entry) {
+      throw new Error(
+        `Together<[…], [… ${member} …]>: this frond declares no class named '${member}'. ` +
+        `The second list names providers to rebuild inside the frame — a service, a mirror, ` +
+        `a repository — so that what they write is covered by the unwind.`,
+      );
+    }
+    return entry;
+  });
+
+  return { entities, providers };
+}
+
+/**
+ * A member that cannot write here at all — its frond is hosted elsewhere.
+ *
+ * Refused rather than compensated: a compensated frame still writes through a local ORM,
+ * and a remote frond registers none. There is nothing to record and nothing to undo.
+ */
+function refuseRemote(members: Members, world: FrameWorld, key: string): void {
+  for (const member of members.entities) {
+    const frond = world.frondOf.get(member.name);
+    if (frond && !world.hostedHere(frond)) {
+      throw new Error(
+        `Together<[…]> (${key}): '${member.name}' belongs to frond '${frond}', which this ` +
+        `process declares in remotes: — it registers no storage here, so its writes cannot be ` +
+        `part of a frame. Host the frond here, or split the work and join the halves with a fact.`,
+      );
+    }
+  }
+}
+
+/**
+ * A provider member writing an entity the frame does not name.
+ *
+ * The frame does not widen itself to cover it: doing so would pull an entity from another
+ * source into the group without anyone writing it down. Named instead, with the one-word fix.
+ */
+function refuseUncoveredWrites(members: Members, key: string): void {
+  const covered = new Set(members.entities.map((member) => member.name));
+  for (const provider of members.providers) {
+    for (const dep of provider.deps) {
+      if (!dep.endsWith('Orm')) continue;
+      const entity = lowerFirst(dep.slice(0, -'Orm'.length));
+      if (covered.has(entity)) continue;
+      throw new Error(
+        `Together<[…]> (${key}): ${provider.ctor.name} writes ${entity}, which is not in the ` +
+        `frame's entity list — its writes would escape the unwind. Add it: ` +
+        `Together<[…, ${upperFirst(entity)}], [… ${provider.ctor.name} …]>.`,
+      );
+    }
+  }
+}
+
+/**
+ * Open the block: build every member over `factory`, in a scope of their own.
+ *
+ * The scope is what makes a provider member work without a locator — its ORM keys are
+ * registered here, so the container hands it the framed ones through the ordinary
+ * constructor. It is disposed when the block ends, whichever way it ended.
+ */
+async function inScope<R>(
+  parent: Container,
+  members: Members,
+  factory: OrmFactory,
+  wrap: (orm: EntityOrm, name: string, schema: SchemaView) => EntityOrm,
+  fn: (entities: unknown[], providers: unknown[]) => Promise<R>,
+): Promise<R> {
+  const scope = parent.createScope();
+  try {
+    const orms = members.entities.map((member) => {
+      const orm = wrap(factory(member.schema, member.name), member.name, member.schema);
+      scope.registerValue(ormKeyOf(member.name), orm);
+      return orm;
+    });
+    // Providers after every ORM is in place: one may depend on another member's.
+    const built = members.providers.map((provider) => {
+      scope.register(provider.ctor.name, provider.ctor, { deps: provider.deps });
+      return scope.resolve(provider.ctor.name);
+    });
+    return await fn(orms, built);
+  } finally {
+    await scope.dispose();
+  }
+}
+
+/**
+ * Register one frame per key a handler or provider of this frond asked for.
+ *
+ * Called with the frond's scope, because that is where the asking constructor resolves —
+ * while the MEMBERS are looked up app-wide, a frame crossing fronds being the ordinary case
+ * rather than the exception (the frond is not the storage boundary; `sources:` is).
+ */
+export function registerFrames(
+  scope: Container,
+  keys: Iterable<string>,
+  providers: readonly ProviderEntry[],
+  world: FrameWorld,
+): void {
+  let registered = 0;
+  for (const key of new Set(keys)) {
+    const names = membersOfTogetherKey(key);
+    if (!names) continue;
+    registered += 1;
+    if (!world.ormFactory) {
+      throw new Error(`Together<[${names.entities.join(', ')}]> needs storage, and this boot declares none.`);
+    }
+
+    const members = resolve(names, providers, world);
+    refuseRemote(members, world, key);
+    refuseUncoveredWrites(members, key);
+
+    const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
+    const judge = (orm: EntityOrm, name: string, schema: SchemaView) =>
+      new StorageGuard(schema.getFields(), name).guard(orm);
+
+    // One engine and a way into it: the engine gives the unwind AND the isolation.
+    if (world.transacted && sources.size === 1) {
+      const source = [...sources][0];
+      world.log.info(`${key} — transaction, source '${source}'`);
+      scope.registerValue(key, {
+        run: <R>(fn: (entities: never, providers: never) => Promise<R>) =>
+          ambient.enterFrame(key, () =>
+            world.transacted!(source, (factory) => inScope(scope, members, factory, judge, fn as never))),
+      });
+      continue;
+    }
+
+    // Split, or an engine that hands out no transaction: the frame keeps the before-image
+    // of every write and replays the inverses itself. `judge` stays OUTSIDE `recording`, so
+    // a write the entity refuses never enters the journal.
+    const why = sources.size > 1
+      ? members.entities.map((m) => `${m.name} in '${world.sourceOf?.(m.name) ?? 'db'}'`).join(', ')
+      : 'this storage hands out no transaction';
+    world.log.info(`${key} — compensated: ${why} — no isolation`);
+    scope.registerValue(key, {
+      run: <R>(fn: (entities: never, providers: never) => Promise<R>): Promise<R> => ambient.enterFrame(key, async () => {
+        const journal: Undo[] = [];
+        const record = (orm: EntityOrm, name: string, schema: SchemaView) =>
+          judge(recording(orm, name, schema.getFields(), journal), name, schema);
+        try {
+          return await inScope(scope, members, world.ormFactory!, record, fn as never);
+        } catch (cause) {
+          return unwind(journal, cause, world.log);
+        }
+      }),
+    });
+  }
+  if (registered > 0 && ambient.degraded) {
+    world.log.warn(
+      'no async context on this runtime — frames run one at a time, and a frame opened '
+      + 'inside another times out instead of being refused',
+    );
+  }
+}

package/src/boot/types.ts

@@ -0,0 +1,261 @@
+/**
+ * The boot's two ends: what `createApp` takes, and what it hands back.
+ *
+ * The scan's descriptors moved to `frond.ts` and the auth contract to `auth.ts` — this
+ * file was named after a role ("the types"), so everything with nowhere else to be
+ * landed in it, seventeen notions deep.
+ */
+import type { Container } from '@fougere/container';
+import type { Fronds } from '../scan/Fronds.js';
+import type { ScanResult } from '../scan/frond.js';
+import type { SchemaView } from '@fougere/schema';
+import type { OrmFactory } from '../orm.js';
+import type { AppMiddleware } from '../wire/middleware.js';
+import type { RpcAnswer, Transport } from '../wire/call.js';
+import type { Extension } from './AppLifecycle.js';
+import type { AuthConfig, AuthRuntime } from './auth.js';
+import type { EffectiveOperationsMap } from '../effective-operation.js';
+import type { DispatchObserver } from '../dispatch/DispatchEvent.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+
+/** Options for createApp(). */
+export interface CreateAppOptions {
+  /** Factory function to create the container. Required. */
+  createContainer: () => Container;
+  /** Factory to auto-generate EntityOrm for each scanned entity. */
+  ormFactory?: OrmFactory;
+  /**
+   * 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.
+   *
+   * Optional together, because a host may hand in a bare `ormFactory` and know neither. A
+   * frame then compensates: not knowing where the rows are and promising atomicity over
+   * them are two different things, and only one of them is honest.
+   */
+  sourceOf?: (entityName: string) => string;
+  transacted?: <R>(source: string, fn: (ormFactory: OrmFactory) => Promise<R>) => Promise<R>;
+  /**
+   * Builds the cross-source reader a frond gets when it declares `reads:`.
+   *
+   * A factory rather than a value, for the same reason `ormFactory` is one: core must
+   * not name a storage package, and this one costs 71 MB of downloaded extensions and a
+   * native module — nothing a first run that only wanted sqlite should carry. The host
+   * decides what backs it; `@fougere/adapter-duckdb` is one answer, not the contract.
+   *
+   * Called once per frond that asks, with the entity CLASSES its `reads:` named — a
+   * name would make the reader resolve the schema a second time.
+   */
+  sourcesFactory?: (reads: unknown[], frond: string) => Promise<unknown> | unknown;
+  /**
+   * What this app is built from — required, because producing it is what reads a disk.
+   *
+   * `scanProject` (`@fougere/core/node`) reads the fronds off the filesystem; a module a
+   * build wrote holds the same value with no disk at all. `createApp` cannot tell them
+   * apart, and that is the point: it names no builtin, so a runtime without `node:fs`
+   * runs it. `root` and `fronds` used to live here — both were arguments to the scan.
+   */
+  scan: ScanResult | (() => Promise<ScanResult> | ScanResult);
+  /**
+   * 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. Wired by
+   * layer-2 packages (e.g. @fougere/transport-http); required when
+   * `remotes` is non-empty.
+   */
+  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.
+   */
+  ports?: Record<string, string>;
+  /**
+   * What this app takes on beyond its fronds, each stating what it does and what it undoes.
+   *
+   * `up` runs before `createApp` returns, in this order; `down` runs inside `dispose()`,
+   * in reverse. Three levels release in reverse of construction, which is the container's
+   * own rule read one level out: extensions first (built last), then the container, then
+   * `onDispose` — a resource opened before any of this existed.
+   *
+   * A member may be `undefined`, so a host writes a conditional one inline rather than a
+   * spread over a ternary. The framework's own two are always declared, `migrate` as an
+   * empty slot when nothing migrates: a host filling it later REPLACES that member in
+   * place instead of adding one after the seeds.
+   */
+  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.
+   *
+   * NOT an extension, and the difference is a time: this was opened BEFORE the container,
+   * so it closes after it, while an extension's `up` runs after the container and its
+   * `down` therefore runs before. A storage's migration is an extension; its connection
+   * is not, and `ResolvedStorage` declares the two beside each other.
+   */
+  onDispose?: () => Promise<void> | void;
+  /**
+   * Which protocol adapters this app serves — see `FougereConfig.adapters`.
+   * Carried onto the App so every door reads one answer instead of each host
+   * deciding for itself.
+   */
+  adapters?: Record<string, boolean | undefined>;
+  /**
+   * Carries an announced fact out of this process — a broker, a queue, a log.
+   *
+   * Called for every emission, ALONGSIDE the local dispatch and never instead of it: a
+   * listener in this process is reached directly, and this is how the others hear.
+   *
+   * It exists because the local dispatch finds its listeners by having READ their code,
+   * which stops at the repository boundary. A carrier hands the fact to a NAME; the far
+   * side subscribes to that same name from its own code, and neither ever reads the other.
+   *
+   * Its failure never reaches the emitter — same rule as a subscriber's.
+   */
+  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;
+}
+
+/** 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`.
+   *
+   * Read by the doors themselves, so an undeclared adapter serves nothing whatever
+   * the host mounted — the route file may exist, the middleware may be installed, and
+   * the answer is still "not here".
+   */
+  adapters: Record<string, boolean | undefined>;
+  /** 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`). The one way to get a live schema for an
+   * entity whose class may not be importable at all (another repo, another
+   * language) — a card travelled, but until now its `schema` was thrown away.
+   */
+  schemaFor(entity: string): Promise<SchemaView>;
+  /**
+   * The door a name exposes to one audience, or `undefined` when it exposes
+   * none. A named surface is CLOSED: a name with no door of its own under that
+   * surface is not in it — it never falls back to the full one.
+   *
+   * **Not always a façade**, despite the name: when the owning frond is declared
+   * remote, nothing is registered locally (`bootstrap.ts`, `declaredRemotes`) and
+   * this resolves to a doublure — a façade-shaped stand-in (`remote.ts`). The
+   * caller cannot tell, which is the point; the word here was simply wrong.
+   *
+   * The one way an adapter reaches that door. It exists so the key format stays
+   * inside core (see `facadeKeyOf`), which is what lets a projection package
+   * stay structurally typed and depend on nothing.
+   */
+  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. Check, explain and adapters read
+   * this table instead of replaying those decisions.
+   */
+  operationsFor(entity: string, surface?: string): EffectiveOperationsMap | undefined;
+  /**
+   * The facts this app has a listener for — what a carrier must subscribe to on its behalf.
+   *
+   * Derived from the signatures it scanned (`Fact<T>` in an op's parameters), so a process
+   * states what it listens to without anyone declaring it twice. The dual of `onEmit`: one
+   * says what leaves, this says what should be brought in.
+   */
+  listensTo(): string[];
+  /**
+   * Hand a fact that came from OUTSIDE to the listeners in this process — and stop there.
+   *
+   * The dual of `onEmit`, and deliberately not the same thing as announcing: resolving the
+   * emission value to deliver an inbound fact would carry it straight back out through
+   * `onEmit`, so a hub echoed every reading it received to the whole fleet. Receiving and
+   * announcing are two operations; only one of them leaves.
+   *
+   * The local dispatch is identical either way — same judge, same binding, same
+   * middlewares — so a fact off a wire is no less checked than one raised next door.
+   *
+   * **It waits, and it tells** — the opposite of announcing, on purpose. It resolves once
+   * every listener here is done, and REJECTS with an `AggregateError` if any refused. A
+   * carrier's whole job is to know whether the fact landed: at-least-once is retrying what
+   * failed, so a delivery that cannot report makes durability impossible to build above it.
+   * "Dispatch is not delivery" protects the EMITTER from a slow subscriber; a carrier is
+   * not the emitter, it is the party whose business this is.
+   *
+   * It still holds nothing. A refused fact is refused, and whether it comes back is the
+   * carrier's decision — Fougere puts the channel underneath rather than reimplementing it.
+   */
+  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}. `undefined` when no loaded frond hosts the entity,
+   * or when the app booted with no storage at all.
+   *
+   * `unknown` because the port belongs to whoever wired it: narrowing it to `EntityOrm`
+   * is the caller saying which implementation they are standing on.
+   */
+  ormFor(entity: string): unknown | undefined;
+  /**
+   * The presenter of an entity, resolved through its owning frond's scope.
+   *
+   * Same shape as {@link ormFor}, and it exists so an adapter never spells the container
+   * key itself: `schema-graphql` wrote out `${Name}Presenter` by hand, and a key respelled
+   * in a second place finds nothing and reports nothing the day the convention moves.
+   */
+  presenterFor(entity: string): unknown | undefined;
+  /** Dispose the root container. */
+  dispose(): Promise<void>;
+  /**
+   * Stop taking calls, and resolve once the running ones are done.
+   *
+   * The step before releasing, when there is work on the app: `dispose()` closes a
+   * storage connection the running calls are standing on. Rejects on `timeoutMs`
+   * naming how many are left, rather than resolving as if it had succeeded.
+   */
+  drain(timeoutMs?: number): Promise<void>;
+  /** How many calls are running right now — one count for all three doors and the wire. */
+  inFlight(): number;
+  /**
+   * The same disposal, spelled so the language does it: `await using app = await
+   * createApp(…)`. Twelve of the twenty-six mounts in this repo's own tests never
+   * called `dispose()` — a scope that closes itself is the only version of that
+   * rule nobody forgets.
+   */
+  [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.
+   *
+   * The gesture a package uses to add a reading core does not hold: an app that never
+   * installed it never registers it, so the runner's refusal is the whole degradation.
+   * A name already declared is refused rather than replaced — `discover` included.
+   */
+  serveRpc(op: string, answer: RpcAnswer): 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/builtins/config.ts

@@ -0,0 +1,19 @@
+/**
+ * The process environment, as a service — so a handler asks for it rather than reading it.
+ *
+ * `process` is absent on a Worker, where the environment arrives as a binding. Read through
+ * `globalThis` and treated as empty when there is none: a missing variable and a missing
+ * `process` are the same answer to a caller, and the fallback already says what to do.
+ */
+export class Config {
+  constructor(private readonly env: Record<string, string | undefined> = envOfProcess()) {}
+
+  get<T = string>(key: string, fallback?: T): T {
+    return (this.env[key] as T) ?? (fallback as T);
+  }
+}
+
+function envOfProcess(): Record<string, string | undefined> {
+  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
+  return proc?.env ?? {};
+}