@fougere/core 0.3.0-alpha.0 → 0.5.0-alpha.0

package/src/boot/types.ts

@@ -0,0 +1,274 @@
+/**
+ * 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 { FrondDescriptor, 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);
+  /**
+   * What this app STATES it hosts — `frond('blog', { entities: [Post] })`.
+   *
+   * Passing this and not `scan:` is how an app says "do not scan": nothing reads a disk,
+   * nothing loads `typescript`, and what was not named does not exist. Passing both fills
+   * the members left unnamed from what the scan found — the app's word wins, the way
+   * `frond.config.ts` wins over the scan one level down.
+   */
+  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. 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>;
+  /** 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`). 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). */
+  /** Watch every dispatch transition; the returned function unsubscribes. */
+  observe(observer: DispatchObserver): () => void;
+  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 ?? {};
+}

package/src/builtins/logger.ts

@@ -0,0 +1,175 @@
+/**
+ * Fougere Logger — structured, colored, multi-runtime.
+ *
+ * Works on Node, Bun, Deno, Cloudflare Workers (console-based, no native bindings).
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+/**
+ * One line, before it was formatted for a terminal.
+ *
+ * The console form is already cooked — ANSI codes, a badge, a timestamp — so anything
+ * that wants to FORWARD a log needs it before that. What travels is the structure, and
+ * nothing here knows where it goes.
+ */
+export interface LogRecord {
+  level: Exclude<LogLevel, 'silent'>;
+  /** The logger's own name — 'boot:app', 'boot:app:catalog'. */
+  name: string;
+  message: string;
+  args: unknown[];
+  /** Epoch milliseconds. */
+  at: number;
+}
+
+export type LogSink = (record: LogRecord) => void;
+
+/**
+ * Who else takes this process's log lines, beside the console. A list, like the span
+ * sinks: a line is one fact, and forwarding it twice is the caller's business.
+ *
+ * Nothing is built when nobody listens — the record is only shaped if a sink exists.
+ */
+const sinks: LogSink[] = [];
+
+/** Take every line this process logs. Returns the way to withdraw. */
+export function onLog(next: LogSink): () => void {
+  sinks.push(next);
+  return () => {
+    const at = sinks.indexOf(next);
+    if (at >= 0) sinks.splice(at, 1);
+  };
+}
+
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+
+/**
+ * The level, held ONCE for the process and CONSULTED at every emission.
+ *
+ * It used to be copied into each Logger by the constructor, and copied again by
+ * `child()` — so there was no place where "the level" was, and changing it meant
+ * rebuilding every logger AND everything that had been handed one. A value read at
+ * the moment it is used costs the same and can move.
+ */
+let threshold: number = LEVELS[envLevel() ?? 'info'];
+
+/**
+ * The level the PROCESS was started with. Read here rather than only at `applyConfig`,
+ * which runs after the boot has already said where its root is — an operator asking for
+ * `warn` got that line anyway. Guarded: this module runs on Workers, where there is no
+ * `process`.
+ */
+export function envLevel(): LogLevel | undefined {
+  const raw = typeof process === 'undefined' ? undefined : process.env.FOUGERE_LOG_LEVEL;
+  return raw !== undefined && raw in LEVELS ? (raw as LogLevel) : undefined;
+}
+
+/**
+ * Set the level for every logger in this process, at once.
+ *
+ * Refuses a level it does not know rather than storing `undefined` as the threshold:
+ * every comparison against it is then `NaN`, so nothing is filtered and `logLevel()`
+ * reports its own fallback instead of what is in force.
+ */
+export function setLogLevel(level: LogLevel): void {
+  if (!(level in LEVELS)) {
+    throw new Error(`Unknown log level: '${level}'. One of ${Object.keys(LEVELS).join(', ')}.`);
+  }
+  threshold = LEVELS[level];
+}
+
+/** What the level is now — the dual, so a reload can report what it changed. */
+export function logLevel(): LogLevel {
+  return (Object.keys(LEVELS) as LogLevel[]).find((l) => LEVELS[l] === threshold) ?? 'info';
+}
+
+const COLORS: Record<string, string> = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+};
+
+const LEVEL_STYLE: Record<string, { badge: string; color: string }> = {
+  debug: { badge: 'DBG', color: 'gray' },
+  info:  { badge: 'INF', color: 'green' },
+  warn:  { badge: 'WRN', color: 'yellow' },
+  error: { badge: 'ERR', color: 'red' },
+};
+
+function supportsColor(): boolean {
+  if (typeof process !== 'undefined') {
+    if (process.env.NO_COLOR) return false;
+    if (process.env.FORCE_COLOR === '1') return true;
+    return process.stdout?.isTTY === true;
+  }
+  return false;
+}
+
+function formatTime(): string {
+  const d = new Date();
+  const h = String(d.getHours()).padStart(2, '0');
+  const m = String(d.getMinutes()).padStart(2, '0');
+  const s = String(d.getSeconds()).padStart(2, '0');
+  const ms = String(d.getMilliseconds()).padStart(3, '0');
+  return `${h}:${m}:${s}.${ms}`;
+}
+
+export interface LoggerOptions {
+  /** Logger name / prefix. */
+  name?: string;
+  /** Force color on/off. Auto-detected by default. */
+  color?: boolean;
+}
+
+export class Logger {
+  private name: string;
+  private color: boolean;
+
+  constructor(prefix?: string, options?: Omit<LoggerOptions, 'name'>) {
+    this.name = prefix ?? 'app';
+    this.color = options?.color ?? supportsColor();
+  }
+
+  /** Create a child logger with a sub-name. It carries no level of its own either. */
+  child(name: string): Logger {
+    return new Logger(`${this.name}:${name}`, { color: this.color });
+  }
+
+  debug(msg: string, ...args: unknown[]) { this.log('debug', msg, args); }
+  info(msg: string, ...args: unknown[])  { this.log('info', msg, args); }
+  warn(msg: string, ...args: unknown[])  { this.log('warn', msg, args); }
+  error(msg: string, ...args: unknown[]) { this.log('error', msg, args); }
+
+  private log(level: string, msg: string, args: unknown[]) {
+    if (LEVELS[level as LogLevel] < threshold) return;
+
+    // Beside the console, never instead of it: a forwarded line is an addition, and a
+    // sink that throws must not cost the operator the line they were reading.
+    for (const take of sinks) {
+      try {
+        take({ level: level as LogRecord['level'], name: this.name, message: msg, args, at: Date.now() });
+      } catch { /* forwarding never breaks logging */ }
+    }
+
+    const style = LEVEL_STYLE[level];
+    const time = formatTime();
+    // One console method per level. `debug` and `info` both went to `console.log`, so
+    // nothing downstream — a terminal filter, a collector — could tell them apart.
+    const method = level as 'debug' | 'info' | 'warn' | 'error';
+
+    if (this.color) {
+      const c = COLORS[style.color];
+      const prefix = `${COLORS.dim}${time}${COLORS.reset} ${c}${COLORS.bold}${style.badge}${COLORS.reset} ${COLORS.magenta}${this.name}${COLORS.reset}`;
+      console[method](prefix, msg, ...args);
+    } else {
+      console[method](`${time} ${style.badge} [${this.name}]`, msg, ...args);
+    }
+  }
+}

package/src/config-loader.ts

@@ -0,0 +1,146 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { AuthConfig } from './boot/auth.js';
+import type { LogLevel } from './builtins/logger.js';
+import type { ConventionsInput } from './scan/conventions.js';
+import { getModuleLoader } from './loader.js';
+
+// ── Types ────────────────────────────────────────
+
+export interface FougereConfig {
+  /** Database configuration — the DEFAULT source, the one an entity lands in unnamed. */
+  db?: 'sqlite' | { dialect: 'sqlite'; path?: string } | false;
+  /**
+   * The other places rows live — a name, an engine, and the entities it holds.
+   *
+   * A fact about the APP, stated beside `remotes:` because it is the same kind of
+   * statement: `remotes:` says where a CALL goes, this says where a ROW is. Neither
+   * belongs on the entity, which describes itself and not its deployment.
+   *
+   * Only the exception is declared: everything unnamed stays in `db`. Membership is
+   * per ENTITY rather than per frond — two fronds may share a database, and one frond
+   * may hold entities in two — so the entity is the truth and a frond-wide shorthand
+   * waits for a case that needs it.
+   *
+   * A `ref()` across two sources gets no foreign key: two databases share no
+   * constraint. The DDL stops pretending rather than the `ref` being refused.
+   */
+  sources?: Record<string, { dialect?: 'sqlite'; path?: string; entities: string[] }>;
+  /**
+   * The names the scan reads instead of deriving them — the import scope, the fronds
+   * directory, the seven convention directories.
+   *
+   * Only what differs is stated. Read BEFORE the fronds are discovered, which is what
+   * lets it name the prefix they are found under: nothing in this file may import
+   * `@fronds/*`, or the name would be needed to read the file that declares it.
+   */
+  conventions?: ConventionsInput;
+  /**
+   * How much every logger says. The one key a running app CONSULTS rather than
+   * consumes, so re-reading this file changes it without rebuilding anything.
+   *
+   * `FOUGERE_LOG_LEVEL` still wins — it is how the CLI speaks, and the precedence is
+   * the usual one (CLI over config file).
+   */
+  logLevel?: LogLevel;
+  /** Remote fronds — frondName → base URL. */
+  remotes?: Record<string, string>;
+  /**
+   * Which realization answers which port — port class name → implementation class name.
+   *
+   * A fact about the APP, stated beside `remotes:` for the same reason `sources:` is:
+   * `remotes:` says where a CALL goes, `sources:` says where a ROW is, this says who
+   * performs an ACTION. None of the three belongs inside the frond, which describes
+   * itself and not its deployment — a `billing` frond naming Stripe would be the one
+   * thing the framework refuses.
+   *
+   * Only the exception is declared. One class extending a port answers it by
+   * convention and this key stays absent; two make the boot refuse until one is named.
+   */
+  ports?: Record<string, string>;
+  /** Auth declaration — picks a provider package and forwards options to it. */
+  auth?: AuthConfig;
+  /**
+   * Which protocol adapters this app serves.
+   *
+   * A fact about the APP, declared once beside `db`, `remotes` and `auth` — not a
+   * property of whichever host runs it. Before this existed the same decision was
+   * spelled five different ways: Nuxt mounted REST unconditionally, the Web hosts
+   * served it if you happened to create a route file, and Express if you happened to
+   * call a middleware. One decision, five dialects, no canonical place.
+   *
+   * Absent means not served. The call envelope is not listed here: it is the wire the
+   * client primitives use, not a projection an app chooses to publish.
+   */
+  adapters?: AdapterConfig;
+}
+
+/** Protocol adapters, by the name of the package that provides them. */
+export interface AdapterConfig {
+  /** `@fougere/adapter-rest` — REST under `/api/{frond}/{plural}`. */
+  rest?: boolean;
+  /** `@fougere/adapter-graphql` — a GraphQL schema over the same operations. */
+  graphql?: boolean;
+  /** A surface of your own; the framework only records that you declared it. */
+  [adapter: string]: boolean | undefined;
+}
+
+// ── Loading ──────────────────────────────────────
+
+const CONFIG_FILES = ['fougere.config.ts', 'fougere.config.js', 'fougere.config.mjs'];
+
+async function loadConfigFrom(dir: string, fresh?: boolean): Promise<FougereConfig> {
+  const loader = getModuleLoader();
+  for (const file of CONFIG_FILES) {
+    const path = resolve(dir, file);
+    if (existsSync(path)) {
+      // A module is cached by its specifier, so a second load of an EDITED file hands
+      // back what was read the first time — measured, and it made re-reading a config
+      // return the config already in force. The loader owns its own cache, so it is the
+      // one told; the old module stays in memory, re-reading being for a change.
+      const mod = await loader(path, fresh ? { fresh } : undefined);
+      return ((mod as { default?: FougereConfig }).default ?? mod) as FougereConfig;
+    }
+  }
+  return {};
+}
+
+/**
+ * Load the root fougere.config.{ts,js,mjs} from the given directory.
+ *
+ * `fresh` re-reads a file that may have changed since the last load — what a host
+ * calls when it decides to reconsider its config, and the only way `applyConfig` has
+ * anything new to apply.
+ */
+export async function loadConfig(root: string, options?: { fresh?: boolean }): Promise<FougereConfig> {
+  return loadConfigFrom(root, options?.fresh);
+}
+
+// ── Merging ──────────────────────────────────────
+
+/**
+ * Override a config with another, the invariant of every cascade level:
+ * scalar keys replace, but `remotes` (the topology) MERGES — an override adds
+ * or redirects a frond without erasing the others. Used for workspace→app and
+ * for global→CLI alike.
+ */
+function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): FougereConfig {
+  const merged: FougereConfig = { ...base, ...override };
+  if (base.remotes || override.remotes) {
+    merged.remotes = { ...base.remotes, ...override.remotes };
+  }
+  return merged;
+}
+
+/**
+ * Load config along the workspace→app frontier. The workspace-root config is
+ * the base (canonical topology: `remotes`, shared `db`); the app-root config
+ * overrides. Same `root` boundary the fronds already cascade along. When both
+ * roots resolve to the same dir (single app, no workspace), this is the plain
+ * root config — idempotent, no behavior change.
+ */
+export async function loadCascadedConfig(workspaceRoot: string, appRoot: string): Promise<FougereConfig> {
+  const base = await loadConfig(workspaceRoot);
+  if (resolve(workspaceRoot) === resolve(appRoot)) return base;
+  return mergeGlobal(base, await loadConfig(appRoot));
+}

package/src/contract/Call.ts

@@ -0,0 +1,18 @@
+import { Invocation, type InvocationInput } from './Invocation.js';
+import type { RouteAddress } from './RouteAddress.js';
+
+/** One normalized request: where it goes and what the caller supplied. */
+export class Call {
+  readonly address: RouteAddress;
+  readonly invocation: Invocation;
+
+  constructor(address: RouteAddress, invocation?: InvocationInput) {
+    this.address = address;
+    this.invocation = Invocation.from(invocation);
+    Object.freeze(this);
+  }
+
+  withInvocation(invocation: Invocation): Call {
+    return new Call(this.address, invocation);
+  }
+}