PIPE_DEV_SAFETY_CONTRACT v1.0 — Contrat de vocabulaire & invariants (PS 5.1)

Scope
- Ce contrat fige les termes, les formats et les garde‑fous du pipe KB/BootPack/Acceptance.
- Objectif: zéro devinette, résultats déterministes, lisibilité stable.

A. Vocabulaire CANONIQUE (les mots exacts à employer)
- BootPack: fichier texte de référence (bootpack.txt / bootpack_paste.txt).
- [BUG_KB_JSON]: SNAPSHOT embarqué de la KB (copie exacte et autonome de BUG_KB.json.txt).
- [BUG_KB_JSON_POINTER]: POINTEUR vers la KB externe (Path, SHA256, Entries).
- KB externe: le fichier BUG_KB.json.txt (source de vérité des entrées).
- Acceptance Gate (acceptance): script lecture‑seule qui lit UNIQUEMENT le SNAPSHOT embarqué.
- Selftest (probe): script lecture‑seule qui lit la KB EXTERNE (et son pointeur) + diagnostiques.
- Entries: nombre d’entrées dans la KB.
- Blocking: nombre d’entrées avec "blocking": true.
- SHA256: empreinte hexadécimale 64 caractères, MAJUSCULES.

B. Sémantique des OUTILS (qui lit quoi)
- acceptance: lit [BUG_KB_JSON] (SNAPSHOT). N’écrit JAMAIS. Sorties obligatoires:
  entries|blocking|ptr_exists|ptr_sha_match|ptr_entries_note|json_entries
- selftest: lit la KB EXTERNE via [BUG_KB_JSON_POINTER] et affiche les mêmes métriques + diag.
- Rebuild/offline: opération de fabrication du BootPack (hors de ce contrat) pour resynchroniser SNAPSHOT et POINTEUR.

C. Invariants de FORMAT (BootPack)
1) Sections: une seule occurrence de chaque en‑tête.
   - [BUG_KB_JSON]  → unique
   - [BUG_KB_JSON_POINTER] → unique
2) Fences du SNAPSHOT:
   - Triple backticks « ``` » sur une ligne seule AVANT et APRES le JSON.
   - Aucune indication de langage après « ``` ».
   - Le JSON entre fences DOIT être valide, multi‑ligne recommandé.
   - Interdit: BOM U+FEFF à l’intérieur du bloc JSON.
3) POINTEUR:
   - Canonique: "Path=", "SHA256=", "Entries=" (symbole "="). Les scripts tolèrent ":" ou "=" en lecture.
   - Path: UNC non quotée recommandé (ex: \DS-918\…), guillemets autorisés mais non préférés.
   - SHA256: 64 hexdigits MAJUSCULES. La comparaison est case‑insensitive.
   - Entries: entier >= 0, DOIT correspondre au nombre d’entrées effectif de la KB.
4) Encodage & retours chariot:
   - BootPack: UTF‑8 sans BOM. Fin de ligne CRLF recommandé (LF accepté).
   - BUG_KB.json.txt: UTF‑8 sans BOM. Le contenu embarqué dans le SNAPSHOT ne doit contenir aucun BOM.
   - Scripts .ps1: UTF‑8 AVEC BOM. ASCII‑safe (pas de typographiques). PS 5.1 strict.
5) Unicité & ordre:
   - L’acceptance lit le PREMIER [BUG_KB_JSON]. Toute duplication ultérieure est interdite.
   - Idem pour [BUG_KB_JSON_POINTER].

D. Règles de COHÉRENCE (mises à jour)
- Après ajout d’une entrée via ingest: selftest doit afficher entries+=1; acceptance peut rester à l’ancien chiffre tant que le SNAPSHOT n’est pas refait.
- Un BootPack « à jour » respecte simultanément: ptr_exists=True, ptr_sha_match=True, ptr_entries_note=Entries, acceptance.entries=json_entries=Entries.
- Canonicalisation conseillée lors d’un rebuild: pointer avec "=" ; SHA en MAJUSCULES ; JSON pretty‑print multi‑ligne.

E. Garde‑fous d’EXÉCUTION (lecture‑seule)
- acceptance: aucune écriture. Échec lisible si SNAPSHOT invalide/absent.
- selftest: aucune écriture. Affiche First3, PathLength, Test‑Path raw/dequoted/UNC, OpenReadOK, KbSha, PtrSha, Entries.

F. Check rapide avant acceptation (manuel, 7 points)
1) Un seul [BUG_KB_JSON].
2) Fences équilibrés ``` … ``` sans langage.
3) JSON parsable, sans BOM interne, multi‑ligne de préférence.
4) Un seul [BUG_KB_JSON_POINTER].
5) Path UNC réel (Test‑Path OK), SHA256 64 hexdigits, Entries = nombre réel.
6) BootPack en UTF‑8 sans BOM (le fichier). Scripts en UTF‑8 avec BOM.
7) Sémantique: acceptance lit snapshot / selftest lit externe (résultats attendus en conséquence).

G. Glossaire de synonymes à proscrire (remplacer par canonique)
- « embedded JSON », « inline KB » → SNAPSHOT ([BUG_KB_JSON])
- « pointer block », « kb ptr » → POINTEUR ([BUG_KB_JSON_POINTER])
- « hash », « digest » → SHA256
- « record count », « notes » → Entries

H. Politique de logs (extraits lisibles, pas de fichiers)
- acceptance: summary unique + [GATE-BLOCK]… ou [PASS]…
- selftest: summary identique + diag: First3, PathLength, TestPath Raw/Dequoted/Long, OpenReadOK, KbSha, PtrSha, PtrEntriesNote.

I. Compatibilité rétro (lecture)
- Les scripts DOIVENT accepter ":" ou "=" dans le POINTEUR. La forme canonique d’écriture reste "=".

Fin — v1.0 (2025‑11‑02)