@fougere/core 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/boot/together.ts

@@ -1,17 +1,9 @@
-/**
- * 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.
- */
+/** Building a frame — what a handler asking for `Together<[…]>` receives. */
 import { ambient } from '#ambient';
 import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { Container } from '@fougere/container';
 import { membersOfTogetherKey, storageKeyOf, entityOfStorageKey, type Storage, type StorageFactory } from '../storage.js';
-import type { Logger } from '../builtins/logger.js';
+import type { Logger } from '../builtin/logger.js';
 import type { ProviderEntry } from '../descriptor/frond.js';
 import { StorageGuard } from '../dispatch/StorageGuard.js';
 import { recording, unwind, type Undo } from './frame.js';
@@ -25,6 +17,8 @@ export interface FrameWorld {
   hostedHere: (frond: string) => boolean;
   storageFactory?: StorageFactory;
   sourceOf?: (entityName: string) => string;
+  /** Whether that source hands one out — asked before the frame is built, not at the call. */
+  transacts?: (source: string) => boolean;
   transacted?: <R>(source: string, fn: (storageFactory: StorageFactory) => Promise<R>) => Promise<R>;
   log: Logger;
 }
@@ -35,14 +29,7 @@ interface Members {
   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.
- */
+/** Each declared name, resolved to what it designates. */
 function resolve(names: { entities: string[]; providers: string[] }, declared: readonly ProviderEntry[], world: FrameWorld): Members {
   const entities = names.entities.map((member) => {
     const name = lowerFirst(member);
@@ -71,12 +58,7 @@ function resolve(names: { entities: string[]; providers: string[] }, declared: r
   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 storage,
- * and a remote frond registers none. There is nothing to record and nothing to undo.
- */
+/** A member that cannot write here at all — its frond is hosted elsewhere. */
 function refuseRemote(members: Members, world: FrameWorld, key: string): void {
   for (const member of members.entities) {
     const frond = world.frondOf.get(member.name);
@@ -90,12 +72,7 @@ function refuseRemote(members: Members, world: FrameWorld, key: string): void {
   }
 }
 
-/**
- * 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.
- */
+/** A provider member writing an entity the frame does not name. */
 function refuseUncoveredWrites(members: Members, key: string, world: FrameWorld): void {
   const covered = new Set(members.entities.map((member) => member.name));
   for (const provider of members.providers) {
@@ -111,13 +88,7 @@ function refuseUncoveredWrites(members: Members, key: string, world: FrameWorld)
   }
 }
 
-/**
- * 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 storage 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.
- */
+/** Open the block. */
 async function inScope<R>(
   parent: Container,
   members: Members,
@@ -143,13 +114,7 @@ async function inScope<R>(
   }
 }
 
-/**
- * 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).
- */
+/** Register one frame per key a handler or provider of this frond asked for. */
 export function registerFrames(
   scope: Container,
   keys: Iterable<string>,
@@ -170,23 +135,25 @@ export function registerFrames(
     refuseUncoveredWrites(members, key, world);
 
     const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
-    const judge = (storage: Storage, name: string, schema: SchemaView) =>
+    const validator = (storage: Storage, name: string, schema: SchemaView) =>
       new StorageGuard(schema.getFields(), name).guard(storage);
 
-    // 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];
+    // One engine and a way into it: the engine gives the unwind AND the isolation. The
+    // question goes to the source these members live in — a composition answering for the
+    // default one would compensate a frame whose own engine holds transactions.
+    const source = sources.size === 1 ? [...sources][0]! : undefined;
+    if (world.transacted && source !== undefined && (world.transacts?.(source) ?? true)) {
       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))),
+            world.transacted!(source, (factory) => inScope(scope, members, factory, validator, 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
+    // of every write and replays the inverses itself. `validator` 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(', ')
@@ -196,7 +163,7 @@ export function registerFrames(
       run: <R>(fn: (entities: never, providers: never) => Promise<R>): Promise<R> => ambient.enterFrame(key, async () => {
         const journal: Undo[] = [];
         const record = (storage: Storage, name: string, schema: SchemaView) =>
-          judge(recording(storage, name, schema.getFields(), journal), name, schema);
+          validator(recording(storage, name, schema, journal), name, schema);
         try {
           return await inScope(scope, members, world.storageFactory!, record, fn as never);
         } catch (cause) {

package/src/boot/types.ts

@@ -1,10 +1,4 @@
-/**
- * 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.
- */
+/** The boot's two ends. */
 import type { Container } from '@fougere/container';
 import type { Fronds } from '../descriptor/Fronds.js';
 import type { FrondDescriptor } from '../descriptor/frond.js';
@@ -27,103 +21,40 @@ export interface CreateAppOptions {
   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.
-   *
-   * Optional together, because a host may hand in a bare `storageFactory` 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.
+   * 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>;
-  /**
-   * Builds the cross-source reader a frond gets when it declares `reads:`.
-   *
-   * A factory rather than a value, for the same reason `storageFactory` 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.
-   */
+  /** 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.
-   *
-   * `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.
-   */
+  /** 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] })`.
-   *
-   * 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.
-   */
+  /** 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. Wired by
-   * layer-2 packages (e.g. @fougere/transport-http); required when
-   * `remotes` is non-empty.
-   */
+  /** 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.
    */
   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.
-   */
+  /** 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.
-   *
-   * 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.
+   * 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`.
-   * Carried onto the App so every door reads one answer instead of each host
-   * deciding for itself.
-   */
+  /** 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.
-   *
-   * 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.
-   */
+  /** 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[];
@@ -142,13 +73,7 @@ export interface App extends DispatchPort {
   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".
-   */
+  /** 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>>;
@@ -157,113 +82,43 @@ export interface App extends DispatchPort {
   /** 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.
+   * 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 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.
-   */
+  /** The door 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. Check, explain and adapters read
-   * this table instead of replaying those decisions.
+   * 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.
-   *
-   * 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.
-   */
+  /** 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.
-   *
-   * 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.
-   */
+  /** 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}. `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 `Storage`
-   * is the caller saying which implementation they are standing on.
+   * 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.
-   *
-   * Same shape as {@link storageFor}, 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.
-   */
+  /** 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.
-   *
-   * 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.
-   */
+  /** 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 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.
-   */
+  /** 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.
-   *
-   * 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;
+  /** Declare one `rpc` op — what the app says about ITSELF, beside the card. */
+  serveRpc(operationName: 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;

package/src/{builtins → builtin}/config.ts

@@ -1,10 +1,4 @@
-/**
- * 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.
- */
+/** The process environment, as a service — so a handler asks for it rather than reading it. */
 export class Config {
   constructor(private readonly env: Record<string, string | undefined> = envOfProcess()) {}
 

package/src/{builtins → builtin}/logger.ts

@@ -1,18 +1,8 @@
-/**
- * Fougere Logger — structured, colored, multi-runtime.
- *
- * Works on Node, Bun, Deno, Cloudflare Workers (console-based, no native bindings).
- */
+/** Fougere Logger — structured, colored, multi-runtime. */
 
 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.
- */
+/** One line, before it was formatted for a terminal. */
 export interface LogRecord {
   level: Exclude<LogLevel, 'silent'>;
   /** The logger's own name — 'boot:app', 'boot:app:catalog'. */
@@ -25,12 +15,7 @@ export interface LogRecord {
 
 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.
- */
+/** Who else takes this process's log lines, beside the console. */
 const sinks: LogSink[] = [];
 
 /** Take every line this process logs. Returns the way to withdraw. */
@@ -44,34 +29,16 @@ export function onLog(next: LogSink): () => void {
 
 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.
- */
+/** The level, held ONCE for the process and CONSULTED at every emission. */
 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`.
- */
+/** The level the PROCESS was started with. */
 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.
- */
+/** Set the level for every logger in this process, at once. */
 export function setLogLevel(level: LogLevel): void {
   if (!(level in LEVELS)) {
     throw new Error(`Unknown log level: '${level}'. One of ${Object.keys(LEVELS).join(', ')}.`);

package/src/config-loader.ts

@@ -1,7 +1,7 @@
 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 { LogLevel } from './builtin/logger.js';
 import type { ConventionsInput } from './scan/conventions.js';
 import { getModuleLoader } from './loader.js';
 
@@ -10,68 +10,22 @@ import { getModuleLoader } from './loader.js';
 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.
-   */
+  /** The other places rows live — a name, an engine, and the entities it holds. */
   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.
+   * The names the scan reads instead of deriving them — the import scope, the fronds directory,
+   * the seven convention directories.
    */
   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).
-   */
+  /** How much every logger says. */
   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.
-   */
+  /** Which realization answers which port — port class name → implementation class name. */
   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.
-   */
+  /** Which protocol adapters this app serves. */
   adapters?: AdapterConfig;
 }
 
@@ -105,13 +59,7 @@ async function loadConfigFrom(dir: string, fresh?: boolean): Promise<FougereConf
   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.
- */
+/** Load the root fougere.config.{ts,js,mjs} from the given directory. */
 export async function loadConfig(root: string, options?: { fresh?: boolean }): Promise<FougereConfig> {
   return loadConfigFrom(root, options?.fresh);
 }
@@ -119,10 +67,9 @@ export async function loadConfig(root: string, options?: { fresh?: boolean }): P
 // ── 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.
+ * 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.
  */
 function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): FougereConfig {
   const merged: FougereConfig = { ...base, ...override };
@@ -132,13 +79,7 @@ function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): Fou
   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.
- */
+/** Load config along the workspace→app frontier. */
 export async function loadCascadedConfig(workspaceRoot: string, appRoot: string): Promise<FougereConfig> {
   const base = await loadConfig(workspaceRoot);
   if (resolve(workspaceRoot) === resolve(appRoot)) return base;