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

package/src/dispatch/StorageGuard.ts

@@ -1,4 +1,4 @@
-import { FieldSet, FieldValueValidator, InputRefusal, type Fields } from '@fougere/schema';
+import { FieldSet, FieldValueValidator, InputRefusal, type Fields, type Verdict } from '@fougere/schema';
 import { COMPARISONS, comparisonOf, unknownIn } from '../storage/Comparison.js';
 import { assertListOptions } from '../storage/Storage.js';
 import { ErrorCode } from '../wire/ErrorCode.js';
@@ -34,22 +34,37 @@ export class StorageGuard {
     const writer = storage as unknown as Writer;
     if (typeof writer.create !== 'function' || typeof writer.update !== 'function') return storage;
 
-    const validation = this;
     const guarded = Object.create(storage) as T & Writer;
 
+    this.guardDelete(guarded, writer);
+    this.guardWrites(guarded, writer);
+    this.guardList(guarded, writer);
+
+    return guarded;
+  }
+
+  /**
+   * What names this row goes first, and this row last: an interruption then leaves fewer
+   * children rather than an orphan. A key holds the rest, at the rows, in one statement.
+   */
+  private guardDelete(guarded: Writer, writer: Writer): void {
     const remove = writer.delete;
-    if (typeof remove === 'function' && validation.releasing) {
-      // What names this row goes first, and this row last: an interruption then leaves fewer
-      // children rather than an orphan. A key holds the rest, at the rows, in one statement.
-      guarded.delete = async function (id) {
-        let gone = false;
-        await release(validation.entity, id, validation.releasing!, [], async () => {
-          gone = await remove.call(this, id);
-        });
-
-        return gone;
-      };
-    }
+    if (typeof remove !== 'function' || !this.releasing) return;
+
+    const validation = this;
+    guarded.delete = async function (id) {
+      let gone = false;
+      await release(validation.entity, id, validation.releasing!, [], async () => {
+        gone = await remove.call(this, id);
+      });
+
+      return gone;
+    };
+  }
+
+  /** Every gesture that puts a row down: judged first, and handed on the value it parsed. */
+  private guardWrites(guarded: Writer, writer: Writer): void {
+    const validation = this;
 
     guarded.create = async function (...args) {
       args[0] = validation.validated(args[0], 'create');
@@ -74,29 +89,29 @@ export class StorageGuard {
 
     const upsertAll = writer.upsertAll;
     if (typeof upsertAll === 'function') {
-      // Every row before the first write: a page refused halfway leaves rows behind that
-      // the caller asked for as one, and the refusal is readable from the input alone.
+      // Every row before the first write, and the keys of the whole page in one read per
+      // relation: a page refused on its fourth row has already written three.
       guarded.upsertAll = async function (...args) {
         args[0] = args[0].map((row, index) => validation.validated(row, 'upsertAll', index));
-        // The keys of the whole page in one read per relation, for the reason above: a page
-        // refused on its fourth row has already written three.
         await validation.targetsOf(args[0], 'upsertAll');
         return upsertAll.apply(this, args);
       };
     }
+  }
 
+  /** A criterion is read where the entity declares it, so a page is asked for what it can answer. */
+  private guardList(guarded: Writer, writer: Writer): void {
     const list = writer.list;
-    if (typeof list === 'function') {
-      guarded.list = async function (...args: unknown[]) {
-        const options = args[0] as { where?: Record<string, unknown> } | undefined;
-        assertListOptions(options, validation.entity, Object.keys(validation.fields));
-        if (options?.where) args[0] = { ...options, where: validation.criteria(options.where) };
+    if (typeof list !== 'function') return;
 
-        return list.apply(this, args);
-      };
-    }
+    const validation = this;
+    guarded.list = async function (...args: unknown[]) {
+      const options = args[0] as { where?: Record<string, unknown> } | undefined;
+      assertListOptions(options, validation.entity, Object.keys(validation.fields));
+      if (options?.where) args[0] = { ...options, where: validation.criteria(options.where) };
 
-    return guarded;
+      return list.apply(this, args);
+    };
   }
 
   /**
@@ -123,34 +138,12 @@ export class StorageGuard {
     const parsed: Record<string, unknown> = {};
 
     for (const [key, asked] of Object.entries(where)) {
-      const field = this.fields[key];
-      if (!field) {
-        errors.push(`${key}: ${InputRefusal.unknownField}`);
-        continue;
-      }
-      // A comparison names its own vocabulary, and a typo in it would otherwise be a
-      // criterion that filters nothing — the silent truncation this facade exists to stop.
-      const comparison = comparisonOf(field, asked);
-      if (comparison) {
-        const unknown = unknownIn(comparison);
-        if (unknown.length) {
-          errors.push(`${key}: unknown comparison ${unknown.join(', ')} — one of ${COMPARISONS.join(', ')}`);
-          continue;
-        }
-        parsed[key] = comparison;
+      const read = this.criterion(key, asked);
+      if ('message' in read) errors.push(`${key}: ${read.message}`);
+      else {
+        parsed[key] = read.value;
         this.beyondTheView(key);
-        continue;
-      }
-
-      const values = Array.isArray(asked) ? asked : [asked];
-      const each = values.map((value) => this.value(field, value));
-      const refused = each.find((one) => typeof one === 'object' && one !== null && 'error' in one);
-      if (refused) {
-        errors.push(`${key}: ${(refused as { error: string }).error}`);
-        continue;
       }
-      parsed[key] = Array.isArray(asked) ? each.map(unwrap) : unwrap(each[0]);
-      this.beyondTheView(key);
     }
 
     if (errors.length > 0) {
@@ -166,6 +159,33 @@ export class StorageGuard {
     return parsed;
   }
 
+  /**
+   * One criterion, told from a value by the FIELD and never by its own shape.
+   *
+   * A comparison names its own vocabulary, and a typo in it would otherwise be a criterion that
+   * filters nothing — the silent truncation this facade exists to stop.
+   */
+  private criterion(key: string, asked: unknown): Verdict {
+    const field = this.fields[key];
+    if (!field) return { message: InputRefusal.unknownField };
+
+    const comparison = comparisonOf(field, asked);
+    if (comparison) {
+      const unknown = unknownIn(comparison);
+
+      return unknown.length
+        ? { message: `unknown comparison ${unknown.join(', ')} — one of ${COMPARISONS.join(', ')}` }
+        : { value: comparison };
+    }
+
+    const values = Array.isArray(asked) ? asked : [asked];
+    const each = values.map((value) => this.value(field, value));
+    const refused = each.find((one) => 'message' in one);
+    if (refused) return refused;
+
+    return { value: Array.isArray(asked) ? each.map(unwrap) : unwrap(each[0]) };
+  }
+
   /**
    * A filter on a field this facade does not hand back.
    *
@@ -186,7 +206,19 @@ export class StorageGuard {
   }
 
   /** One value against one field — validated, then decoded the way the wire hands it. */
-  private value(field: Fields[string], asked: unknown): { value: unknown } | { error: string } {
+  /**
+   * One key a handler wrote. A key the entity does not declare has no column to land in and no
+   * judge to pass: on the client facade it is a typo, and on this one a mapping that went stale.
+   */
+  private written(key: string, item: unknown): Verdict {
+    const field = this.fields[key];
+    if (!field) return { message: InputRefusal.unknownField };
+    if (item === undefined) return { value: item };
+
+    return FieldValueValidator.of(field).parse(item);
+  }
+
+  private value(field: Fields[string], asked: unknown): Verdict {
     if (asked === null || asked === undefined) return { value: asked };
     return FieldValueValidator.of(field).parse(asked);
   }
@@ -199,20 +231,9 @@ export class StorageGuard {
     const parsed: Record<string, unknown> = {};
 
     for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
-      const field = this.fields[key];
-      // A key the entity does not declare has no column to land in and no judge to pass:
-      // on the client facade it is a typo, and on this one it is a mapping that went stale.
-      if (!field) {
-        errors.push(`${where}${key}: ${InputRefusal.unknownField}`);
-        continue;
-      }
-      if (item === undefined) {
-        parsed[key] = item;
-        continue;
-      }
-      const value = FieldValueValidator.of(field).parse(item);
-      if ('error' in value) errors.push(`${where}${key}: ${value.error}`);
-      else parsed[key] = value.value;
+      const read = this.written(key, item);
+      if ('message' in read) errors.push(`${where}${key}: ${read.message}`);
+      else parsed[key] = read.value;
     }
 
     if (errors.length > 0) {
@@ -266,5 +287,5 @@ export class StorageGuard {
   }
 }
 
-const unwrap = (one: { value: unknown } | { error: string }): unknown =>
+const unwrap = (one: Verdict): unknown =>
   'value' in one ? one.value : undefined;

package/src/dispatch/decoded.ts

@@ -0,0 +1,37 @@
+import { Visibility, type Fields, type SchemaView } from '@fougere/schema';
+import { preserveArrayProperties } from './ArrayResult.js';
+import { asPage } from '../wire/Page.js';
+
+/**
+ * What a caller receives, read back into the shape its type promises — the dual of
+ * `OutputView.project`, applied on the other side of the call.
+ *
+ * `date-time` means a `Date` on both sides (`Boundary.forShape`), and only the outgoing half was
+ * ever applied: `Visibility.encode` turned `new Date(0)` into `"1970-01-01T00:00:00.000Z"` and
+ * nobody turned it back, so `Facade<PostHandler>` promised `createdAt: Date` and handed over a
+ * string — in this process as well as across a wire.
+ *
+ * Applied by the facade a caller HOLDS, never by the one that answers: a row leaves as data,
+ * which is what a Rust frond or a plain HTTP client reads, and the codecs are what this side
+ * knows how to put back. Measured 2026-09-18: 389 ns per row against the 1 277 ns encoding one
+ * already costs.
+ *
+ * Documented: [the gradient](https://fougere.dev/docs/infra/gradient).
+ */
+export function decoded(schema: SchemaView | undefined, answer: unknown): unknown {
+  if (!schema || answer === null || answer === undefined) return answer;
+
+  const fields = schema.getFields() as Fields;
+  const visibility = Visibility.of(fields);
+  const row = (one: unknown) => (one !== null && typeof one === 'object' && !Array.isArray(one)
+    ? visibility.decode(one as Record<string, unknown>)
+    : one);
+
+  const page = asPage(answer, fields);
+  if (page) return { ...page, items: page.items.map(row) };
+
+  // An op annotating `ListResult<T>` still answers the array those properties ride on.
+  return Array.isArray(answer)
+    ? preserveArrayProperties(answer, answer.map(row))
+    : row(answer);
+}

package/src/entry/facade.ts

@@ -2,6 +2,7 @@ import { Call } from '../wire/Call.js';
 
 import { RouteAddress } from '../wire/RouteAddress.js';
 import type { DispatchPort } from '../dispatch/DispatchPort.js';
+import type { Received } from '../dispatch/Received.js';
 
 type Operation = (...args: any[]) => unknown;
 
@@ -22,21 +23,32 @@ export function dynamicOperations(operation: (name: string) => Operation): Recor
   });
 }
 
-/** Turns facade method calls into canonical dispatches. */
+/**
+ * Turns facade method calls into canonical dispatches.
+ *
+ * `received` is what this side puts back before handing the answer over: a row leaves as data
+ * and `date-time` means a `Date` on both sides. A facade built without one hands over what the
+ * wire carried, which is what a caller holding no schema can do.
+ */
 export function facadeOperations(
   dispatcher: DispatchPort,
   entity: string,
   operationNames?: Iterable<string>,
   surface?: string,
+  received?: Received,
 ): Record<string, Operation> {
-  const operation = (name: string): Operation => (invocation) => dispatcher.dispatch(new Call(
-    new RouteAddress({
-      entity,
-      operation: name,
-      ...(surface !== undefined ? { surface } : {}),
-    }),
-    invocation,
-  ));
+  const operation = (name: string): Operation => async (invocation) => {
+    const answer = await dispatcher.dispatch(new Call(
+      new RouteAddress({
+        entity,
+        operation: name,
+        ...(surface !== undefined ? { surface } : {}),
+      }),
+      invocation,
+    ));
+
+    return received ? received(name, answer) : answer;
+  };
 
   return operationNames
     ? Object.fromEntries([...operationNames].map((name) => [name, operation(name)]))

package/src/index.ts

@@ -6,6 +6,9 @@ export type { Extension } from './boot/Extension.js';
 export { defineFougere } from './define.js';
 export type { AdapterConfig } from './AdapterConfig.js';
 export type { FougereConfig } from './FougereConfig.js';
+export { statesModule, type FrondsStated, type FrondStated } from './FrondsStated.js';
+export { statedFronds, type StatedFrond } from './StatedFrond.js';
+export { nested } from './boot/nesting.js';
 export type { AnswerFor } from './AnswerFor.js';
 export type { FougereNames } from './FougereNames.js';
 export type { FougerePorts } from './FougerePorts.js';
@@ -46,6 +49,7 @@ export { JOURNAL, type Journal } from './dispatch/Journal.js';
 // them — or a test of one — has to be able to make one through the facade.
 export { DispatchEvent } from './dispatch/DispatchEvent.js';
 export type { CallPage, CallRecord } from './contract.js';
+export { pageOf, asPage, type Page } from './contract.js';
 export { driftOf, agrees, explain, type CardDrift } from './contract.js';
 export type { OperationContract } from './wire/OperationContract.js';
 export type { OperationsMap } from './wire/OperationsMap.js';

package/src/node.ts

@@ -1,6 +1,7 @@
 /** What Fougere does with a filesystem, minus the scan — that is `@fougere/compiler`. */
 export { setModuleLoader, getModuleLoader } from './loader.js';
-export { loadConfig, loadCascadedConfig } from './FougereConfig.js';
+export { loadConfig, loadCascadedConfig, remotesOf } from './FougereConfig.js';
+export { statedModules } from './StatedModules.js';
 export { defineFrond, loadFrondConfig } from './FrondConfig.js';
 
 // Making a key and binding a name to it happen once, at a deployment, on a machine with

package/src/prefab/CrudConstructor.ts

@@ -6,6 +6,7 @@ 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 { pageOf, type Page } from '../wire/Page.js';
 import type { CrudOps } from './CrudOps.js';
 
 /**
@@ -56,7 +57,7 @@ function crudOps(entity: SchemaView & { partial?: () => SchemaView }): Record<st
       output: entity, cardinality: 'page',
       binding: [{ name: 'options', source: { kind: 'query' }, optional: true }],
       signature: {
-        name: 'list', returnType: returns(`ListResult<${name}>`, 'ListResult'),
+        name: 'list', returnType: returns(`Page<${name}>`, 'Page'),
         params: [{ name: 'options', type: { raw: 'ListOptions', name: 'ListOptions' }, optional: true }],
       },
     },
@@ -139,7 +140,7 @@ export function Crud<E extends EntityConstructor, V extends CrudViews | EntityCo
       this.storage = storage as Storage<T>;
     }
 
-    async list(options?: ListOptions): Promise<ListResult<T>> { return this.storage.list(options) as Promise<ListResult<T>>; }
+    async list(options?: ListOptions): Promise<Page<T>> { return pageOf(await this.storage.list(options)); }
     async findById(id: string): Promise<T | undefined> { return this.storage.findById(id); }
     async create(input: Partial<T>): Promise<T> { return this.storage.create(input); }
     async update(id: string, input: Partial<T>): Promise<T> { return this.storage.update(id, input); }

package/src/prefab/CrudOps.ts

@@ -1,7 +1,7 @@
 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 { Page } from '../wire/Page.js';
 import type { Storage } from '../storage/Storage.js';
 
 /** The view an op emits, fabricated. */
@@ -16,7 +16,7 @@ type OutOf<V, K extends CrudOpName, 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>>>;
+  list(options?: ListOptions, ...collected: never[]): Promise<Page<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>>;

package/src/prefab/MirrorConstructor.ts

@@ -27,7 +27,7 @@ export function Mirror<E extends EntityConstructor>(shape: E): MirrorConstructor
         written += await this.storage.upsertAll(page);
       }
 
-      return { written, since, ms: Date.now() - started };
+      return { written, ...(since && { since: since.toISOString() }), ms: Date.now() - started };
     }
   }
 

package/src/prefab/Refreshed.ts

@@ -2,8 +2,13 @@
 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;
+  /**
+   * The age the pull was asked to start from, as an ISO string — absent when it asked for
+   * everything. A STRING because a refresh is an operation: what it answers leaves through a
+   * facade, where only data crosses, and a `Date` reaches a caller here and an ISO string
+   * behind `fronds:` off the same code.
+   */
+  since?: string;
   /** How long the whole pass took, pull included. */
   ms: number;
 }

package/src/storage/Storage.ts

@@ -172,7 +172,7 @@ const KINDS = '|';
 /** The members behind a frame key, or `undefined` when the key is not one. */
 export function membersOfTogetherKey(key: string): { entities: string[]; providers: string[] } | undefined {
   if (key.length <= FRAME.length || !key.endsWith(FRAME)) return undefined;
-  const [entities, providers = ''] = key.slice(0, -FRAME.length).split(KINDS);
+  const [entities = '', providers = ''] = key.slice(0, -FRAME.length).split(KINDS);
   const split = (list: string) => list.split(SEPARATOR).filter(Boolean);
-  return { entities: split(entities!), providers: split(providers) };
+  return { entities: split(entities), providers: split(providers) };
 }

package/src/storage/Store.ts

@@ -1,8 +1,9 @@
-import { applyCreate, applyUpdate, Lifecycle, Role, type SchemaView } from '@fougere/schema';
+import { applyCreate, applyUpdate, Role, type SchemaView } from '@fougere/schema';
 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';
+import type { ListResult } from './ListResult.js';
 
 /** Instances addressed by key — what an adapter supplies, and all of it. */
 export interface Store {
@@ -45,19 +46,16 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
         ? Object.fromEntries(Object.entries(values).filter(([key]) => selected.has(key)))
         : values);
 
-      // Same contract as SQL: the key and the creation stamps survive an overwrite.
+      // Same contract as SQL: a row that is already there is UPDATED, so what the write leaves
+      // out stays where it was.
       // Named, and not reached through `this`: a caller may have wrapped these gestures,
       // 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;
+        const created = applyCreate(fields, applyUpdate(fields, input));
+        const id = created[pk] as string | undefined;
         if (id === undefined) throw new Error(`${name}.upsert(): no \`${pk}\` — an upsert needs the key it writes at.`);
         const previous = await store.get(keyOf(id));
-        if (previous) {
-          for (const [key, field] of Object.entries(fields)) {
-            if (key === pk || Lifecycle.of(field).stampedOnce) values[key] = previous[key];
-          }
-        }
+        const values = previous ? { ...previous, ...applyUpdate(fields, input) } : created;
         await store.set(keyOf(id), values);
         return pick(values);
       };
@@ -68,24 +66,8 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
           let items = await store.all();
           if (options?.where) items = items.filter((values) => matches(values, options.where));
           if (options?.orderBy) items = sorted(items, options.orderBy, options.order);
-          // Held before the page is cut, and after the filter: `total` answers "how many
-          // match", which is what a paginator divides. Reading `store.size` at the end
-          // answered a different question — everything the store holds, including the ones
-          // the filter exists to keep out of this caller's sight.
-          const matching = items.length;
-          const limit = options?.limit;
-          const offset = options?.page && limit ? (options.page - 1) * limit : options?.offset ?? 0;
-          if (offset > 0) items = items.slice(offset);
-          const hasMore = limit ? items.length > limit : false;
-          if (limit) items = items.slice(0, limit);
-          // The cursor is read before the scope cuts: a view that drops the key still
-          // pages, the way it does over SQL.
-          const endCursor = items.length > 0 ? String((items[items.length - 1] as any)[pk] ?? '') : undefined;
-          const result = items.map(pick) as any;
-          result.hasMore = hasMore;
-          result.endCursor = endCursor;
-          if (options?.count) result.total = matching;
-          return result;
+
+          return paged(items, options, pk, pick);
         },
         async findById(id: string) {
           const values = await store.get(keyOf(id));
@@ -206,3 +188,39 @@ const rank = (left: unknown, right: unknown): number => {
 
   return held === against ? 0 : held < against ? -1 : 1;
 };
+
+/**
+ * The page cut out of what matched.
+ *
+ * `total` is held BEFORE the cut and after the filter — it answers "how many match", which is
+ * what a paginator divides. Reading the store's size at the end answered a different question:
+ * everything it holds, including the rows the filter exists to keep out of this caller's sight.
+ */
+function paged(
+  matched: Values[],
+  options: { limit?: number; page?: number; offset?: number; count?: boolean } | undefined,
+  pk: string,
+  pick: (values: Values) => Values,
+): ListResult<Values> {
+  const matching = matched.length;
+  const limit = options?.limit;
+  const offset = options?.page && limit ? (options.page - 1) * limit : options?.offset ?? 0;
+
+  let items = offset > 0 ? matched.slice(offset) : matched;
+  const hasMore = limit ? items.length > limit : false;
+  if (limit) items = items.slice(0, limit);
+
+  // The cursor is read before the scope cuts: a view that drops the key still pages, the way it
+  // does over SQL.
+  const endCursor = items.length > 0
+    ? String((items[items.length - 1] as Record<string, unknown>)[pk] ?? '')
+    : undefined;
+
+  // An array that carries the page's terms on itself — what `ListResult` is.
+  const result = items.map(pick) as ListResult<Values>;
+  result.hasMore = hasMore;
+  result.endCursor = endCursor;
+  if (options?.count) result.total = matching;
+
+  return result;
+}

package/src/verify.ts

@@ -17,6 +17,16 @@ export type Misplaced = Diagnostic & {
 /** A dependency declared in a frond's scope, and what kind of thing it is. */
 type Registration = { frond: string; kind: string };
 
+/** Everything above a frond in the tree — what its scope reaches by walking up. */
+function ancestors(frond: FrondDescriptor, byName: Map<string, FrondDescriptor>): Set<string> {
+  const above = new Set<string>();
+  for (let at = frond.extends; at !== undefined && !above.has(at); at = byName.get(at)?.extends) {
+    above.add(at);
+  }
+
+  return above;
+}
+
 /**
  * The container keys a frond registers in its own scope, keyed as a handler's `deps` spell them —
  * DI resolves by type name, so both sides are PascalCase.
@@ -50,6 +60,7 @@ function injectablesOf(frond: FrondDescriptor) {
  */
 export function verify(app: { fronds: readonly FrondDescriptor[] }): Misplaced[] {
   const index = new Map<string, Registration>();
+  const byName = new Map(app.fronds.map((frond) => [frond.name, frond]));
   for (const frond of app.fronds) {
     for (const [key, reg] of registrationsOf(frond)) index.set(key, reg);
   }
@@ -76,6 +87,10 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Misplaced[]
         // façade key, or an unresolved name. None is a boundary crossing, and
         // an unresolved dependency is the container's complaint, not this rule's.
         if (!declared || declared.frond === frond.name) continue;
+        // An ANCESTOR is not across: the frond tree says this one resolves what that one
+        // declared, and its scope hangs off it. A sibling, a descendant or a stranger stays
+        // refused — inheriting code is not calling a frond.
+        if (ancestors(frond, byName).has(declared.frond)) continue;
         violations.push({
           code: 'cross-frond-dependency',
           severity: 'warning',

package/src/wire/AppMiddleware.ts

@@ -1,7 +1,16 @@
 import type { OperationContext } from './OperationContext.js';
 import type { AppNext } from './AppNext.js';
 
-export type AppMiddleware = (ctx: OperationContext, next: AppNext) => Promise<unknown>;
+/**
+ * A middleware answers what the chain answered — the same TYPE, whatever it does with the value.
+ *
+ * `T` is the whole rule and nothing enforces it at runtime: a middleware is handed a type it
+ * cannot name, so the only value of that type it can produce is the one `next()` gave it. It may
+ * observe it, log it, replace it with another of the same shape, or refuse by throwing; it may
+ * not wrap it in `{ data, meta }` nor invent one, because a caller reads the handler's signature
+ * and nothing tells that signature a middleware stood in the way.
+ */
+export type AppMiddleware = <T>(ctx: OperationContext, next: AppNext<T>) => Promise<T>;
 
 // ── Runner ──────────────────────────────────────
 

package/src/wire/AppNext.ts

@@ -1 +1,2 @@
-export type AppNext = () => Promise<unknown>;
+/** What a middleware holds: the rest of the chain, and the answer it will hand back. */
+export type AppNext<T = unknown> = () => Promise<T>;

package/src/wire/Facade.ts

@@ -10,10 +10,22 @@ type Served = keyof FougereOperations & string;
  */
 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`. */
+/**
+ * The facade built in front of a handler — the framework's second port, after `Storage`.
+ *
+ * What the handler knows is WHICH operations exist and what each one answers. The two ends are
+ * the port's own: an invocation goes in where the handler takes positional arguments, and a
+ * promise comes back where the handler may answer a bare value. A facade is a crossing, and a
+ * crossing is awaited before any transport — the dispatch resolves a route, runs the middlewares
+ * and awaits the collectors, so `readLocation(): string` was typed as answering now and never did.
+ *
+ * `Awaited` because a promise does not stack: `Promise.resolve(p)` IS `p`, so writing
+ * `Promise<R>` over an async handler would describe a `Promise<Promise<Post>>` that no value can
+ * have — `.then` would hand its callback a promise the runtime never delivers.
+ */
 export type Facade<T> = {
   [K in keyof T]: T[K] extends (...args: never[]) => infer R
-    ? (invocation?: InvocationContext) => R
+    ? (invocation?: InvocationContext) => Promise<Awaited<R>>
     : never;
 };
 

package/src/wire/FougereError.ts

@@ -20,7 +20,7 @@ export class FougereError<Code extends ErrorCode = ErrorCode> extends Error {
 
   constructor(options: FougereErrorOptions<Code>) {
     super(options.message, { cause: options.cause });
-    this.name = new.target.name;
+    this.name = 'FougereError';
     this.code = options.code;
     this.entity = options.entity;
     this.operation = options.operation;

package/src/wire/Invocation.ts

@@ -24,6 +24,8 @@ function canonicalRecord(value: unknown): Record<string, unknown> {
 
 /** Canonical invocation shared by every entry and transport. */
 export class Invocation implements InvocationContext {
+  static readonly empty = Invocation.from();
+
   readonly params: Record<string, unknown>;
   readonly query: Record<string, unknown>;
   readonly input: unknown;
@@ -53,7 +55,6 @@ export class Invocation implements InvocationContext {
     return context instanceof Invocation ? context : new Invocation(context ?? {});
   }
 
-  static readonly empty = Invocation.from();
 
   /** Replaces the input — how the façade hands on the value it parsed. */
   withInput(input: unknown): Invocation {

package/src/wire/OperationContract.ts

@@ -36,7 +36,7 @@ export function cardinalityOf(type: TypeRef | undefined): OperationContract['car
   if (!type) return undefined;
   const inner = type.name === 'Promise' ? type.generics?.[0] : type;
   if (!inner) return 'none';
-  if (inner.name === 'ListResult') return 'page';
+  if (inner.name === 'Page' || inner.name === 'ListResult') return 'page';
   if (inner.array) return 'many';
   if (PRIMITIVE_RETURNS.has(inner.name)) return 'none';
   return inner.nullable || inner.undefined ? 'maybe' : 'one';