spec: schéma du manifeste normatif de surface

[atlas-by-clodocapeo]

1. Canonical provenance

• ADR : ZabLaboratory/QueryMe · docs/adr/001-positionnement-et-architecture.md · Status: accepted · Decided: 2026-08-15 · Deciders: @ClodoCapeo
• Révision ADR : celle mergée par ec54f54b1, non amendée. base_revision : main 17e78871d
• ID provisoire : QM-P0-01 · Phase : P0
• Work unit amont : QUERYME-ADR-001-ISSUES (Atlas — découpe, ancre [anchor] ADR 001 persistence lease #6) · aval : QM-P0-02, QM-P0-05, QM-P1-01
• Rapport de routage : proposition Atlas du 2026-08-15 sur [anchor] ADR 001 persistence lease #6, graphe validé nommément par Eleven ; création effective sur validation nommée, issue par issue (agent-runtime.md §6)

2. Objective

Le manifeste normatif de surface existe comme schéma formel, typé et source-agnostique : une surface d'accès candidate s'exprime intégralement dedans, ou elle n'est pas exprimable.

3. Work graph

• continues: —
• depends_on: —
• parallelization_group: p0-spec
• initial_state: ready
• recommended_role: forge
• required_agent_reports: forge, probe

4. Owned scope

• Schéma formel du manifeste (JSON Schema normatif + modèles Pydantic V2 de référence), versionné, avec un identifiant de version du schéma distinct de la version du paquet.
• Relations : identifiant, discriminant de cloisonnement déclaré (I1), sous-clé de partition optionnelle avec le nom de la revendication de justificatif dont elle dérive (§3.4), deux limites de débit — extraction et mutation — obligatoires (I9).
• Champs : déclaration opt-in, type, appartenance à une relation (I4).
• Opérations : operation_id, paramètres typés, projection déclarée, relations déclarées modifiées, pré/post-conditions pour les écritures (I6), sous-ensemble des paramètres marqués porteurs de coût, et deux expressions de coût — extraction et mutation (§3.3).
• Opérateurs : ensemble fermé admissible dans les prédicats, aucune forme libre (I5).
• Règles de bonne formation structurelles exprimées dans le schéma lui-même : un manifeste muet sur le cloisonnement d'une relation atteignable, sur l'une des deux limites de débit, ou sur une post-condition d'écriture, ne valide pas (§3.2, « l'obligation de déclarer est toujours structurelle »).
• Reprise du vocabulaire de QueryDescriptor comme point de départ (§3.8, « Devenir de l'existant »), et retrait explicite de SchemaDescriptor / _schema et de la sémantique de compile_query() de la nouvelle ligne.
• Trois exemples de manifeste bien formés, versionnés avec le schéma, servant de fixtures aux issues avales.

5. Exclusions

• Aucun vérificateur d'invariant : les règles qui exigent une analyse de graphe (atteignabilité I1, énumération rôles×relations I2, calcul des deux graphes) sont QM-P0-02. Ici, seules les contraintes exprimables dans le schéma lui-même.
• Aucune compilation : ni SQL, ni fonctions de coût compilées, ni artefact — P1 (QM-P1-01, QM-P1-05).
• Aucun format d'artefact signé (attestation, autorisation, allocation) — QM-P0-03.
• Aucun seuil, aucune borne, aucune politique : les valeurs admissibles des limites de débit et la proportion maximale d'opérations budgétées appartiennent au profil — QM-P0-04. Le schéma déclare qu'une limite existe, jamais ce qu'elle vaut.
• Aucun corpus de conformité — QM-P0-06. Les trois exemples livrés ici sont des fixtures de bonne formation, pas les « ≥3 configurations conformes de référence » de RC-2.
• Aucune modification de la ligne 0.x : v0.2.2 est gelé (§3.8), les six consommateurs ne reçoivent rien.
• Confusion voisine à écarter : ce n'est pas une reprise de SchemaDescriptor. La direction de la vérité s'inverse — la forme est déclarée en amont, jamais interrogée à l'exécution (§4).

6. Inputs and outputs

Entrées — ADR §3.2 (I1..I9, obligation de déclarer structurelle), §3.3 (deux expressions de coût, paramètres porteurs de coût, operation_id comme identité de forme), §3.4 (sous-clé de partition, deux limites par relation), §3.8 (devenir de QueryDescriptor, SchemaDescriptor, compile_query()). État existant : src/queryme/descriptor.py sur v0.2.2.

Sorties — le schéma normatif versionné, les modèles Pydantic de référence, les trois manifestes-fixtures, et la note de correspondance QueryDescriptor → vocabulaire du manifeste (ce qui est repris, ce qui est abandonné et pourquoi).

7. Acceptance criteria

• Le schéma valide les trois manifestes-fixtures et les rejette dès qu'un champ obligatoire est retiré — un cas de retrait par champ obligatoire, exécuté en CI.
• Un manifeste déclarant une relation atteignable sans discriminant de cloisonnement est invalide contre le schéma.
• Un manifeste déclarant une relation atteignable avec une seule des deux limites de débit est invalide — deux tests, un par axe manquant.
• Un manifeste déclarant une opération d'écriture sans post-condition est invalide.
• Un manifeste déclarant une opération sans les deux expressions de coût est invalide — les deux sont exigées pour toute opération, bornée comme budgétée (§3.3, propriété normative 1).
• Un manifeste déclarant une sous-clé de partition sans nommer la revendication de justificatif dont elle dérive est invalide.
• Un manifeste employant un opérateur hors de l'ensemble fermé est invalide.
• Aucun champ du schéma ne porte de seuil, de borne ni de valeur de politique — vérifié par revue et par grep sur le schéma (contrat de frontière avec QM-P0-04).
• SchemaDescriptor, l'endpoint _schema et la sémantique d'appel de compile_query() n'apparaissent nulle part dans la nouvelle ligne — grep en CI.
• mypy --strict et ruff verts ; uv lock --check vert.

8. Expected evidence

Fichier de schéma et son empreinte ; sortie de la suite de validation listant chaque cas de rejet nommément (un test = un champ obligatoire) ; les trois fixtures ; la note de correspondance QueryDescriptor ; SHA du commit signé et lien du run CI vert.

9. Risks and rollback

Risque principal — un schéma trop permissif reporte silencieusement sur les vérificateurs (QM-P0-02) une contrainte que §3.2 exige structurelle ; la faute ne se voit qu'au premier manifeste vulnérable accepté, c'est-à-dire au corpus (QM-P0-06), très en aval. Contre-mesure : chaque obligation de §3.2 est tracée à la ligne de schéma qui la porte ou explicitement déléguée à QM-P0-02 dans la note de correspondance — pas de troisième cas.

Rollback — tant que QM-P0-02 et QM-P0-06 ne sont pas mergés, le revert du commit de schéma est suffisant et sans état résiduel. Après eux, un revert nu orpheline les vérificateurs et le corpus : la procédure est alors revert du schéma puis ré-exécution du corpus pour constater l'état, et non l'inverse. Aucun consommateur de production n'est exposé à ce rollback : v0.2.2 est gelé et ne reçoit rien de cette ligne.

10. ADR clauses and invariants covered

§3.2 — obligation de déclarer, structurelle dans les trois régimes ; part déclarative d'I1, I4, I5, I6, I9. §3.3 — « Fonctions de coût — une par axe » (déclaration des deux expressions et des paramètres porteurs de coût), « Identité de forme » (operation_id). §3.4 — « Granularité de l'identité » (sous-clé issue du justificatif), « Déclaration » (deux limites par relation). §3.8 — « Devenir de l'existant » (les trois décisions sur le scaffold). §3.9 — P0, « Schéma du manifeste normatif de surface ».

---

Ancre du cycle : #6 (lien, pas dépendance bloquante).