Branches et propositions

Le schéma d'ontologie est versionné. Il existe une baseline publiée canonique — main — et chaque modification se fait sur une branche de proposition qui est examinée avant d'être fusionnée.

Pourquoi versionner

Le schéma est consommé par les workflows, les agents, la vue graphique, l'analyste et toute interface personnalisée. Un changement de schéma qui casse le type de propriété attendu par un workflow est exactement le type de modification que vous souhaitez voir en révision avant sa mise en production. Les propositions vous offrent cette révision sans ralentir le travail quotidien.

main

main est la baseline publiée. Depuis le plan de travail :

• main apparaît dans le sélecteur de branche comme valeur par défaut.
• main est en lecture seule. Vous pouvez naviguer, rechercher, traverser — vous ne pouvez pas modifier.
• Chaque consommateur (outils de workflow, vue graphique, analyste) lit depuis main par défaut.

Propositions

Une proposition est une branche depuis main avec un nom comme proposal/add-customer-tier ou proposal/rename-account-status. Les propositions peuvent :

• Ajouter de nouveaux types d'objets, types de liens, types d'actions, bindings.
• Modifier des types existants (changer un type de propriété, ajouter une propriété, modifier les règles d'identité).
• Supprimer des types (avec un chemin de migration).
• Mettre à jour les bindings (remapper des colonnes, changer de tables source).

Le plan de travail affiche le diff entre la proposition et main. Un réviseur peut voir exactement quels types ont changé et comment.

Le noyau prend également en charge une proposition ciblée, hors branche, pour une seule ressource de schéma. Il s'agit soit d'un upsert avec une charge utile de schéma entièrement validée, soit d'une rétraction épinglée à l'assertion active exacte qu'elle fermerait. Pour un upsert, un expectedAssertionId omis ou nul signifie « création uniquement » et échoue si la ressource existe déjà ; une chaîne signifie « remplacer exactement cette assertion examinée » et échoue si cette assertion n'est plus l'unique propriétaire actuel. Une rétraction n'est jamais résolue par son seul nom. Ces contrôles de propriétaire obsolète sont répétés dans la transaction de publication. L'approbation de l'une de ces propositions publie atomiquement une révision immuable ; son rejet enregistre la décision sans modifier le schéma publié.

Les lectures de propositions sont filtrées selon l'habilitation. Une proposition ne peut pas servir à abaisser la classification d'une modification de schéma : l'approbation conserve le marquage de la proposition, et une rétraction conserve également le marquage et la provenance de la cible.

Le SDK du noyau expose client.proposals.list(...) et client.proposals.get(...) pour ces enregistrements filtrés selon l'habilitation. Les listes prennent en charge les sélecteurs d'état, de type de schéma, de curseur et de limite. Les propositions associées à une branche sont délibérément exclues de cette surface générique. Leur association durable est l'identifiant exact de la branche enregistré par branch.declare, et elles ne sont exposées qu'à travers la vue de cette branche.

Cycle de vie d'une branche du noyau

Le noyau représente une branche de révision comme un objet gouverné épinglé à la révision publiée qui était courante lors de sa création. client.branches expose le cycle de vie complet :

1. create(...) crée une branche draft depuis la révision publiée courante.
2. declare(...) ajoute à ce brouillon des upserts ou rétractions de schéma validés. Une seule proposition ouverte peut cibler chaque combinaison de type de schéma et de nom de ressource.
3. submit(...) fait passer un brouillon à l'état in_review.
4. publish(...) accepte uniquement une branche in_review dont la base est toujours courante, applique atomiquement l'ensemble complet de ses propositions autorisées, publie une révision et ferme la branche à l'état published.
5. rebase(...) déplace la base d'un brouillon vers la révision publiée courante lorsque ses propositions ne recoupent pas les changements publiés. Les conflits sont signalés au lieu d'être résolus implicitement.
6. archive(...) ferme toute branche non archivée à l'état archived.

client.branches.list(...), .get(...) et .manifest(...) fournissent des lectures filtrées selon l'habilitation. L'appel de manifeste renvoie la superposition de la branche sans modifier main. Les méthodes de lecture du schéma acceptent un sélecteur branch à la place de revisionId ; fournir les deux est invalide.

Chacun des appels de cycle de vie ci-dessus est une action du noyau : elle ajoute au registre d'assertions et renvoie un reçu, tandis que la ligne lue par list(...), .get(...) et .manifest(...) est matérialisée ensuite par le projecteur d'état courant. Un create(...) suivi immédiatement d'un get(...) sur le nouveau extensions.branchId répond donc normalement NOT_FOUND : la branche existe, la projection n'a pas encore rattrapé son retard. Interrogez la lecture jusqu'à son apparition, dans la limite d'une échéance que vous choisissez, et ne traitez NOT_FOUND et PROJECTION_LAGGING comme un « redemandez » qu'à l'intérieur de cette attente bornée : en dehors, NOT_FOUND signifie aussi que l'habilitation de l'appelant ne domine pas le marquage de la ligne.

Cycle de vie

   ┌─────────┐    proposer    ┌──────────────┐
   │  main   │ ──────────────▶│  proposition │
   └─────────┘                └──────────────┘
        ▲                             │
        │ publier (remplace main)     │ révision
        └─────────────────────────────┘
                                     │
                                     ▼ archiver (abandonnée)
                                  [fin]

Ce que « publier » fait

La publication d'une proposition :

1. Valide la proposition par rapport au main actuel — signale les conflits.
2. Remplace atomiquement la baseline de main par la baseline de la proposition.
3. Réédite le tampon de version sur chaque binding, type d'action et type d'objet.
4. Émet un événement structuré pour les consommateurs en aval.
5. Enregistre un événement d'audit avec l'acteur, la proposition et les modifications publiées.

Après la publication, la branche de proposition est fermée. Les futures modifications repartent depuis le nouveau main.

Ce que « archiver » fait

L'archivage d'une proposition :

1. Marque la proposition comme archivée dans le catalogue.
2. La retire du sélecteur de branches actives.
3. Enregistre un événement d'audit.

Les propositions archivées sont conservées à des fins de conformité et d'audit, mais n'apparaissent pas dans la navigation normale. L'archivage est définitif ; pour poursuivre le travail, il faut créer une nouvelle branche à partir de la révision publiée appropriée.

Modifications simultanées

Plusieurs propositions peuvent être en cours simultanément. L'étape de publication effectue une vérification des conflits — si une deuxième proposition touche un type qu'une première proposition a déjà publié, le réviseur de la deuxième proposition voit le conflit et décide comment le résoudre.

Autorisation

La publication ou le rejet d'une proposition exige une révision indépendante. La personne qui a rédigé une proposition ne peut pas la décider, même si elle est administratrice de l'espace de travail ou de l'organisation. Un autre réviseur éligible peut la décider conformément à la politique de l'espace de travail. Cette séparation s'applique à l'approbation comme au rejet ; aucune solution de repli générique n'est accordée aux automatisations.

Voir aussi

• Concepts → Branches — où les branches s'inscrivent dans les cinq couches.
• Journalisation des audits — chaque publication et archivage est journalisé.
• SDK d'authoring → Ontologies — les packs se déploient sur main par défaut ; les mises à jour de packs arrivent via des propositions.