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

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