# Métadonnées de l'application Trois propriétés racines scalaires identifient votre application : `name`, `version` et `description`. Seule `name` est obligatoire. Ensemble, elles ancrent le registre de versions immuable de Sovrium et sa détection de dérive du schéma. ```yaml name: '@acme/crm' version: 2.1.0 description: 'A CRM workspace for managing contacts, deals, and tasks.' ``` ## `name` Le nom de l'application suit les conventions de nommage des paquets npm. Il est en minuscules, compatible avec les URL et constitue la seule propriété obligatoire de tout le schéma. | Contrainte | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | Motif | `^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$` — lettres minuscules, chiffres, traits d'union, points, tildes. | | Longueur | 1 à 214 caractères (préfixe `@scope/` inclus s'il y a une portée). | | Début | Ne peut pas commencer par un point ou un tiret bas ; aucune espace en début ou fin. | | Avec portée | Les noms à portée de style npm sont autorisés : `@scope/name` (par ex. `@acme/dashboard`). | ```yaml # Valid names name: my-app name: task-tracker-v2 name: '@acme/dashboard' ``` ## `version` Une chaîne Semantic Versioning 2.0.0 ([semver.org](https://semver.org)). Optionnelle, mais recommandée — lorsqu'elle est présente, elle alimente le registre de versions décrit ci-dessous. | Règle | Description | | -------------------- | -------------------------------------------------------------------------------------- | | Format | `MAJOR.MINOR.PATCH` (par ex. `1.0.0`). Chaque composant est un entier non négatif. | | Pas de 0 initial | `01.0.0` est rejeté — les composants de version ne doivent pas avoir de zéros en tête. | | Pré-version | Suffixe optionnel avec trait d'union : `1.0.0-alpha`, `1.0.0-beta.1`, `2.0.0-rc.1`. | | Métadonnées de build | Suffixe optionnel avec signe plus : `1.0.0+build.123`, `1.0.0-alpha+001`. | ```yaml version: 1.0.0 # Stable release version: 2.0.0-beta.1 # Pre-release version: 1.0.0+build.42 # Build metadata ``` ## `description` Une description sur une seule ligne affichée dans l'interface d'administration et les métadonnées. | Contrainte | Description | | ------------ | --------------------------------------------------------------- | | Format | Une seule ligne — les sauts de ligne (`\n`, `\r`) sont rejetés. | | Longueur max | 2000 caractères. | | Unicode | Prise en charge complète d'Unicode, y compris les emojis. | ```yaml description: 'Full-featured e-commerce platform with cart, checkout & payment processing' ``` ## Historique des versions Chaque application Sovrium conserve un **registre de versions immuable** — un journal d'audit en ajout seul des instantanés du schéma. Chaque publication réussie ajoute une ligne contenant l'instantané encodé du schéma, une somme de contrôle SHA-256 de cet instantané, et la `source` qui l'a produit. Restaurer une version antérieure copie son instantané dans une _nouvelle_ ligne ; l'historique n'est jamais modifié. ### Les quatre transports Une modification du schéma peut arriver par l'un des quatre transports. Chaque transition ajoute exactement une ligne au registre, et la colonne `source` enregistre quel transport l'a produite. | Transport | Valeur `source` | Comment une modification arrive | | --------------------- | --------------- | ------------------------------------------------------------------------------------------------ | | **Fichier de config** | `config-file` | `sovrium start app.yaml` au démarrage, ou `sovrium reload` pour un serveur en cours d'exécution. | | **Variable d'env** | `env` | La variable d'environnement `APP_SCHEMA` (JSON/YAML en ligne ou instantané d'URL distante). | | **API d'admin** | `api` | L'API HTTP d'administration (`POST /api/admin/schema/draft/publish`). | | **MCP** | `mcp` | Un outil d'édition de schéma MCP (`{app}_schema_draft_publish`). | Une cinquième `source`, `restore`, marque les lignes créées par la restauration d'une version antérieure. Les sommes de contrôle sont autonomes (chaque ligne hache son propre instantané, pas celui d'un parent), ce qui rend sûre l'élagage des lignes intérieures. ## Détection de dérive du schéma Comme le schéma actif peut être modifié à l'exécution (via l'API d'admin ou MCP) alors qu'un `config-file` reste sur le disque, l'application active peut **dériver** de son fichier source. Sovrium calcule une posture de dérive à partir du registre et l'expose pour que l'outillage puisse avertir avant d'écraser un travail. | Statut de dérive | Signification | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `in-sync` | La version active provient d'un transport `config-file`/`env` — l'application en cours correspond à sa source. | | `drifted-from-file` | La version active provient de `api`/`mcp`/`restore` — l'application active a été modifiée à l'exécution et ne correspond plus au fichier. | | `file-ahead` | La somme de contrôle normalisée du fichier sur le disque a changé — le fichier source est désormais en avance sur l'application active. | :::callout **`sovrium reload` respecte la dérive.** Recharger un serveur lancé par `config-file` sonde d'abord le statut de dérive actif. Si l'application active est en `drifted-from-file`, le rechargement est refusé sauf si vous passez `--force` — empêchant un écrasement accidentel des modifications d'exécution par un contenu de fichier obsolète. ::: ## Obsolescence des brouillons L'édition à l'exécution se fait sur un **brouillon modifiable** — une copie de travail unique dérivée de la version active. Le brouillon enregistre la `baseVersion` dont il est issu, qui sert à la fois de jeton de concurrence optimiste à la publication et d'**ancre d'obsolescence**. Un brouillon devient **obsolète** dès que `draft.baseVersion` ne correspond plus au numéro de version active. Cela se produit lorsqu'un autre administrateur publie, ou lorsqu'un rechargement `config-file`/`env` déplace la base sous un brouillon ouvert. | Opération sur un brouillon obsolète | Autorisée ? | | ----------------------------------- | -------------------------------------------- | | Aperçu / validation / édition | Oui | | Publication | Non — bloquée jusqu'au rebasage du brouillon | Pour lever l'obsolescence, **rebasez** le brouillon : repointez sa `baseVersion` vers la version active, en laissant le contenu du brouillon intact. Il n'y a pas de fusion au niveau des champs — la prochaine publication est une opération d'instantané complet, le dernier auteur l'emportant, cohérente avec le système de schéma instantané-atomique de Sovrium. ## Étapes suivantes - [Vue d'ensemble du schéma](/fr/docs/overview) — toutes les propriétés racines en un coup d'œil. - [Fichiers de configuration](/fr/docs/configuration-files) — comment les transports `config-file` et `env` chargent votre application. - [Référence CLI](/fr/docs/cli) — `sovrium reload` et la gestion de la dérive.