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

package/src/prefab/{crud.ts → CrudConstructor.ts}

@@ -1,7 +1,12 @@
 import { lowerFirst, type EntityConstructor, type SchemaView } from '@fougere/schema';
-import type { Storage, ListOptions, ListResult } from '../storage/port.js';
-import type { OperationContract } from '../wire/operation.js';
+import type { ListOptions } from '../storage/ListOptions.js';
+import type { ListResult } from '../storage/ListResult.js';
+import type { Storage } from '../storage/Storage.js';
+import type { OperationContract } from '../wire/OperationContract.js';
 import { targetOf } from './prefab.js';
+import type { CrudOpName } from './CrudOpName.js';
+import type { CrudViews } from './CrudViews.js';
+import type { CrudOps } from './CrudOps.js';
 
 /**
  * A class is recognized by what it ANSWERS — the mixin leaves no other trace.
@@ -27,11 +32,14 @@ export function subjectOf(ctor: unknown, address: string): string {
 
 /** The id of the row an op acts on — a route segment, or a query fallback. */
 const byId = { name: 'id', source: { kind: 'param' as const, name: 'id' }, optional: false };
+
 const fromBody = { name: 'input', source: { kind: 'input' as const }, optional: false };
 
 /** The same five, written as the scan would have written them. */
 const idParam = { name: 'id', type: { raw: 'string', name: 'string' } };
+
 const inputParam = (entity: string) => ({ name: 'input', type: { raw: `Partial<${entity}>`, name: entity } });
+
 const returns = (raw: string, name: string, extra?: { array?: boolean; nullable?: boolean }) =>
   ({ raw, name, ...extra });
 
@@ -78,12 +86,6 @@ function asCrudConstructor<T, V>(impl: object): CrudConstructor<T, V> {
   return impl as CrudConstructor<T, V>;
 }
 
-/** The five ops the mixin fabricates. */
-export type CrudOpName = 'list' | 'findById' | 'create' | 'update' | 'delete';
-
-/** Which view each op speaks — omitted ops speak the entity, the trivial view. */
-export type CrudViews = Partial<Record<CrudOpName, EntityConstructor>>;
-
 /** The view an op emits, fabricated. */
 type OutOf<V, K extends CrudOpName, T> =
   // Bracketed on purpose: a naked `V extends …` DISTRIBUTES, and the no-view default
@@ -93,16 +95,6 @@ type OutOf<V, K extends CrudOpName, T> =
   : K extends keyof V ? (V[K] extends EntityConstructor ? InstanceType<V[K]> : T)
   : T;
 
-/** The five ops, typed from the entity and its views. */
-export interface CrudOps<T, V = {}> {
-  storage: Storage<T>;
-  list(options?: ListOptions, ...collected: never[]): Promise<ListResult<OutOf<V, 'list', T>>>;
-  findById(id: string, ...collected: never[]): Promise<OutOf<V, 'findById', T> | undefined>;
-  create(input: Partial<T>, ...collected: never[]): Promise<OutOf<V, 'create', T>>;
-  update(id: string, input: Partial<T>, ...collected: never[]): Promise<OutOf<V, 'update', T>>;
-  delete(id: string, ...collected: never[]): Promise<boolean>;
-}
-
 /** The prefab handler class — its ops, plus the statics the bootstrap and adapters read. */
 export interface CrudConstructor<T, V = {}> {
   // `Storage<T>`, not the bare `Storage`: a handler that injects a second storage has to

package/src/prefab/CrudOpName.ts

@@ -0,0 +1,2 @@
+/** The five ops the mixin fabricates. */
+export type CrudOpName = 'list' | 'findById' | 'create' | 'update' | 'delete';

package/src/prefab/CrudOps.ts

@@ -0,0 +1,24 @@
+import type { CrudOpName } from './CrudOpName.js';
+import type { EntityConstructor } from '@fougere/schema';
+import type { ListOptions } from '../storage/ListOptions.js';
+import type { ListResult } from '../storage/ListResult.js';
+import type { Storage } from '../storage/Storage.js';
+
+/** The view an op emits, fabricated. */
+type OutOf<V, K extends CrudOpName, T> =
+  // Bracketed on purpose: a naked `V extends …` DISTRIBUTES, and the no-view default
+  // is the empty map, whose `keyof` is `never` — distribution would then collapse
+  // every op's output to `never` instead of falling through to the entity.
+  [V] extends [EntityConstructor] ? InstanceType<V & EntityConstructor>
+  : K extends keyof V ? (V[K] extends EntityConstructor ? InstanceType<V[K]> : T)
+  : T;
+
+/** The five ops, typed from the entity and its views. */
+export interface CrudOps<T, V = {}> {
+  storage: Storage<T>;
+  list(options?: ListOptions, ...collected: never[]): Promise<ListResult<OutOf<V, 'list', T>>>;
+  findById(id: string, ...collected: never[]): Promise<OutOf<V, 'findById', T> | undefined>;
+  create(input: Partial<T>, ...collected: never[]): Promise<OutOf<V, 'create', T>>;
+  update(id: string, input: Partial<T>, ...collected: never[]): Promise<OutOf<V, 'update', T>>;
+  delete(id: string, ...collected: never[]): Promise<boolean>;
+}

package/src/prefab/CrudViews.ts

@@ -0,0 +1,5 @@
+import { type EntityConstructor } from '@fougere/schema';
+import type { CrudOpName } from './CrudOpName.js';
+
+/** Which view each op speaks — omitted ops speak the entity, the trivial view. */
+export type CrudViews = Partial<Record<CrudOpName, EntityConstructor>>;

package/src/prefab/MirrorConstructor.ts

@@ -0,0 +1,35 @@
+import type { EntityConstructor } from '@fougere/schema';
+import type { Storage } from '../storage/Storage.js';
+import type { Refreshed } from './Refreshed.js';
+import type { MirrorOf } from './MirrorOf.js';
+
+export interface MirrorConstructor<T> {
+  new (storage: Storage<T>): MirrorOf<T>;
+  readonly __entity: unknown;
+}
+
+export function Mirror<E extends EntityConstructor>(shape: E): MirrorConstructor<InstanceType<E>> {
+  type T = InstanceType<E>;
+
+  abstract class MirrorBase implements MirrorOf<T> {
+    static readonly __entity = shape;
+
+    constructor(public storage: Storage<T>) {}
+
+    abstract pull(since?: Date): AsyncIterable<Partial<T>[]>;
+
+    async refresh(since?: Date): Promise<Refreshed> {
+      const started = Date.now();
+      let written = 0;
+      // Preserve the source's page boundaries: one page becomes one upsert.
+      for await (const page of this.pull(since)) {
+        if (page.length === 0) continue;
+        written += await this.storage.upsertAll(page);
+      }
+
+      return { written, since, ms: Date.now() - started };
+    }
+  }
+
+  return MirrorBase as unknown as MirrorConstructor<T>;
+}

package/src/prefab/MirrorOf.ts

@@ -0,0 +1,19 @@
+import type { Storage } from '../storage/Storage.js';
+import type { Refreshed } from './Refreshed.js';
+
+/**
+ * A paginated local copy of a source that cannot be queried directly.
+ *
+ * Documented: [the base](https://fougere.dev/docs/concepts/the-base).
+ */
+export interface MirrorOf<T> {
+  /** The copy's own storage — where a page lands. */
+  storage: Storage<T>;
+  /** Pages of rows to write. The one thing a mirror's author supplies. */
+  pull(since?: Date): AsyncIterable<Partial<T>[]>;
+  /**
+   * Pull from `since` and write every page. The mark is the CALLER's: only it knows
+   * whether a pass completed, and a pass that throws must not advance it.
+   */
+  refresh(since?: Date): Promise<Refreshed>;
+}

package/src/prefab/Refreshed.ts

@@ -0,0 +1,9 @@
+/** What one refresh did — enough to log it, and to decide whether to run again. */
+export interface Refreshed {
+  /** Instances written, counting a replaced one once. */
+  written: number;
+  /** The age the pull was asked to start from — absent when it asked for everything. */
+  since?: Date;
+  /** How long the whole pass took, pull included. */
+  ms: number;
+}

package/src/prefab/{repository.ts → RepositoryConstructor.ts}

@@ -1,18 +1,11 @@
 import { upperFirst, type EntityConstructor } from '@fougere/schema';
-import type { Storage, ListOptions, ListResult, SelectOption } from '../storage/port.js';
+import type { ListOptions } from '../storage/ListOptions.js';
+import type { ListResult } from '../storage/ListResult.js';
+import type { SelectOption } from '../storage/SelectOption.js';
+import type { Storage } from '../storage/Storage.js';
 import type { SchemaView } from '@fougere/schema';
-
-/**
- * Repository(…entities) — who owns an entity's storage, and where its questions are named.
- *
- * Documented: [repositories](https://fougere.dev/docs/business/repositories).
- */
-
-/**
- * The shape a repository of ONE entity has — the port itself, plus whatever the subclass names on
- * top.
- */
-export type RepositoryOf<T> = Storage<T>;
+import type { AggregateOf } from './AggregateOf.js';
+import type { AggregateConstructor } from './AggregateConstructor.js';
 
 /** The single-entity form: the port, plus whatever the subclass names. */
 export interface RepositoryConstructor<T> {
@@ -25,21 +18,12 @@ declare abstract class AggregateShape<E extends readonly EntityConstructor[]> {
   protected storages: { [K in keyof E]: Storage<InstanceType<E[K]>> };
 }
 
-/** The tuple an aggregate holds — the readable form of {@link AggregateShape}'s member. */
-export type AggregateOf<E extends readonly EntityConstructor[]> =
-  { [K in keyof E]: Storage<InstanceType<E[K]>> };
-
-export type AggregateConstructor<E extends readonly EntityConstructor[]> =
-  (new (...storages: unknown[]) => AggregateShape<E>) & {
-    readonly __entity: unknown;
-    /** The entities this class owns. Present from two on — an owner of one owns nothing. */
-    readonly __owns: E;
-  };
-
 export function Repository<E extends EntityConstructor>(entity: E): RepositoryConstructor<InstanceType<E>>;
+
 export function Repository<E extends readonly [EntityConstructor, EntityConstructor, ...EntityConstructor[]]>(
   ...entities: E
 ): AggregateConstructor<E>;
+
 export function Repository(...entities: EntityConstructor[]): unknown {
   return entities.length === 1 ? one(entities[0]) : many(entities);
 }

package/src/prefab/RepositoryOf.ts

@@ -0,0 +1,7 @@
+import type { Storage } from '../storage/Storage.js';
+
+/**
+ * The shape a repository of ONE entity has — the port itself, plus whatever the subclass names on
+ * top.
+ */
+export type RepositoryOf<T> = Storage<T>;

package/src/scan.ts

@@ -1,29 +1,9 @@
 import type { Fronds } from './descriptor/Fronds.js';
-
-/** Something the scan could NOT do — recorded instead of swallowed. */
-export interface ScanDiagnostic {
-  /**
-   * `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;
-  /** Absolute path of what could not be read. */
-  filePath: string;
-  /** The frond it belongs to, when the scan got far enough to know. */
-  frond?: string;
-  /** The declaration the diagnostic is about — e.g. `PostHandler.publish`. */
-  subject?: string;
-  /** What could not be done, and what it costs. One sentence, for a human. */
-  message: string;
-  /** The underlying failure, kept whole. */
-  cause?: unknown;
-}
+import type { Diagnostic } from './diagnostic.js';
 
 /** Result of scanning a project directory. */
 export interface ScanResult {
   fronds: Fronds;
-  /** What the scan could not do. Empty is a claim, not a default — see {@link ScanDiagnostic}. */
-  diagnostics: ScanDiagnostic[];
+  /** What the scan could not do. Empty is a claim, not a default — see {@link Diagnostic}. */
+  diagnostics: Diagnostic[];
 }

package/src/storage/{criterion.ts → Comparison.ts}

@@ -1,5 +1,5 @@
-/** What a read may ask about one field, and how a storage tells the two forms apart. */
 import { type Field, Shapes } from '@fougere/schema';
+import type { ComparisonName } from './ComparisonName.js';
 
 /**
  * The comparisons a criterion may name.
@@ -23,8 +23,6 @@ export interface Comparison {
 
 export const COMPARISONS = ['gte', 'lte', 'gt', 'lt', 'ne', 'between', 'contains', 'notIn', 'isNull'] as const;
 
-export type ComparisonName = (typeof COMPARISONS)[number];
-
 /**
  * Is this criterion a comparison, or a value that happens to be an object?
  *

package/src/storage/ComparisonName.ts

@@ -0,0 +1,3 @@
+export const COMPARISONS = ['gte', 'lte', 'gt', 'lt', 'ne', 'between', 'contains', 'notIn', 'isNull'] as const;
+
+export type ComparisonName = (typeof COMPARISONS)[number];

package/src/storage/ListOptions.ts

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

package/src/storage/ListResult.ts

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

package/src/storage/SelectOption.ts

@@ -0,0 +1,6 @@
+import { type SchemaView } from '@fougere/schema';
+
+/** Select option — restrict returned fields to those of a SchemaView. */
+export interface SelectOption {
+  select?: SchemaView;
+}

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;
-}