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

package/src/EffectiveOperationModel.ts

@@ -117,6 +117,25 @@ export function resolveEffectiveOperations(
         const contract = normalizeBinding(rawContract, handler, frond, name, resolutionDiagnostics);
         if (!contract) continue;
 
+        // An operation answers DATA — what JSON keeps. A DECLARED output is converted by its
+        // fields, so `created()` leaves as an ISO string and nothing is asked of it here; an
+        // undeclared one has nothing to convert it, so it must already be data. Measured
+        // 2026-09-18: `{ at: new Date(0) }` reaches a local caller as a `Date` and a remote one
+        // as a string, and an object carrying methods loses them on both sides, differently.
+        if (!contract.output && contract.signature?.notData) {
+          resolutionDiagnostics.push({
+            severity: 'blocking',
+            code: 'operation-output-not-data',
+            filePath: handler.filePath,
+            frond: frond.name,
+            subject,
+            message: `${subject}() answers ${contract.signature.notData}, which carries methods.\n`
+              + '  An operation answers data — what JSON keeps.\n'
+              + '  Declare the output as an entity, whose fields convert it, or answer what it produces.',
+          });
+          continue;
+        }
+
         const override = frond.operationsOverrides?.[name];
         const inference = inferOperationKind(name);
         const inferredKinds = new Set<OperationKind>();

package/src/boot/install.ts

@@ -37,6 +37,7 @@ import { RouteAddress } from '../wire/RouteAddress.js';
 import { servedSurfaces } from '../descriptor/surface.js';
 import { OperationRoute } from '../dispatch/OperationRoute.js';
 import { facadeOperations } from '../entry/facade.js';
+import { decoded } from '../dispatch/decoded.js';
 
 /**
  * What the app is made of while it is still being made. `createApp` builds these, hands
@@ -449,6 +450,9 @@ function buildFacadeInto(
     handler.address,
     routeRegistry.operationNames(handler.address, handler.surface),
     handler.surface,
+    // The output SCHEMA, per op: `Crud(Post, { list: PostCard })` names a different one for
+    // one operation, so the answer is read back through the view that op actually serves.
+    (operation, answer) => decoded(facade.effectiveOperations.get(operation)?.output, answer),
   ));
 }
 

package/src/boot/remote.ts

@@ -15,6 +15,7 @@ import { ErrorCode } from '../wire/ErrorCode.js';
 import { FougereError } from '../wire/FougereError.js';
 import { Card, type SchemaView, type SchemaDescriptor } from '@fougere/schema';
 import { dynamicOperations } from '../entry/facade.js';
+import { decoded } from '../dispatch/decoded.js';
 
 interface Route {
   frond: string;
@@ -103,13 +104,19 @@ export function createRemoteFacade(
   middlewaresFor: (address: string) => AppMiddleware[],
 ): Facade {
   const opFn = (op: string) => async (invocation: InvocationContext = Invocation.empty) => {
-    const { frond, transport } = await router.route(entity);
+    const { frond, transport, schema } = await router.route(entity);
     const call: FrondCall = { frond, entity, op };
     const ctx: OperationContext = {
       entity, frond, operation: op, args: [], state: invocation.state, invocation,
     };
-    return runMiddlewares(middlewaresFor(entity), ctx, () =>
+    const answer = await runMiddlewares(middlewaresFor(entity), ctx, () =>
       transport(call, ctx.invocation ?? invocation));
+
+    // The schema the card carried, put to work: a row crosses as data and comes back through
+    // the same codecs a local facade applies, so a placement does not decide what a caller
+    // holds. It is the ENTITY's — an op serving a narrower view is the far side's business,
+    // and what this card names is the shape it publishes.
+    return decoded(schema, answer);
   };
 
   return dynamicOperations(opFn) as Facade;

package/src/contract.ts

@@ -29,6 +29,7 @@ export { MAX_BODY_BYTES } from './wire/SignedCall.js';
 // call log ignoring its own reader — has to be able to name it.
 export { RPC_ENTITY } from './wire/RpcAnswer.js';
 export type { CallPage } from './wire/CallPage.js';
+export { pageOf, asPage, type Page } from './wire/Page.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.
@@ -55,6 +56,7 @@ 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';
+export { decoded } from './dispatch/decoded.js';
 
 /** The key a class name is filed under — 'Post' → 'post'. */
 export { lowerFirst } from '@fougere/schema';

package/src/dispatch/OutputView.ts

@@ -1,5 +1,6 @@
 import { Visibility, type Fields } from '@fougere/schema';
 import { preserveArrayProperties } from './ArrayResult.js';
+import { asPage } from '../wire/Page.js';
 
 /** What one operation result may show. One of the two exits a validator watches. */
 export class OutputView {
@@ -15,6 +16,12 @@ export class OutputView {
       return preserveArrayProperties(result, result.map((item) => this.project(item)));
     }
 
+    // A paged op answers an envelope, so what a view applies to is its ROWS. Projecting the
+    // envelope itself let every field of every row through — `Visibility.encode` finds none of
+    // its own keys on `{ items, total }` and hands the object back.
+    const page = asPage(result, this.fields);
+    if (page) return { ...page, items: page.items.map((item) => this.project(item)) };
+
     if (typeof result !== 'object') return result;
 
     const record = result as Record<string, unknown>;

package/src/dispatch/PresenterExecutor.ts

@@ -2,6 +2,7 @@ import { ErrorCode } from '../wire/ErrorCode.js';
 import { FougereError } from '../wire/FougereError.js';
 import { preserveArrayProperties } from './ArrayResult.js';
 import type { PresenterArgs } from './PresenterArgs.js';
+import { asPage } from '../wire/Page.js';
 
 /** Adds a presenter's computed fields after output projection. */
 export class PresenterExecutor {
@@ -17,6 +18,12 @@ export class PresenterExecutor {
       return result;
     }
 
+    // A paged op answers an envelope, and what a computed field sits on is a ROW. Handed the
+    // envelope itself, a presenter added its fields to `{ items, total }` and every row came
+    // back untouched.
+    const page = asPage(result, Object.fromEntries(this.fieldNames.map((name) => [name, true])));
+    if (page) return { ...page, items: await this.present(page.items, args) as unknown[] };
+
     const rows = Array.isArray(result) ? result : [result];
     const values = new Map<string, unknown[]>();
     for (const name of this.fieldNames) {

package/src/dispatch/Received.ts

@@ -0,0 +1,2 @@
+/** What a facade puts back into an answer before handing it to its caller, read per operation. */
+export type Received = (operation: string, answer: unknown) => unknown;

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

@@ -49,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/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/Store.ts

@@ -1,4 +1,4 @@
-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';
@@ -46,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);
       };

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/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';

package/src/wire/Page.ts

@@ -0,0 +1,50 @@
+/**
+ * What a paged operation answers — the rows, and what the storage said about the rest of them.
+ *
+ * An ENVELOPE rather than the array `Storage.list` hands back: that one carries `total` and
+ * `hasMore` as properties OF the array, and `JSON.stringify` keeps only the indices. Measured
+ * 2026-09-18 — `page.total` is 42 in this process and `undefined` behind `fronds:`, off the same
+ * code. What crosses has to be named, so it is a field.
+ *
+ * `Storage.list` keeps its array: it answers inside a frond and never crosses.
+ */
+export interface Page<Row> {
+  items: Row[];
+  /** Only when the caller asked to count. */
+  total?: number;
+  hasMore?: boolean;
+  endCursor?: string;
+}
+
+/**
+ * The array `Storage.list` answers, read as the page an operation hands over.
+ *
+ * A storage handed in by a host may answer the envelope already — `storageFactory` is its door,
+ * and nothing there is obliged to subclass an array. Taken as it comes in that case.
+ */
+export function pageOf<Row>(rows: Page<Row> | readonly Row[]): Page<Row> {
+  if (!Array.isArray(rows)) return rows as Page<Row>;
+
+  const { total, hasMore, endCursor } = rows as unknown as Omit<Page<Row>, 'items'>;
+
+  return {
+    items: [...rows],
+    ...(total !== undefined && { total }),
+    ...(hasMore !== undefined && { hasMore }),
+    ...(endCursor !== undefined && { endCursor }),
+  };
+}
+
+/**
+ * The value read as a page, or nothing.
+ *
+ * Read from the FORM, and arbitrated by the schema: an entity legally declaring a field named
+ * `items` answers a row, not a page, and it is the only thing that could tell the two apart.
+ */
+export function asPage(value: unknown, fields: Record<string, unknown>): Page<unknown> | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  if ('items' in fields) return undefined;
+  const page = value as Page<unknown>;
+
+  return Array.isArray(page.items) ? page : undefined;
+}

package/src/wire/Signature.ts

@@ -10,4 +10,11 @@ export interface Signature {
   inherited?: boolean;
   /** The operation in words — the first sentence of the method's doc comment. */
   description?: string;
+  /**
+   * The first thing in the return type that is not data — its path, and the type sitting there.
+   *
+   * Written whenever a checker read the signature, and judged only where nothing converts the
+   * output: what a declared entity answers is encoded by its fields.
+   */
+  notData?: string;
 }