# Prompt de démarrage `0.3.3` — Store/PostgreSQL `RawTransaction` vertical slice ## 1. Identité de la release et base exacte requise La release à ouvrir est : ```text 0.3.3 — Store/PostgreSQL RawTransaction vertical slice ``` La base autoritaire attendue est exclusivement la release stable : ```text v0.3.2 workspace.package.version = 0.3.2 ``` La nouvelle session doit partir de l'archive opérateur stable `0.3.2` lorsqu'elle est fournie. Cette archive gagne sur les souvenirs, snippets, anciens overlays et prompts intermédiaires. L'archive historique suivante est également **obligatoire pour `pre.001`** : ```text khadhroony-bot3_v0.5.3-pre.005-fix010.zip ``` Elle sert uniquement à auditer l'ancien schéma/repository PostgreSQL des transactions RAW et leurs observations. Elle n'est jamais une base de code ni une autorité architecturale. Ne pas ouvrir `0.3.3` depuis : ```text 0.3.2-pre.* 0.3.2-pre.*-fix.* 0.3.2-rel.* non encore publié stable une archive de travail intermédiaire khadhroony-bot3 comme base de code un souvenir de session ``` À l'ouverture, vérifier au minimum : ```text tag Git v0.3.2 si metadata Git disponible workspace.package.version = 0.3.2 deltas/0.3.2/rel.001.md présent prompts/022-V0_3_3_START_PROMPT.md présent ksp-store-api présent ksp-store-lib présent ksp-store-postgres-lib présent migration bootstrap V000 présente Config std.store présent archive khadhroony-bot3_v0.5.3-pre.005-fix010.zip disponible ``` Si une divergence existe entre ce prompt et la base stable réelle, **la base stable réelle gagne** et la divergence devient une sortie explicite de `pre.001`. `pre.001` reste obligatoirement une tranche de **lecture + audit + brainstorming + threat model + design physique + sizing + planification**. Ne pas commencer la migration métier `RawTransaction` ni les repositories SQL avant la sortie cohérente de ce gate. --- ## 2. Mission et résultat attendu `0.3.3` étend le couple existant : ```text ksp-store-lib ksp-store-postgres-lib ``` avec la première vertical slice métier PostgreSQL complète de `ksp-store-api` : ```text RawTransaction RawTransactionObservation RawTransaction query/pagination RawTransaction retention/tombstone/force-rehydrate ``` Les six capabilities `ksp-store-api` concernées sont : ```text RawTransactionRead RawTransactionWrite RawTransactionObservationRead RawTransactionObservationWrite RawTransactionRetentionRead RawTransactionRetentionWrite ``` Le résultat attendu à la clôture est que : ```text ksp-store-postgres-lib implémente réellement la persistence physique RawTransaction ksp-store-lib::Store expose/dispatch les six capabilities via la façade commune une acquisition transaction + observation est atomique les writes sont idempotents pour un contenu identique une même identité avec contenu divergent retourne ERROR_CODE_RAW_CONFLICT une observation supplémentaire est idempotente et liée à une transaction existante get/list respectent les contrats backend-agnostic la pagination est déterministe et cursorisée sans policy worker cachée la rétention/tombstone/force-rehydrate est atomique et conforme aux contrats acquis les mismatches de network sont rejetés avant I/O aucun type PostgreSQL/row/SQL ne fuit par ksp-store-lib le tout est prouvé sur PostgreSQL réel par un gate opt-in non destructif ``` La release **ne doit pas** ouvrir `RawAccountState`. Cette famille reste réservée à : ```text 0.3.4 — RawAccountState PostgreSQL + complétude/conformance RAW ``` --- ## 3. Sources de vérité internes obligatoires — ordre de lecture ### 3.1 Règles globales Lire d'abord : ```text RULES.md docs/000-README.md docs/rules/RULES_GENERAL.md docs/rules/RULES_KSP.md docs/rules/RULES_RUST.md docs/rules/RULES_DEPENDENCIES.md docs/rules/RULES_DOCUMENTATION.md docs/rules/FILE_CONTRACTS.md docs/rules/VERSION_WORKFLOW.md docs/rules/PROMPT_STRUCTURE.md ``` Relire particulièrement les règles applicables aux frontières : ```text KSP-API-* KSP-CONFIG-* KSP-STORE-* KSP-NOTIFY-* KSP-PROC-* KSP-REL-* DEP-KSP-* DEP-CARGO-* DEP-LOG-* DEP-STORE-* DEP-WORKER-* DEP-JOB-* ``` Rappels directement structurants : ```text ksp-store-lib -> ksp-store-api ksp-store-lib[postgres] -> ksp-store-postgres-lib ksp-store-postgres-lib -> ksp-store-api ksp-store-postgres-lib -X-> ksp-store-lib Config -> Store autorisé Store/backend -X-> Config Transport -X-> Store Program/Materializer -X-> Store consumer ordinaire -> ksp-store-lib consumer ordinaire -X-> ksp-store-postgres-lib ``` ### 3.2 Architecture durable Lire ensuite : ```text docs/architecture/000-README.md docs/architecture/001-PROJECT_OBJECTIVES.md docs/architecture/002-LAYERS_AND_DEPENDENCIES.md docs/architecture/003-COMPONENT_CONTRACTS.md docs/architecture/004-COMPONENT_INVENTORY.md docs/architecture/005-DEPENDENCY_GRAPH.md docs/architecture/007-EXECUTION_AND_POLICY.md docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md ``` Préserver notamment : ```text Store persiste et sert ; il ne possède pas la policy de travail pagination/cursorisation Store != batch-size/priorité/backlog worker/job 1 Store instance = 1 RawNetworkId + 1 backend physique pas de multiplexage automatique de réseaux/bases dans Store Config possède targets/URI/.env/secrets backend PostgreSQL possède driver/pool/TLS/SQL/migrations aucun type backend physique ne traverse la façade commune ``` ### 3.3 Contrats RAW stables `0.3.1` Lire intégralement : ```text docs/plans/022-V0_3_1_STORE_RAW_PLAN.md docs/validation/018-V0_3_1_STORE_RAW.md crates/ksp-store-api/Cargo.toml crates/ksp-store-api/src/** crates/ksp-store-api/tests/** ``` Relire particulièrement : ```text RawTransaction / RawTransactionObservation RawTransactionReference RawPayload / RawContentHash / RawObservationKey RawAcquisitionProvenance RawTransactionQuery / RawPage* / RawSlotRange / RawSortDirection RawAcquisitionWriteOutcome / RawEntityWriteOutcome / RawObservationWriteOutcome RawRetentionState RawTransactionAcquisitionMode RawTransactionRetentionTransition RawTransactionTombstone les six capabilities RawTransaction/observation/retention ``` Ne pas redessiner ces contrats pour simplifier PostgreSQL. Une modification de `ksp-store-api` n'est recevable que si `pre.001` démontre un **gap backend-agnostic réel et bloquant**. ### 3.4 Fondation runtime/backend stable `0.3.2` Lire ensuite : ```text docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md crates/ksp-store-lib/Cargo.toml crates/ksp-store-lib/README.md crates/ksp-store-lib/USAGE.md crates/ksp-store-lib/src/** crates/ksp-store-lib/tests/** crates/ksp-store-postgres-lib/Cargo.toml crates/ksp-store-postgres-lib/README.md crates/ksp-store-postgres-lib/USAGE.md crates/ksp-store-postgres-lib/src/** crates/ksp-store-postgres-lib/tests/** crates/ksp-config-lib/README.md crates/ksp-config-lib/USAGE.md config/std.store.json config/schemas/std.store.schema.json config/examples/std.store.example.json ``` Lire enfin : ```text CHANGELOG.md ROADMAP.md ``` Créer en `pre.001` : ```text docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md ``` --- ## 4. Audit historique kbot3 obligatoire et ciblé L'archive kbot3 est requise parce que `0.3.3` ouvre la première vraie persistence métier PostgreSQL. Réauditer uniquement les éléments historiques pouvant informer la conception physique de `RawTransaction` : ```text ks-store/Cargo.toml ks-store/README.md ks-store/USAGE.md ks-store/src/contracts/dto/raw.rs ks-store/src/contracts/entity/raw.rs ks-store/src/contracts/repository.rs ks-store/src/postgres/query/raw_queries.rs ks-store/src/postgres/repository/raw_transaction_repository.rs ks-store/migrations/postgres/schema/tables/create_table_if_not_exists_k_sol_raw_transactions.sql ks-store/migrations/postgres/schema/tables/create_table_if_not_exists_k_sol_obs_transaction_observations.sql ks-store/migrations/postgres/schema/indexes/*raw_transactions* ks-store/migrations/postgres/schema/indexes/*transaction_observations* ks-store/migrations/postgres/schema/constraints/*raw_transactions* ks-store/migrations/postgres/schema/constraints/*transaction_observations* docs/guides/POSTGRES_STORAGE.md docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md ``` Classer explicitement chaque idée utile sous : ```text REPRENDRE REDESSINER REPORTER REJETER ``` L'audit doit notamment comparer : ```text identité physique transaction stockage signature/hash/payload observation/idempotence atomicité acquisition + observation conflit de contenu indexes de lecture/pagination ordre/cursorisation rétention/purge concurrence SQL error mapping ``` Ne pas reprendre automatiquement : ```text SQLx ancien monolithe Store processing_state/processing ledger anticipé CORE/DECODE/materialization maintenance destructive publique identifiants SQL comme API publique JSON métier comme excuse pour contourner RawPayload KSP batch/replay policy dans Store ``` Si l'archive historique n'est pas disponible : ```text ne pas inventer son contenu depuis la mémoire ne pas déclarer l'audit héritage terminé ne pas figer le schéma/indexes RawTransaction définitifs ``` --- ## 5. Sources externes à réauditer lorsque nécessaire La fondation dépend déjà de : ```text tokio-postgres 0.7.x deadpool-postgres 0.14.x tokio-postgres-rustls 0.14.x rustls 0.23 sha2 0.11 ``` La base `0.3.2` a réellement résolu lors de son gate : ```text tokio-postgres 0.7.18 deadpool-postgres 0.14.2 tokio-postgres-rustls 0.14.0 rustls 0.23.43 sha2 0.11.0 ``` `0.3.3` n'est pas une release de mise à jour de dépendances. Ne modifier ces versions/features que si l'audit de la tranche concernée démontre un besoin concret. Consulter les sources PostgreSQL/tokio-postgres actuelles lorsque le design l'exige, en particulier pour : ```text transactions et rollback isolation/locking concurrent INSERT ... ON CONFLICT et garanties réelles constraints/checks/indexes BYTEA et représentation de valeurs fixed-width représentation exacte des u64/u32 KSP sans narrowing ordre stable et keyset pagination limites SQL/parameter/row applicables comportement de statement/transaction sous cancellation ``` Préférer les sources primaires PostgreSQL et upstream tokio-postgres. Ne pas ajouter ORM/query builder/codec externe par habitude. --- ## 6. État validé `0.3.2` à préserver ### 6.1 Façade/runtime La base stable possède : ```text ksp-store-lib 84 exports crate-root au gate 0.3.2 feature default = postgres ksp-store-postgres-lib optional dependency Store::open(settings).await Store::runtime_snapshot() Store::health().await Store::close(self).await Store non Clone Store lié à exactement un RawNetworkId ``` `ksp-store-lib` ne possède ni SQL ni type physique PostgreSQL. ### 6.2 Backend PostgreSQL La base stable possède : ```text ksp-store-postgres-lib PostgresBackend / PostgresBackendSettings pool Deadpool borné TLS Disabled / VerifyFull Rustls + roots système + AWS-LC URI parsing/normalization/redaction aucune lecture env/PG*/.pgpass bootstrap privé health/readiness sûr shutdown borné ``` Les types suivants restent privés : ```text Pool Client Row Statement Transaction SQL config driver TLS internals ``` ### 6.3 Migrations La fondation stable possède : ```text V000__bootstrap.sql ksp_store_schema_migrations version/name/SHA-256 advisory transaction lock borné bootstrap transactionnel mismatch/newer schema explicites aucun down automatique ``` La prochaine migration métier commence donc normalement à : ```text V001 ``` `pre.001` doit confirmer la convention exacte avant création. ### 6.4 Config et réseaux `std.store` possède les targets : ```text devnet -> network devnet mainnet -> network mainnet-beta testnet -> network testnet ``` Chaque target utilise une URI/base PostgreSQL indépendante. `Store` n'est pas un registry multi-target. Invariant acquis : ```text Store.network != input/query/reference.network -> rejet avant I/O -> jamais de routage automatique vers une autre Store ``` ### 6.5 Preuve PostgreSQL réelle Le gate `0.3.2` a exercé la fondation sur : ```text PostgreSQL major 17 ``` La policy de fondation supportée reste : ```text PostgreSQL >= 15 ``` Aucun maximum artificiel n'est imposé par KSP. ### 6.6 Ce qui est encore absent À l'ouverture de `0.3.3`, le backend PostgreSQL ne doit encore implémenter aucune capability métier : ```text RawTransaction* RawAccountState* ``` Aucune table/index métier RAW ne doit exister dans les migrations KSP `0.3.2`. --- ## 7. Décisions acquises et questions réellement ouvertes ### 7.1 Décisions acquises ```text mêmes crates ksp-store-lib + ksp-store-postgres-lib pas de nouvelle façade Store pas de nouvelle crate repository PostgreSQL reste le backend de référence les six capabilities RawTransaction sont la surface fonctionnelle de 0.3.3 ksp-store-postgres-lib réalise la persistence physique ksp-store-lib::Store dispatch les capabilities aux backends compilés network mismatch rejeté avant I/O acquisition transaction + observation atomique même identité + même contenu = idempotence même identité + contenu divergent = ERROR_CODE_RAW_CONFLICT observation_key est la clé d'idempotence observation normal sur tombstone purgé = SkippedPurged / NotRecorded ForceRehydrate est explicite et ne masque jamais un conflit pagination Store reste navigation/cursorisation uniquement batch-size/priorité/backlog/policy restent hors Store SQL/rows/index ids restent privés au backend Config reste propriétaire des URI/secrets/targets ``` ### 7.2 Questions à fermer obligatoirement en `pre.001` #### Schéma physique et binding réseau Décider explicitement : ```text noms des tables/indexes/constraints KSP clé physique transaction clé physique observation comment la database prouve son RawNetworkId en cas d'URI mal configurée network stocké par ligne, metadata de database, ou autre preuve robuste ``` Une mauvaise URI ne doit jamais permettre de relire silencieusement des données Devnet comme Mainnet ou inversement. #### Représentation des entiers KSP Auditer sans narrowing : ```text slot u64 format_version u32 source_payload_size_bytes u64 borné RawTimestamp u64 borné page limit u64 ``` PostgreSQL `BIGINT` est signé. Il est interdit de résoudre la différence par un cast silencieux ou une réduction arbitraire du contrat `ksp-store-api`. #### Idempotence et concurrence Figer l'algorithme exact pour : ```text deux inserts identiques concurrents deux inserts divergents concurrents transaction déjà présente + observation nouvelle observation_key déjà présent identique observation_key déjà présent divergent ForceRehydrate concurrent rollback si l'observation échoue après la partie canonical ``` Éviter tout pattern race-prone du type : ```text SELECT/has puis INSERT séparé sans garantie transactionnelle ``` #### Pagination/cursor Figer : ```text ordre total déterministe clé de tie-break format/version du cursor opaque validation d'un cursor hostile liaison du cursor à network/range/direction si nécessaire comportement pour une RawPageLimit trop grande pour une limite physique PostgreSQL réelle ``` Le cursor : ```text ne contient aucun SQL public ne contient aucun secret ne devient pas un protocole public documenté reste <= MAX_RAW_PAGE_CURSOR_BYTES ``` Ne pas ajouter `bincode`. Si un encodage privé fixe suffit, le coder directement sans ouvrir un codec wire KSP. Les codecs wire officiels restent possédés par `ksp-interface-lib` et ne sont ajoutés que lorsqu'un protocole réel l'exige. #### Rétention physique Les contrats logiques acquis sont : ```text Full -> Compacted -> Archived -> Purged Full -> Archived Compacted -> Archived ``` `pre.001` doit décider comment PostgreSQL peut représenter **honnêtement** chaque état supporté. Ne pas marquer `Compacted` si aucun compactage réel n'existe, ni `Archived` si le payload reste simplement dans le même hot path sans sémantique d'archive. Si un gap backend-agnostic empêche une conformance honnête, le documenter avant de modifier `ksp-store-api`. `Purged` doit conserver le tombstone minimal défini par l'API et supprimer l'accès ordinaire au payload complet. #### Erreurs Définir une taxonomie sûre pour les échecs de persistence/query backend : ```text conflit logique -> ERROR_CODE_RAW_CONFLICT input/query invalide -> codes Store API existants backend/SQL failure -> code(s) Store runtime sûrs à définir si nécessaires aucun SQLSTATE/message serveur/valeur bindée sensible dans l'erreur publique ``` --- ## 8. Livrables fonctionnels et hors périmètre ### 8.1 Livrables `0.3.3` doit livrer : ```text migration(s) métier RawTransaction à partir de V001 schema/constraints/indexes PostgreSQL minimaux justifiés mapping privé rows <-> ksp-store-api impl des six capabilities sur le backend PostgreSQL impl/dispatch des six capabilities sur Store atomicité canonical + observation idempotence/conflits get transaction get observation record observation list références transaction cursorisé retention state retention transition atomique tombstone ForceRehydrate tests déterministes canaris API/dependency/security PostgreSQL live integration README/USAGE/plan/validation réconciliés en fermeture ``` ### 8.2 Hors périmètre strict Ne pas ouvrir : ```text RawAccountState PostgreSQL RawAccountObservation PostgreSQL schema/indexes account state N2 STRUCTURAL N3 DECODED N4 DOMAIN processing ledger worker/job/backfill batch scheduler Store Desk / inspection app event bus / LISTEN NOTIFY nouveau transport/acquisition provider conversion HTTP/WS/gRPC -> RawTransaction codec wire officiel compression/archive worker global maintenance destructive publique backend MySQL/SQLite/Oracle/RocksDB/ClickHouse ``` Les tests peuvent construire directement des modèles `ksp-store-api`; `0.3.3` ne doit pas aspirer Transport uniquement pour fabriquer des fixtures. --- ## 9. Contraintes sécurité/API/architecture spécifiques ### 9.1 Atomicité ```text persist_raw_transaction_acquisition canonical + observation dans une unité atomique jamais canonical durable si observation échoue jamais observation orpheline ``` Toute course concurrente doit produire un outcome déterministe ou une erreur stable, jamais un overwrite silencieux. ### 9.2 Network boundary Avant toute acquisition/query/retention : ```text input.network == Store.network ``` Sinon : ```text rejet avant pool.get / SQL aucun fallback aucun auto-routing ``` Le backend doit également empêcher une mauvaise URI de transformer l'identité réseau des données déjà persistées. ### 9.3 SQL ```text SQL statique ou paramètres bindés aucune interpolation de valeur métier identifiants physiques constants KSP constraints correspondant aux invariants exacts lorsqu'elles sont utiles pas de SQL exposé dans API/log/error pas d'ORM ajouté sans besoin démontré ``` ### 9.4 Représentation des bytes Préserver exactement : ```text signature 64 bytes content hash 32 bytes observation key 32 bytes payload canonical opaque <= 16 MiB source payload hash optionnel 32 bytes ``` Une lecture de row invalide est un échec backend sûr ; elle ne doit jamais reconstruire un modèle partiel ou tronqué. ### 9.5 Pagination Utiliser une pagination keyset/cursor déterministe si retenue par `pre.001`; ne pas utiliser un `OFFSET` non borné comme substitut automatique à un cursor opaque lorsque cela compromet stabilité ou coût. Aucune limite `100`, `500`, `1000`, etc. n'est inventée par Store. Une limitation physique réelle doit être représentée honnêtement par continuation ou erreur backend justifiée. ### 9.6 Rétention et policy Store applique la transition demandée par le caller ; il ne décide jamais : ```text quand compacter quand archiver quand purger si STRUCTURAL/DECODED est suffisamment complet ``` Ces décisions appartiennent aux futurs jobs/workers/policies. ### 9.7 Secrets et diagnostics Aucun : ```text URI credential payload RAW signature complète hash complet observation key complète SQL bind value server error brut ``` ne doit apparaître dans un log/error/debug non explicitement conçu pour l'exposer. Les `Debug` existants de Store API restent la référence de redaction. ### 9.8 Async/runtime ```text async-first pas de runtime global additionnel pas de spawn orphelin pas de mutex sync gardé à travers await transactions SQL bornées par les timeouts existants ou des bounds justifiés pool central réutilisé shutdown foundation inchangé ``` ### 9.9 Logging Utiliser uniquement `ksp-logging-lib` avec `TRACING_TARGET` existant. Ne pas journaliser les données métier RAW ni le SQL. --- ## 10. Première mission `0.3.3-pre.001` `pre.001` ne crée pas encore la migration métier ni les repositories lourds. ### 10.1 Vérifier la base stable réelle Inventorier : ```text versions Cargo/features Store exports/modules exacts des trois crates Store migrations présentes et checksum V000 Config std.store final Store/network lifecycle final tests hardening/completeness 0.3.2 PostgreSQL live proof 0.3.2 ``` ### 10.2 Auditer exactement les six capabilities Pour chacune, écrire une matrice : ```text input invariants pré-I/O transaction SQL nécessaire row(s) touchée(s) idempotence conflit absence/not-found error mapping concurrence test déterministe test PostgreSQL live ``` ### 10.3 Audit historique kbot3 ciblé Exécuter l'audit de la section 4 et produire la classification `REPRENDRE / REDESSINER / REPORTER / REJETER`. ### 10.4 Design physique Proposer puis figer : ```text V001 exact noms tables/columns/indexes/constraints network binding database/rows mapping de tous les champs API représentation u64/u32 sans narrowing algorithme conflict/idempotence transaction boundaries observation uniqueness cursor format/order retention storage purge/tombstone ForceRehydrate error taxonomy ``` Aucun champ physique ne doit être ajouté « au cas où » pour les futurs processors. ### 10.5 Threat model Couvrir au minimum : ```text wrong-network input avant I/O wrong-network database URI signature/hash/key malformed dans DB payload oversized/corrupted dans DB u64 overflow/narrowing observation orphan canonical orphan après rollback identical concurrent insert divergent concurrent insert observation-key collision cursor hostile/replayed against another query pagination duplicate/skip sous ordre ambigu retention compare-and-transition race purge vs read/write race ForceRehydrate vs normal acquisition race SQL/server error leak pool cancellation pendant transaction schema/index migration mismatch ``` ### 10.6 Sizing Chaque tranche intermédiaire prévue au-delà d'environ **15 à 20 minutes de travail effectif** doit être scindée avant implémentation. Ce budget sert au sizing, pas à promettre un délai. Si `RawTransaction` complet ne semble plus clôturable dans une session, redécouper la release avant le SQL lourd. Ne jamais tirer `RawAccountState` dans `0.3.3`. ### 10.7 Documents de gate Créer : ```text docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md ``` Le plan doit reprendre la prévision souple recalibrée et les décisions physiques exactes. ### 10.8 Critères de sortie de `pre.001` `pre.001` est terminé seulement si : ```text base stable vérifiée règles/architecture 0.3.1/0.3.2 relues six capabilities auditées archive kbot3 ciblée relue et classée schema V001 proposé network binding décidé représentation u64/u32 décidée atomicité/idempotence/conflit décidés cursor/order décidés retention/tombstone/rehydrate décidés ou gap API explicitement identifié error taxonomy décidée indexes minimaux justifiés threat model complet stratégie live PostgreSQL définie plan 024 créé validation 020 créée prévision souple recalibrée aucun RawAccountState/N2/worker aspiré ``` --- ## 11. Prévision souple initiale des prereleases Cette prévision est volontairement fine et peut être scindée/recalibrée par `pre.001`. ### `pre.001` — Audit contrats, kbot3, schéma, concurrence et sizing Lecture complète, matrice des six capabilities, audit historique ciblé, design V001/indexes/network binding/u64/cursor/rétention, threat model et plan/validation. ### `pre.002` — Migration V001 + schéma/indexes RawTransaction Ajouter uniquement les structures physiques réellement nécessaires à `RawTransaction`, observations et rétention, via le moteur de migrations KSP existant. Tests checksum/history/schema. Pas encore de façade métier complète. ### `pre.003` — Mapping physique + lectures unitaires Introduire les mappings privés rows/API et les primitives SQL de lecture `get transaction`, `get observation`, retention metadata/tombstone, avec validation hostile des rows. Aucun type SQL public. ### `pre.004` — Persistence acquisition atomique + observations Implémenter `persist_raw_transaction_acquisition` et `record_raw_transaction_observation` avec atomicité, idempotence, conflit et concurrence déterministes. ### `pre.005` — List/query + cursorisation Implémenter `RawTransactionQuery`, ordre total, slot range, directions, cursor opaque/versionné, continuation et gestion honnête des limites physiques. ### `pre.006` — Rétention, tombstone et ForceRehydrate Implémenter compare-and-transition atomique, lecture state/tombstone, purge conforme et réhydratation forcée selon le design `pre.001`, sans policy worker. ### `pre.007` — Composition façade + conformance des six capabilities Faire implémenter/dispatcher les six traits par `Store`, fermer network mismatch pré-I/O, error mapping, feature mismatch et canaris d'API/dependency. ### `pre.008` — PostgreSQL integration réelle RawTransaction Gate opt-in sur base dédiée : migration V001, write/read, observation, idempotence, conflit, concurrence, pagination multi-page, rétention/tombstone/rehydrate, rollback et close. ### `pre.009` — Hardening/completeness Inputs hostiles, rows corrompues, cursor adversarial, no-secret/no-SQL-leak, exact exports/modules, `ksp-store-api` non régressé, aucun AccountState, aucun worker policy. ### `pre.010` — Gate technique final `cargo clean` si pertinent, workspace complet, tests ciblés, `cargo test --workspace`, graphes/features et replay du live PostgreSQL RawTransaction. Aucun développement fonctionnel nouveau. ### `pre.011` — Réconciliation documentaire finale README/USAGE Store/backend, plan, validation et indexes docs réellement impactés. Ne pas toucher `CHANGELOG.md`, `ROADMAP.md` ni au prompt suivant. ### `pre.012` — Préparation de publication minimale Uniquement : ```text Cargo.toml CHANGELOG.md ROADMAP.md prompts/023-V0_3_4_START_PROMPT.md deltas/0.3.3/pre.012.md ``` ### `rel.001` — Publication stable Version finale + delta uniquement. --- ## 12. Versionnement, deltas, commits et tags Respecter `docs/rules/VERSION_WORKFLOW.md`. Rappels : ```text workspace.package.version prerelease : 0.3.3-pre.N livraison : 0.3.3-pre.NNN fix runtime/code : Cargo 0.3.3-pre.N.fix.M fix doc-only : Cargo inchangé chaque delta commité tag stable final : v0.3.3 ``` Chaque delta contient : ```text base requise objectif fichiers ajoutés/modifiés/supprimés validations exécutées validations non exécutées décisions questions ouvertes ``` Une commande non exécutée n'est jamais déclarée PASS. --- ## 13. Procédure d'application et validation opérateur Après chaque 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.3 cargo check --workspace cargo clippy --workspace --all-targets ``` Tests ciblés typiques : ```bash cargo test -p ksp-store-api cargo test -p ksp-store-postgres-lib cargo test -p ksp-store-lib cargo test -p ksp-store-lib --no-default-features cargo test -p ksp-config-lib cargo check -p ksp-store-lib --no-default-features ``` Lorsque le graphe/features change ou au gate final : ```bash cargo tree -p ksp-store-lib --edges normal cargo tree -p ksp-store-lib -e features cargo tree -p ksp-store-postgres-lib --edges normal cargo tree --duplicates ``` Le gate technique final inclut : ```bash cargo test --workspace ``` Ne pas refaire systématiquement les builds Tauri : `0.3.3` n'a aucune raison d'en modifier les resources/configs desktop sauf changement réellement démontré. --- ## 14. Validation PostgreSQL réelle spécifique La release doit disposer d'un test PostgreSQL réel opt-in, sûr et non destructif sur une database dédiée. Le gate doit couvrir au minimum : ```text PostgreSQL >= 15 V000 + V001 bootstrap open Store pour un RawNetworkId explicite persist acquisition nouvelle read transaction exacte read observation exacte re-persist identique -> AlreadyPresent conflit même identité/contenu divergent -> ERROR_CODE_RAW_CONFLICT observation supplémentaire observation idempotente concurrence identical/divergent list ascending/descending slot range au moins deux pages et cursor continuation cursor hostile rejeté retention state compare-and-transition concurrent purge/tombstone normal acquisition après purge -> SkippedPurged ForceRehydrate conforme rollback d'une acquisition forcée en échec health reste Ready après opérations valides close borné cleanup uniquement des objets possédés par le test ``` Le test ne doit : ```text afficher aucune URI/credential lire aucun env depuis Store/backend DROP aucune database/schema non créée par lui utiliser aucune table RawAccountState exiger aucun endpoint Solana live ``` --- ## 15. Critères de clôture de `0.3.3` La release stable est prête seulement si : ```text V001+ migrations RawTransaction sont versionnées/checksummées schema physique conserve tous les invariants API utiles sans narrowing binding réseau empêche une réinterprétation cross-network PostgresBackend satisfait les six capabilities RawTransaction Store satisfait/dispatch les six capabilities network mismatch est rejeté avant I/O acquisition canonical+observation est atomique idempotence identical est stable conflit divergent retourne ERROR_CODE_RAW_CONFLICT observations supplémentaires sont idempotentes get transaction/observation fonctionnent list est déterministe et cursorisé aucune policy batch/backlog n'est introduite rétention compare-and-transition est atomique purge conserve le tombstone minimal normal post-purge skippe ForceRehydrate fonctionne sans écraser un conflit aucun SQL/type physique n'est exposé par la façade aucun secret/payload/SQL distant ne fuite dans erreurs/logs ksp-store-api reste backend-agnostic ou toute modification est justifiée par un gap réel RawAccountState PostgreSQL reste absent PostgreSQL live gate est vert workspace/Clippy/tests/graphes sont verts README/USAGE/plan/validation sont réconciliés prompt 0.3.4 réserve RawAccountState + complétude RAW ``` --- ## 16. Release suivante et instruction d'ouverture La release suivante envisagée est : ```text 0.3.4 — Store/PostgreSQL RawAccountState + complétude/conformance RAW ``` Elle réutilisera la même fondation `0.3.2` et les patterns physiques/concurrence validés par `0.3.3`, sans recréer une seconde architecture Store. ### Instruction d'ouverture À réception de la base stable `v0.3.2` et de l'archive historique requise : 1. vérifier la base exacte et les migrations réellement présentes ; 2. lire règles, architecture, plans/validations `0.3.1` et `0.3.2`, puis les sources des trois crates Store ; 3. auditer les six capabilities `RawTransaction` une par une ; 4. réauditer kbot3 uniquement sur son ancienne vertical slice RAW transaction/observation ; 5. figer V001, network binding, représentation u64/u32, idempotence/concurrence, cursor et rétention ; 6. produire threat model, sizing, plan `024` et validation `020` ; 7. **ne pas créer la migration métier ni le repository lourd avant validation cohérente de `pre.001`** ; 8. **ne pas ouvrir `RawAccountState`, STRUCTURAL, jobs/workers ou application d'inspection dans `0.3.3`**.