@fougere/core 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/boot/together.ts

@@ -1,18 +1,10 @@
-/**
- * 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, ormKeyOf, type EntityOrm, type OrmFactory } from '../orm.js';
-import type { Logger } from '../builtins/logger.js';
-import type { ProviderEntry } from '../scan/frond.js';
+import { membersOfTogetherKey, storageKeyOf, entityOfStorageKey, type Storage, type StorageFactory } from '../storage.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';
 
@@ -23,9 +15,11 @@ export interface FrameWorld {
   /** Which frond holds an entity — the question `remotes:` turns into a refusal. */
   frondOf: Map<string, string>;
   hostedHere: (frond: string) => boolean;
-  ormFactory?: OrmFactory;
+  storageFactory?: StorageFactory;
   sourceOf?: (entityName: string) => string;
-  transacted?: <R>(source: string, fn: (ormFactory: OrmFactory) => Promise<R>) => Promise<R>;
+  /** 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 ORM,
- * 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,19 +72,13 @@ 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.
- */
-function refuseUncoveredWrites(members: Members, key: string): void {
+/** 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) {
     for (const dep of provider.deps) {
-      if (!dep.endsWith('Orm')) continue;
-      const entity = lowerFirst(dep.slice(0, -'Orm'.length));
-      if (covered.has(entity)) continue;
+      const entity = entityOfStorageKey(dep, (name) => world.entityByName.has(name));
+      if (!entity || 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: ` +
@@ -112,45 +88,33 @@ function refuseUncoveredWrites(members: Members, key: string): void {
   }
 }
 
-/**
- * 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.
- */
+/** Open the block. */
 async function inScope<R>(
   parent: Container,
   members: Members,
-  factory: OrmFactory,
-  wrap: (orm: EntityOrm, name: string, schema: SchemaView) => EntityOrm,
+  factory: StorageFactory,
+  wrap: (storage: Storage, name: string, schema: SchemaView) => Storage,
   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;
+    const storages = members.entities.map((member) => {
+      const storage = wrap(factory(member.schema, member.name), member.name, member.schema);
+      scope.registerValue(storageKeyOf(member.name), storage);
+      return storage;
     });
-    // Providers after every ORM is in place: one may depend on another member's.
+    // Providers after every storage 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);
+    return await fn(storages, 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).
- */
+/** Register one frame per key a handler or provider of this frond asked for. */
 export function registerFrames(
   scope: Container,
   keys: Iterable<string>,
@@ -162,32 +126,34 @@ export function registerFrames(
     const names = membersOfTogetherKey(key);
     if (!names) continue;
     registered += 1;
-    if (!world.ormFactory) {
+    if (!world.storageFactory) {
       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);
+    refuseUncoveredWrites(members, key, world);
 
     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);
+    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,10 +162,10 @@ export function registerFrames(
     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);
+        const record = (storage: Storage, name: string, schema: SchemaView) =>
+          validator(recording(storage, name, schema, journal), name, schema);
         try {
-          return await inScope(scope, members, world.ormFactory!, record, fn as never);
+          return await inScope(scope, members, world.storageFactory!, record, fn as never);
         } catch (cause) {
           return unwind(journal, cause, world.log);
         }

package/src/boot/types.ts

@@ -1,15 +1,10 @@
-/**
- * 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 '../scan/Fronds.js';
-import type { FrondDescriptor, ScanResult } from '../scan/frond.js';
+import type { Fronds } from '../descriptor/Fronds.js';
+import type { FrondDescriptor } from '../descriptor/frond.js';
+import type { ScanResult } from '../scan/result.js';
 import type { SchemaView } from '@fougere/schema';
-import type { OrmFactory } from '../orm.js';
+import type { StorageFactory } from '../storage.js';
 import type { AppMiddleware } from '../wire/middleware.js';
 import type { RpcAnswer, Transport } from '../wire/call.js';
 import type { Extension } from './AppLifecycle.js';
@@ -22,107 +17,44 @@ import type { DispatchPort } from '../dispatch/DispatchPort.js';
 export interface CreateAppOptions {
   /** Factory function to create the container. Required. */
   createContainer: () => Container;
-  /** Factory to auto-generate EntityOrm for each scanned entity. */
-  ormFactory?: OrmFactory;
+  /** 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.
-   *
-   * 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.
+   * questions that decide whether `Together<[…]>` gets the engine's own unwind or replays inverses
+   * itself.
    */
   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.
-   */
+  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:`. */
   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[];
@@ -141,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>>;
@@ -156,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 `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.
+   * 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.
-   *
-   * 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(', ')}.`);