NeuralWall Rules Kit

ADR-0001 — Format, sérialisation et multilingue

  • Statut : Accepted
  • Date : 2026-06-03
  • Contexte associé : ADR-0002 (modèle de contenu), docs/control-taxonomy.md

Contexte

La fiche doit être lisible par un humain, par une machine (NeuralWall, tooling vendor) et par une IA (RAG), nativement multilingue, versionnable, et contribuée par PR communautaire. Question : quel format de source et quelle stratégie d'internationalisation ?

Décision

Sérialisation

  • Source de vérité : YAML. Auteurable à la main, commentaires autorisés (expliquer le pourquoi d'une règle), diffable en Git, validable en JSON Schema.
  • Représentation MACHINE : JSON dérivé du YAML, déterministe, locale-indépendant. C'est ce que NeuralWall ingère.
  • HUMAIN : Markdown rendu par locale. IA/RAG : carte rendue par locale.
  • Modèle « une source → N représentations », inspiré du principe JADN d'OpenC2 (modèle d'information indépendant de la sérialisation).

Multilingue

  • La structure est neutre : enums/identifiants ne sont jamais traduits.
  • Seule la prose est multilingue, en inline locale-map dans la source : title: { fr: "…", en: "…" }.
  • Le rendu HUMAIN/IA est produit par locale ; les embeddings RAG peuvent être générés par langue (retrieval multilingue natif).

Alternatives écartées

  • JSON en source — pas de commentaires, prose multi-ligne pénible, hostile à l'auteur. Conservé seulement comme sortie machine.
  • XML (xml:lang) — seul à offrir un i18n natif, mais verbeux et hostile aux contributeurs PR ; on résout l'i18n structurellement, donc l'avantage ne compense pas la friction.
  • Fichiers de prose séparés par locale (i18n/{locale}.yaml) — plus scalable au-delà de ~3 langues et meilleur pour des traducteurs dédiés, mais ajoute une indirection injustifiée en Phase 1. Retenu comme chemin de migration quand le nombre de langues ou de contributeurs le justifiera.

Conséquences

  • (+) Source unique, contributions PR fluides, validation forte, ingestion JSON triviale.
  • (+) Multilingue sans toucher la logique firewall.
  • (−) YAML a des pièges (coercition de types, indentation) → imposer safe_load et un linter YAML en CI.
  • (−) L'inline locale-map alourdit la source si le nombre de langues explose → déclencher la migration vers fichiers séparés à ce moment-là (réversible, non bloquant).