Ramener un workspace Carbon Forge à un cut

Aussi en: English, Español, Português, 日本語, Deutsch, 한국어, 简体中文, Italiano, हिन्दी · Tous les guides en français

Transparence : nous développons Carbon Forge chez 100monkeys.ai ; lisez donc ceci comme le récit de son fabricant. Ce guide a été rédigé par l'un de nos agents d'IA à partir de la documentation publique (en anglais), principalement la page Snapshots du catalogue et Working in lanes, et relu par l'entreprise ; cette édition française est une traduction du guide original en anglais. Les noms d'outils, les arguments et les phrases citées viennent de la documentation ; les citations restent en anglais, avec la traduction à côté. La documentation ne donne pas de JSON complet pour ces appels, donc nous n'en montrons pas. Là où la documentation laisse une question ouverte, la dernière section le dit.

Ce que sont un snapshot et un cut

Un snapshot enregistre la révision actuelle de chaque page, atome, arbre de code et entrée de bibliothèque, ainsi que les patchs vivants de chaque lane ouverte, "as one sealed manifest of ids and hashes chained to the previous snapshot." (sous la forme d'un manifeste scellé d'identifiants et de hachages, chaîné au snapshot précédent.) Il ne contient que "ids and hashes only, never a body or a blob's bytes" (des identifiants et des hachages, jamais un contenu ni les octets d'un blob), et coûte donc peu. Un cut est un nom pour un snapshot, et "it never moves." (il ne bouge jamais.) Snapshots et cuts sont en ajout seul : "the database refuses to change or remove either while the workspace exists." (la base refuse de modifier ou de supprimer l'un ou l'autre tant que le workspace existe.)

Étape 1. Couper l'état que vous voudrez peut-être retrouver

Avant un changement important ou risqué, appelez snapshots.cut avec un name. Un nom compte de 1 à 128 lettres, chiffres, points, tirets et soulignés, et commence par une lettre ou un chiffre ; les exemples de la documentation sont stable, v0.9 et release-2026.10.16. Réutiliser un nom est refusé, parce qu'un cut ne bouge jamais : le refus dit de nommer le nouvel état avec un nouveau cut. Couper demande le rôle editor.

Étape 2. Retrouver le cut plus tard

cuts.list renvoie les cuts du workspace, du plus récent au plus ancien, chacun avec le snapshot qu'il nomme. snapshots.get avec cut renvoie un snapshot : son condensé, son sceau, son prédécesseur, ses compteurs et les lanes ouvertes qu'il a enregistrées. Ce sont deux lectures accessibles au rôle viewer.

Étape 3. Lire ce qui a changé depuis le cut

cuts.notes liste chaque changeset intégré après une borne jusqu'à une autre, dans l'ordre d'intégration, groupé par le premier mot de son intent. Son to doit être un cut ou un identifiant de snapshot ; pour comparer le cut avec le workspace tel qu'il est maintenant, appelez d'abord snapshots.cut sans nom, puis passez votre cut comme from et l'identifiant du nouveau snapshot comme to. Ajoutez path_glob pour ne garder que les changesets qui ont touché les chemins qui vous intéressent. Chaque changeset donne son intent, son acteur, la lane d'où il a été intégré et les chemins touchés, ce qui suffit en général pour voir quel travail vous êtes sur le point d'annuler.

Étape 4. Regarder une entité telle que le cut la garde

snapshots.materialize avec cut renvoie une page du manifeste du cut, chaque entrée avec ces champs :

kind, entity_id, revision_id, content_hash, seal_hash, path, title

Ajoutez entity_id et il renvoie cette entité à la révision que nomme le cut : le contenu et les métadonnées d'une page, le contenu d'un atome, les entrées d'un arbre, le hachage d'une entrée de bibliothèque. "The same snapshot answers the same every time." (Le même snapshot répond la même chose à chaque fois.) Une entrée dont la révision a été purgée depuis répond purged et ne porte aucun contenu.

Étape 5. Vérifier qui peut revenir en arrière

snapshots.revert demande le rôle admin, et parmi les préréglages de jeton il ne figure que dans full : un agent qui tient un jeton SCM agent ou SCM release ne peut pas l'appeler. Sur un workspace dont le trunk est protégé, un retour en arrière qui écrirait un arbre de code ou une entrée de bibliothèque, ou une page ou un atome là où les pages sont aussi protégées, est refusé avant toute écriture : workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.

Étape 6. Revenir au cut

Appelez snapshots.revert avec cut et intent, le message du changeset, de 1 à 4 096 caractères. "Revert is forward only: nothing is removed or rewritten." (Le retour en arrière ne va que vers l'avant : rien n'est supprimé ni réécrit.) Chaque entité dont le contenu diffère de celui du cut reçoit une nouvelle révision qui porte le contenu du cut, le tout dans un seul changeset scellé. Une révision restaurée de page ou d'atome porte le commentaire Restored from cut <cut> (R#<revision>). Là où le cut a enregistré chemins et titres, une page renommée retrouve son ancien chemin et son ancien titre, et le chemin qu'elle quitte continue de rediriger vers elle. Puis un nouveau snapshot est coupé, marqué du cut vers lequel on est revenu.

Étape 7. Lire la réponse

La réponse est le nouveau snapshot, avec ces champs :

snapshot, cut, changeset_id, restored, unchanged, extraneous, collisions

Chaque ligne de restored est :

kind, entity_id, from_revision_id, new_revision_id

unchanged est un compteur. collisions liste les entités dont l'ancien chemin est maintenant tenu par une autre page ou un autre atome vivant : là, "the body and metadata alone are restored, and nothing moves." (seuls le contenu et les métadonnées sont restaurés, et rien ne bouge.) Deux refus n'écrivent rien du tout : un cut qui nomme une révision purgée, ou une entité qui est maintenant à la corbeille, que le refus vous dit de restaurer d'abord ; et un cut auquel le workspace correspond déjà, qui reçoit la réponse Every entity already holds what cut <cut> names; nothing changes.

Étape 8. Traiter ce que le retour en arrière laisse en place

"Entities created after the cut are reported as extraneous and left as they are." (Les entités créées après le cut sont signalées comme extraneous et laissées telles quelles.) Une page créée par l'agent de la nuit est toujours là après le retour en arrière ; décidez pour chacune si elle reste. Comme le retour en arrière est un changeset comme un autre, le travail de la nuit et son annulation restent tous deux lisibles dans l'historique, et cuts.notes lancé de part et d'autre du retour montre les deux. Pour une seule intégration plutôt qu'un workspace entier, changesets.revert annule un seul changeset, et il prend lane : sur un trunk protégé, il peut donc être déposé sur une lane et intégré depuis celle-ci.

Pour nommer des releases avec des cuts et les publier, lisez notre guide Créer une release dans Carbon Forge et la pousser sur GitHub.

Ce que la documentation laisse sans réponse

• Comment ramener un trunk protégé à un cut. snapshots.revert ne prend pas de lane, et la documentation ne déroule pas le retour d'un cut entier par une lane.
• Comment supprimer en une étape les entités extraneous. La documentation les signale et s'arrête là.
• Ce que contient cut dans la réponse d'un retour en arrière. D'après la description de la documentation, le nouveau snapshot est coupé sans nom propre, et le champ n'est pas expliqué pour cet appel.
• Un exemple complet. Le catalogue donne chaque argument mais aucun exemple d'appel ni de réponse pour ces sept outils.