@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/verify.ts

@@ -0,0 +1,193 @@
+import type { FrondDescriptor } from './scan/frond.js';
+import { lowerFirst } from '@fougere/schema';
+import { repositoryKeyOf } from './prefab/repository.js';
+import { ormKeyOf } from './orm.js';
+import { presenterKeyOf } from './prefab/presenter.js';
+import { collectorKeyOf } from './prefab/collector.js';
+
+/**
+ * What a rule found in an app.
+ *
+ * `message` is the sentence the rule replaces — the prose a human used to have
+ * to remember. `Known issues` says "Keep collectors in the consuming frond";
+ * this is that sentence, told about a specific handler, by something that runs.
+ */
+export interface Violation {
+  /** Rule name, stable — 'cross-frond-dependency'. */
+  rule: string;
+  /**
+   * What it costs, decided by the rule that raises it — never by whoever renders it.
+   *
+   * The two rules here are not the same animal: a cross-frond dependency resolves
+   * today and stops resolving the day the other frond answers over the wire, while a
+   * collector declared elsewhere is already wrong in one process. A reader holding a
+   * table of rule names would be a second opinion on a fact the rule already has.
+   */
+  severity: 'blocking' | 'warning';
+  /** The frond the subject lives in. */
+  frond: string;
+  /** What violates it — 'PostHandler'. */
+  subject: string;
+  /** Where to go and look. */
+  filePath: string;
+  /**
+   * What the subject reaches for, and where it actually lives.
+   *
+   * `frond` above is the CONSUMER; the target used to exist only inside the
+   * sentence. A reader that has to parse prose to learn which frond a violation
+   * points at is a second opinion on a fact the checker already held — so the
+   * boot can ask "does this violation target a frond named in `remotes:`?" by
+   * reading a field.
+   */
+  dependsOn: { key: string; frond: string; kind: string };
+  /** What breaks, and what the caller gets instead. */
+  message: string;
+}
+
+/** A dependency declared in a frond's scope, and what kind of thing it is. */
+type Registration = { frond: string; kind: string };
+
+/**
+ * The container keys a frond registers in its own scope, keyed as a handler's
+ * `deps` spell them — DI resolves by type name, so both sides are PascalCase.
+ *
+ * Every key comes from the function that states it, never from a derivation
+ * respelled here: a second reader that spells one differently finds nothing and
+ * reports nothing wrong, which is the failure mode a checker must not have.
+ */
+function registrationsOf(frond: FrondDescriptor): Map<string, Registration> {
+  const out = new Map<string, Registration>();
+  const put = (key: string, kind: string) => out.set(key, { frond: frond.name, kind });
+
+  for (const p of frond.providers) put(p.ctor.name, 'provider');
+  for (const p of frond.presenters) put(presenterKeyOf(p.entityName), 'presenter');
+  for (const c of frond.collectors) put(collectorKeyOf(c.typeName), 'collector');
+  for (const e of frond.entities) {
+    put(ormKeyOf(e.name), 'ORM');
+    put(repositoryKeyOf(e.name), 'repository');
+  }
+  return out;
+}
+
+/**
+ * Everything in a frond that is constructed by DI, so carries `deps`.
+ * Handlers, presenters and collectors are all built from a constructor whose
+ * argument types the scan read; each one can therefore reach across.
+ */
+function injectablesOf(frond: FrondDescriptor) {
+  return [
+    ...frond.handlers.map((h) => ({ name: h.ctor.name, deps: h.deps, filePath: h.filePath })),
+    ...frond.presenters.map((p) => ({ name: p.ctor.name, deps: p.deps, filePath: p.filePath })),
+    ...frond.collectors.map((c) => ({ name: c.ctor.name, deps: c.deps, filePath: c.filePath })),
+  ];
+}
+
+/**
+ * Does this app survive being split?
+ *
+ * A frond runs in-process or in its own process behind JSON-RPC with identical
+ * user code — that is the whole claim. What the claim does not say is that
+ * *every* app survives the move: a dependency that crosses a frond boundary
+ * resolves today because both scopes live in one container, and resolves to
+ * nothing the day the other frond answers over the wire.
+ *
+ * The question only exists where a module boundary is meant to become a process
+ * boundary later. Where every inter-module call is already remote there is
+ * nothing to check, and where no exit is planned there is nothing to check
+ * either. Here it means something, and until now it had no answer.
+ *
+ * Pure over `app.fronds`: no mount, no process, no file. Call it from a test.
+ */
+export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[] {
+  const index = new Map<string, Registration>();
+  for (const frond of app.fronds) {
+    for (const [key, reg] of registrationsOf(frond)) index.set(key, reg);
+  }
+
+  // Which frond declares a collector for which entity. Collectors are the one
+  // thing a handler asks for by OPERATION PARAMETER, never by constructor, so
+  // they need their own index and their own rule.
+  const collectorFronds = new Map<string, string>();
+  for (const frond of app.fronds) {
+    for (const c of frond.collectors) collectorFronds.set(c.typeName, frond.name);
+  }
+
+  const violations: Violation[] = [];
+  for (const frond of app.fronds) {
+    // Rule 1 — a constructor dependency declared in another frond's scope.
+    // Façade keys are exempt by construction, not by omission: a `Facade<X>`
+    // dependency is spelled camelCase (`articleHandler`) while every type key
+    // here is PascalCase, so the two namespaces cannot collide. The façade IS
+    // the sanctioned crossing — see tests/cross-frond.test.ts.
+    for (const subject of injectablesOf(frond)) {
+      for (const dep of subject.deps) {
+        const declared = index.get(dep);
+        // Not in the index at all = a builtin (Logger, Config), a
+        // façade key, or an unresolved name. None is a boundary crossing, and
+        // an unresolved dependency is the container's complaint, not this rule's.
+        if (!declared || declared.frond === frond.name) continue;
+        violations.push({
+          rule: 'cross-frond-dependency',
+          severity: 'warning',
+          frond: frond.name,
+          subject: subject.name,
+          filePath: subject.filePath,
+          dependsOn: { key: dep, frond: declared.frond, kind: declared.kind },
+          message:
+            `${subject.name} depends on ${dep}, the ${declared.kind} of frond '${declared.frond}'. ` +
+            `Each frond registers into its own scope, so this does not resolve here. ` +
+            `Declare ${dep} in '${frond.name}', or reach '${declared.frond}' through its ` +
+            `façade — the one sanctioned crossing.`,
+        });
+      }
+    }
+
+    // Rule 2 — an operation parameter that wanted a collector this frond has not
+    // got. The preliminary binding convention can only see this frond's collector
+    // set, so it produces body evidence. EffectiveOperation refuses that evidence
+    // before boot: another frond's collector proves the provenance is not a body.
+    const own = new Set(frond.collectors.map((c) => c.typeName));
+    for (const handler of frond.handlers) {
+      for (const [opName, op] of handler.operations) {
+        for (const param of op.signature?.params ?? []) {
+          // Same key the scan writes and the binding plan looks up — `toLowerCase()`
+          // here missed a two-word type in BOTH directions: neither confirmed the
+          // collector was local nor found it elsewhere, so the rule reported nothing.
+          const wanted = lowerFirst(param.type.name);
+          if (own.has(wanted)) continue;
+          const elsewhere = collectorFronds.get(wanted);
+          // No collector anywhere for that type may be an ordinary body parameter.
+          // Only a collector that exists in the wrong place makes that interpretation
+          // provably false.
+          if (!elsewhere) continue;
+          violations.push({
+            rule: 'collector-in-another-frond',
+            severity: 'blocking',
+            frond: frond.name,
+            subject: `${handler.ctor.name}.${opName}(${param.name})`,
+            filePath: handler.filePath,
+            dependsOn: { key: collectorKeyOf(wanted), frond: elsewhere, kind: 'collector' },
+            message:
+              `'${param.name}' is typed ${param.type.name}, and the collector that produces one ` +
+              `is declared in frond '${elsewhere}'. A binding plan only sees its own frond's ` +
+              `collectors, so the preliminary body interpretation is invalid. Fougere refuses ` +
+              `the operation before it can receive what the caller sent. ` +
+              `Move the collector into '${frond.name}'.`,
+          });
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * The same verdict, as an assertion. Throws naming every rule that failed, so a
+ * test is one line and its output is the sentence — not a diff of two objects.
+ */
+export function assertSplittable(app: { fronds: readonly FrondDescriptor[] }): void {
+  const violations = verify(app);
+  if (violations.length === 0) return;
+  const lines = violations.map((v) => `  [${v.rule}] ${v.frond}/${v.subject}\n    ${v.message}\n    ${v.filePath}`);
+  throw new Error(`${violations.length} violation(s) — this app does not survive a split:\n${lines.join('\n')}`);
+}

package/src/wire/call.ts

@@ -0,0 +1,369 @@
+/**
+ * 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 './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. */
+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/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;
+}