# bion-triplet

Le **triplet d'Adressage Génératif** en Rust `std`-only : la donnée comme pure adresse.

```
triplet = ( hash_générateur , coordonnées , hash_résidu )
          └─ BLAKE3, 32 o ─┘ └─ opaque ──┘ └─ BLAKE3, 32 o ─┘
```

## Quoi

Ce crate fige la **logique** de la spec `adressage-generatif-triplet-v0`
(my_website2, `resources/papers/adressage-generatif-triplet-v0.md`) : les trois
champs du triplet et les trois opérations dessus.

- **ÉCRIRE** — `encode(générateur, data, coords)` : calcule
  `résidu = data ⊖ G(coords)` et retourne `(Triplet, résidu)`. On ne garde que
  l'écart au prédictible ; si la donnée est exactement la prédiction, le résidu
  est **vide** (le cas « déjà su » : la pure structure ne coûte rien).
- **LIRE** — `decode(générateur, triplet, résidu)` : vérifie les **deux** hash
  (générateur ET résidu), puis `data = G(coords) ⊕ résidu`. Bit-exact, sur
  toute machine, à toute époque.
- **ALIGNEMENT** — `align(a, b)` : égalité des `gen_hash`, décidable au bit.
  Deux nœuds alignés ne s'échangent que `(coordonnées, résidu)` — des adresses,
  pas des blobs.

Générateurs d'exemple fournis : `ConstGenerator` (octets constants),
`PatternGenerator` (motif répété + offset), `IdentityGenerator` (le plancher :
résidu = donnée entière, le cas dégénéré posé par la spec).

## Pourquoi

Une donnée n'est pas un contenu qu'on garde, c'est une adresse dans un espace
génératif. Le triplet est le « connecteur logiciel » éternel de XERB0XI0N :
position, DM et réplication sont la même opération à trois échelles — ce qui
voyage n'est jamais l'instant, c'est **l'écart entre l'instant et ce que
l'autre bout savait déjà en prédire**. Ce bion se build une fois ; ensuite on
n'optimise que les générateurs au-dessus, jamais le connecteur.

Il **complète** `tsoin-codec` (xerboxion-rt) sans le dupliquer : `tsoin-codec`
est un *compresseur* (codage arithmétique, une manière maline de fabriquer un
petit résidu) ; `bion-triplet` est le *format d'adresse* qui cite un générateur
et un résidu par hash. Le codec se branche au-dessus, comme n'importe quel `⊖`
de domaine.

## Exemple

```rust
use bion_triplet::{encode, decode, align, ConstGenerator};

let g = ConstGenerator::new(0x2A);
let data = [0x2A, 0x2A, 0xFF, 0x2A];
let (triplet, residu) = encode(&g, &data, ConstGenerator::coords(4));
assert_eq!(residu, vec![0, 0, 0x2A ^ 0xFF, 0]); // seule la surprise pèse
assert_eq!(decode(&g, &triplet, &residu).unwrap(), data);

let (autre, _) = encode(&g, b"****", ConstGenerator::coords(4));
assert!(align(&triplet, &autre)); // même générateur, décidable au bit
```

## Choix de design (documentés)

- **`⊖` = XOR à longueur portée par le résidu.** Sans ambiguïté : résidu vide
  ⇔ « exactement la prédiction » ; sinon `résidu.len() == data.len()` et la
  prédiction est complétée par des zéros si elle est plus courte. Honnête face
  au mur de Kolmogorov : un mauvais générateur donne un résidu au poids plein,
  jamais un mensonge.
- **Décoder vérifie avant de calculer.** Mauvais générateur ⇒
  `GeneratorMismatch` ; résidu corrompu ⇒ `ResidualMismatch`. Jamais une donnée
  silencieusement fausse.
- **Identité d'un générateur = hash d'une description canonique versionnée**
  (`bion-triplet:v0:const:…`), jamais un état interne. Changer la sémantique =
  nouveau nom = nouveau hash : rétrocompatibilité éternelle.
- **Un générateur ne panique jamais** sur des coordonnées malformées : il
  prédit « rien » et le résidu porte tout le réel.
- **Exception dépendance** : `blake3` (default-features off). On n'implémente
  pas une fonction de hachage cryptographique from scratch — le bion, c'est la
  logique du triplet.

## Liens build-your-own-x

Dans l'esprit de [build-your-own-x](https://github.com/codecrafters-io/build-your-own-x) :

- *Build your own Git* — le store adressé par contenu (`C1`) que le triplet
  cite est exactement le modèle objet de Git (hash → blob).
- *Build your own Docker / virtual machine* — le générateur comme programme pur
  sandboxé (WASM `C0`) rejouable partout.
- Compression / codage arithmétique (voir `tsoin-codec` du core) — le `⊖`
  malin qui fabrique de petits résidus.

## Comment l'optimiser (l'invitation au fork)

Le triplet ne change plus ; **tout le gain est au-dessus**. Pistes :

- un `⊖` de domaine plus malin que le XOR (diff structuré, delta d'images,
  codage arithmétique via `tsoin-codec`) — même API, résidu plus petit ;
- des générateurs réels : modèle de mouvement GPS, contexte de DM, index
  Hilbert 4D du Cubion — tous bit-exacts (entiers seulement) ;
- une sérialisation binaire du `Triplet` (72 octets + coords) pour le manifeste
  de réplication diff-only (*XI0N-résidu*) ;
- un panel de générateurs nommés + la grandeur honnête
  `certitude = 1 − L_min / L_baseline` (spec §3.2) ;
- brancher le chiffrement GPG du résidu (toujours, au repos et en transit) —
  hors de ce crate, dans la couche réseau.

Licence AGPL-3.0 · spec gelée `adressage-generatif-triplet-v0` · *Ne pas nuire.*