published-language/instrument/README.md

# L'instrument — où chaque garde vit réellement

Chaque garde vit à son étage ; l'instrument regarde où elle est réellement
posée. Il court **dans la CI de la juridiction observée** — la juridiction se
mesure elle-même ; le registre publie l'instrument et reçoit les constats
(`temoin/ADR-018`, `prismagram-corpus/ADR-061` §2.6 et §2.8).

## Ce qu'il constate

Pour chaque invariant que la juridiction déclare dans le front-matter de ses
parcours (`invariants:`), l'instrument cherche chaque fichier qui le **nomme**
et rend un état :

| État | Sens |
|---|---|
| `domicilie` | nommé par une épreuve à son étage dû, nulle part au-dessus |
| `renforce` | nommé par des épreuves à son étage dû **et** au-dessus — défense en profondeur, signalée positivement, jamais blâmée |
| `mal_domicilie` | nommé par des épreuves **uniquement hors** de son étage dû — le seul écart |
| `aucun_locus` | nommé par aucune épreuve |

L'instrument constate la **nomination**, pas l'exécution : c'est la CI de la
juridiction qui fait passer ses épreuves ; l'instrument dit seulement où elles
habitent. Un même identifiant déclaré avec deux énoncés différents est une
homonymie : elle est portée dans le constat, jamais résolue ici.

## Le réglage — il appartient à la juridiction

L'instrument ne connaît aucun chemin d'aucun projet : toute convention vit
dans un fichier de réglage que la juridiction tient dans son dépôt, et que
chaque constat épingle par son empreinte. Voir
[`selftest/fixture/reglage.yaml`](selftest/fixture/reglage.yaml) pour la forme
complète : `juridiction`, `cadence_heures`, `parcours`, `strates` (la première
— ou celle marquée `due: true` — est l'étage dû), `epreuves`, `sortie`,
`journal_execution`.

## La correspondance vers une échelle tierce (`rang`, optionnel)

Une juridiction peut faire correspondre chacune de ses strates à une échelle
tierce (p. ex. les rangs 1–5 de Percursus) en déclarant `rang: N` sur la
strate, dans son réglage. L'instrument émet alors `rangs_constates` dans
chaque constat — **seulement si toutes les strates constatées portent un
rang** : une correspondance partielle laisserait deviner, et deviner n'est
pas constater — et publie la table complète (`correspondance_rangs`) dans le
journal d'exécution, pour joindre les constats anciens, qui ne se réécrivent
jamais. La grossièreté se dit dans le réglage (en commentaire) : un rang
absent de la correspondance est un rang que la juridiction ne sait pas
instrumenter, pas un rang qui va de soi.

## Les gardes nommées — des candidats, jamais des constats (optionnel)

Une exception de domaine est une règle qui a un nom et un `throw` — et souvent
ni épreuve ni déclaration. Si le réglage porte `gardes_nommees` (motifs de
fichiers) et `adr` (où chercher les citations), le journal rend
`gardes_nommees: { motifs, total, non_nommees_par_un_parcours, sans_epreuve,
ecartees, differees, candidats }`. Trois précautions, chacune répondant à une
faute possible :

- **« Nommée », jamais « déclarée ».** Un parcours peut porter la règle en
  langue naturelle sans nommer la classe ; l'instrument n'observe que la
  nomination, et les champs le disent (`nommee_par_parcours`, `_par_adr`,
  `_par_epreuve`). Absent ≠ non déclaré.
- **Une exception n'est pas un invariant.** Une absence (`NotFound`) n'est une
  règle pour personne : la juridiction l'exclut par motif (`gardes_exclues`).
- **Décider que non a un réceptacle.** Un registre de la juridiction
  (`gardes_ecartees` : `nom`, `decision: ecarte | differe`, `motif`, `jusqu_au`),
  que l'instrument **lit et n'écrit jamais** : l'écarté sort des candidats et
  reste dans le compte ; le différé revient à sa date.

L'instrument **mesure une existence, il ne déclare rien** ; rien ne devient un
constat, aucun état ne change de sens ; sans les clés, la section n'existe pas.
Sa limite est dans le journal (`motifs`) : ce qui ne porte pas le motif —
`require`, objets-valeurs, contraintes de schéma — lui est invisible.

Pourquoi si peu : c'est le plus petit instrument qui prouve que le code tient
des règles que nul n'a déclarées. Mesuré chez openathle le jour de son
écriture — huit exceptions de domaine, zéro citée par un parcours.

## Ce qu'il écrit — chez la juridiction, jamais ailleurs

- **`sortie`** : les constats, en **ajout seul**, et **seulement quand l'état
  change** — un constat inchangé ne produit aucun événement. Chaque constat
  porte ses pièces (chemin, ligne, strate), sa révision, l'empreinte du
  réglage : il est recalculable par quiconque clone le dépôt.
- **`journal_execution`** : réécrit à **chaque** exécution — le témoin de
  fraîcheur. Un journal plus vieux que la cadence déclarée est un écart que le
  lecteur du dépôt constate ; jamais un silence.

## Exécution

```sh
node instrument/run.mjs --config docs/parcours/_meta/strates.yaml
# --repo DIR   : racine du dépôt mesuré (défaut : répertoire courant)
# --dry-run    : affiche les constats sans rien écrire
```

Sort en erreur **uniquement** sur prérequis cassé (réglage absent ou
illisible, aucun parcours, aucun invariant) — jamais sur un écart constaté :
l'écart est le produit, pas une panne. `npm run instrument:selftest` joue
l'auto-épreuve sur une juridiction d'essai jetable.

## Limites dites (v0)

- Seuls les invariants déclarés dans les parcours sont mesurés ; un invariant
  qui ne vit que dans une ADR n'est pas encore vu.
- La citation est textuelle (mot entier) ; une épreuve qui vérifie sans nommer
  n'est pas constatée — nommer ses invariants dans ses épreuves est le geste
  que l'instrument récompense.
- Une citation est attribuée à l'identifiant que les parcours déclarent ; si
  une ADR déclare un homonyme, l'attribution peut se tromper. Unifier son
  espace de noms d'invariants est un geste de la juridiction, en amont de
  toute mesure.