v0.3.1-pre.001
This commit is contained in:
@@ -1,12 +1,12 @@
|
|||||||
# file: Cargo.toml
|
# file: Cargo.toml
|
||||||
# version: 322
|
# version: 323
|
||||||
|
|
||||||
[workspace]
|
[workspace]
|
||||||
resolver = "3"
|
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-wallet-lib"]
|
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-wallet-lib"]
|
||||||
|
|
||||||
[workspace.package]
|
[workspace.package]
|
||||||
version = "0.2.14"
|
version = "0.3.1-pre.1"
|
||||||
edition = "2024"
|
edition = "2024"
|
||||||
license = "MIT"
|
license = "MIT"
|
||||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||||
|
|||||||
296
deltas/0.3.1/pre.001.md
Normal file
296
deltas/0.3.1/pre.001.md
Normal file
@@ -0,0 +1,296 @@
|
|||||||
|
<!-- file: deltas/0.3.1/pre.001.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# Delta `0.3.1-pre.001` — audit Store API, N1 RAW et split PostgreSQL
|
||||||
|
|
||||||
|
## 1. Base requise
|
||||||
|
|
||||||
|
Base directe attendue :
|
||||||
|
|
||||||
|
```text
|
||||||
|
v0.2.14
|
||||||
|
workspace.package.version = 0.2.14
|
||||||
|
```
|
||||||
|
|
||||||
|
Sources obligatoires réellement disponibles à l'ouverture :
|
||||||
|
|
||||||
|
```text
|
||||||
|
archive opérateur khadhroony-solana-project-v0.2.14.zip
|
||||||
|
archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip
|
||||||
|
```
|
||||||
|
|
||||||
|
La metadata Git n'est pas incluse dans l'archive opérateur ; le tag `v0.2.14` ne peut donc pas être interrogé localement. La version Cargo, `deltas/0.2.14/rel.001.md`, le prompt 020 et la surface Program API publiée concordent avec la base stable attendue.
|
||||||
|
|
||||||
|
Commit attendu :
|
||||||
|
|
||||||
|
```text
|
||||||
|
v0.3.1-pre.001
|
||||||
|
```
|
||||||
|
|
||||||
|
Archive overlay attendue :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-general-0.3.1-pre.001.zip
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Objectif
|
||||||
|
|
||||||
|
Ouvrir `0.3.1` uniquement par le gate prévu :
|
||||||
|
|
||||||
|
```text
|
||||||
|
lecture règles + architecture
|
||||||
|
audit base KSP stable
|
||||||
|
audit historique kbot3
|
||||||
|
audit PostgreSQL/driver actuel
|
||||||
|
brainstorming N1 RAW
|
||||||
|
split ksp-store-api / ksp-store-lib
|
||||||
|
ownership
|
||||||
|
API candidate
|
||||||
|
backend extension model
|
||||||
|
threat model
|
||||||
|
stratégie de tests
|
||||||
|
sizing et prévision souple recalibrée
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucune crate Store fonctionnelle n'est ajoutée dans cette livraison.
|
||||||
|
|
||||||
|
## 3. Décision de scope majeure
|
||||||
|
|
||||||
|
Le scope du prompt initial est volontairement réduit et scindé :
|
||||||
|
|
||||||
|
```text
|
||||||
|
0.3.1 = ksp-store-api uniquement
|
||||||
|
0.3.2 = ksp-store-lib PostgreSQL via tokio-postgres
|
||||||
|
```
|
||||||
|
|
||||||
|
`ksp-store-api` possédera le modèle objet/struct commun et les opérations backend-agnostic. Les représentations internes, rows, requêtes, migrations, pools et transactions SQL seront invisibles aux consumers.
|
||||||
|
|
||||||
|
Une future implémentation alternative, par exemple `ksp-store-mysql-lib`, dépendra directement de `ksp-store-api` et non de `ksp-store-lib`.
|
||||||
|
|
||||||
|
La composition/configuration choisira l'implémentation liée au host puis fournira la même façade `Store` aux consumers.
|
||||||
|
|
||||||
|
Le `ROADMAP.md` stable contient encore l'ancienne prévision combinée. Il n'est pas modifié dans cette tranche et sera réconcilié dans la lane de préparation de publication conformément au workflow KSP.
|
||||||
|
|
||||||
|
## 4. N1 RAW retenu
|
||||||
|
|
||||||
|
Le niveau N1/D1 est défini comme acquisition persistée/replayable.
|
||||||
|
|
||||||
|
Surface initiale `0.3.1` :
|
||||||
|
|
||||||
|
```text
|
||||||
|
RawTransaction
|
||||||
|
RawTransactionObservation
|
||||||
|
RawLog
|
||||||
|
RawLogObservation
|
||||||
|
RawPayload/provenance/reference/outcome/page communs
|
||||||
|
```
|
||||||
|
|
||||||
|
Familles prévues mais reportées :
|
||||||
|
|
||||||
|
```text
|
||||||
|
RawAccount
|
||||||
|
RawBlock
|
||||||
|
RawSlot/updates si besoin durable distinct
|
||||||
|
autres acquisitions justifiées ultérieurement
|
||||||
|
```
|
||||||
|
|
||||||
|
HTTP, WebSocket et gRPC sont des moyens d'acquisition/provenance, pas des familles RAW séparées.
|
||||||
|
|
||||||
|
Le RAW transaction devra pouvoir être transformé ultérieurement en normalisation Solana générique (actuellement nommée CORE/D2), puis décomposé en instructions top-level et CPI indépendantes afin qu'un decoder absent/Unsupported n'empêche pas le traitement du reste.
|
||||||
|
|
||||||
|
## 5. API/backend model
|
||||||
|
|
||||||
|
Décisions candidates :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Store = façade consumer commune
|
||||||
|
StoreBackend = contrat d'implémentation externe object-safe
|
||||||
|
capabilities = StoreHealth + RawTransactionStore + RawLogStore
|
||||||
|
async = StoreFuture<'a, T> boxed KSP-owned par défaut
|
||||||
|
atomicité = opérations métier persist_*_acquisition
|
||||||
|
transaction SQL handle public = interdit
|
||||||
|
page = 100 défaut / 500 max / cursor opaque borné
|
||||||
|
```
|
||||||
|
|
||||||
|
Sémantique d'idempotence :
|
||||||
|
|
||||||
|
```text
|
||||||
|
nouvelle clé -> Inserted
|
||||||
|
même clé + même contenu -> AlreadyPresent
|
||||||
|
même clé + contenu divergent -> Error Conflict
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun `has_*` n'est requis avant write.
|
||||||
|
|
||||||
|
## 6. Héritage kbot3
|
||||||
|
|
||||||
|
L'archive historique a été extraite et les surfaces Store prioritaires réellement relues.
|
||||||
|
|
||||||
|
Le Store historique comporte 16 tables N1-N3, 240 ressources SQL atomiques et 79 index attendus. La séparation façade/PostgreSQL, les observations, la pagination bornée et l'idempotence sont réutilisables conceptuellement, mais les contrats N2/N3 et la représentation physique ne sont pas repris.
|
||||||
|
|
||||||
|
Résumé :
|
||||||
|
|
||||||
|
```text
|
||||||
|
REPRENDRE séparation façade/backend, health portable, repository capabilities, pagination bornée, observations, idempotence
|
||||||
|
REDESSINER StoreOpenOptions, raw DTO/entities, write semantics, diagnostics, Config Store
|
||||||
|
REPORTER schema/migrations/indexes, raw table physique, replay processing, CORE, DECODE, materialization, processing ledger
|
||||||
|
REJETER maintenance destructive publique, JSON backend options opaque, PK SQL comme identité API, monolithe N1/N2/N3
|
||||||
|
```
|
||||||
|
|
||||||
|
La matrice détaillée est dans `docs/plans/022-V0_3_1_STORE_RAW_PLAN.md`.
|
||||||
|
|
||||||
|
## 7. Audit externe
|
||||||
|
|
||||||
|
Audit actuel au 28 août 2026 :
|
||||||
|
|
||||||
|
```text
|
||||||
|
PostgreSQL 18.6 — stable courant, 13 août 2026
|
||||||
|
tokio-postgres 0.7.18 — stable courant, 12 juin 2026
|
||||||
|
Rust 2024, MSRV 1.85
|
||||||
|
prepared statements / transactions / COPY / async pipelined supportés
|
||||||
|
```
|
||||||
|
|
||||||
|
Décision opérateur : `tokio-postgres` sera le driver interne du backend PostgreSQL de référence dans `0.3.2`.
|
||||||
|
|
||||||
|
Aucune dependency PostgreSQL n'est ajoutée dans `0.3.1`.
|
||||||
|
|
||||||
|
## 8. Dependency graph `0.3.1`
|
||||||
|
|
||||||
|
Cible :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-store-api
|
||||||
|
└── ksp-core-lib
|
||||||
|
```
|
||||||
|
|
||||||
|
`ksp-interface-lib`, serde, chrono, tokio et toute crate DB restent absents tant qu'un usage public réel ne les justifie pas.
|
||||||
|
|
||||||
|
## 9. Sizing recalibré
|
||||||
|
|
||||||
|
Prévision active :
|
||||||
|
|
||||||
|
```text
|
||||||
|
pre.001 audit/design/split
|
||||||
|
pre.002 scaffold ksp-store-api
|
||||||
|
pre.003 primitives RAW + transaction
|
||||||
|
pre.004 raw logs + extensibilité N1
|
||||||
|
pre.005 backend contract + Store facade + external canary
|
||||||
|
pre.006 queries/pagination/outcomes/notification reference
|
||||||
|
pre.007 adversarial/API hardening + completeness
|
||||||
|
pre.008 gate technique final
|
||||||
|
pre.009 réconciliation documentaire
|
||||||
|
pre.010 préparation de publication minimale
|
||||||
|
rel.001 publication stable
|
||||||
|
```
|
||||||
|
|
||||||
|
Le futur `0.3.2` ouvre `ksp-store-lib` PostgreSQL/`tokio-postgres`.
|
||||||
|
|
||||||
|
## 10. Fichiers ajoutés
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
|
||||||
|
docs/validation/018-V0_3_1_STORE_RAW.md
|
||||||
|
deltas/0.3.1/pre.001.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## 11. Fichiers modifiés
|
||||||
|
|
||||||
|
```text
|
||||||
|
Cargo.toml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 12. Fichiers supprimés
|
||||||
|
|
||||||
|
```text
|
||||||
|
aucun
|
||||||
|
```
|
||||||
|
|
||||||
|
## 13. Version Cargo
|
||||||
|
|
||||||
|
La prerelease non-fix synchronise :
|
||||||
|
|
||||||
|
```text
|
||||||
|
workspace.package.version = 0.3.1-pre.1
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucune crate Store n'existe encore ; le changement Cargo identifie uniquement le gate `pre.001` conformément au workflow.
|
||||||
|
|
||||||
|
## 14. Validations de baseline
|
||||||
|
|
||||||
|
Le journal opérateur fourni à l'ouverture sur `v0.2.14` montre :
|
||||||
|
|
||||||
|
```text
|
||||||
|
cargo fmt --all PASS
|
||||||
|
audit Rust général / exports / workspace PASS
|
||||||
|
audit Markdown PASS — 175 tables / 128 fichiers
|
||||||
|
cargo check --workspace PASS
|
||||||
|
cargo clippy --workspace --all-targets PASS
|
||||||
|
cargo test --workspace PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
Les smokes live opt-in restent ignorés comme prévu par leurs contrats.
|
||||||
|
|
||||||
|
Cette preuve de base ne remplace pas le gate après application de `pre.001`.
|
||||||
|
|
||||||
|
## 15. Validations après application
|
||||||
|
|
||||||
|
Dans l'environnement de génération du présent overlay, les contrôles statiques suivants ont été réellement exécutés après modification :
|
||||||
|
|
||||||
|
```text
|
||||||
|
python3 scripts/audit_rust_workspace_rules.py
|
||||||
|
General Rust rule audit: clean
|
||||||
|
Rust export completeness audit: 0 candidate(s)
|
||||||
|
KSP workspace Rust rule audit: clean
|
||||||
|
|
||||||
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
|
||||||
|
Markdown table audit: clean (184 tables, 121 files)
|
||||||
|
```
|
||||||
|
|
||||||
|
`cargo` n'est pas installé dans l'environnement de génération utilisé pour préparer l'archive. `cargo fmt --all`, `cargo check --workspace` et `cargo clippy --workspace --all-targets` n'ont donc pas été rejoués ici et ne sont pas déclarés PASS. Le baseline opérateur `v0.2.14` fourni reste vert, mais ne remplace pas le gate opérateur après application.
|
||||||
|
|
||||||
|
## 16. Validations non requises dans cette tranche
|
||||||
|
|
||||||
|
```text
|
||||||
|
cargo test -p ksp-store-api crate encore absente
|
||||||
|
cargo tree -p ksp-store-api crate encore absente
|
||||||
|
PostgreSQL live backend reporté à 0.3.2
|
||||||
|
migration/schema tests backend reporté à 0.3.2
|
||||||
|
```
|
||||||
|
|
||||||
|
## 17. Questions ouvertes
|
||||||
|
|
||||||
|
Aucune question architecturale ne bloque `pre.002`.
|
||||||
|
|
||||||
|
Restent volontairement à stabiliser par les tranches de code :
|
||||||
|
|
||||||
|
```text
|
||||||
|
nom exact des wrappers d'identité RAW
|
||||||
|
format_id/version concret du premier RawPayload transaction
|
||||||
|
bornes finales payload/provenance
|
||||||
|
identité déterministe exacte d'un RawLog
|
||||||
|
forme finale StoreFuture/backend traits
|
||||||
|
référence notification introduite en pre.006 ou reportée si insuffisamment stable
|
||||||
|
```
|
||||||
|
|
||||||
|
Ces questions ne remettent pas en cause :
|
||||||
|
|
||||||
|
```text
|
||||||
|
Store API seule en 0.3.1
|
||||||
|
PostgreSQL/tokio-postgres en 0.3.2
|
||||||
|
modèle public commun backend-agnostic
|
||||||
|
transaction + logs comme premières familles N1
|
||||||
|
```
|
||||||
|
|
||||||
|
## 18. Application et validation opérateur
|
||||||
|
|
||||||
|
Après application de l'overlay :
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
Aucun scaffold Store, SQL, migration ou changement Config ne doit être ajouté à ce delta.
|
||||||
1015
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
Normal file
1015
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
Normal file
File diff suppressed because it is too large
Load Diff
268
docs/validation/018-V0_3_1_STORE_RAW.md
Normal file
268
docs/validation/018-V0_3_1_STORE_RAW.md
Normal file
@@ -0,0 +1,268 @@
|
|||||||
|
<!-- file: docs/validation/018-V0_3_1_STORE_RAW.md -->
|
||||||
|
<!-- version: 1 -->
|
||||||
|
|
||||||
|
# Validation `0.3.1` — Store API RAW foundation
|
||||||
|
|
||||||
|
## 1. Objet
|
||||||
|
|
||||||
|
Cette matrice est ouverte par `0.3.1-pre.001`. Elle valide désormais **`ksp-store-api` uniquement** ; l'implémentation PostgreSQL `ksp-store-lib` a été déplacée vers `0.3.2` par décision opérateur pendant le gate de brainstorming.
|
||||||
|
|
||||||
|
Le scope concret N1 initial est :
|
||||||
|
|
||||||
|
```text
|
||||||
|
RawTransaction + observation
|
||||||
|
RawLog + observation
|
||||||
|
provenance/références/outcomes/queries communs
|
||||||
|
façade Store + contrat backend externe
|
||||||
|
```
|
||||||
|
|
||||||
|
Les autres familles RAW restent extensibles et reportées jusqu'à audit réel de leur besoin.
|
||||||
|
|
||||||
|
## 2. Gate `pre.001`
|
||||||
|
|
||||||
|
| Critère | Statut | Preuve |
|
||||||
|
|----------------------------|---------|-------------------------------------------------------------------------------|
|
||||||
|
| base stable `0.2.14` | PASS | Cargo `0.2.14`, `rel.001` et prompt 020 présents |
|
||||||
|
| metadata Git/tag | N/A | archive opérateur sans metadata Git exploitable |
|
||||||
|
| baseline opérateur | PASS | audits, check, Clippy et workspace tests fournis verts sur `v0.2.14` |
|
||||||
|
| `ksp-program-api` stable | PASS | façade instruction-only relue |
|
||||||
|
| `ksp-store-api` absent | PASS | aucun répertoire Store API sur la base |
|
||||||
|
| `ksp-store-lib` absent | PASS | aucun répertoire Store lib sur la base |
|
||||||
|
| archive kbot3 disponible | PASS | archive historique extraite et auditée |
|
||||||
|
| règles Store/API relues | PASS | règles KSP/Dependencies/Workflow prescrites relues |
|
||||||
|
| architecture durable relue | PASS | graph/store/acquisition relus, D1/D2 séparés |
|
||||||
|
| matrice héritage kbot3 | PASS | `REPRENDRE / REDESSINER / REPORTER / REJETER` dans le plan 022 |
|
||||||
|
| audit externe PostgreSQL | PASS | PostgreSQL 18.6 courant au 28 août 2026 |
|
||||||
|
| audit driver futur | PASS | `tokio-postgres 0.7.18`, Rust 2024/MSRV 1.85, async/transactions/COPY audités |
|
||||||
|
| split version | PASS | `0.3.1 = Store API`, `0.3.2 = Store lib PostgreSQL` |
|
||||||
|
| dependency graph `0.3.1` | PASS | cible Core-only |
|
||||||
|
| modèle backend commun | PASS | API object/struct commune, rows backend privées |
|
||||||
|
| inventaire RAW initial | PASS | transaction + logs + observations |
|
||||||
|
| autres RAW | REPORTÉ | account/block/slot ajoutés seulement sur besoin audité |
|
||||||
|
| provenance | PASS | provider/protocol/origin/timing sûrs, aucun secret |
|
||||||
|
| idempotence | PASS | atomic put, `Inserted/AlreadyPresent`, divergence = conflict |
|
||||||
|
| API candidate | PASS | façade Store + capabilities object-safe + external backend |
|
||||||
|
| public SQL transaction | ABSENT | invariants atomiques exprimés par opérations métier |
|
||||||
|
| pagination | PASS | 100 par défaut / 500 max / cursor opaque borné |
|
||||||
|
| notification ownership | PASS | référence RAW KSP-owned, mécanisme hors scope |
|
||||||
|
| D2/CORE persistence | ABSENT | explicitement hors `0.3.1` |
|
||||||
|
| DECODE/SPECIALIZED | ABSENT | explicitement hors `0.3.1` |
|
||||||
|
| schema PostgreSQL candidat | REPORTÉ | déplacé intégralement à `0.3.2` par split API/backend |
|
||||||
|
| migration policy | REPORTÉ | responsabilité `ksp-store-lib` `0.3.2` |
|
||||||
|
| PostgreSQL live gate | REPORTÉ | aucun backend DB dans `0.3.1`; gate obligatoire à définir en `0.3.2` |
|
||||||
|
| threat model | PASS | modèle hostile/API/backend couvert dans plan 022 |
|
||||||
|
| stratégie de tests | PASS | unit/public/external/firewall/completeness, aucun PostgreSQL live |
|
||||||
|
| sizing | PASS | dix prereleases courtes + lanes fermeture séparées |
|
||||||
|
|
||||||
|
## 3. Décisions structurelles à prouver par le code
|
||||||
|
|
||||||
|
| Contrat | Décision `pre.001` | 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` |
|
||||||
|
| backend PostgreSQL | absent de `0.3.1` | completeness `pre.007` |
|
||||||
|
| `RawPayload` | KSP-owned, source-independent, versionné, borné, Debug sans bytes | `pre.003` |
|
||||||
|
| transaction identity | réseau + signature logique, jamais PK SQL | `pre.003` |
|
||||||
|
| `RawTransaction` | objet persistant commun replayable | `pre.003` |
|
||||||
|
| `RawTransactionObservation` | acquisition/provenance séparée du RAW | `pre.003` |
|
||||||
|
| `RawLog` | famille N1 distincte avec ordering préservé | `pre.004` |
|
||||||
|
| `RawLogObservation` | provenance séparée du log canonique | `pre.004` |
|
||||||
|
| future RAW families | extensibles sans JSON universel | `pre.004` / `pre.007` |
|
||||||
|
| `StoreFuture<'a, T>` | future object-safe KSP-owned, sans `async-trait` par défaut | `pre.005` |
|
||||||
|
| backend trait | implémentable hors workspace, `Send + Sync` | `pre.005` |
|
||||||
|
| façade `Store` | même consumer surface quel que soit backend injecté | `pre.005` |
|
||||||
|
| transaction handle | aucun handle SQL/backend public | `pre.005` |
|
||||||
|
| atomic acquisition | méthode métier RAW + observation all-or-nothing | `pre.005` / `pre.006` |
|
||||||
|
| write outcome | `Inserted / AlreadyPresent`; divergence = `Err Conflict` | `pre.006` |
|
||||||
|
| `PageRequest` | borné, default 100, max 500 | `pre.006` |
|
||||||
|
| cursor | opaque, borné, aucun SQL/backend contract visible | `pre.006` |
|
||||||
|
| notification reference | compacte, durable, payload non dupliqué | `pre.006` ou report explicite |
|
||||||
|
| health | portable et sanitisé | `pre.005` / `pre.006` |
|
||||||
|
|
||||||
|
## 4. Dependency firewall final attendu
|
||||||
|
|
||||||
|
Le graphe final `0.3.1` doit rester :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-store-api
|
||||||
|
└── ksp-core-lib
|
||||||
|
└── solana-pubkey
|
||||||
|
```
|
||||||
|
|
||||||
|
Interdits par défaut dans Store API :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-store-lib
|
||||||
|
ksp-onchain-transport-lib
|
||||||
|
ksp-offchain-transport-lib
|
||||||
|
ksp-interface-lib sans usage de type réel
|
||||||
|
ksp-program-api
|
||||||
|
ksp-program-lib
|
||||||
|
ksp-materializer-api
|
||||||
|
ksp-config-lib
|
||||||
|
ksp-logging-lib
|
||||||
|
ksp-wallet-lib
|
||||||
|
tokio-postgres
|
||||||
|
sqlx
|
||||||
|
serde / serde_json
|
||||||
|
chrono
|
||||||
|
tokio
|
||||||
|
async-trait
|
||||||
|
Tauri
|
||||||
|
```
|
||||||
|
|
||||||
|
Toute divergence exige un usage public réel et une révision du plan.
|
||||||
|
|
||||||
|
## 5. Matrice N1 initiale
|
||||||
|
|
||||||
|
| Famille | `0.3.1` | Identité logique candidate | Replay couvert | Provenance |
|
||||||
|
|-------------|---------|-----------------------------------------------------------|---------------------------------------------------------------------------|-------------------------------|
|
||||||
|
| transaction | IN | network + signature | future décomposition générique Solana complète couverte par le format RAW | observations séparées |
|
||||||
|
| logs | IN | identité transaction/slot + clé déterministe à stabiliser | ordre et contenu log nécessaires à replay/inspection | observations séparées |
|
||||||
|
| account | REPORTÉ | pubkey + context/slot/version à auditer | futur compte RAW replayable | prévu par primitives communes |
|
||||||
|
| block | REPORTÉ | network + slot/block identity | futur backfill/block replay | prévu par primitives communes |
|
||||||
|
| slot/update | REPORTÉ | sémantique exacte à auditer | seulement si un fait durable distinct est utile | prévu par primitives communes |
|
||||||
|
|
||||||
|
## 6. Frontière N1 -> D2
|
||||||
|
|
||||||
|
`0.3.1` doit préserver sans implémenter :
|
||||||
|
|
||||||
|
```text
|
||||||
|
RawTransaction
|
||||||
|
-> generic Solana normalization
|
||||||
|
-> transaction/message
|
||||||
|
-> account keys
|
||||||
|
-> top-level instructions
|
||||||
|
-> CPI/inner instructions
|
||||||
|
-> logs/meta/balances/return data
|
||||||
|
-> traitement individuel ultérieur
|
||||||
|
```
|
||||||
|
|
||||||
|
Canari négatif durable :
|
||||||
|
|
||||||
|
```text
|
||||||
|
ksp-store-api -X-> ksp-program-api
|
||||||
|
```
|
||||||
|
|
||||||
|
Le terme `CORE` reste le nom architectural actuel de D2 mais peut être renommé avant ouverture de cette couche sans modifier la séparation fonctionnelle.
|
||||||
|
|
||||||
|
## 7. Extensibilité backend
|
||||||
|
|
||||||
|
Le canari externe doit démontrer :
|
||||||
|
|
||||||
|
```text
|
||||||
|
crate/test consumer externe
|
||||||
|
-> dépend de ksp-store-api
|
||||||
|
-> définit son propre backend mémoire
|
||||||
|
-> implémente le contrat public
|
||||||
|
-> construit la façade Store
|
||||||
|
-> écrit et relit transaction/log via les mêmes fonctions
|
||||||
|
-X-> ksp-store-lib
|
||||||
|
-X-> PostgreSQL
|
||||||
|
```
|
||||||
|
|
||||||
|
L'implémentation PostgreSQL officielle de `0.3.2` devra satisfaire la même suite de conformance.
|
||||||
|
|
||||||
|
## 8. Threat/API gates futurs
|
||||||
|
|
||||||
|
| Gate | Attendu | Statut initial |
|
||||||
|
|---------------------------------|-----------------------------------------------------|-----------------------|
|
||||||
|
| oversized RAW payload | rejet avant stockage/copied allocation pathologique | `pre.003` |
|
||||||
|
| payload Debug | aucun bytes brut | `pre.003` |
|
||||||
|
| hostile provenance text | borné/trim/control policy explicite | `pre.003` |
|
||||||
|
| duplicate same content | outcome `AlreadyPresent` | `pre.006` |
|
||||||
|
| duplicate divergent content | erreur Conflict stable | `pre.006` |
|
||||||
|
| check-then-insert | absent de l'API publique | `pre.005` |
|
||||||
|
| partial transaction+observation | interdit par atomic acquisition contract | `pre.005` |
|
||||||
|
| page limit 0/>500 | rejet | `pre.006` |
|
||||||
|
| cursor oversize | rejet | `pre.006` |
|
||||||
|
| SQL/backend cursor leak | absent | `pre.006` / `pre.007` |
|
||||||
|
| provider secret leak | absent du modèle public | `pre.003` / `pre.007` |
|
||||||
|
| backend row/public type | absent | `pre.007` |
|
||||||
|
| async runtime dependency | aucune dependency Tokio dans API par défaut | `pre.005` / `pre.007` |
|
||||||
|
| external backend | compile et fonctionne sans Store lib | `pre.005` |
|
||||||
|
| closed RAW enum | future family ajoutable | `pre.004` / `pre.007` |
|
||||||
|
| D2/D3/D4 creep | aucune surface | `pre.007` |
|
||||||
|
|
||||||
|
## 9. Gates de fermeture prévus
|
||||||
|
|
||||||
|
### Gate technique final `pre.008`
|
||||||
|
|
||||||
|
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` y réconcilie la nouvelle séquence `0.3.1 API -> 0.3.2 PostgreSQL`.
|
||||||
|
|
||||||
|
## 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 backend de référence et prévoir :
|
||||||
|
|
||||||
|
```text
|
||||||
|
tokio-postgres
|
||||||
|
settings programmatiques issus de Config/composition
|
||||||
|
pool/TLS audités
|
||||||
|
migrations KSP-owned
|
||||||
|
schema conformance
|
||||||
|
write/read round-trip des modèles API
|
||||||
|
idempotence/race
|
||||||
|
atomic rollback
|
||||||
|
pagination
|
||||||
|
error/DSN redaction
|
||||||
|
PostgreSQL réel opt-in puis gate final obligatoire
|
||||||
|
```
|
||||||
|
|
||||||
|
## 11. État initial des tranches
|
||||||
|
|
||||||
|
| Tranche | Objet | État |
|
||||||
|
|-----------|---------------------------------|-----------------------|
|
||||||
|
| `pre.001` | audit/design/split API/backend | PRÊT après gate local |
|
||||||
|
| `pre.002` | scaffold Store API | À FAIRE |
|
||||||
|
| `pre.003` | primitives + RawTransaction | À FAIRE |
|
||||||
|
| `pre.004` | RawLog + extensibilité N1 | À FAIRE |
|
||||||
|
| `pre.005` | backend contract + façade Store | À FAIRE |
|
||||||
|
| `pre.006` | queries/outcomes/notification | À FAIRE |
|
||||||
|
| `pre.007` | adversarial/completeness | À FAIRE |
|
||||||
|
| `pre.008` | gate technique final | À FAIRE |
|
||||||
|
| `pre.009` | réconciliation documentaire | À FAIRE |
|
||||||
|
| `pre.010` | préparation publication | À FAIRE |
|
||||||
|
| `rel.001` | stable | À FAIRE |
|
||||||
Reference in New Issue
Block a user