@fougere/core 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/wire/call.ts

@@ -1,17 +1,21 @@
-/**
- * Call contract — a frond call is a value.
- *
- * (frond, entity, op, invocation) → result, or a thrown FougereError.
- * A transport is a function that executes this call elsewhere; the local
- * runner below is the reference realization. Transports move the value,
- * they never reshape it.
- */
+/** Call contract — a frond call is a value. */
 import { Card, type SchemaDescriptor } from '@fougere/schema';
 import { factsAnnouncedBy } from '../emit.js';
-import type { InvocationContext } from '../contract/Invocation.js';
+import { Invocation, type InvocationContext, type PartialInvocation } from './Invocation.js';
+import type { RouteAddress } from './RouteAddress.js';
 import { FougereError, ErrorCode } from './errors.js';
-import type { App } from '../boot/types.js';
-import { createTransportEntry } from '../entry/TransportEntry.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);
+  }
+}
 
 /** Target of a call — which façade operation, wherever it lives. */
 export interface FrondCall {
@@ -27,49 +31,27 @@ export interface FrondCall {
 export type Transport = (call: FrondCall, invocation: InvocationContext) => Promise<unknown>;
 
 /** Reserved namespace — calls the runner answers itself, never a façade. */
-/**
- * What a receiver accepts before it stops reading a body.
- *
- * Stated once because it was stated FOUR times — `transport/http/policy.ts` said so in its
- * own comment ("spelled in four packages") while three doors kept their own literal, so
- * raising the cap here used to leave three of them refusing at the old one.
- *
- * `@fougere/http` keeps a fourth copy on purpose: it declares no Fougere dependency at all,
- * and giving a leaf port a dependency on the kernel to share a number is the wrong trade.
- */
+/** What a receiver accepts before it stops reading an input. */
 export const MAX_BODY_BYTES = 1024 * 1024;
 
 export const RPC_ENTITY = 'rpc';
 
-/**
- * What an `rpc` op answers — the door for what the app says about ITSELF, never about a row.
- *
- * `discover` is core's own, registered like any other (`bootstrap.ts`): a package declares
- * its reading beside it, and an app that installed none serves none.
- */
+/** What an `rpc` op answers — the door for what the app says about ITSELF, never about a row. */
 export type RpcAnswer = (invocation: InvocationContext, surface?: string) => unknown;
 
-/**
- * Everything a caller's envelope covers — the call as the sender meant it.
- *
- * Here and not beside the signing code because it is a CONTRACT: the sender binds it,
- * the receiver re-presents what arrived, and a frond written in another language reads
- * this shape without reading our crypto. `body` is bound by digest (arbitrary, possibly
- * large), the rest by value — which is what keeps a canonical-JSON dependency out.
- */
+/** Everything a caller's envelope covers — the call as the sender meant it. */
 export interface SignedCall {
   entity: string;
   op: string;
   params?: Record<string, unknown>;
   query?: Record<string, unknown>;
-  body?: unknown;
+  input?: unknown;
   state?: Record<string, unknown>;
 }
 
 /**
- * One operation, as a stranger meets it — its name, what it is for, what it takes
- * and whether it reads or writes. Everything here already existed on the contract;
- * it just never left the process.
+ * One operation, as a stranger meets it — its name, what it is for, what it takes and whether it
+ * reads or writes.
  */
 export interface CardOp {
   name: string;
@@ -81,57 +63,21 @@ export interface CardOp {
   output?: SchemaDescriptor;
   /** `query` reads, `command` writes — the same call REST turns into GET vs POST. */
   kind: 'query' | 'command';
-  /**
-   * How much `output` describes: one row, maybe one, many, a page, or nothing shaped.
-   * `output` alone is the shape of a ROW, so a consumer generating a signature from
-   * this card would otherwise have to guess — and `list` returning a page rather than
-   * an array is exactly the guess it would get wrong.
-   */
+  /** How much `output` describes. */
   cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
 }
 
-/**
- * What an app hosts — the wire projection of its scanned fronds.
- *
- * Two lists per frond, and they are duals: **what you may call**, and **what you will
- * receive**. A door is entered from outside; a fact leaves on its own.
- *
- * `doors` was called `entities` and the name lied: an entry is an ADDRESS, and the shape
- * behind it is optional (`facadeKeyOf` builds its key from a handler's name, which need not
- * be an entity's). The lie cost something real — `fougere sync` demanded a descriptor on
- * every entry and refused whole cards over a health check.
- */
+/** What an app hosts — the wire projection of its scanned fronds. */
 export interface IdentityCard {
   fronds: {
     name: string;
     doors: {
       name: string;
       ops: CardOp[];
-      /**
-       * The shape stored under this name — **absent when nothing is**. A handler may
-       * carry no entity (`bootstrap`: *pointing at nothing is legal*), and a door with
-       * no rows behind it is ordinary: a health check, a computation, a search across
-       * several shapes. A reader that needs the shape must say what it does without one.
-       */
+      /** The shape stored under this name — **absent when nothing is**. */
       schema?: SchemaDescriptor;
     }[];
-    /**
-     * The facts this frond ANNOUNCES — one entry per `Emit<T>` its handlers inject.
-     *
-     * They carry no operation, which is why they cannot ride in `doors`: the rule there is
-     * *hosting means answering*, and an entity with no façade is excluded on purpose (it
-     * would publish the auth tables to anyone who asks). A fact is the opposite case —
-     * someone WROTE that it leaves, so publishing its shape is honouring a statement, not
-     * leaking one.
-     *
-     * Without this, a fact stopped at the repository boundary: `remotes:` gives the
-     * location, colocation gives the contract, and across two repositories there is no
-     * colocation. The subscriber had to hand-copy the emitter's declaration.
-     *
-     * `schema` is absent when the announced type is not a declared entity — legal (nothing
-     * requires a fact to be one) and worth saying rather than hiding: the name travels, the
-     * shape does not, and a consumer can see exactly that.
-     */
+    /** The facts this frond ANNOUNCES — one entry per `Emit<T>` its handlers inject. */
     facts: { name: string; schema?: SchemaDescriptor }[];
   }[];
 }
@@ -152,17 +98,7 @@ export interface Edge {
   errors: number;
 }
 
-/**
- * The shape of the system as ONE process discovered it — the answer to `rpc.topology`.
- *
- * Here and not in the package that produces it, for the reason `SignedCall` is here: it
- * crosses a process boundary, so a reader consumes it without depending on the producer.
- * `@fougere/observability` fills it; a panel reads it; neither imports the other.
- *
- * Nothing in it is declared — a frond is `local` because this process scanned it, `remote`
- * because it answered a call nobody here hosts. `remotes:` states an intent, and the two
- * disagree exactly when something is misconfigured.
- */
+/** The shape of the system as ONE process discovered it — the answer to `rpc.topology`. */
 export interface TopologyReport {
   /** When this process started counting — an edge count is read against it. */
   since: number;
@@ -172,18 +108,7 @@ export interface TopologyReport {
   edges: Edge[];
 }
 
-/**
- * The shape a card must have to be walked — `fronds`, and each frond's `doors`.
- *
- * A card crosses a process boundary, so it is judged like anything else that does.
- * The check lives beside the type because two readers walk it: the boot indexes a
- * remote's doors, and `fougere sync` writes classes from them. `TypeError:
- * card.fronds is not iterable` was what a malformed card produced at the boot,
- * naming neither the remote nor the address.
- *
- * The descriptor behind a door is NOT checked here — `Card.toSchema` refuses it, and
- * only where one is consumed.
- */
+/** The shape a card must have to be walked — `fronds`, and each frond's `doors`. */
 export function assertIdentityCard(value: unknown, source: string): IdentityCard {
   const card = value as IdentityCard | undefined;
   const fronds = Array.isArray(card?.fronds) ? card.fronds : undefined;
@@ -206,176 +131,20 @@ function cardRefusal(source: string, what: string): FougereError {
 }
 
 /** A façade as the runtime holds it: op names to functions, nothing typed about them. */
-type AnyFacade = Record<string, (invocation?: InvocationContext) => Promise<unknown>>;
 
-/**
- * The door built in front of a handler — the framework's second port, after `EntityOrm`.
- *
- * `Facade<PostHandler>` is what a neighbouring frond injects. It names what ARRIVES
- * rather than what is written: never the handler (nobody injects it, and its methods take
- * positional arguments), but the door, whose every op takes the invocation and whose
- * implementation is the local façade or a doublure. A signature therefore says nothing
- * about where the other frond runs, which is the whole point.
- *
- * `keyof T` is the right set by construction, not by approximation: the scan skips
- * `private` and `protected` (`handler-parser.ts`) because "TypeScript already has the
- * word for it", so a handler's public methods ARE its operations — and `keyof` excludes
- * the rest for the same reason.
- */
+/** The door built in front of a handler — the framework's second port, after `Storage`. */
 export type Facade<T> = {
   [K in keyof T]: T[K] extends (...args: never[]) => infer R
     ? (invocation?: InvocationContext) => R
     : never;
 };
 
-/**
- * The container key of a façade — THE one place that spells the format.
- *
- * A surface is a named audience, and it is a key: `handlers/public/PostHandler.ts`
- * registers `public:postHandler` next to the default `postHandler`. The default
- * surface is the empty key, so callers that know nothing about surfaces keep
- * designating exactly what they designated before.
- *
- * Nobody outside this package builds this string: adapters ask `app.facadeFor()`,
- * which is why an adapter can stay structurally typed and core-free.
- */
+/** The container key of a façade — THE one place that spells the format. */
 export function facadeKeyOf(entityName: string, surface?: string): string {
   return surface ? `${surface}:${entityName}Handler` : `${entityName}Handler`;
 }
 
-/**
- * Where the contracts behind a façade live — the dual of `facadeKeyOf`.
- *
- * The façade answers calls; it does not say what it answers. That sentence used
- * to be true only inside `buildFacade`, so anything asking the app what it hosts
- * got bare names. A door and its terms are registered together, under the same
- * audience.
- */
+/** Where the contracts behind a façade live — the dual of `facadeKeyOf`. */
 export function contractsKeyOf(entityName: string, surface?: string): string {
   return `${facadeKeyOf(entityName, surface)}:contracts`;
 }
-
-/**
- * Serialize what the app hosts, for one audience. Served on `rpc.discover`,
- * cached by callers.
- *
- * Hosting means answering: an entity with no façade declares no operation, so
- * it is not among the DOORS — publishing its shape would hand an anonymous caller
- * the structure of tables it can never reach (the auth tables, typically), and
- * `fougere sync` would rebuild a schema with nothing to call on it.
- *
- * `facts` is the one thing that shape-without-a-door rule does not cover, and the
- * reason is the opposite of a leak: an entity nobody exposed is silent, whereas a
- * fact was explicitly declared to leave.
- *
- * `surface` makes that sentence audience-aware rather than app-wide: a door
- * answers with what IT serves. Nothing falls back to the full façade — under a
- * named surface, an entity with no façade of its own is simply not there.
- */
-export function identityCardOf(app: App, surface?: string): IdentityCard {
-  const declared = app.fronds.schemas();
-
-  return {
-    fronds: app.fronds.map((frond) => {
-      // What the frond answers to, not what it stores. This walked `frond.entities`, so a
-      // handler carrying no entity — a health check, a search across shapes — was built,
-      // served, and absent from the card: `sync` could not generate its door and a remote
-      // consumer had no way to know it existed. The boot has said "pointing at nothing is
-      // legal" since handlers became the subject; the card had not caught up.
-      const byEntity = new Map(frond.entities.map((entity) => [entity.name, entity]));
-      const addresses = [...new Set([
-        ...frond.entities.map((entity) => entity.name),
-        ...frond.handlers.map((handler) => handler.address),
-      ])];
-
-      return {
-        name: frond.name,
-        doors: addresses.flatMap((address) => {
-          const ops = facadeOps(app, address, surface);
-          if (ops.length === 0) return [];
-          const entity = byEntity.get(address);
-          return [{
-            name: address,
-            ops,
-            // Absent when nothing of that name is stored. A door is still a door.
-            ...(entity ? { schema: Card.fromSchema(entity.entityClass, address).descriptor } : {}),
-          }];
-        }),
-        /**
-         * What leaves on its own — the same list on every surface, deliberately.
-         *
-         * A door has an audience; a fact does not. `Emit<T>` names a subject and *the
-         * number of readers is not the emitter's business* (`emit.ts`), so narrowing this
-         * by `surface` would invent an axis the primitive refuses. The consequence is
-         * stated rather than hidden: a fact's SHAPE is readable by anyone who can read the
-         * card at all. What must not be published must not be announced.
-         */
-        facts: factsAnnouncedBy(frond.handlers).map((name) => {
-          const entityClass = declared.get(name);
-          return { name, ...(entityClass ? { schema: Card.fromSchema(entityClass, name).descriptor } : {}) };
-        }),
-      };
-    }),
-  };
-}
-
-function facadeOps(app: App, entityName: string, surface?: string): CardOp[] {
-  let facade: AnyFacade;
-  try {
-    facade = app.container.resolve<AnyFacade>(facadeKeyOf(entityName, surface));
-  } catch {
-    return [];
-  }
-
-  // The façade is the list of names; the model is the resolved terms.
-  const effective = app.operationsFor(entityName, surface);
-  if (!effective) {
-    throw new Error(
-      `Facade '${facadeKeyOf(entityName, surface)}' exists without an effective operation table.`,
-    );
-  }
-
-  return Object.keys(facade).map((name) => {
-    const contract = effective.get(name);
-    if (!contract) {
-      throw new Error(
-        `Facade '${facadeKeyOf(entityName, surface)}' serves '${name}' without an effective contract.`,
-      );
-    }
-
-    return {
-      name,
-      ...(contract?.description && { description: contract.description }),
-      ...(contract?.input && { input: Card.fromSchema(contract.input, name).descriptor }),
-      ...(contract?.output && { output: Card.fromSchema(contract.output, name).descriptor }),
-      ...(contract?.cardinality && { cardinality: contract.cardinality }),
-      kind: contract.kind,
-    };
-  });
-}
-
-/**
- * Build the local runner — the reference realization of Transport.
- *
- * Resolves strictly from the app's own container: a call that lands here is
- * judged here. A miss is a typed NOT_FOUND, never a forward to another remote.
- */
-export function createLocalRunner(app: App, surface?: string): Transport {
-  return createTransportEntry(app.local, surface);
-}
-
-/**
- * Build the app runner — same judgment, but resolution follows the app's
- * topology: local façades and remote doublures alike. This is the runner
- * an app's own entry points (browser endpoint, bridges) stand on.
- *
- * `surface` is the audience this runner serves, and it belongs to the DOOR that
- * builds the runner, never to the call: a caller cannot name its own audience
- * any more than it can name its own identity (`state` is stamped server-side
- * for the same reason). Reaching the admin door IS the proof. So `FrondCall`
- * gains nothing and the wire format gains nothing — a remote frond's audience
- * is simply which URL `remotes:` points at.
- */
-export function createAppRunner(app: App, surface?: string): Transport {
-  return createTransportEntry(app, surface);
-}

package/src/wire/drift.ts

@@ -1,13 +1,7 @@
 import { Card, type Change, type SchemaDescriptor } from '@fougere/schema';
 import type { IdentityCard } from './call.js';
 
-/**
- * What separates the copy a consumer holds from what the producer actually serves.
- *
- * It lives beside `IdentityCard` and not in `@fougere/testing` for the reason the card
- * itself does: the subject is the card, and a second reader arrived — the dev panel, which
- * must not drag a 426 KB faker in to compare two of them.
- */
+/** What separates the copy a consumer holds from what the producer actually serves. */
 export interface CardDrift {
   frond: string;
   /** A door the consumer calls that the producer no longer serves. */
@@ -41,26 +35,13 @@ function factsOf(card: IdentityCard, frond: string): Map<string, SchemaDescripto
   return found;
 }
 
-/**
- * What a consumer's synced copy no longer matches in what the producer serves.
- *
- * The gap TypeScript cannot see, and the only place the gradient genuinely lies: the code
- * is identical in-process and split, but one side may have aged. `fougere sync` wrote the
- * consumer's copy three weeks ago, the producer moved on, and it still compiles —
- * production is where that is found today. This is what Pact sells; the material was
- * already here, in `rpc.discover` and in `Card.diff`.
- *
- * Read in ONE direction on purpose: what the consumer holds, checked against what is
- * served. A producer serving MORE than the consumer knows is not drift — it is a producer
- * that moved forward without breaking anyone, which is the whole point of the order the
- * repo already states (re-sync the readers, then deploy the sender).
- */
+/** What a consumer's synced copy no longer matches in what the producer serves. */
 export function driftOf(mine: IdentityCard, theirs: IdentityCard, frond: string): CardDrift {
-  const held = doorsOf(mine, frond);
+  const mineDoors = doorsOf(mine, frond);
   const served = doorsOf(theirs, frond);
   const drift: CardDrift = { frond, missingDoors: [], missingOps: [], shapes: [], facts: [] };
 
-  for (const [name, door] of held) {
+  for (const [name, door] of mineDoors) {
     const there = served.get(name);
     if (!there) { drift.missingDoors.push(name); continue; }
 
@@ -97,13 +78,7 @@ export function agrees(drift: CardDrift): boolean {
     && drift.facts.length === 0;
 }
 
-/**
- * The drift, in the words a deploy needs.
- *
- * A fact says the order out loud, because the repo already states it as a rule and
- * nothing enforced it: a fact is judged strictly, so a reader that has not been re-synced
- * refuses what the sender now announces.
- */
+/** The drift, in the words a deploy needs. */
 export function explain(drift: CardDrift): string[] {
   const lines: string[] = [];
   for (const door of drift.missingDoors) lines.push(`${drift.frond}.${door} — you call it, it is not served`);

package/src/wire/errors.ts

@@ -1,11 +1,4 @@
-/**
- * The error vocabulary — what a refusal IS, independently of who hears it.
- *
- * It travels on the wire (`toJSON`/`fromJSON`) and through the browser-safe
- * `@fougere/core/contract`, so nothing here may know about HTTP, a logger, or a
- * middleware chain. Its HTTP reading is one file over, in `http-error.ts`; it used
- * to live in `middleware.ts`, which named the one concept this is not.
- */
+/** The error vocabulary — what a refusal IS, independently of who hears it. */
 
 import type { ValidationError } from '@fougere/schema';
 
@@ -79,12 +72,7 @@ export class FougereError extends Error {
     };
   }
 
-  /**
-   * Dual of toJSON — rebuild a typed error from its wire form.
-   *
-   * Wire input is untrusted: an unknown code degrades to INTERNAL_ERROR
-   * (original code kept in details) instead of forging a fake semantic code.
-   */
+  /** Dual of toJSON — rebuild a typed error from its wire form. */
   static fromJSON(json: unknown): FougereError {
     const raw = (typeof json === 'object' && json !== null ? json : {}) as Record<string, unknown>;
     const known = Object.values(ErrorCode).includes(raw.code as ErrorCode);
@@ -99,16 +87,8 @@ export class FougereError extends Error {
 }
 
 /**
- * The refusals behind a VALIDATION_FAILED, or nothing — the ONE place that reads
- * `details` under that code.
- *
- * `details` is `unknown` because it is genuinely polymorphic: `StorageGuard.judge` puts a
- * `string[]` there under INTERNAL_ERROR, `fromJSON` puts `{ originalCode, details }`
- * there for a code it does not know. So the shape is not the field's, it is a reading
- * of the PAIR (code, details) — which is why this is a reader and not a narrower type.
- *
- * It judges rather than casts: five call sites asserted `{ path, message }[]` by hand,
- * and a malformed VALIDATION_FAILED would have been accepted as structured refusals.
+ * The refusals behind a VALIDATION_FAILED, or nothing — the ONE place that reads `details` under
+ * that code.
  */
 export function validationErrorsOf(error: unknown): ValidationError[] | undefined {
   if (!(error instanceof FougereError) || error.code !== ErrorCode.VALIDATION_FAILED) return undefined;

package/src/wire/http-error.ts

@@ -1,17 +1,9 @@
-/**
- * HTTP reading of an error — used by HTTP bridges (REST, Next, Inertia).
- *
- * Not imported by GraphQL, CLI, or event bus bridges. The vocabulary it projects
- * is in `errors.ts` and knows nothing of this file.
- */
+/** HTTP reading of an error — used by HTTP bridges (REST, Next, Inertia). */
 import { FougereError, ErrorCode } from './errors.js';
-import { Logger } from '../builtins/logger.js';
+import { Logger } from '../builtin/logger.js';
 /**
- * An INTERNAL_ERROR is the one class of error whose message never leaves: it was not
- * written for a caller and may quote a path, a query or a row. Masking it is right, and
- * masking it *silently* is how a bug becomes unobservable — the operator loses the same
- * sentence the attacker does. So the mask and the record live in one function: whoever
- * calls `toPublicError` cannot forget the half that keeps the error findable.
+ * An INTERNAL_ERROR is the one class of error whose message never leaves: it was not written for a
+ * caller and may quote a path, a query or a row.
  */
 const log = new Logger('error');
 
@@ -42,13 +34,7 @@ function httpStatusFor(code: ErrorCode): number {
   return HTTP_STATUS[code] ?? 500;
 }
 
-/**
- * Serialize an application error for an untrusted caller.
- *
- * Every code but INTERNAL_ERROR was written for the caller and travels whole. An
- * INTERNAL_ERROR is replaced by a constant — and logged here, with its cause, so the
- * sentence exists exactly once: on the server.
- */
+/** 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('.');

package/src/wire/loggerMiddleware.ts

@@ -2,15 +2,9 @@
  * Logger middleware — logs every operation with timing.
  */
 import type { AppMiddleware } from './middleware.js';
-import type { Logger } from '../builtins/logger.js';
+import type { Logger } from '../builtin/logger.js';
 
-/**
- * Create a logger middleware that logs operation entry, exit, and errors.
- *
- * ```ts
- * app.use(loggerMiddleware(app.resolve('Logger')))
- * ```
- */
+/** Create a logger middleware that logs operation entry, exit, and errors. */
 export function loggerMiddleware(logger: Logger): AppMiddleware {
   return async (ctx, next) => {
     const start = performance.now();

package/src/wire/middleware.ts

@@ -1,8 +1,4 @@
-/**
- * App-level middleware — intercepts handler facade operations.
- *
- * Works regardless of entry point (HTTP, Nitro, event bus, CLI, tests).
- */
+/** App-level middleware — intercepts handler facade operations. */
 
 // ── Types ───────────────────────────────────────
 export interface OperationContext {
@@ -19,8 +15,8 @@ export interface OperationContext {
   args: unknown[];
   /** Extensible bag — middlewares deposit data here (user, permissions, etc.). */
   state: Record<string, unknown>;
-  /** Transport-agnostic invocation context (params, query, body, state). */
-  invocation?: import('../contract/Invocation.js').InvocationContext;
+  /** Transport-agnostic invocation context (params, query, input, state). */
+  invocation?: import('../wire/Invocation.js').InvocationContext;
 }
 
 export type AppNext = () => Promise<unknown>;