@fougere/core 0.16.7-alpha.0 → 0.17.0-alpha.0

package/src/dispatch/StorageGuard.ts

@@ -154,9 +154,7 @@ export class StorageGuard {
     if (errors.length > 0) {
       throw new FougereError({
         code: ErrorCode.BAD_REQUEST,
-        message: `Refused as a filter — ${errors.join(', ')}`,
-        entity: this.entity,
-        operation: 'list',
+        message: `Refused as a filter on ${this.entity} — ${errors.join(', ')}`,
         details: errors,
       });
     }
@@ -247,9 +245,7 @@ export class StorageGuard {
     if (errors.length > 0) {
       throw new FougereError({
         code: ErrorCode.INTERNAL_ERROR,
-        message: `Refused on the way out — ${errors.join(', ')}`,
-        entity: this.entity,
-        operation,
+        message: `Refused on the way out of ${this.entity}.${operation} — ${errors.join(', ')}`,
         details: errors,
       });
     }
@@ -287,9 +283,7 @@ export class StorageGuard {
 
     throw new FougereError({
       code: ErrorCode.VALIDATION_FAILED,
-      message: `Refused on the way out — ${errors.join(', ')}`,
-      entity: this.entity,
-      operation,
+      message: `Refused on the way out of ${this.entity}.${operation} — ${errors.join(', ')}`,
       details: errors,
     });
   }

package/src/dispatch/remoteRoutes.ts

@@ -2,14 +2,14 @@ import { OperationRoute } from './OperationRoute.js';
 import type { RouteResolver } from './RouteResolver.js';
 
 type RemoteFacade = Record<string, Function>;
-export type RemoteFacadeResolver = (entity: string) => RemoteFacade | undefined;
+export type RemoteFacadeResolver = (address: string) => RemoteFacade | undefined;
 
 /** Builds a remote route on the first call, once the remote façade can be resolved. */
 export function remoteRoutes(facades: RemoteFacadeResolver): RouteResolver {
   return (address) => {
     if (address.surface !== undefined) return undefined;
 
-    const facade = facades(address.entity);
+    const facade = facades(address.address);
     const operation = facade?.[address.operation];
 
     if (typeof operation !== 'function') return undefined;

package/src/dispatch/routeNotFound.ts

@@ -1,6 +1,7 @@
 import type { Call } from '../wire/Call.js';
 import { ErrorCode } from '../wire/ErrorCode.js';
 import { FougereError } from '../wire/FougereError.js';
+import { RPC_ADDRESS } from '../wire/RpcAnswer.js';
 import type { Route } from './Route.js';
 import type { RoutePolicy } from './RoutePolicy.js';
 
@@ -12,7 +13,7 @@ export function servedOperations(
 ): readonly string[] {
   return routes
     .filter((route) => !policy || policy.accepts(route))
-    .filter((route) => route.address.entity === call.address.entity)
+    .filter((route) => route.address.address === call.address.address)
     .filter((route) => route.kind === 'system' || route.address.surface === call.address.surface)
     .map((route) => route.address.operation);
 }
@@ -22,13 +23,13 @@ export function routeNotFound(
   call: Call,
   served: readonly string[],
 ): FougereError {
-  const { entity, operation } = call.address;
-  const message = entity === 'rpc'
+  const { address, operation } = call.address;
+  const message = address === RPC_ADDRESS
     ? `Unknown rpc operation '${operation}'. `
       + (served.length ? `It serves ${served.join(', ')}.` : 'It serves nothing.')
     : served.length
-      ? `Unknown operation '${operation}' on '${entity}'. It serves ${served.join(', ')}.`
+      ? `Unknown operation '${operation}' on '${address}'. It serves ${served.join(', ')}.`
       : `No route serves '${call.address}'`;
 
-  return new FougereError({ code: ErrorCode.NOT_FOUND, message, entity, operation });
+  return new FougereError({ code: ErrorCode.NOT_FOUND, message, address, operation });
 }

package/src/dispatch/validateInput.ts

@@ -7,8 +7,6 @@ import { FougereError } from '../wire/FougereError.js';
 export function validateInput(
   schema: SchemaView | undefined,
   invocation: InvocationContext,
-  entity: string,
-  operation: string,
 ): InvocationContext {
   if (!schema || invocation.input === undefined || invocation.input === null) return invocation;
 
@@ -20,8 +18,6 @@ export function validateInput(
       code: ErrorCode.VALIDATION_FAILED,
       message: result.errors.map((error) => `${dotted(error.path)}: ${error.message}`).join(', '),
       details: result.errors,
-      entity,
-      operation,
     });
   }
 

package/src/entry/facade.ts

@@ -32,7 +32,7 @@ export function dynamicOperations(operation: (name: string) => Operation): Recor
  */
 export function facadeOperations(
   dispatcher: DispatchPort,
-  entity: string,
+  address: string,
   operationNames?: Iterable<string>,
   surface?: string,
   received?: Received,
@@ -40,7 +40,7 @@ export function facadeOperations(
   const operation = (name: string): Operation => async (invocation) => {
     const answer = await dispatcher.dispatch(new Call(
       new RouteAddress({
-        entity,
+        address,
         operation: name,
         ...(surface !== undefined ? { surface } : {}),
       }),

package/src/entry/transport.ts

@@ -7,7 +7,7 @@ import type { Transport } from '../wire/Transport.js';
 export function createTransportEntry(dispatcher: DispatchPort, surface?: string): Transport {
   return (legacy, invocation) => dispatcher.dispatch(new Call(
     new RouteAddress({
-      entity: legacy.entity,
+      address: legacy.address,
       operation: legacy.op,
       ...(surface !== undefined ? { surface } : {}),
     }),

package/src/index.ts

@@ -62,7 +62,7 @@ export { FougereError, ErrorCode, validationErrorsOf } from './contract.js';
 export type { AppMiddleware } from './wire/AppMiddleware.js';
 export type { AppNext } from './wire/AppNext.js';
 export type { OperationContext } from './wire/OperationContext.js';
-export { assertIdentityCard, RPC_ENTITY, ENVELOPE_BYTES, maxBodyBytes, maxFrameBytes, setMaxBodyBytes } from './contract.js';
+export { assertIdentityCard, RPC_ADDRESS, ENVELOPE_BYTES, maxBodyBytes, maxFrameBytes, setMaxBodyBytes } from './contract.js';
 export { createLocalRunner, createAppRunner } from './boot/runner.js';
 
 // A frond an app STATES, for a boot that will not scan. No disk, no `typescript` — which

package/src/wire/CallRecord.ts

@@ -5,7 +5,7 @@ export interface CallRecord {
   /** Monotonic, and the whole cursor protocol: a reader asks for what is above its own. */
   seq: number;
   frond?: string;
-  entity: string;
+  address: string;
   operation: string;
   surface?: string;
   /** Known at `resolved`, so absent on a call that never found a route. */

package/src/wire/FougereError.ts

@@ -14,24 +14,35 @@ import type { FougereErrorOptions } from './FougereErrorOptions.js';
  */
 export class FougereError<Code extends ErrorCode = ErrorCode> extends Error {
   readonly code: Code;
-  readonly entity?: string;
-  readonly operation?: string;
+  address?: string;
+  operation?: string;
   readonly details?: unknown;
 
   constructor(options: FougereErrorOptions<Code>) {
     super(options.message, { cause: options.cause });
     this.name = 'FougereError';
     this.code = options.code;
-    this.entity = options.entity;
+    this.address = options.address;
     this.operation = options.operation;
     this.details = options.details;
   }
 
+  /**
+   * Where the call was refused. The facade a refusal crosses first is where it happened, so a
+   * facade further out leaves what a deeper one wrote.
+   */
+  at(address: string, operation: string): this {
+    this.address ??= address;
+    this.operation ??= operation;
+
+    return this;
+  }
+
   toJSON() {
     return {
       code: this.code,
       message: this.message,
-      ...(this.entity && { entity: this.entity }),
+      ...(this.address && { address: this.address }),
       ...(this.operation && { operation: this.operation }),
       ...(this.details !== undefined && { details: this.details }),
     };
@@ -45,7 +56,7 @@ export class FougereError<Code extends ErrorCode = ErrorCode> extends Error {
     return new FougereError({
       code: known ? (raw.code as ErrorCode) : ErrorCode.INTERNAL_ERROR,
       message: typeof raw.message === 'string' ? raw.message : 'Unknown error',
-      entity: typeof raw.entity === 'string' ? raw.entity : undefined,
+      address: typeof raw.address === 'string' ? raw.address : undefined,
       operation: typeof raw.operation === 'string' ? raw.operation : undefined,
       details: known ? raw.details : { originalCode: raw.code, details: raw.details },
     });

package/src/wire/FougereErrorOptions.ts

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

package/src/wire/FrondCall.ts

@@ -2,8 +2,8 @@
 export interface FrondCall {
   /** Frond name, when the caller knows it. Routing hint only. */
   frond?: string;
-  /** Entity registration key (e.g. 'product'). */
-  entity: string;
+  /** The address a handler answers at (e.g. 'product'). */
+  address: string;
   /** Façade operation name (e.g. 'findById', 'search'). */
   op: string;
 }

package/src/wire/OperationContext.ts

@@ -1,7 +1,7 @@
 // ── Types ───────────────────────────────────────
 export interface OperationContext {
-  /** Entity name (e.g. 'product'). */
-  entity: string;
+  /** The address the operation answers at — `checkout` in `checkout.pay`. */
+  address: string;
   /**
    * Which frond owns this operation — the unit that gets deployed, and therefore the
    * one a reader groups by first. Absent only where no frond claims the call.

package/src/wire/RouteAddress.ts

@@ -14,13 +14,13 @@ function optional(value: string | undefined, name: string): string | undefined {
 
 /** Canonical identity of one callable operation. */
 export class RouteAddress {
-  readonly entity: string;
+  readonly address: string;
   readonly operation: string;
   readonly surface?: string;
 
   /** Names one callable operation, and freezes it so a registry key cannot drift. */
   constructor(input: RouteAddressInput) {
-    this.entity = required(input.entity, 'entity');
+    this.address = required(input.address, 'address');
     this.operation = required(input.operation, 'operation');
     this.surface = optional(input.surface, 'surface');
     Object.freeze(this);
@@ -28,7 +28,7 @@ export class RouteAddress {
 
   /** Serializes the three segments so a route can be looked up in a `Map`. */
   key(): string {
-    return JSON.stringify([this.surface ?? null, this.entity, this.operation]);
+    return JSON.stringify([this.surface ?? null, this.address, this.operation]);
   }
 
   /** Compares two addresses by their key, so `surface` counts as much as the operation. */
@@ -40,13 +40,13 @@ export class RouteAddress {
   toString(): string {
     const audience = this.surface ? `${this.surface}/` : '';
 
-    return `${audience}${this.entity}.${this.operation}`;
+    return `${audience}${this.address}.${this.operation}`;
   }
 
   /** Sends the address over the wire without `surface: undefined` riding along. */
   toJSON(): RouteAddressInput {
     return {
-      entity: this.entity,
+      address: this.address,
       operation: this.operation,
       ...(this.surface !== undefined ? { surface: this.surface } : {}),
     };

package/src/wire/RouteAddressInput.ts

@@ -1,5 +1,5 @@
 export interface RouteAddressInput {
-  entity: string;
+  address: string;
   operation: string;
   surface?: string;
 }

package/src/wire/RpcAnswer.ts

@@ -1,7 +1,7 @@
 import type { InvocationContext } from './InvocationContext.js';
 
 /** Reserved namespace — calls the runner answers itself, never a façade. */
-export const RPC_ENTITY = 'rpc';
+export const RPC_ADDRESS = 'rpc';
 
 /** What an `rpc` op answers — the facade for what the app says about ITSELF, never about a row. */
 export type RpcAnswer = (invocation: InvocationContext, surface?: string) => unknown;

package/src/wire/SignedCall.ts

@@ -1,6 +1,6 @@
 /** Everything a caller's envelope covers — the call as the sender meant it. */
 export interface SignedCall {
-  entity: string;
+  address: string;
   op: string;
   params?: Record<string, unknown>;
   query?: Record<string, unknown>;

package/src/wire/StateShape.ts

@@ -51,7 +51,7 @@ export class StateShape {
    */
   judge(
     state: Record<string, unknown>,
-    entity: string,
+    address: string,
     operation: string,
     entered: Record<string, unknown> = {},
   ): Record<string, unknown> {
@@ -69,7 +69,7 @@ export class StateShape {
       message: errors.map((error) => `${dotted(error.path)}: ${error.message}`).join(', ')
         + (declared.length ? ` — this process declares ${declared.join(', ')}` : ' — this process declares no state member'),
       details: errors,
-      entity,
+      address,
       operation,
     });
   }

package/src/wire/card/IdentityCard.ts

@@ -7,18 +7,19 @@ import type { CardOp } from './CardOp.js';
 export interface IdentityCard {
   fronds: {
     name: string;
-    facades: {
-      name: string;
-      ops: CardOp[];
-      /** The shape stored under this name — **absent when nothing is**. */
-      schema?: SchemaDescriptor;
-    }[];
+    /** What the frond STORES — one schema per entity, under the entity's name. */
+    entities: { name: string; schema: SchemaDescriptor }[];
+    /**
+     * What the frond ANSWERS — one entry per address, each op carrying its own input and output.
+     * An output that IS an entity is titled with the entity's name.
+     */
+    facades: { name: string; ops: CardOp[] }[];
     /** The facts this frond ANNOUNCES — one entry per `Emit<T>` its handlers inject. */
     facts: { name: string; schema?: SchemaDescriptor }[];
   }[];
 }
 
-/** The shape a card must have to be walked — `fronds`, and each frond's `facades`. */
+/** The shape a card must have to be walked — `fronds`, and each frond's `entities` and `facades`. */
 export function assertIdentityCard(value: unknown, source: string): IdentityCard {
   const card = value as IdentityCard | undefined;
   const fronds = Array.isArray(card?.fronds) ? card.fronds : undefined;
@@ -26,6 +27,7 @@ export function assertIdentityCard(value: unknown, source: string): IdentityCard
   for (const frond of fronds) {
     if (!frond || typeof frond.name !== 'string') throw cardRefusal(source, 'a frond with no name');
     if (!Array.isArray(frond.facades)) throw cardRefusal(source, `frond '${frond.name}' has no valid facades array`);
+    if (!Array.isArray(frond.entities)) throw cardRefusal(source, `frond '${frond.name}' has no valid entities array`);
   }
 
   return card as IdentityCard;

package/src/wire/drift.ts

@@ -8,26 +8,18 @@ export interface CardDrift {
   missingDoors: string[];
   /** An operation the consumer calls that the facade no longer has. */
   missingOps: { facade: string; ops: string[] }[];
-  /** A shape that moved under a facade the consumer still calls. */
-  shapes: { facade: string; changes: Change[] }[];
+  /** What an operation the consumer still calls answers, and how it moved. */
+  shapes: { facade: string; op: string; changes: Change[] }[];
   /** A fact the consumer subscribes to whose shape moved, or that is gone. */
   facts: { fact: string; changes: Change[] | 'gone' }[];
 }
 
-/** Every facade of a card, by name. */
-/** What a door of that card answers, and the shape of the row it hands back. */
-interface Answering {
-  ops: Set<string>;
-  schema?: SchemaDescriptor;
-}
-
-function facadesOf(card: IdentityCard, frond: string): Map<string, Answering> {
-  const found = new Map<string, Answering>();
+/** Every facade of a card, by name, and what each of its operations answers. */
+function facadesOf(card: IdentityCard, frond: string): Map<string, Map<string, SchemaDescriptor | undefined>> {
+  const found = new Map<string, Map<string, SchemaDescriptor | undefined>>();
   for (const one of card.fronds) {
     if (one.name !== frond) continue;
-    for (const facade of one.facades) {
-      found.set(facade.name, { ops: new Set(facade.ops.map((op) => op.name)), schema: facade.schema });
-    }
+    for (const facade of one.facades) found.set(facade.name, new Map(facade.ops.map((op) => [op.name, op.output])));
   }
 
   return found;
@@ -53,29 +45,32 @@ export function driftOf(mine: IdentityCard, theirs: IdentityCard, frond: string)
   return drift;
 }
 
-/** A door that is gone, an operation it no longer answers, or a row that changed shape. */
+/** A door that is gone, an operation it no longer answers, or an answer that changed shape. */
 function driftInDoors(
-  mine: Map<string, Answering>,
-  theirs: Map<string, Answering>,
+  mine: Map<string, Map<string, SchemaDescriptor | undefined>>,
+  theirs: Map<string, Map<string, SchemaDescriptor | undefined>>,
   drift: CardDrift,
 ): void {
-  for (const [name, facade] of mine) {
+  for (const [name, ops] of mine) {
     const there = theirs.get(name);
     if (!there) {
       drift.missingDoors.push(name);
       continue;
     }
 
-    const missing = [...facade.ops].filter((op) => !there.ops.has(op));
+    const missing = [...ops.keys()].filter((op) => !there.has(op));
     if (missing.length > 0) drift.missingOps.push({ facade: name, ops: missing.sort() });
 
-    if (!facade.schema || !there.schema) continue;
+    for (const [op, output] of ops) {
+      const answered = there.get(op);
+      if (!output || !answered) continue;
 
-    // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
-    // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so the
-    // pair is reported as it is and a human reads it.
-    const moved = Card.fromDescriptor(facade.schema).diff(Card.fromDescriptor(there.schema));
-    if (moved.changes.length > 0) drift.shapes.push({ facade: name, changes: moved.changes });
+      // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
+      // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so the
+      // pair is reported as it is and a human reads it.
+      const moved = Card.fromDescriptor(output).diff(Card.fromDescriptor(answered));
+      if (moved.changes.length > 0) drift.shapes.push({ facade: name, op, changes: moved.changes });
+    }
   }
 }
 
@@ -112,8 +107,8 @@ export function explain(drift: CardDrift): string[] {
   const lines: string[] = [];
   for (const facade of drift.missingDoors) lines.push(`${drift.frond}.${facade} — you call it, it is not served`);
   for (const { facade, ops } of drift.missingOps) lines.push(`${drift.frond}.${facade} — gone: ${ops.join(', ')}`);
-  for (const { facade, changes } of drift.shapes) {
-    for (const change of changes) lines.push(`${drift.frond}.${facade} — ${describe(change)}`);
+  for (const { facade, op, changes } of drift.shapes) {
+    for (const change of changes) lines.push(`${drift.frond}.${facade}.${op} — ${describe(change)}`);
   }
   for (const { fact, changes } of drift.facts) {
     if (changes === 'gone') { lines.push(`${fact} — you subscribe to it, it is no longer announced`); continue; }

package/src/wire/http-error.ts

@@ -38,13 +38,13 @@ function httpStatusFor(code: ErrorCode): number {
 /** Serialize an application error for an untrusted caller. */
 export function toPublicError(err: FougereError): ReturnType<FougereError['toJSON']> {
   if (err.code !== ErrorCode.INTERNAL_ERROR) return err.toJSON();
-  const where = [err.entity, err.operation].filter(Boolean).join('.');
+  const where = [err.address, err.operation].filter(Boolean).join('.');
   log.error(`${where || 'internal'}: ${err.message}`, err.cause ?? err);
 
   return {
     code: ErrorCode.INTERNAL_ERROR,
     message: 'Internal error',
-    ...(err.entity && { entity: err.entity }),
+    ...(err.address && { address: err.address }),
     ...(err.operation && { operation: err.operation }),
   };
 }