@ogygie/core 0.1.0

package/src/design-brief.ts

@@ -0,0 +1,581 @@
+/**
+ * @intent Testable heart of `pnpm ogygie:design-brief <feature>`
+ * (specs/ogygie-design-brief.spec.md): turns the repo's sources of truth
+ * (manifest routes, Zod contracts as JSON Schema, feature spec, design tokens,
+ * pattern catalog, fixture counts) into a DesignBrief object and its Markdown
+ * rendering. A derived brief cannot forget a field, invent an absent datum or
+ * skip an error state — the three diseases of unimplementable mockups.
+ *
+ * Generic tooling, hence the core (AGENTS.md workflow step 5, tooling
+ * exception): it knows naming CONVENTIONS (*Cents, *Meters, *At/*Date, enums)
+ * but not one word of any product's domain. Pure functions — sources in,
+ * brief out — so the spec's Given/When/Then blocks attack them directly; the
+ * fs walking and dynamic imports live in scripts/ogygie-design-brief.ts.
+ *
+ * Determinism is a contract (spec behavior 6): nothing here reads the clock
+ * or randomness, so two runs over unchanged sources render byte-identical
+ * documents. Signaled, never guessed: an empty section renders with an
+ * explicit marker instead of silence, and unknown field formats say so.
+ */
+import { z } from "zod";
+import { ogygieError, type OgygieError } from "./error.schema.js";
+import { SpecFrontmatterSchema, parseSpecFrontmatter } from "./spec.schema.js";
+
+// ------------------------------------------------------------- field formats
+/**
+ * Display format deduced from the FIELD NAME conventions of the repo —
+ * never from the value. A name following no known convention is listed as
+ * "unknown": signaled, never guessed (spec behavior 4).
+ */
+export const FieldFormatSchema = z.enum([
+  "currency-amount", // *Cents → firm currency amount (tabular-nums, unit shown)
+  "measure", // *Meters → SI measure, converted at presentation time only
+  "local-date", // *At / *Date → UTC ISO 8601 rendered as a local date
+  "translated-enum-label", // enum → the CODE is English, the label is translated
+  "unknown",
+]);
+export type FieldFormat = z.infer<typeof FieldFormatSchema>;
+
+export function formatOfField(fieldName: string, isEnum: boolean): FieldFormat {
+  const leaf = (fieldName.split(".").pop() ?? fieldName).replace(/\[\]$/, "");
+  if (/Cents$/.test(leaf)) return "currency-amount";
+  if (/Meters$/.test(leaf)) return "measure";
+  if (/(At|Date)$/.test(leaf)) return "local-date";
+  if (isEnum) return "translated-enum-label";
+  return "unknown";
+}
+
+// ------------------------------------------------------ JSON Schema flatten
+/**
+ * The subset of JSON Schema (draft 2020-12) that `z.toJSONSchema` emits for
+ * our contracts. Structural on purpose: the caller asserts zod's output onto
+ * it, and every read below tolerates absence.
+ */
+export interface JsonSchemaNode {
+  type?: string | string[];
+  properties?: Record<string, JsonSchemaNode>;
+  required?: string[];
+  items?: JsonSchemaNode;
+  enum?: Array<string | number | boolean | null>;
+  anyOf?: JsonSchemaNode[];
+  oneOf?: JsonSchemaNode[];
+  format?: string;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+}
+
+export const FieldDescriptorSchema = z.object({
+  name: z.string().describe("Dotted path; [] marks an array level, e.g. lines[].label"),
+  type: z.string().describe('Human label, e.g. "string(uuid)", "int", "string | null"'),
+  required: z.boolean(),
+  constraints: z.array(z.string()),
+  format: FieldFormatSchema,
+});
+export type FieldDescriptor = z.infer<typeof FieldDescriptorSchema>;
+
+/** `z.toJSONSchema` pads integers with ±MAX_SAFE_INTEGER bounds: noise, not a constraint. */
+const SAFE_INTEGER_BOUND = 9_007_199_254_740_991;
+
+/** Strips the nullable wrapper (`anyOf: [X, {type:"null"}]`) zod emits. */
+function unwrapNullable(node: JsonSchemaNode): { node: JsonSchemaNode; nullable: boolean } {
+  const members = node.anyOf ?? node.oneOf;
+  if (members !== undefined) {
+    const nonNull = members.filter((member) => member.type !== "null");
+    if (nonNull.length === 1 && nonNull[0] !== undefined) {
+      return { node: nonNull[0], nullable: nonNull.length < members.length };
+    }
+  }
+  if (Array.isArray(node.type) && node.type.includes("null")) {
+    const remaining = node.type.filter((typeName) => typeName !== "null");
+    return { node: { ...node, type: remaining[0] ?? remaining }, nullable: true };
+  }
+  return { node, nullable: false };
+}
+
+function typeLabelOf(node: JsonSchemaNode): string {
+  if (node.enum !== undefined) {
+    return `enum(${node.enum.map((value) => String(value)).join(" ; ")})`;
+  }
+  const members = node.anyOf ?? node.oneOf;
+  if (members !== undefined) {
+    return members.map((member) => typeLabelOf(member)).join(" | ");
+  }
+  if (Array.isArray(node.type)) return node.type.join(" | ");
+  if (node.type === "integer") return node.format === undefined ? "int" : `int(${node.format})`;
+  if (node.type === undefined) return "unknown";
+  return node.format === undefined ? node.type : `${node.type}(${node.format})`;
+}
+
+function constraintsOf(node: JsonSchemaNode): string[] {
+  const constraints: string[] = [];
+  if (node.minLength !== undefined || node.maxLength !== undefined) {
+    constraints.push(`longueur ${node.minLength ?? 0}..${node.maxLength ?? "∞"}`);
+  }
+  // A pattern accompanying a named format (uuid, date-time…) is the format's
+  // own machine regex — noise for a design tool, the format already says it.
+  if (node.pattern !== undefined && node.format === undefined) {
+    constraints.push(`motif ${node.pattern}`);
+  }
+  if (node.minimum !== undefined && Math.abs(node.minimum) !== SAFE_INTEGER_BOUND) {
+    constraints.push(`min ${node.minimum}`);
+  }
+  if (node.exclusiveMinimum !== undefined) constraints.push(`> ${node.exclusiveMinimum}`);
+  if (node.maximum !== undefined && Math.abs(node.maximum) !== SAFE_INTEGER_BOUND) {
+    constraints.push(`max ${node.maximum}`);
+  }
+  if (node.exclusiveMaximum !== undefined) constraints.push(`< ${node.exclusiveMaximum}`);
+  return constraints;
+}
+
+/**
+ * Flattens an object contract into one descriptor per LEAF field, in the
+ * declaration order of the schema (stable, hence deterministic output).
+ */
+export function fieldDescriptorsOfJsonSchema(root: JsonSchemaNode): FieldDescriptor[] {
+  const fields: FieldDescriptor[] = [];
+  walkProperties(root, "", fields);
+  return fields;
+}
+
+function walkProperties(node: JsonSchemaNode, prefix: string, out: FieldDescriptor[]): void {
+  for (const [name, child] of Object.entries(node.properties ?? {})) {
+    const path = `${prefix}${name}`;
+    const required = (node.required ?? []).includes(name);
+    const { node: bare, nullable } = unwrapNullable(child);
+    if (bare.properties !== undefined) {
+      walkProperties(bare, `${path}.`, out);
+      continue;
+    }
+    if (bare.type === "array" && bare.items?.properties !== undefined) {
+      walkProperties(bare.items, `${path}[].`, out);
+      continue;
+    }
+    const leaf = bare.type === "array" && bare.items !== undefined ? bare.items : bare;
+    const insideArray = leaf !== bare;
+    const baseLabel = typeLabelOf(unwrapNullable(leaf).node);
+    const label = insideArray ? `array<${baseLabel}>` : baseLabel;
+    out.push({
+      name: path,
+      type: nullable || unwrapNullable(leaf).nullable ? `${label} | null` : label,
+      required,
+      constraints: constraintsOf(unwrapNullable(leaf).node),
+      format: formatOfField(path, unwrapNullable(leaf).node.enum !== undefined),
+    });
+  }
+}
+
+// --------------------------------------------------------------- spec reads
+/** Body of the spec's « # États UI » section, one trimmed line per entry. */
+export function uiStatesOfSpec(specContent: string): string[] {
+  const section = /\n# États UI\n([\s\S]*?)(?=\n# |$)/.exec(specContent);
+  if (section === null || section[1] === undefined) return [];
+  return section[1]
+    .split("\n")
+    .map((line) => line.trim().replace(/^-\s+/, ""))
+    .filter((line) => line !== "");
+}
+
+/** Spec lines flagged as undecided — the convention is the words themselves. */
+export function openPointsOfSpec(specContent: string): string[] {
+  return specContent
+    .split("\n")
+    .map((line) => line.trim().replace(/^-\s+/, ""))
+    .filter((line) => /non tranché|à trancher/i.test(line));
+}
+
+/** Deferred behaviors of the spec frontmatter; unreadable frontmatter ⇒ none. */
+export function deferredOfSpec(specContent: string): string[] {
+  const block = /^---\n([\s\S]*?)\n---/.exec(specContent);
+  if (block === null || block[1] === undefined) return [];
+  const parsed = parseSpecFrontmatter(block[1]);
+  if (parsed.problems.length > 0) return [];
+  const frontmatter = SpecFrontmatterSchema.safeParse(parsed.value);
+  return frontmatter.success ? frontmatter.data.deferred : [];
+}
+
+// ------------------------------------------------------------- error codes
+/** Stable error codes raised by the feature's production sources. */
+export function errorCodesOfSources(
+  sources: Array<{ file: string; content: string }>,
+): string[] {
+  const codes = new Set<string>();
+  for (const source of sources) {
+    for (const match of source.content.matchAll(/\bcode:\s*"([A-Z][A-Z0-9_]+)"/g)) {
+      if (match[1] !== undefined) codes.add(match[1]);
+    }
+  }
+  return [...codes].sort();
+}
+
+// ------------------------------------------------------------- the contract
+export const SchemaFieldGroupSchema = z.object({
+  schemaName: z.string(),
+  route: z.string().describe('e.g. "GET /api/orders"'),
+  fields: z.array(FieldDescriptorSchema),
+});
+export type SchemaFieldGroup = z.infer<typeof SchemaFieldGroupSchema>;
+
+export const DesignBriefSchema = z.object({
+  feature: z.string(),
+  visualLanguage: z
+    .string()
+    .nullable()
+    .describe("Raw design/tokens.json text, verbatim — null when absent"),
+  patterns: z.array(
+    z.object({
+      name: z.string(),
+      intent: z.string().nullable(),
+    }),
+  ),
+  outputFields: z.array(SchemaFieldGroupSchema),
+  inputFields: z.array(SchemaFieldGroupSchema),
+  actions: z.array(
+    z.object({
+      method: z.string(),
+      path: z.string(),
+      description: z.string(),
+      kind: z.enum(["read", "mutation"]),
+    }),
+  ),
+  uiStates: z.array(z.string()),
+  errorCodes: z.array(z.string()),
+  volumes: z.array(
+    z.object({
+      table: z.string(),
+      fixtureRowCount: z
+        .number()
+        .int()
+        .nullable()
+        .describe("null = not measured (no fixture found)"),
+    }),
+  ),
+  constraints: z.array(z.string()),
+  openQuestions: z.array(z.string()),
+  warnings: z.array(z.string()),
+});
+export type DesignBrief = z.infer<typeof DesignBriefSchema>;
+
+/** Non-negotiable constraints of every screen (AGENTS.md §Front + i18n). */
+export const NON_NEGOTIABLE_DESIGN_CONSTRAINTS: readonly string[] = [
+  "i18n fr/en : la longueur des libellés varie fortement — prévoir l'élasticité, jamais de largeur figée sur un texte",
+  "mobile-first : la mise en page se conçoit d'abord pour un écran étroit",
+  "montants : `tabular-nums`, alignés à droite, unité explicite",
+  "accessibilité : parcours clavier complet et rôles ARIA sur chaque composant interactif",
+  "budget bundle : aucune dépendance front nouvelle pour un écran (AGENTS.md §Front)",
+];
+
+// -------------------------------------------------------------- the builder
+export interface DesignBriefSources {
+  featureName: string;
+  /** Feature names known to the manifest — membership is checked here. */
+  validFeatureNames: string[];
+  /** Raw text of design/tokens.json, null when the file does not exist. */
+  visualTokensJson: string | null;
+  /** Raw text of design/patterns.md, null when the file does not exist. */
+  patternsCatalogDoc: string | null;
+  /** Pattern modules found in the front apps' patterns folders. */
+  patternModules: Array<{ name: string; intent: string | null }>;
+  routes: Array<{
+    method: string;
+    path: string;
+    description: string;
+    inputSchemaName: string;
+    outputSchemaName: string;
+    inputJsonSchema: JsonSchemaNode | null;
+    outputJsonSchema: JsonSchemaNode | null;
+  }>;
+  /** Full text of the feature's spec, null when the file does not exist. */
+  specContent: string | null;
+  /** Production sources of the feature (tests excluded), for the error scan. */
+  featureSources: Array<{ file: string; content: string }>;
+  /** One entry per owned table; null count = no fixture found. */
+  fixtureCounts: Array<{ table: string; count: number | null }>;
+}
+
+export type DesignBriefBuildResult =
+  | { brief: DesignBrief; failure: null }
+  | { brief: null; failure: OgygieError };
+
+/** Catalog entries: every `## <Name>` heading of design/patterns.md. */
+function patternsOfCatalogDoc(catalogDoc: string): Array<{ name: string; intent: string | null }> {
+  const entries: Array<{ name: string; intent: string | null }> = [];
+  const headings = [...catalogDoc.matchAll(/\n## +(.+?) *\n([\s\S]*?)(?=\n## |$)/g)];
+  for (const heading of headings) {
+    if (heading[1] === undefined) continue;
+    const body = (heading[2] ?? "").trim();
+    entries.push({ name: heading[1], intent: body === "" ? null : body });
+  }
+  return entries;
+}
+
+export function buildDesignBrief(sources: DesignBriefSources): DesignBriefBuildResult {
+  if (!sources.validFeatureNames.includes(sources.featureName)) {
+    return {
+      brief: null,
+      failure: ogygieError({
+        code: "DESIGN_BRIEF_UNKNOWN_FEATURE",
+        message: `Feature "${sources.featureName}" is unknown to the manifest. Valid features: ${sources.validFeatureNames.join(", ")}.`,
+        file: "ogygie.manifest.json",
+        cause: `no features[] entry has name="${sources.featureName}"`,
+        suggestedFix: "Pick one of the valid feature names listed in the message.",
+      }),
+    };
+  }
+
+  // Catalog first, then modules: a module's @intent overrides the catalog
+  // entry of the same name (the code is closer to the truth than the doc).
+  const patternsByName = new Map<string, { name: string; intent: string | null }>();
+  for (const entry of patternsOfCatalogDoc(sources.patternsCatalogDoc ?? "")) {
+    patternsByName.set(entry.name, entry);
+  }
+  for (const moduleEntry of sources.patternModules) {
+    const known = patternsByName.get(moduleEntry.name);
+    patternsByName.set(moduleEntry.name, {
+      name: moduleEntry.name,
+      intent: moduleEntry.intent ?? known?.intent ?? null,
+    });
+  }
+  const patterns = [...patternsByName.values()].sort((a, b) =>
+    a.name.localeCompare(b.name, "en"),
+  );
+
+  const outputFields: SchemaFieldGroup[] = [];
+  const inputFields: SchemaFieldGroup[] = [];
+  const unreadableSchemas: string[] = [];
+  for (const route of sources.routes) {
+    const routeLabel = `${route.method} ${route.path}`;
+    if (route.outputJsonSchema !== null) {
+      outputFields.push({
+        schemaName: route.outputSchemaName,
+        route: routeLabel,
+        fields: fieldDescriptorsOfJsonSchema(route.outputJsonSchema),
+      });
+    } else {
+      unreadableSchemas.push(`${route.outputSchemaName} (${routeLabel})`);
+    }
+    if (route.inputJsonSchema !== null) {
+      inputFields.push({
+        schemaName: route.inputSchemaName,
+        route: routeLabel,
+        fields: fieldDescriptorsOfJsonSchema(route.inputJsonSchema),
+      });
+    } else {
+      unreadableSchemas.push(`${route.inputSchemaName} (${routeLabel})`);
+    }
+  }
+
+  const uiStates = sources.specContent === null ? [] : uiStatesOfSpec(sources.specContent);
+  const openQuestions =
+    sources.specContent === null
+      ? []
+      : [
+          ...openPointsOfSpec(sources.specContent),
+          ...deferredOfSpec(sources.specContent).map((entry) => `deferred — ${entry}`),
+        ];
+
+  // The spec-mandated warning comes first: a brief without states produces a
+  // happy-path-only mockup, and it must be said AT THE HEAD of the document.
+  const warnings: string[] = [];
+  if (uiStates.length === 0) {
+    warnings.push(
+      "DESIGN_BRIEF_MISSING_UI_STATES — la spec de la feature n'a pas de section « États UI » exploitable : un brief sans états produit une maquette du seul cas heureux.",
+    );
+  }
+  if (sources.visualTokensJson === null) {
+    warnings.push(
+      "DESIGN_BRIEF_MISSING_DESIGN_TOKENS — design/tokens.json introuvable : la section « Langage visuel » est vide. L'outil de design n'invente PAS de palette ; déclarer les tokens d'abord.",
+    );
+  }
+  if (patterns.length === 0) {
+    warnings.push(
+      "DESIGN_BRIEF_MISSING_PATTERNS — aucun pattern trouvé (ni design/patterns.md, ni dossier patterns/ d'une app front) : le vocabulaire de composition est vide.",
+    );
+  }
+  for (const unreadable of unreadableSchemas) {
+    warnings.push(
+      `DESIGN_BRIEF_SCHEMA_UNREADABLE — ${unreadable} : schéma introuvable ou non convertible, ses champs manquent au brief.`,
+    );
+  }
+
+  const brief = DesignBriefSchema.parse({
+    feature: sources.featureName,
+    visualLanguage: sources.visualTokensJson,
+    patterns,
+    outputFields,
+    inputFields,
+    actions: sources.routes.map((route) => ({
+      method: route.method,
+      path: route.path,
+      description: route.description,
+      kind: route.method.toUpperCase() === "GET" ? "read" : "mutation",
+    })),
+    uiStates,
+    errorCodes: errorCodesOfSources(sources.featureSources),
+    volumes: sources.fixtureCounts.map((entry) => ({
+      table: entry.table,
+      fixtureRowCount: entry.count,
+    })),
+    constraints: [...NON_NEGOTIABLE_DESIGN_CONSTRAINTS],
+    openQuestions,
+    warnings,
+  });
+  return { brief, failure: null };
+}
+
+// ------------------------------------------------------------- the renderer
+/** Escapes what would break a Markdown table cell. */
+function cell(text: string): string {
+  return text.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+/** The canonical marker of an empty section: signaled, never guessed. */
+function signaledEmpty(reason: string): string {
+  return `_Section vide — signalée, jamais devinée : ${reason}._`;
+}
+
+function fieldTable(groups: SchemaFieldGroup[], lines: string[]): void {
+  for (const group of groups) {
+    lines.push(`### \`${group.schemaName}\` — ${group.route}`, "");
+    if (group.fields.length === 0) {
+      lines.push("(aucun champ)", "");
+      continue;
+    }
+    lines.push(
+      "| Champ | Type | Obligatoire | Contraintes | Format |",
+      "|---|---|---|---|---|",
+    );
+    for (const field of group.fields) {
+      lines.push(
+        `| \`${cell(field.name)}\` | ${cell(field.type)} | ${field.required ? "oui" : "non"} | ${
+          field.constraints.length === 0 ? "—" : cell(field.constraints.join(" ; "))
+        } | ${field.format} |`,
+      );
+    }
+    lines.push("");
+  }
+}
+
+export function renderDesignBriefMarkdown(brief: DesignBrief): string {
+  const lines: string[] = [
+    `# Brief de design — ${brief.feature}`,
+    "",
+    `> Document DÉRIVÉ des sources de vérité du repo par \`pnpm ogygie:design-brief ${brief.feature}\`.`,
+    "> Ne pas éditer à la main : corriger la source, puis régénérer.",
+    "> Destinataire : un outil de design (humain ou IA) qui produit une mise en page — jamais du code.",
+    "",
+  ];
+
+  if (brief.warnings.length > 0) {
+    lines.push("## ⚠ Avertissements", "");
+    for (const warning of brief.warnings) lines.push(`- ${warning}`);
+    lines.push("");
+  }
+
+  lines.push("## Langage visuel", "");
+  if (brief.visualLanguage === null) {
+    lines.push(signaledEmpty("design/tokens.json introuvable"), "");
+  } else {
+    lines.push(
+      "Tokens déclarés (`design/tokens.json`) — l'outil de design n'invente ni couleur, ni typo, ni espacement :",
+      "",
+      "```json",
+      brief.visualLanguage.trimEnd(),
+      "```",
+      "",
+    );
+  }
+
+  lines.push("## Vocabulaire de composition", "");
+  if (brief.patterns.length === 0) {
+    lines.push(
+      signaledEmpty("ni design/patterns.md, ni dossier patterns/ d'une app front"),
+      "",
+    );
+  } else {
+    lines.push(
+      "Tout écran est une COMPOSITION de ces patterns — un pattern manquant se crée dans le catalogue, jamais dans l'écran :",
+      "",
+    );
+    for (const pattern of brief.patterns) {
+      lines.push(`- **${pattern.name}** — ${pattern.intent ?? "(intent non déclaré)"}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Données à afficher", "");
+  if (brief.outputFields.length === 0) {
+    lines.push(signaledEmpty("aucun schéma de sortie exploitable pour cette feature"), "");
+  } else {
+    fieldTable(brief.outputFields, lines);
+  }
+
+  lines.push("## Données à saisir", "");
+  if (brief.inputFields.length === 0) {
+    lines.push(signaledEmpty("aucun schéma d'entrée exploitable pour cette feature"), "");
+  } else {
+    fieldTable(brief.inputFields, lines);
+  }
+
+  lines.push("## Actions", "");
+  if (brief.actions.length === 0) {
+    lines.push(signaledEmpty("aucune route au manifeste pour cette feature"), "");
+  } else {
+    for (const action of brief.actions) {
+      const placement =
+        action.kind === "mutation"
+          ? "mutation : un bouton ou une commande à placer"
+          : "lecture : alimente l'écran";
+      lines.push(`- **${action.method} ${action.path}** — ${action.description} — ${placement}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## États obligatoires", "");
+  if (brief.uiStates.length === 0 && brief.errorCodes.length === 0) {
+    lines.push(
+      signaledEmpty("aucune section « États UI » dans la spec, aucun code d'erreur dans le code"),
+      "",
+    );
+  } else {
+    for (const state of brief.uiStates) lines.push(`- ${state}`);
+    if (brief.uiStates.length > 0) lines.push("");
+    if (brief.errorCodes.length > 0) {
+      lines.push("Codes d'erreur réels (chaque code = un état d'erreur à maquetter) :", "");
+      for (const code of brief.errorCodes) lines.push(`- \`${code}\``);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Volumétries réelles", "");
+  if (brief.volumes.length === 0) {
+    lines.push(signaledEmpty("aucune table possédée par cette feature"), "");
+  } else {
+    for (const volume of brief.volumes) {
+      lines.push(
+        volume.fixtureRowCount === null
+          ? `- \`${volume.table}\` : non mesurée (aucune fixture trouvée dans test-fixtures/)`
+          : `- \`${volume.table}\` : ${volume.fixtureRowCount} ligne(s) de fixtures`,
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push("## Contraintes non négociables", "");
+  for (const constraint of brief.constraints) lines.push(`- ${constraint}`);
+  lines.push("");
+
+  lines.push("## Questions ouvertes", "");
+  if (brief.openQuestions.length === 0) {
+    lines.push("_Aucune question ouverte : rien de non tranché dans la spec, aucun deferred._", "");
+  } else {
+    for (const question of brief.openQuestions) lines.push(`- ${question}`);
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/error.schema.ts

@@ -0,0 +1,62 @@
+/**
+ * @intent Single error format of Ogygie (runtime, validation, CI).
+ * Designed for the agent loop: generate → verify → fix.
+ * Every error says WHERE (file), WHAT (cause), and HOW to fix (suggestedFix).
+ */
+import { z } from "zod";
+
+export const OgygieErrorSchema = z.object({
+  ogygie: z.literal(true).describe("Marker: lets an agent tell our errors from noise"),
+  code: z
+    .string()
+    .regex(/^[A-Z][A-Z0-9_]+$/, "SCREAMING_SNAKE_CASE, stable over time"),
+  message: z.string().min(10).describe("Human-readable sentence (technical English)"),
+  file: z
+    .string()
+    .nullable()
+    .describe("Relative path of the file involved, null when not localizable"),
+  cause: z.string().describe("The precise datum or condition that triggered the error"),
+  suggestedFix: z.string().describe("Concrete action to fix — never empty"),
+  details: z.record(z.string(), z.unknown()).default({}),
+  timestamp: z.iso.datetime(),
+});
+export type OgygieError = z.infer<typeof OgygieErrorSchema>;
+
+/** Canonical factory — the only way to build an error payload in the repo. */
+export function ogygieError(
+  input: Omit<OgygieError, "ogygie" | "timestamp" | "details"> &
+    Partial<Pick<OgygieError, "details">>,
+): OgygieError {
+  return OgygieErrorSchema.parse({
+    ogygie: true,
+    timestamp: new Date().toISOString(),
+    details: {},
+    ...input,
+  });
+}
+
+/**
+ * Throwable wrapper around an OgygieError payload. It carries the HTTP status
+ * OUTSIDE the payload (the payload is the wire contract, the status is
+ * transport). Fastify's error handler maps it to a response; only the payload
+ * fields ever reach the client (never a stack trace).
+ */
+export class OgygieFailure extends Error {
+  public readonly error: OgygieError;
+  public readonly httpStatus: number;
+
+  constructor(error: OgygieError, httpStatus = 500) {
+    super(error.message);
+    this.name = "OgygieFailure";
+    this.error = error;
+    this.httpStatus = httpStatus;
+  }
+}
+
+/** Build-and-throw shortcut: `throwOgygieError({...}, 403)`. */
+export function throwOgygieError(
+  input: Parameters<typeof ogygieError>[0],
+  httpStatus = 500,
+): never {
+  throw new OgygieFailure(ogygieError(input), httpStatus);
+}

package/src/examples/erreur-convention-ci.json

@@ -0,0 +1,10 @@
+{
+  "ogygie": true,
+  "code": "MANIFEST_GHOST_ROUTE",
+  "message": "The manifest declares a route that does not exist in the code.",
+  "file": "ogygie.manifest.json",
+  "cause": "Route 'DELETE /api/orders/:id' declared for feature 'orders', but no matching route registration in src/features/orders/routes.ts",
+  "suggestedFix": "Either implement the route in src/features/orders/routes.ts, or remove it from the manifest. The manifest must never lie.",
+  "details": { "feature": "orders", "method": "DELETE", "path": "/api/orders/:id" },
+  "timestamp": "2026-07-29T10:15:00.000Z"
+}

package/src/examples/erreur-validation-runtime.json

@@ -0,0 +1,10 @@
+{
+  "ogygie": true,
+  "code": "HTTP_INPUT_VALIDATION",
+  "message": "The body of the POST /api/orders request is invalid.",
+  "file": "src/features/orders/schemas.ts",
+  "cause": "field 'quantity' = -3: violates the positive() constraint of CreateOrderInputSchema",
+  "suggestedFix": "Send a strictly positive quantity. See the CreateOrderInputSchema contract in src/features/orders/schemas.ts.",
+  "details": { "field": "quantity", "receivedValue": -3, "constraint": "positive" },
+  "timestamp": "2026-07-29T10:12:00.000Z"
+}