@fougere/core 0.8.3-alpha.0 → 0.9.0-alpha.0

package/src/boot/seed.ts

@@ -4,8 +4,15 @@ import type { FrondDescriptor, SeedEntry, SeedFactory } from '../descriptor/fron
 import type { App } from './types.js';
 import type { Extension } from './AppLifecycle.js';
 
+/** What the ordering satisfied, and what no order can. */
+export interface SeedOrder {
+  ordered: SeedEntry[];
+  /** Seeds whose `ref()` targets wait on each other — no order plants them all. */
+  cycle: SeedEntry[];
+}
+
 /** Seeds in dependency order — a `ref()` target is planted before its referrer. */
-export function orderSeeds(fronds: FrondDescriptor[]): SeedEntry[] {
+export function orderSeeds(fronds: FrondDescriptor[]): SeedOrder {
   const refs = new Map<string, Set<string>>();
   for (const frond of fronds) {
     for (const entity of frond.entities) {
@@ -45,7 +52,7 @@ export function orderSeeds(fronds: FrondDescriptor[]): SeedEntry[] {
     waiting.delete(ready);
   }
 
-  return [...ordered, ...waiting.keys()];
+  return { ordered, cycle: [...waiting.keys()] };
 }
 
 /** Where a seed writes, and what it may skip — resolved per entity. */
@@ -120,7 +127,15 @@ export function seeding(report?: (message: string) => void): Extension {
   return {
     name: 'seeds',
     up: async (app: App) => {
-      const seeds = orderSeeds(app.fronds);
+      const { ordered, cycle } = orderSeeds(app.fronds);
+      if (cycle.length > 0) {
+        report?.(
+          `  ${cycle.map((seed) => seed.entityName).join(', ')}: a ref() cycle, and no order `
+          + 'plants them all — planted in the order they are declared, and the source answers for the rest',
+        );
+      }
+
+      const seeds = [...ordered, ...cycle];
       if (seeds.length > 0) await runSeeds(app, seeds, report);
     },
   };

package/src/boot/statement-drift.ts

@@ -1,6 +1,6 @@
 /** 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/result.js';
+import type { ScanDiagnostic } from '../scan.js';
 import type { BindingPlan } from '../wire/binding.js';
 import type { Signature } from '../wire/signature.js';
 

package/src/boot/together.ts

@@ -2,7 +2,7 @@
 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 { 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 { StorageGuard } from '../dispatch/StorageGuard.js';

package/src/boot/types.ts

@@ -2,9 +2,9 @@
 import type { Container } from '@fougere/container';
 import type { Fronds } from '../descriptor/Fronds.js';
 import type { FrondDescriptor } from '../descriptor/frond.js';
-import type { ScanResult } from '../scan/result.js';
+import type { ScanResult } from '../scan.js';
 import type { SchemaView } from '@fougere/schema';
-import type { StorageFactory } from '../storage.js';
+import type { StorageFactory } from '../storage/port.js';
 import type { Constraint } from '../source.js';
 import type { AppMiddleware } from '../wire/middleware.js';
 import type { RpcAnswer, Transport } from '../wire/call.js';
@@ -28,6 +28,16 @@ export interface CreateAppOptions {
   sourceOf?: (entityName: string) => string;
   transacts?: (source: string) => boolean;
   transacted?: <R>(source: string, fn: (storageFactory: StorageFactory) => Promise<R>) => Promise<R>;
+  /**
+   * Bring the shape of what lives here up to date — a source's own gesture, declared on
+   * `Source.migrate` and handed over whole.
+   *
+   * Handed here rather than assembled by the host: four of them wrote
+   * `migrating(storage.migrate)` themselves, one of them as a string inside generated
+   * code, and eight demos wrote nothing — so they had no migration and nothing said it.
+   * The ASCENT is core's to order, since rows after tables is not a host's preference.
+   */
+  migrate?: (app: App) => Promise<void> | void;
   /** Whether that source refuses a constraint at the rows — the boot says so when it does not. */
   enforces?: (source: string, constraint: Constraint) => boolean;
   /** Builds the cross-source reader a frond gets when it declares `reads:`. */
@@ -47,7 +57,12 @@ export interface CreateAppOptions {
    * 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 answers a port. A string names the realization; a LIST is the chain, from the
+   * outside in — `['Retrying', 'Stripe']` puts `Retrying` in front of `Stripe`, and the
+   * last name is what actually charges.
+   */
+  ports?: Record<string, string | readonly string[]>;
   /** What this app takes on beyond its fronds, each stating what it does and what it undoes. */
   extensions?: readonly (Extension | undefined)[];
   /**

package/src/builtin/LogLine.ts

@@ -0,0 +1,38 @@
+import { entity, oneOf, text, json, list, optional, created } from '@fougere/schema';
+
+/**
+ * One line. A fact about the process, announced like any other — which is what makes a
+ * destination an ordinary handler and `remotes:` the only thing that decides where it runs.
+ *
+ * Here and not in `@fougere/log`, because the BOOT announces: core would otherwise have to
+ * name an optional package's entity to reach its own lines. What is optional is where a
+ * line GOES, and that is what `@fougere/log` ships.
+ *
+ * No `primary()`: an id costs 87 µs to generate (cuid2), and nothing addresses a line
+ * by one. `at` is `created()`, so announcing is what fills it.
+ */
+export default class LogLine extends entity({
+  level: oneOf('debug', 'info', 'warn', 'error'),
+  /** Who wrote it — 'app', 'app:catalog'. */
+  name: text(),
+  message: text({ min: 1 }),
+  /** What the writer passed beside the message — most lines pass none. */
+  args: optional(list(json())),
+  at: created(),
+}) {}
+
+/** The fact a boot announces, spelled once. */
+export const LOG_LINE = 'logLine';
+
+/**
+ * The addresses whose operations CARRY a line — every destination this app installed.
+ *
+ * Whatever carries a fact must not produce one, or the emission refuses it by name:
+ * keeping a line is a DISPATCH, so logging it announces a line inside the announcement of
+ * one. FILLED BY THE BOOT from what binds `logLine`, not written down — a hard-coded list
+ * cannot know a third party's destination, and the app already knows who subscribed.
+ *
+ * Read by `loggerMiddleware` and by `observability`'s `trace()`, both of which observe
+ * every operation and would otherwise observe the observation.
+ */
+export const CARRIES_LINE = new Set<string>();

package/src/builtin/logger.ts

@@ -18,6 +18,54 @@ export type LogSink = (record: LogRecord) => void;
 /** Who else takes this process's log lines, beside the console. */
 const sinks: LogSink[] = [];
 
+/**
+ * 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;
+  }
+}
+
 /** Take every line this process logs. Returns the way to withdraw. */
 export function onLog(next: LogSink): () => void {
   sinks.push(next);
@@ -79,8 +127,8 @@ function supportsColor(): boolean {
   return false;
 }
 
-function formatTime(): string {
-  const d = new Date();
+function stamp(at: number | Date): string {
+  const d = new Date(at);
   const h = String(d.getHours()).padStart(2, '0');
   const m = String(d.getMinutes()).padStart(2, '0');
   const s = String(d.getSeconds()).padStart(2, '0');
@@ -91,6 +139,12 @@ function formatTime(): string {
 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;
 }
@@ -98,15 +152,17 @@ export interface LoggerOptions {
 export class Logger {
   private name: string;
   private color: boolean;
+  private carry?: Carry;
 
   constructor(prefix?: string, options?: Omit<LoggerOptions, 'name'>) {
     this.name = prefix ?? 'app';
     this.color = options?.color ?? supportsColor();
+    this.carry = options?.carry;
   }
 
   /** 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 });
+    return new Logger(`${this.name}:${name}`, { color: this.color, ...(this.carry ? { carry: this.carry } : {}) });
   }
 
   debug(msg: string, ...args: unknown[]) { this.log('debug', msg, args); }
@@ -116,27 +172,63 @@ export class Logger {
 
   private log(level: string, msg: string, args: unknown[]) {
     if (LEVELS[level as LogLevel] < threshold) return;
+    const record: LogRecord = {
+      level: level as LogRecord['level'], name: this.name, message: msg, args, at: Date.now(),
+    };
 
     // 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() });
+        take(record);
       } 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);
-    }
+    this.carry?.push(record);
+
+    // The console ALWAYS, whoever else took the line. Skipping it once a destination
+    // existed made `calls()` — a devtools ring that prints nothing — silence the
+    // operator's terminal: 306 per-operation lines in `demos/observability` became 2.
+    // A destination sends a line ELSEWHERE; it does not take over stderr.
+    const { method, text } = formatted(record, this.color);
+    console[method](...text);
   }
 }
+
+/**
+ * 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(),
+): { method: Rendered['level']; text: unknown[] } {
+  const style = LEVEL_STYLE[record.level];
+  const time = stamp(record.at);
+  const method = record.level;
+
+  if (color) {
+    const c = COLORS[style.color];
+    const prefix = `${COLORS.dim}${time}${COLORS.reset} ${c}${COLORS.bold}${style.badge}${COLORS.reset} ${COLORS.magenta}${record.name}${COLORS.reset}`;
+
+    return { method, text: [prefix, record.message, ...(record.args ?? [])] };
+  }
+
+  return { method, text: [`${time} ${style.badge} [${record.name}]`, record.message, ...(record.args ?? [])] };
+}

package/src/config-loader.ts

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 import type { AuthConfig } from './boot/auth.js';
 import type { LogLevel } from './builtin/logger.js';
-import type { ConventionsInput } from './scan/conventions.js';
+import type { ConventionsInput } from './conventions.js';
 import { getModuleLoader } from './loader.js';
 
 // ── Types ────────────────────────────────────────
@@ -22,7 +22,8 @@ export interface FougereConfig {
   /** Remote fronds — frondName → base URL. */
   remotes?: Record<string, string>;
   /** Which realization answers which port — port class name → implementation class name. */
-  ports?: Record<string, string>;
+  /** What answers a port — a name, or the chain from the outside in. */
+  ports?: Record<string, string | readonly string[]>;
   /** Auth declaration — picks a provider package and forwards options to it. */
   auth?: AuthConfig;
   /** Which protocol adapters this app serves. */

package/src/contract.ts

@@ -3,25 +3,21 @@
  * runtime: the error vocabulary, the invocation shape, the call value, the naming convention.
  */
 import { lowerFirst } from '@fougere/schema';
-import { canonicalInvocation, type InvocationContext } from './wire/Invocation.js';
+import { Invocation, type InvocationContext } from './wire/Invocation.js';
 import type { FrondCall } from './wire/call.js';
 
 export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
 // What a read may ask about one field. Here rather than on the main entry because an
 // adapter reads it to compile a query, and an adapter carries no boot.
-export { comparisonOf, comparisonsIn, unknownIn, COMPARISONS } from './criterion.js';
-export type { Comparison, ComparisonName } from './criterion.js';
+export { comparisonOf, comparisonsIn } from './storage/criterion.js';
+export type { Comparison } from './storage/criterion.js';
 // A receiver turns a refusal into what may cross a process boundary, and it is not
 // core's boot — reaching it through the main entry dragged the scanner into a bundle.
 export { toPublicError } from './wire/http-error.js';
-export type { FougereErrorOptions } from './wire/errors.js';
-export { canonicalInvocation, EMPTY_INVOCATION } from './wire/Invocation.js';
-export type { InvocationContext } from './wire/Invocation.js';
 export { Invocation } from './wire/Invocation.js';
-export type { PartialInvocation } from './wire/Invocation.js';
+export type { InvocationContext } from './wire/Invocation.js';
 export { Call } from './wire/call.js';
 export { RouteAddress } from './wire/RouteAddress.js';
-export type { RouteAddressInput } from './wire/RouteAddress.js';
 export type { FrondCall, Transport, SignedCall } from './wire/call.js';
 export { MAX_BODY_BYTES } from './wire/call.js';
 // The reserved entity, VALUE and not type: a consumer that wants to leave it alone — a
@@ -59,5 +55,5 @@ export function callValueOf(
     typeof opOrInput === 'string'
       ? [{ entity: lowerFirst((target as { name: string }).name), op: opOrInput }, input]
       : [target as FrondCall, opOrInput];
-  return { call, invocation: canonicalInvocation(given) };
+  return { call, invocation: Invocation.from(given) };
 }

package/src/{scan/conventions.ts → conventions.ts}

@@ -14,6 +14,12 @@ export interface Conventions {
     presenters: string;
     collectors: string;
     seeds: string;
+    /**
+     * What runs around this frond's operations. Scoped to the frond that declares it,
+     * unless `frond.config.ts` widens it — the one directory whose members apply to code
+     * they do not name.
+     */
+    middlewares: string;
     /**
      * What the domain computes with nothing injected. Read into the type program, because
      * a handler names one of its types in a signature, and registered nowhere: no class
@@ -37,6 +43,7 @@ export const DEFAULT_CONVENTIONS: Conventions = {
     presenters: 'presenters',
     collectors: 'collectors',
     seeds: 'seeds',
+    middlewares: 'middlewares',
     rules: 'rules',
     versions: 'versions',
   },
@@ -70,9 +77,9 @@ export function providerDirsOf(conventions: Conventions): string[] {
 
 /** The frond vocabulary — every directory the scan reads. */
 export function frondDirsOf(conventions: Conventions): string[] {
-  const { entities, handlers, presenters, collectors, seeds, rules, versions } = conventions.dirs;
+  const { entities, handlers, presenters, collectors, seeds, middlewares, rules, versions } = conventions.dirs;
   return [...new Set([
-    entities, handlers, presenters, collectors, seeds, rules, versions,
+    entities, handlers, presenters, collectors, seeds, middlewares, rules, versions,
     ...providerDirsOf(conventions),
   ])];
 }

package/src/crypto/encoding.ts

@@ -24,13 +24,6 @@ export function unb64url(input: string): Uint8Array {
 }
 
 /** Plain base64, padded — what an environment variable carries a PEM as. */
-export function b64(input: Uint8Array | string): string {
-  const bytes = typeof input === 'string' ? bytesOf(input) : input;
-  let binary = '';
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary);
-}
-
 export const unb64 = (input: string): Uint8Array => {
   const binary = atob(input);
   const bytes = new Uint8Array(binary.length);

package/src/declare.ts

@@ -1,10 +1,10 @@
 /** A frond stated by its author, for an app that will not scan. */
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 import type {
-  CollectorEntry, EntityEntry, FrondDescriptor, HandlerEntry,
+  CollectorEntry, EntityEntry, FrondDescriptor, HandlerEntry, MiddlewareEntry,
   PresenterEntry, ProviderEntry, SeedEntry,
 } from './descriptor/frond.js';
-import { DEFAULT_CONVENTIONS } from './scan/conventions.js';
+import { DEFAULT_CONVENTIONS } from './conventions.js';
 import { getPresenterFields } from './prefab/presenter.js';
 import type { OperationContract } from './wire/operation.js';
 
@@ -90,6 +90,14 @@ export interface FrondDeclaration {
   collectors?: (Ctor | DeclaredSubject)[];
   providers?: Declared[];
   seeds?: { entityName: string; data: SeedEntry['data'] }[];
+  /**
+   * What runs around this frond's operations. The scope is stated beside the class here,
+   * where `frond.config.ts` states it by class name — a statement has no config file to
+   * put it in.
+   */
+  middlewares?: (Ctor | (DeclaredSubject & { scope?: MiddlewareEntry['scope'] }))[];
+  /** The ops that finish a fact, in order — the same key `frond.config.ts` states. */
+  pipes?: Record<string, string[]>;
   /** Per-surface entity lists — the same key `frond.config.ts` states. */
   surfaces?: Record<string, string[]>;
   /** The import scope this frond answers under. Defaults to the conventional one. */
@@ -179,6 +187,14 @@ export function frond(name: string, declared: FrondDeclaration = {}): FrondDescr
     filePath: '',
   }));
 
+  const middlewares: MiddlewareEntry[] = (declared.middlewares ?? []).map((m) => ({
+    name: ctorOf(m).name,
+    ctor: ctorOf(m),
+    scope: (typeof m === 'function' ? undefined : m.scope) ?? 'frond',
+    deps: depsOf(m),
+    filePath: '',
+  }));
+
   return {
     name,
     source: { path: '', package: `${scope}/${name}` },
@@ -189,6 +205,8 @@ export function frond(name: string, declared: FrondDeclaration = {}): FrondDescr
     presenters,
     collectors,
     seeds,
+    middlewares,
+    ...(declared.pipes ? { pipes: declared.pipes } : {}),
     ...(declared.surfaces ? { surfaces: declared.surfaces } : {}),
   };
 }

package/src/descriptor/frond.ts

@@ -112,6 +112,23 @@ export interface CollectorEntry {
   filePath: string;
 }
 
+/**
+ * A discovered middleware — a class declaring `around(ctx, next)`, which runs before and
+ * after every operation in its scope.
+ */
+export interface MiddlewareEntry {
+  /** Class name — what `frond.config.ts` addresses to widen the scope. */
+  name: string;
+  /** The middleware class. */
+  ctor: new (...args: never[]) => unknown;
+  /** How far it reaches: its own frond's entities, or every operation in the process. */
+  scope: 'frond' | 'app';
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}
+
 /** A discovered seed file (array of records or async factory). */
 export interface SeedEntry {
   /** Entity name this seed targets (from filename: Author.seed.ts → 'author'). */
@@ -142,6 +159,16 @@ export interface FrondDescriptor {
   presenters: PresenterEntry[];
   collectors: CollectorEntry[];
   seeds: SeedEntry[];
+  middlewares: MiddlewareEntry[];
+  /**
+   * Brought by an EXTENSION rather than by the app — `@fougere/calls` keeping its lines,
+   * `@fougere/observability` sending them on. It is installed like any other, and it is not
+   * what the app SERVES: a report that lists it describes the instrumentation, not the
+   * domain. Set by the boot, never by a declaration.
+   */
+  brought?: true;
+  /** The ops that finish a fact, in order — see `FrondConfig.pipes`. */
+  pipes?: Record<string, string[]>;
   /**
    * Per-surface entity lists from frond.config.ts (e.g. { graphql: ['Post'], rest: ['Post',
    * 'Author'] }).
@@ -156,5 +183,9 @@ export interface FrondDescriptor {
     handlerName?: string;
     /** Method name on the resolved handler (defaults to op name). */
     method?: string;
+    /** The GraphQL root field this op answers to — read by `adapter/graphql`. */
+    graphql?: string;
+    /** Where it answers over REST — read by `adapter/rest`, the dual of `graphql`. */
+    rest?: { method?: string; path?: string; status?: number };
   }>;
 }

package/src/descriptor/index.ts

@@ -0,0 +1,15 @@
+/**
+ * What it takes to PRODUCE a descriptor — the surface a scan reads, whoever wrote it.
+ * The main entry serves what an app RUNS; this one serves what fills it in.
+ */
+export * from './frond.js';
+export { Fronds } from './Fronds.js';
+
+export { cardinalityOf, type OperationContract, type OperationsMap, type Param, type TypeRef } from '../wire/operation.js';
+export { computeBindingPlan, type BindingPlan } from '../wire/binding.js';
+export type { Signature } from '../wire/signature.js';
+export { emitKeyOf, awaitKeyOf } from '../wire/emit.js';
+export { storageKeyOf } from '../storage/port.js';
+export { getPresenterFields } from '../prefab/presenter.js';
+export { targetOf, viewsOf, outputOf } from '../prefab/prefab.js';
+export { ownedBy, repositoryKeyOf } from '../prefab/repository.js';

package/src/descriptor/surface.ts

@@ -0,0 +1,23 @@
+import type { FrondDescriptor, HandlerEntry } from './frond.js';
+
+/**
+ * The surfaces a handler answers on — its own when it has one, otherwise the default
+ * and every surface that names its address without opening a door of its own.
+ * `undefined` is the default surface, as `facadeKeyOf` and `RouteAddress` spell it.
+ */
+export function servedSurfaces(
+  frond: FrondDescriptor,
+  handler: HandlerEntry,
+): (string | undefined)[] {
+  if (handler.surface) return [handler.surface];
+
+  const declared = Object.entries(frond.surfaces ?? {})
+    .filter(([surface, addresses]) =>
+      addresses.some((address) => address.toLowerCase() === handler.address.toLowerCase())
+      && !frond.handlers.some((other) =>
+        other.address === handler.address && other.surface === surface))
+    .map(([surface]) => surface)
+    .sort();
+
+  return [undefined, ...declared];
+}

package/src/dispatch/ArgumentResolver.ts

@@ -38,8 +38,12 @@ export class ArgumentResolver {
           args.push(val);
           break;
         }
-        case 'fact': {
-          // A fact IS the payload — the whole of what happened, never a piece of it.
+        case 'fact':
+        case 'pipe': {
+          // A fact IS the payload — the whole of what happened, never a piece of it. The
+          // same holds before it is final: an op that finishes one is handed all of it,
+          // and answers all of it.
+          //
           // Identical to `input` today, and deliberately not sharing its branch: the two
           // agree by coincidence, not by rule, and the day `input` learns to look up a
           // value by parameter name a subscriber would receive ONE FIELD of the fact it

package/src/dispatch/HandlerFacade.ts

@@ -12,12 +12,13 @@ import { presenterKeyOf } from '../prefab/presenter.js';
 import { repositoryKeyOf } from '../prefab/repository.js';
 import type { OperationContract, OperationsMap } from '../wire/operation.js';
 import type { EffectiveOperation, EffectiveOperationsMap } from '../effective-operation.js';
-import { canonicalInvocation, type InvocationContext } from '../wire/Invocation.js';
+import type { BindingPlan } from '../wire/binding.js';
+import { Invocation, type InvocationContext } from '../wire/Invocation.js';
 import type { HandlerEntry, PresenterEntry } from '../descriptor/frond.js';
 import { ArgumentResolver } from './ArgumentResolver.js';
 import { OutputView } from './OutputView.js';
 import { PresenterExecutor } from './PresenterExecutor.js';
-import { presenterArguments } from './presenterArguments.js';
+import { presenterArguments, presenterPlans } from './presenterArguments.js';
 import { validateInput } from './validateInput.js';
 
 /** What boot resolved around one handler, beyond the handler and the scope it resolves in. */
@@ -54,6 +55,8 @@ export class HandlerFacade {
   private readonly arguments = new ArgumentResolver(
     (typeName) => this.collectorResolver(typeName),
   );
+  /** A computed field's parameters and the collectors in scope are both boot-time facts. */
+  private readonly presenterPlans: Map<string, BindingPlan>;
 
   constructor(
     private readonly handler: HandlerEntry,
@@ -62,6 +65,10 @@ export class HandlerFacade {
   ) {
     this.refuseCrudWithoutRepository(handler);
 
+    this.presenterPlans = door.presenter
+      ? presenterPlans(door.presenter, door.collectors)
+      : new Map();
+
     scope.register(this.handlerKey, handler.ctor, { deps: this.depsOf(handler) });
 
     this.effectiveOperations = door.operations;
@@ -94,7 +101,7 @@ export class HandlerFacade {
       );
     }
 
-    const invocation = canonicalInvocation(input);
+    const invocation = Invocation.from(input);
     const context: OperationContext = {
       entity,
       frond: this.door.frond,
@@ -135,7 +142,7 @@ export class HandlerFacade {
       op,
     );
 
-    return presenterArguments(presenter, invocation, this.arguments, this.door.collectors)
+    return presenterArguments(this.presenterPlans, invocation, this.arguments)
       .then((args) => executor.present(output, args));
   }