v0.3.6-pre.006
This commit is contained in:
272
deltas/0.3.6/pre.006.md
Normal file
272
deltas/0.3.6/pre.006.md
Normal file
@@ -0,0 +1,272 @@
|
||||
<!-- file: deltas/0.3.6/pre.006.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.6-pre.006` — conversion RAW transaction v1 et provenance observée
|
||||
|
||||
## Base requise
|
||||
|
||||
```text
|
||||
0.3.6-pre.005-fix.001 appliquée
|
||||
workspace.package.version = 0.3.6-pre.5.fix.1
|
||||
```
|
||||
|
||||
La base opérateur inclut également la synchronisation manuelle des versions d'en-tête omise dans l'archive initiale du fix :
|
||||
|
||||
```text
|
||||
Cargo.toml header 400 -> 401
|
||||
crates/ksp-job-backfill-lib/src/discovery.rs header 1 -> 2
|
||||
```
|
||||
|
||||
Le gate opérateur fourni pour cette base confirme :
|
||||
|
||||
```text
|
||||
cargo fmt --all PASS
|
||||
python3 scripts/audit_rust_workspace_rules.py PASS / clean
|
||||
python3 scripts/audit_markdown_tables.py ... PASS / clean (264 tables / 148 fichiers)
|
||||
cargo check --workspace PASS
|
||||
cargo clippy --workspace --all-targets PASS
|
||||
cargo test -p ksp-job-backfill-lib PASS
|
||||
unitaires 11 PASS
|
||||
dependency_boundary 2 PASS
|
||||
public_api 2 PASS
|
||||
release_completeness 2 PASS
|
||||
cargo tree -p ksp-job-backfill-lib --edges normal exécuté
|
||||
cargo tree -p ksp-job-backfill-lib -e features exécuté
|
||||
```
|
||||
|
||||
## Objectif
|
||||
|
||||
Matérialiser exclusivement la tranche `pre.006` du plan 027 : convertir un candidat Backfill déjà découvert en transaction RAW canonique v1 et en observation d'acquisition sûre à partir du chemin Transport observé `getTransaction`, sans encore persister dans Store ni ouvrir le runtime de Job.
|
||||
|
||||
L'identité logique reste strictement :
|
||||
|
||||
```text
|
||||
RawTransactionReference = (RawNetworkId, RawTransactionSignature)
|
||||
```
|
||||
|
||||
Provider, endpoint, protocole, méthode Transport et `JobId` ne deviennent jamais une identité de transaction. Ils servent uniquement à caractériser l'acquisition et, lorsqu'une transaction existe, l'identité déterministe de son observation.
|
||||
|
||||
## Signature canonique
|
||||
|
||||
`BackfillSignature::to_raw_transaction_signature` ajoute le passage de la forme Base58 bornée de `pre.005` vers `RawTransactionSignature` exactement 64 octets.
|
||||
|
||||
Le décodeur Base58 est privé, borné et spécialisé pour cette frontière :
|
||||
|
||||
- alphabet Base58 Solana exact ;
|
||||
- exactement 64 octets décodés requis ;
|
||||
- zéros initiaux `1` conservés ;
|
||||
- dépassement arithmétique rejeté ;
|
||||
- aucune dépendance SDK/protocolaire Solana ;
|
||||
- aucune nouvelle dépendance Base58 externe.
|
||||
|
||||
La conversion ne modifie pas l'identité réseau du candidat et rejette avant Transport tout candidat dont le réseau diffère de la requête.
|
||||
|
||||
## Hydratation Transport observée
|
||||
|
||||
La voie publique :
|
||||
|
||||
```text
|
||||
hydrate_backfill_candidate
|
||||
```
|
||||
|
||||
appelle exclusivement :
|
||||
|
||||
```text
|
||||
HttpTransportPool::get_transaction_observed
|
||||
```
|
||||
|
||||
avec :
|
||||
|
||||
```text
|
||||
encoding = base64
|
||||
commitment = engagement explicite du Backfill
|
||||
maxSupportedTransactionVersion = 0
|
||||
```
|
||||
|
||||
Transport reste propriétaire du routage, retry, pacing, cooldown et endpoint victorieux. Job n'introduit aucun second client ni boucle de retry.
|
||||
|
||||
Deux outcomes sont distingués :
|
||||
|
||||
- `Available(BackfillRawAcquisition)` : transaction présente, RAW v1 et observation construits en mémoire ;
|
||||
- `Missing(RawTransactionReference)` : JSON RPC `result: null`, aucune provenance ni observation fabriquée.
|
||||
|
||||
## RAW transaction v1
|
||||
|
||||
Le format KSP figé par la tranche est :
|
||||
|
||||
```text
|
||||
format_id = ksp.solana.raw_transaction
|
||||
format_version = 1
|
||||
```
|
||||
|
||||
Le payload canonique est du JSON UTF-8 compact déterministe. La forme top-level est construite dans cet ordre :
|
||||
|
||||
1. `transaction` ;
|
||||
2. `meta` si le champ wire n'est pas omitted ;
|
||||
3. `version` si le champ wire n'est pas omitted ;
|
||||
4. `transactionIndex` si le champ wire n'est pas omitted.
|
||||
|
||||
La transaction est conservée sans décodage métier sous la forme :
|
||||
|
||||
```json
|
||||
["<base64>","base64"]
|
||||
```
|
||||
|
||||
Les objets JSON imbriqués sont canonisés récursivement par tri lexical des clés ; l'ordre des tableaux reste intact. Les états wire `Omitted`, `Null` et `Value` de `meta`, `version` et `transactionIndex` restent distincts.
|
||||
|
||||
`slot` et `blockTime` appartiennent aux champs structurés de `RawTransaction` et ne sont pas dupliqués dans le payload. Un `blockTime` négatif ou non représentable dans `RawTimestamp` est une erreur de conversion terminale.
|
||||
|
||||
SHA-256 et `byte_len` sont calculés sur les octets canoniques exacts avant construction de `RawPayload`.
|
||||
|
||||
Les réponses transactionnelles non Base64 sont rejetées ; Job ne bascule pas vers une interprétation JSON/jsonParsed ou fournisseur.
|
||||
|
||||
## Provenance d'acquisition
|
||||
|
||||
Une transaction disponible produit `RawAcquisitionProvenance` avec :
|
||||
|
||||
- provider réellement victorieux ;
|
||||
- protocole sûr `solana.http.json_rpc` ;
|
||||
- méthode `getTransaction` ;
|
||||
- endpoint sûr réellement victorieux ;
|
||||
- engagement demandé ;
|
||||
- `JobId` comme capture session id ;
|
||||
- origine `Backfill` ;
|
||||
- timestamp de réception fourni par l'hôte.
|
||||
|
||||
Aucun URL, header, secret, body HTTP ou payload fournisseur brut n'est copié dans la provenance.
|
||||
|
||||
La clé `RawTransactionObservationKey` utilise SHA-256 avec séparation de domaine et couvre :
|
||||
|
||||
- `JobId` ;
|
||||
- fingerprint du scope ;
|
||||
- signature RAW 64 octets ;
|
||||
- provider ;
|
||||
- endpoint ;
|
||||
- engagement ;
|
||||
- version du contrat d'observation.
|
||||
|
||||
Même réseau + même signature + endpoint différent représente donc toujours la même transaction logique mais une observation d'acquisition distincte.
|
||||
|
||||
## Dépendances
|
||||
|
||||
La crate conserve ses dépendances KSP de `pre.005` et ajoute uniquement :
|
||||
|
||||
```text
|
||||
serde_json.workspace = true
|
||||
```
|
||||
|
||||
`serde_json` est déjà centralisé dans `[workspace.dependencies]`. `sha2` reste la primitive SHA-256 déjà présente. Aucune dépendance `bs58`, SDK Solana, Store API/backend, Config, reqwest ou tonic n'est ajoutée.
|
||||
|
||||
## Tests matérialisés
|
||||
|
||||
La tranche ajoute **8 tests unitaires**, portant le total de `ksp-job-backfill-lib` à **19 unitaires** :
|
||||
|
||||
- décodage Base58 exact 64 octets, longueur excessive et overflow ;
|
||||
- golden payload canonique, longueur, SHA-256 et provenance ;
|
||||
- distinction omitted/null des champs wire ;
|
||||
- rejet des transactions non Base64 ;
|
||||
- block times négatifs ou non représentables ;
|
||||
- clé d'observation déterministe et sensible à provider/endpoint ;
|
||||
- mismatch réseau rejeté avant Transport ;
|
||||
- outcome Missing limité à la référence réseau + signature.
|
||||
|
||||
Une canarie publique supplémentaire porte les canaries d'intégration à **7** :
|
||||
|
||||
- `dependency_boundary` : 2 ;
|
||||
- `public_api` : 3 ;
|
||||
- `release_completeness` : 2.
|
||||
|
||||
Les canaries verrouillent en outre l'usage du chemin observé, `base64`, `maxSupportedTransactionVersion = 0`, l'absence de persistance et les firewalls de dépendances.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
```text
|
||||
crates/ksp-job-backfill-lib/src/conversion.rs
|
||||
crates/ksp-job-backfill-lib/unit_tests/conversion.rs
|
||||
deltas/0.3.6/pre.006.md
|
||||
```
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-job-backfill-lib/Cargo.toml
|
||||
crates/ksp-job-backfill-lib/src/error.rs
|
||||
crates/ksp-job-backfill-lib/src/lib.rs
|
||||
crates/ksp-job-backfill-lib/src/request.rs
|
||||
crates/ksp-job-backfill-lib/tests/dependency_boundary.rs
|
||||
crates/ksp-job-backfill-lib/tests/public_api.rs
|
||||
crates/ksp-job-backfill-lib/tests/release_completeness.rs
|
||||
docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md
|
||||
docs/validation/023-V0_3_6_JOB_API_BACKFILL.md
|
||||
```
|
||||
|
||||
## Versions d'en-tête
|
||||
|
||||
Tous les fichiers Rust/TOML modifiés par cette tranche incrémentent leur version d'en-tête par rapport à la base opérateur corrigée :
|
||||
|
||||
```text
|
||||
Cargo.toml 401 -> 402
|
||||
crates/ksp-job-backfill-lib/Cargo.toml 1 -> 2
|
||||
crates/ksp-job-backfill-lib/src/error.rs 1 -> 2
|
||||
crates/ksp-job-backfill-lib/src/lib.rs 1 -> 2
|
||||
crates/ksp-job-backfill-lib/src/request.rs 1 -> 2
|
||||
crates/ksp-job-backfill-lib/tests/dependency_boundary.rs 1 -> 2
|
||||
crates/ksp-job-backfill-lib/tests/public_api.rs 1 -> 2
|
||||
crates/ksp-job-backfill-lib/tests/release_completeness.rs 1 -> 2
|
||||
```
|
||||
|
||||
Les nouveaux fichiers Rust commencent à `version: 1`. Les documents Markdown modifiés incrémentent eux aussi leur en-tête documentaire : plan 027 et validation 023 passent de `9` à `10`.
|
||||
|
||||
## Version workspace
|
||||
|
||||
La tranche modifie du code Rust et le manifeste runtime de la crate :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.6-pre.6
|
||||
delivery = 0.3.6-pre.006
|
||||
commit = v0.3.6-pre.006
|
||||
```
|
||||
|
||||
Aucun tag prerelease.
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Frontières conservées
|
||||
|
||||
- aucune persistance Store ;
|
||||
- aucune prélecture Store avant hydratation ;
|
||||
- aucun checkpoint ou frontier contiguë ;
|
||||
- aucune concurrence d'hydratation concrète ;
|
||||
- aucun snapshot Job concret ;
|
||||
- aucune Config/env ;
|
||||
- aucun Worker ou exécutable ;
|
||||
- aucune modification Transport ou Store ;
|
||||
- aucun endpoint/provider/protocole dans l'identité transactionnelle ;
|
||||
- aucun README, USAGE, CHANGELOG ou ROADMAP rouvert ;
|
||||
- aucun code kbot3 copié.
|
||||
|
||||
## Validations dans l'environnement d'assemblage
|
||||
|
||||
L'environnement d'assemblage exécute les audits statiques du dépôt et les contrôles d'archive. Il ne possède ni `cargo`, ni `rustc`, ni `rustfmt`; le gate Rust de `pre.006` doit donc être rejoué par l'opérateur avant clôture.
|
||||
|
||||
## Gate opérateur demandé
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.6
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-job-backfill-lib
|
||||
cargo tree -p ksp-job-backfill-lib --edges normal
|
||||
cargo tree -p ksp-job-backfill-lib -e features
|
||||
```
|
||||
|
||||
Résultat attendu : **19 tests unitaires + 7 canaries d'intégration**, sans persistance Store et avec un graphe normal qui conserve `ksp-store-lib` sans backend imposé.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
Aucune pour `pre.006`. La persistance atomique Store et ses outcomes restent réservés à `pre.007` après gate vert de cette tranche.
|
||||
Reference in New Issue
Block a user