188 lines
6.2 KiB
Markdown
188 lines
6.2 KiB
Markdown
<!-- file: deltas/0.3.9/pre.001.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.3.9-pre.001` — audit, architecture et sizing Worker API
|
||
|
||
## Base requise
|
||
|
||
```text
|
||
archive stable fournie : khadhroony-solana-project-v0.3.8.zip
|
||
workspace.package.version = 0.3.8
|
||
delta stable = deltas/0.3.8/rel.001.md
|
||
prompt = prompts/028-V0_3_9_START_PROMPT.md
|
||
```
|
||
|
||
## Type de livraison
|
||
|
||
```text
|
||
ksp-doc-0.3.9-pre.001.zip
|
||
```
|
||
|
||
La livraison est strictement documentaire et contient uniquement les deux nouveaux documents `docs/` et le présent delta.
|
||
|
||
## Objectif
|
||
|
||
Ouvrir `0.3.9` par le gate documentaire imposé : vérification complète des archives/règles, audit de `ksp-job-api` comme référence de propriétés, décision de l’architecture générique `ksp-worker-api`, threat map, tests et sizing, **sans créer la crate Worker ni commencer l’audit fonctionnel RAW provider**.
|
||
|
||
## Vérification des archives
|
||
|
||
```text
|
||
KSP SHA-256 = b3a34a3dfd56fac1eef3d23f13631ff001338b612834488038cf259112c63624
|
||
KSP entries = 1809
|
||
KSP unzip -t = PASS
|
||
|
||
kbot3 SHA-256 = ee47643b9f8b582ee8db97b2381ec107e45aef8c009fee44757531514615d318
|
||
kbot3 entries = 2501
|
||
kbot3 unzip -t = PASS
|
||
```
|
||
|
||
Aucune entrée absolue/traversal/symlink et aucun `target`, `node_modules`, `.git`, `Cargo.lock` ou `.env` livré n’a été détecté.
|
||
|
||
La source de code reste exclusivement KSP `v0.3.8`. kbot3 n’a pas été utilisé pour concevoir Worker API ; son futur usage est réservé à la référence **fonctionnelle historique** lors de l’audit RAW après freeze.
|
||
|
||
## Audits baseline exécutés avant modification
|
||
|
||
```text
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
General Rust rule audit: clean
|
||
Rust export completeness audit: 0 candidate(s)
|
||
KSP workspace Rust rule audit: clean
|
||
|
||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
|
||
Markdown table audit: clean (316 table(s), 725 file(s))
|
||
```
|
||
|
||
Le binaire `cargo` est absent de l’environnement d’assemblage. Les commandes Cargo de baseline et `cargo tree -p ksp-job-api` sont donc **non exécutées et non PASS** localement. Le manifest de `ksp-job-api` a néanmoins été audité statiquement : une seule dépendance normale `ksp-core-lib`, aucune feature/dev/build dependency.
|
||
|
||
## Audits post-modification
|
||
|
||
Après ajout du plan, de la validation et du présent delta :
|
||
|
||
```text
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
General Rust rule audit: clean
|
||
Rust export completeness audit: 0 candidate(s)
|
||
KSP workspace Rust rule audit: clean
|
||
|
||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
|
||
Markdown table audit: clean (321 table(s), 728 file(s))
|
||
```
|
||
|
||
Le diff exact contre les bytes du ZIP stable contient uniquement les trois fichiers ajoutés de cette livraison ; aucun fichier de la base n’est modifié ou supprimé. Le cache Python créé par l’audit local est un artefact ignoré et est supprimé avant packaging.
|
||
|
||
## Décisions Worker API
|
||
|
||
Surface V1 prévue :
|
||
|
||
```text
|
||
WorkerId / WorkerKindCode, bornés à 128 octets
|
||
WorkerState = Created / Starting / Running / Stopping / Stopped / Faulted(ErrorCode)
|
||
WorkerHealth = Unknown / Healthy / Degraded / Unhealthy
|
||
WorkerActivity = Unknown / Idle / Active
|
||
WorkerLifecycle producteur-owned, terminal immutable
|
||
WorkerStopToken coopératif partagé/idempotent
|
||
WorkerSnapshotSequence monotone checked
|
||
WorkerSnapshot fixe sans payload arbitraire
|
||
WorkerSnapshotSource latest-value, Send + Sync et object-safe
|
||
Core Error/ErrorCode/ErrorContext/Result
|
||
```
|
||
|
||
Dependency map exact décidé :
|
||
|
||
```text
|
||
ksp-worker-api -> ksp-core-lib uniquement
|
||
```
|
||
|
||
Explicitement exclus : Job API, Interface, Config, Logging, Transport, Store, Tokio, futures, serde, Tauri, provider SDK et toute notion RawTransaction/slot/provider/endpoint/replay/backfill.
|
||
|
||
Le snapshot commun est volontairement fixe plutôt que générique : le control plane obtient un état uniforme et aucun payload/string libre ne peut entrer dans l’API Worker. Les métriques métier restent au worker concret.
|
||
|
||
Restart/retry/process control ne font pas partie de Worker API V1. Un lifecycle/source terminal ne redevient jamais actif et n’est jamais rebinding vers une nouvelle instance ; la recréation appartient au caller/futur control plane.
|
||
|
||
## Recalibrage de la trajectoire
|
||
|
||
Le noyau API reste en deux tranches de code :
|
||
|
||
```text
|
||
pre.002 contrats
|
||
pre.003 hardening + external implementation + freeze fonctionnelle
|
||
```
|
||
|
||
L’audit RAW initialement regroupé en une tranche est scindé afin de respecter le budget KSP :
|
||
|
||
```text
|
||
pre.004 Solana standard + inventaire KSP
|
||
pre.005 Helius/Yellowstone/providers + kbot3 fonctionnel historique
|
||
pre.006 synthèse multi-source + handoff 0.3.10/0.3.12
|
||
pre.007 gate technique final
|
||
pre.008 réconciliation documentaire
|
||
pre.009 préparation publication
|
||
rel.001 publication stable
|
||
```
|
||
|
||
L’owner prévu du document d’audit final est `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`, créé seulement après freeze de Worker API.
|
||
|
||
## Fichiers ajoutés
|
||
|
||
```text
|
||
docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
|
||
docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md
|
||
deltas/0.3.9/pre.001.md
|
||
```
|
||
|
||
## Fichiers modifiés
|
||
|
||
```text
|
||
aucun
|
||
```
|
||
|
||
## Fichiers supprimés
|
||
|
||
```text
|
||
aucun
|
||
```
|
||
|
||
## Version Cargo
|
||
|
||
Aucun code/build/runtime/config n’est modifié. Conformément à l’autorisation explicite du prompt 028 pour ce premier gate doc-only :
|
||
|
||
```text
|
||
workspace.package.version reste 0.3.8
|
||
```
|
||
|
||
## Non inclus
|
||
|
||
```text
|
||
aucune crate ksp-worker-api créée
|
||
aucun Rust modifié
|
||
aucun Cargo.toml modifié
|
||
aucun worker RawTransaction
|
||
aucune modification Transport/Config/Store
|
||
aucun endpoint/profil Helius
|
||
aucun nouveau secret
|
||
aucun audit provider courant déclaré réalisé
|
||
aucune analyse fonctionnelle kbot3 encore réalisée
|
||
aucune modification CHANGELOG/ROADMAP
|
||
```
|
||
|
||
## Validations non exécutées
|
||
|
||
```text
|
||
cargo fmt/check/clippy/test/tree : cargo absent du sandbox
|
||
sources externes RAW : réservées après freeze Worker API
|
||
smoke réseau/provider : hors pre.001
|
||
```
|
||
|
||
## Questions différées
|
||
|
||
```text
|
||
WorkerHandle/start/join générique
|
||
registry/factory/restart generation
|
||
reconfiguration live
|
||
remote protocol/IPC
|
||
serialization commune
|
||
metrics métier universelles
|
||
```
|
||
|
||
Elles ne sont pas nécessaires au contrat générique V1 et ne doivent pas élargir `pre.002` sans preuve.
|