Une branche par exécution d’agent
Créez une branche de la base avant l’exécution d’un agent, laissez l’agent écrire dans la copie, relisez ce qui a changé, puis fusionnez-la ou jetez-la. Créez une branche d’un instant passé pour récupérer ce qu’une exécution a cassé.
Construit avec la timeline de barrel : barrel:branch/3, merge/1 et delete/1, les mêmes opérations en REST et sous forme des outils MCP branch_create et merge.
Le problème
Laisser un agent modifier des données en production est risqué, et copier une base pour lui donner un bac à sable est lent et vous laisse retrouver les différences à la main. Quand une exécution tourne mal, vous voulez les données telles qu’elles étaient avant son début.
Comment les pièces s’assemblent
-
Votre orchestrateur
- Avant l’exécution branch/3, une branche en temps constant
- L’agent n’écrit que dans la branche
- branch/3
-
Barrel
- main données de production, intactes pendant l’exécution
- run_42 la branche : une base ordinaire
- changes, puis merge
-
Relecture
- Changements depuis la branche ce qu’a fait l’exécution
- merge/1 ou delete/1 la garder ou la jeter
La branche partage ses fichiers avec main en copie à l’écriture, jusqu’à ce que l’un des deux côtés compacte. Ses écritures portent leur propre identifiant de source, ce qui permet à une fusion de distinguer ce que la branche a fait de ce dont elle a hérité.
Le construire
Cinq étapes. Les exemples REST et MCP utilisent une base nommée demo et une branche demo-exp, comme dans l’exécution enregistrée.
-
Créer une branche avant l’exécution
Une branche est un point de contrôle des stockages par liens physiques : la créer coûte autant quelle que soit la taille. Une branche en mode enregistrement reçoit son propre stockage vectoriel, reconstruit à partir des embeddings déjà stockés dans les documents.
{ok, Run} = barrel:branch(Db, run_42, #{vectordb => #{db_path => "data/run_42_vec"}}).curl -X POST localhost:8080/db/demo/_timeline/branch \ -H 'content-type: application/json' \ -d '{"name":"demo-exp"}'{"jsonrpc":"2.0","id":20,"method":"tools/call", "params":{"name":"branch_create", "arguments":{"db":"demo","name":"demo-exp"}}}HTTP/1.1 201 Created {"ok":true,"parent":"demo","fork_hlc":"AAABobh22gAAAAAA", "branch":"demo-exp"} -
Laisser l’agent écrire dans la branche
La branche accepte lectures, écritures, requêtes et recherche comme n’importe quelle base. Donnez son nom à l’agent ;
mainne change pas.{ok, D} = barrel:get_doc(Run, <<"kb:201">>), {ok, _} = barrel:put_doc(Run, D#{<<"title">> => <<"Export invoices and credit notes">>}).curl -X PUT localhost:8080/db/demo-exp/doc/e \ -H 'content-type: application/json' \ -d '{"kind":"note","title":"on branch"}' -
Relire ce que l’exécution a changé
Lisez les changements de la branche depuis l’instant de sa création.
fork_hlcest un curseur de changements.{ok, #{fork_hlc := Fork}} = barrel:info(Run), {ok, Changed, _Last} = barrel:changes(Run, Fork).FORK=AAABobh22gAAAAAA # fork_hlc from step 1 curl "localhost:8080/db/demo-exp/changes?since=$FORK" -
La fusionner, ou la jeter
Une fusion n’envoie que les documents modifiés par la branche. Les modifications faites entre-temps sur
mainaux mêmes documents deviennent des conflits ordinaires. Une nouvelle fusion plus tard est incrémentale.{ok, _Report} = barrel:merge(Run), ok = barrel:delete(Run).curl -X POST localhost:8080/db/demo-exp/_timeline/merge curl -X DELETE 'localhost:8080/db/demo-exp?purge=true'{"jsonrpc":"2.0","id":21,"method":"tools/call", "params":{"name":"merge", "arguments":{"db":"demo-exp"}}}{"failed":[],"last_merged":"AAABobh224EAAAAA", "docs_read":1,"docs_written":1,"doc_write_failures":0, "att_sync":{"atts_written":0, …}, …} -
Retrouver un état d’avant l’exécution
Gardez un curseur de changements avant chaque exécution. Une branche créée avec
atsur ce curseur vous donne chaque document tel qu’il était alors, à côté des données d’aujourd’hui, tant que l’instant est dans la fenêtre de rétention (30 jours par défaut). En REST,at_timeaccepte aussi une date RFC 3339.{ok, _, Before} = barrel:changes(Db, first), %% ... the run happens ... {ok, Then} = barrel:branch(Db, before_run_42, #{at => Before, vectordb => #{db_path => "data/before_42_vec"}}).curl -X POST localhost:8080/db/demo/_timeline/branch \ -H 'content-type: application/json' \ -d '{"name":"before-run", "at_time":"2026-11-07T09:00:00Z"}'{"jsonrpc":"2.0","id":22,"method":"tools/call", "params":{"name":"branch_create", "arguments":{"db":"demo","name":"before-run", "at":"AAABobh22gAAAAAA"}}}
Ce que fait Barrel
- Crée une branche en temps constant et l’isole entièrement
- Ne fusionne que ce que la branche a changé, par le mécanisme de réplication
- Garde comme conflits les modifications concurrentes des deux côtés
- Restaure un instant passé dans la fenêtre de rétention
- Reconstruit les vecteurs d’une branche en mode enregistrement à partir des embeddings stockés
Ce que fait votre application
- Nomme une branche par exécution et y dirige l’agent
- Décide de ce qu’est une relecture : une personne, une suite de tests ou un autre agent
- Résout les conflits laissés par une fusion
- Supprime les branches dont elle n’a plus besoin
Limites
- La filiation est linéaire : une branche d’une branche est refusée avec
cannot_branch_a_branch. - Un instant passé antérieur au plancher de l’historique échoue avec
pitr_window_exceeded. - Une branche d’un instant passé n’est pas refusionnée comme un retour arrière ; ramener
mainà un instant donné n’est pas encore disponible. - Les branches ordinaires (hors mode enregistrement) démarrent avec un stockage vectoriel vide.
- Sur une branche d’un instant passé, les pièces jointes sont celles du moment de la création de la branche, pas de l’instant choisi.
- Il n’y a pas de politique de conflit par fusion ; c’est le
conflict_resolverdu parent qui s’applique. Un jeton de capacité ne peut pas atteindre une branche de son espace ;branch_createetmergedemandent des droits d’administration.