@ogygie/core 0.10.2 → 0.11.0

package/README.md

@@ -17,7 +17,8 @@ dans `apps/`.
 | `@ogygie/core/vocabulary` | Appariement des racines de vocabulaire sur les identifiants machine — les racines appartiennent au produit |
 | `@ogygie/core/vocabulary-audit` | Jugement du gate de vocabulaire : alias interdits du code, pureté des fichiers gouvernés |
 | `@ogygie/core/gateway` | Passerelle publique dérivée du manifeste (ci-dessous) |
-| `@ogygie/core/client` | Client d'API front dérivé du manifeste (clés de cache, invalidations) |
+| `@ogygie/core/client` | Client d'API front dérivé du manifeste : transport (`fetchImpl` injecté), clés de cache et invalidations (D13) |
+| `@ogygie/core/client-react` | Les hooks du même client — `react` et `@tanstack/react-query` en peers OPTIONNELS, chargés dynamiquement (D13) |
 
 ## Le test du vocabulaire couvre TOUT le core
 
@@ -142,3 +143,68 @@ et les `Set-Cookie` de l'amont, eux, traversent **octet pour octet** — une
 | `GATEWAY_ROUTE_UNKNOWN` | 404 | Aucune route déclarée ne correspond (et aucun fallback SPA applicable). |
 | `GATEWAY_UPSTREAM_UNAVAILABLE` | 502 | L'amont est injoignable. Aucun détail interne ne fuit : ni URL privée, ni stack. |
 | `GATEWAY_UPSTREAM_TIMEOUT` | 504 | L'amont n'a pas répondu dans `timeoutMs`. |
+
+## Client d'API dérivé du manifeste — `@ogygie/core/client` et `/client-react`
+
+`createManifestClient(manifest, schemas, options)` est le **pendant front** de
+la passerelle (spec `manifest-client`, D13) : chaque route déclarée devient une
+méthode, sous le namespace de sa racine de chemin. Une route absente du
+manifeste n'existe pas côté client. Les **clés de cache** et les
+**invalidations** sont DÉRIVÉES — un produit n'écrit plus une seule clé à la
+main, ni un seul `fetch`.
+
+### Usage minimal
+
+```ts
+import { createManifestClient } from "@ogygie/core/client";
+import { createApiHooks } from "@ogygie/core/client-react";
+import * as widgetSchemas from "@my-product/api/features/widgets/schemas";
+
+const api = createManifestClient(manifest, { ...widgetSchemas }, {
+  fetchImpl: globalThis.fetch,                       // effet injecté, jamais importé au fond d'un helper
+  validateResponses: import.meta.env.DEV ? "always" : "never",
+});
+
+api.widgets.list();                                  // GET  /api/widgets
+api.widgets.get({ widgetId });                       // GET  /api/widgets/:widgetId
+api.widgets.list.queryKey();                         // ["widgets", "list"]
+api.widgets.create.invalidationRoots;                // ["widgets", ...invalidates du manifeste]
+
+// Les hooks : peers OPTIONNELS, chargés dynamiquement (refus structuré si absents).
+const { useApiQuery, useApiMutation } = await createApiHooks(queryClient);
+useApiQuery(api.widgets.list);
+useApiMutation(api.widgets.create);                  // invalide ["widgets"] + les racines déclarées
+```
+
+### Dérivations
+
+| Élément | Règle |
+|---|---|
+| Namespace | Premier segment après `/api`, camelCasé (`/api/work-orders/...` → `client.workOrders`). |
+| Opération | Segments statiques suivants (`.../:id/archive` → `archive`) ; sinon le VERBE du nom du schéma d'entrée (`SearchReportsInputSchema` → `search`) ; sinon la méthode (`GET` → `list`/`get`, `POST` → `create`, `PATCH`/`PUT` → `update`, `DELETE` → `delete`). |
+| Clé de cache | `[racine, opération, ...valeurs des params, reste de l'entrée]`. L'opération EN FAIT PARTIE : deux GET voisins sur la même entité partageraient sinon une entrée de cache, et le second ne partirait jamais. |
+| Invalidation | Racine propre + les racines déclarées dans `invalidates` de la route (vérifiées par `verify-manifest` : une cible fantôme casse le build). |
+
+### Options
+
+| Option | Requis | Effet |
+|---|---|---|
+| `fetchImpl` | oui | L'effet réseau, injecté (`globalThis.fetch`, ou un faux en test). Le module n'appelle jamais le réseau autrement. |
+| `validateResponses` | oui | `"always"` reparse chaque réponse avec son `schemaOutput` (dev : un contrat cassé échoue ICI) ; `"never"` = passthrough. Le PRODUIT choisit par environnement — le core ne lit aucune variable d'env. |
+| `baseUrl` | non | Préfixe du chemin dérivé ; vide par défaut, le front appelle son api en relatif. |
+
+### Erreurs
+
+| Code | Quand |
+|---|---|
+| `MANIFEST_CLIENT_INVALID_MANIFEST` | **À la construction** : manifeste illisible, chemin malformé, route déclarée deux fois. |
+| `MANIFEST_CLIENT_UNKNOWN_SCHEMA` | **À la construction** : un `schemaInput`/`schemaOutput` du manifeste manque au registre. |
+| `MANIFEST_CLIENT_AMBIGUOUS_OPERATION` | **À la construction** : deux routes dérivent le même nom d'opération — jamais un écrasement silencieux. |
+| `MANIFEST_CLIENT_MISSING_PATH_PARAM` | Appel sans le param de chemin que la route exige, avant tout appel réseau. |
+| `NETWORK_ERROR` | `fetchImpl` a rejeté, ou l'api a échoué SANS corps `OgygieError` (statut conservé). |
+| `CONTRACT_BROKEN` | Réponse non-JSON, ou violant `schemaOutput` en `validateResponses: "always"`. |
+| `CLIENT_REACT_PEER_MISSING` | `client-react` sans `@tanstack/react-query` installé : refus nommant la commande, jamais une erreur de résolution de module. |
+
+Un corps `OgygieError` renvoyé par l'api, lui, **ressort intact** (code,
+`details`, `suggestedFix`, statut) : c'est la seule chose sur laquelle un écran
+puisse agir.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/core",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Ogygie framework core: manifest/spec/error schemas, generic tenancy and gate tooling. Ships TypeScript sources — Ogygie products run tsx/vitest by construction (D1).",
   "license": "MIT",
   "type": "module",
@@ -33,15 +33,18 @@
     "./shared-tables": "./src/shared-tables.ts",
     "./test-kit": "./src/test-kit.ts",
     "./gateway": "./src/manifest-gateway.ts",
-    "./client": "./src/manifest-client.ts"
+    "./client": "./src/manifest-client.ts",
+    "./client-react": "./src/manifest-client-react.ts"
   },
   "peerDependencies": {
     "@electric-sql/pglite": "^0.3.0",
     "@fastify/helmet": "^13.0.0",
     "@fastify/rate-limit": "^10.0.0",
     "@fastify/static": "^10.1.2",
+    "@tanstack/react-query": "^5.0.0",
     "drizzle-orm": "^0.45.2",
     "fastify": "^5.0.0",
+    "react": "^19.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -57,11 +60,17 @@
     "@fastify/static": {
       "optional": true
     },
+    "@tanstack/react-query": {
+      "optional": true
+    },
     "drizzle-orm": {
       "optional": true
     },
     "fastify": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/manifest-client-react.test.ts

@@ -0,0 +1,187 @@
+/**
+ * @intent Proves the behaviors of specs/manifest-client.spec.md §2: the hooks
+ * carry the DERIVED cache key and the invalidations a successful mutation
+ * implies — a screen writes neither — and the optional peer is refused
+ * STRUCTURALLY when it is missing (this repo deliberately does not install it,
+ * so that last test is the real thing, not a simulation).
+ */
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { OgygieFailure } from "./error.schema.js";
+import {
+  createManifestClient,
+  type ApiOperation,
+  type ManifestClient,
+} from "./manifest-client.js";
+import {
+  createApiHooks,
+  loadReactQuery,
+  staleQueryKeysOf,
+  type ApiMutationOptions,
+  type ApiQueryOptions,
+  type ReactQueryLike,
+} from "./manifest-client-react.js";
+
+/** Reads a derived operation, or fails the test — never a cast. */
+function operationOf(client: ManifestClient, namespace: string, operation: string): ApiOperation {
+  const found = client[namespace]?.[operation];
+  if (found === undefined) throw new Error(`fixture client has no ${namespace}.${operation}`);
+  return found;
+}
+
+function fixtureClient() {
+  const schemas: Record<string, z.ZodType> = {
+    ListWidgetsInputSchema: z.record(z.string(), z.unknown()),
+    ListWidgetsOutputSchema: z.record(z.string(), z.unknown()),
+    CreateWidgetInputSchema: z.record(z.string(), z.unknown()),
+    CreateWidgetOutputSchema: z.record(z.string(), z.unknown()),
+  };
+  const manifest = {
+    features: [
+      {
+        name: "widgets",
+        routes: [
+          {
+            method: "GET",
+            path: "/api/widgets",
+            schemaInput: "ListWidgetsInputSchema",
+            schemaOutput: "ListWidgetsOutputSchema",
+          },
+          {
+            method: "POST",
+            path: "/api/widgets",
+            schemaInput: "CreateWidgetInputSchema",
+            schemaOutput: "CreateWidgetOutputSchema",
+            invalidates: ["work-orders"],
+          },
+        ],
+      },
+    ],
+  };
+  const calls: string[] = [];
+  const client = createManifestClient(manifest, schemas, {
+    fetchImpl: async (url) => {
+      calls.push(url);
+      return { ok: true, status: 200, text: async () => JSON.stringify({ ok: true }) };
+    },
+    validateResponses: "never",
+  });
+  return { client, calls };
+}
+
+/** The peer, faked: it only has to record what the hooks hand it. */
+function fakeReactQuery(): {
+  module: ReactQueryLike;
+  queries: ApiQueryOptions[];
+  mutations: ApiMutationOptions[];
+} {
+  const queries: ApiQueryOptions[] = [];
+  const mutations: ApiMutationOptions[] = [];
+  return {
+    queries,
+    mutations,
+    module: {
+      useQuery: (options: ApiQueryOptions) => {
+        queries.push(options);
+        return { data: undefined, isPending: true, isError: false, error: null };
+      },
+      useMutation: (options: ApiMutationOptions) => {
+        mutations.push(options);
+        return { mutate: () => undefined, isPending: false };
+      },
+    },
+  };
+}
+
+function recordingQueryClient(): {
+  queryClient: { invalidateQueries: (filters: { queryKey: ReadonlyArray<unknown> }) => unknown };
+  invalidated: ReadonlyArray<unknown>[];
+} {
+  const invalidated: ReadonlyArray<unknown>[] = [];
+  return {
+    invalidated,
+    queryClient: {
+      invalidateQueries: (filters) => {
+        invalidated.push(filters.queryKey);
+        return undefined;
+      },
+    },
+  };
+}
+
+describe("manifest-client-react — hooks dérivés (spec manifest-client §2)", () => {
+  it("useApiQuery lit par la clé DÉRIVÉE et appelle l'opération, sans une ligne au site d'appel", async () => {
+    const { client, calls } = fixtureClient();
+    const peer = fakeReactQuery();
+    const { queryClient } = recordingQueryClient();
+    const hooks = await createApiHooks(queryClient, peer.module);
+
+    hooks.useApiQuery(operationOf(client, "widgets", "list"), { q: "ab" });
+
+    expect(peer.queries[0]?.queryKey).toEqual(["widgets", "list", { q: "ab" }]);
+    await peer.queries[0]?.queryFn();
+    expect(calls).toEqual(["/api/widgets?q=ab"]);
+  });
+
+  it("ÉTANT DONNÉ une mutation réussie ALORS sa racine est invalidée sans une ligne dans le code appelant", async () => {
+    const { client } = fixtureClient();
+    const peer = fakeReactQuery();
+    const { queryClient, invalidated } = recordingQueryClient();
+    const hooks = await createApiHooks(queryClient, peer.module);
+
+    hooks.useApiMutation(operationOf(client, "widgets", "create"));
+    await peer.mutations[0]?.onSuccess();
+
+    // Own root FIRST, then the cross-invalidation the manifest declares.
+    expect(invalidated).toEqual([["widgets"], ["work-orders"]]);
+  });
+
+  it("ÉTANT DONNÉ une route déclarant invalidates ALORS la dépendance croisée est LUE, jamais devinée", () => {
+    const { client } = fixtureClient();
+    expect(staleQueryKeysOf(operationOf(client, "widgets", "create"))).toEqual([
+      ["widgets"],
+      ["work-orders"],
+    ]);
+    expect(staleQueryKeysOf(operationOf(client, "widgets", "list"))).toEqual([["widgets"]]);
+  });
+
+  it("ÉTANT DONNÉ client-react chargé sans @tanstack/react-query ALORS refus structuré nommant la commande", async () => {
+    // The absence is SIMULATED at the importer, not at the disk: the framework
+    // repo installs the peer the day it declares it (pnpm resolves declared
+    // peers), and a behavior may not stop being proven because the machine
+    // happens to satisfy it.
+    let thrown: unknown;
+    try {
+      await loadReactQuery(() =>
+        Promise.reject(new Error("Cannot find package '@tanstack/react-query'")),
+      );
+    } catch (failure) {
+      thrown = failure;
+    }
+    expect(thrown).toBeInstanceOf(OgygieFailure);
+    const failure = thrown as OgygieFailure;
+    expect(failure.error.code).toBe("CLIENT_REACT_PEER_MISSING");
+    expect(failure.error.suggestedFix).toContain("pnpm add react @tanstack/react-query");
+  });
+
+  it("ÉTANT DONNÉ le peer installé ALORS l'import dynamique rend de vrais hooks", async () => {
+    const { queryClient } = recordingQueryClient();
+    const hooks = await createApiHooks(queryClient);
+    expect(typeof hooks.useApiQuery).toBe("function");
+    expect(typeof hooks.useApiMutation).toBe("function");
+  });
+
+  it("MUTATION : un module de peer sans hooks est refusé comme un peer absent", async () => {
+    const { queryClient } = recordingQueryClient();
+    let thrown: unknown;
+    try {
+      // The injected module is the peer's shape, so an empty one must be
+      // refused HERE — otherwise the failure would surface as "undefined is
+      // not a function" inside a render.
+      await createApiHooks(queryClient, { useQuery: undefined, useMutation: undefined });
+    } catch (failure) {
+      thrown = failure;
+    }
+    expect((thrown as OgygieFailure | undefined)?.error.code).toBe("CLIENT_REACT_PEER_MISSING");
+  });
+});

package/src/manifest-client-react.ts

@@ -0,0 +1,196 @@
+/**
+ * @intent React hooks over the manifest-derived client (D13, entry point
+ * `@ogygie/core/client-react`) — SEPARATE from `@ogygie/core/client` so the
+ * pure module stays consumable without React: a script, a test, another
+ * framework. A front feature no longer writes a `queries.ts`: the hook
+ * carries the derived cache key, the call, and the invalidations a successful
+ * mutation implies (own root + the roots the manifest declares).
+ *
+ * `react` and `@tanstack/react-query` are OPTIONAL peers of `@ogygie/core`
+ * (D1): the product that uses this module already owns them. They are loaded
+ * by DYNAMIC import, the doctrine already held for the studio and the MCP
+ * server (D7/D9) — which is exactly what makes the refusal STRUCTURED
+ * (CLIENT_REACT_PEER_MISSING, naming the install command) instead of a module
+ * resolution error nobody can act on. Hence an ASYNC factory. The peer may
+ * also be INJECTED (principle 5: a declared effect is passed in), which is
+ * what the tests do and what a product that prefers the explicit can do.
+ *
+ * This module imports NO react type: it declares the SHAPES it needs and
+ * nothing else — the framework repo does not install the peers, so a static
+ * import would make its own typecheck depend on a package it refuses to own.
+ */
+import type { ApiOperation } from "./manifest-client.js";
+import { throwOgygieError } from "./error.schema.js";
+
+/** The install command a refusal names — one place, so it cannot drift. */
+const PEER_INSTALL_COMMAND = "pnpm add react @tanstack/react-query";
+
+/** What this module needs from a QueryClient: making derived keys stale. */
+export interface QueryClientLike {
+  invalidateQueries: (filters: { queryKey: ReadonlyArray<unknown> }) => unknown;
+}
+
+export interface ApiQueryOptions {
+  queryKey: ReadonlyArray<unknown>;
+  queryFn: () => Promise<unknown>;
+  enabled?: boolean;
+}
+
+export interface ApiMutationOptions {
+  mutationKey: ReadonlyArray<unknown>;
+  mutationFn: (input?: Record<string, unknown>) => Promise<unknown>;
+  onSuccess: () => Promise<void>;
+}
+
+/** The two hooks of the peer this module builds upon — nothing else is used. */
+export interface ReactQueryLike {
+  useQuery: (options: ApiQueryOptions) => unknown;
+  useMutation: (options: ApiMutationOptions) => unknown;
+}
+
+/**
+ * The SUBSET of a react-query result a screen composes with. The peer returns
+ * more; declaring what we consume keeps this module free of its types (and
+ * honest about what it promises).
+ */
+export interface ApiQueryResult<TData> {
+  data: TData | undefined;
+  isPending: boolean;
+  isError: boolean;
+  error: unknown;
+}
+
+export interface ApiMutationResult<TData> {
+  mutate: (input?: Record<string, unknown>) => void;
+  mutateAsync: (input?: Record<string, unknown>) => Promise<TData>;
+  data: TData | undefined;
+  isPending: boolean;
+  isError: boolean;
+  error: unknown;
+}
+
+export interface ApiHooks {
+  /** Reads through the derived cache key — nothing to name, nothing to invent. */
+  useApiQuery: <TData = unknown>(
+    operation: ApiOperation,
+    input?: Record<string, unknown>,
+    options?: { enabled?: boolean },
+  ) => ApiQueryResult<TData>;
+  /** Writes, then makes stale what the manifest says this route makes stale. */
+  useApiMutation: <TData = unknown>(operation: ApiOperation) => ApiMutationResult<TData>;
+}
+
+/**
+ * The cache keys a successful mutation makes stale: its own root, plus every
+ * root the route declares in `invalidates`. DERIVED, never written in a
+ * screen — a forgotten invalidation never fails, it serves stale data.
+ */
+export function staleQueryKeysOf(operation: ApiOperation): ReadonlyArray<ReadonlyArray<string>> {
+  return operation.invalidationRoots.map((root) => [root]);
+}
+
+/** Applies that plan. Exposed so a consumer outside React keeps the behavior. */
+export async function invalidateAfterMutation(
+  queryClient: QueryClientLike,
+  operation: ApiOperation,
+): Promise<void> {
+  for (const queryKey of staleQueryKeysOf(operation)) {
+    await queryClient.invalidateQueries({ queryKey });
+  }
+}
+
+function looksLikeReactQuery(value: unknown): value is ReactQueryLike {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<ReactQueryLike>;
+  return typeof candidate.useQuery === "function" && typeof candidate.useMutation === "function";
+}
+
+/**
+ * The peer arrives from OUTSIDE the type system — a dynamic import, or the
+ * module a product hands over. It is therefore validated, never trusted: a
+ * module without the two hooks is refused HERE, where the refusal can name
+ * the fix, instead of surfacing as "undefined is not a function" in a render.
+ */
+function asReactQuery(loaded: unknown, origin: string): ReactQueryLike {
+  if (!looksLikeReactQuery(loaded)) {
+    throwOgygieError(
+      {
+        code: "CLIENT_REACT_PEER_MISSING",
+        message: "@ogygie/core/client-react received no usable @tanstack/react-query module.",
+        file: null,
+        cause: `${origin}: the module carries neither useQuery nor useMutation as functions`,
+        suggestedFix: `Check the installed peer (${PEER_INSTALL_COMMAND}) — this module only uses useQuery and useMutation.`,
+      },
+      500,
+    );
+  }
+  return loaded;
+}
+
+/**
+ * Loads the optional peer, or REFUSES with the command to run. The default
+ * importer keeps the specifier LITERAL so a bundler can see it (a computed one
+ * would break the browser build); it is a parameter because the load is an
+ * effect like any other (principle 5) — that is how the refusal is proven in a
+ * repo where the peer happens to be installed.
+ */
+export async function loadReactQuery(
+  importPeer: () => Promise<unknown> = () => import("@tanstack/react-query"),
+): Promise<ReactQueryLike> {
+  let loaded: unknown;
+  try {
+    loaded = await importPeer();
+  } catch (thrown) {
+    throwOgygieError(
+      {
+        code: "CLIENT_REACT_PEER_MISSING",
+        message: "@ogygie/core/client-react needs its optional peer @tanstack/react-query.",
+        file: null,
+        cause: `dynamic import of "@tanstack/react-query" failed: ${String(thrown)}`,
+        suggestedFix: `Install the peers in the project that uses these hooks: ${PEER_INSTALL_COMMAND} — or pass the module to createApiHooks yourself.`,
+      },
+      500,
+    );
+  }
+  return asReactQuery(loaded, "dynamic import of @tanstack/react-query");
+}
+
+/**
+ * THE way a product gets its hooks. `reactQuery` is optional: absent, the
+ * optional peer is loaded dynamically (and its absence refused structurally).
+ */
+export async function createApiHooks(
+  queryClient: QueryClientLike,
+  reactQuery?: unknown,
+): Promise<ApiHooks> {
+  const hooks =
+    reactQuery === undefined
+      ? await loadReactQuery()
+      : asReactQuery(reactQuery, "module injected into createApiHooks");
+
+  return {
+    useApiQuery: <TData = unknown>(
+      operation: ApiOperation,
+      input?: Record<string, unknown>,
+      options?: { enabled?: boolean },
+    ): ApiQueryResult<TData> => {
+      const queryOptions: ApiQueryOptions = {
+        queryKey: operation.queryKey(input),
+        queryFn: () => operation(input),
+        ...(options?.enabled === undefined ? {} : { enabled: options.enabled }),
+      };
+      // The peer returns its own richer result; we promise only the subset we
+      // declared, and the response was already validated by the client.
+      return hooks.useQuery(queryOptions) as ApiQueryResult<TData>;
+    },
+
+    useApiMutation: <TData = unknown>(operation: ApiOperation): ApiMutationResult<TData> => {
+      const mutationOptions: ApiMutationOptions = {
+        mutationKey: [operation.namespace, operation.operation],
+        mutationFn: (input?: Record<string, unknown>) => operation(input),
+        onSuccess: () => invalidateAfterMutation(queryClient, operation),
+      };
+      return hooks.useMutation(mutationOptions) as ApiMutationResult<TData>;
+    },
+  };
+}

package/src/manifest-client.test.ts

@@ -1,19 +1,29 @@
 /**
- * @intent Proves the manifest-client derivation (spec front-derivation §1):
- * the client exposes exactly the declared routes (mutation test: a removed
- * route disappears), derives namespaces, operations, cache keys and
- * invalidation roots, and refuses loudly what it cannot derive. Fixtures are
- * deliberately vocabulary-neutral — the vocabulary test next door scans this
- * file too.
+ * @intent Proves the behaviors of specs/manifest-client.spec.md §1: the client
+ * exposes exactly the declared routes (mutation test: a removed route
+ * disappears), derives namespaces, operations, cache keys and invalidation
+ * roots, refuses loudly what it cannot derive, and speaks ONE error language
+ * on the wire (OgygieError untouched, everything else NETWORK_ERROR or
+ * CONTRACT_BROKEN). Fixtures are deliberately vocabulary-neutral — the
+ * vocabulary gate scans this file too.
  */
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
-import { OgygieFailure } from "./error.schema.js";
+import { OgygieFailure, ogygieError } from "./error.schema.js";
 import {
   createManifestClient,
-  type ManifestClientRequest,
+  type ApiOperation,
+  type HttpResponseLike,
+  type ManifestClient,
 } from "./manifest-client.js";
 
+/** Reads a derived operation, or fails the test — never a cast. */
+function operationOf(client: ManifestClient, namespace: string, operation: string): ApiOperation {
+  const found = client[namespace]?.[operation];
+  if (found === undefined) throw new Error(`fixture client has no ${namespace}.${operation}`);
+  return found;
+}
+
 const SCHEMA_NAMES = [
   "ListWidgetsInputSchema",
   "ListWidgetsOutputSchema",
@@ -22,7 +32,6 @@ const SCHEMA_NAMES = [
   "UpdateWidgetInputSchema",
   "UpdateWidgetOutputSchema",
   "WidgetParamsSchema",
-  "GetWidgetOutputSchema",
   "ArchiveWidgetOutputSchema",
   "ListWorkOrdersInputSchema",
   "ListWorkOrdersOutputSchema",
@@ -34,9 +43,13 @@ const SCHEMA_NAMES = [
 
 /** One distinct schema instance per name, so identity can be asserted. */
 function schemaRegistry(): Record<string, z.ZodType> {
-  return Object.fromEntries(
-    SCHEMA_NAMES.map((name) => [name, z.record(z.string(), z.unknown())]),
-  );
+  return {
+    ...Object.fromEntries(
+      SCHEMA_NAMES.map((name) => [name, z.record(z.string(), z.unknown())]),
+    ),
+    // One STRICT contract, so response validation has something to refuse.
+    GetWidgetOutputSchema: z.object({ widgetId: z.string() }),
+  };
 }
 
 interface RouteOverride {
@@ -143,14 +156,49 @@ function fixtureManifest(options?: {
   };
 }
 
-function buildClient(manifest: unknown = fixtureManifest()) {
-  const requests: ManifestClientRequest[] = [];
-  const schemas = schemaRegistry();
-  const client = createManifestClient(manifest, schemas, {
-    performRequest: async (request) => {
-      requests.push(request);
-      return { ok: true };
+interface RecordedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+/** A response the fake transport hands back, built like a real one would be. */
+function response(status: number, rawBody: string): HttpResponseLike {
+  return { ok: status < 400, status, text: async () => rawBody };
+}
+
+function jsonResponse(status: number, body: unknown): HttpResponseLike {
+  return response(status, JSON.stringify(body));
+}
+
+function buildClient(options?: {
+  manifest?: unknown;
+  schemas?: Record<string, z.ZodType>;
+  validateResponses?: "always" | "never";
+  baseUrl?: string;
+  answer?: (request: RecordedRequest) => HttpResponseLike;
+}): {
+  client: ManifestClient;
+  requests: RecordedRequest[];
+  schemas: Record<string, z.ZodType>;
+} {
+  const requests: RecordedRequest[] = [];
+  const schemas = options?.schemas ?? schemaRegistry();
+  const answer = options?.answer ?? (() => jsonResponse(200, { ok: true }));
+  const client = createManifestClient(options?.manifest ?? fixtureManifest(), schemas, {
+    fetchImpl: async (url, init) => {
+      const recorded: RecordedRequest = {
+        url,
+        method: init.method,
+        headers: init.headers,
+        ...(init.body === undefined ? {} : { body: init.body }),
+      };
+      requests.push(recorded);
+      return answer(recorded);
     },
+    validateResponses: options?.validateResponses ?? "always",
+    ...(options?.baseUrl === undefined ? {} : { baseUrl: options.baseUrl }),
   });
   return { client, requests, schemas };
 }
@@ -164,7 +212,17 @@ function failureCodeOf(run: () => unknown): string | null {
   }
 }
 
-describe("manifest-client — dérivation (spec front-derivation §1)", () => {
+async function failureOf(run: () => Promise<unknown>): Promise<OgygieFailure> {
+  try {
+    await run();
+  } catch (thrown) {
+    if (thrown instanceof OgygieFailure) return thrown;
+    throw thrown;
+  }
+  throw new Error("the call was expected to fail, and it did not");
+}
+
+describe("manifest-client — dérivation (spec manifest-client §1)", () => {
   it("ÉTANT DONNÉ le manifeste QUAND le client est construit ALORS il expose exactement les routes déclarées", () => {
     const { client } = buildClient();
     expect(Object.keys(client).sort()).toEqual(["reports", "widgets", "workOrders"]);
@@ -180,11 +238,17 @@ describe("manifest-client — dérivation (spec front-derivation §1)", () => {
   });
 
   it("MUTATION : une route retirée du manifeste disparaît du client", () => {
-    const { client } = buildClient(fixtureManifest({ dropArchiveRoute: true }));
+    const { client } = buildClient({ manifest: fixtureManifest({ dropArchiveRoute: true }) });
     expect(client["widgets"]?.["archive"]).toBeUndefined();
     expect(client["widgets"]?.["create"]).toBeDefined();
   });
 
+  it("chaque opération porte les schémas du registre, sans annotation manuelle", () => {
+    const { client, schemas } = buildClient();
+    expect(client["reports"]?.["search"]?.outputSchema).toBe(schemas["SearchReportsOutputSchema"]);
+    expect(client["reports"]?.["search"]?.inputSchema).toBe(schemas["SearchReportsInputSchema"]);
+  });
+
   it("les clés de cache sont dérivées du chemin : racine, opération, valeurs de params, puis reste de l'entrée", () => {
     const { client } = buildClient();
     expect(client["widgets"]?.["list"]?.queryKey()).toEqual(["widgets", "list"]);
@@ -203,7 +267,7 @@ describe("manifest-client — dérivation (spec front-derivation §1)", () => {
     expect(client["workOrders"]?.["list"]?.queryKey()).toEqual(["work-orders", "list"]);
   });
 
-  it("RÉGRESSION (ecrans-plan) : deux GET voisins sur la même entité ne partagent JAMAIS une clé de cache", () => {
+  it("RÉGRESSION : deux GET voisins sur la même entité ne partagent JAMAIS une clé de cache", () => {
     // Without the operation in the key, widgets.get and a sibling
     // GET /api/widgets/:widgetId/child would collide — TanStack would dedupe
     // them and the second query would silently never fire.
@@ -224,64 +288,139 @@ describe("manifest-client — dérivation (spec front-derivation §1)", () => {
     expect(client["widgets"]?.["list"]?.isMutation).toBe(false);
   });
 
+  it("MUTATION : un schéma absent du registre refuse la construction", () => {
+    const schemas = schemaRegistry();
+    delete schemas["CreateWidgetInputSchema"];
+    expect(failureCodeOf(() => buildClient({ schemas }))).toBe("MANIFEST_CLIENT_UNKNOWN_SCHEMA");
+  });
+
+  it("MUTATION : deux routes qui dérivent la même opération refusent la construction", () => {
+    const manifest = fixtureManifest({
+      extraWidgetRoutes: [
+        {
+          method: "PUT",
+          path: "/api/widgets/:widgetId",
+          description: "Collides with PATCH: same derived operation name.",
+          schemaInput: "UpdateWidgetInputSchema",
+          schemaOutput: "UpdateWidgetOutputSchema",
+        },
+      ],
+    });
+    expect(failureCodeOf(() => buildClient({ manifest }))).toBe(
+      "MANIFEST_CLIENT_AMBIGUOUS_OPERATION",
+    );
+  });
+
+  it("MUTATION : un manifeste invalide refuse la construction au lieu de dériver un client menteur", () => {
+    expect(failureCodeOf(() => buildClient({ manifest: { version: 1 } }))).toBe(
+      "MANIFEST_CLIENT_INVALID_MANIFEST",
+    );
+  });
+});
+
+describe("manifest-client — transport (spec manifest-client §1)", () => {
   it("un appel GET envoie le reste de l'entrée en query string, sans body", async () => {
-    const { client, requests, schemas } = buildClient();
+    const { client, requests } = buildClient({ validateResponses: "never" });
     await client["reports"]?.["search"]?.({ q: "ab", limit: 20 });
     expect(requests).toEqual([
       {
+        url: "/api/reports?q=ab&limit=20",
         method: "GET",
-        path: "/api/reports?q=ab&limit=20",
-        outputSchema: schemas["SearchReportsOutputSchema"],
+        headers: { accept: "application/json" },
       },
     ]);
   });
 
   it("un appel de mutation consomme les params du chemin et envoie le reste en body", async () => {
-    const { client, requests } = buildClient();
+    const { client, requests } = buildClient({ validateResponses: "never" });
     await client["widgets"]?.["update"]?.({ widgetId: "w-1", title: "renamed" });
     await client["workOrders"]?.["accept"]?.({ orderId: "o-9" });
-    expect(requests[0]?.path).toBe("/api/widgets/w-1");
-    expect(requests[0]?.body).toEqual({ title: "renamed" });
-    expect(requests[1]?.path).toBe("/api/work-orders/o-9/accept");
-    expect(requests[1]?.body).toEqual({});
+    expect(requests[0]?.url).toBe("/api/widgets/w-1");
+    expect(requests[0]?.body).toBe(JSON.stringify({ title: "renamed" }));
+    expect(requests[0]?.headers["content-type"]).toBe("application/json");
+    expect(requests[1]?.url).toBe("/api/work-orders/o-9/accept");
+    expect(requests[1]?.body).toBe("{}");
   });
 
-  it("un param de chemin manquant à l'appel est refusé bruyamment", async () => {
-    const { client } = buildClient();
-    await expect(client["widgets"]?.["update"]?.({ title: "renamed" })).rejects.toSatisfy(
-      (thrown) =>
-        thrown instanceof OgygieFailure && thrown.error.code === "CLIENT_MISSING_PATH_PARAM",
+  it("le baseUrl préfixe le chemin dérivé, sans jamais doubler la barre", async () => {
+    const { client, requests } = buildClient({
+      validateResponses: "never",
+      baseUrl: "https://api.example.test/",
+    });
+    await client["widgets"]?.["list"]?.();
+    expect(requests[0]?.url).toBe("https://api.example.test/api/widgets");
+  });
+
+  it("un param de chemin manquant à l'appel est refusé bruyamment, sans appeler le réseau", async () => {
+    const { client, requests } = buildClient();
+    const failure = await failureOf(() => operationOf(client, "widgets", "update")({ title: "x" }));
+    expect(failure.error.code).toBe("MANIFEST_CLIENT_MISSING_PATH_PARAM");
+    expect(requests).toEqual([]);
+  });
+
+  it("ÉTANT DONNÉ validateResponses \"always\" et une réponse violant le schéma ALORS CONTRACT_BROKEN", async () => {
+    const { client } = buildClient({
+      answer: () => jsonResponse(200, { widgetId: 42 }),
+    });
+    const failure = await failureOf(
+      () => operationOf(client, "widgets", "get")({ widgetId: "w-1" }),
     );
+    expect(failure.error.code).toBe("CONTRACT_BROKEN");
+    expect(failure.error.cause).toContain("GetWidgetOutputSchema");
   });
 
-  it("MUTATION : un schéma absent du registre refuse la construction (CLIENT_MANIFEST_INVALID)", () => {
-    const schemas = schemaRegistry();
-    delete schemas["CreateWidgetInputSchema"];
-    expect(
-      failureCodeOf(() =>
-        createManifestClient(fixtureManifest(), schemas, {
-          performRequest: async () => ({}),
-        }),
-      ),
-    ).toBe("CLIENT_MANIFEST_INVALID");
+  it("ÉTANT DONNÉ validateResponses \"never\" ALORS la même réponse passe telle quelle", async () => {
+    const { client } = buildClient({
+      validateResponses: "never",
+      answer: () => jsonResponse(200, { widgetId: 42 }),
+    });
+    await expect(client["widgets"]?.["get"]?.({ widgetId: "w-1" })).resolves.toEqual({
+      widgetId: 42,
+    });
   });
 
-  it("MUTATION : deux routes qui dérivent la même opération refusent la construction", () => {
-    const manifest = fixtureManifest({
-      extraWidgetRoutes: [
-        {
-          method: "PUT",
-          path: "/api/widgets/:widgetId",
-          description: "Collides with PATCH: same derived operation name.",
-          schemaInput: "UpdateWidgetInputSchema",
-          schemaOutput: "UpdateWidgetOutputSchema",
-        },
-      ],
+  it("une réponse qui n'est pas du JSON est un contrat cassé, jamais une SyntaxError nue", async () => {
+    const { client } = buildClient({
+      answer: () => response(200, "<html>gateway timeout</html>"),
     });
-    expect(failureCodeOf(() => buildClient(manifest))).toBe("CLIENT_MANIFEST_INVALID");
+    const failure = await failureOf(() => operationOf(client, "widgets", "list")());
+    expect(failure.error.code).toBe("CONTRACT_BROKEN");
   });
 
-  it("MUTATION : un manifeste invalide refuse la construction au lieu de dériver un client menteur", () => {
-    expect(failureCodeOf(() => buildClient({ version: 1 }))).toBe("CLIENT_MANIFEST_INVALID");
+  it("ÉTANT DONNÉ une réponse d'échec portant un corps OgygieError ALORS elle ressort inchangée", async () => {
+    const apiFailure = ogygieError({
+      code: "WIDGET_TITLE_ALREADY_USED",
+      message: "A widget with this title already exists in this account.",
+      file: "src/features/widgets/service.ts",
+      cause: "title=renamed already stored",
+      suggestedFix: "Choose another title, or update the existing widget.",
+      details: { conflictingId: "w-2" },
+    });
+    const { client } = buildClient({ answer: () => jsonResponse(409, apiFailure) });
+    const failure = await failureOf(
+      () => operationOf(client, "widgets", "update")({ widgetId: "w-1", title: "renamed" }),
+    );
+    expect(failure.error).toEqual(apiFailure);
+    expect(failure.httpStatus).toBe(409);
+  });
+
+  it("ÉTANT DONNÉ un échec sans corps OgygieError ALORS NETWORK_ERROR, statut conservé", async () => {
+    const { client } = buildClient({ answer: () => jsonResponse(502, { message: "boom" }) });
+    const failure = await failureOf(() => operationOf(client, "widgets", "list")());
+    expect(failure.error.code).toBe("NETWORK_ERROR");
+    expect(failure.error.details["status"]).toBe(502);
+    expect(failure.httpStatus).toBe(502);
+  });
+
+  it("ÉTANT DONNÉ un fetchImpl qui rejette ALORS NETWORK_ERROR, jamais l'erreur brute", async () => {
+    const client = createManifestClient(fixtureManifest(), schemaRegistry(), {
+      fetchImpl: async () => {
+        throw new TypeError("Failed to fetch");
+      },
+      validateResponses: "always",
+    });
+    const failure = await failureOf(() => operationOf(client, "widgets", "list")());
+    expect(failure.error.code).toBe("NETWORK_ERROR");
+    expect(failure.error.cause).toContain("Failed to fetch");
   });
 });

package/src/manifest-client.ts

@@ -1,11 +1,11 @@
 /**
  * @intent GENERIC manifest-derived API client factory, framework side — the
  * browser pendant of the manifest-derived gateway: this module knows ZERO
- * product vocabulary (D10 amended — generic tooling lives in the core), and
- * the vocabulary test next to it proves it. It derives callable operations
- * from an Ogygie manifest: every declared route becomes a method under its
- * path-root namespace, nothing else exists — a route removed from the
- * manifest disappears from the client, the manifest is the only map (D27).
+ * product vocabulary (generic tooling lives in the core), and the vocabulary
+ * gate next to it proves it. It derives callable operations from an Ogygie
+ * manifest: every declared route becomes a method under its path-root
+ * namespace, nothing else exists — a route removed from the manifest
+ * disappears from the client, the manifest is the only map.
  *
  * Derivations (all from the manifest, nothing hand-written per feature):
  * - namespace: first path segment after /api, camelCased
@@ -15,20 +15,24 @@
  *   declared input schema name ("SearchThingsInputSchema" → search); when the
  *   schema name carries no verb, a method fallback (GET → list, GET on
  *   ":param" → get, POST → create, PATCH/PUT → update, DELETE → delete);
- * - cache key: [root, ...path param values, remaining input if any] — the
- *   number-one source of cache bugs, so it is never written by hand;
+ * - cache key: [root, operation, ...path param values, remaining input if any]
+ *   — the number-one source of cache bugs, so it is never written by hand;
  * - invalidation roots: the route's own root, plus the roots the manifest
  *   declares in `invalidates` (cross-feature staleness is READ, never
  *   guessed in a screen).
  *
- * Transport stays OUTSIDE: the consumer injects `performRequest` (its typed
- * fetch over the shared contracts, dev-time response validation included) —
- * this module only resolves paths, splits inputs and derives keys. Building
- * an incoherent client REFUSES loudly (CLIENT_MANIFEST_INVALID): a refusal
+ * The TRANSPORT lives here too and owns no effect of its own: `fetchImpl` is
+ * injected (principle 5), no environment variable is ever read, and the
+ * response contract is re-validated when the product asks for it
+ * (`validateResponses: "always"` in dev). Failures speak ONE language: an
+ * OgygieError body comes back untouched, anything else is wrapped in
+ * NETWORK_ERROR or CONTRACT_BROKEN — never a raw fetch rejection.
+ *
+ * Building an incoherent client REFUSES loudly (MANIFEST_CLIENT_*): a refusal
  * at construction beats a method that lies at call time.
  */
 import { z } from "zod";
-import { throwOgygieError } from "./error.schema.js";
+import { OgygieErrorSchema, OgygieFailure, throwOgygieError } from "./error.schema.js";
 
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 
@@ -58,18 +62,36 @@ export const ClientManifestViewSchema = z.object({
 });
 export type ClientManifestView = z.infer<typeof ClientManifestViewSchema>;
 
-/** What the injected transport receives: a fully resolved request. */
-export interface ManifestClientRequest {
-  method: HttpMethod;
-  /** Path with params substituted and the query string already appended. */
-  path: string;
-  /** Present on POST/PUT/PATCH only: the input minus the path params. */
-  body?: unknown;
-  outputSchema: z.ZodType;
+/** The SHAPE of a response the client needs — a `Response` satisfies it. */
+export interface HttpResponseLike {
+  ok: boolean;
+  status: number;
+  text: () => Promise<string>;
 }
 
+/**
+ * The injected network effect. `globalThis.fetch` satisfies it, and so does a
+ * fake in a test — this module never reaches the network by itself.
+ */
+export type FetchLike = (
+  url: string,
+  init: { method: HttpMethod; headers: Record<string, string>; body?: string },
+) => Promise<HttpResponseLike>;
+
 export interface ManifestClientOptions {
-  performRequest: (request: ManifestClientRequest) => Promise<unknown>;
+  fetchImpl: FetchLike;
+  /**
+   * "always" re-parses every response with its declared output schema (in dev
+   * a broken contract must fail HERE, not three screens later); "never" is a
+   * passthrough. The PRODUCT decides per environment — the core reads no env.
+   */
+  validateResponses: "always" | "never";
+  /**
+   * Prefix put in front of the derived "/api/..." path. Empty by default: the
+   * front calls its api RELATIVELY and knows neither host nor port
+   * (AGENTS.md §Sécurité 8). A trailing "/" is trimmed.
+   */
+  baseUrl?: string;
 }
 
 /** One derived operation: callable, and self-describing for the query layer. */
@@ -83,7 +105,7 @@ export interface ApiOperation {
   outputSchema: z.ZodType;
   /** True for POST/PUT/PATCH/DELETE — the caller picks query vs mutation. */
   isMutation: boolean;
-  /** Derived cache key: [root, ...param values, remaining input if any]. */
+  /** Derived cache key: [root, operation, ...param values, remaining input if any]. */
   queryKey: (input?: Record<string, unknown>) => ReadonlyArray<unknown>;
   /** Cache roots stale after a successful mutation: own root + declared `invalidates`. */
   invalidationRoots: ReadonlyArray<string>;
@@ -107,15 +129,28 @@ function verbOfInputSchemaName(schemaName: string): string | null {
   return match?.[1] === undefined ? null : match[1].toLowerCase();
 }
 
-function refuseClient(cause: string): never {
+/**
+ * Construction refusals, one STABLE code per cause: "the manifest is
+ * unreadable", "a declared schema is missing from the registry" and "two
+ * routes derive the same operation" are three different things to fix, and an
+ * agent reading the error alone must know which.
+ */
+function refuseClient(
+  code:
+    | "MANIFEST_CLIENT_INVALID_MANIFEST"
+    | "MANIFEST_CLIENT_UNKNOWN_SCHEMA"
+    | "MANIFEST_CLIENT_AMBIGUOUS_OPERATION",
+  cause: string,
+  suggestedFix: string,
+): never {
   throwOgygieError(
     {
-      code: "CLIENT_MANIFEST_INVALID",
-      message: "Manifest client construction refused: the manifest cannot be derived into operations.",
+      code,
+      message:
+        "Manifest client construction refused: the manifest cannot be derived into operations.",
       file: "ogygie.manifest.json",
       cause,
-      suggestedFix:
-        "Fix the manifest (or register the missing schema in the client's schema registry) — a construction refusal beats a method that lies.",
+      suggestedFix,
     },
     500,
   );
@@ -163,9 +198,11 @@ export function createManifestClient(
   const parsedManifest = ClientManifestViewSchema.safeParse(manifest);
   if (!parsedManifest.success) {
     refuseClient(
+      "MANIFEST_CLIENT_INVALID_MANIFEST",
       parsedManifest.error.issues
         .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
         .join(" ; "),
+      "Fix the declared route surface (method, /api path, schemaInput, schemaOutput) — a construction refusal beats a method that lies.",
     );
   }
 
@@ -173,24 +210,40 @@ export function createManifestClient(
   const mounted = new Set<string>();
   for (const feature of parsedManifest.data.features) {
     for (const route of feature.routes) {
+      const key = `${route.method} ${route.path}`;
       if (!WELL_FORMED_ROUTE_PATH.test(route.path)) {
-        refuseClient(`feature "${feature.name}": route path "${route.path}" is malformed`);
+        refuseClient(
+          "MANIFEST_CLIENT_INVALID_MANIFEST",
+          `feature "${feature.name}": route path "${route.path}" is malformed`,
+          'Write the path as static or ":param" segments under /api (e.g. "/api/orders/:orderId").',
+        );
       }
       for (const schemaName of [route.schemaInput, route.schemaOutput]) {
         if (schemas[schemaName] === undefined) {
           refuseClient(
-            `feature "${feature.name}": route ${route.method} ${route.path} declares schema "${schemaName}" which is not in the schema registry`,
+            "MANIFEST_CLIENT_UNKNOWN_SCHEMA",
+            `feature "${feature.name}": route ${key} declares schema "${schemaName}", absent from the schema registry`,
+            `Register "${schemaName}" in the registry passed to createManifestClient, or fix the name declared in the manifest.`,
           );
         }
       }
-      const key = `${route.method} ${route.path}`;
-      if (mounted.has(key)) refuseClient(`route ${key} is declared twice`);
+      if (mounted.has(key)) {
+        refuseClient(
+          "MANIFEST_CLIENT_INVALID_MANIFEST",
+          `route ${key} is declared twice`,
+          "Declare each method+path exactly once in the manifest.",
+        );
+      }
       mounted.add(key);
 
       const segments = route.path.split("/").slice(2);
       const root = segments[0];
       if (root === undefined || root.startsWith(":")) {
-        refuseClient(`route ${key}: the first segment after /api must be static`);
+        refuseClient(
+          "MANIFEST_CLIENT_INVALID_MANIFEST",
+          `route ${key}: the first segment after /api must be static`,
+          'Start the path with a static root — it is both the namespace and the cache root ("/api/orders/...").',
+        );
       }
       const entry: DerivedRoute = {
         method: route.method,
@@ -215,7 +268,9 @@ export function createManifestClient(
     const namespaceOperations = (client[route.namespace] ??= {});
     if (namespaceOperations[route.operation] !== undefined) {
       refuseClient(
-        `operation "${route.namespace}.${route.operation}" is derived twice (${route.method} ${route.path} collides) — the derivation must stay unambiguous`,
+        "MANIFEST_CLIENT_AMBIGUOUS_OPERATION",
+        `operation "${route.namespace}.${route.operation}" is derived twice (${route.method} ${route.path} collides)`,
+        "Give one of the two routes a distinct static segment (or a distinct input schema verb) — a silent overwrite would hide a route.",
       );
     }
     namespaceOperations[route.operation] = buildOperation(route, schemas, options);
@@ -223,6 +278,26 @@ export function createManifestClient(
   return client;
 }
 
+/** JSON body of a response, or a CONTRACT_BROKEN refusal — never a raw SyntaxError. */
+function parseJsonBody(rawBody: string, route: DerivedRoute, url: string): unknown {
+  if (rawBody.trim() === "") return undefined;
+  try {
+    return JSON.parse(rawBody) as unknown;
+  } catch (thrown) {
+    throwOgygieError(
+      {
+        code: "CONTRACT_BROKEN",
+        message: `Response of ${route.namespace}.${route.operation} is not JSON.`,
+        file: null,
+        cause: `${route.method} ${url} answered a body starting with ${JSON.stringify(rawBody.slice(0, 80))} (${String(thrown)})`,
+        suggestedFix:
+          "Find what really answered on this path (a proxy error page? an html fallback?) — the declared output schema promises JSON.",
+      },
+      500,
+    );
+  }
+}
+
 function buildOperation(
   route: DerivedRoute,
   schemas: Record<string, z.ZodType>,
@@ -231,8 +306,14 @@ function buildOperation(
   const inputSchema = schemas[route.schemaInput];
   const outputSchema = schemas[route.schemaOutput];
   if (inputSchema === undefined || outputSchema === undefined) {
-    refuseClient(`route ${route.method} ${route.path}: schema lookup failed`); // unreachable — checked above
+    // Unreachable: createManifestClient refused every unknown schema above.
+    refuseClient(
+      "MANIFEST_CLIENT_UNKNOWN_SCHEMA",
+      `route ${route.method} ${route.path}: schema lookup failed`,
+      "Register the declared input and output schemas before building the client.",
+    );
   }
+  const baseUrl = (options.baseUrl ?? "").replace(/\/$/, "");
 
   /** Path params consumed by name; everything else is body or query string. */
   function splitInput(input: Record<string, unknown>): {
@@ -246,7 +327,7 @@ function buildOperation(
       if (typeof value !== "string" || value === "") {
         throwOgygieError(
           {
-            code: "CLIENT_MISSING_PATH_PARAM",
+            code: "MANIFEST_CLIENT_MISSING_PATH_PARAM",
             message: `Operation ${route.namespace}.${route.operation} was called without its ":${paramName}" path param.`,
             file: null,
             cause: `${route.method} ${route.path} needs "${paramName}", received ${JSON.stringify(value)}`,
@@ -270,24 +351,83 @@ function buildOperation(
         encodeURIComponent(String(input[paramName])),
       );
     }
-    if (METHODS_WITH_BODY.has(route.method)) {
-      return options.performRequest({
+
+    const carriesBody = METHODS_WITH_BODY.has(route.method);
+    let url = `${baseUrl}${resolvedPath}`;
+    if (!carriesBody) {
+      const searchParameters = new URLSearchParams();
+      for (const [name, value] of Object.entries(rest)) {
+        if (value !== undefined && value !== null) searchParameters.set(name, String(value));
+      }
+      const queryString = searchParameters.toString();
+      if (queryString !== "") url = `${url}?${queryString}`;
+    }
+
+    let response: HttpResponseLike;
+    let rawBody: string;
+    try {
+      response = await options.fetchImpl(url, {
         method: route.method,
-        path: resolvedPath,
-        body: rest,
-        outputSchema,
+        headers: carriesBody
+          ? { "content-type": "application/json", accept: "application/json" }
+          : { accept: "application/json" },
+        ...(carriesBody ? { body: JSON.stringify(rest) } : {}),
       });
+      rawBody = await response.text();
+    } catch (thrown) {
+      // The network layer failed BEFORE anything could be judged: nothing was
+      // answered, so nothing can be blamed on a contract.
+      throwOgygieError(
+        {
+          code: "NETWORK_ERROR",
+          message: `Call to ${route.namespace}.${route.operation} never reached the api.`,
+          file: null,
+          cause: `${route.method} ${url} threw ${String(thrown)}`,
+          suggestedFix:
+            "Check that the api answers on this path (dev proxy up? offline?) — the client never invents a fallback answer.",
+        },
+        503,
+      );
     }
-    const searchParameters = new URLSearchParams();
-    for (const [name, value] of Object.entries(rest)) {
-      if (value !== undefined && value !== null) searchParameters.set(name, String(value));
+
+    if (!response.ok) {
+      // An OgygieError body is the api SPEAKING: it comes back untouched —
+      // code, details and suggestedFix included. Wrapping it would destroy
+      // the only thing a screen can act on.
+      const failurePayload = OgygieErrorSchema.safeParse(parseJsonBody(rawBody, route, url));
+      if (failurePayload.success) throw new OgygieFailure(failurePayload.data, response.status);
+      throwOgygieError(
+        {
+          code: "NETWORK_ERROR",
+          message: `Call to ${route.namespace}.${route.operation} failed with status ${response.status}.`,
+          file: null,
+          cause: `${route.method} ${url} answered ${response.status} without an OgygieError body: ${JSON.stringify(rawBody.slice(0, 200))}`,
+          suggestedFix:
+            "Find what answered (gateway? proxy? an api without its error handler?) — every Ogygie failure carries an OgygieError body.",
+          details: { status: response.status },
+        },
+        response.status,
+      );
+    }
+
+    const data = parseJsonBody(rawBody, route, url);
+    if (options.validateResponses === "never") return data;
+    const validated = outputSchema.safeParse(data);
+    if (!validated.success) {
+      throwOgygieError(
+        {
+          code: "CONTRACT_BROKEN",
+          message: `Response of ${route.namespace}.${route.operation} violates its declared output schema.`,
+          file: null,
+          cause: `${route.method} ${url} — ${route.schemaOutput}: ${validated.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join(" ; ")}`,
+          suggestedFix: `Align the api answer with ${route.schemaOutput}, or amend the contract on both sides in the same PR.`,
+        },
+        500,
+      );
     }
-    const queryString = searchParameters.toString();
-    return options.performRequest({
-      method: route.method,
-      path: queryString === "" ? resolvedPath : `${resolvedPath}?${queryString}`,
-      outputSchema,
-    });
+    return validated.data;
   };
 
   return Object.assign(call, {
@@ -303,7 +443,7 @@ function buildOperation(
       // The OPERATION is part of the key: two GET routes on the same entity
       // (…/:id, …/:id/quantities, …/:id/costs) must never share a cache entry
       // — without it TanStack dedupes them and the later queries never fire
-      // (found by ecrans-plan, the first consumer of sibling GET routes).
+      // (regression found by the first consumer of sibling GET routes).
       const key: unknown[] = [route.root, route.operation, ...paramValues];
       if (Object.keys(rest).length > 0) key.push(rest);
       return key;

package/src/manifest.schema.test.ts

@@ -73,7 +73,7 @@ describe("manifest — features front", () => {
   });
 });
 
-// Front-derivation extension (spec front-derivation): a mutation route may
+// Manifest-client extension (specs/manifest-client.spec.md §3): a mutation route may
 // declare the cache roots it stales beyond its own — read by the derived
 // client, verified here: a target matching nothing is a typo that would
 // silently never invalidate anything.
@@ -102,7 +102,7 @@ const listArchiveRoute = {
   schemaOutput: "ListRecordArchiveOutputSchema",
 };
 
-describe("manifest — invalidations croisées des routes (spec front-derivation)", () => {
+describe("manifest — invalidations croisées des routes (spec manifest-client §3)", () => {
   it("une route sans invalidates reste acceptée (champ optionnel, élargissement libre)", () => {
     const parsed = OgygieManifestSchema.safeParse(
       manifestWithApiRoutes([createRecordRoute]),