---
title: "Concepts et cycles de vie de Kodama"
description: "Comprendre le modèle de Kodama : propriété des tenants, révisions du travail, espaces Git, exécutions immuables, tentatives, artefacts, validations et déploiements."
canonical_url: https://optimi.com/fr/docs/kodama/concepts
md_url: https://optimi.com/fr/docs/kodama/concepts.md
last_updated: 2026-10-23
---

# Concepts et cycles de vie

Kodama conserve **l’intention métier, le travail sur le code, l’exécution et les
décisions humaines** dans des enregistrements distincts. Comprendre ces
frontières évite de confondre une commande réussie avec un résultat métier
revu ou livré.

## Propriété : installation, tenant et projet

Une **factory** est une installation. Un **tenant** est une organisation qui y
possède des projets et des appartenances. Un **projet** regroupe le travail,
les paramètres du dépôt, les définitions de pipelines, la configuration et les
environnements de livraison.

La propriété tenant/projet accompagne les enregistrements, routes API,
événements, artefacts et identités d’exécution. Connaître un identifiant ne donne
pas accès à la ressource. Les organisations clientes d’une application produite
par Kodama sont des **tenants applicatifs**, distincts de ceux de l’usine.

En mode autonome, OIDC établit l’identité de la personne et les appartenances
locales établissent ses autorisations. Les rôles fixes se combinent par attribution :

| Rôle | Responsabilité principale |
| --- | --- |
| `admin` | Appartenances, paramètres du projet et gestion des identifiants |
| `analyst` | Spécifications et critères d’acceptation |
| `engineer` | Modifications techniques, espaces de travail, exécutions et livraison |
| `reviewer` | Décisions de validation humaine et finalisation métier |
| `viewer` | Lecture des ressources autorisées |

Un administrateur n’est pas automatiquement habilité à approuver une revue.
Une charge de travail reçoit des actions limitées à sa tentative, pas un rôle
humain. Un jeton valide nécessite encore une attribution courante pour
l’opération demandée.

## Les éléments de travail décrivent le résultat attendu

Un **élément de travail** (*work item*) contient un type, un titre, une
spécification, des critères d’acceptation et un état métier. Les stories, tâches
et défauts sont exécutables ; une epic regroupe du travail. Une carte représente
un élément sur un tableau. Le plan appartient à la spécification plutôt qu’à
une ressource de planification distincte.

Le cycle métier est le suivant :

**Le travail métier possède son propre cycle**

![Le travail passe de backlog à ready, active, review et done. La reprise et la réouverture reviennent à active ; le travail non terminé peut être annulé.](/diagrams/kodama/work-lifecycle-fr.svg)

*Un pipeline réussi apporte des preuves. Il ne décide pas de l’état métier de l’élément de travail.*

Toute entrée dans `active` vérifie la capacité de travail en cours, ou WIP.
Un élément bloqué conserve son état et continue à occuper son créneau actif.
Ses dépendances décrivent des prérequis métier, distincts des dépendances entre
étapes d’un pipeline. Un prérequis non satisfait empêche l’admission en travail
actif.

L’entrée en revue exige un candidat identifié et des preuves applicables.
La finalisation est une action explicite du reviewer sur ce sujet et les
exigences courantes. Les validations humaines d’un pipeline ont leur propre
cycle : leur approbation ne fait pas automatiquement passer le travail à `done`.

## Version de ressource et révision de contenu

Ces deux nombres répondent à des questions différentes :

| Valeur | Évolue lorsque | Usage |
| --- | --- | --- |
| `version` | Toute mutation de la ressource | Contrôle de concurrence avec `If-Match` ou `--if-version` dans le CLI |
| `contentRevision` | La spécification ou les critères d’acceptation changent | Figer les exigences évaluées par une exécution ou une revue |

Une transition peut incrémenter `version` sans changer `contentRevision`.
Une exécution fige la révision de contenu utilisée lors de son admission.
Modifier les exigences ne réécrit pas les exécutions ou décisions antérieures :
une nouvelle exécution évalue les nouvelles exigences. Après un conflit de
version, relisez la ressource et son historique avant de décider si votre
modification reste applicable.

## Les espaces de travail préservent la continuité du code

Un **espace de travail** (*workspace*) est le contexte source logique et durable
associé à un élément exécutable. Ses états sont `provisioning`, `available` et
`archived`. Sa branche et son commit accepté vivent dans Git ; sa propriété et
ses publications sont enregistrées dans PostgreSQL. Le système de fichiers
d’un conteneur en cours reste temporaire.

- Un **point de reprise** (*checkpoint*) est un commit conservé pour la reprise
  ou le travail ultérieur.
- Un **candidat** est le commit proposé à la revue et à la livraison.
- Chaque tentative utilise un clone privé, sans système de fichiers modifiable
  partagé avec une autre tentative.
- Les lecteurs utilisent un commit figé. `workspace.access: read` interdit la
  publication, mais permet les modifications temporaires des outils de build.
- Les écrivains sont ordonnés. La publication compare la pointe distante
  attendue avant de déplacer la branche : c’est un compare-and-swap Git.

Un push humain qui déplace la branche peut donc provoquer un conflit plutôt
qu’être écrasé. Une réponse de push perdue impose d’examiner la référence distante
avant de libérer le créneau d’écriture. Supprimer un Pod ne prouve pas que sa
publication est réglée. Archivage et restauration concernent le même espace
et n’effacent pas les commits conservés.

## Définitions, exécutions, étapes et tentatives

Une **définition de pipeline** est une version immuable d’un graphe orienté sans
cycle. L’enregistrement valide le document et conserve son empreinte canonique.
Un contenu identique retrouve la version existante.

Une **exécution** (*run*) applique une définition à des entrées, un commit source,
une révision de contenu et une configuration figés. Une **étape d’exécution**
représente un nœud du graphe. Une **tentative** exécute une fois un nœud
exécutable ; une nouvelle tentative autorisée ne réécrit pas la précédente.

| Ressource | États persistés |
| --- | --- |
| Exécution | `queued`, `running`, `succeeded`, `failed`, `cancelled` |
| Étape | `pending`, `running`, `succeeded`, `failed`, `skipped`, `cancelled` |
| Tentative | `running`, `succeeded`, `failed`, `cancelled` |
| Validation humaine | `pending`, `approved`, `rejected` |
| Déploiement | `pending`, `running`, `succeeded`, `failed` |

Attente, demande d’annulation, dépassement de délai et effet externe incertain
s’expriment par des motifs et horodatages, pas par des états supplémentaires.
Une annulation peut être acceptée pendant que l’exécution reste en cours :
observez-la jusqu’à sa résolution.

## Agents, preuves et validations humaines

Un **profil d’agent** sélectionne de façon immuable l’image du harness, les
instructions, le modèle, les outils et les limites prises en charge. L’étape
agent devient une exécution ordinaire du runtime. Les modèles et outils doivent
être approuvés par le projet et couverts par le catalogue de wrappers qualifiés
de l’installation. Un profil ne peut créer des droits que l’installation
n’accorde pas.

Un **artefact** est une sortie conservée : rapport, trace ou journal.
Une **preuve** associe l’artefact et sa provenance à l’évaluation d’un candidat
ou déploiement précis. Un code de sortie réussi sans les sorties obligatoires
peut encore échouer lors de la finalisation.

Une **validation humaine** (*gate*) demande une décision sur un sujet identifié.
Ce sujet lie le code, la révision de contenu, la définition et les preuves,
ainsi que la configuration du déploiement si nécessaire. La décision est
immuable. L’autorité courante de la personne et la validité du sujet sont
revérifiées avant consommation de l’approbation. L’attente reste en base sans
réserver de conteneur.

Un agent qui retourne `needs_input` échoue avec une question enregistrée.
Après clarification de la spécification, démarrez une nouvelle exécution ; il
n’y a pas de continuation implicite de conversation. De même, une validation
approuvée ou un résultat QA positif ne termine jamais automatiquement le travail
métier.

## Deux sens du mot environnement

**`KODAMA_ENV`** sélectionne les adaptateurs du processus : `development`, `test`
ou `production`. Un **environnement de livraison** est une cible nommée du
projet, par exemple un namespace de prévisualisation ou de staging, avec sa
configuration et ses identifiants limités à ce périmètre.

Un **déploiement** enregistre la cible, le code, l’image par empreinte, la
configuration et le résultat d’exécution. Une **prévisualisation** est un
déploiement temporaire. L’expiration demande un nettoyage par le cycle de
livraison ; elle n’efface ni l’historique du déploiement ni ses preuves.

Suite : **[Architecture](/fr/docs/kodama/architecture)** et
**[parcours développeur](/fr/docs/kodama/guide-developpeur)**.