Que fait XERJ.code — codage par référence ?
Un agent qui ne connaît pas une API devine, exécute, échoue et devine à nouveau. Chaque cycle coûte des jetons de sortie, qui sont les plus chers. Cette compétence remplace les cycles par une recherche : cloner les dépôts qui contiennent déjà une implémentation correcte, les indexer avec XERJ, et récupérer le passage avant d'écrire.
L'échange est délibéré. La recherche utilise des jetons d'entrée, moins chers par
jeton et facilement mis en cache ; les cycles utilisent des jetons de sortie. Voir
COSTS.md pour
les calculs et les conditions dans lesquelles cet échange perd.
Statut, dit simplement : mesuré, et la valeur est réelle mais étroite. (Étude de cas complète avec jetons et dollars réels :
docs/case-studies/reference-coding/CASE_STUDY.md, 2026-08-05.)La comparaison pertinente est contre Claude Code natif — le même agent avec des outils qui pourraient parcourir le source lui-même — pas un modèle nu. Mesuré dans trois régimes, même agent, un verdict objectif (compilation + tests cachés passés) :
- Code inconnu avec un contrat que le modèle ne peut pas se rappeler (un sceau, une poignée générationnelle, un rechargement paresseux, un schéma de hachage spécifique — mesuré dans sept bibliothèques spécialement construites, 21 exécutions) : natif et xerj résolvent tous les deux 21/21 ; xerj utilise 1,5× moins de jetons de sortie et coûte 1,3× moins que natif, car la recherche remplace le parcours. La mémoire pure échoue 1/21 et brûle 6,5× le coût en tâtonnant. C'est le gain, et il est décisif. Le compilateur peut fuiter un nom d'API nom à travers une boucle de nouvelle tentative, mais jamais un contrat.
- Code mémorisé (toute crate publique populaire — même une table de 256 valeurs, ou un varint de style protobuf) : la recherche est un surcoût. La mémoire pure est la moins chère ; injecter une grosse référence peut être le pire cas, car le modèle réémet ce qu'on lui a donné.
Donc : utilisez ceci quand la référence est un code que le modèle n'a pas mémorisé — votre propre code privé/propriétaire, une API interne, une bibliothèque récente ou de niche. Sur les références de bibliothèques publiques que le modèle connaît déjà, cela coûte plus que cela n'économise. L'écart natif-vs-xerj augmente avec la taille du corpus (le parcours tire tout l'arbre dans le contexte ; la recherche tire un seul passage).
Depuis #977, toute la boucle est
à l'intérieur du binaire xerj — xerj corpus add / xerj corpus index /
xerj code — plus l'outil MCP xerj_code_search pour les agents sans shell.
Les anciens scripts d'encapsulation (xc-corpus.sh, xc-index.sh, xc.py) ont disparu ; vos
corpus et index ~/.xerj-code existants fonctionnent sans modification (voir
Migration ci-dessous).
Corpus permanents pour ce dépôt (OBLIGATOIRE depuis 2026-08-06)
Dans le dépôt xerj, la récupération-avant-écriture est requise pour le travail
moteur non trivial, pas optionnelle. Chaque corpus ci-dessous a une définition
figée et vérifiée pour les licences dans hub/ — xerj corpus add --from hub/<name>.json le
reconstruit aux mêmes commits que tout le monde utilise :
| corpus | projets | utilisez-le pour |
|---|---|---|
xerj-search | lucene, tantivy, meilisearch, quickwit, sonic, elasticsearch | FTS, BM25, postings, politique de fusion, tolérance aux fautes de frappe, disposition des segments, sémantique ES wire |
xerj-vector | qdrant, usearch, instant-distance, hnswlib | Construction HNSW, heuristiques de voisinage, quantification, kNN filtré |
xerj-storage | sled, fjall, redb | WAL, époques de vidage, récupération après crash, compaction, allocation de pages |
xerj-columnar | clickhouse | Stockage columnar, exécution d'agrégation, codecs de compression, scans vectorisés |
Sources d'approche uniquement : elasticsearch (AGPL-3.0 / SSPL-1.0 / Elastic-2.0)
et sonic (MPL-2.0). Ne copiez jamais leur code dans XERJ sous Apache-2.0 ; pour ES,
coller la source falsifierait également la revendication publique du projet "ne partage aucun code avec
Elasticsearch". meilisearch est MIT pour le cœur mais BUSL-1.1 pour ses parties
Enterprise Edition — vérifiez d'abord l'en-tête/le chemin. Lisez la conception,
écrivez notre propre implémentation. Le champ review.use de chaque manifeste indique dans quel
seau se trouve un repo ; hub/README.md explique les trois.
Corpus du hub ou corpus local
Deux types de corpus résident sur le même nœud local. Chacun répond à un type différent de question :
| corpus du hub | corpus local | |
|---|---|---|
| ce qu'il contient | Matériel public à un commit figé : le code source d'une bibliothèque, une norme, une réglementation, un flux d'avis | Fichiers uniquement présents sur cette machine : le projet sur lequel vous travaillez, des documents privés, des exportations |
| quand l'utiliser | Vous avez besoin d'un détail que vous ne pouvez pas citer exactement de mémoire | La réponse est dans vos propres fichiers |
| comment l'ajouter | xerj corpus add --from ./<slug>.json, puis xerj corpus index <slug> | xerj autoindex <dossier> |
| comment l'interroger | xerj code <slug> "<question>" · MCP xerj_code_search | xerj search "<mots>" · xerj def "<symbole>" · MCP xerj_search |
Un dossier indexé avec xerj autoindex --prefix <p> est le chemin local dans ce tableau, pas
un corpus xerj code : xerj corpus list lit ~/.xerj-code et ne liste pas <p> jusqu'à ce que
xerj corpus add enregistre le dossier, et les commandes qui le recherchent sont xerj search --prefix <p> et xerj def --prefix <p>.
N'utilisez ni l'un ni l'autre pour un fait que vous pouvez déjà énoncer exactement : sur un contenu mémorisé, la recherche est un surcoût (voir la note de statut ci-dessus).
Un manifeste du hub provient d'un checkout de la branche corpus-hub
(tools/xerj-code/hub/<slug>.json) ou, sans checkout, de son URL brute.
xerj corpus index et xerj code communiquent tous deux avec un nœud en cours d'exécution :
curl -fsSLO https://raw.githubusercontent.com/xerj-org/xerj/corpus-hub/tools/xerj-code/hub/<slug>.json
xerj corpus add --from ./<slug>.json # dernière ligne : next: xerj corpus index <slug>
xerj corpus index <slug> # fin : corpus '<slug>' searchable: <N> records
xerj code <slug> "<question>" # passages précédés du chemin du fichier et de la ligne
--from lit un fichier local : v1.0.0-rc.95 ne récupère pas d'URL, et en passer une
répond "no such manifest".
Choisir un corpus pour le projet en cours
Les quatre corpus moteur ci-dessus sont l'ensemble permanent de ce dépôt. Le catalogue
complet et actualisé est consultable sur hub.xerj.org, avec
une ligne par corpus dans hub.xerj.org/llms.txt ;
ce qu'un nœud a chargé est xerj corpus list --url <node>. Chaque corpus est
figé à un commit avec sa licence enregistrée par source. G7 (une
porte de récupération en cinq questions dont la suite a été pré-enregistrée avant que la récupération
ne soit exécutée) a été noté pour certains corpus et pas d'autres, et chaque page du hub
indique lesquels. Choisissez par le domaine du projet, pas par taille :
| le projet est… | commencez par | pourquoi |
|---|---|---|
| un moteur de recherche / requêtes | xerj-search | postings, BM25, politique de fusion, disposition des segments, sémantique ES wire |
| recherche vectorielle / ANN | xerj-vector, faiss, annoy | Construction HNSW, heuristiques de voisinage, quantification, kNN filtré ; faiss est l'implémentation de référence ANN, annoy la variante forestière |
| moteur de stockage / KV | xerj-storage, duckdb, rocksdb, leveldb, badger, lmdb, pebble, valkey-src | WAL, récupération après crash, compaction, allocation de pages ; arbres LSM-vs-B ; pebble pour les sous-niveaux L0 et la sémantique de suppression de plage ; valkey pour les structures de données d'un serveur KV en mémoire |
| analytique / columnar | xerj-columnar, duckdb, arrow-rs, parquet-format, iceberg | Disposition columnar, codecs, scans vectorisés, formats de table |
| un serveur de base de données | sqlite-src, postgres-src | Analyseurs, planificateurs, exécuteurs — les deux codebases les plus étudiées dans le domaine |
| messagerie / consensus | kafka-src, rabbitmq, nats-server, etcd-src, raft-rs, dragonboat | Compaction de journal, sémantique de livraison, exactitude du quorum/bail |
| surveillance / séries temporelles | influxdb, prometheus-src | Disposition TSDB, sous-échantillonnage, chemins de raclage/ingestion |
| TLS / crypto / tunnels | rustls, openssl, s2n-tls, boringtun | TLS-moderne-à-la-main, précédent de durcissement, motifs à temps constant |
| QUIC / HTTP / réseaux | quinn, nghttp2, curl-src, libuv, caddy, envoy, nginx | Machines d'état de protocole, mise en commun de connexions, boucles d'événements |
| compression / sérialisation | zstd, lz4, brotli, zlib-ng, snappy, protobuf, flatbuffers, capnproto, msgpack-c | Conception de format, codage par blocs/entropie, schémas zéro-copie |
| service de secrets / configuration | openbao | Magasin KV avec scellement/déscellement, machinerie de bail |
| révision de conception d'API | rust-api-guidelines, msft-api-guidelines, zalando-restful-api-guidelines, google-eng-practices | Nommage, forme des erreurs, versionnement ; Zalando est l'ensemble de politiques REST le plus complet en clauses, google-eng-practices est la référence pour la doctrine de révision de code |
| conformité aux protocoles/spécifications | openapi-spec, graphql-spec, json-schema-spec, w3c-css, whatwg-specs, ecma262, nats-protocol, kafka-protocol | Le texte normatif par lequel une implémentation est jugée — normes vivantes HTML/DOM/URL, grammaire ECMAScript, cadrage du protocole filaire |
| localiser la bonne RFC avant de la lire | ietf-rfc-abstracts | Un enregistrement par RFC (9 015) : numéro, titre, date, résumé — "quelle RFC couvre réellement X" sans extraire les textes complets (TLP-5.0) |
| production / SRE | gitlab-runbooks, school-of-sre, tldr-pages, mozilla-ssl-configs, twelve-factor | Véritables playbooks d'incidents, un programme complet de cours SRE, la syntaxe des commandes par outil, les configurations TLS déployées, la doctrine de déploiement |
| administration de systèmes Unix | freebsd-handbook, openbsd-faq | Procédures rc/ZFS/jail/réseau, les positions FAQ canoniques d'OpenBSD |
| documentation sur une API hébergée | github-api-description | La description OpenAPI de github.rest — sémantique des champs, valeurs enum, en-têtes d'aperçu |
| documentation des opérations d'une base de données | valkey-docs, etcd-docs | Sémantique des commandes, boutons de configuration, conseils de réglage — la référence opérationnelle pour chaque |
| câblage de télémétrie / observabilité | la moitié semconv de otel-proto (candidat — G7 2/5, stationné dans la voie sémantique) | Conventions sémantiques OpenTelemetry pour les noms d'attributs ; les tours lexicaux n'ont pas pu combler le fossé entre paraphrase et prose normative |
| internationalisation | unicode-cldr | Structure des données locales CLDR, squelettes de calendrier/date/nombre |
| révision de sécurité des dépendances Rust | rustsec-advisories, le pack rust-vulns (xerj corpus add --from la recette du hub) | Un enregistrement texte par avis (1 963 : RustSec + crates.io OSV, aucun chevauchement d'alias) : versions affectées, correctifs publiés, listes de symboles de fonction affectée sur 271 ; le pack reste le véhicule pour l'extraction de paires corrigées (étude de classe de défaut #1111) |
| révision de sécurité des dépendances Python | pysec | Enregistrements d'avis PYSEC avec versions affectées et corrigées, alias CVE/GHSA |
| audit de dépendances inter-écosystèmes | ghsa-db | Avis révisés par GitHub (36 263 enregistrements texte) : vecteurs CVSS, plages corrigées, packages affectés sur npm/PyPI/Go/Rust/maven et autres |
| révision de sécurité des modules Go | go-vulndb | Avis organisés par l'équipe Go (4 577) : packages et symboles affectés, versions corrigées, identifiants GO avec alias CVE |
| précédent de déni de service par regex | redos-precedent | 634 avis ReDoS spécifiques aux regex (classe CWE-1337/185, pas de simple CWE-400) : l'entrée pathologique, la fonction affectée, la réécriture bornée |
| précédent d'utilisation abusive de la crypto | crypto-misuse-precedent | 721 avis de classe CWE-326/327/328/329/347 : chiffrements faibles, clés codées en dur, réutilisation de nonce, contournement de vérification de signature, oracles de padding, ECB |
| taxonomie des vulnérabilités / faiblesses | mitre-cwe, mitre-capec | Définitions de faiblesses CWE et modèles d'attaque CAPEC, niveau identifiant |
| techniques adverses / ingénierie de détection | mitre-attck | Enregistrements par technique ATT&CK v19.2 : identifiants de technique, tactiques, sources de données de détection, exemples de procédures (entreprise/mobile/ics ; objets logiciels et de groupe hors scope) |
| triage des priorités de correctifs | cisa-kev | Le catalogue des vulnérabilités connues exploitées, un enregistrement par CVE — statut d'exploitation dans la nature, dates de correction contraignantes |
| comment faire de la sécurité des applications web | owasp-cheatsheets | Les recettes de contre-mesures de la série Cheat Sheet par sujet — gestion de session, secrets d'authentification, gestion des erreurs, gestion des téléchargements |
| planification d'un test de pénétration d'application web | owasp-wstg | Le catalogue du Web Security Testing Guide v4.2 : objectifs et méthode par test, organisés par catégorie (authn, authz, session, gestion des entrées) |
| triage d'une campagne active | cisa-alerts | IOC des avis CISA, actions requises et mesures d'atténuation (fenêtre 2025-05..2026-10) |
| interrogation de la visibilité des terminaux | osquery-config-examples | Packs osquery réels déployés et formes de requêtes planifiées |
| non-logiciel (fiscalité, emploi, droit britannique) | ecfr-title-12, ecfr-title-29, ecfr-title-26, uk-legislation | Réglementation consolidée actuelle, section par fichier |
| aviation (FAR) | ecfr-title-14 | 14 CFR section par fichier : minimums de visibilité, espace aérien transpondeur, intervalles d'inspection, priorité de passage |
| règles de navigation maritime | navrules | Texte COMDTINST M16672.2D par règle — risque de collision, chenaux étroits, situations de croisement, feux et signaux sonores |
| composants d'interface utilisateur accessibles | govuk-design-system | Options des composants GOV.UK et critères d'accessibilité — la sémantique exacte des options (maxwords vs maxlength, texte de séparateur, focus-on-load) |
| étiquettes de médicaments / pharma | dailymed | Sections des étiquettes FDA : indications, contre-indications, calendrier d'administration |
| directives de traitement clinique | cdc-clinical | Régimes et doses de traitement STI du CDC, désensibilisation à la syphilis, signes cliniques de la rougeole |
| sécurité des services alimentaires | fda-food-code | Dispositions du FDA Food Code 2022 : surfaces en contact avec les mains, temps comme mesure de contrôle de la santé publique, marquage des dates, état de préparation mains nues |
| dispositifs de contrôle de la circulation | mutcd | FHWA MUTCD 11e éd (Rév 1) : warrants de panneaux et signaux, marquages, applications typiques en zone de travaux |
| travaux de construction (Angleterre) | uk-building-regs | Règlement sur la construction 2010 (SI 2010/2214) par disposition : exigences des parties A–P, variations galloises |
…
[le reste du contenu reste inchangé, car la section est tronquée dans l'original]