@fougere/core 0.3.0-alpha.0 → 0.5.0-alpha.0

package/src/wire/call.ts

@@ -0,0 +1,381 @@
+/**
+ * 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.
+ */
+import { Card, type SchemaDescriptor } from '@fougere/schema';
+import { factsAnnouncedBy } from '../emit.js';
+import type { InvocationContext } from '../contract/Invocation.js';
+import { FougereError, ErrorCode } from './errors.js';
+import type { App } from '../boot/types.js';
+import { createTransportEntry } from '../entry/TransportEntry.js';
+
+/** Target of a call — which façade operation, wherever it lives. */
+export interface FrondCall {
+  /** Frond name, when the caller knows it. Routing hint only. */
+  frond?: string;
+  /** Entity registration key (e.g. 'product'). */
+  entity: string;
+  /** Façade operation name (e.g. 'findById', 'search'). */
+  op: string;
+}
+
+/** A transport executes a call somewhere else. Failures surface as thrown FougereError. */
+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.
+ */
+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.
+ */
+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.
+ */
+export interface SignedCall {
+  entity: string;
+  op: string;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  body?: 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.
+ */
+export interface CardOp {
+  name: string;
+  /** The author's own doc sentence, when the method carries one. */
+  description?: string;
+  /** JSON Schema of what it accepts, when the contract names a view. */
+  input?: SchemaDescriptor;
+  /** JSON Schema of what it emits, when the contract names one. */
+  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.
+   */
+  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.
+ */
+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.
+       */
+      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.
+     */
+    facts: { name: string; schema?: SchemaDescriptor }[];
+  }[];
+}
+
+/** A frond this process knows about, and whether it runs here. */
+export interface FrondPlacement {
+  frond: string;
+  placement: 'local' | 'remote';
+  entities: number;
+  doors: number;
+}
+
+/** One frond calling another — an edge of the graph, counted where the call was made. */
+export interface Edge {
+  from: string;
+  to: string;
+  count: number;
+  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.
+ */
+export interface TopologyReport {
+  /** When this process started counting — an edge count is read against it. */
+  since: number;
+  /** Calls running right now: the one signal a static shape cannot carry. */
+  active: number;
+  fronds: FrondPlacement[];
+  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.
+ */
+export function assertIdentityCard(value: unknown, source: string): IdentityCard {
+  const card = value as IdentityCard | undefined;
+  const fronds = Array.isArray(card?.fronds) ? card.fronds : undefined;
+  if (!fronds) throw cardRefusal(source, 'no fronds array');
+  for (const frond of fronds) {
+    if (!frond || typeof frond.name !== 'string') throw cardRefusal(source, 'a frond with no name');
+    if (!Array.isArray(frond.doors)) throw cardRefusal(source, `frond '${frond.name}' has no valid doors array`);
+  }
+  return card as IdentityCard;
+}
+
+function cardRefusal(source: string, what: string): FougereError {
+  return new FougereError({
+    code: ErrorCode.INTERNAL_ERROR,
+    message:
+      `${source} answered an invalid identity card: ${what}.\n`
+      + `  A card is what tells this process what the other one hosts, so nothing can be routed from it.\n`
+      + `  - Check that the address serves a Fougere app, and that its version still speaks this card.`,
+  });
+}
+
+/** 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.
+ */
+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.
+ */
+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.
+ */
+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

@@ -0,0 +1,131 @@
+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.
+ */
+export interface CardDrift {
+  frond: string;
+  /** A door the consumer calls that the producer no longer serves. */
+  missingDoors: string[];
+  /** An operation the consumer calls that the door no longer has. */
+  missingOps: { door: string; ops: string[] }[];
+  /** A shape that moved under a door the consumer still calls. */
+  shapes: { door: string; changes: Change[] }[];
+  /** A fact the consumer subscribes to whose shape moved, or that is gone. */
+  facts: { fact: string; changes: Change[] | 'gone' }[];
+}
+
+/** Every door of a card, by name. */
+function doorsOf(card: IdentityCard, frond: string): Map<string, { ops: Set<string>; schema?: SchemaDescriptor }> {
+  const found = new Map<string, { ops: Set<string>; schema?: SchemaDescriptor }>();
+  for (const one of card.fronds) {
+    if (one.name !== frond) continue;
+    for (const door of one.doors) {
+      found.set(door.name, { ops: new Set(door.ops.map((op) => op.name)), schema: door.schema });
+    }
+  }
+  return found;
+}
+
+function factsOf(card: IdentityCard, frond: string): Map<string, SchemaDescriptor | undefined> {
+  const found = new Map<string, SchemaDescriptor | undefined>();
+  for (const one of card.fronds) {
+    if (one.name !== frond) continue;
+    for (const fact of one.facts ?? []) found.set(fact.name, fact.schema as SchemaDescriptor | undefined);
+  }
+  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).
+ */
+export function driftOf(mine: IdentityCard, theirs: IdentityCard, frond: string): CardDrift {
+  const held = doorsOf(mine, frond);
+  const served = doorsOf(theirs, frond);
+  const drift: CardDrift = { frond, missingDoors: [], missingOps: [], shapes: [], facts: [] };
+
+  for (const [name, door] of held) {
+    const there = served.get(name);
+    if (!there) { drift.missingDoors.push(name); continue; }
+
+    const missing = [...door.ops].filter((op) => !there.ops.has(op));
+    if (missing.length > 0) drift.missingOps.push({ door: name, ops: missing.sort() });
+
+    if (door.schema && there.schema) {
+      // `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(door.schema).diff(Card.fromDescriptor(there.schema));
+      if (moved.changes.length > 0) drift.shapes.push({ door: name, changes: moved.changes });
+    }
+  }
+
+  const heldFacts = factsOf(mine, frond);
+  const servedFacts = factsOf(theirs, frond);
+  for (const [name, shape] of heldFacts) {
+    if (!servedFacts.has(name)) { drift.facts.push({ fact: name, changes: 'gone' }); continue; }
+    const there = servedFacts.get(name);
+    if (!shape || !there) continue;
+    const moved = Card.fromDescriptor(shape).diff(Card.fromDescriptor(there));
+    if (moved.changes.length > 0) drift.facts.push({ fact: name, changes: moved.changes });
+  }
+
+  return drift;
+}
+
+/** Whether anything at all separates the two cards. */
+export function agrees(drift: CardDrift): boolean {
+  return drift.missingDoors.length === 0
+    && drift.missingOps.length === 0
+    && drift.shapes.length === 0
+    && 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.
+ */
+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`);
+  for (const { door, ops } of drift.missingOps) lines.push(`${drift.frond}.${door} — gone: ${ops.join(', ')}`);
+  for (const { door, changes } of drift.shapes) {
+    for (const change of changes) lines.push(`${drift.frond}.${door} — ${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; }
+    for (const change of changes) lines.push(`${fact} — ${describe(change)} → re-sync and deploy the readers, THEN the sender`);
+  }
+  return lines;
+}
+
+function describe(change: Change): string {
+  switch (change.kind) {
+    case 'added': return `+ ${change.field}${change.required ? ' (required)' : ''}`;
+    case 'removed': return `- ${change.field}`;
+    case 'renamed': return `${change.from} → ${change.to}`;
+    case 'retyped': return `${change.field}: ${[...change.from].join('|')} → ${[...change.to].join('|')}`;
+    case 'reshaped': return `${change.field}: its bounds moved`;
+    case 'required': return `${change.field}: ${change.from ? 'no longer' : 'now'} required`;
+    case 'restated': return `${change.field}: its ${change.axis} moved`;
+  }
+}

package/src/wire/errors.ts

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+
+import type { ValidationError } from '@fougere/schema';
+
+// ── ErrorCode ──────────────────────────────────
+
+/** Semantic error codes — transport-agnostic. Each bridge maps them to its own format. */
+export enum ErrorCode {
+  // Input
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+  BAD_REQUEST = 'BAD_REQUEST',
+
+  // Auth
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+
+  // Resources
+  NOT_FOUND = 'NOT_FOUND',
+  GONE = 'GONE',
+  CONFLICT = 'CONFLICT',
+  LOCKED = 'LOCKED',
+  METHOD_NOT_ALLOWED = 'METHOD_NOT_ALLOWED',
+
+  // Limits
+  PRECONDITION_FAILED = 'PRECONDITION_FAILED',
+  PAYLOAD_TOO_LARGE = 'PAYLOAD_TOO_LARGE',
+  UNPROCESSABLE_ENTITY = 'UNPROCESSABLE_ENTITY',
+  TOO_MANY_REQUESTS = 'TOO_MANY_REQUESTS',
+  REQUEST_TIMEOUT = 'REQUEST_TIMEOUT',
+
+  // Server
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
+  BAD_GATEWAY = 'BAD_GATEWAY',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+  GATEWAY_TIMEOUT = 'GATEWAY_TIMEOUT',
+}
+
+// ── FougereError ────────────────────────────────
+
+export interface FougereErrorOptions {
+  code: ErrorCode;
+  message: string;
+  entity?: string;
+  operation?: string;
+  details?: unknown;
+  cause?: unknown;
+}
+
+export class FougereError extends Error {
+  readonly code: ErrorCode;
+  readonly entity?: string;
+  readonly operation?: string;
+  readonly details?: unknown;
+
+  constructor(options: FougereErrorOptions) {
+    super(options.message, { cause: options.cause });
+    this.name = 'FougereError';
+    this.code = options.code;
+    this.entity = options.entity;
+    this.operation = options.operation;
+    this.details = options.details;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.entity && { entity: this.entity }),
+      ...(this.operation && { operation: this.operation }),
+      ...(this.details !== undefined && { details: this.details }),
+    };
+  }
+
+  /**
+   * 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.
+   */
+  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);
+    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,
+      operation: typeof raw.operation === 'string' ? raw.operation : undefined,
+      details: known ? raw.details : { originalCode: raw.code, details: raw.details },
+    });
+  }
+}
+
+/**
+ * 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.
+ */
+export function validationErrorsOf(error: unknown): ValidationError[] | undefined {
+  if (!(error instanceof FougereError) || error.code !== ErrorCode.VALIDATION_FAILED) return undefined;
+  const { details } = error;
+  if (!Array.isArray(details)) return undefined;
+  const refusals = details.filter(
+    (entry): entry is ValidationError =>
+      typeof entry === 'object' && entry !== null
+      && typeof (entry as ValidationError).path === 'string'
+      && typeof (entry as ValidationError).message === 'string',
+  );
+  return refusals.length === details.length ? refusals : undefined;
+}