build · gpt-5.3-codex 

PD-281 — Specification canonique du Z-lint: discrimination state machine vs type/category et completion des types Z¶

1. Objectif¶

La story PD-281 doit contractualiser un comportement de verification formelle ou:

• le generateur Z-lint distingue strictement les enums de state machine (eligibles au check Anchor enum) des enums de classification (non eligibles);
• les types Z manquants pour les vraies machines a etats soient presents dans les fichiers .zed cibles;
• la regeneration du pipeline rende un resultat deterministe et conforme: verify-norm.sh en succes sur 9/9 normes, sans faux positifs Anchor enum.

2. Perimetre / Hors perimetre¶

Inclus¶

• Regles de discrimination entre colonnes status et colonnes type/category.
• Liste contractuelle des entites/colonnes explicitement exclues du check Anchor enum.
• Presence contractuelle des types Z manquants dans les fichiers .zed identifies.
• Regeneration des artefacts _generated-z-lint.yaml et verification de resultat global.
• Preservation des checks existants hors scope Anchor enum (notamment Anchor entity).

Exclu¶

• Toute modification des entites TypeORM backend.
• Ajout de nouvelles normes dans le pipeline.
• Refonte du systeme de verification formelle.
• Modification du principe du check Anchor entity (mapping entite -> schema Z).
• Definition metier detaillee des transitions de lifecycle (hors perimetre de cette story).

3. Definitions¶

• Anchor enum check: controle Z-lint qui exige un type Z ancre pour une entite portant un enum de machine a etats.
• State machine: enum de lifecycle porte par une colonne status (ou mapping explicite dans _z_enum_type_mappings).
• Type/category: enum de classification (ex: event_type, envelope_type, document_category, validation_status) sans exigence d’ancrage <entity>_state.
• Type Z: type enum declare dans un fichier .zed.
• Faux positif: echec Z-lint declenche alors que la colonne ne represente pas une machine a etats.
• Vrai gap: absence effective d’un type Z requis pour une colonne status.

4. Invariants (non negociables)¶

5. Flux nominaux¶

5.1 Modele de donnees contractuel (formats et contraintes)¶

Defini une seule fois dans cette section; toute autre section y fait reference.

Regle de referencement: toute mention de ces donnees ailleurs dans la spec doit etre interpretee selon ce tableau (§5.1), sans redefinition.

5.2 Flux nominal A — Discrimination des enums dans la generation Z-lint¶

1. Le systeme lit les faits extraits et identifie chaque couple (entity_name, column_name) conforme §5.1.
2. Pour chaque couple:
3. si column_name == status ou mapping explicite present dans _z_enum_type_mappings, alors le check Anchor enum est produit;
4. sinon, aucun check Anchor enum n’est produit pour ce couple.
5. Les exclusions explicites suivantes sont obligatoires (non regressives):
6. anchor_batch_event.event_type
7. key_envelope.envelope_type
8. legal_access_event.event_type
9. legal_mandate.validation_status
10. deposit.document_category
11. Le resultat genere respecte l’idempotence (INV-281-05).

5.3 Flux nominal B — Completion des types Z requis¶

Les declarations suivantes doivent exister dans les fichiers cibles, avec valeurs strictement conformes:

Regle conditionnelle:

• si deposit.status existe comme colonne lifecycle dans la source de verite, alors DepositStatus devient obligatoire dans NF_Z42_013.zed et ISO_14641.zed;
• sinon, DepositStatus est interdit comme exigence de cette story.

5.4 Flux nominal C — Regeneration et verification globale¶

1. Les configurations _generated-z-lint.yaml sont regenerees.
2. La verification complete verify-norm.sh est executee sur les 9 normes cibles.
3. Le verdict attendu est SUCCESS global, sans echec Z-lint.
4. AUDIT-SYNTHESIS.md doit afficher Z-lint 9/9 PASS.

5.5 Transitions inverses et etats terminaux¶

• Perimetre PD-281: ancrage de types Z et regles de lint, sans specification des transitions metier internes de chaque enum.
• Aucune transition retour applicable dans le perimetre de cette story.
• Pour les etats terminaux metier (ex: DESTROYED), la politique de transition sortante est hors perimetre de PD-281 et doit etre specifiee dans la norme metier source correspondante.

5bis. Diagrammes¶

5bis.1 State diagram — TimestampBatchStatus (INV-281-03)¶

Machine a etats declaree dans RFC_3161.zed (cf. §5.3).

stateDiagram-v2
    [*] --> OPEN
    OPEN --> SEALED
    SEALED --> TIMESTAMPED
    OPEN --> FAILED
    SEALED --> FAILED
    TIMESTAMPED --> [*]
    FAILED --> [*]

5bis.2 State diagram — AnchorBatchStatus (INV-281-03)¶

Machine a etats declaree dans NF_Z42_013.zed et ISO_14641.zed (cf. §5.3).

stateDiagram-v2
    [*] --> PENDING
    PENDING --> BUILDING
    BUILDING --> SUBMITTED
    SUBMITTED --> PENDING_FINALITY
    PENDING_FINALITY --> FINALIZED
    PENDING --> FAILED
    BUILDING --> FAILED
    SUBMITTED --> FAILED
    PENDING_FINALITY --> FAILED
    FINALIZED --> [*]
    FAILED --> [*]

5bis.3 State diagram — LegalReKeyStatus (INV-281-03)¶

Machine a etats declaree dans PV_PRE.zed (cf. §5.3).

stateDiagram-v2
    [*] --> ACTIVE
    ACTIVE --> REVOKED
    ACTIVE --> EXPIRED
    ACTIVE --> COMPLETED
    REVOKED --> DESTROYED
    EXPIRED --> DESTROYED
    COMPLETED --> DESTROYED
    DESTROYED --> [*]

5bis.4 Sequence diagram — Pipeline de discrimination et verification (INV-281-01, INV-281-02, INV-281-05, INV-281-06)¶

Flux nominaux A + C : generation Z-lint avec discrimination puis verification globale.

sequenceDiagram
    participant O as Orchestrateur (verify-norm.sh)
    participant E as extract-facts.py
    participant G as Generateur Z-lint
    participant Z as Fichiers .zed
    participant C as Configs _generated-z-lint.yaml
    participant A as AUDIT-SYNTHESIS.md

    O->>E: Extraction des faits (entites, colonnes)
    E-->>O: Couples (entity_name, column_name)

    loop Pour chaque couple
        O->>G: Soumet (entity_name, column_name)
        alt column_name == "status" OU mapping _z_enum_type_mappings
            G->>C: Produit check Anchor enum (INV-281-01)
        else Colonne classification (event_type, envelope_type, etc.)
            G-->>G: Aucun check Anchor enum (INV-281-02)
        end
    end

    G->>C: Ecriture _generated-z-lint.yaml (idempotent — INV-281-05)

    O->>Z: Verification types Z requis (INV-281-03)
    Z-->>O: Presence/absence des types declares §5.3

    O->>C: Verification 9 normes
    C-->>O: Verdict par norme

    alt 9/9 PASS (INV-281-06)
        O->>A: Ecriture Z-lint 9/9 PASS
    else Echec >= 1 norme
        O->>A: Ecriture Z-lint FAIL + motifs
    end

6. Cas d’erreur¶

7. Criteres d’acceptation (testables)¶

8. Scenarios de test (Given / When / Then)¶

• SCN-281-01 (exclusion classification)
  Given un fait anchor_batch_event.event_type conforme §5.1
  When la generation Z-lint est executee
  Then aucun Anchor enum check n’est genere pour ce couple.

• SCN-281-02 (inclusion state machine)
  Given un fait anchor_batch.status conforme §5.1
  When la generation Z-lint est executee
  Then un Anchor enum check est genere pour anchor_batch_state (ou mapping explicite).

• SCN-281-03 (type Z manquant)
  Given timestamp_batch.status present et TimestampBatchStatus absent de RFC_3161.zed
  When verify-norm.sh est execute
  Then la verification echoue avec motif type Z manquant.

• SCN-281-04 (type Z present)
  Given TimestampBatchStatus present avec valeurs exactes
  When verify-norm.sh est execute
  Then le controle associe passe.

• SCN-281-05 (idempotence)
  Given un meme jeu d’entree
  When la generation + verification est executee deux fois
  Then le verdict global et le statut Z-lint sont identiques.

• SCN-281-06 (condition DepositStatus)
  Given deposit.status existe dans la source de verite
  When verification des .zed est faite
  Then DepositStatus est requis dans NF_Z42_013.zed et ISO_14641.zed.

• SCN-281-07 (condition inverse DepositStatus)
  Given deposit.status n’existe pas
  When verification des .zed est faite
  Then aucune exigence DepositStatus n’est appliquee.

9. Hypotheses explicites¶

10. Points a clarifier¶

10.1 Contraintes techniques (stack reelle du projet cible)¶

• Projet cible: ProbatioVault-doc (scripts/formal specs).
• Stack constatee sur ce perimetre: Shell (orchestration), Python 3 (extract-facts.py), fichiers YAML (_generated-z-lint.yaml), specs formelles .zed, documentation Markdown.
• Clarification requise: la matrice stack standard fournie ne liste pas ProbatioVault-doc; confirmer que cette stack documentaire est la reference contractuelle pour PD-281.

10.2 Bornes numeriques obligatoires¶

10.3 SLA temporels¶

• Aucune transition temporelle identifiee.

10.4 Contraintes inter-modules¶

• Aucune contrainte inter-module applicable.

10.5 Migration DDL¶

• Aucune strategie de migration DDL applicable (aucune modification de colonne base de donnees dans ce perimetre).

10.6 Atomicite multi-composant¶

• Aucune exigence d’atomicite DB + queue applicable dans ce perimetre documentaire.

10.7 Invariant envelope encryption¶

• Hors perimetre pour PD-281 (aucun artefact cryptographique temporaire manipule dans ce module documentaire).

10.8 Donnees manquantes a confirmer¶

• Reference epique exacte (valeur fournie vide).
• Existence effective de deposit.status dans la source de verite.
• Liste definitive des 9 normes du run courant (noms exacts).

References¶

• Epic : A clarifier (reference epique non fournie)
• JIRA : PD-281
• Repos concernes : ProbatioVault-doc
• Documents associes : Expression de besoin PD-281; AUDIT-SYNTHESIS.md; fichiers .zed cibles; configs _generated-z-lint.yaml; script verify-norm.sh; script extract-facts.py; learnings PD-250, PD-37, PD-35.