@ogygie/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x10sion LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @ogygie/core
+
+Le framework **Ogygie** : l'outillage et l'infrastructure GÉNÉRIQUES du repo.
+Règle de séparation (DECISIONS.md D10) — le core ne connaît **aucun mot du
+domaine** du produit qui le consomme ; la dépendance va produit → core, jamais
+l'inverse. Un module qui contient une seule décision propre au produit reste
+dans `apps/`.
+
+| Export | Rôle |
+|---|---|
+| `@ogygie/core/errors` | Format `OgygieError` (code stable, `file`, `cause`, `suggestedFix`) |
+| `@ogygie/core/manifest` | Schéma du manifeste `ogygie.manifest.json` |
+| `@ogygie/core/spec` | Frontmatter des specs (`parseSpecFrontmatter`) et sections canoniques |
+| `@ogygie/core/db` · `/clock` · `/tenant` · `/test-kit` | Accès DB, horloge injectable, façade multi-tenant, kit de test |
+| `@ogygie/core/web-lint` · `/bundle-budget` | Parties testables des gates front |
+| `@ogygie/core/vocabulary` | Checker du test du vocabulaire (D10) — les stems appartiennent au produit |
+| `@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) |
+
+## Le test du vocabulaire couvre TOUT le core
+
+Le gate `src/product-vocabulary.scan.test.ts` scanne chaque fichier de
+`src/**` — modules, tests, fixtures, JSON d'exemples — et casse la CI au
+moindre stem produit (nom du produit, id de feature, mot du domaine, dans
+les deux langues). Les fixtures fuient le vocabulaire aussi facilement que
+le code : rien n'est exempté, sauf le fichier de scan lui-même, seul endroit
+autorisé à ÉCRIRE les mots interdits.
+
+## Hypothèses structurelles assumées (non-vocabulaires)
+
+Sans domaine ne veut pas dire sans opinion. Les hypothèses ci-dessous sont
+GRAVÉES dans les modules du core ; on les DÉCLARE ici plutôt que de les
+diluer — un produit qui ne peut pas les accepter ne peut pas consommer ce
+core tel quel.
+
+1. **SaaS multi-tenant à colonne tenant unique.** `TenantContext`
+   (`tenantId`, `userId`, `db`, `tenantColumnKey`) est le contrat d'accès aux
+   données : chaque table métier porte UNE colonne tenant et tout accès passe
+   par la façade `tenantDb` (injection à l'écriture, filtre à la lecture,
+   transactions comprises). Seule exception : les référentiels PARTAGÉS,
+   déclarés au manifeste (`shared: true`) et vérifiés par `shared-tables`.
+   Le produit nomme son tenant comme il veut (un alias) ; le core impose le
+   MODÈLE.
+2. **PostgreSQL, via Drizzle.** `Database` est un `PgDatabase`
+   (drizzle-orm/pg-core) ; migrations en SQL Postgres ; policy RLS attendue
+   sur toute table tenant (second rempart) ; transactions imbriquées =
+   savepoints Postgres ; test-kit sur PGlite (Postgres en mémoire). Ni
+   MySQL, ni SQLite, ni un autre ORM.
+3. **Fastify comme runtime HTTP.** `manifest-gateway` produit une app
+   Fastify (helmet, rate-limit, static) et l'API du produit est supposée
+   être un `FastifyInstance` décoré (`app.db`, `app.clock`).
+4. **Zod aux frontières.** Toute entrée/sortie a un schéma Zod, source
+   unique de vérité (validation runtime + type inféré + doc) ; le graphe
+   d'un `schemas.ts` n'autorise par défaut QUE `zod` (`contract-purity`,
+   D29).
+5. **Une devise de travail par tenant.** L'argent est un entier en centimes
+   + code ISO 4217 ; aucune conversion de change ne traverse le core. Les
+   futurs helpers monétaires naîtront ici sous cette hypothèse.
+6. **Temps en UTC, horloge injectée.** `Clock` est la seule porte d'accès
+   au temps ; les instants persistés sont de l'ISO 8601 UTC.
+7. **Repo cartographié par un manifeste.** `ogygie.manifest.json` à la
+   racine décrit apps, features, routes, tables, dépendances — les gates et
+   les dérivations (passerelle, client) le tiennent pour LA carte du repo.
+8. **Monorepo TypeScript ESM strict.** Modules NodeNext (imports relatifs
+   en `.js`), pnpm workspace, vitest, TypeScript strict ; les analyses
+   statiques (module-purity, contract-purity) lisent la syntaxe d'import
+   TypeScript — pas un bundler, pas un graphe runtime.
+9. **Anglais machine-lisible.** Identifiants, codes d'erreur, valeurs
+   d'enum et commentaires en anglais (D11) ; les documents humains du repo
+   consommateur restent en français.
+
+## Passerelle dérivée du manifeste — `@ogygie/core/gateway`
+
+`createManifestGateway(manifest, options)` dérive une passerelle Fastify d'un
+manifeste Ogygie : **chaque route déclarée devient un relais typé**, et rien
+d'autre n'est atteignable. Zéro ligne de code par feature — livrer une route
+n'ajoute aucun travail ici, l'oublier au manifeste la rend inatteignable.
+
+C'est un **relais pur** : il ne décide jamais qui a le droit de quoi
+(l'autorisation reste dans l'API — un relais qui autorise devient un confused
+deputy), ne transforme aucun payload, ne détient aucune session.
+
+### Usage minimal
+
+```ts
+import { readFileSync } from "node:fs";
+import { createManifestGateway } from "@ogygie/core/gateway";
+import * as widgetSchemas from "@my-product/api/features/widgets/schemas";
+
+const manifest: unknown = JSON.parse(readFileSync("ogygie.manifest.json", "utf8"));
+
+const app = await createManifestGateway(manifest, {
+  upstreamBaseUrl: "http://127.0.0.1:3000", // l'api, sur le réseau privé
+  schemas: { ...widgetSchemas },            // contrats indexés par nom exporté
+  staticRoot: "apps/web/dist",              // build du front + fallback SPA
+  rateLimit: { max: 300, timeWindow: "1 minute" },
+  timeoutMs: 10_000,
+  csp: { nonce: true },
+  passthroughPrefixes: ["/api/auth/"],      // liste FERMÉE, relais sans validation
+});
+
+await app.listen({ port: 8080, host: "0.0.0.0" });
+console.log(`${app.gatewayRoutes.length} relais montés depuis le manifeste`);
+for (const route of app.gatewayRoutes) console.log(route.method, route.path);
+```
+
+### Options
+
+| Option | Requis | Effet |
+|---|---|---|
+| `upstreamBaseUrl` | oui | Adresse privée de l'api. Jamais exposée au client, même en erreur. |
+| `schemas` | oui | `Record<string, ZodType>` indexé par nom exporté. Doit contenir **tous** les `schemaInput`/`schemaOutput` du manifeste, sinon le démarrage est refusé. |
+| `timeoutMs` | oui | Délai au-delà duquel l'appel amont est abandonné (→ 504). |
+| `csp.nonce` | oui | Pose un nonce CSP par requête et l'estampille sur les `<script>` de l'`index.html` servi. |
+| `staticRoot` | non | Dossier du build front : fichiers statiques + fallback `index.html` pour le routage client. Absent = rien n'est servi. |
+| `rateLimit` | non | `{ max, timeWindow }` ; défaut `300 / 1 minute`. |
+| `passthroughPrefixes` | non | Préfixes relayés **sans validation de contrat** (ex. un catch-all d'auth possédé par l'api, absent du manifeste par nature). Seule brèche à la règle « rien ne passe qui ne soit au manifeste » : liste fermée, chaque entrée justifiée, jamais un motif large. |
+
+Ce que le module N'inclut PAS, et qui reste à la charge de l'application : le
+registre de schémas (produit-conscient par nature), le contrat d'environnement,
+le point d'entrée, et le contenu de `passthroughPrefixes`.
+
+### Ce qui est posé pour tout le produit
+
+En-têtes de sécurité **possédés par la passerelle** (une copie amont ne peut pas
+les écraser) : CSP stricte sans `unsafe-inline`, HSTS, `X-Content-Type-Options`,
+`Referrer-Policy`, `Permissions-Policy`, plus le rate limit. Le statut, le corps
+et les `Set-Cookie` de l'amont, eux, traversent **octet pour octet** — une
+`OgygieError` métier arrive au client sans reformatage.
+
+### Erreurs
+
+| Code | Statut | Quand |
+|---|---|---|
+| `GATEWAY_MANIFEST_INVALID` | 500, **au démarrage** | Manifeste illisible, chemin de route malformé, route déclarée deux fois, ou schéma déclaré absent de `schemas`. Levée en `OgygieFailure` : le processus ne démarre pas — un démarrage impossible vaut mieux qu'un relais qui ment. |
+| `CONTRACT_VALIDATION_FAILED` | 400 | L'entrée ne satisfait pas le schéma déclaré. Émise PAR la passerelle : le trafic invalide n'atteint jamais le réseau privé. Le corps JSON est validé sur POST/PUT/PATCH, `{ ...query, ...params }` sur GET/DELETE. |
+| `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`. |

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@ogygie/core",
+  "version": "0.1.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",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./manifest": "./src/manifest.schema.ts",
+    "./vocabulary": "./src/vocabulary.ts",
+    "./web-lint": "./src/web-lint.ts",
+    "./bundle-budget": "./src/bundle-budget.ts",
+    "./spec": "./src/spec.schema.ts",
+    "./decision-refs": "./src/decision-refs.ts",
+    "./design-brief": "./src/design-brief.ts",
+    "./module-purity": "./src/module-purity.ts",
+    "./contract-purity": "./src/contract-purity.ts",
+    "./errors": "./src/error.schema.ts",
+    "./db": "./src/db.ts",
+    "./clock": "./src/clock.ts",
+    "./tenant": "./src/tenant.ts",
+    "./shared-tables": "./src/shared-tables.ts",
+    "./test-kit": "./src/test-kit.ts",
+    "./gateway": "./src/manifest-gateway.ts",
+    "./client": "./src/manifest-client.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": "^0.3.0",
+    "@fastify/helmet": "^13.0.0",
+    "@fastify/rate-limit": "^10.0.0",
+    "@fastify/static": "^10.1.2",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "@fastify/helmet": {
+      "optional": true
+    },
+    "@fastify/rate-limit": {
+      "optional": true
+    },
+    "@fastify/static": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.3.0",
+    "@fastify/helmet": "^13.0.0",
+    "@fastify/rate-limit": "^10.0.0",
+    "@fastify/static": "^10.1.2",
+    "@types/node": "^24.0.0",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.0.0",
+    "typescript": "^5.8.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/bundle-budget.test.ts

@@ -0,0 +1,64 @@
+/**
+ * @intent Mutation tests of the bundle-budget gate logic (D22: a known
+ * violation must be DETECTED, not just the happy path).
+ */
+import { describe, expect, it } from "vitest";
+import { bundleBudgetVerdict, entryAssetPathsOf } from "./bundle-budget.js";
+
+const BUILT_INDEX_HTML = `<!doctype html>
+<html>
+  <head>
+    <script type="module" crossorigin src="/assets/index-C3PO.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/vendor-R2D2.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-BB88.css">
+    <link rel="icon" href="/favicon.svg">
+  </head>
+  <body><div id="root"></div></body>
+</html>`;
+
+describe("bundle-budget", () => {
+  it("collecte script d'entrée, modulepreload et stylesheet — et EXCLUT les liens non initiaux", () => {
+    const paths = entryAssetPathsOf(BUILT_INDEX_HTML);
+    expect(paths).toEqual([
+      "/assets/index-C3PO.js",
+      "/assets/vendor-R2D2.js",
+      "/assets/index-BB88.css",
+    ]);
+  });
+
+  it("ne compte pas un chunk paresseux non référencé par index.html", () => {
+    // A lazy chunk (locale catalog…) never appears in index.html: the parser
+    // must not invent it. Mutation guard: a regex that matched every asset
+    // in dist/ would return it.
+    expect(entryAssetPathsOf(BUILT_INDEX_HTML)).not.toContain("/assets/fr-LOCALE.js");
+  });
+
+  it("verdict NÉGATIF : un bundle au-delà du budget est refusé (jamais avalé)", () => {
+    const verdict = bundleBudgetVerdict(
+      [
+        { path: "/assets/index.js", gzipBytes: 200_000 },
+        { path: "/assets/vendor.js", gzipBytes: 60_000 },
+      ],
+      250 * 1024,
+    );
+    expect(verdict.totalGzipBytes).toBe(260_000);
+    expect(verdict.withinBudget).toBe(false);
+  });
+
+  it("verdict nominal : sous le budget, assets triés du plus lourd au plus léger", () => {
+    const verdict = bundleBudgetVerdict(
+      [
+        { path: "/assets/a.js", gzipBytes: 10 },
+        { path: "/assets/b.js", gzipBytes: 20 },
+      ],
+      250 * 1024,
+    );
+    expect(verdict.withinBudget).toBe(true);
+    expect(verdict.assets[0]?.path).toBe("/assets/b.js");
+  });
+
+  it("verdict NÉGATIF : la limite est stricte (250 kB pile = refusé, la spec dit « < »)", () => {
+    const verdict = bundleBudgetVerdict([{ path: "/a.js", gzipBytes: 256_000 }], 256_000);
+    expect(verdict.withinBudget).toBe(false);
+  });
+});

package/src/bundle-budget.ts

@@ -0,0 +1,51 @@
+/**
+ * @intent Testable logic of the CI gate `ogygie:verify-bundle` (D22: a gate is
+ * born with its mutation test — see bundle-budget.test.ts). PURE on purpose
+ * (no node imports — the core tsconfig has no node types): the script
+ * scripts/verify-bundle.ts reads the files and gzips them, this module decides
+ * WHICH assets count as the initial bundle and whether the budget holds.
+ * "Initial bundle" = everything the browser loads before first paint: entry
+ * scripts, stylesheets and modulepreload'ed chunks referenced by index.html —
+ * lazy chunks (e.g. locale catalogs) deliberately excluded.
+ */
+
+export interface BundleAsset {
+  path: string;
+  gzipBytes: number;
+}
+
+export interface BundleBudgetVerdict {
+  assets: BundleAsset[];
+  totalGzipBytes: number;
+  budgetBytes: number;
+  withinBudget: boolean;
+}
+
+/** Extracts the initial-load asset paths referenced by a built index.html. */
+export function entryAssetPathsOf(indexHtml: string): string[] {
+  const paths: string[] = [];
+  for (const match of indexHtml.matchAll(/<script[^>]*\bsrc="([^"]+)"/g)) {
+    if (match[1] !== undefined) paths.push(match[1]);
+  }
+  for (const match of indexHtml.matchAll(/<link[^>]+>/g)) {
+    const tag = match[0];
+    const isInitial = /\brel="(?:stylesheet|modulepreload)"/.test(tag);
+    const href = /\bhref="([^"]+)"/.exec(tag)?.[1];
+    if (isInitial && href !== undefined) paths.push(href);
+  }
+  return paths;
+}
+
+/** Sums the gzip sizes and compares against the budget — nothing is dropped silently. */
+export function bundleBudgetVerdict(
+  assets: BundleAsset[],
+  budgetBytes: number,
+): BundleBudgetVerdict {
+  const totalGzipBytes = assets.reduce((total, asset) => total + asset.gzipBytes, 0);
+  return {
+    assets: [...assets].sort((a, b) => b.gzipBytes - a.gzipBytes),
+    totalGzipBytes,
+    budgetBytes,
+    withinBudget: totalGzipBytes < budgetBytes,
+  };
+}

package/src/clock.ts

@@ -0,0 +1,24 @@
+/**
+ * @intent Injectable clock: any function that needs the current time receives it
+ * as a dependency (declared-effects principle). Never a bare `new Date()` inside
+ * a service — the clock is the only access point to time.
+ */
+
+export interface Clock {
+  /** Current instant, UTC (dates are ALWAYS stored as UTC ISO 8601). */
+  now(): Date;
+}
+
+/** Real system clock — only injected at bootstrap (server.ts). */
+export const systemClock: Clock = {
+  now: () => new Date(),
+};
+
+/** Frozen clock for tests: `fixedClock("2026-07-01")`. */
+export function fixedClock(isoInstant: string): Clock {
+  const instant = new Date(isoInstant);
+  if (Number.isNaN(instant.getTime())) {
+    throw new Error(`fixedClock: invalid ISO instant "${isoInstant}"`);
+  }
+  return { now: () => instant };
+}

package/src/contract-purity.test.ts

@@ -0,0 +1,185 @@
+/**
+ * @intent Proves the transitive contract gate AND its mutations (D22): each
+ * case below is a way the server has come back — or could come back — into a
+ * contract graph, and the audit must catch every one of them without crying
+ * wolf on the erased forms. The keystone case is the historical incident
+ * (schemas.ts → index.ts → data loader → node:fs): it is caught THROUGH the
+ * chain, which is precisely what a single-file check cannot do.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  auditContractPurity,
+  contractEntryPaths,
+  resolveContractImport,
+  type ContractPurityManifest,
+} from "./contract-purity.js";
+
+const MANIFEST: ContractPurityManifest = {
+  apps: [
+    { name: "api", path: "apps/api", type: "api" },
+    { name: "web", path: "apps/web", type: "front" },
+  ],
+  features: [
+    { name: "orders", folder: "src/features/orders", status: "delivered" },
+    { name: "labels", folder: "src/features/labels", status: "delivered" },
+    { name: "ecrans", app: "web", folder: "src/features", status: "delivered" },
+    { name: "futur", folder: "src/features/futur", status: "skeleton" },
+  ],
+};
+
+const ORDERS = "apps/api/src/features/orders/schemas.ts";
+const LABELS = "apps/api/src/features/labels/schemas.ts";
+
+/** A pure two-feature graph: zod, a shared contract, a sibling contract. */
+const PURE_MODULES: Record<string, string> = {
+  [ORDERS]: `
+    import { z } from "zod";
+    import { LabelCodeSchema } from "../labels/schemas.js";
+    import { SourceProvenanceSchema } from "../../provenance.js";
+    export const OrderSchema = z.object({ labelCode: LabelCodeSchema });
+  `,
+  [LABELS]: `import { z } from "zod";\nexport const LabelCodeSchema = z.string();`,
+  "apps/api/src/provenance.ts": `import { z } from "zod";\nexport const SourceProvenanceSchema = z.object({});`,
+};
+
+function auditWith(overrides: Record<string, string>) {
+  const modules = { ...PURE_MODULES, ...overrides };
+  return auditContractPurity({
+    manifest: MANIFEST,
+    readModule: (path) => modules[path] ?? null,
+  });
+}
+
+describe("contract-purity", () => {
+  it("les points d'entrée sont DÉRIVÉS du manifeste : api uniquement, skeleton exclu", () => {
+    expect(contractEntryPaths(MANIFEST)).toEqual([ORDERS, LABELS]);
+  });
+
+  it("un graphe de contrats pur ne remonte aucune impureté", () => {
+    const report = auditWith({});
+    expect(report.impurities).toEqual([]);
+    expect(report.reachedPaths).toContain("apps/api/src/provenance.ts");
+  });
+
+  // ------------------------------------------------------------- mutations
+  it("MUTATION — l'incident historique : schemas.ts → index.ts → loader.ts → node:fs", () => {
+    const report = auditWith({
+      [ORDERS]: `import { searchLabels } from "../labels/index.js";`,
+      "apps/api/src/features/labels/index.ts": `export * from "./loader.js";`,
+      "apps/api/src/features/labels/loader.ts": `import { readFileSync } from "node:fs";`,
+    });
+    expect(report.impurities).toHaveLength(1);
+    expect(report.impurities[0]?.kind).toBe("SERVER_SURFACE");
+    expect(report.impurities[0]?.entryPath).toBe(ORDERS);
+  });
+
+  it("MUTATION — la TRANSITIVITÉ : un intermédiaire innocent qui ramène node:fs", () => {
+    const report = auditWith({
+      [ORDERS]: `import { ORDER_CODES } from "./constants.js";`,
+      "apps/api/src/features/orders/constants.ts": `export * from "./loader.js";`,
+      "apps/api/src/features/orders/loader.ts": `import { readFileSync } from "node:fs";`,
+    });
+    expect(report.impurities).toHaveLength(1);
+    const [impurity] = report.impurities;
+    expect(impurity?.kind).toBe("RUNTIME_PACKAGE");
+    expect(impurity?.specifier).toBe("node:fs");
+    expect(impurity?.chain).toEqual([
+      ORDERS,
+      "apps/api/src/features/orders/constants.ts",
+      "apps/api/src/features/orders/loader.ts",
+    ]);
+  });
+
+  it("MUTATION — Drizzle importé directement dans un contrat casse le gate", () => {
+    const report = auditWith({
+      [ORDERS]: `import { pgTable } from "drizzle-orm/pg-core";\nimport { z } from "zod";`,
+    });
+    expect(report.impurities).toHaveLength(1);
+    expect(report.impurities[0]?.specifier).toBe("drizzle-orm/pg-core");
+    expect(report.impurities[0]?.kind).toBe("RUNTIME_PACKAGE");
+  });
+
+  it("MUTATION — un index.ts PUR reste interdit : c'est la surface serveur", () => {
+    const report = auditWith({
+      [ORDERS]: `import { LABELS_LIST } from "../labels/index.js";`,
+      "apps/api/src/features/labels/index.ts": `export const LABELS_LIST = [];`,
+    });
+    expect(report.impurities).toHaveLength(1);
+    expect(report.impurities[0]?.kind).toBe("SERVER_SURFACE");
+  });
+
+  it("MUTATION — un module illisible est SIGNALÉ, jamais avalé en silence", () => {
+    const report = auditWith({ [ORDERS]: `import { X } from "./disparu.js";` });
+    expect(report.impurities).toHaveLength(1);
+    expect(report.impurities[0]?.kind).toBe("MODULE_NOT_FOUND");
+    expect(report.impurities[0]?.specifier).toBe("apps/api/src/features/orders/disparu.ts");
+  });
+
+  it("MUTATION — un contrat absent du disque est signalé (le gate ne saute pas une feature)", () => {
+    const report = auditContractPurity({
+      manifest: MANIFEST,
+      readModule: (path) => (path === ORDERS ? PURE_MODULES[path] ?? null : null),
+    });
+    expect(report.impurities.map((impurity) => impurity.kind)).toEqual([
+      "MODULE_NOT_FOUND", // ../labels/schemas.js, atteint depuis orders
+      "MODULE_NOT_FOUND", // ../../provenance.js
+      "MODULE_NOT_FOUND", // l'entrée labels elle-même
+    ]);
+  });
+
+  it("MUTATION — chaque contrat cassé est rapporté séparément, même faute partagée", () => {
+    const report = auditWith({
+      [LABELS]: `import { sql } from "drizzle-orm";`,
+    });
+    // orders atteint labels/schemas.ts, labels est aussi une entrée.
+    expect(report.impurities.map((impurity) => impurity.entryPath)).toEqual([ORDERS, LABELS]);
+  });
+
+  it("un import type vers la surface serveur reste permis : il est effacé à la compilation", () => {
+    const report = auditWith({
+      [ORDERS]: `import type { Label } from "../labels/index.js";\nimport { z } from "zod";`,
+    });
+    expect(report.impurities).toEqual([]);
+  });
+
+  it("un cycle d'imports ne fait pas tourner le gate en rond", () => {
+    const report = auditWith({
+      [ORDERS]: `import { A } from "./a.js";`,
+      "apps/api/src/features/orders/a.ts": `import { B } from "./b.js";`,
+      "apps/api/src/features/orders/b.ts": `import { A } from "./a.js";`,
+    });
+    expect(report.impurities).toEqual([]);
+  });
+
+  it("la politique d'autorisation est explicite : élargir est une décision", () => {
+    const modules: Record<string, string> = {
+      ...PURE_MODULES,
+      [ORDERS]: `import { format } from "date-fns";`,
+    };
+    const options = { manifest: MANIFEST, readModule: (path: string) => modules[path] ?? null };
+    expect(auditContractPurity(options).impurities).toHaveLength(1);
+    expect(
+      auditContractPurity({ ...options, allowedRuntimeSpecifiers: ["zod", "date-fns"] }).impurities,
+    ).toEqual([]);
+  });
+
+  it("resolveContractImport rend le chemin du dépôt, extension TypeScript restaurée", () => {
+    expect(resolveContractImport("zod", ORDERS)).toEqual({ kind: "external", specifier: "zod" });
+    expect(resolveContractImport("node:fs", ORDERS)).toEqual({
+      kind: "external",
+      specifier: "node:fs",
+    });
+    expect(resolveContractImport("../../provenance.js", ORDERS)).toEqual({
+      kind: "internal",
+      path: "apps/api/src/provenance.ts",
+    });
+    expect(resolveContractImport("./formulas", ORDERS)).toEqual({
+      kind: "internal",
+      path: "apps/api/src/features/orders/formulas.ts",
+    });
+    expect(resolveContractImport("../labels/index.js", ORDERS)).toEqual({
+      kind: "server-surface",
+      path: "apps/api/src/features/labels/index.ts",
+    });
+  });
+});