From 2f0eb316f5d61c5b639d25e6e1286dd8ddff7f52 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sat, 29 Aug 2026 11:22:29 +0200 Subject: [PATCH] v0.3.1-pre.009 --- Cargo.toml | 4 +- deltas/0.3.1/pre.009.md | 123 ++++++++ docs/000-README.md | 12 +- docs/IDEAS.md | 12 +- docs/architecture/003-COMPONENT_CONTRACTS.md | 10 +- docs/architecture/004-COMPONENT_INVENTORY.md | 75 ++--- docs/architecture/005-DEPENDENCY_GRAPH.md | 16 +- .../009-ACQUISITION_WORKERS_AND_JOBS.md | 10 +- ...010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md | 5 +- docs/plans/000-README.md | 7 +- docs/plans/022-V0_3_1_STORE_RAW_PLAN.md | 90 +++--- docs/validation/000-README.md | 7 +- docs/validation/018-V0_3_1_STORE_RAW.md | 285 ++++++++++-------- 13 files changed, 412 insertions(+), 244 deletions(-) create mode 100644 deltas/0.3.1/pre.009.md diff --git a/Cargo.toml b/Cargo.toml index ff7bab1..7bdd54a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 328 +# version: 329 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.3.1-pre.8" +version = "0.3.1-pre.9" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.3.1/pre.009.md b/deltas/0.3.1/pre.009.md new file mode 100644 index 0000000..2abc788 --- /dev/null +++ b/deltas/0.3.1/pre.009.md @@ -0,0 +1,123 @@ + + + +# Delta `0.3.1-pre.009` — Réconciliation documentaire finale Store API RAW + +## Base requise + +```text +0.3.1-pre.008 +``` + +Le gate opérateur de cette base a été exécuté après `cargo clean` et passe les audits Rust/Markdown, `cargo check --workspace`, Clippy, les tests ciblés des crates présentes, `cargo test --workspace`, les trois builds Tauri Linux et les graphes Cargo. La commande ciblée initiale `cargo test -p ksp-program-lib` utilisait un nom de package inexistant ; `cargo test -p ksp-program-api` a ensuite été exécuté séparément et passe intégralement. + +## Objectif + +Fermer la réconciliation documentaire durable de `0.3.1` sans développement fonctionnel nouveau et sans empiéter sur la lane de publication `pre.010`. + +La tranche doit refléter la surface réellement matérialisée de `ksp-store-api` : + +```text +RawTransaction / RawTransactionObservation +RawAccountState / RawAccountObservation +primitives RAW/provenance/format/hash/timestamps +queries cursorisées sans plafond métier KSP arbitraire +outcomes d'idempotence/conflit +RawRetentionState + tombstone transactionnel +normal skip après purge + force rehydrate explicite +10 capabilities backend fines/object-safe +``` + +Elle doit également figer explicitement les reports : + +```text +TransactionStatusObservation +logs/slot/vote event-only contracts +StoreHealth/readiness runtime +type canonique dédié de wake-up persisté-data +processing ledger / backlog métier / executor policy +compression/archive physique +ksp-store-lib / PostgreSQL / std.store +N2 STRUCTURAL / N3 DECODED / N4 DOMAIN +``` + +## Fichiers ajoutés + +```text +deltas/0.3.1/pre.009.md +``` + +## Fichiers modifiés + +```text +Cargo.toml +docs/000-README.md +docs/IDEAS.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 +docs/plans/000-README.md +docs/plans/022-V0_3_1_STORE_RAW_PLAN.md +docs/validation/000-README.md +docs/validation/018-V0_3_1_STORE_RAW.md +``` + +## Fichiers supprimés + +Aucun. + +## Décisions réconciliées + +- `workspace.package.version` passe à `0.3.1-pre.9` conformément à `VER-ID-009` pour une nouvelle prerelease non-fix, même documentaire. +- `ksp-store-api` reste la seule crate Store de `0.3.1` et conserve uniquement `ksp-core-lib` comme dépendance runtime normale. +- Le health/readiness n'est pas un contrat RAW nécessaire et n'est pas inventé dans `ksp-store-api`; il est reporté au runtime `ksp-store-lib` de `0.3.2` si un consumer réel le justifie. +- `0.3.1` n'ajoute aucun type dédié de notification persistée-data. Les références durables existantes pourront alimenter un futur contrat de wake-up lorsqu'un publisher/consumer réel sera introduit. +- PostgreSQL `LISTEN/NOTIFY` n'est plus présenté comme mécanisme déjà retenu. Un futur publisher suit `persist -> commit -> publish`; un mécanisme PostgreSQL éventuel reste une optimisation backend/runtime et jamais un event bus possédé par Store. +- Les consumers runtime ordinaires — jobs, workers et apps — utilisent `ksp-store-lib` à partir de `0.3.2`; ils ne dépendent pas d'un backend concret. Les crates backend implémentent `ksp-store-api` et ne dépendent pas de `ksp-store-lib`. +- La pagination Store exprime navigation/cursorisation. Batch-size, priorité et policy de sélection appartiennent au worker/job/executor. Store ne crée aucun plafond métier global inférieur à une capacité physique disponible du backend. +- `RawAccountState` et `RawAccountObservation` sont réconciliés comme surface réellement livrée de `0.3.1`, tandis que `TransactionStatusObservation` reste explicitement reporté. +- Les index `docs/`, plans et validations référencent désormais `0.2.14` et la candidate `0.3.1` actuelle. +- `README.md` racine ne contient aucune surface Store détaillée devenue fausse et aucun README/USAGE propre à `ksp-store-api` n'existe encore ; aucun fichier artificiel n'est créé uniquement pour satisfaire une prévision ancienne. +- `CHANGELOG.md`, `ROADMAP.md` et `prompts/021-V0_3_2_START_PROMPT.md` restent strictement réservés à `pre.010`. +- La réconciliation globale du vocabulaire historique `CORE` vers le futur N2 `STRUCTURAL` n'est toujours pas ouverte dans les architectures générales ; elle reste reportée au moment où N2 sera réellement introduit. + +## Validations exécutées pendant la génération + +```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/0.3.1 +-> Markdown table audit: clean (186 table(s), 134 file(s)) +``` + +Les tableaux modifiés ont été réalignés selon le format RustRover attendu par l'audit Markdown. + +## Validations non exécutées pendant la génération + +L'environnement de génération ne dispose pas de la toolchain Cargo/Rust utilisée par l'opérateur ; aucun `cargo check`, Clippy ou test Cargo n'est revendiqué pour cette archive. + +Aucun code Rust, manifest de crate, ressource runtime, migration ou configuration exécutable n'est modifié dans cette tranche. Le gate lourd `pre.008` reste la preuve technique de référence ; `pre.009` nécessite seulement un re-gate ciblé après application. + +## 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.1 +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-store-api +``` + +Les builds Tauri et le `cargo test --workspace` complet n'ont pas besoin d'être rejoués pour cette tranche purement documentaire/versionnée si ce gate ciblé reste vert. + +## Questions ouvertes + +Aucune question bloquante pour `0.3.1`. + +Les décisions runtime/backend restantes appartiennent au prompt et à la release `0.3.2` : façade `ksp-store-lib`, backend `ksp-store-postgres-lib`, Config `std.store`, migrations et validation PostgreSQL réelle. diff --git a/docs/000-README.md b/docs/000-README.md index 31c52c6..d4079bf 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation KSP @@ -56,7 +56,9 @@ docs/ │ ├── 017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md │ ├── 018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md │ ├── 019-V0_2_12_SOL_PRICES_DESK_PLAN.md -│ └── 020-V0_2_13_INTERFACE_PLAN.md +│ ├── 020-V0_2_13_INTERFACE_PLAN.md +│ ├── 021-V0_2_14_PROGRAM_API_PLAN.md +│ └── 022-V0_3_1_STORE_RAW_PLAN.md ├── validation/ │ ├── 000-README.md │ ├── 001-V0_1_4_CONFIG_DESKTOP.md @@ -74,7 +76,9 @@ docs/ │ ├── 013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md │ ├── 014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md │ ├── 015-V0_2_12_SOL_PRICES_DESK.md -│ └── 016-V0_2_13_INTERFACE.md +│ ├── 016-V0_2_13_INTERFACE.md +│ ├── 017-V0_2_14_PROGRAM_API.md +│ └── 018-V0_3_1_STORE_RAW.md └── rules/ ├── FILE_CONTRACTS.md ├── PROMPT_STRUCTURE.md @@ -91,7 +95,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é ## Documents de planification -Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert la release stable `0.2.2 — HTTP Accounts + Tokens + Cluster`. Son plan clôturé [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) conserve l'audit et l'implémentation des 22 wrappers typés, tandis que [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) enregistre les validations déterministes, les graphes Cargo et les deux smokes Devnet passés avant publication. Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) a ouvert la release stable `0.2.3 — HTTP Transactions`. Son plan clôturé [`plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) conserve l'audit et l'implémentation des 11 wrappers ; le réaudit [`validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`](validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md) confirme la complétude des 37 wrappers HTTP typés et [`validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](validation/006-V0_2_3_HTTP_TRANSACTIONS.md) enregistre les validations finales, graphes Cargo et deux smokes Devnet passés avant publication. Le prompt [`../prompts/009-V0_2_4_START_PROMPT.md`](../prompts/009-V0_2_4_START_PROMPT.md) a ouvert la release stable `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale`. Son plan clôturé [`plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md) conserve l’implémentation des 15 wrappers et la compliance `52/52 + 14/14`; la matrice finale [`validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md`](validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md) enregistre le réaudit SIMD/inventaire, les canaries globales et les preuves opérateur avant publication. Le prompt [`../prompts/010-V0_2_5_START_PROMPT.md`](../prompts/010-V0_2_5_START_PROMPT.md), finalisé par `0.2.4-pre.009-fix.001`, ouvre `0.2.5 — Wallet foundation` sur la base stable `v0.2.4`. Son plan historique clôturé [`plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md`](plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md) part du gate `pre.001` (héritage, threat model offline, VIEW/OWNER indépendants et niveau B read-only), puis matérialise la crate en `pre.002`, le wire/transcript en `pre.003`, les primitives Argon2id/XChaCha20-Poly1305 en `pre.004`, les payloads/create/open en `pre.005`, la persistence en `pre.006`, l'administration/signature en `pre.007` et les adapters transfer en `pre.008`. `pre.009` ferme l'audit adversarial/interoperability/compliance dans [`validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md`](validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md) avant la documentation finale `pre.010` ; `pre.010` finalise [`../crates/ksp-wallet-lib/README.md`](../crates/ksp-wallet-lib/README.md), [`../crates/ksp-wallet-lib/USAGE.md`](../crates/ksp-wallet-lib/USAGE.md), la spec, les graphes et la matrice ; `pre.010-fix.001`–`fix.003` ferment ensuite la mise à niveau Dalek et la normalisation Rust/audit structurel. `0.2.5-rel.001` publie la release stable et [`../prompts/011-V0_2_6_START_PROMPT.md`](../prompts/011-V0_2_6_START_PROMPT.md) ouvre `0.2.6 — Wallet Desk`. Le gate `0.2.6-pre.001` est conservé dans [`plans/013-V0_2_6_WALLET_DESK_PLAN.md`](plans/013-V0_2_6_WALLET_DESK_PLAN.md) : il réaudite Config Desk et les APIs finales, retient le gabarit desktop, fixe `std.wallet`, la composition Config/Wallet/HTTP/Logging, les secrets `KSP_SECRET_WALLET_PASS_*`, les frontières VIEW/OWNER et la trajectoire de validation. `pre.002`–`pre.014` matérialisent ensuite le shell Tauri, Config Wallet/composite, inventory, create/open, balance HTTP, import/export, metadata, rotations, révocation VIEW forte, compliance et polish desktop. `pre.015` fige le wire binaire `.kspwallet` V2, `pre.016` matérialise les APIs génériques/versionnées et le runtime V2, puis `pre.017` ajoute la migration explicite OWNER-authentifiée V1 -> V2. `pre.018` ferme le runtime Tauri packagé Config/resources et la documentation candidate ; `pre.018-fix.001` corrige le canari d'ownership Config, après quoi le gate workspace et le build final Linux sont verts. `pre.018-fix.002` renforce uniquement le contrat de reprise `0.2.7`. `0.2.6-rel.001` publie cette surface stable et [`../prompts/012-V0_2_7_START_PROMPT.md`](../prompts/012-V0_2_7_START_PROMPT.md) devient le prochain point d'entrée. Le gate `0.2.7-pre.001` ouvre la release WebSocket standard dans [`plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md`](plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md) ; la matrice normative puis finale est conservée dans [`validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md`](validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md). `0.2.7-pre.014` ferme la candidate technique/documentaire après validation 18/18, smoke WebSocket Devnet et audit du graphe Cargo ; `pre.014-fix.001` renforce uniquement le prompt suivant. `0.2.7-rel.001` publie `0.2.7 — WebSocket Solana standard` stable et [`../prompts/013-V0_2_8_START_PROMPT.md`](../prompts/013-V0_2_8_START_PROMPT.md) ouvre `0.2.8 — Helius LaserStream WebSocket`. Le plan historique clôturé [`plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md`](plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md) et la matrice finale [`validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md`](validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md) conservent la release stable `0.2.8 — Helius LaserStream WebSocket` publiée par `rel.001` : protocol `helius_laserstream`, sept familles standard Helius (`account/logs/program/root/signature/slot/slotsUpdates`), extension `transactionSubscribe`/`transactionUnsubscribe`, `block/vote` absents, heartbeat Ping 60 s, Config/secrets redacted, lifecycle adversarial et graphes Cargo finaux validés. [`../prompts/014-V0_2_9_START_PROMPT.md`](../prompts/014-V0_2_9_START_PROMPT.md) devient le contrat actif pour ouvrir Yellowstone gRPC standard/provider-neutral depuis le tag stable `v0.2.8`. La release stable `0.2.9` est conservée dans [`plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) et [`validation/012-V0_2_9_YELLOWSTONE_GRPC.md`](validation/012-V0_2_9_YELLOWSTONE_GRPC.md) : stratégie proto Apache + client KSP/Tonic, moteur N1, standard N2, Config V3, profils PublicNode Mainnet/Testnet authentifiés par `x-token` secret et smoke live `Subscribe` validé sur les deux réseaux. La candidate `0.2.10 — OrbitFlare Yellowstone gRPC` est réconciliée dans [`plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) et [`validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) : Devnet `http://devnet.rpc.orbitflare.com:10000`, License Key `ORBIT-*` injectée comme metadata secrète `x-token`, Config Transport V3 inchangée, live `Subscribe -> Slot + Ping` passé, aucun overlay provider et aucun heartbeat supplémentaire. La candidate `0.2.11 — Off-chain price transport` est réconciliée dans [`plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) et [`validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) : SOL/USD V1, huit adapters REST sans SDK provider, décimal exact, registry/availability/rate limits possédés par Off-chain Transport, Config `std.offchain_transport`, refresh individuel/multiple provider-neutral et smoke live keyless final `7/7` après correction CoinMarketCap V2. [`../crates/ksp-offchain-transport-lib/README.md`](../crates/ksp-offchain-transport-lib/README.md) et [`../crates/ksp-offchain-transport-lib/USAGE.md`](../crates/ksp-offchain-transport-lib/USAGE.md) deviennent les références durables ; la future `ksp-app-solprices-desk` reste une HID sans logique provider. La release stable `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk` est conservée dans [`plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md) et [`validation/015-V0_2_12_SOL_PRICES_DESK.md`](validation/015-V0_2_12_SOL_PRICES_DESK.md) : `ksp-app-solprices-desk` fournit le refresh manuel row/selected/all provider-neutral, états/timestamps exacts et diagnostics sûrs sur ports 1434/1435 ; Wallet Desk réutilise `MarketPriceService::refresh_all` pendant le refresh balance pour afficher une moyenne SOL/USD consumer-owned et l'équivalent USD exact, sans provider concret ni fallback Off-chain. Les gates finaux workspace/live et les trois builds Tauri Linux sont verts avant publication. `0.2.13 — Interface / wire foundation` est réconciliée comme candidate dans [`plans/020-V0_2_13_INTERFACE_PLAN.md`](plans/020-V0_2_13_INTERFACE_PLAN.md) avec la matrice finale candidate [`validation/016-V0_2_13_INTERFACE.md`](validation/016-V0_2_13_INTERFACE.md) : `ksp-interface-lib` expose le `Pubkey` Core, `ProgramAccountMeta` et `ProgramInstruction`, bornés à `255` account metas et `10_240` bytes de data, avec façade crate-root exacte, diagnostics bornés, consumer externe et firewall `Interface -> Core` validés. Le gate technique final `pre.006` est intégralement vert ; [`../crates/ksp-interface-lib/README.md`](../crates/ksp-interface-lib/README.md) et [`../crates/ksp-interface-lib/USAGE.md`](../crates/ksp-interface-lib/USAGE.md) deviennent les références durables avant préparation de publication. Le prompt d’ouverture historique reste [`../prompts/018-V0_2_13_START_PROMPT.md`](../prompts/018-V0_2_13_START_PROMPT.md). `0.2.14 — Program API foundation` est réconciliée comme candidate dans [`plans/021-V0_2_14_PROGRAM_API_PLAN.md`](plans/021-V0_2_14_PROGRAM_API_PLAN.md) avec la matrice finale candidate [`validation/017-V0_2_14_PROGRAM_API.md`](validation/017-V0_2_14_PROGRAM_API.md) : `ksp-program-api` fournit une façade instruction-only ouverte, `ProgramInstructionRecognition`, `ProgramInstructionDecodeOutcome` et `ProgramInstructionDecoder`, avec output associé possédé par l’implémentation, Program Pubkeys opaques/non enregistrés acceptés, canari externe et firewall `Program API -> Core + Interface`. Le gate technique final `pre.006` est intégralement vert ; [`../crates/ksp-program-api/README.md`](../crates/ksp-program-api/README.md) et [`../crates/ksp-program-api/USAGE.md`](../crates/ksp-program-api/USAGE.md) deviennent les références durables avant préparation de publication. Le prompt d’ouverture historique reste [`../prompts/019-V0_2_14_START_PROMPT.md`](../prompts/019-V0_2_14_START_PROMPT.md). +Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert la release stable `0.2.2 — HTTP Accounts + Tokens + Cluster`. Son plan clôturé [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) conserve l'audit et l'implémentation des 22 wrappers typés, tandis que [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) enregistre les validations déterministes, les graphes Cargo et les deux smokes Devnet passés avant publication. Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) a ouvert la release stable `0.2.3 — HTTP Transactions`. Son plan clôturé [`plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) conserve l'audit et l'implémentation des 11 wrappers ; le réaudit [`validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`](validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md) confirme la complétude des 37 wrappers HTTP typés et [`validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](validation/006-V0_2_3_HTTP_TRANSACTIONS.md) enregistre les validations finales, graphes Cargo et deux smokes Devnet passés avant publication. Le prompt [`../prompts/009-V0_2_4_START_PROMPT.md`](../prompts/009-V0_2_4_START_PROMPT.md) a ouvert la release stable `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale`. Son plan clôturé [`plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md) conserve l’implémentation des 15 wrappers et la compliance `52/52 + 14/14`; la matrice finale [`validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md`](validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md) enregistre le réaudit SIMD/inventaire, les canaries globales et les preuves opérateur avant publication. Le prompt [`../prompts/010-V0_2_5_START_PROMPT.md`](../prompts/010-V0_2_5_START_PROMPT.md), finalisé par `0.2.4-pre.009-fix.001`, ouvre `0.2.5 — Wallet foundation` sur la base stable `v0.2.4`. Son plan historique clôturé [`plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md`](plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md) part du gate `pre.001` (héritage, threat model offline, VIEW/OWNER indépendants et niveau B read-only), puis matérialise la crate en `pre.002`, le wire/transcript en `pre.003`, les primitives Argon2id/XChaCha20-Poly1305 en `pre.004`, les payloads/create/open en `pre.005`, la persistence en `pre.006`, l'administration/signature en `pre.007` et les adapters transfer en `pre.008`. `pre.009` ferme l'audit adversarial/interoperability/compliance dans [`validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md`](validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md) avant la documentation finale `pre.010` ; `pre.010` finalise [`../crates/ksp-wallet-lib/README.md`](../crates/ksp-wallet-lib/README.md), [`../crates/ksp-wallet-lib/USAGE.md`](../crates/ksp-wallet-lib/USAGE.md), la spec, les graphes et la matrice ; `pre.010-fix.001`–`fix.003` ferment ensuite la mise à niveau Dalek et la normalisation Rust/audit structurel. `0.2.5-rel.001` publie la release stable et [`../prompts/011-V0_2_6_START_PROMPT.md`](../prompts/011-V0_2_6_START_PROMPT.md) ouvre `0.2.6 — Wallet Desk`. Le gate `0.2.6-pre.001` est conservé dans [`plans/013-V0_2_6_WALLET_DESK_PLAN.md`](plans/013-V0_2_6_WALLET_DESK_PLAN.md) : il réaudite Config Desk et les APIs finales, retient le gabarit desktop, fixe `std.wallet`, la composition Config/Wallet/HTTP/Logging, les secrets `KSP_SECRET_WALLET_PASS_*`, les frontières VIEW/OWNER et la trajectoire de validation. `pre.002`–`pre.014` matérialisent ensuite le shell Tauri, Config Wallet/composite, inventory, create/open, balance HTTP, import/export, metadata, rotations, révocation VIEW forte, compliance et polish desktop. `pre.015` fige le wire binaire `.kspwallet` V2, `pre.016` matérialise les APIs génériques/versionnées et le runtime V2, puis `pre.017` ajoute la migration explicite OWNER-authentifiée V1 -> V2. `pre.018` ferme le runtime Tauri packagé Config/resources et la documentation candidate ; `pre.018-fix.001` corrige le canari d'ownership Config, après quoi le gate workspace et le build final Linux sont verts. `pre.018-fix.002` renforce uniquement le contrat de reprise `0.2.7`. `0.2.6-rel.001` publie cette surface stable et [`../prompts/012-V0_2_7_START_PROMPT.md`](../prompts/012-V0_2_7_START_PROMPT.md) devient le prochain point d'entrée. Le gate `0.2.7-pre.001` ouvre la release WebSocket standard dans [`plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md`](plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md) ; la matrice normative puis finale est conservée dans [`validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md`](validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md). `0.2.7-pre.014` ferme la candidate technique/documentaire après validation 18/18, smoke WebSocket Devnet et audit du graphe Cargo ; `pre.014-fix.001` renforce uniquement le prompt suivant. `0.2.7-rel.001` publie `0.2.7 — WebSocket Solana standard` stable et [`../prompts/013-V0_2_8_START_PROMPT.md`](../prompts/013-V0_2_8_START_PROMPT.md) ouvre `0.2.8 — Helius LaserStream WebSocket`. Le plan historique clôturé [`plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md`](plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md) et la matrice finale [`validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md`](validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md) conservent la release stable `0.2.8 — Helius LaserStream WebSocket` publiée par `rel.001` : protocol `helius_laserstream`, sept familles standard Helius (`account/logs/program/root/signature/slot/slotsUpdates`), extension `transactionSubscribe`/`transactionUnsubscribe`, `block/vote` absents, heartbeat Ping 60 s, Config/secrets redacted, lifecycle adversarial et graphes Cargo finaux validés. [`../prompts/014-V0_2_9_START_PROMPT.md`](../prompts/014-V0_2_9_START_PROMPT.md) devient le contrat actif pour ouvrir Yellowstone gRPC standard/provider-neutral depuis le tag stable `v0.2.8`. La release stable `0.2.9` est conservée dans [`plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) et [`validation/012-V0_2_9_YELLOWSTONE_GRPC.md`](validation/012-V0_2_9_YELLOWSTONE_GRPC.md) : stratégie proto Apache + client KSP/Tonic, moteur N1, standard N2, Config V3, profils PublicNode Mainnet/Testnet authentifiés par `x-token` secret et smoke live `Subscribe` validé sur les deux réseaux. La candidate `0.2.10 — OrbitFlare Yellowstone gRPC` est réconciliée dans [`plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) et [`validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) : Devnet `http://devnet.rpc.orbitflare.com:10000`, License Key `ORBIT-*` injectée comme metadata secrète `x-token`, Config Transport V3 inchangée, live `Subscribe -> Slot + Ping` passé, aucun overlay provider et aucun heartbeat supplémentaire. La candidate `0.2.11 — Off-chain price transport` est réconciliée dans [`plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) et [`validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) : SOL/USD V1, huit adapters REST sans SDK provider, décimal exact, registry/availability/rate limits possédés par Off-chain Transport, Config `std.offchain_transport`, refresh individuel/multiple provider-neutral et smoke live keyless final `7/7` après correction CoinMarketCap V2. [`../crates/ksp-offchain-transport-lib/README.md`](../crates/ksp-offchain-transport-lib/README.md) et [`../crates/ksp-offchain-transport-lib/USAGE.md`](../crates/ksp-offchain-transport-lib/USAGE.md) deviennent les références durables ; la future `ksp-app-solprices-desk` reste une HID sans logique provider. La release stable `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk` est conservée dans [`plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md) et [`validation/015-V0_2_12_SOL_PRICES_DESK.md`](validation/015-V0_2_12_SOL_PRICES_DESK.md) : `ksp-app-solprices-desk` fournit le refresh manuel row/selected/all provider-neutral, états/timestamps exacts et diagnostics sûrs sur ports 1434/1435 ; Wallet Desk réutilise `MarketPriceService::refresh_all` pendant le refresh balance pour afficher une moyenne SOL/USD consumer-owned et l'équivalent USD exact, sans provider concret ni fallback Off-chain. Les gates finaux workspace/live et les trois builds Tauri Linux sont verts avant publication. `0.2.13 — Interface / wire foundation` est réconciliée comme candidate dans [`plans/020-V0_2_13_INTERFACE_PLAN.md`](plans/020-V0_2_13_INTERFACE_PLAN.md) avec la matrice finale candidate [`validation/016-V0_2_13_INTERFACE.md`](validation/016-V0_2_13_INTERFACE.md) : `ksp-interface-lib` expose le `Pubkey` Core, `ProgramAccountMeta` et `ProgramInstruction`, bornés à `255` account metas et `10_240` bytes de data, avec façade crate-root exacte, diagnostics bornés, consumer externe et firewall `Interface -> Core` validés. Le gate technique final `pre.006` est intégralement vert ; [`../crates/ksp-interface-lib/README.md`](../crates/ksp-interface-lib/README.md) et [`../crates/ksp-interface-lib/USAGE.md`](../crates/ksp-interface-lib/USAGE.md) deviennent les références durables avant préparation de publication. Le prompt d’ouverture historique reste [`../prompts/018-V0_2_13_START_PROMPT.md`](../prompts/018-V0_2_13_START_PROMPT.md). `0.2.14 — Program API foundation` est réconciliée comme candidate dans [`plans/021-V0_2_14_PROGRAM_API_PLAN.md`](plans/021-V0_2_14_PROGRAM_API_PLAN.md) avec la matrice finale candidate [`validation/017-V0_2_14_PROGRAM_API.md`](validation/017-V0_2_14_PROGRAM_API.md) : `ksp-program-api` fournit une façade instruction-only ouverte, `ProgramInstructionRecognition`, `ProgramInstructionDecodeOutcome` et `ProgramInstructionDecoder`, avec output associé possédé par l’implémentation, Program Pubkeys opaques/non enregistrés acceptés, canari externe et firewall `Program API -> Core + Interface`. Le gate technique final `pre.006` est intégralement vert ; [`../crates/ksp-program-api/README.md`](../crates/ksp-program-api/README.md) et [`../crates/ksp-program-api/USAGE.md`](../crates/ksp-program-api/USAGE.md) deviennent les références durables avant préparation de publication. Le prompt d’ouverture historique reste [`../prompts/019-V0_2_14_START_PROMPT.md`](../prompts/019-V0_2_14_START_PROMPT.md). `0.3.1 — Store API RAW foundation` est réconciliée comme candidate dans [`plans/022-V0_3_1_STORE_RAW_PLAN.md`](plans/022-V0_3_1_STORE_RAW_PLAN.md) avec la matrice [`validation/018-V0_3_1_STORE_RAW.md`](validation/018-V0_3_1_STORE_RAW.md) : `ksp-store-api` reste Core-only et backend-agnostic, expose les modèles RAW transaction/account et observations, queries cursorisées, outcomes, capabilities fines et lifecycle de rétention/tombstone, sans backend runtime, PostgreSQL, processing ledger ni N2/N3/N4. Le gate `pre.008` a été reconstruit après `cargo clean` et validé sur le workspace complet et les trois builds Tauri ; `pre.009` réconcilie la documentation durable avant la préparation de publication `pre.010`. ## Spécifications de formats diff --git a/docs/IDEAS.md b/docs/IDEAS.md index eb0d784..9b6f8b2 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -1,5 +1,5 @@ - + # Idées à explorer @@ -292,9 +292,9 @@ Définir un mécanisme sûr de suspension/reprise d'une exécution lorsque la po ### Schémas SQL D1/D2/D3/D4 -**Status :** À explorer avec la première release Store +**Status :** À explorer à partir de `0.3.2` -La structure durable D1–D4 est retenue, mais les noms de tables, colonnes, contraintes, index et repositories doivent être conçus avec les premiers workloads réels. +`0.3.1` a stabilisé uniquement les contrats RAW backend-agnostic. Les noms de tables, colonnes, contraintes, index, migrations et repositories PostgreSQL appartiennent à `ksp-store-postgres-lib` à partir de `0.3.2`; les couches D2/D3/D4 n'ajoutent leur persistence qu'au moment où elles sont réellement ouvertes. ### Format générique D3 @@ -308,7 +308,7 @@ Le journal D3 doit accepter les outputs de materializers officiels ou externes s **Status :** Transférée vers une décision/règle -Les processing outcomes par processor/version/capability constituent la vérité du backlog. Les cursors sont des optimisations et les jobs historiques conservent en plus leurs checkpoints de source. +Les futurs processing outcomes versionnés constituent la preuve durable de traitement. Les queries/cursors Store décrivent la navigation dans les données et ne fixent ni batch-size, ni priorité, ni policy d'executor ; les jobs historiques conservent en plus leurs checkpoints de source. ### Jobs de replay @@ -318,9 +318,9 @@ L'ancienne liste figée `ksp-job-replay-core` / `ksp-job-replay-generic-material ### Notification backend de référence -**Status :** Transférée vers une décision/règle +**Status :** À réauditer avec le premier publisher/consumer réel -PostgreSQL LISTEN/NOTIFY est retenu comme mécanisme initial de référence de wake-up, combiné à un periodic polling du backlog. Le Store reste la source de vérité. +Aucun mécanisme PostgreSQL de notification n'est figé par `0.3.1`. L'ordre durable reste `persist -> commit -> publish`, le publisher appartenant au worker/analyser/runtime de composition et non au Store lui-même. Un polling périodique peut compléter le wake-up. Si PostgreSQL `LISTEN/NOTIFY` devient utile plus tard, il reste une optimisation backend/runtime et jamais la source de vérité ni un event bus possédé par `ksp-store-lib`. ## Workers / jobs — questions d'implémentation restantes diff --git a/docs/architecture/003-COMPONENT_CONTRACTS.md b/docs/architecture/003-COMPONENT_CONTRACTS.md index f51f663..f2b2cfd 100644 --- a/docs/architecture/003-COMPONENT_CONTRACTS.md +++ b/docs/architecture/003-COMPONENT_CONTRACTS.md @@ -1,5 +1,5 @@ - + # Contrats initiaux des composants KSP @@ -16,7 +16,7 @@ Couples explicitement retenus : ```text ksp-program-api / ksp-program-lib ksp-materializer-api / ksp-materializer-lib -ksp-store-api / ksp-store-lib +ksp-store-api / ksp-store-lib + ksp-store--lib ``` Lifecycle APIs séparées : @@ -27,6 +27,8 @@ ksp-job-api ksp-execution-policy-api ``` +Pour Store, le couple API/façade est complété par des crates backend séparées : chaque `ksp-store--lib` implémente `ksp-store-api` et ne dépend jamais de `ksp-store-lib`. Les consumers runtime ordinaires utilisent la façade `ksp-store-lib`, pas une crate backend concrète. + Une crate `*-api` n'est jamais créée uniquement pour la symétrie des noms. ## Core @@ -156,7 +158,9 @@ Interprétation Program/protocole puis matérialisation générique/journal dura Projections queryables de domaine : token, metadata, pools, trades, OHLC, routes, etc. -`ksp-store-api` possède les contrats backend-agnostic. `ksp-store-lib` fournit PostgreSQL comme backend officiel. +`ksp-store-api` possède les contrats backend-agnostic. `ksp-store-lib` fournit la façade/runtime commune et sélectionne les backends compilés par features. PostgreSQL est le backend officiel par défaut mais son implémentation physique appartient à `ksp-store-postgres-lib`. + +Les jobs, workers et applications consomment normalement `ksp-store-lib`; les crates backend dépendent de `ksp-store-api` et restent invisibles aux consumers. Une dépendance directe à `ksp-store-api` reste réservée aux implémentations de contrats ou composants réutilisables qui ont réellement besoin de ces traits/types sans façade runtime. La première Store release est RAW-only ; les couches suivantes sont ajoutées quand elles sont réellement ouvertes. diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index 0d5afa8..8780a44 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -17,42 +17,43 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse ## Inventaire synthétique -| Domaine | Composant | Type | Statut | Première cible actuelle | Mission | -|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|----------------------------------------------------------------| -| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales | -| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP | -| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config | -| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config | -| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical | -| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export | -| Wallet Desk | `ksp-app-wallet-desk` | app | Stable | `0.2.6` | Wallet + Config + balance HTTP + projection SOL/USD auxiliaire | -| Wallet V2 | `ksp-wallet-lib` | lib | Stable | `0.2.6` | wire/runtime V2 + API default/versionnée + migration explicite | -| Standard WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées | -| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé | -| Yellowstone | `ksp-onchain-transport-lib` | lib | Stable | `0.2.9` | client gRPC standard/provider-neutral | -| Off-chain price | `ksp-offchain-transport-lib` | lib | Stable | `0.2.11` | prix SOL/USD multi-provider, limits et availability | -| SOL Prices Desk | `ksp-app-solprices-desk` | app | Stable | `0.2.12` | HID provider-agnostic pour visualisation/refresh prix | -| Wire | `ksp-interface-lib` | lib | Retenu | `0.2.13` | façade wire officielle + API publique wire | -| Program API | `ksp-program-api` | API | Retenu | `0.2.14` | contrats extensibles Program | -| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles | -| Program extension | `ksp-program--lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` | -| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | contrats persistence backend-agnostic, RAW d'abord | -| Store PostgreSQL | `ksp-store-lib` | lib | Retenu | `0.3.1` | backend PostgreSQL officiel, RAW d'abord | -| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.3` | lifecycle des jobs terminables | -| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.3` | acquisition historique vers RAW | -| Backfill Desk | nom à fixer | app | Retenu | `0.3.4` | contrôle/inspection du backfill RAW | -| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus | -| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW | -| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE | -| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu | -| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation | -| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes | -| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte | -| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport | -| Scenarios | `ksp-scenario--lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe | -| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun | -| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC | -| Trading Intelligence | noms à définir | libs/jobs | Pressenti | après données stables | features/signaux/anomalies/ML | +| Domaine | Composant | Type | Statut | Première cible actuelle | Mission | +|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|---------------------------------------------------------------------------------------------| +| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales | +| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP | +| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config | +| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config | +| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical | +| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export | +| Wallet Desk | `ksp-app-wallet-desk` | app | Stable | `0.2.6` | Wallet + Config + balance HTTP + projection SOL/USD auxiliaire | +| Wallet V2 | `ksp-wallet-lib` | lib | Stable | `0.2.6` | wire/runtime V2 + API default/versionnée + migration explicite | +| Standard WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées | +| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé | +| Yellowstone | `ksp-onchain-transport-lib` | lib | Stable | `0.2.9` | client gRPC standard/provider-neutral | +| Off-chain price | `ksp-offchain-transport-lib` | lib | Stable | `0.2.11` | prix SOL/USD multi-provider, limits et availability | +| SOL Prices Desk | `ksp-app-solprices-desk` | app | Stable | `0.2.12` | HID provider-agnostic pour visualisation/refresh prix | +| Wire | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire officielle + API publique wire | +| Program API | `ksp-program-api` | API | Stable | `0.2.14` | contrats extensibles Program | +| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles | +| Program extension | `ksp-program--lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` | +| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | RAW transaction/account, observations, queries, outcomes, rétention et capabilities backend | +| Store runtime | `ksp-store-lib` | lib | Retenu | `0.3.2` | façade Store commune, dispatch par features/config | +| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Retenu | `0.3.2` | backend PostgreSQL officiel par défaut, privé derrière Store | +| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.4` | lifecycle des jobs terminables | +| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.4` | acquisition historique vers RAW via `ksp-store-lib` | +| Backfill Desk | nom à fixer | app | Retenu | `0.3.5` | contrôle/inspection du backfill RAW | +| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus | +| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW | +| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE | +| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu | +| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation | +| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes | +| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte | +| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport | +| Scenarios | `ksp-scenario--lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe | +| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun | +| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC | +| Trading Intelligence | noms à définir | libs/jobs | Pressenti | après données stables | features/signaux/anomalies/ML | ## Contrats séparés retenus diff --git a/docs/architecture/005-DEPENDENCY_GRAPH.md b/docs/architecture/005-DEPENDENCY_GRAPH.md index 3d77c32..aafcbd5 100644 --- a/docs/architecture/005-DEPENDENCY_GRAPH.md +++ b/docs/architecture/005-DEPENDENCY_GRAPH.md @@ -1,5 +1,5 @@ - + # Graphe de dépendances KSP @@ -336,6 +336,12 @@ ksp-store-api -> ksp-core-lib ksp-store-lib + -> ksp-store-api + -> ksp-core-lib + -> ksp-logging-lib + -> ksp-store-postgres-lib # feature postgres par défaut, optionnelle au build + +ksp-store-postgres-lib -> ksp-store-api -> ksp-core-lib -> ksp-logging-lib @@ -347,9 +353,11 @@ Interdictions : ```text ksp-store-api -X-> transport/program/materializer ksp-store-lib -X-> transport/program/materializer +ksp-store-postgres-lib -X-> ksp-store-lib +worker/job -X-> ksp-store-postgres-lib ``` -La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches. +La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches. Les consumers runtime ordinaires (jobs, workers, apps) utilisent `ksp-store-lib`; ils ne sélectionnent ni n'importent directement `ksp-store-postgres-lib` ou un autre backend. ## Jobs @@ -364,7 +372,7 @@ Premier job pressenti : ksp-job-backfill -> ksp-job-api -> ksp-onchain-transport-lib - -> ksp-store-api + -> ksp-store-lib -> ksp-config-lib -> ksp-logging-lib ``` @@ -426,7 +434,7 @@ backfill app ```text ksp-app-market-desk - -> ksp-store-api + -> ksp-store-lib -> live transport only where explicitly useful -> KSP domain/query contracts ``` diff --git a/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md b/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md index c0deedc..b176aa9 100644 --- a/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md +++ b/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md @@ -1,5 +1,5 @@ - + # Acquisition, workers, jobs et pipelines spécialisés @@ -262,7 +262,7 @@ status progress ``` -Les types exacts sont décidés à `0.3.3` avec le premier vrai backfill. +Les types exacts sont décidés à `0.3.4` avec le premier vrai backfill. Aucune `ksp-job-control-lib` n'est créée sans duplication concrète. @@ -290,6 +290,8 @@ output + durable outcome Les notifications ne remplacent jamais le Store. +La taille du batch, la priorité et la stratégie de sélection appartiennent au worker/job/executor. Store fournit les primitives de query/cursor/claim nécessaires et peut refléter une contrainte physique du backend, mais `ksp-store-lib` n'invente pas un plafond métier global inférieur à la capacité réellement disponible. + La sémantique cible reste at-least-once avec idempotence durable, plutôt qu'un faux exactly-once. ## Processing outcomes @@ -340,7 +342,7 @@ Les événements utiles comprennent notamment : ksp-job-backfill -> ksp-job-api -> ksp-onchain-transport-lib - -> ksp-store-api / backend injecté + -> ksp-store-lib # façade Store ; backend sélectionné par feature + Config -> ksp-config-lib # orchestration/config, pas ownership transport -> ksp-logging-lib ``` @@ -351,7 +353,7 @@ ksp-job-backfill ksp-worker-raw-retriever -> ksp-worker-api -> ksp-onchain-transport-lib - -> ksp-store-api / backend injecté + -> ksp-store-lib # façade Store ; backend sélectionné par feature + Config -> ksp-config-lib -> ksp-logging-lib ``` diff --git a/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md b/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md index befc3a2..3214ea6 100644 --- a/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +++ b/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md @@ -1,5 +1,5 @@ - + # Applications, services, scenarios et control plane @@ -107,10 +107,11 @@ ksp-app-solprices-desk -> ksp-offchain-transport-lib ksp-app-store-desk - -> ksp-store-api -> ksp-store-lib ``` +`ksp-store-lib` réexporte la surface Store commune nécessaire aux applications ; une app ne dépend pas directement de `ksp-store-api` uniquement pour atteindre les modèles/capabilities, et ne dépend jamais d'une crate backend concrète. + Les couches N1–N4 expriment des responsabilités et une direction de dépendances ; elles n'imposent pas de traverser toutes les couches intermédiaires. ## Tauri diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index 1b5d229..d4165c2 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -28,8 +28,9 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) — plan historique clôturé de la release stable `0.2.10 — OrbitFlare Yellowstone gRPC`; il conserve le Devnet gRPC gratuit, N1/N2 immuables, la License Key `x-token` et le smoke final `Slot + Ping`. - [`018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) — plan historique clôturé de `0.2.11 — Off-chain price transport`; SOL/USD V1, huit providers REST sans SDK, registry/availability/rate limits Off-chain et Config `std.offchain_transport`. - [`019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](019-V0_2_12_SOL_PRICES_DESK_PLAN.md) — plan historique clôturé de `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk`; il conserve le gabarit 1434/1435, le composite Config, les DTO/commands provider-neutral, l’intégration Wallet minimale et les gates live/build finaux. -- [`020-V0_2_13_INTERFACE_PLAN.md`](020-V0_2_13_INTERFACE_PLAN.md) — plan candidat réconcilié de `0.2.13 — Interface / wire foundation`; il fixe la surface finale `ProgramAccountMeta` + `ProgramInstruction`, les bornes `255` / `10_240`, le firewall Interface -> Core, les canaris de complétude/consumer externe et la frontière avec Program API/RAW/CORE. -- [`021-V0_2_14_PROGRAM_API_PLAN.md`](021-V0_2_14_PROGRAM_API_PLAN.md) — plan candidat réconcilié de `0.2.14 — Program API foundation`; il fixe la façade instruction-only ouverte, les enums Recognition/Outcome, `ProgramInstructionDecoder`, l'output associé possédé par l'implémentation, le canari externe avec Program Pubkey non enregistré, le firewall Core/Interface et le report du payload canonique D3, du registry runtime et de `ProgramExecutionPreparer`. +- [`020-V0_2_13_INTERFACE_PLAN.md`](020-V0_2_13_INTERFACE_PLAN.md) — plan historique clôturé de la release stable `0.2.13 — Interface / wire foundation`; il fixe la surface finale `ProgramAccountMeta` + `ProgramInstruction`, les bornes `255` / `10_240`, le firewall Interface -> Core, les canaris de complétude/consumer externe et la frontière avec Program API/RAW/CORE. +- [`021-V0_2_14_PROGRAM_API_PLAN.md`](021-V0_2_14_PROGRAM_API_PLAN.md) — plan historique clôturé de la release stable `0.2.14 — Program API foundation`; il fixe la façade instruction-only ouverte, les enums Recognition/Outcome, `ProgramInstructionDecoder`, l'output associé possédé par l'implémentation, le canari externe avec Program Pubkey non enregistré, le firewall Core/Interface et le report du payload canonique D3, du registry runtime et de `ProgramExecutionPreparer`. +- [`022-V0_3_1_STORE_RAW_PLAN.md`](022-V0_3_1_STORE_RAW_PLAN.md) — plan candidat réconcilié de `0.3.1 — Store API RAW foundation`; il fixe `ksp-store-api` seul, les modèles transaction/account + observations, queries/outcomes/capabilities, rétention/tombstone, la frontière event-only/Interface et le report de `ksp-store-lib` + PostgreSQL à `0.3.2`. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md b/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md index 2cdafd2..78c1c01 100644 --- a/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md +++ b/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md @@ -1,5 +1,5 @@ - + # Plan `0.3.1` — Store API RAW foundation @@ -76,12 +76,12 @@ observations d'acquisition persistantes lorsque leur conservation est utile références durables outcomes d'écriture/idempotence queries cursorisées sans plafond métier arbitraire -health/readiness communs utiles contrats/capabilities backend extensibles -référence/format canonique de wake-up pour une donnée déjà persistée, conformément aux règles KSP-NOTIFY cycle de rétention logique du RAW et tombstones anti-rebackfill ``` +Le health/readiness runtime et un éventuel type canonique dédié de wake-up ne sont finalement pas matérialisés dans `0.3.1`. Les références durables de l'API suffisent pour la foundation RAW ; le health appartient à la façade runtime `ksp-store-lib` de `0.3.2`, tandis qu'un contrat de notification dédié ne sera ajouté que lorsqu'un consumer/publisher réel en aura besoin conformément aux règles KSP-NOTIFY. + La release doit aussi auditer les autres données on-chain réellement utiles afin de distinguer explicitement : ```text @@ -941,7 +941,7 @@ Les autres références sont ajoutées uniquement avec leur modèle réel. Le Store runtime persiste et lit. Il ne possède ni scheduler, ni event bus, ni mécanisme de publication et ne doit pas s'appuyer sur une notification native de base de données pour piloter le pipeline. -Les règles `KSP-NOTIFY-001..006` restent applicables : `ksp-store-api` peut posséder **le format canonique** d'un wake-up signifiant qu'une donnée déjà commitée est disponible, sous forme de référence durable compacte. Cela ne signifie pas que la base ou `ksp-store-lib` publie elle-même le signal. +Les règles `KSP-NOTIFY-001..006` restent applicables, mais `0.3.1` n'ajoute **aucun type de notification dédié**. Les références durables déjà exposées par `ksp-store-api` fournissent l'identité compacte nécessaire à un futur contrat de wake-up si un publisher/consumer réel le justifie. La base et `ksp-store-lib` ne publient pas eux-mêmes le signal. Le futur ordre d'orchestration est : @@ -1036,20 +1036,13 @@ La policy est **spécifique à chaque famille**. `RawAccountState`, qui pourrait `0.3.1` doit préparer les contrats logiques de rétention/tombstone sans implémenter compression, stockage d'archive, cron/worker de purge ou maintenance PostgreSQL. -## 13. Health et diagnostics +## 13. Health et diagnostics — reportés au runtime Store -La façade peut exposer un health commun minimal : +`0.3.1` n'expose aucun `StoreHealth` dans `ksp-store-api`. Le health/readiness est un état runtime de la façade et des backends, pas une propriété nécessaire des modèles RAW persistants. -```text -Unknown -Healthy -Degraded -Unhealthy -``` +`0.3.2` devra cadrer dans `ksp-store-lib` une projection portable uniquement si les consumers runtime en ont réellement besoin ; les backends pourront fournir leurs diagnostics privés derrière cette projection. -avec un backend code sûr et un code diagnostic borné si nécessaire. - -Ne pas exposer dans l'API commune : +Ne jamais exposer dans l'API commune : ```text migration SQL state @@ -1060,7 +1053,7 @@ DSN SQLSTATE arbitraire présenté comme contrat portable ``` -Les diagnostics spécifiques à PostgreSQL appartiennent à `ksp-store-postgres-lib`. `ksp-store-lib` ne projette vers le contrat commun que les états réellement portables et sanitised. +Les diagnostics spécifiques à PostgreSQL appartiennent à `ksp-store-postgres-lib`. Si `ksp-store-lib` expose un health commun en `0.3.2`, il ne projette que les états réellement portables et sanitised. ## 14. Dependency graph `0.3.1` @@ -1121,12 +1114,12 @@ L'archive contient aussi les documents kbot2 historiques. Ils avaient déjà for |------------------------------------------|-------------------------------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------| | séparation façade Store / PostgreSQL | PostgreSQL et driver privés | REPRENDRE | API commune séparée ; façade + backend PostgreSQL reportés à `0.3.2` | | `StoreOpenOptions` / backend selection | backend + options historiques partiellement opaques | REDESSINER | Config produit les settings ; `ksp-store-lib` sélectionne un backend compilé | -| health/readiness | contrat backend-neutral présent | REPRENDRE | health minimal portable dans `ksp-store-api` | +| health/readiness | contrat backend-neutral présent | REPORTER | health runtime portable à cadrer dans `ksp-store-lib` `0.3.2`; aucun `StoreHealth` dans `ksp-store-api` `0.3.1` | | transaction canonique source-independent | HTTP/WS/gRPC convergent vers une transaction canonique | REPRENDRE | `RawTransaction` commun seulement si la source satisfait le contrat complet | | acquisition observations | transaction + account observations séparées du RAW | REPRENDRE | concept N1 central ; transaction d'abord, account prévu après matrice de compatibilité | | ancienne raw WS notification | kbot2 l'a supprimée de la baseline persistante | REPRENDRE | `logsSubscribe`/events restent event-only par défaut ; pas de table de notification brute | | logs transactionnels | conservés puis extraits dans la couche Core historique | REDESSINER | restent dans `RawTransaction`, puis deviennent des unités N2 STRUCTURAL ; pas de `RawLog` persistant séparé | -| account observations/states | N1 account observation + N2 account state existaient | REDESSINER | prévoir `RawAccountState`/observation ; N2 seulement si une décomposition réellement utile est démontrée | +| account observations/states | N1 account observation + N2 account state existaient | REDESSINER | `RawAccountState`/observation stabilisés en N1 ; N2 seulement si une décomposition réellement utile est démontrée | | repository traits | capabilities async séparées | REPRENDRE | capabilities read/write fines, aucune obligation de supporter toutes les familles | | pagination | cursor opaque historique | REDESSINER | limite caller > 0 sans plafond métier KSP ; cursor hostile borné uniquement | | replay contracts | sélection + force replay version-aware | REPRENDRE | futur replay piloté par processor/version/input hash, jamais par simple bool | @@ -1341,30 +1334,30 @@ Aucun PostgreSQL live test n'appartient à `0.3.1` puisque le backend PostgreSQL ## 21. Ownership -| Concept | Owner candidat/fixé | Visibilité | Introduction | Raison | -|--------------------------------------|-------------------------------|-----------------------------|---------------------------------------|-----------------------------------------------------| -| `RawTransaction` | `ksp-store-api` | public | `0.3.1` | modèle persistant/replayable commun | -| `RawTransactionObservation` | `ksp-store-api` | public | `0.3.1` | acquisition durable distincte du RAW | -| transaction log messages RAW | dans `RawTransaction` | public via modèle RAW | `0.3.1` | font partie de la transaction avant décomposition | -| structural transaction log lines | future couche N2 | hors `0.3.1` | série STRUCTURAL | unités extraites après décomposition | -| `RawAccountState` | `ksp-store-api` | public si audit PASS | prévu `0.3.1`, capability progressive | état canonique commun HTTP/WS/gRPC à confirmer | -| `RawAccountObservation` | `ksp-store-api` | public si audit PASS | prévu `0.3.1`, capability progressive | provenance/account acquisition | -| `TransactionStatusObservation` | à confirmer `ksp-store-api` | public si persistence utile | exploration `0.3.1` | petit état durable/event potentiel | -| log/status/slot/vote event-only | préférer `ksp-interface-lib` | public passif | future tranche Interface si retenue | échange inter-composants sans persistence Store | -| `RawRetentionState` / tombstone | `ksp-store-api` | public logique | à stabiliser en `0.3.1` | cycle de vie RAW backend-agnostic | -| processing ledger versionné | future contrat Store commun | hors surface initiale RAW | avec jobs/N2/N3 | preuve durable stage/version/input, pas bool | -| RAW references | `ksp-store-api` | public | `0.3.1` | reads/replay/lineage | -| write outcomes | `ksp-store-api` | public | `0.3.1` | sémantique idempotente commune | -| query/page | `ksp-store-api` | public | `0.3.1` | navigation/replay backend-agnostic | -| health portable | `ksp-store-api` | public | `0.3.1` | consumer commun | -| backend capabilities | `ksp-store-api` | public | `0.3.1` | implémentations externes | -| `Store` facade | `ksp-store-lib` | public | `0.3.2` | point de consommation commun | -| backend dispatch/settings | `ksp-store-lib` | public/privé selon contrat | `0.3.2` | features disponibles + sélection Config | -| PostgreSQL rows/pool/SQL/migrations | `ksp-store-postgres-lib` | privé/opérateur | `0.3.2` | détails physiques | -| transport -> RAW conversion | composition/pipeline futur | privé/réutilisable | release acquisition | conversion explicite, jamais dépendance inverse | -| RAW -> STRUCTURAL | future pipeline générique | hors `0.3.1` | série suivante | aucune dépendance Program | -| event runtime / scheduler / analyzer | worker/analyser/runtime futur | hors Store | ultérieur | Store ne notifie pas lui-même | -| retention policy/maintenance worker | job/worker/opérateur futur | hors Store API décisionnel | ultérieur | décide l'éligibilité ; Store applique la transition | +| Concept | Owner candidat/fixé | Visibilité | Introduction | Raison | +|--------------------------------------|-------------------------------|----------------------------|-------------------------------------|------------------------------------------------------------------| +| `RawTransaction` | `ksp-store-api` | public | `0.3.1` | modèle persistant/replayable commun | +| `RawTransactionObservation` | `ksp-store-api` | public | `0.3.1` | acquisition durable distincte du RAW | +| transaction log messages RAW | dans `RawTransaction` | public via modèle RAW | `0.3.1` | font partie de la transaction avant décomposition | +| structural transaction log lines | future couche N2 | hors `0.3.1` | série STRUCTURAL | unités extraites après décomposition | +| `RawAccountState` | `ksp-store-api` | public | `0.3.1` | état canonique commun HTTP/WS/gRPC sous admission stricte | +| `RawAccountObservation` | `ksp-store-api` | public | `0.3.1` | provenance/acquisition de l'état compte | +| `TransactionStatusObservation` | non fixé | absent | reporté | HTTP snapshot, WS transition et Yellowstone update non fusionnés | +| log/status/slot/vote event-only | préférer `ksp-interface-lib` | public passif | future tranche Interface si retenue | échange inter-composants sans persistence Store | +| `RawRetentionState` / tombstone | `ksp-store-api` | public logique | `0.3.1` | cycle de vie RAW backend-agnostic stabilisé | +| processing ledger versionné | future contrat Store commun | hors surface initiale RAW | avec jobs/N2/N3 | preuve durable stage/version/input, pas bool | +| RAW references | `ksp-store-api` | public | `0.3.1` | reads/replay/lineage | +| write outcomes | `ksp-store-api` | public | `0.3.1` | sémantique idempotente commune | +| query/page | `ksp-store-api` | public | `0.3.1` | navigation/replay backend-agnostic | +| health runtime | `ksp-store-lib` | hors `0.3.1` | `0.3.2` à cadrer | état runtime, non requis par les modèles RAW | +| backend capabilities | `ksp-store-api` | public | `0.3.1` | implémentations externes | +| `Store` facade | `ksp-store-lib` | public | `0.3.2` | point de consommation commun | +| backend dispatch/settings | `ksp-store-lib` | public/privé selon contrat | `0.3.2` | features disponibles + sélection Config | +| PostgreSQL rows/pool/SQL/migrations | `ksp-store-postgres-lib` | privé/opérateur | `0.3.2` | détails physiques | +| transport -> RAW conversion | composition/pipeline futur | privé/réutilisable | release acquisition | conversion explicite, jamais dépendance inverse | +| RAW -> STRUCTURAL | future pipeline générique | hors `0.3.1` | série suivante | aucune dépendance Program | +| event runtime / scheduler / analyzer | worker/analyser/runtime futur | hors Store | ultérieur | Store ne notifie pas lui-même | +| retention policy/maintenance worker | job/worker/opérateur futur | hors Store API décisionnel | ultérieur | décide l'éligibilité ; Store applique la transition | ## 22. Hors scope strict `0.3.1` @@ -1430,15 +1423,17 @@ La tranche matérialise aussi le résultat distinct `ExpectedStateMismatch` pour ### `pre.008` — Gate technique final -**Statut : préparé par `0.3.1-pre.008`, à fermer par le gate opérateur complet.** +**Statut : PASS opérateur.** La tranche reste un gate pur : aucun nouveau modèle, capability, test métier, backend, codec, event-only type ou comportement runtime. Elle synchronise uniquement la version workspace et les preuves documentaires du gate final. -Le gate opérateur doit couvrir le workspace complet, les tests Store API, l'ownership Logging et les graphes Cargo. Aucun développement fonctionnel nouveau. +Le gate opérateur a été exécuté après `cargo clean` : audits Rust/Markdown, `cargo check --workspace`, Clippy, tests ciblés de toutes les crates présentes, `cargo test --workspace`, builds Tauri des trois Desk et graphes Cargo sont verts. La commande ciblée initiale `cargo test -p ksp-program-lib` était un nom de package erroné ; `cargo test -p ksp-program-api` a ensuite été exécuté séparément et passe intégralement. ### `pre.009` — Réconciliation documentaire finale -README/USAGE, plan, validation et références durables réellement concernées. Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant. +**Statut : matérialisé par `0.3.1-pre.009`.** + +Le plan, la validation, l'inventaire/graphe d'architecture, les dépendances des futurs consumers Store et `IDEAS.md` sont réconciliés avec la surface réellement livrée. `README.md` ne porte pas d'inventaire Store détaillé et aucun USAGE Store n'existe encore : aucune modification artificielle n'y est ajoutée. Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant n'est touché. ### `pre.010` — Préparation de publication minimale @@ -1486,7 +1481,7 @@ ksp-store-api existe seule dans le domaine Store RawTransaction + observations stables aucune source partielle ne fabrique un RawTransaction incomplet logs transactionnels restent dans RawTransaction jusqu'à N2 STRUCTURAL -RawAccountState/observation audités et modèle prévu si compatibilité cross-source prouvée +RawAccountState/observation audités, modèles et capabilities stabilisés sous admission cross-source stricte TransactionStatusObservation classé explicitement logsSubscribe/slot/vote classés event-only/Interface, reportés ou rejetés explicitement RawBlock reste IDEA sans persistence tant qu'un besoin block-level n'est pas démontré @@ -1496,7 +1491,7 @@ models et capabilities séparés contrats backend communs stables backend externe implémentable sans ksp-store-lib aucun type backend/SQL public -queries/pagination cursorisée sans plafond métier KSPs +queries/pagination cursorisée sans plafond métier KSP idempotence/conflict semantics explicites atomic acquisition contract explicite références durables stables @@ -1504,6 +1499,7 @@ RawRetentionState/tombstone empêchent le rebackfill normal après purge force rehydrate reste explicitement distinct aucun simple processed bool n'est présenté comme preuve suffisante de traitement future preuve processing versionnée stage/processor/input reste possible +health/readiness runtime et type de wake-up dédié restent explicitement hors `ksp-store-api` `0.3.1` aucune dépendance PostgreSQL aucune surface N2 STRUCTURAL/N3 DECODED/N4 DOMAIN implémentée workspace et graphes entièrement verts diff --git a/docs/validation/000-README.md b/docs/validation/000-README.md index a0734a6..f5deed4 100644 --- a/docs/validation/000-README.md +++ b/docs/validation/000-README.md @@ -1,5 +1,5 @@ - + # Validations KSP @@ -24,5 +24,6 @@ Documents : - [`013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) — matrice finale de la release stable `0.2.10` : Free Devnet, auth `x-token`, endpoint security, heartbeat standard, Config V3, smoke live `Slot + Ping` et invariant N1/N2 immuable. - [`014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) — matrice historique clôturée de `0.2.11` : SOL/USD multi-provider, numeric safety, rate limiting/availability, Config capability-aware et smoke keyless final `7/7`. - [`015-V0_2_12_SOL_PRICES_DESK.md`](015-V0_2_12_SOL_PRICES_DESK.md) — matrice historique clôturée de `0.2.12` : screen/features, DTO/commands, Config/composite, frontières provider-neutral, sécurité, Wallet integration, packaging Tauri et gates live/build. -- [`016-V0_2_13_INTERFACE.md`](016-V0_2_13_INTERFACE.md) — matrice candidate finale de `0.2.13` : ownership Interface/Core/Transport/Program, surface passive, bornes/adversarial, façade publique exacte, consumer externe, release completeness, dependency firewall et gate technique `pre.006` intégralement vert. -- [`017-V0_2_14_PROGRAM_API.md`](017-V0_2_14_PROGRAM_API.md) — matrice candidate finale de `0.2.14 — Program API foundation` : façade instruction-only ouverte, Recognition/Outcome, trait externe, Program Pubkey non enregistré, hardening adversarial, release completeness, firewall Core/Interface et gate technique `pre.006` intégralement vert. +- [`016-V0_2_13_INTERFACE.md`](016-V0_2_13_INTERFACE.md) — matrice historique clôturée de la release stable `0.2.13` : ownership Interface/Core/Transport/Program, surface passive, bornes/adversarial, façade publique exacte, consumer externe, release completeness et dependency firewall. +- [`017-V0_2_14_PROGRAM_API.md`](017-V0_2_14_PROGRAM_API.md) — matrice historique clôturée de la release stable `0.2.14 — Program API foundation` : façade instruction-only ouverte, Recognition/Outcome, trait externe, Program Pubkey non enregistré, hardening adversarial, release completeness et firewall Core/Interface. +- [`018-V0_3_1_STORE_RAW.md`](018-V0_3_1_STORE_RAW.md) — matrice candidate finale de `0.3.1 — Store API RAW foundation` : modèles transaction/account, observations, capabilities backend, pagination sans policy executor, outcomes, rétention/tombstone, hardening, gate complet `pre.008` et reports explicites vers `0.3.2+`. diff --git a/docs/validation/018-V0_3_1_STORE_RAW.md b/docs/validation/018-V0_3_1_STORE_RAW.md index 377fc34..711a775 100644 --- a/docs/validation/018-V0_3_1_STORE_RAW.md +++ b/docs/validation/018-V0_3_1_STORE_RAW.md @@ -1,5 +1,5 @@ - + # Validation `0.3.1` — Store API RAW foundation @@ -11,6 +11,7 @@ Le scope concret N1 certain est : ```text RawTransaction + observation +RawAccountState + observation provenance/références/outcomes/queries communs contrats/capabilities backend externes cycle de rétention logique + tombstone @@ -33,8 +34,8 @@ cycle de rétention logique + tombstone | `RawTransaction` | PASS | premier modèle persistant certain | | logs dans transaction | PASS | restent dans `RawTransaction`, extraction seulement en N2 STRUCTURAL | | logsSubscribe | REPORTÉ | event-only candidat ; pas de `RawLog` Store persistant par défaut | -| account state | PRÉVU | modèle/observation à figer après matrice de compatibilité | -| transaction status | PRÉVU | observation/event à figer si sémantique commune prouvée | +| account state | PASS | `pre.004` matérialise modèle/observation sous bytes complets + slot | +| transaction status | REPORTÉ | HTTP snapshot, WS transition et Yellowstone update restent distincts | | slot/vote | TODO | event-only candidats ; ownership Interface à auditer | | RawBlock | IDEA | non persisté par défaut ; `getBlock` sert de conteneur d'acquisition | | Yellowstone Entry | REJETÉ | aucun replay/decomposition/event métier justifiant un modèle Store | @@ -52,31 +53,31 @@ cycle de rétention logique + tombstone ## 3. Décisions structurelles à prouver par le code -| Contrat | Décision `pre.001-fix.002` | Gate futur | -|--------------------------------|-------------------------------------------------------------------|------------------------------| -| crate `ksp-store-api` | seule crate Store créée en `0.3.1` | `pre.002` | -| dépendance normale | `ksp-core-lib` uniquement par défaut | `pre.002` | -| `RawPayload` | KSP-owned, source-independent, versionné, borné, Debug sans bytes | `pre.003` | -| `RawTransaction` | objet persistant commun uniquement depuis une source complète | `pre.003` | -| `RawTransactionObservation` | acquisition/provenance séparée du RAW | `pre.003` | -| transaction `logMessages` | partie du RAW transactionnel | `pre.003` | -| logs structuraux | extraction N2 STRUCTURAL future, jamais `RawLog` N1 distinct | canari négatif `pre.003/007` | -| `RawAccountState`/observation | modèle prévu si HTTP/WS/gRPC convergent sans perte | `pre.004` | -| `TransactionStatusObservation` | modèle prévu si surfaces status convergent | `pre.004` | -| logs/slot/vote event-only | ne créent aucune capability Store par défaut | `pre.004/007` | -| Interface vs Store | event-only partagé -> Interface ; persistent/replay -> Store API | `pre.004/007` | -| model vs capability | un modèle API n'oblige pas tous les backends à le persister | `pre.005` | -| capabilities | read/write fines et object-safe | `pre.005` | -| transaction handle | aucun handle SQL/backend public | `pre.005` | -| atomic acquisition | méthode métier RAW + observation all-or-nothing | `pre.005/006` | -| write outcome | `Inserted / AlreadyPresent`; divergence = `Err Conflict` | `pre.006` | -| page/cursor | limit caller > 0 ; sans max KSP ; cursor opaque <= 4 KiB | `pre.006` | -| `RawRetentionState` | logique `Full/Compacted/Archived/Purged`, sans détail physique | `pre.006` | -| tombstone | identité/hash/slot minimal durable après purge | `pre.006` | -| backfill normal après purge | skip distinct | `pre.006` | -| force rehydrate | chemin explicite distinct, jamais fallback automatique | `pre.006` | -| processing evidence | futur ledger version-aware, jamais un bool unique | boundary `pre.006/007` | -| façade runtime `Store` | reportée à `ksp-store-lib`, hors `0.3.1` | `0.3.2` | +| Contrat | Décision `pre.001-fix.002` | Gate futur | +|--------------------------------|------------------------------------------------------------------------------|------------------------------| +| crate `ksp-store-api` | seule crate Store créée en `0.3.1` | `pre.002` | +| dépendance normale | `ksp-core-lib` uniquement par défaut | `pre.002` | +| `RawPayload` | KSP-owned, source-independent, versionné, borné, Debug sans bytes | `pre.003` | +| `RawTransaction` | objet persistant commun uniquement depuis une source complète | `pre.003` | +| `RawTransactionObservation` | acquisition/provenance séparée du RAW | `pre.003` | +| transaction `logMessages` | partie du RAW transactionnel | `pre.003` | +| logs structuraux | extraction N2 STRUCTURAL future, jamais `RawLog` N1 distinct | canari négatif `pre.003/007` | +| `RawAccountState`/observation | modèle admis si HTTP/WS/gRPC convergent sans perte, matérialisé en `pre.004` | `pre.004` | +| `TransactionStatusObservation` | non matérialisé : surfaces status non équivalentes | report explicite `pre.004` | +| logs/slot/vote event-only | ne créent aucune capability Store par défaut | `pre.004/007` | +| Interface vs Store | event-only partagé -> Interface ; persistent/replay -> Store API | `pre.004/007` | +| model vs capability | un modèle API n'oblige pas tous les backends à le persister | `pre.005` | +| capabilities | read/write fines et object-safe | `pre.005` | +| transaction handle | aucun handle SQL/backend public | `pre.005` | +| atomic acquisition | méthode métier RAW + observation all-or-nothing | `pre.005/006` | +| write outcome | `Inserted / AlreadyPresent`; divergence = `Err Conflict` | `pre.006` | +| page/cursor | limit caller > 0 ; sans max KSP ; cursor opaque <= 4 KiB | `pre.006` | +| `RawRetentionState` | logique `Full/Compacted/Archived/Purged`, sans détail physique | `pre.006` | +| tombstone | identité/hash/slot minimal durable après purge | `pre.006` | +| backfill normal après purge | skip distinct | `pre.006` | +| force rehydrate | chemin explicite distinct, jamais fallback automatique | `pre.006` | +| processing evidence | futur ledger version-aware, jamais un bool unique | boundary `pre.006/007` | +| façade runtime `Store` | reportée à `ksp-store-lib`, hors `0.3.1` | `0.3.2` | ## 4. Dependency firewall final attendu @@ -307,93 +308,6 @@ Le canari `tests/external_backend.rs` définit un backend mémoire externe qui i Aucune implémentation de persistence n'est fournie par `ksp-store-api`; les futures concrètes du canari ne servent qu'à vérifier le contrat d'extension. -## 9. Gates de fermeture prévus - -### Gate technique final `pre.008` - -`0.3.1-pre.008` n'ajoute aucun développement fonctionnel. Le gate opérateur de `pre.007-fix.001` fourni le 29 août 2026 est vert pour fmt, audits Rust/Markdown, workspace check/Clippy et `cargo test -p ksp-store-api` : 15 tests unitaires, 2 dependency-boundary, 1 external-backend, 7 public-api, 5 release-completeness, 4 security-hardening et doc-tests propres. - -La tranche `pre.008` doit maintenant fermer le gate technique complet, y compris workspace, ownership Logging et graphes Cargo. - -Commandes de référence : - -```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.1 -cargo check --workspace -cargo clippy --workspace --all-targets -cargo test -p ksp-store-api -cargo test -p ksp-logging-lib --test ownership -cargo test --workspace -cargo tree -p ksp-store-api --edges normal -cargo tree --duplicates -``` - -### Réconciliation documentaire `pre.009` - -Doit fermer : - -```text -crates/ksp-store-api/README.md -crates/ksp-store-api/USAGE.md -plan 022 -validation 018 -indexes/références durables concernées -``` - -Sans `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant. - -### Préparation de publication `pre.010` - -Doit rester limitée à : - -```text -Cargo.toml -CHANGELOG.md -ROADMAP.md -prompts/021-V0_3_2_START_PROMPT.md -delta pre.010 -``` - -Le `ROADMAP.md` est réconcilié par `pre.001-fix.001` puis `pre.001-fix.002`; `pre.010` ne doit plus avoir à réparer la taxonomie N1/N2 ni le split backend. - -## 10. PostgreSQL reporté à `0.3.2` - -Aucun gate PostgreSQL live n'est demandé à `0.3.1`. - -Le prochain prompt devra transformer les invariants API en façade commune + backend de référence et prévoir : - -```text -ksp-store-lib - -> façade Store commune - -> réexports utiles de ksp-store-api - -> feature postgres par défaut - -> dispatch backend selon Config - -> erreur backend connu mais non compilé - -ksp-store-postgres-lib - -> tokio-postgres - -> pool/TLS audités - -> migrations KSP-owned - -> schema conformance - -> write/read round-trip des modèles API - -> idempotence/race - -> atomic rollback - -> pagination - -Config - -> std.store - -> URI/DSN backend lorsque naturel - -> secrets ${KSP_SECRET_*} / .env owned par ksp-config-lib - -> aucun vrai secret versionné - -sécurité - -> URI/DSN/credentials redacted - -> aucune lecture directe env/.env par Store ou backend - -> PostgreSQL réel opt-in puis gate final obligatoire -``` - ### 8.4 Matérialisation `pre.006` La tranche ajoute les contrats logiques suivants sans backend/runtime : @@ -458,18 +372,131 @@ aucune fuite PostgreSQL/MySQL/backend runtime La course de rétention est un état normal de concurrence : si l'état durable ne correspond plus à `expected` et n'est pas déjà `target`, le backend doit retourner `ExpectedStateMismatch`. Cette sémantique évite d'utiliser une erreur de validation pour une course et impose une compare-and-transition atomique à l'implémentation future. -## 11. État initial des tranches +### 8.6 Gate technique `pre.008` -| Tranche | Objet | État | -|-----------|------------------------------------------|-----------------------| -| `pre.001` | audit/design/taxonomie/split | PRÊT après gate local | -| `pre.002` | scaffold + taxonomie Store API | PRÊT après gate local | -| `pre.003` | primitives + RawTransaction | PRÊT après gate local | -| `pre.004` | admission matrix + account/status models | PRÊT après gate local | -| `pre.005` | backend contracts/capabilities | PRÊT après gate local | -| `pre.006` | queries/outcomes/retention/tombstone | PRÊT après gate local | -| `pre.007` | boundary/adversarial/completeness | PRÊT après gate local | -| `pre.008` | gate technique final | PRÊT pour gate local | -| `pre.009` | réconciliation documentaire | À FAIRE | -| `pre.010` | préparation publication | À FAIRE | -| `rel.001` | stable | À FAIRE | +Le gate opérateur final a été exécuté après `cargo clean`, donc sans dépendre du cache incrémental précédent. + +Résultat : + +```text +audits Rust/Markdown PASS +cargo check --workspace PASS +cargo clippy --workspace --all-targets PASS +tests ciblés Core/Logging/Config/Transport/Off-chain/Wallet/Interface/Store/Desks PASS +cargo test --workspace PASS +cargo tauri build SOL Prices Desk PASS +cargo tauri build Wallet Desk PASS +cargo tauri build Config Desk PASS +cargo tree -p ksp-store-api --edges normal inspecté +cargo tree --duplicates inspecté +``` + +Le seul incident de commande était le nom inexistant `ksp-program-lib`; il ne correspond à aucune crate publiée. Le test ciblé correct `cargo test -p ksp-program-api` a ensuite été exécuté séparément et passe : 3 unit, 2 dependency-boundary, 2 external-implementation, 4 public-api, 4 release-completeness et 3 security-hardening, plus doc-tests. + +Le graphe normal Store API reste strictement `ksp-store-api -> ksp-core-lib` et aucune dépendance backend/runtime n'entre dans la crate. + +### 8.7 Réconciliation `pre.009` + +La surface finale réellement retenue pour `0.3.1` est : + +```text +RawTransaction / RawTransactionObservation +RawAccountState / RawAccountObservation +primitives de provenance/format/hash/timestamps +queries cursorisées sans plafond métier KSP arbitraire +outcomes idempotence/conflit +RawRetentionState + tombstone transactionnel +normal skip après purge + force rehydrate explicite +10 capabilities backend fines/object-safe +``` + +Sont explicitement reportés plutôt que simulés dans la foundation : + +```text +TransactionStatusObservation +logs/slot/vote event-only contracts +StoreHealth/readiness runtime +type canonique dédié de wake-up persisté-data +processing ledger / backlog métier / executor policy +compression/archive physique +backend PostgreSQL et std.store +N2 STRUCTURAL / N3 DECODED / N4 DOMAIN +``` + +`README.md` ne contient aucune surface Store détaillée devenue fausse et aucun document USAGE Store n'existe encore ; ils ne sont donc pas modifiés artificiellement par cette tranche. + +## 9. Gates de fermeture + +### Gate technique final `pre.008` + +**PASS opérateur complet.** Voir §8.6. Le gate a été reconstruit après `cargo clean` et couvre audits, workspace check/Clippy/tests, builds Tauri des trois Desk et graphes Cargo. Le test ciblé `ksp-program-api` a également été rejoué avec le bon nom de package. + +### Réconciliation documentaire `pre.009` + +**PRÊT après audits documentaires.** Voir §8.7. Le plan, la validation, les architectures Store réellement concernées et `IDEAS.md` sont réconciliés. Aucun README/USAGE Store n'existe à maintenir actuellement ; `CHANGELOG.md`, `ROADMAP.md` et le prompt suivant restent réservés à `pre.010`. + +### Préparation de publication `pre.010` + +Doit rester limitée à : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompts/021-V0_3_2_START_PROMPT.md +delta pre.010 +``` + +Le `ROADMAP.md` est réconcilié par `pre.001-fix.001` puis `pre.001-fix.002`; `pre.010` ne doit plus avoir à réparer la taxonomie N1/N2 ni le split backend. + +## 10. PostgreSQL reporté à `0.3.2` + +Aucun gate PostgreSQL live n'est demandé à `0.3.1`. + +Le prochain prompt devra transformer les invariants API en façade commune + backend de référence et prévoir : + +```text +ksp-store-lib + -> façade Store commune + -> réexports utiles de ksp-store-api + -> feature postgres par défaut + -> dispatch backend selon Config + -> erreur backend connu mais non compilé + +ksp-store-postgres-lib + -> tokio-postgres + -> pool/TLS audités + -> migrations KSP-owned + -> schema conformance + -> write/read round-trip des modèles API + -> idempotence/race + -> atomic rollback + -> pagination + +Config + -> std.store + -> URI/DSN backend lorsque naturel + -> secrets ${KSP_SECRET_*} / .env owned par ksp-config-lib + -> aucun vrai secret versionné + +sécurité + -> URI/DSN/credentials redacted + -> aucune lecture directe env/.env par Store ou backend + -> PostgreSQL réel opt-in puis gate final obligatoire +``` + +## 11. État des tranches + +| Tranche | Objet | État | +|-----------|------------------------------------------|---------------------------------| +| `pre.001` | audit/design/taxonomie/split | PASS | +| `pre.002` | scaffold + taxonomie Store API | PASS | +| `pre.003` | primitives + RawTransaction | PASS après `fix.001` | +| `pre.004` | admission matrix + account/status models | PASS | +| `pre.005` | backend contracts/capabilities | PASS | +| `pre.006` | queries/outcomes/retention/tombstone | PASS après `fix.001` | +| `pre.007` | boundary/adversarial/completeness | PASS après `fix.001` | +| `pre.008` | gate technique final | PASS opérateur complet | +| `pre.009` | réconciliation documentaire | PRÊT après audits documentaires | +| `pre.010` | préparation publication | À FAIRE | +| `rel.001` | stable | À FAIRE |