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

package/src/contract.ts

@@ -3,38 +3,57 @@
  * runtime: the error vocabulary, the invocation shape, the call value, the naming convention.
  */
 import { lowerFirst } from '@fougere/schema';
-import { Invocation, type InvocationContext } from './wire/Invocation.js';
-import type { FrondCall } from './wire/call.js';
+import { Invocation } from './wire/Invocation.js';
+import { type InvocationContext } from './wire/InvocationContext.js';
+import type { FrondCall } from './wire/FrondCall.js';
 
-export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
+export { ErrorCode } from './wire/ErrorCode.js';
+export { FougereError, validationErrorsOf } from './wire/FougereError.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 } from './storage/criterion.js';
-export type { Comparison } from './storage/criterion.js';
+export { comparisonOf, comparisonsIn } from './storage/Comparison.js';
+export type { Comparison } from './storage/Comparison.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 { Invocation } from './wire/Invocation.js';
-export type { InvocationContext } from './wire/Invocation.js';
-export { Call } from './wire/call.js';
+export type { InvocationContext } from './wire/InvocationContext.js';
+export { Call } from './wire/Call.js';
 export { RouteAddress } from './wire/RouteAddress.js';
-export type { FrondCall, Transport, SignedCall } from './wire/call.js';
-export { MAX_BODY_BYTES } from './wire/call.js';
+export type { FrondCall } from './wire/FrondCall.js';
+export type { SignedCall } from './wire/SignedCall.js';
+export type { Transport } from './wire/Transport.js';
+export { MAX_BODY_BYTES } from './wire/SignedCall.js';
 // The reserved entity, VALUE and not type: a consumer that wants to leave it alone — a
 // call log ignoring its own reader — has to be able to name it.
-export { RPC_ENTITY } from './wire/call.js';
-export type { CallPage, CallRecord } from './wire/CallLog.js';
+export { RPC_ENTITY } from './wire/RpcAnswer.js';
+export type { CallPage } from './wire/CallPage.js';
+export type { CallRecord } from './wire/CallRecord.js';
 // The comparison of two cards, which a consumer runs about a producer — browser-safe on
 // purpose: a panel showing the drift holds only the two cards, never the app.
 export { driftOf, agrees, explain } from './wire/drift.js';
 export type { CardDrift } from './wire/drift.js';
 
 /** What `rpc.discover` answers. */
-export type {
-  IdentityCard, CardOp, TopologyReport, FrondPlacement, Edge,
-  DeclaredTopology, DeclaredFrond, DeclaredEdge,
-} from './wire/call.js';
-export { assertIdentityCard } from './wire/call.js';
+export { refusalsOf, type Refusable } from './wire/refusals.js';
+export type { Addresses } from './wire/Addresses.js';
+export type { Answer } from './wire/Answer.js';
+export type { AnyHandler } from './wire/AnyHandler.js';
+export type { FacadeName } from './wire/FacadeName.js';
+export type { FougereHandlers } from './wire/FougereHandlers.js';
+export type { FougereOperations } from './wire/FougereOperations.js';
+export type { HandlerOf } from './wire/HandlerOf.js';
+export type { Refused } from './wire/Refused.js';
+export type { Rows } from './wire/Rows.js';
+export type { CardOp } from './wire/card/CardOp.js';
+export type { IdentityCard } from './wire/card/IdentityCard.js';
+export type { DeclaredEdge } from './wire/topology/DeclaredEdge.js';
+export type { DeclaredFrond } from './wire/topology/DeclaredFrond.js';
+export type { DeclaredTopology } from './wire/topology/DeclaredTopology.js';
+export type { Edge } from './wire/topology/Edge.js';
+export type { FrondPlacement } from './wire/topology/FrondPlacement.js';
+export type { TopologyReport } from './wire/topology/TopologyReport.js';
+export { assertIdentityCard } from './wire/card/IdentityCard.js';
 
 /** The key a class name is filed under — 'Post' → 'post'. */
 export { lowerFirst } from '@fougere/schema';

package/src/crypto/CryptoPort.ts

@@ -0,0 +1,12 @@
+import type { Signer } from './Signer.js';
+import type { Verifier } from './Verifier.js';
+import type { PublicJwk } from './PublicJwk.js';
+
+export interface CryptoPort {
+  /** SHA-256. What binds an input to an envelope without carrying the input. */
+  sha256(data: Uint8Array): Promise<Uint8Array>;
+  /** From a PKCS#8 PEM — what `fougere keys` writes. */
+  signerOf(privateKeyPem: string): Promise<Signer>;
+  /** From an SPKI PEM (the root's) or a JWK (the one a grant embeds). */
+  verifierOf(key: string | PublicJwk): Promise<Verifier>;
+}

package/src/crypto/PublicJwk.ts

@@ -0,0 +1,7 @@
+/** A public key as a grant carries it — `{ kty: 'OKP', crv: 'Ed25519', x }`. */
+export interface PublicJwk {
+  kty: string;
+  crv?: string;
+  x?: string;
+  [key: string]: unknown;
+}

package/src/crypto/Signer.ts

@@ -0,0 +1,4 @@
+/** A parsed private key. */
+export interface Signer {
+  sign(data: Uint8Array): Promise<Uint8Array>;
+}

package/src/crypto/Verifier.ts

@@ -0,0 +1,5 @@
+/** A parsed public key. */
+export interface Verifier {
+  /** False, never a throw: a bad signature is an answer, not a failure. */
+  verify(data: Uint8Array, signature: Uint8Array): Promise<boolean>;
+}

package/src/crypto/node.ts

@@ -1,6 +1,9 @@
 /** Ed25519 through `node:crypto` — the default realization, and the fast one. */
 import { createHash, createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
-import type { CryptoPort, PublicJwk, Signer, Verifier } from './port.js';
+import type { CryptoPort } from './CryptoPort.js';
+import type { PublicJwk } from './PublicJwk.js';
+import type { Signer } from './Signer.js';
+import type { Verifier } from './Verifier.js';
 
 export const crypto: CryptoPort = {
   async sha256(data) {

package/src/crypto/webcrypto.ts

@@ -1,6 +1,9 @@
 /** Ed25519 through WebCrypto — what a runtime with no `node:` builtin has. */
 import { derOf } from './encoding.js';
-import type { CryptoPort, PublicJwk, Signer, Verifier } from './port.js';
+import type { CryptoPort } from './CryptoPort.js';
+import type { PublicJwk } from './PublicJwk.js';
+import type { Signer } from './Signer.js';
+import type { Verifier } from './Verifier.js';
 
 interface WebSubtle {
   digest(algorithm: string, data: Uint8Array): Promise<ArrayBuffer>;

package/src/define.ts

@@ -1,4 +1,4 @@
-import type { FougereConfig } from './config-loader.js';
+import type { FougereConfig } from './FougereConfig.js';
 
 /**
  * Identity helper for fougere.config.ts — preserves literal types for autocomplete while

package/src/descriptor/CollectorEntry.ts

@@ -0,0 +1,11 @@
+/** A discovered collector (resolves handler input params from invocation context). */
+export interface CollectorEntry {
+  /** Registration key of the TYPE this collector resolves — 'user', 'ability'. */
+  typeName: string;
+  /** The collector class. */
+  ctor: new (...args: never[]) => unknown;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/EntityEntry.ts

@@ -0,0 +1,13 @@
+import type { SchemaView } from '@fougere/schema';
+
+/** A discovered entity (Entity subclass in entities/ dir). */
+export interface EntityEntry {
+  /** Registration key: class name lowercased first char (e.g. 'product'). */
+  name: string;
+  /** The Entity class (has static getFields()). */
+  entityClass: SchemaView;
+  /** Absolute file path (for debugging). */
+  filePath: string;
+  /** Whether this entity is part of the frond's public contract. */
+  exposed?: boolean;
+}

package/src/descriptor/ExtensionEntry.ts

@@ -0,0 +1,15 @@
+/**
+ * An extension this frond declares — what rises and falls with the process, written beside the
+ * code it instruments.
+ *
+ * It travels with its frond: moved behind `remotes:`, it mounts on the process serving it there,
+ * which is why no key widens it. What must be everywhere is a frond that is everywhere, which
+ * `Extension.fronds` already answers.
+ */
+export interface ExtensionEntry {
+  /** Its own `name`, or the file's — the ascent REPLACES a name already declared. */
+  name: string;
+  /** The value handed to the ascent, the same shape `CreateAppOptions.extensions` takes. */
+  extension: { name?: string; up?: (app: never) => void | Promise<void>; down?: (app: never) => void | Promise<void> };
+  filePath: string;
+}

package/src/descriptor/FrondDescriptor.ts

@@ -0,0 +1,58 @@
+import type { OperationContract } from '../wire/OperationContract.js';
+import type { ProviderEntry } from './ProviderEntry.js';
+import type { EntityEntry } from './EntityEntry.js';
+import type { HandlerEntry } from './HandlerEntry.js';
+import type { PresenterEntry } from './PresenterEntry.js';
+import type { CollectorEntry } from './CollectorEntry.js';
+import type { MiddlewareEntry } from './MiddlewareEntry.js';
+import type { SeedEntry } from './SeedEntry.js';
+import type { FrondSource } from './FrondSource.js';
+import type { ExtensionEntry } from './ExtensionEntry.js';
+
+/**
+ * The key a provider answers under. What the source said, and the class's own name only
+ * where nobody wrote it down — a statement is read as code, and code can say it.
+ */
+export const nameOf = (provider: ProviderEntry): string => provider.name ?? provider.ctor.name;
+
+export interface FrondDescriptor {
+  name: string;
+  source: FrondSource;
+  providers: ProviderEntry[];
+  entities: EntityEntry[];
+  handlers: HandlerEntry[];
+  presenters: PresenterEntry[];
+  collectors: CollectorEntry[];
+  seeds: SeedEntry[];
+  middlewares: MiddlewareEntry[];
+  /** What this frond mounts on the process that serves it. Absent when it declares none. */
+  extensions?: ExtensionEntry[];
+  /**
+   * 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'] }).
+   */
+  surfaces?: Record<string, string[]>;
+  /** Entities this frond may read across sources — see `FrondConfig.reads`. */
+  reads?: string[];
+  /** Per-operation overrides from frond.config.ts. */
+  operationsOverrides?: Record<string, OperationContract & {
+    kind?: 'query' | 'command';
+    /** Class name to resolve from DI (overrides default `{Entity}Handler` lookup). */
+    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/FrondSource.ts

@@ -0,0 +1,7 @@
+/** Where a frond lives on disk. */
+export interface FrondSource {
+  /** Absolute path to the frond directory. */
+  path: string;
+  /** The @fronds/{name} package name. Always present. */
+  package: string;
+}

package/src/descriptor/Fronds.ts

@@ -1,5 +1,6 @@
 import type { SchemaView } from '@fougere/schema';
-import type { EntityEntry, FrondDescriptor } from './frond.js';
+import type { EntityEntry } from './EntityEntry.js';
+import type { FrondDescriptor } from './FrondDescriptor.js';
 
 /** What this app hosts, with the questions everyone was asking it by hand. */
 export class Fronds extends Array<FrondDescriptor> {

package/src/descriptor/HandlerEntry.ts

@@ -0,0 +1,27 @@
+import type { SchemaView } from '@fougere/schema';
+import type { OperationsMap } from '../wire/OperationsMap.js';
+
+/** A discovered handler (controls what a service exposes). */
+export interface HandlerEntry {
+  /** Registration key (e.g. 'postHandler'). */
+  name: string;
+  /**
+   * The name this handler answers to — its class name minus `Handler`, lowercased (`PostHandler` →
+   * `post`).
+   */
+  address: string;
+  /** The handler class. */
+  ctor: new (...args: never[]) => unknown;
+  /** All operations with full signatures for binding. */
+  operations: OperationsMap;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+  /** Whether this handler is part of the frond's public contract. */
+  exposed?: boolean;
+  /** Output schema override — when Crud(Entity, Output), restricts storage output. */
+  outputOverride?: SchemaView;
+  /** Surface name — subdirectory in handlers/ (e.g. 'admin', 'public'). */
+  surface?: string;
+}

package/src/descriptor/MiddlewareEntry.ts

@@ -0,0 +1,16 @@
+/**
+ * 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;
+}

package/src/descriptor/PresenterEntry.ts

@@ -0,0 +1,23 @@
+import type { PresenterViews } from '../prefab/presenter.js';
+import type { PresenterFieldMeta } from './PresenterFieldMeta.js';
+
+/** A discovered presenter (computed fields for an entity's output). */
+export interface PresenterEntry {
+  /** Entity name this presenter enriches (e.g. 'post' from PostPresenter). */
+  entityName: string;
+  /** The presenter class. */
+  ctor: new (...args: never[]) => unknown;
+  /** Computed field names (method names on prototype). */
+  fields: string[];
+  /** Per-field type metadata (inferred from source via parser). */
+  fieldMeta: PresenterFieldMeta[];
+  /**
+   * The view each computed field emits, when the presenter declares one (`Presenter(Order, {
+   * items: [OrderItemView] })`).
+   */
+  views?: PresenterViews;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/PresenterFieldMeta.ts

@@ -0,0 +1,14 @@
+import type { Param } from '../wire/Param.js';
+
+/** Return type metadata for a presenter computed field. */
+export interface PresenterFieldMeta {
+  name: string;
+  /** Inferred return type name: 'string', 'number', 'boolean', or a class name. */
+  returnType?: string;
+  /** The field emits a LIST per row — `tags(posts: Post[]): string[][]`. */
+  list?: boolean;
+  /** Whether the return is nullable. */
+  nullable?: boolean;
+  /** The declared parameters AFTER the rows. */
+  params?: Param[];
+}

package/src/descriptor/ProviderEntry.ts

@@ -0,0 +1,18 @@
+/** A discovered provider — a class under `services/` or `repositories/`, injected by type. */
+export interface ProviderEntry {
+  /**
+   * The container key — the class name as the SOURCE spells it.
+   *
+   * Read at boot off `ctor.name` for a decade of no consequence, until a bundler lowered
+   * a `static readonly` field and renamed the declaration doing it: the provider
+   * registered as `_Communes` and the handler asking for `Communes` got a container miss.
+   * A name a tool may rewrite is written down, for the same reason `deps` is.
+   */
+  name?: string;
+  /** The class constructor (default export of the file). */
+  ctor: new (...args: never[]) => unknown;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/SeedEntry.ts

@@ -0,0 +1,11 @@
+import type { SeedFactory } from './SeedFactory.js';
+
+/** A discovered seed file (array of records or async factory). */
+export interface SeedEntry {
+  /** Entity name this seed targets (from filename: Author.seed.ts → 'author'). */
+  entityName: string;
+  /** Raw default export — array or function. Resolved at runtime. */
+  data: Record<string, unknown>[] | SeedFactory;
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}

package/src/descriptor/SeedFactory.ts

@@ -0,0 +1,2 @@
+/** Seed factory — receives a resolver to access handlers cross-frond. */
+export type SeedFactory = (resolve: <T>(name: string) => T) => Promise<Record<string, unknown>[]>;

package/src/descriptor/bases.ts

@@ -0,0 +1,30 @@
+import { type ProviderEntry } from './ProviderEntry.js';
+
+/**
+ * Port class name → the classes that extend it, in scan order.
+ *
+ * ONE condition, and the caller owns it: something already answers under that name. The boot
+ * asks its container, where the providers sit in the frond's scope and the builtins in its
+ * parent — so a neighbour service and `Logger` both count, a framework class being a port like
+ * any other, which is what makes a default overridable.
+ *
+ * It is also what excludes a prefab: a repository extends the class `Repository(Post)`
+ * returned (`RepositoryBase`), and no key is ever that name.
+ *
+ * Read twice, which is why it is stated once: the boot binds against it, and the scan emits
+ * the same relation as types so a config cannot name a class that does not answer the port.
+ */
+export function basesOf(
+  providers: ProviderEntry[],
+  answers: (name: string) => boolean,
+): Map<string, ProviderEntry[]> {
+  const bases = new Map<string, ProviderEntry[]>();
+  for (const provider of providers) {
+    const base = Object.getPrototypeOf(provider.ctor) as { name?: string } | null;
+    const port = base?.name;
+    if (!port || !answers(port)) continue;
+    bases.set(port, [...(bases.get(port) ?? []), provider]);
+  }
+
+  return bases;
+}

package/src/descriptor/index.ts

@@ -2,14 +2,32 @@
  * 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 * from './ProviderEntry.js';
+export * from './EntityEntry.js';
+export * from './HandlerEntry.js';
+export * from './PresenterFieldMeta.js';
+export * from './PresenterEntry.js';
+export * from './CollectorEntry.js';
+export * from './MiddlewareEntry.js';
+export * from './SeedEntry.js';
+export * from './SeedFactory.js';
+export * from './FrondSource.js';
+export * from './ExtensionEntry.js';
+export * from './FrondDescriptor.js';
 export { Fronds } from './Fronds.js';
 
-export { cardinalityOf, type OperationContract, type OperationsMap, type Param, type TypeRef } from '../wire/operation.js';
+export { cardinalityOf, type OperationContract } from '../wire/OperationContract.js';
+export { type OperationsMap } from '../wire/OperationsMap.js';
+export { type Param } from '../wire/Param.js';
+export { type TypeRef } from '../wire/TypeRef.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 type { Signature } from '../wire/Signature.js';
+export { awaitKeyOf, emitKeyOf } from '../wire/Emit.js';
+export { storageKeyOf } from '../storage/Storage.js';
 export { getPresenterFields } from '../prefab/presenter.js';
 export { targetOf, viewsOf, outputOf } from '../prefab/prefab.js';
-export { ownedBy, repositoryKeyOf } from '../prefab/repository.js';
+export { ownedBy, repositoryKeyOf } from '../prefab/RepositoryConstructor.js';
+
+// The surfaces a handler answers on — a directory names one, and so does `frond.config.ts`.
+export { servedSurfaces } from './surface.js';
+export { basesOf } from './bases.js';

package/src/descriptor/surface.ts

@@ -1,8 +1,9 @@
-import type { FrondDescriptor, HandlerEntry } from './frond.js';
+import type { FrondDescriptor } from './FrondDescriptor.js';
+import type { HandlerEntry } from './HandlerEntry.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.
+ * and every surface that names its address without opening a facade of its own.
  * `undefined` is the default surface, as `facadeKeyOf` and `RouteAddress` spell it.
  */
 export function servedSurfaces(

package/src/diagnostic.ts

@@ -0,0 +1,41 @@
+/**
+ * One thing that does not hold, in the terms of whoever has to fix it — raised by the scan,
+ * by a boot rule, or by `fougere check`, which is why it belongs to no phase.
+ */
+export interface Diagnostic {
+  /**
+   * `blocking` — the app now serves less than its source declares, and no caller can know it: a
+   * handler that failed to parse contributes zero operations.
+   */
+  severity: 'blocking' | 'warning';
+  /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */
+  code: string;
+  /** Where to go and look. */
+  filePath: string;
+  /** The frond it belongs to, when whoever raised it got far enough to know. */
+  frond?: string;
+  /**
+   * What the diagnostic is ABOUT — `PostHandler.publish` — when the rule holds it as a fact
+   * rather than inside its sentence. Two ops of one handler breaking the same rule read as
+   * one repeated line without it.
+   */
+  subject?: string;
+  /** What does not hold, and what it costs. One sentence, for a human. */
+  message: string;
+  /** The underlying failure, kept whole. */
+  cause?: unknown;
+}
+
+/**
+ * Every blocking diagnostic in ONE refusal, so a boot names all of them rather than the
+ * first — the shape `fougere check` renders, read back by whoever has to fix it.
+ */
+export function refusalOf(diagnostics: readonly Diagnostic[], what: string): Error | undefined {
+  const blocking = diagnostics.filter((one) => one.severity === 'blocking');
+  if (blocking.length === 0) return undefined;
+
+  const lines = blocking.map((one) =>
+    `  [${one.code}]${one.subject ? ` ${one.subject}` : ''}\n    ${one.message}\n    ${one.filePath}`);
+
+  return new Error(`Fougere boot refused: ${blocking.length} ${what}:\n${lines.join('\n')}`);
+}

package/src/dispatch/ArgumentResolver.ts

@@ -1,11 +1,6 @@
-import type { InvocationContext } from '../wire/Invocation.js';
+import type { InvocationContext } from '../wire/InvocationContext.js';
 import type { BindingPlan } from '../wire/binding.js';
-
-export interface CollectorResolver {
-  collect(ctx: InvocationContext): Promise<unknown>;
-}
-
-export type CollectorLookup = (typeName: string) => CollectorResolver | undefined;
+import type { CollectorLookup } from './CollectorLookup.js';
 
 /** Resolves an operation's declared binding plan against one invocation. */
 export class ArgumentResolver {

package/src/dispatch/CollectorLookup.ts

@@ -0,0 +1,3 @@
+import type { CollectorResolver } from './CollectorResolver.js';
+
+export type CollectorLookup = (typeName: string) => CollectorResolver | undefined;

package/src/dispatch/CollectorResolver.ts

@@ -0,0 +1,5 @@
+import type { InvocationContext } from '../wire/InvocationContext.js';
+
+export interface CollectorResolver {
+  collect(ctx: InvocationContext): Promise<unknown>;
+}

package/src/dispatch/DispatchEvent.ts

@@ -1,7 +1,6 @@
-import type { Call } from '../wire/call.js';
-import type { RouteKind } from '../wire/RouteAddress.js';
-
-export type DispatchStage = 'received' | 'resolved' | 'completed' | 'failed' | 'settled';
+import type { Call } from '../wire/Call.js';
+import type { RouteKind } from '../wire/RouteKind.js';
+import type { DispatchStage } from './DispatchStage.js';
 
 /** Immutable transition observed across one dispatch lifecycle. */
 export class DispatchEvent {
@@ -34,5 +33,3 @@ export class DispatchEvent {
     return new DispatchEvent('settled', call, routeKind);
   }
 }
-
-export type DispatchObserver = (event: DispatchEvent) => void;

package/src/dispatch/DispatchLifecycle.ts

@@ -1,4 +1,5 @@
-import type { DispatchEvent, DispatchObserver } from './DispatchEvent.js';
+import type { DispatchEvent } from './DispatchEvent.js';
+import type { DispatchObserver } from './DispatchObserver.js';
 
 /** Publishes dispatch transitions without participating in dispatch decisions. */
 export class DispatchLifecycle {

package/src/dispatch/DispatchObserver.ts

@@ -0,0 +1,3 @@
+import type { DispatchEvent } from './DispatchEvent.js';
+
+export type DispatchObserver = (event: DispatchEvent) => void;

package/src/dispatch/DispatchPort.ts

@@ -1,4 +1,4 @@
-import type { Call } from '../wire/call.js';
+import type { Call } from '../wire/Call.js';
 
 /** The only capability an entry needs. */
 export interface DispatchPort {

package/src/dispatch/DispatchStage.ts

@@ -0,0 +1 @@
+export type DispatchStage = 'received' | 'resolved' | 'completed' | 'failed' | 'settled';

package/src/dispatch/Dispatcher.ts

@@ -1,4 +1,4 @@
-import type { Call } from '../wire/call.js';
+import type { Call } from '../wire/Call.js';
 import { DispatchEvent } from './DispatchEvent.js';
 import { DispatchLifecycle } from './DispatchLifecycle.js';
 import type { DispatchPort } from './DispatchPort.js';

package/src/dispatch/Facade.ts

@@ -0,0 +1,25 @@
+import type { Container } from '@fougere/container';
+import { type AppMiddleware } from '../wire/AppMiddleware.js';
+import type { EffectiveOperationsMap } from '../EffectiveOperationsMap.js';
+import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
+import type { PresenterEntry } from '../descriptor/PresenterEntry.js';
+
+/** What boot resolved around one handler, beyond the handler and the scope it resolves in. */
+export interface Facade {
+  /** The container key this facade answers under. */
+  key: string;
+  /** The frond this facade belongs to — travels on every OperationContext. */
+  frond: string;
+  /** Handlers in the owning frond, used to realize a resolved implementation override. */
+  handlers: readonly HandlerEntry[];
+  /** The canonical operation table resolved before boot performs any side effect. */
+  operations: EffectiveOperationsMap;
+  /** Entity names this frond has a collector for. */
+  collectors: Set<string>;
+  /** The presenter over this handler's entity, when the frond declares one. */
+  presenter: PresenterEntry | undefined;
+  /** Presenters live in the frond's own scope, whatever sub-scope this facade resolves in. */
+  presenterScope: Container;
+  /** The middlewares that apply to this address, read at call time and never at boot. */
+  middlewares: () => AppMiddleware[];
+}

package/src/dispatch/GuardReport.ts

@@ -0,0 +1,9 @@
+import { type Fields } from '@fougere/schema';
+
+/** What a guard says about a filter it let through. The boot owns the voice. */
+export interface GuardReport {
+  /** The fields this facade hands back, when it hands back fewer than the entity has. */
+  view?: Fields;
+  /** Said once per field — a filter is not a write, and a warning per call is noise. */
+  outOfView?: (message: string) => void;
+}