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

package/src/boot/remote.ts

@@ -3,11 +3,16 @@
  *
  * Documented: [the gradient](https://fougere.dev/docs/infra/gradient).
  */
-import type { FrondCall, Transport } from '../wire/call.js';
-import { assertIdentityCard, RPC_ENTITY } from '../wire/call.js';
-import { runMiddlewares, type AppMiddleware, type OperationContext } from '../wire/middleware.js';
-import { type InvocationContext, Invocation } from '../wire/Invocation.js';
-import { FougereError, ErrorCode } from '../wire/errors.js';
+import type { FrondCall } from '../wire/FrondCall.js';
+import type { Transport } from '../wire/Transport.js';
+import { RPC_ENTITY } from '../wire/RpcAnswer.js';
+import { assertIdentityCard } from '../wire/card/IdentityCard.js';
+import { runMiddlewares, type AppMiddleware } from '../wire/AppMiddleware.js';
+import { type OperationContext } from '../wire/OperationContext.js';
+import { Invocation } from '../wire/Invocation.js';
+import { type InvocationContext } from '../wire/InvocationContext.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 import { Card, type SchemaView, type SchemaDescriptor } from '@fougere/schema';
 import { dynamicOperations } from '../entry/facade.js';
 
@@ -35,7 +40,7 @@ export function createRemoteRouter(
   const pending = new Map(Object.entries(remotes));
   const transports = new Map<string, Transport>();
 
-  /** Which remote label claimed a door name — so a second claim can name the first. */
+  /** Which remote label claimed a facade name — so a second claim can name the first. */
   const claimedBy = new Map<string, string>();
 
   const discover = async (): Promise<void> => {
@@ -65,28 +70,28 @@ export function createRemoteRouter(
       const card = assertIdentityCard(answer, `Remote '${label}' (${url})`);
 
       for (const frond of card.fronds) {
-        // Doors only. A fact is not routable — nobody calls it, it arrives — so
-        // adding one here would answer a call with a transport to a door that
+        // Facades only. A fact is not routable — nobody calls it, it arrives — so
+        // adding one here would answer a call with a transport to a facade that
         // does not exist.
-        for (const door of frond.doors) {
-          const first = claimedBy.get(door.name);
+        for (const facade of frond.facades) {
+          const first = claimedBy.get(facade.name);
           /** Two remotes claiming one name is refused, not silently arbitrated. */
           if (first !== undefined && first !== label) {
             throw new FougereError({
               code: ErrorCode.INTERNAL_ERROR,
               message:
-                `Two remotes serve '${door.name}': '${first}' and '${label}'.\n`
+                `[claim] Two remotes serve '${facade.name}': '${first}' and '${label}'.\n`
                 + `  A call names an entity, not a frond, so nothing could choose between them.\n`
                 + `  - Keep one of the two out of \`remotes:\`, or\n`
                 + `  - expose one of them under a different entity name.`,
-              entity: door.name,
+              entity: facade.name,
             });
           }
-          claimedBy.set(door.name, label);
-          byEntity.set(door.name, {
+          claimedBy.set(facade.name, label);
+          byEntity.set(facade.name, {
             frond: frond.name,
             transport,
-            ...(door.schema ? { schema: Card.fromDescriptor(door.schema as SchemaDescriptor).toSchema() } : {}),
+            ...(facade.schema ? { schema: Card.fromDescriptor(facade.schema as SchemaDescriptor).toSchema() } : {}),
           });
         }
       }
@@ -101,13 +106,15 @@ export function createRemoteRouter(
       if (pending.size > 0) {
         throw new FougereError({
           code: ErrorCode.SERVICE_UNAVAILABLE,
-          message: `No reachable remote hosts '${entity}' — unreachable: ${[...pending.keys()].join(', ')}`,
+          message: `No reachable remote hosts '${entity}' — unreachable: ${[...pending.keys()].join(', ')}.\n`
+          + '  Named in `remotes:`, and did not answer.',
           entity,
         });
       }
       throw new FougereError({
         code: ErrorCode.NOT_FOUND,
-        message: `No declared remote hosts '${entity}'`,
+        message: `No declared remote hosts '${entity}'.\n`
+          + '  Nothing here serves it either — add its frond to `fronds:`/`scan:`, or name the frond that does in `remotes:`.',
         entity,
       });
     },

package/src/boot/runner.ts

@@ -1,6 +1,6 @@
 /** A Transport built from an app — the two ways a call enters this process. */
-import type { App } from './types.js';
-import type { Transport } from '../wire/call.js';
+import type { App } from './App.js';
+import type { Transport } from '../wire/Transport.js';
 import { createTransportEntry } from '../entry/transport.js';
 
 /** Build the local runner — the reference realization of Transport. */

package/src/boot/seed.ts

@@ -1,8 +1,10 @@
 import { Role } from '@fougere/schema';
-import { facadeKeyOf } from '../wire/call.js';
-import type { FrondDescriptor, SeedEntry, SeedFactory } from '../descriptor/frond.js';
-import type { App } from './types.js';
-import type { Extension } from './AppLifecycle.js';
+import { facadeKeyOf } from '../wire/Facade.js';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import type { SeedEntry } from '../descriptor/SeedEntry.js';
+import type { SeedFactory } from '../descriptor/SeedFactory.js';
+import type { App } from './App.js';
+import type { Extension } from './Extension.js';
 
 /** What the ordering satisfied, and what no order can. */
 export interface SeedOrder {
@@ -56,7 +58,7 @@ export function orderSeeds(fronds: FrondDescriptor[]): SeedOrder {
 }
 
 /** Where a seed writes, and what it may skip — resolved per entity. */
-interface SeedDoor {
+interface SeedFacade {
   list(): Promise<unknown[]>;
   write(item: unknown): Promise<unknown>;
 }
@@ -75,13 +77,13 @@ export async function runSeeds(
     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) {
+    const facade = facadeFor(app, seed.entityName);
+    if (!facade) {
       report(`  ${seed.entityName}: no handler façade nor storage — skipping seed`);
       continue;
     }
 
-    const existing = await door.list();
+    const existing = await facade.list();
     if (existing.length > 0) {
       report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
       continue;
@@ -91,7 +93,7 @@ export async function runSeeds(
     // key is exactly what a seed gets wrong.
     for (const item of data) {
       try {
-        await door.write(item);
+        await facade.write(item);
       } catch (cause) {
         throw new Error(
           `Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${(cause as Error)?.message ?? cause}`,
@@ -104,7 +106,7 @@ export async function runSeeds(
 }
 
 /** A seed is not a client. */
-function doorFor(app: App, entityName: string): SeedDoor | undefined {
+function facadeFor(app: App, entityName: string): SeedFacade | undefined {
   let handler: Record<string, Function> | undefined;
   try { handler = app.resolve<Record<string, Function>>(facadeKeyOf(entityName)); } catch {}
 

package/src/boot/statement-drift.ts

@@ -1,8 +1,9 @@
 /** Where a STATED contract and the signature it is about have stopped agreeing. */
-import type { FrondDescriptor, HandlerEntry } from '../descriptor/frond.js';
-import type { ScanDiagnostic } from '../scan.js';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
+import type { Diagnostic } from '../diagnostic.js';
 import type { BindingPlan } from '../wire/binding.js';
-import type { Signature } from '../wire/signature.js';
+import type { Signature } from '../wire/Signature.js';
 
 /** The parameters a binding plan names, against the ones the method declares. */
 function namesDisagreeing(plan: BindingPlan, signature: Signature): string[] {
@@ -12,8 +13,8 @@ function namesDisagreeing(plan: BindingPlan, signature: Signature): string[] {
 }
 
 /** What a frond's stated contracts no longer match. */
-export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): ScanDiagnostic[] {
-  const found: ScanDiagnostic[] = [];
+export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): Diagnostic[] {
+  const found: Diagnostic[] = [];
 
   for (const [name, override] of Object.entries(frond.operationsOverrides ?? {})) {
     if (!override.binding) continue;

package/src/boot/together.ts

@@ -6,11 +6,13 @@
 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/port.js';
-import type { Logger } from '../builtin/logger.js';
-import type { ProviderEntry } from '../descriptor/frond.js';
+import { entityOfStorageKey, membersOfTogetherKey, storageKeyOf, type Storage } from '../storage/Storage.js';
+import { type StorageFactory } from '../storage/StorageFactory.js';
+import type { Logger } from '../builtin/Logger.js';
+import type { ProviderEntry } from '../descriptor/ProviderEntry.js';
 import { StorageGuard } from '../dispatch/StorageGuard.js';
 import { recording, unwind, type Undo } from './frame.js';
+import type { Diagnostic } from '../diagnostic.js';
 
 /** Everything the boot knows that a frame needs, gathered once for every frond. */
 export interface FrameWorld {
@@ -33,61 +35,87 @@ interface Members {
   providers: ProviderEntry[];
 }
 
-/** 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) => {
+/** Each declared name, resolved to what it designates — or nothing, and why. */
+function resolve(
+  names: { entities: string[]; providers: string[] },
+  declared: readonly ProviderEntry[],
+  world: FrameWorld,
+  asked: Asked,
+  refused: Diagnostic[],
+): Members | undefined {
+  const before = refused.length;
+
+  const entities = names.entities.flatMap((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.`,
-      );
+      refused.push({
+        ...asked,
+        code: 'together-entity-unknown',
+        message: `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 [];
     }
-    return { name, schema };
+
+    return [{ name, schema }];
   });
 
-  const providers = names.providers.map((member) => {
+  const providers = names.providers.flatMap((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.`,
-      );
+      refused.push({
+        ...asked,
+        code: 'together-provider-unknown',
+        message: `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 [];
     }
-    return entry;
+
+    return [entry];
   });
 
-  return { entities, providers };
+  return refused.length === before ? { entities, providers } : undefined;
 }
 
+/** Who asked for the frame, and where they wrote it — the same three fields every refusal here carries. */
+type Asked = { severity: 'blocking'; filePath: string; subject: string };
+
 /** A member that cannot write here at all — its frond is hosted elsewhere. */
-function refuseRemote(members: Members, world: FrameWorld, key: string): void {
+function remoteMembers(members: Members, world: FrameWorld, asked: Asked, refused: Diagnostic[]): 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.`,
-      );
+      refused.push({
+        ...asked,
+        code: 'together-member-remote',
+        message: `'${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. */
-function refuseUncoveredWrites(members: Members, key: string, world: FrameWorld): void {
+function uncoveredWrites(members: Members, world: FrameWorld, asked: Asked, refused: Diagnostic[]): void {
   const covered = new Set(members.entities.map((member) => member.name));
   for (const provider of members.providers) {
     for (const dep of provider.deps) {
       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: ` +
-        `Together<[…, ${upperFirst(entity)}], [… ${provider.ctor.name} …]>.`,
-      );
+      refused.push({
+        ...asked,
+        filePath: provider.filePath,
+        code: 'together-write-uncovered',
+        message: `${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} …]>.`,
+      });
     }
   }
 }
@@ -121,22 +149,34 @@ async function inScope<R>(
 /** Register one frame per key a handler or provider of this frond asked for. */
 export function registerFrames(
   scope: Container,
-  keys: Iterable<string>,
+  wanted: Iterable<{ key: string; filePath: string }>,
   providers: readonly ProviderEntry[],
   world: FrameWorld,
+  refused: Diagnostic[],
 ): void {
   let registered = 0;
-  for (const key of new Set(keys)) {
+  const seen = new Set<string>();
+  for (const { key, filePath } of wanted) {
+    if (seen.has(key)) continue;
+    seen.add(key);
     const names = membersOfTogetherKey(key);
     if (!names) continue;
     registered += 1;
+    const asked = { severity: 'blocking', filePath, subject: key } as const;
     if (!world.storageFactory) {
-      throw new Error(`Together<[${names.entities.join(', ')}]> needs storage, and this boot declares none.`);
+      refused.push({
+        ...asked,
+        code: 'together-needs-storage',
+        message: `Together<[${names.entities.join(', ')}]> needs storage, and this boot declares none.`,
+      });
+      continue;
     }
 
-    const members = resolve(names, providers, world);
-    refuseRemote(members, world, key);
-    refuseUncoveredWrites(members, key, world);
+    const members = resolve(names, providers, world, asked, refused);
+    // Nothing left to build a frame out of, and the refusals above already say what is missing.
+    if (!members) continue;
+    remoteMembers(members, world, asked, refused);
+    uncoveredWrites(members, world, asked, refused);
 
     const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
     const validator = (storage: Storage, name: string, schema: SchemaView) =>

package/src/builtin/Carry.ts

@@ -0,0 +1,49 @@
+import type { LogRecord } from './LogRecord.js';
+
+/**
+ * Where one boot's lines wait, and where they go once they can.
+ *
+ * PER BOOT and never per process: two apps in one process each have their own
+ * destinations, and a slot shared between them sent the second app's lines to the first
+ * app's facade — measured on `demos/observability`, where only the first of three printed.
+ *
+ * A boot writes most of what a process ever logs, and it writes it before any emission is
+ * registered, so the lines that say what an app is made of are the ones a destination
+ * would miss. Bounded: a boot that never finishes must not grow, and what is dropped is
+ * the OLDEST since the lines explaining a refusal are the last.
+ */
+export class Carry {
+  private held: LogRecord[] = [];
+  private take?: (line: LogRecord) => void;
+
+  static readonly MAX = 500;
+
+  /** Take it now, or keep it for whoever arrives. */
+  push(record: LogRecord): void {
+    if (this.take) {
+      try {
+        this.take(record);
+      } catch { /* announcing never breaks logging, for the same reason a sink does not */ }
+      return;
+    }
+    this.held.push(record);
+    if (this.held.length > Carry.MAX) this.held.shift();
+  }
+
+  /** Hand what is held over, and everything after it. */
+  to(take: (line: LogRecord) => void): () => void {
+    this.take = take;
+    for (const line of this.held.splice(0)) take(line);
+
+    return () => { this.take = undefined; };
+  }
+
+  /**
+   * Forget what is still held — a boot that refused, or an app that declares no
+   * destination. Nothing is printed: the console had every one of these lines when it was
+   * written, and the hold exists only to hand them on later.
+   */
+  forget(): void {
+    this.held.length = 0;
+  }
+}

package/src/builtin/LogLevel.ts

@@ -0,0 +1 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';

package/src/builtin/LogRecord.ts

@@ -0,0 +1,12 @@
+import type { LogLevel } from './LogLevel.js';
+
+/** 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'. */
+  name: string;
+  message: string;
+  args: unknown[];
+  /** Epoch milliseconds. */
+  at: number;
+}

package/src/builtin/LogSink.ts

@@ -0,0 +1,4 @@
+import type { LogRecord } from './LogRecord.js';
+
+/** Where a line goes once it is written — `@fougere/log` ships one, `observability` another. */
+export type LogSink = (record: LogRecord) => void;

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

@@ -1,68 +1,8 @@
-/** Fougere Logger — structured, colored, multi-runtime. */
-
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
-
-/** 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'. */
-  name: string;
-  message: string;
-  args: unknown[];
-  /** Epoch milliseconds. */
-  at: number;
-}
-
-/** Where a line goes once it is written — `@fougere/log` ships one, `observability` another. */
-export type LogSink = (record: LogRecord) => void;
-
-/**
- * Where one boot's lines wait, and where they go once they can.
- *
- * PER BOOT and never per process: two apps in one process each have their own
- * destinations, and a slot shared between them sent the second app's lines to the first
- * app's door — measured on `demos/observability`, where only the first of three printed.
- *
- * A boot writes most of what a process ever logs, and it writes it before any emission is
- * registered, so the lines that say what an app is made of are the ones a destination
- * would miss. Bounded: a boot that never finishes must not grow, and what is dropped is
- * the OLDEST since the lines explaining a refusal are the last.
- */
-export class Carry {
-  private held: LogRecord[] = [];
-  private take?: (line: LogRecord) => void;
-
-  static readonly MAX = 500;
-
-  /** Take it now, or keep it for whoever arrives. */
-  push(record: LogRecord): void {
-    if (this.take) {
-      try {
-        this.take(record);
-      } catch { /* announcing never breaks logging, for the same reason a sink does not */ }
-      return;
-    }
-    this.held.push(record);
-    if (this.held.length > Carry.MAX) this.held.shift();
-  }
-
-  /** Hand what is held over, and everything after it. */
-  to(take: (line: LogRecord) => void): () => void {
-    this.take = take;
-    for (const line of this.held.splice(0)) take(line);
-
-    return () => { this.take = undefined; };
-  }
-
-  /**
-   * Forget what is still held — a boot that refused, or an app that declares no
-   * destination. Nothing is printed: the console had every one of these lines when it was
-   * written, and the hold exists only to hand them on later.
-   */
-  forget(): void {
-    this.held.length = 0;
-  }
-}
+import type { LogLevel } from './LogLevel.js';
+import type { LogRecord } from './LogRecord.js';
+import type { Carry } from './Carry.js';
+import type { LoggerOptions } from './LoggerOptions.js';
+import type { Rendered } from './Rendered.js';
 
 const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
 
@@ -125,19 +65,6 @@ function stamp(at: number | Date): string {
   return `${h}:${m}:${s}.${ms}`;
 }
 
-export interface LoggerOptions {
-  /** Logger name / prefix. */
-  name?: string;
-  /**
-   * Where its lines go — one boot's, so two apps in a process do not share a door. A
-   * logger without one writes to the console and nowhere else, which is what the boot's
-   * first lines do and what an app declaring no destination does forever.
-   */
-  carry?: Carry;
-  /** Force color on/off. Auto-detected by default. */
-  color?: boolean;
-}
-
 export class Logger {
   private name: string;
   private color: boolean;
@@ -176,26 +103,6 @@ export class Logger {
   }
 }
 
-/**
- * One line, ready for a terminal — the console arguments and which method takes them.
- *
- * Here rather than inside the class because the boot is not the only writer: a destination
- * that prints (`@fougere/log`) hands its own record to the same formatting, so the two
- * outputs cannot drift.
- *
- * 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.
- */
-export interface Rendered {
-  level: Exclude<LogLevel, 'silent'>;
-  name: string;
-  message: string;
-  /** Absent on most lines: a message usually carries its own detail. */
-  args?: unknown[] | null;
-  /** Epoch milliseconds from a logger, a `Date` from an entity that stamped it. */
-  at: number | Date;
-}
-
 export function formatted(
   record: Rendered,
   color = supportsColor(),

package/src/builtin/LoggerOptions.ts

@@ -0,0 +1,14 @@
+import type { Carry } from './Carry.js';
+
+export interface LoggerOptions {
+  /** Logger name / prefix. */
+  name?: string;
+  /**
+   * Where its lines go — one boot's, so two apps in a process do not share a facade. A
+   * logger without one writes to the console and nowhere else, which is what the boot's
+   * first lines do and what an app declaring no destination does forever.
+   */
+  carry?: Carry;
+  /** Force color on/off. Auto-detected by default. */
+  color?: boolean;
+}

package/src/builtin/Rendered.ts

@@ -0,0 +1,21 @@
+import type { LogLevel } from './LogLevel.js';
+
+/**
+ * One line, ready for a terminal — the console arguments and which method takes them.
+ *
+ * Here rather than inside the class because the boot is not the only writer: a destination
+ * that prints (`@fougere/log`) hands its own record to the same formatting, so the two
+ * outputs cannot drift.
+ *
+ * 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.
+ */
+export interface Rendered {
+  level: Exclude<LogLevel, 'silent'>;
+  name: string;
+  message: string;
+  /** Absent on most lines: a message usually carries its own detail. */
+  args?: unknown[] | null;
+  /** Epoch milliseconds from a logger, a `Date` from an entity that stamped it. */
+  at: number | Date;
+}