v0.3.9-pre.001
This commit is contained in:
567
docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
Normal file
567
docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
Normal file
@@ -0,0 +1,567 @@
|
||||
<!-- file: docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Plan v0.3.9 — Worker API générique + audit RAW Transaction
|
||||
|
||||
## 1. But de la version
|
||||
|
||||
La version `0.3.9` a deux responsabilités successives et volontairement séparées :
|
||||
|
||||
```text
|
||||
1. stabiliser ksp-worker-api comme lifecycle API générique de services continus ;
|
||||
2. seulement après sa freeze fonctionnelle, auditer exhaustivement les voies d’acquisition RawTransaction afin de préparer 0.3.10.
|
||||
```
|
||||
|
||||
Aucun besoin Solana, provider, Store, endpoint, replay ou backfill ne doit influencer le contrat générique de `ksp-worker-api` avant sa freeze.
|
||||
|
||||
## 2. Base autoritaire et vérification d’ouverture
|
||||
|
||||
Base fournie et vérifiée le 4 septembre 2026 :
|
||||
|
||||
```text
|
||||
archive KSP : 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
|
||||
```
|
||||
|
||||
Preuves d’archive :
|
||||
|
||||
```text
|
||||
KSP SHA-256 = b3a34a3dfd56fac1eef3d23f13631ff001338b612834488038cf259112c63624
|
||||
KSP entries = 1809
|
||||
KSP raw bytes = 19667131
|
||||
KSP unzip -t = PASS
|
||||
|
||||
kbot3 SHA-256 = ee47643b9f8b582ee8db97b2381ec107e45aef8c009fee44757531514615d318
|
||||
kbot3 entries = 2501
|
||||
kbot3 raw bytes = 37467702
|
||||
kbot3 unzip -t = PASS
|
||||
```
|
||||
|
||||
Les deux ZIP ont été contrôlés sans entrée absolue, traversal, lien symbolique, `target/`, `node_modules/`, `.git/`, `Cargo.lock` ou `.env` livré.
|
||||
|
||||
Le ZIP stable ne contient volontairement pas les métadonnées Git ; le tag `v0.3.8` n’est donc pas réinspectable depuis `.git`. La base est néanmoins admissible selon le prompt car l’opérateur l’a fournie explicitement comme archive stable, sa version Cargo vaut `0.3.8` et son `rel.001` exige puis décrit le tag stable `v0.3.8`.
|
||||
|
||||
### 2.1 Membres structurants confirmés
|
||||
|
||||
```text
|
||||
ksp-app-store-desk
|
||||
ksp-job-api
|
||||
ksp-job-backfill-lib
|
||||
ksp-onchain-transport-lib
|
||||
ksp-config-lib
|
||||
ksp-store-api
|
||||
ksp-store-lib
|
||||
ksp-store-postgres-lib
|
||||
```
|
||||
|
||||
Le workspace stable comporte 18 membres et ne contient pas encore `ksp-worker-api`.
|
||||
|
||||
### 2.2 Baseline locale avant modification
|
||||
|
||||
Exécuté sur l’archive KSP inchangée :
|
||||
|
||||
```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` n’est pas installé dans l’environnement d’assemblage. Les commandes Cargo de baseline, dont `cargo fmt --all -- --check`, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo tree -p ksp-job-api`, sont donc **non exécutées ici et non déclarées PASS**. La preuve stable du delta `0.3.8-rel.001` rappelle qu’un gate opérateur complet avait été fermé en amont ; elle ne remplace pas une exécution locale de cette session.
|
||||
|
||||
## 3. Sources internes lues avant décision
|
||||
|
||||
Les règles et architectures demandées par le prompt ont été auditées avant la présente planification :
|
||||
|
||||
```text
|
||||
RULES.md
|
||||
ROADMAP.md
|
||||
CHANGELOG.md
|
||||
docs/000-README.md
|
||||
|
||||
docs/rules/RULES_GENERAL.md
|
||||
docs/rules/RULES_KSP.md
|
||||
docs/rules/RULES_RUST.md
|
||||
docs/rules/RULES_DEPENDENCIES.md
|
||||
docs/rules/RULES_DOCUMENTATION.md
|
||||
docs/rules/FILE_CONTRACTS.md
|
||||
docs/rules/VERSION_WORKFLOW.md
|
||||
docs/rules/PROMPT_STRUCTURE.md
|
||||
|
||||
docs/architecture/000-README.md
|
||||
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
|
||||
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||||
docs/architecture/004-COMPONENT_INVENTORY.md
|
||||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
|
||||
|
||||
ksp-job-api manifest/README/USAGE/src/tests
|
||||
docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md
|
||||
docs/validation/023-V0_3_6_JOB_API_BACKFILL.md
|
||||
|
||||
ksp-job-backfill-lib README/USAGE/src/tests
|
||||
ksp-app-backfill-desk README/USAGE
|
||||
docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md
|
||||
docs/validation/024-V0_3_7_BACKFILL_DESK.md
|
||||
```
|
||||
|
||||
Les headers/version des fichiers normatifs et architecturaux exigés sont présents et cohérents. Aucun document stable antérieur n’est modifié dans `pre.001`.
|
||||
|
||||
## 4. Frontière Worker / Job décidée
|
||||
|
||||
Règle sémantique de base :
|
||||
|
||||
```text
|
||||
Job = traitement borné/terminable, fin normale et outcome attendus.
|
||||
Worker = service continu, Running peut durer indéfiniment, arrêt normal sans notion de completion.
|
||||
```
|
||||
|
||||
`ksp-job-api` est une référence de **propriétés déjà prouvées**, pas un parent nominal de Worker et pas une dépendance.
|
||||
|
||||
| Concept Job audité | Propriété générique | Décision Worker API | Motif |
|
||||
|---------------------------|-----------------------------------------|---------------------------------|--------------------------------------------------------|
|
||||
| JobId borné | oui | WorkerId propre | même propriété, identité sémantiquement distincte |
|
||||
| JobKindCode borné | oui | WorkerKindCode propre | famille stable utile au contrôle sans dépendre de Job |
|
||||
| Created | oui | WorkerState::Created | état passif avant démarrage |
|
||||
| Running | oui | WorkerState::Running | un Worker peut y rester indéfiniment |
|
||||
| Cancelling | non nominalement | WorkerState::Stopping | un service s’arrête, il ne termine pas un Job annulé |
|
||||
| Completed + JobCompletion | non | interdit | un Worker continu n’a pas de completion normale |
|
||||
| Cancelled | non | WorkerState::Stopped | arrêt normal distinct d’une annulation de traitement |
|
||||
| Failed | partiellement | WorkerState::Faulted(ErrorCode) | fault terminal avec diagnostic statique sûr |
|
||||
| Cancellation token | oui conceptuellement | WorkerStopToken | intention coopérative partagée et idempotente |
|
||||
| Notification générique S | latest-value oui, payload générique non | WorkerSnapshot fixe | évite payload arbitraire et simplifie le control plane |
|
||||
| Sequence monotone | oui | WorkerSnapshotSequence | resynchronisation sans queue |
|
||||
| SnapshotSource | oui | WorkerSnapshotSource | lecture current + wait_for_change runtime-neutral |
|
||||
| Terminal immuable | oui | retenu | ancien handle/source ne peut pas être réactivé |
|
||||
| Checkpoint / resume | non | interdit | spécifique aux Jobs/backfills |
|
||||
| Outcome / résultat | non | interdit | spécifique à un traitement terminable |
|
||||
| Core-only | oui | retenu | API passive et dependency firewall minimal |
|
||||
|
||||
Conséquence : une duplication limitée de petites primitives (`WorkerId`, séquence, token stop) est intentionnelle. Elle maintient deux vocabulaires de lifecycle indépendants et évite qu’une future évolution Job force Worker ou inversement.
|
||||
|
||||
## 5. Surface publique Worker API prévue
|
||||
|
||||
`pre.002` doit ouvrir uniquement le noyau suivant, sous réserve d’un défaut réel découvert lors de sa matérialisation :
|
||||
|
||||
```text
|
||||
WorkerId
|
||||
WorkerKindCode
|
||||
MAX_WORKER_ID_BYTES = 128
|
||||
MAX_WORKER_KIND_CODE_BYTES = 128
|
||||
|
||||
WorkerState
|
||||
WorkerHealth
|
||||
WorkerActivity
|
||||
WorkerLifecycle
|
||||
|
||||
WorkerStopToken
|
||||
|
||||
WorkerSnapshotSequence
|
||||
WorkerSnapshot
|
||||
WorkerSnapshotFuture<'a>
|
||||
WorkerSnapshotSource
|
||||
|
||||
ERROR_CODE_WORKER_ID_INVALID
|
||||
ERROR_CODE_WORKER_KIND_INVALID
|
||||
ERROR_CODE_WORKER_TRANSITION_INVALID
|
||||
ERROR_CODE_WORKER_SNAPSHOT_SEQUENCE_EXHAUSTED
|
||||
|
||||
reexports Core : Error, ErrorCode, ErrorContext, Result
|
||||
```
|
||||
|
||||
Modules de production prévus :
|
||||
|
||||
```text
|
||||
src/lib.rs
|
||||
src/error.rs
|
||||
src/identity.rs
|
||||
src/lifecycle.rs
|
||||
src/snapshot.rs
|
||||
src/stop.rs
|
||||
```
|
||||
|
||||
La façade reste crate-root ; aucun `pub mod`.
|
||||
|
||||
### 5.1 Identité
|
||||
|
||||
`WorkerId` et `WorkerKindCode` utilisent un contrat borné analogue dans ses propriétés à Job mais avec leurs propres types :
|
||||
|
||||
```text
|
||||
non vide
|
||||
maximum 128 octets
|
||||
alphabet ASCII sûr : A-Z a-z 0-9 _ - . :
|
||||
aucun slash, whitespace ou Unicode libre
|
||||
WorkerId Debug = redacted
|
||||
WorkerKindCode Debug = valeur validée sûre
|
||||
```
|
||||
|
||||
`WorkerId` identifie l’instance logique observée par un lifecycle/source donné. La V1 ne définit aucune notion de génération/restart et ne rebinde jamais un ancien handle/source terminal vers une nouvelle exécution.
|
||||
|
||||
## 6. Lifecycle exact retenu
|
||||
|
||||
États :
|
||||
|
||||
```text
|
||||
Created
|
||||
Starting
|
||||
Running
|
||||
Stopping
|
||||
Stopped
|
||||
Faulted(ErrorCode)
|
||||
```
|
||||
|
||||
| État source | Transitions autorisées | Transitions interdites notables |
|
||||
|---------------|----------------------------------|-----------------------------------|
|
||||
| Created | Starting, Stopped | Running direct, Stopping, Faulted |
|
||||
| Starting | Running, Stopping, Faulted(code) | Stopped direct, Created |
|
||||
| Running | Stopping, Faulted(code) | Starting, Stopped direct |
|
||||
| Stopping | Stopped, Faulted(code) | Running, Starting |
|
||||
| Stopped | aucune | toutes |
|
||||
| Faulted(code) | aucune | toutes |
|
||||
|
||||
Décisions :
|
||||
|
||||
- `Created -> Stopped` représente un arrêt demandé avant démarrage effectif ;
|
||||
- `Starting` et `Stopping` sont nécessaires parce que start/shutdown peuvent avoir une durée non nulle ;
|
||||
- `Running` n’a aucune notion de completion ;
|
||||
- `Faulted(ErrorCode)` ne conserve qu’un identifiant d’erreur KSP statique, jamais un message arbitraire ni un `Box<dyn Error>` ;
|
||||
- `Stopped` et `Faulted` sont terminaux et immuables ;
|
||||
- `WorkerLifecycle` est producteur-owned et non cloneable ; les clones éventuels concernent le token de stop et la source de snapshot, pas l’autorité de transition ;
|
||||
- une transition invalide retourne une erreur stable et laisse l’état inchangé ;
|
||||
- les appels lifecycle répétés ne sont pas silencieusement idempotents : l’idempotence appartient à l’intention de stop, pas à la state machine.
|
||||
|
||||
### 6.1 Race stop / fault
|
||||
|
||||
Le modèle ne crée pas de mutation concurrente de `WorkerLifecycle`. Le runtime concret possède une seule autorité de transition et arbitre les événements. Les ordres légaux sont explicitement testables :
|
||||
|
||||
```text
|
||||
Running -> Faulted => terminal Faulted, stop lifecycle ultérieur rejeté
|
||||
Running -> Stopping -> Faulted => terminal Faulted, Stopped ultérieur rejeté
|
||||
Running -> Stopping -> Stopped => terminal Stopped, Faulted ultérieur rejeté
|
||||
```
|
||||
|
||||
Le premier état terminal **validement enregistré** gagne. Un `WorkerStopToken` demandé après terminal peut conserver l’intention atomique mais ne réanime ni ne transforme l’état terminal.
|
||||
|
||||
## 7. Health et activity
|
||||
|
||||
`health` est distinct du lifecycle. Il décrit la qualité opérationnelle observée, pas la phase du service :
|
||||
|
||||
```text
|
||||
WorkerHealth::Unknown
|
||||
WorkerHealth::Healthy
|
||||
WorkerHealth::Degraded
|
||||
WorkerHealth::Unhealthy
|
||||
```
|
||||
|
||||
`activity` est volontairement plus faible qu’un progrès de Job :
|
||||
|
||||
```text
|
||||
WorkerActivity::Unknown
|
||||
WorkerActivity::Idle
|
||||
WorkerActivity::Active
|
||||
```
|
||||
|
||||
Aucun `current/total`, pourcentage, ETA, compteur métier, slot, signature, backlog ou débit n’entre dans Worker API. Un worker concret peut publier ses métriques métier via sa propre API/snapshot sans les injecter dans le snapshot commun.
|
||||
|
||||
Le lifecycle reste autoritaire pour savoir si le service est terminal ; health/activity ne doivent jamais être interprétés comme une seconde state machine.
|
||||
|
||||
## 8. Snapshot latest-value décidé
|
||||
|
||||
Contrairement à `JobNotification<S>`, Worker V1 retient un snapshot **fixe et non générique** afin que le control plane puisse lire la même forme pour tous les workers et afin d’empêcher un payload arbitraire dans le contrat commun.
|
||||
|
||||
`WorkerSnapshot` contient uniquement :
|
||||
|
||||
```text
|
||||
WorkerId
|
||||
WorkerKindCode
|
||||
WorkerSnapshotSequence
|
||||
WorkerState
|
||||
WorkerHealth
|
||||
WorkerActivity
|
||||
```
|
||||
|
||||
Aucune `String` diagnostique libre, aucun provider, endpoint, payload, transaction, slot, Store reference ou secret.
|
||||
|
||||
### 8.1 Séquence
|
||||
|
||||
`WorkerSnapshotSequence` :
|
||||
|
||||
```text
|
||||
initial = 0
|
||||
next = checked_add(1)
|
||||
aucun wrap silencieux
|
||||
is_after(observed) pour la resynchronisation
|
||||
```
|
||||
|
||||
Toute modification publiée du snapshot commun avance la séquence exactement une fois. Le détail de stockage/wakeup reste au runtime concret.
|
||||
|
||||
### 8.2 Source
|
||||
|
||||
Contrat prévu :
|
||||
|
||||
```text
|
||||
trait WorkerSnapshotSource: Send + Sync
|
||||
current() -> WorkerSnapshot
|
||||
wait_for_change(observed: WorkerSnapshotSequence) -> WorkerSnapshotFuture<'_>
|
||||
```
|
||||
|
||||
Le trait doit être object-safe pour permettre `&dyn WorkerSnapshotSource` ou une composition équivalente sans imposer Tokio.
|
||||
|
||||
Sémantique latest-value :
|
||||
|
||||
```text
|
||||
pas de queue d’événements
|
||||
pas de callback producteur
|
||||
les updates intermédiaires peuvent être coalescées
|
||||
un listener lent reçoit le snapshot courant le plus récent
|
||||
plusieurs listeners restent indépendants
|
||||
un listener tardif commence par current()
|
||||
le snapshot terminal reste lisible tant que la source existe
|
||||
```
|
||||
|
||||
Un appel `wait_for_change` n’est attendu qu’après inspection de `current()` et ne doit pas produire de boucle artificielle sur une séquence terminale déjà observée.
|
||||
|
||||
## 9. Stop coopératif
|
||||
|
||||
`WorkerStopToken` est une primitive runtime-neutral cloneable fondée sur une intention atomique :
|
||||
|
||||
```text
|
||||
request_stop() -> true uniquement pour la première demande partagée
|
||||
is_stop_requested() -> bool
|
||||
```
|
||||
|
||||
La demande est bornée au sens API : opération atomique locale, non bloquante, sans attente réseau/process/thread. Elle **ne garantit pas** que le worker concret s’arrête dans un délai donné. Timeout, drain, join, retry et politique de shutdown appartiennent au runtime/caller.
|
||||
|
||||
Le token ne modifie pas directement `WorkerLifecycle`; le producteur observe l’intention puis publie `Stopping`/terminal selon sa politique concrète.
|
||||
|
||||
## 10. Restart et supervision
|
||||
|
||||
La V1 ne contient pas :
|
||||
|
||||
```text
|
||||
restart()
|
||||
restart policy
|
||||
retry/backoff policy
|
||||
scheduler
|
||||
process manager
|
||||
remote protocol
|
||||
registry global
|
||||
WorkerHandle générique possédant le runtime
|
||||
```
|
||||
|
||||
Restart/recreate appartient au caller ou au futur `ksp-worker-control-lib`. Un lifecycle/source terminal ne redevient jamais Running et n’est jamais rebinding vers une nouvelle instance. Cette règle ferme la race « old handle observes a restarted worker » sans introduire prématurément une génération globale.
|
||||
|
||||
Un futur control plane peut composer les primitives `WorkerId`/kind/snapshot/stop avec ses propres factories et règles de remplacement.
|
||||
|
||||
## 11. Dépendances exactes
|
||||
|
||||
Cible décidée :
|
||||
|
||||
```text
|
||||
ksp-worker-api -> ksp-core-lib
|
||||
```
|
||||
|
||||
| Dépendance | Statut prévu | Justification |
|
||||
|-------------------------------|--------------|---------------------------------------------------------------|
|
||||
| ksp-core-lib | REQUISE | Error, ErrorCode, ErrorContext et Result communs |
|
||||
| ksp-job-api | INTERDITE | lifecycle Job distinct ; réutilisation seulement conceptuelle |
|
||||
| ksp-interface-lib | INTERDITE | aucun événement wire/domain requis |
|
||||
| ksp-config-lib | INTERDITE | Config/secrets hors API passive |
|
||||
| ksp-logging-lib | INTERDITE | aucun comportement runtime à instrumenter |
|
||||
| ksp-onchain-transport-lib | INTERDITE | aucun transport dans le contrat Worker |
|
||||
| ksp-store-api / ksp-store-lib | INTERDITES | aucune persistence dans le lifecycle commun |
|
||||
| tokio / futures | INTERDITES | std::future suffit au contrat d’attente abstrait |
|
||||
| serde | INTERDITE | aucun wire/serialization commun imposé |
|
||||
| Tauri / provider SDK | INTERDITS | contrôle UI/provider hors API |
|
||||
|
||||
Le manifeste prévu ne comporte ni feature, ni dev-dependency, ni build-dependency tant qu’un besoin réel n’est pas démontré. Les tests doivent fonctionner avec `std` + dépendance normale Core.
|
||||
|
||||
## 12. Error codes et Debug
|
||||
|
||||
Domaine prévu :
|
||||
|
||||
```text
|
||||
worker_api
|
||||
```
|
||||
|
||||
Codes prévus :
|
||||
|
||||
```text
|
||||
worker_id_invalid
|
||||
worker_kind_invalid
|
||||
worker_transition_invalid
|
||||
worker_snapshot_sequence_exhausted
|
||||
```
|
||||
|
||||
Les erreurs d’identité ne recopient pas la valeur hostile dans message/context ; elles indiquent uniquement le champ fautif. Les erreurs de transition exposent seulement les codes d’état source/cible. `Faulted(ErrorCode)` expose un code statique et non une chaîne externe.
|
||||
|
||||
Debug :
|
||||
|
||||
```text
|
||||
WorkerId -> valeur masquée
|
||||
WorkerKindCode -> code sûr borné autorisé
|
||||
WorkerLifecycle -> id masqué, kind/state sûrs
|
||||
WorkerStopToken -> bool stop_requested uniquement
|
||||
WorkerSnapshot -> id masqué, autres champs statiques/bornés
|
||||
```
|
||||
|
||||
## 13. Threat map
|
||||
|
||||
| Risque | Mesure décidée | Preuve prévue |
|
||||
|-------------------------------------|------------------------------------------------------------------------|-----------------------------------|
|
||||
| queue de notifications non bornée | latest-value unique, aucun backlog événementiel dans l’API | canarie source + audit production |
|
||||
| listener lent bloque producteur | coalescing ; listener se resynchronise sur current | listeners lents/indépendants |
|
||||
| snapshot périmé | sequence monotone attachée à toute valeur publiée | late listener + is_after |
|
||||
| wrap sequence | checked_add et erreur explicite | test exhaustion |
|
||||
| stop vs fault | lifecycle producteur unique ; premier terminal valide gagne | matrice et ordres adversariaux |
|
||||
| stop répété | WorkerStopToken atomique idempotent | multi-clone / cross-thread |
|
||||
| restart réanime ancien handle | terminal immutable ; nouvelle instance/source, aucun rebind | canarie terminal + documentation |
|
||||
| fuite identité | alphabet borné ; Debug WorkerId redacted | hostile marker |
|
||||
| payload/secret dans snapshot commun | snapshot fixe sans String/payload générique | inventaire de champs + Debug |
|
||||
| erreur externe dans état | Faulted ne retient qu’un ErrorCode statique | surface publique exacte |
|
||||
| confusion health/lifecycle | dimensions séparées ; lifecycle terminal reste autoritaire | tests indépendance |
|
||||
| fausse progression finie | aucun percent/total générique ; activité Unknown/Idle/Active seulement | inventaire API |
|
||||
| contamination Solana/Store/Config | Core-only + canaries lexicales/dependencies | dependency_boundary |
|
||||
| runtime implicite | aucun spawn/thread/channel Tokio possédé par API | manifest/source firewall |
|
||||
|
||||
## 14. Tests planifiés
|
||||
|
||||
### 14.1 Unit tests
|
||||
|
||||
```text
|
||||
identity exact bounds : 0, 1, 128, 129 octets
|
||||
alphabet hostile : whitespace, slash, backslash, Unicode, control chars
|
||||
lifecycle transition matrix exhaustive
|
||||
invalid transition leaves state unchanged
|
||||
Stopped/Faulted immutable sous tous les mutateurs
|
||||
Faulted conserve uniquement ErrorCode
|
||||
stop token first-wins/idempotent/shared
|
||||
stop token Send + Sync / cross-thread
|
||||
snapshot sequence initial/next/is_after/exhaustion
|
||||
health/activity stable safe codes si helpers exposés
|
||||
Debug hostile marker absent
|
||||
```
|
||||
|
||||
### 14.2 Integration/public API
|
||||
|
||||
```text
|
||||
construction exclusivement depuis crate root
|
||||
ErrorCode constants exacts
|
||||
bounds publics exacts
|
||||
WorkerSnapshotSource implémentable depuis une crate externe
|
||||
WorkerSnapshotSource object-safe
|
||||
source custom std-only sans Tokio
|
||||
slow + independent listeners resync vers latest value
|
||||
late listener current puis wait
|
||||
terminal current reste disponible
|
||||
Send/Sync des primitives promises
|
||||
```
|
||||
|
||||
### 14.3 Dependency/release completeness
|
||||
|
||||
```text
|
||||
manifest dependency exacte = ksp-core-lib uniquement
|
||||
aucune feature/dev/build dependency
|
||||
aucun tokio/futures/serde/tracing/Tauri
|
||||
aucun ksp-job-api/Config/Interface/Transport/Store
|
||||
aucun RawTransaction/slot/provider/endpoint/backfill/checkpoint
|
||||
modules de production exacts
|
||||
exports crate-root exacts
|
||||
aucun pub mod
|
||||
```
|
||||
|
||||
Les tests ne créent aucun runtime KSP fictif. Une implémentation de test peut utiliser `std::future::ready`, `Arc` et primitives `std` uniquement.
|
||||
|
||||
## 15. Questions explicitement différées
|
||||
|
||||
Les points suivants ne bloquent pas Worker API V1 et ne doivent pas être ouverts en `pre.002` par anticipation :
|
||||
|
||||
```text
|
||||
WorkerHandle générique de start/join
|
||||
registry/factory commune
|
||||
reconfiguration live
|
||||
generation/restart identity globale
|
||||
remote proxy/protocol/IPC
|
||||
serialization du snapshot commun
|
||||
metrics/rates/counters métier universels
|
||||
control-plane persistence
|
||||
process ownership
|
||||
```
|
||||
|
||||
Ils ne deviennent candidats que lorsqu’au moins plusieurs workers ou le futur control plane prouvent un besoin transverse.
|
||||
|
||||
## 16. Audit RAW Transaction : position et owner documentaire
|
||||
|
||||
Aucune analyse fonctionnelle de kbot3 ni réaudit provider courant n’est effectué dans `pre.001`, conformément au séquencement du prompt.
|
||||
|
||||
Après freeze fonctionnelle de `ksp-worker-api` en `pre.003`, l’audit RAW est scindé pour respecter le budget de tranche. Son owner durable prévu est :
|
||||
|
||||
```text
|
||||
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
|
||||
```
|
||||
|
||||
Ce document séparera :
|
||||
|
||||
```text
|
||||
partie durable : taxonomy capabilities/roles/combinations/convergence
|
||||
partie audit daté : disponibilité provider, quotas, replay, tiers et liens sources primaires
|
||||
handoff : gaps Transport/Config 0.3.10 et applicability Backfill 0.3.12
|
||||
```
|
||||
|
||||
Ce choix évite de transformer le plan de release en registre provider tout en donnant à `0.3.10` et `0.3.12` une référence architecturale réauditable. L’index architecture ne sera synchronisé qu’au moment où ce document sera réellement créé, puis réconcilié dans le couloir documentaire final.
|
||||
|
||||
kbot3 ne sera alors utilisé que pour inventorier des comportements historiques. Aucun code, DTO, Config, URL, dependency ou version n’en sera repris.
|
||||
|
||||
## 17. Prévision souple recalibrée
|
||||
|
||||
Le `pre.004` unique imaginé par le prompt est scindé en trois tranches d’audit/synthèse : un audit Solana/KSP, un audit provider/kbot3, puis une synthèse. Un audit externe exhaustif Solana + Helius + Yellowstone + providers + KSP + mainnet naming dans une seule tranche dépasserait vraisemblablement le budget normatif de 15-20 minutes.
|
||||
|
||||
| Tranche | Objet | Budget de planification | Sortie |
|
||||
|---------|-----------------------------------------------------------------|-------------------------|--------------------------------------------------------|
|
||||
| pre.001 | audit, architecture, threat map, plan/tests | 15-20 min | présente livraison doc-only |
|
||||
| pre.002 | crate + contrats Worker API décidés | 15-20 min | noyau + tests unit/public/dependency |
|
||||
| pre.003 | hardening, races, object-safety, impl externe, freeze | 15-20 min | Worker API fonctionnellement fermée |
|
||||
| pre.004 | audit RAW A : Solana standard + KSP Transport/Store/Config | 15-20 min | capabilities/roles/gaps internes |
|
||||
| pre.005 | audit RAW B : Helius, Yellowstone/providers + kbot3 fonctionnel | 15-20 min | preuves primaires, quotas/replay/disponibilité |
|
||||
| pre.006 | synthèse RAW multi-source + handoff 0.3.10/0.3.12 | 15-20 min | matrice finale, combinaisons, gaps et stratégie réseau |
|
||||
| pre.007 | gate technique final | 10-15 min | workspace/worker-api/trees/duplicates verts |
|
||||
| pre.008 | réconciliation documentaire finale | 10-15 min | README/USAGE/plan/validation/architecture cohérents |
|
||||
| pre.009 | préparation de publication | 5-10 min | prompt 0.3.10 + CHANGELOG + ROADMAP + Cargo + delta |
|
||||
| rel.001 | publication mécanique stable | 5-10 min | v0.3.9 sans rattrapage |
|
||||
|
||||
Les numéros restent souples. Un défaut réel peut ouvrir `pre.NNN-fix.MMM` dans le même couloir ou forcer un split supplémentaire. Les responsabilités `gate technique -> réconciliation documentaire -> préparation de publication` restent séparées.
|
||||
|
||||
## 18. Versioning de `pre.001`
|
||||
|
||||
La présente tranche est strictement documentaire : nouveau plan, nouvelle validation et nouveau delta. Elle ne modifie aucun code/build/runtime/configuration et conserve donc explicitement :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.8
|
||||
```
|
||||
|
||||
Cette exception de démarrage est explicitement autorisée par le prompt 028 et cohérente avec `VER-ID-008`. Le premier changement Rust de `pre.002` portera la version technique correspondant à sa livraison selon le workflow KSP.
|
||||
|
||||
## 19. Gate de sortie `pre.001`
|
||||
|
||||
La tranche est fermée architecturalement lorsque les points suivants sont présents dans le plan/validation :
|
||||
|
||||
```text
|
||||
architecture Worker API décidée
|
||||
state/health/activity/snapshot/stop décidés
|
||||
surface publique prévue
|
||||
Core-only exact dependency map
|
||||
questions différées listées
|
||||
threat map
|
||||
plan de tests
|
||||
prévision souple recalibrée
|
||||
audit RAW positionné après freeze Worker API
|
||||
aucun code worker concret commencé
|
||||
```
|
||||
|
||||
Les gates Cargo restent à exécuter par l’opérateur dans un environnement Rust. Leur absence locale n’est pas masquée par les audits Python.
|
||||
Reference in New Issue
Block a user