Vision : la base de données pour les agents
Cette note définit ce que devient l’application barrel : non pas une
surcouche de barrel_docdb et barrel_vectordb, mais la couche qui en fait
une seule base de données, pensée pour les charges de travail d’agents.
Lisez-la avant de travailler sur une fonctionnalité de cette couche ; le
journal des décisions, à la fin, consigne ce qui est arrêté et pourquoi.
Positionnement
Le discours de Turso sur les agents se ramène à cinq idées : le multi-tenant par base-fichier, les branches en copie sur écriture, le MVCC avec détection des conflits au commit, la synchronisation asymétrique avec un distant qui fait autorité, et un packaging en journal d’audit (AgentFS). Le domaine de l’infrastructure pour agents se divise entre une couche mémoire (Letta, Mem0, Zep : extraction, consolidation, oubli progressif) et un substrat (Neon, Turso, Tiger, Cloudflare : bases isolées peu coûteuses, branches, voyage dans le temps, recherche hybride, MCP). Personne ne possède les deux. Barrel, si : cette umbrella est le substrat, et la couche mémoire se place au-dessus.
Les points d’appui de Barrel, que les acteurs en place ne peuvent pas copier :
- L’intégration dans la VM pour les applications BEAM : pas de saut réseau, pas de sérialisation.
- Une vraie synchronisation edge et multi-maître avec résolution causale des conflits (HLC) ; Turso a reculé sur les répliques edge et applique « le dernier push gagne ».
- La fusion de branches. Les branches de Turso et de Neon sont des bifurcations à sens unique ; un moteur héritier de CouchDB obtient la fusion grâce à sa mécanique de réplication.
- La provenance au niveau de la base (« que savait l’agent, et quand »).
- Open source et auto-hébergé de bout en bout, adapté à l’UE.
L’enregistrement
Un enregistrement barrel est une unité : corps du document, blobs (pièces jointes), vecteurs et provenance (HLC, acteur, source, session). Un seul chemin d’écriture le possède.
- Écriture = document + marqueur d’embedding en attente dans un seul WriteBatch docdb (atomique). L’indexation vectorielle est pilotée par le flux de changements avec une sémantique exactly-once ; un consommateur relancé répare les vecteurs manquants après un crash.
- Politique d’embedding par base : quels champs sont embeddés, avec quel modèle, en synchrone ou en asynchrone. Le mode synchrone donne une recherche qui voit vos propres écritures ; l’asynchrone est le défaut.
barrel_vectordbne stocke que les vecteurs et les index ANN. Le texte et les métadonnées sont lus via la jonctionbarrel_vectordb_docstore, pointée sur la base de l’enregistrement (le sens de la jonction s’inverse : le document est primaire, le vecteur est dérivé).- À terme (phase ultérieure) : les column families vectorielles rejoignent le RocksDB du stockage des enregistrements, pour que vecteur et document soient commités dans le même batch, sans marqueur.
Requêtes : BQL, un dialecte PartiQL
Une seule surface de requête sur les documents, les vecteurs et le plein texte.
- Sémantique PartiQL : MISSING vs NULL, expressions de chemin, UNNEST. Adopter la spécification, ne pas inventer de sémantique.
- Parseur leex/yecc (riak_ql sert de modèle architectural). Le planificateur compile vers la mécanique existante : indexation automatique des chemins, postings roaring64, sélection d’index par cardinalité, curseurs d’instantané.
- Les vecteurs et le FTS entrent dans le SQL d’abord comme fonctions de
table :
vector_top_k(...),bm25_top_k(...)(le modèle de libSQL, sans magie dans le planificateur). Hybride = RRF. Une réécritureORDER BY distance LIMIT kdans le planificateur pourra venir plus tard. - Requêtes live : la même requête + SUBSCRIBE, adossée aux abonnements de requêtes existants ; une requête live est un processus Erlang qui pousse des deltas.
- Périmètre v1 : SELECT, WHERE, ORDER BY, LIMIT, chemins, UNNEST, fonctions de table. Hors v1 : jointures, GROUP BY, complétude SQL-92.
Synchronisation
Le serveur fait autorité pour les clients légers ; multi-maître entre serveurs.
- Les vecteurs de versions HLC remplacent la sémantique des arbres de révisions (le choix de Couchbase Lite 4.0). Conflit par défaut : la dernière écriture gagne selon la HLC, ce qui respecte la causalité. Les versions perdantes sont remplacées, pas supprimées, et restent interrogeables dans l’historique. Un hook de fusion permet une résolution personnalisée.
- Protocole asymétrique : pousser des mutations logiques estampillées HLC, tirer un journal de changements compacté.
- La synchronisation partielle est un index construit à l’écriture (des channels dérivés des listes de postings de chemins existantes), jamais un filtre appliqué à la lecture sur le flux global.
- Les blobs se synchronisent hors bande, adressés par contenu. Les vecteurs se synchronisent quantifiés ; les index ANN ne sont jamais envoyés, ils se reconstruisent localement.
- Une fenêtre de rétention par base borne les tombstones, la fenêtre PITR et la fenêtre de fusion avec un seul réglage.
Timeline : branches et restauration à un instant donné
Branches, PITR et fusion forment un seul sous-système bâti sur deux primitives : les checkpoints RocksDB (la mécanique de bifurcation : SST en liens physiques, quasi instantané) et un journal de changements HLC conservé (la sémantique). Le flux de changements doit conserver l’historique dans la fenêtre de rétention ; aujourd’hui, il ne garde que le dernier changement par document.
- Branche = bifurcation maintenant : checkpoint des deux stockages,
enregistrement de
{parent, fork_hlc}. - PITR = bifurcation à un T passé : checkpoint le plus proche avant T, puis rejeu du journal jusqu’à T. La restauration crée une nouvelle base (parité avec Turso), et elle peut être fusionnée en retour.
- Fusion = réplication ponctuelle des changements de la branche depuis
fork_hlcvers le parent, par la mécanique normale de conflits de la synchronisation, avec une politiquelww | fail_on_conflict | Fun. La fusion est une synchronisation ; pas de moteur séparé. - En v1, la lignée est parent-enfant linéaire. Les DAG de branches et les fusions entre lignées viennent explicitement plus tard.
Couche agents
- Une base par agent : ouverture/création assez peu coûteuse pour des
centaines de bases éphémères par tâche ; un processus supervisé par base,
des noms binaires de bout en bout (pas de fuite d’atomes), et un
gestionnaire de cycle de vie (
barrel_dbs) avec fermeture sur inactivité et éviction LRU. - Espaces : des conteneurs de contexte partagés avec des jetons de capacité ; le contexte est partagé par référence, pas copié. Un espace EST une base barrel ; une capacité est un jeton aléatoire haché avec des droits read < write < admin, révocable localement.
- Les sessions avec TTL et les passations sont des primitives barrel ; une
passation est un espace partagé plus une capacité dont la possession vaut
droit d’accepter. Les sessions reposent sur une primitive générale de TTL
de document (
expires_at+ balayeur activé sur demande). - MCP comme surface de premier rang : bases et requêtes live exposées comme ressources MCP avec abonnements (spécifiés mais non implémentés dans tout le secteur), plus des outils pour requêter, écrire, créer une branche et fusionner, et la couche agents.
- Audit : les champs de provenance et le journal de changements conservé répondent à « que savait l’agent, et quand » au niveau de la base.
- LIVRÉ (phase 8) : voir la ligne 6 du journal des décisions.
Concurrence et chiffrement
- Les lectures ponctuelles quittent le writer de la base pour des
instantanés RocksDB (les requêtes le contournent déjà ;
get_docdoit le faire aussi). Group commit dans le writer. Le CAS de révision au niveau du document reste la détection des conflits au commit. La montée en charge en écriture vient de la multiplication des bases, que le modèle d’agents fournit. - Chiffrement au repos : un behaviour
barrel_keyprovideravec des clés par base (BYOK) résolues sur le KEYSPACE (une branche s’ouvre avec la clé de son parent), l’EncryptedEnv de RocksDB pour chaque stockage, et un chiffrement par secteur (AES-256-CTR adressable par offset + enveloppes GCM pour les fichiers de termes) pour les fichiers plats mappés en mémoire que l’EncryptedEnv ne couvre pas : BM25 disque et DiskANN. L’état HNSW/FAISS est persisté via les stockages chiffrés. Ouvertures à échec sûr grâce à des marqueurs de vérification de clé en clair. Les clés par base servent aussi d’isolation entre agents. LIVRÉ (phase 7).
Navigateur : barrel-lite
Un client de protocole en TypeScript, pas un portage WASM du moteur.
- Stockage OPFS avec élection d’un leader par Web Locks (un seul writer par origine).
- Mutations locales estampillées HLC ; pousser du logique, tirer le journal de changements ; les données locales sont un cache (Safari évince), la synchronisation assure la durabilité.
- Sous-ensemble BQL local pour l’ensemble synchronisé ; pas d’ANN dans le navigateur : cosinus en force brute sur le sous-ensemble synchronisé, embeddings transformers.js en option, requêtes lourdes ou globales déléguées au serveur.
- LIVRÉ (phases 9a, 9b, 9c) : voir la ligne 7 du journal des décisions.
Non-objectifs
- Pas de réplication CRDT symétrique (les retours d’expérience du domaine sont sans appel).
- Pas de complétude SQL-92 avant que le sous-ensemble documents ne l’ait méritée.
- Pas de portage WASM du moteur Erlang.
- Pas de moteur de requêtes DuckDB/DataFusion embarqué (il ne peut pas voir les index de barrel).
Journal des décisions
| # | Décision | Choix | Justification |
|---|---|---|---|
| 1 | Cœur de la synchronisation | Vecteurs de versions HLC, pas d’arbres de révisions | Les plaies des arbres de révisions (tombstones, gagnants arbitraires, métadonnées dans le chemin de lecture) ; précédent de CBL 4.0. LIVRÉ en phases 3+5 : protocole VV + historique conservé (phase 3) ; transport réseau en HTTP (protocole JSON + base64, /db/:db/_sync/*), authentification bearer statique, channels construits à l’écriture (flux 0x1E) pour la synchronisation partielle, synchronisation des pièces jointes adressées par contenu (flux dans le stockage de blobs, LWW sur la HLC d’origine, transfert en streaming), tâches continues pilotées par événements (réveil par le flux de changements, polling distant adaptatif, backoff sur erreur). Synchronisation des vecteurs quantifiés reportée à la phase 9 |
| 2 | Atomicité document+vecteur | Marqueur outbox dans un seul WriteBatch, indexation par le flux de changements ; unification du stockage plus tard | Atomique dès maintenant sans bloquer la vie autonome de vectordb. LIVRÉ comme mode enregistrement (phase 2) : outbox étiquetée + indexeur supervisé + mode synchrone + docstore en lecture traversante |
| 3 | Dialecte de requête | Sémantique PartiQL | Une sémantique SQL orientée JSON déjà spécifiée ; rien à inventer. LIVRÉ comme BQL v1 (phase 4) : parseur leex/yecc abaissé vers le moteur de requêtes, fonctions de table vector_top_k/bm25_top_k/hybrid_top_k, UNNEST, requêtes live SUBSCRIBE, point d’accès REST en streaming |
| 4 | Branches | Sous-système timeline : checkpoint + journal HLC conservé ; branche, PITR, fusion comme synchronisation ; lignée linéaire en v1 | La fusion est le saut qui dépasse Turso/Neon ; la parité PITR est requise. LIVRÉ (phase 6) : bifurcations en O(1) par liens physiques via les checkpoints rocksdb + indirection de keyspace (la branche garde le nom du parent dans les clés, identité dans le fichier annexe TIMELINE, nouveau source_id) ; retour PITR à partir du journal d’historique conservé, reconstruction des fenêtres de conflit comprise ; fusion = réplication incrémentale depuis la bifurcation via put_version (LWW/conflict_merger) avec une phase pièces jointes ; les branches en mode enregistrement remplissent leur stockage vectoriel à partir des embeddings stockés ; REST /db/:db/_timeline/* |
| 5 | Chiffrement au repos | Clés par base via barrel_keyprovider, résolues par keyspace ; EncryptedEnv + chiffrement par secteur pour les fichiers plats | Les clés servent aussi d’isolation entre agents ; une branche partage la clé de son parent par le keyspace. LIVRÉ (phase 7) : application barrel_crypto (enveloppe GCM, CTR adressable par offset, jetons de vérification de clé, fournisseurs env/personnalisés) ; EncryptedEnv sur les documents et pièces jointes docdb et sur chaque RocksDB vectordb ; BM25 disque (nonce des postings statiques renouvelé à chaque compaction, blockmax intégré) et DiskANN (secteurs de graphe intégrés, vecteurs/pq statiques, meta/pq_state scellés) ; matrice d’ouverture à échec sûr partout ; une seule spécification encryption à barrel:open couvre toute la base logique ; serveur via open_opts |
| 6 | Couche agents | Espaces = bases + jetons de capacité ; sessions/passations intégrées ; MCP dans barrel_server | Le partage par référence vaut mieux que la copie ; la possession du jeton vaut mieux que l’identité de l’appelant pour les passations ; un seul gestionnaire de cycle de vie sert REST, MCP et les espaces. LIVRÉ (phase 8) : noms de bases binaires + registre via pour vectordb (fuite d’atomes refermée) ; gestionnaire de cycle de vie barrel_dbs (fermeture sur inactivité, plafond LRU, épinglage) ; option d’écriture provenance (actor/session/source, colonne d’entité + queue TLV dans l’historique, locale seulement sur le protocole) avec lectures d’audit (history/doc_versions/version_body) et points d’accès REST ; TTL de document (expires_at, index d’expiration 0x1F, lectures paresseuses + balayeur activé sur demande) ; apps/barrel_spaces (base registre, identifiants sp_, chiffrement par espace), barrel_caps (jetons bsp_, stockage du hash seul, échelle de droits), sessions (TTL glissant, messages chronologiques, janitor), passations (acceptation par CAS, la complétion révoque, chaînes) ; REST /spaces + /handoffs avec des bearers de capacité ; point d’accès MCP sur /mcp (pont livery_mcp, fournisseur d’authentification propre pour les jetons serveur et de capacité, 26 outils, 3 modèles de ressources, pont de requêtes live avec notifications updated temporisées, GC des sessions, capacités) |
| 7 | Client navigateur | barrel-lite : un client de protocole TS dans l’umbrella (clients/barrel-lite), pas un portage WASM | Le protocole est du JSON + base64 simple : le client réimplémente les codecs et garde les données locales comme cache. LIVRÉ (phase 9a) : codecs HLC/version/VV exacts à l’octet (fixtures de référence générées depuis l’Erlang par un escript) ; stockage local sur un StorageAdapter (mémoire + OPFS asynchrone sur le thread principal) avec un source id persisté et des checkpoints côté client ; synchronisation live ponctuelle et en polling adaptatif (l’application reproduit do_put_version : skip/fast-forward/LWW avec un hook onConflict) ; élection de leader par Web Locks avec RPC proxy des suiveurs par BroadcastChannel (le leader possède le stockage et la synchronisation) ; prérequis côté serveur = middleware CORS (surcouche livery_cors) et jetons de capacité limités aux routes /db de leur espace (read = branche pull, write = branche push, classifieur à échec sûr) ; intégration contre un vrai barrel_server et un smoke test Playwright chromium. LIVRÉ (phase 9b) : un mode SSE continu /changes côté serveur (push par abonnement, contre-pression par ack, heartbeat) avec un flux client qui réveille le poller et se dégrade en cas de coupure ; synchronisation des pièces jointes (stockage de blobs OPFS adressé par contenu, digest sha256-, LWW sur la HLC d’origine, flux + checkpoint séparés, API put/get/remove/gc) ; et un sous-ensemble BQL local porté octet pour octet (lexer + parseur à descente récursive + abaissement + évaluateur) conforme au sous-ensemble documents du serveur, fixé par des fixtures de référence de bout en bout générées depuis l’Erlang, avec queryRemote qui délègue les fonctions de table à POST /db/:db/query. LIVRÉ (phase 9c) : recherche vectorielle dans le navigateur = un tirage dédié des embeddings (include_embedding sur GET doc + POST /db/:db/_bulk_get, le seul changement serveur ; les vecteurs voyagent en float32 LE base64 sans perte, exacts à l’octet avec barrel_doc:encode_embedding), un index vectoriel persisté à dimension unique dans le stockage local (instantané vectors.json), et db.searchLocal qui calcule un top-k cosinus en force brute sur les vecteurs synchronisés avec un pré-filtre BQL WHERE optionnel ; db.searchVector/searchText délèguent aux points d’accès /search du serveur (un corpus ANN à la dimension du modèle, distinct de la colonne emb par document), et transformers.js est un adaptateur optionnel réservé aux exemples, jamais une dépendance d’exécution |
| 8 | Montée en charge | Contextes : des jeux de données bornés et portables que les agents découvrent, attachent et interrogent ensemble ; la fédération par composition, pas des shards transparents | LIVRÉ dans barrel 1.10.0 et barrel_server 1.10.0 (#50 à #59), conception dans contexts.md. Composition distante : catalogue de contextes, client de requête distant, exécuteur BQL fédéré avec statut, version et couverture par source, route de requête bornée (max_rows, deadline_ms, version observée), REST /contexts et outils MCP context_*. Classement : la récupération est groupée par contexte ; vector_top_k ne fusionne par score que lorsque chaque membre déclare la même empreinte d’embedding et la distance cosinus (mesuré égal à un index unique en force brute) ; les scores BM25, hybrides et RRF ne fusionnent jamais ; le rerank est refusé tant qu’un reranker adapté au code n’est pas validé. Portabilité : ouvertures en lecture seule, export et import vérifié en lecture seule d’une génération de base, ensembles de travail avec tranches de l’ensemble récupéré et couverture hors ligne (guide). Reporté : paquets d’index ngram, en attente d’un format de segment compact |