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

package/src/storage/{port.ts → Storage.ts}

@@ -1,44 +1,7 @@
 import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
-
-/** Options for list queries — pagination, sorting, counting. */
-export interface ListOptions {
-  /** Number of records to return. */
-  limit?: number;
-
-  /** Offset-based: skip N records. */
-  offset?: number;
-
-  /** Page-based: 1-indexed page number (requires limit). */
-  page?: number;
-
-  /** Cursor-based: fetch records after this ID. */
-  after?: string;
-
-  /** Field name to order by. */
-  orderBy?: string;
-
-  /** Sort direction (default: 'asc'). */
-  order?: 'asc' | 'desc';
-
-  /** If true, also returns total count (for pagination UIs). */
-  count?: boolean;
-
-  /**
-   * Equality criteria, field by field — `{ orderId: '…' }`. Named rather than spread across the
-   * options so an unknown key stays ignored instead of silently becoming a filter.
-   */
-  where?: Record<string, unknown>;
-}
-
-/** Result of list() — extends Array so it's backward compatible. */
-export interface ListResult<T> extends Array<T> {
-  /** Total number of matching records (only set when count: true). */
-  total?: number;
-  /** Cursor of the last item (for cursor-based pagination). */
-  endCursor?: string;
-  /** Whether more records exist after endCursor. */
-  hasMore?: boolean;
-}
+import type { ListOptions } from './ListOptions.js';
+import type { ListResult } from './ListResult.js';
+import type { SelectOption } from './SelectOption.js';
 
 /** The keys `list()` answers to. */
 const LIST_OPTION_KEYS = [
@@ -72,11 +35,6 @@ export function assertListOptions(
   );
 }
 
-/** Select option — restrict returned fields to those of a SchemaView. */
-export interface SelectOption {
-  select?: SchemaView;
-}
-
 /** Per-entity storage — scoped CRUD operations on a single entity type. */
 export interface Storage<T = Record<string, unknown>> {
   list(options?: ListOptions & SelectOption): Promise<ListResult<T>>;
@@ -179,12 +137,6 @@ export abstract class Storage<T = Record<string, unknown>> {
   get client(): unknown { return behind<T>(this).client; }
 }
 
-/**
- * Factory that creates a Storage for a given entity.
- * Called by bootstrap for every scanned entity.
- */
-export type StorageFactory = (entity: SchemaView, name: string) => Storage;
-
 /** Container key of an entity's storage — 'reading' → 'ReadingStorage'. */
 export function storageKeyOf(entity: string): string {
   return `${upperFirst(entity)}${HELD}`;
@@ -201,11 +153,6 @@ export function entityOfStorageKey(key: string, known: (entity: string) => boole
 /** What a holder keeps, said in the key it is registered under. */
 const HELD = 'Storage';
 
-/** `Together<[Account, Ledger]>` — writes that stand or fall as one. */
-export interface Together<E extends readonly unknown[], P extends readonly unknown[] = []> {
-  run<R>(fn: (entities: { [K in keyof E]: Storage<E[K]> }, providers: P) => Promise<R>): Promise<R>;
-}
-
 /**
  * The container key of a frame — `[['Account', 'Ledger'], ['RateMirror']]` →
  * 'Account+Ledger|RateMirrorTogether'.
@@ -216,7 +163,9 @@ export function togetherKeyOf(entities: readonly string[], providers: readonly s
 }
 
 const FRAME = 'Together';
+
 const SEPARATOR = '+';
+
 /** Separates the two lists — what the unwind covers, and what is rebuilt to make it true. */
 const KINDS = '|';
 

package/src/storage/StorageFactory.ts

@@ -0,0 +1,8 @@
+import { type SchemaView } from '@fougere/schema';
+import type { Storage } from './Storage.js';
+
+/**
+ * Factory that creates a Storage for a given entity.
+ * Called by bootstrap for every scanned entity.
+ */
+export type StorageFactory = (entity: SchemaView, name: string) => Storage;

package/src/storage/{store.ts → Store.ts}

@@ -1,10 +1,8 @@
-/** The thirteen gestures of {@link Storage}, derived from four. */
 import { applyCreate, applyUpdate, Lifecycle, Role, type SchemaView } from '@fougere/schema';
-import { comparisonOf, comparisonsIn, type Comparison } from './criterion.js';
-import type { Storage, StorageFactory } from './port.js';
-
-/** One instance, as every realization hands it over. */
-export type Values = Record<string, unknown>;
+import { comparisonOf, comparisonsIn, type Comparison } from './Comparison.js';
+import type { Storage } from './Storage.js';
+import type { StorageFactory } from './StorageFactory.js';
+import type { Values } from './Values.js';
 
 /** Instances addressed by key — what an adapter supplies, and all of it. */
 export interface Store {
@@ -49,7 +47,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
 
       // Same contract as SQL: the key and the creation stamps survive an overwrite.
       // Named, and not reached through `this`: a caller may have wrapped these gestures,
-      // and a derived one that goes back through the front door is judged twice.
+      // and a derived one that goes back through the front facade is judged twice.
       const upsert = async (input: Partial<Record<string, unknown>>): Promise<Values> => {
         const values = applyCreate(fields, applyUpdate(fields, input));
         const id = values[pk] as string | undefined;

package/src/storage/Together.ts

@@ -0,0 +1,6 @@
+import type { Storage } from './Storage.js';
+
+/** `Together<[Account, Ledger]>` — writes that stand or fall as one. */
+export interface Together<E extends readonly unknown[], P extends readonly unknown[] = []> {
+  run<R>(fn: (entities: { [K in keyof E]: Storage<E[K]> }, providers: P) => Promise<R>): Promise<R>;
+}

package/src/storage/Values.ts

@@ -0,0 +1,2 @@
+/** One instance, as every realization hands it over. */
+export type Values = Record<string, unknown>;

package/src/verify.ts

@@ -1,27 +1,18 @@
-import type { FrondDescriptor } from './descriptor/frond.js';
+import type { FrondDescriptor } from './descriptor/FrondDescriptor.js';
+import type { Diagnostic } from './diagnostic.js';
 import { lowerFirst } from '@fougere/schema';
-import { repositoryKeyOf } from './prefab/repository.js';
-import { storageKeyOf } from './storage/port.js';
+import { repositoryKeyOf } from './prefab/RepositoryConstructor.js';
+import { storageKeyOf } from './storage/Storage.js';
 import { presenterKeyOf } from './prefab/presenter.js';
 import { collectorKeyOf } from './prefab/collector.js';
 
-/** What a rule found in an app. */
-export interface Violation {
-  /** Rule name, stable — 'cross-frond-dependency'. */
-  rule: string;
-  /** What it costs, decided by the rule that raises it — never by whoever renders it. */
-  severity: 'blocking' | 'warning';
-  /** The frond the subject lives in. */
+/** A subject declared in one frond and reached from another — the rules below find no other kind. */
+export type Misplaced = Diagnostic & {
   frond: string;
-  /** What violates it — 'PostHandler'. */
   subject: string;
-  /** Where to go and look. */
-  filePath: string;
   /** What the subject reaches for, and where it actually lives. */
   dependsOn: { key: string; frond: string; kind: string };
-  /** What breaks, and what the caller gets instead. */
-  message: string;
-}
+};
 
 /** A dependency declared in a frond's scope, and what kind of thing it is. */
 type Registration = { frond: string; kind: string };
@@ -57,7 +48,7 @@ function injectablesOf(frond: FrondDescriptor) {
  * Does this app survive being split? A frond runs in-process or in its own process behind JSON-RPC
  * with identical user code — that is the whole claim.
  */
-export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[] {
+export function verify(app: { fronds: readonly FrondDescriptor[] }): Misplaced[] {
   const index = new Map<string, Registration>();
   for (const frond of app.fronds) {
     for (const [key, reg] of registrationsOf(frond)) index.set(key, reg);
@@ -71,7 +62,7 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
     for (const collector of frond.collectors) collectorFronds.set(collector.typeName, frond.name);
   }
 
-  const violations: Violation[] = [];
+  const violations: Misplaced[] = [];
   for (const frond of app.fronds) {
     // Rule 1 — a constructor dependency declared in another frond's scope.
     // Façade keys are exempt by construction, not by omission: a `Facade<X>`
@@ -86,7 +77,7 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
         // an unresolved dependency is the container's complaint, not this rule's.
         if (!declared || declared.frond === frond.name) continue;
         violations.push({
-          rule: 'cross-frond-dependency',
+          code: 'cross-frond-dependency',
           severity: 'warning',
           frond: frond.name,
           subject: subject.name,
@@ -120,7 +111,7 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
           // provably false.
           if (!elsewhere) continue;
           violations.push({
-            rule: 'collector-in-another-frond',
+            code: 'collector-in-another-frond',
             severity: 'blocking',
             frond: frond.name,
             subject: `${handler.ctor.name}.${opName}(${param.name})`,
@@ -147,6 +138,6 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
 export function assertSplittable(app: { fronds: readonly FrondDescriptor[] }): void {
   const violations = verify(app);
   if (violations.length === 0) return;
-  const lines = violations.map((v) => `  [${v.rule}] ${v.frond}/${v.subject}\n    ${v.message}\n    ${v.filePath}`);
+  const lines = violations.map((v) => `  [${v.code}] ${v.frond}/${v.subject}\n    ${v.message}\n    ${v.filePath}`);
   throw new Error(`${violations.length} violation(s) — this app does not survive a split:\n${lines.join('\n')}`);
 }

package/src/wire/Addresses.ts

@@ -0,0 +1,17 @@
+import type { FougereOperations } from './FougereOperations.js';
+
+type Served = keyof FougereOperations & string;
+
+/**
+ * Both halves below take the union through a type PARAMETER, which is what makes the
+ * conditional distribute: `Served` is an alias, and an alias is matched whole — `'a.x' | 'b.y'`
+ * does not extend `` `${string}.${string}` `` as one thing, so the naive form answers `never`.
+ */
+type AddressIn<Key> = Key extends `${infer Address}.${string}` ? Address : never;
+
+/**
+ * The addresses this app answers at — or any string, until a scan has said otherwise. The
+ * `[Served] extends [never]` form is what keeps an ungenerated project compiling: a bare `never`
+ * in a parameter position refuses every call, the correct ones included.
+ */
+export type Addresses = [Served] extends [never] ? string : AddressIn<Served>;

package/src/wire/Answer.ts

@@ -0,0 +1,3 @@
+/** What one operation of a handler answers, unwrapped — the page's row type, never restated. */
+export type Answer<Handler, Op extends keyof Handler> =
+  Handler[Op] extends (...args: never[]) => infer Returned ? Awaited<Returned> : never;

package/src/wire/AnyHandler.ts

@@ -0,0 +1,2 @@
+/** A facade whose operations no type describes — an ungenerated project's, and a form's. */
+export type AnyHandler = Record<string, (...args: never[]) => Promise<unknown>>;

package/src/wire/AppMiddleware.ts

@@ -0,0 +1,24 @@
+import type { OperationContext } from './OperationContext.js';
+import type { AppNext } from './AppNext.js';
+
+export type AppMiddleware = (ctx: OperationContext, next: AppNext) => Promise<unknown>;
+
+// ── Runner ──────────────────────────────────────
+
+/**
+ * Execute a middleware chain (onion model) then the handler.
+ */
+export function runMiddlewares(
+  middlewares: AppMiddleware[],
+  ctx: OperationContext,
+  handler: AppNext,
+): Promise<unknown> {
+  let index = 0;
+  const next = (): Promise<unknown> => {
+    if (index < middlewares.length) {
+      return middlewares[index++](ctx, next);
+    }
+    return handler();
+  };
+  return next();
+}

package/src/wire/AppNext.ts

@@ -0,0 +1 @@
+export type AppNext = () => Promise<unknown>;

package/src/wire/Call.ts

@@ -0,0 +1,15 @@
+import { Invocation } from './Invocation.js';
+import { type PartialInvocation } from './PartialInvocation.js';
+import type { RouteAddress } from './RouteAddress.js';
+
+/** One normalized request, frozen: where it goes and what the caller supplied. */
+export class Call {
+  readonly address: RouteAddress;
+  readonly invocation: Invocation;
+
+  constructor(address: RouteAddress, invocation?: PartialInvocation) {
+    this.address = address;
+    this.invocation = Invocation.from(invocation);
+    Object.freeze(this);
+  }
+}

package/src/wire/CallPage.ts

@@ -0,0 +1,9 @@
+import type { CallRecord } from './CallRecord.js';
+
+/** One page of the ring. */
+export interface CallPage {
+  calls: CallRecord[];
+  cursor: number;
+  inFlight: number;
+  dropped: number;
+}

package/src/wire/{CallLog.ts → CallRecord.ts}

@@ -1,6 +1,6 @@
-import type { RouteKind } from './RouteAddress.js';
+import type { RouteKind } from './RouteKind.js';
 
-/** What crosses the door. */
+/** What crosses the facade. */
 export interface CallRecord {
   /** Monotonic, and the whole cursor protocol: a reader asks for what is above its own. */
   seq: number;
@@ -20,11 +20,3 @@ export interface CallRecord {
   verdict: 'running' | 'ok' | 'failed';
   refusal?: { code?: string; message: string };
 }
-
-/** One page of the ring. */
-export interface CallPage {
-  calls: CallRecord[];
-  cursor: number;
-  inFlight: number;
-  dropped: number;
-}

package/src/wire/{emit.ts → Emit.ts}

@@ -1,9 +1,7 @@
-/**
- * Announcing a fact — the half of the topology `remotes:` never covered.
- *
- * Documented: [facts](https://fougere.dev/docs/business/facts).
- */
 import { lowerFirst } from '@fougere/schema';
+import { computeBindingPlan } from './binding.js';
+import type { OperationContract } from './OperationContract.js';
+import type { OperationsMap } from './OperationsMap.js';
 
 /**
  * What an emitter injects. PARTIAL, because announcing is what REALIZES the fact's
@@ -13,25 +11,6 @@ import { lowerFirst } from '@fougere/schema';
  */
 export type Emit<T, A = never> = (fact: Partial<T>) => Promise<A[]>;
 
-/**
- * What a subscriber accepts — and what it PROMISES about itself.
- *
- * What it ANSWERS is its own to choose: `Promise<void>` says nothing, any other type is an
- * opinion. It reaches an announcer that asked for one — `Emit<CanBook, Verdict>` — and
- * nobody otherwise, since a plain announcement does not wait.
- */
-export type Fact<T> = T;
-
-/**
- * The same fact, BEFORE it is final: an op taking one ANSWERS the value every subscriber
- * then receives, so it is the declared form of what `Emissions.stamped` already does for
- * `created()`.
- *
- * Not a second announcement and not a chain a subscriber joins: the links run once, before
- * anyone is handed anything, which is what keeps a fact the same for every reader.
- */
-export type Pipe<T> = T;
-
 /** The container key of an emission — THE one place that spells the format. */
 export function emitKeyOf(fact: string): string {
   return `${lowerFirst(fact)}Emit`;
@@ -47,6 +26,7 @@ export function awaitKeyOf(fact: string): string {
 }
 
 const SUFFIX = 'Emit';
+
 const AWAIT_SUFFIX = 'Await';
 
 /** The fact behind an emission key, or `undefined` when the key is not one. */
@@ -75,6 +55,26 @@ export function factsAwaitedBy(handlers: readonly { deps: readonly string[] }[])
   return factsIn(handlers, factOfAwaitKey);
 }
 
+/**
+ * What a set of handlers LISTENS to — the dual of what it announces, and the half no
+ * dependency spells: accepting a `Fact<T>` IS the subscription, so it is read from the
+ * binding plan, where `Emissions` reads it too.
+ */
+export function factsListenedTo(handlers: readonly { operations: OperationsMap }[]): string[] {
+  const taken = (contract: OperationContract): string[] => {
+    const plan = contract.binding
+      ?? (contract.signature ? computeBindingPlan(contract.signature.params, NO_COLLECTOR) : []);
+
+    return plan.flatMap((bound) =>
+      bound.source.kind === 'fact' || bound.source.kind === 'pipe' ? [bound.source.factName] : []);
+  };
+
+  return [...new Set(handlers.flatMap((handler) => [...handler.operations.values()].flatMap(taken)))];
+}
+
+/** `Fact` and `Pipe` name themselves, and the plan reads them before it reads a collector. */
+const NO_COLLECTOR = new Set<string>();
+
 function factsIn(
   handlers: readonly { deps: readonly string[] }[],
   behindKey: (key: string) => string | undefined,

package/src/wire/ErrorCode.ts

@@ -0,0 +1,33 @@
+/** Semantic error codes — transport-agnostic. Each bridge maps them to its own format. */
+export enum ErrorCode {
+  // Input
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+  BAD_REQUEST = 'BAD_REQUEST',
+
+  // Auth
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+
+  // Resources
+  NOT_FOUND = 'NOT_FOUND',
+  GONE = 'GONE',
+  CONFLICT = 'CONFLICT',
+  LOCKED = 'LOCKED',
+  METHOD_NOT_ALLOWED = 'METHOD_NOT_ALLOWED',
+
+  // Limits
+  PRECONDITION_FAILED = 'PRECONDITION_FAILED',
+  PAYLOAD_TOO_LARGE = 'PAYLOAD_TOO_LARGE',
+  UNPROCESSABLE_ENTITY = 'UNPROCESSABLE_ENTITY',
+  TOO_MANY_REQUESTS = 'TOO_MANY_REQUESTS',
+  REQUEST_TIMEOUT = 'REQUEST_TIMEOUT',
+
+  // Server
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
+  BAD_GATEWAY = 'BAD_GATEWAY',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+  GATEWAY_TIMEOUT = 'GATEWAY_TIMEOUT',
+}
+
+// ── FougereError ────────────────────────────────

package/src/wire/Facade.ts

@@ -0,0 +1,28 @@
+import type { InvocationContext } from './InvocationContext.js';
+import type { FougereOperations } from './FougereOperations.js';
+
+type Served = keyof FougereOperations & string;
+
+/**
+ * Both halves below take the union through a type PARAMETER, which is what makes the
+ * conditional distribute: `Served` is an alias, and an alias is matched whole — `'a.x' | 'b.y'`
+ * does not extend `` `${string}.${string}` `` as one thing, so the naive form answers `never`.
+ */
+type AddressIn<Key> = Key extends `${infer Address}.${string}` ? Address : never;
+
+/** The facade built in front of a handler — the framework's second port, after `Storage`. */
+export type Facade<T> = {
+  [K in keyof T]: T[K] extends (...args: never[]) => infer R
+    ? (invocation?: InvocationContext) => R
+    : never;
+};
+
+/** The container key of a façade — THE one place that spells the format. */
+export function facadeKeyOf(entityName: string, surface?: string): string {
+  return surface ? `${surface}:${entityName}Handler` : `${entityName}Handler`;
+}
+
+/** Where the contracts behind a façade live — the dual of `facadeKeyOf`. */
+export function contractsKeyOf(entityName: string, surface?: string): string {
+  return `${facadeKeyOf(entityName, surface)}:contracts`;
+}

package/src/wire/FacadeName.ts

@@ -0,0 +1,13 @@
+/**
+ * One facade: where a call goes, and the handler that answers there.
+ *
+ * The address is carried as a LITERAL, which is what lets an operation be looked up by
+ * `address.op`. A page never builds one by hand — the scan writes a `const` per address, and a
+ * page imports it, so a project that never generated them fails to resolve rather than losing
+ * its types in silence.
+ */
+export interface FacadeName<Handler, Address extends string> {
+  readonly address: Address;
+  /** Never read: it is how the handler's own signatures reach the page. */
+  readonly handler?: Handler;
+}

package/src/wire/Fact.ts

@@ -0,0 +1,8 @@
+/**
+ * What a subscriber accepts — and what it PROMISES about itself.
+ *
+ * What it ANSWERS is its own to choose: `Promise<void>` says nothing, any other type is an
+ * opinion. It reaches an announcer that asked for one — `Emit<CanBook, Verdict>` — and
+ * nobody otherwise, since a plain announcement does not wait.
+ */
+export type Fact<T> = T;

package/src/wire/{errors.ts → FougereError.ts}

@@ -1,63 +1,24 @@
+import type { ValidationError } from '@fougere/schema';
+import { ErrorCode } from './ErrorCode.js';
+import type { FougereErrorOptions } from './FougereErrorOptions.js';
+
 /**
- * The error vocabulary — what a refusal IS, independently of who hears it.
+ * A refusal, and which one — narrowed by the operation that answered it where the caller knows.
  *
- * Documented: [errors](https://fougere.dev/docs/business/errors).
+ * `Code` defaults to every code there is, so a thrower writes what it always wrote. What it buys
+ * is on the READING side: a client generated from a card gets `FougereError<'NOT_FOUND' |
+ * 'CONFLICT'>`, and a `switch` over `code` with a `never` in its default stops compiling the day
+ * the op learns to refuse something else.
+ *
+ * Documented: [observability](https://fougere.dev/docs/infra/observability).
  */
-
-import type { ValidationError } from '@fougere/schema';
-
-// ── ErrorCode ──────────────────────────────────
-
-/** Semantic error codes — transport-agnostic. Each bridge maps them to its own format. */
-export enum ErrorCode {
-  // Input
-  VALIDATION_FAILED = 'VALIDATION_FAILED',
-  BAD_REQUEST = 'BAD_REQUEST',
-
-  // Auth
-  UNAUTHORIZED = 'UNAUTHORIZED',
-  FORBIDDEN = 'FORBIDDEN',
-
-  // Resources
-  NOT_FOUND = 'NOT_FOUND',
-  GONE = 'GONE',
-  CONFLICT = 'CONFLICT',
-  LOCKED = 'LOCKED',
-  METHOD_NOT_ALLOWED = 'METHOD_NOT_ALLOWED',
-
-  // Limits
-  PRECONDITION_FAILED = 'PRECONDITION_FAILED',
-  PAYLOAD_TOO_LARGE = 'PAYLOAD_TOO_LARGE',
-  UNPROCESSABLE_ENTITY = 'UNPROCESSABLE_ENTITY',
-  TOO_MANY_REQUESTS = 'TOO_MANY_REQUESTS',
-  REQUEST_TIMEOUT = 'REQUEST_TIMEOUT',
-
-  // Server
-  INTERNAL_ERROR = 'INTERNAL_ERROR',
-  NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
-  BAD_GATEWAY = 'BAD_GATEWAY',
-  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
-  GATEWAY_TIMEOUT = 'GATEWAY_TIMEOUT',
-}
-
-// ── FougereError ────────────────────────────────
-
-export interface FougereErrorOptions {
-  code: ErrorCode;
-  message: string;
-  entity?: string;
-  operation?: string;
-  details?: unknown;
-  cause?: unknown;
-}
-
-export class FougereError extends Error {
-  readonly code: ErrorCode;
+export class FougereError<Code extends ErrorCode = ErrorCode> extends Error {
+  readonly code: Code;
   readonly entity?: string;
   readonly operation?: string;
   readonly details?: unknown;
 
-  constructor(options: FougereErrorOptions) {
+  constructor(options: FougereErrorOptions<Code>) {
     super(options.message, { cause: options.cause });
     this.name = new.target.name;
     this.code = options.code;

package/src/wire/FougereErrorOptions.ts

@@ -0,0 +1,10 @@
+import type { ErrorCode } from './ErrorCode.js';
+
+export interface FougereErrorOptions<Code extends ErrorCode = ErrorCode> {
+  code: Code;
+  message: string;
+  entity?: string;
+  operation?: string;
+  details?: unknown;
+  cause?: unknown;
+}

package/src/wire/FougereHandlers.ts

@@ -0,0 +1,8 @@
+/**
+ * The handler behind each address, carried as `import('…/PostHandler').default`.
+ *
+ * TypeScript resolves it from the source, so the operations that exist and what each one
+ * answers cost the generated module nothing: no signature is printed into it, and none can
+ * drift from the class it was read off.
+ */
+export interface FougereHandlers {}

package/src/wire/FougereOperations.ts

@@ -0,0 +1,2 @@
+/** What one facade answers for, keyed `address.op` — `surface:address.op` for a named surface. */
+export interface FougereOperations {}

package/src/wire/FrondCall.ts

@@ -0,0 +1,9 @@
+/** Target of a call — which façade operation, wherever it lives. */
+export interface FrondCall {
+  /** Frond name, when the caller knows it. Routing hint only. */
+  frond?: string;
+  /** Entity registration key (e.g. 'product'). */
+  entity: string;
+  /** Façade operation name (e.g. 'findById', 'search'). */
+  op: string;
+}

package/src/wire/HandlerOf.ts

@@ -0,0 +1,10 @@
+import type { FougereHandlers } from './FougereHandlers.js';
+import type { AnyHandler } from './AnyHandler.js';
+
+/**
+ * The handler that answers at one address. It falls back to an unconstrained facade when nothing
+ * was generated, because a `never` there would refuse every call a project makes.
+ */
+export type HandlerOf<Address extends string> =
+  [keyof FougereHandlers] extends [never] ? AnyHandler
+  : Address extends keyof FougereHandlers ? FougereHandlers[Address] : AnyHandler;

package/src/wire/Invocation.ts

@@ -1,14 +1,5 @@
-export interface InvocationContext {
-  params: Record<string, unknown>;
-  query: Record<string, unknown>;
-  input: unknown;
-  state: Record<string, unknown>;
-  trace?: string;
-  identity?: string;
-  caller?: string;
-}
-
-export type PartialInvocation = Partial<InvocationContext>;
+import type { InvocationContext } from './InvocationContext.js';
+import type { PartialInvocation } from './PartialInvocation.js';
 
 /** Freezes plain data deeply, and leaves a class instance alone — a `Date` is not a record. */
 function canonicalValue(value: unknown): unknown {
@@ -40,8 +31,9 @@ export class Invocation implements InvocationContext {
   readonly trace?: string;
   readonly identity?: string;
   readonly caller?: string;
+  readonly runAt?: number;
 
-  /** Gives every entry and every transport the same seven-member value, frozen. */
+  /** Gives every entry and every transport the same eight-member value, frozen. */
   private constructor(context: PartialInvocation) {
     this.params = canonicalRecord(context.params);
     this.query = canonicalRecord(context.query);
@@ -52,6 +44,7 @@ export class Invocation implements InvocationContext {
     if (context.trace !== undefined) this.trace = context.trace;
     if (context.identity !== undefined) this.identity = context.identity;
     if (context.caller !== undefined) this.caller = context.caller;
+    if (context.runAt !== undefined) this.runAt = context.runAt;
     Object.freeze(this);
   }
 

package/src/wire/InvocationContext.ts

@@ -0,0 +1,11 @@
+export interface InvocationContext {
+  params: Record<string, unknown>;
+  query: Record<string, unknown>;
+  input: unknown;
+  state: Record<string, unknown>;
+  trace?: string;
+  identity?: string;
+  caller?: string;
+  /** Epoch milliseconds before which this call is not to run. */
+  runAt?: number;
+}