# Prompt de démarrage `0.3.1` — Store RAW foundation ## 1. Identité de la release et bases exactes requises La base KSP attendue est **exclusivement** la release stable : ```text v0.2.14 ``` La release à ouvrir est : ```text 0.3.1 — Store RAW foundation ``` La première tranche est : ```text 0.3.1-pre.001 ``` Deux archives sont requises au démarrage de la session : ```text 1. archive opérateur correspondant exactement à KSP v0.2.14 2. archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip ``` Ordre d'autorité : ```text v0.2.14 réelle / archive opérateur autorité KSP actuelle règles + architecture de v0.2.14 autorité normative et architecturale khadhroony-bot3 historique source d'audit/héritage uniquement sources PostgreSQL/crates actuelles autorité externe sur le comportement présent anciens prompts / snippets / mémoire auxiliaires seulement ``` L'archive kbot3 **est obligatoire pour le gate `pre.001`**. Elle contient un ancien `ks-store`, des migrations PostgreSQL, une configuration Store et une architecture de persistence suffisamment riches pour éviter de réinventer sans audit les problèmes déjà rencontrés. Elle n'est toutefois jamais une base de code ni une autorité architecturale : l'ancien Store couvre RAW, CORE, DECODE, materialization et processing ledger, alors que `0.3.1` doit rester strictement **RAW-only**. Si l'archive historique n'est pas disponible : ```text ne pas inventer son contenu depuis la mémoire ne pas déclarer l'audit d'héritage terminé ne pas commencer le schéma PostgreSQL fonctionnel ``` Ne pas ouvrir `0.3.1` depuis : ```text 0.2.14-pre.* 0.2.14-pre.*-fix.* 0.2.14-rel.* non encore validé stable une archive de travail intermédiaire l'ancien dépôt khadhroony-bot3 comme base de code un souvenir de session ``` À l'ouverture, vérifier au minimum : ```text tag Git v0.2.14 si metadata Git disponible workspace.package.version = 0.2.14 deltas/0.2.14/rel.001.md présent prompts/020-V0_3_1_START_PROMPT.md présent ksp-program-api présent et conforme à la surface stable 0.2.14 ksp-store-api absent sauf contradiction de la base réelle ksp-store-lib absent sauf contradiction de la base réelle 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 réelle gagne et la divergence devient une sortie explicite de `pre.001`. `pre.001` est obligatoirement une tranche **lecture + audit KSP + audit kbot3 + audit PostgreSQL/dependencies + définition RAW + dependency graph + API/backend model + threat model + stratégie migrations/tests + sizing + planification**. Aucun schéma PostgreSQL définitif, repository fonctionnel lourd, migration active ni API Store publique définitive ne doit être figé avant la sortie cohérente de ce gate. --- ## 2. Mission et résultat attendu La mission de `0.3.1` est d'introduire le premier Store KSP durable sous la séparation : ```text ksp-store-api = contrats backend-agnostic de persistence ksp-store-lib = implémentation PostgreSQL officielle de référence ``` La release est volontairement limitée à : ```text D1 / RAW uniquement ``` Elle ne doit pas ouvrir prématurément : ```text D2 / CORE D3 / DECODE D4 / SPECIALIZED ``` Le résultat attendu à la clôture est un Store RAW suffisamment réel pour : ```text représenter un input d'acquisition persistant et replayable pour les catégories retenues préserver provenance et identité d'idempotence nécessaires écrire/lire ces faits via une API backend-agnostic fournir PostgreSQL comme backend officiel de référence prouver l'atomicité/idempotence attendue sur un PostgreSQL réel permettre à un backend externe de satisfaire le contrat public sans dépendre de ksp-store-lib ``` La release ne doit pas confondre : ```text modèle Transport != modèle RAW persistent Store API != PostgreSQL API payload replayable != décodage Program notification de disponibilité != source de vérité du backlog migration SQL != API publique Config != Store ``` La question centrale de `0.3.1` est : > quel est le plus petit contrat RAW backend-agnostic qui conserve assez fidèlement l'acquisition couverte pour permettre un replay ultérieur sans redemander la donnée au provider, tout en restant indépendant des modèles Transport, des wires génériques futurs de `0.3.2` et des couches CORE/DECODE/SPECIALIZED ? Le gate `pre.001` peut réduire le nombre de catégories RAW initiales si le scope complet ne tient pas dans une session. Une réduction doit être fonctionnelle et explicitement documentée ; elle ne doit pas être masquée derrière un type « fourre-tout » non justifié. --- ## 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 : ```text KSP-API-001..007 KSP-CONFIG-001..018 KSP-NOTIFY-001..006 KSP-STORE-001..002 KSP-DATA-001..004 KSP-PIPE-001..007 DEP-KSP-001..005 DEP-CARGO-001..007 DEP-LOG-001..012 DEP-STORE-001..008 DEP-TRANSPORT-001..005 DEP-PIPE-001..008 DEP-WORKER-001..003 DEP-JOB-001..003 ``` Rappels directement structurants : ```text ksp-store-api ne dépend pas de ksp-store-lib ksp-store-api ne dépend pas de Program / Materializer / Transport ksp-store-lib dépend de ksp-store-api et contient PostgreSQL de référence ksp-store-lib ne dépend pas des implémentations Transport / Program / Materializer les conversions Transport -> RAW appartiennent à la composition/pipeline futur aucun ksp-data-api global les notifications ne sont qu'un wake-up, jamais le backlog persistence/commit précèdent toute notification ``` Pour tout Rust modifié : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Pour tout Markdown touché : ```bash python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1 ``` Une commande non exécutée n'est jamais déclarée PASS. ### 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/006-WIRE_AND_PROGRAM.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 ``` Les références centrales de `0.3.1` sont : ```text docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md docs/architecture/005-DEPENDENCY_GRAPH.md docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md ``` Préserver notamment : ```text RAW -> CORE -> DECODE -> SPECIALIZED RAW et CORE indépendants du décodage Program Store persiste des contrats ; il ne possède ni transport, ni decoder, ni materializer ksp-store-api backend-agnostic ksp-store-lib PostgreSQL officiel première Store release RAW-only Transport -X-> Store ``` ### 3.3 État de release précédent à relire Lire : ```text docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md docs/validation/017-V0_2_14_PROGRAM_API.md crates/ksp-program-api/README.md crates/ksp-program-api/USAGE.md CHANGELOG.md ROADMAP.md ``` But : préserver les frontières acquises. L'existence de `ksp-program-api` ne justifie aucune dépendance Store -> Program en `0.3.1`. --- ## 4. Audit historique kbot3 obligatoire ### 4.1 Archive Auditer : ```text khadhroony-bot3_v0.5.3-pre.005-fix010.zip ``` Au minimum : ```text ks-store/Cargo.toml ks-store/README.md ks-store/USAGE.md ks-store/TODO.md ks-store/src/lib.rs ks-store/src/store.rs ks-store/src/contracts/** ks-store/src/postgres/** ks-store/migrations/postgres/** config/store.config.json config/schemas/store.config.schema.json ks-config/src/store.rs docs/architecture/STORAGE_ARCHITECTURE.md docs/guides/POSTGRES_STORAGE.md docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md ``` ### 4.2 Concepts historiques à classifier Produire une matrice : ```text REPRENDRE REDESSINER REPORTER REJETER ``` Classer au minimum : ```text séparation façade Store / PostgreSQL StoreOpenOptions / backend selection health/readiness contracts/dto/raw.rs contracts/entity/raw.rs RawTransactionStore repository traits pagination replay contracts error contracts schema validation / migration bootstrap migrations atomiques constraints/indexes idempotence / uniqueness raw transaction table acquisition observations processing ledger CORE tables DECODE coverage/events materialization journal maintenance truncate/drop Config Store runtime diagnostics ``` ### 4.3 Contraintes d'héritage Ne pas copier tel quel : ```text le monolithe ks-store N1/N2/N3 les 16 tables historiques les 240 ressources SQL historiques les noms physiques k_sol_* historiques les contrats CORE/decode/materialization les processing ledgers appartenant à des couches non ouvertes les DTO JSON génériques uniquement parce qu'ils existaient les surfaces Config historiques les dépendances historiques ou leurs versions ``` L'audit doit distinguer : ```text concept toujours valide forme historique devenue trop large contrat qui appartient à 0.3.2+ contrat incompatible avec les règles KSP actuelles ``` --- ## 5. Sources externes à réauditer au début de `pre.001` La release introduit un backend PostgreSQL réel et probablement une nouvelle dépendance Rust de database access. La fraîcheur est donc obligatoire. Consulter en priorité des sources primaires actuelles : ```text PostgreSQL documentation officielle crate/repository/documentation officielle du candidat PostgreSQL Rust retenu Cargo/crates.io pour la version stable réellement courante ``` Le candidat historique principal est `sqlx`, mais `pre.001` doit vérifier sa pertinence actuelle avant de l'ajouter. Auditer au minimum : ```text version stable actuelle MSRV/rust edition compatibility runtime TLS/features nécessaires PostgreSQL feature set migration support transactions query parameter binding pool settings statement/query timeout possibilités error surfaces compile-time/offline requirements éventuels features transitives et doublons Cargo ``` Ne pas conserver dans le prompt ou le manifeste une version historique de `sqlx` simplement parce que kbot3 l'utilisait. Si une alternative à `sqlx` est proposée, comparer explicitement sa valeur pour KSP avant décision. PostgreSQL doit également être réaudité sur les types réellement retenus : ```text BIGINT / integer bounds BYTEA si payload binaire retenu TIMESTAMPTZ / timestamp semantics JSONB uniquement si un besoin réel le justifie unique constraints / ON CONFLICT transaction isolation nécessaire indexes/pagination choisis ``` Ne pas inventer une dépendance ou un type SQL avant que le contrat RAW soit défini. --- ## 6. État stable `v0.2.14` à préserver La base acquise contient notamment : ```text ksp-core-lib ksp-logging-lib ksp-config-lib ksp-interface-lib ksp-program-api ksp-onchain-transport-lib ksp-offchain-transport-lib ksp-wallet-lib applications desktop existantes ``` Program API stable : ```text ProgramInstructionRecognition ProgramInstructionDecodeOutcome ProgramInstructionDecoder ``` La direction Program reste : ```text ksp-program-api -> Core + Interface ``` Store ne doit pas l'inverser ni s'y connecter en `0.3.1` : ```text ksp-store-api -X-> ksp-program-api ksp-store-lib -X-> ksp-program-api ``` Transport conserve ses modèles homogènes et sa responsabilité réseau : ```text ksp-onchain-transport-lib -X-> ksp-store-api ksp-onchain-transport-lib -X-> ksp-store-lib ``` La conversion future doit rester explicite dans une composition/pipeline : ```text transport model -> conversion RAW explicite -> ksp-store-api contract -> backend injecté ``` --- ## 7. Décisions acquises avant `pre.001` Les décisions suivantes ne sont pas à redébattre sans contradiction de la base réelle : ### 7.1 Nommage et split ```text ksp-store-api ksp-store-lib ``` `ksp-store-api` est une exception volontaire au suffixe `-lib` : c'est une API publique de backend extensible. ### 7.2 Backend officiel ```text PostgreSQL = backend officiel de référence de ksp-store-lib ``` Cette décision ne signifie pas : ```text PostgreSQL types dans ksp-store-api sqlx types dans ksp-store-api noms physiques de tables dans l'API publique ``` ### 7.3 Première couche ```text 0.3.1 = RAW seulement ``` Les contrats D2/D3/D4 sont explicitement interdits dans cette release. ### 7.4 Backend-agnostic Un consumer logique doit pouvoir dépendre de `ksp-store-api` sans dépendre de `ksp-store-lib`. Une implémentation externe de l'API doit être techniquement possible lorsque le contrat retenu le justifie. ### 7.5 Notifications `ksp-store-api` est l'owner retenu du format canonique de notification/référence quand elle signifie qu'une donnée persistée est disponible. Mais : ```text le mécanisme concret de diffusion est hors scope une notification ne remplace jamais une query/backlog Store publication seulement après commit ``` `pre.001` doit décider si le type de référence RAW minimal est assez stabilisé pour introduire ce format maintenant ou s'il doit être reporté tout en conservant l'ownership. ### 7.6 Configuration `ksp-store-lib` ne lit pas lui-même : ```text .env KSP_* / KSPB_* fichier Config ``` `ksp-config-lib` reste seul owner de ces sources. Aucun document `std.store` n'est exigé par `0.3.1` tant qu'aucun lifecycle host n'en a besoin. --- ## 8. Questions réellement ouvertes pour `pre.001` Ne pas décider par intuition avant audit : ### 8.1 Inventaire RAW initial Déterminer quelles catégories RAW sont nécessaires dans `0.3.1`. Candidats à examiner : ```text transaction acquisition account observation block/slot acquisition generic envelope par catégorie ``` Le scope doit être assez utile pour préparer `0.3.3` backfill, mais assez petit pour être clôturé dans une session. ### 8.2 Forme du payload replayable Décider comment conserver une acquisition suffisamment fidèle sans : ```text dépendre de Transport faire de Store un owner de wire Solana inventer un JSON universel introduire un codec wire concurrent à ksp-interface-lib ``` Si des bytes opaques sont retenus, documenter clairement qui possède leur encodage et comment un futur replay sait les interpréter. Si un JSON/JSONB est retenu pour une catégorie précise, justifier son statut et ne pas en faire un contrat universel par commodité. ### 8.3 Identité/idempotence Définir pour chaque catégorie retenue : ```text clé logique hash/idempotence key comportement duplicate replacement éventuel origine/provider duplication éventuelle ``` Ne pas promettre exactly-once distribué. ### 8.4 Provenance Déterminer les champs publics réellement nécessaires parmi : ```text cluster/network provider transport/protocol source/endpoint identity sûre acquisition role live/backfill/import observed_at persisted_at slot/signature/pubkey selon catégorie cursor/page/range/checkpoint si pertinent ``` Ne jamais stocker ou exposer un secret d'endpoint/credential dans une provenance publique. ### 8.5 API async/backend extensible Décider la forme des contracts `ksp-store-api` : ```text traits par capability/repository façade globale ou composition de traits futures/async trait strategy Send/Sync requirements object safety seulement si un vrai consumer dyn l'exige transaction abstraction éventuelle pagination/cursors health/readiness ``` Ne pas ajouter `async-trait`, boxing ou registry backend uniquement pour anticiper un usage non démontré. ### 8.6 Frontière `ksp-store-api` / `ksp-store-lib` Décider quels types appartiennent à API et lesquels restent privés à PostgreSQL : ```text RAW DTOs persistent references write outcomes query filters page cursors health state backend open/settings migration state pool/transaction handles SQL error mapping ``` ### 8.7 Migrations Décider : ```text layout migrations bootstrap/upgrade policy strict validation d'un schéma existant additive-only éventuel rollback policy maintenance scripts ou non version de schema ``` Ne pas reprendre automatiquement le système « une instruction SQL par fichier » de kbot3 sans justification KSP actuelle. ### 8.8 Test PostgreSQL réel Définir un gate reproductible sur un PostgreSQL réel sans transférer l'ownership Config/env vers Store. Préférer une stratégie opérateur explicite et sûre : ```text DSN fourni uniquement au test live/integration aucun secret imprimé aucun DSN dans Debug/Error base/schema de test isolé cleanup borné ``` Le mécanisme exact doit être choisi en `pre.001`. --- ## 9. Objectifs et livrables Sous réserve du sizing `pre.001`, la release doit viser : ### 9.1 `ksp-store-api` Minimum attendu : ```text crate *-api déclarative contrats RAW backend-agnostic retenus capabilities read/write nécessaires outcomes/errors via Core aucun type PostgreSQL/sqlx public façade crate-root explicite external backend canary ``` Dépendance cible maximale par défaut : ```text ksp-store-api └── ksp-core-lib ``` Toute dépendance supplémentaire doit être justifiée par un type réellement nécessaire. Ne pas ajouter `ksp-interface-lib` par symétrie ; `0.3.2` doit rester propriétaire des wires génériques futurs. ### 9.2 `ksp-store-lib` Minimum attendu : ```text implémentation PostgreSQL officielle settings/open contract programmatique pool/connection private migrations/schema RAW seulement write/read RAW idempotence/atomicité pagination/query bornée si retenue health/readiness safe logging KSP si comportement runtime réel ``` Graphe cible : ```text ksp-store-lib ├── ksp-store-api ├── ksp-core-lib ├── ksp-logging-lib └── PostgreSQL dependency candidate retenue ``` `ksp-store-lib` ne doit pas dépendre de : ```text ksp-onchain-transport-lib ksp-program-api ksp-program-lib ksp-materializer-api ksp-materializer-lib ksp-wallet-lib ksp-config-lib Tauri ``` ### 9.3 Documentation Créer lors de `pre.001` : ```text docs/plans/022-V0_3_1_STORE_RAW_PLAN.md docs/validation/018-V0_3_1_STORE_RAW.md ``` Puis documenter les crates au moment de leur scaffold : ```text crates/ksp-store-api/README.md crates/ksp-store-api/USAGE.md crates/ksp-store-lib/README.md crates/ksp-store-lib/USAGE.md ``` Les index durables sont réconciliés dans la lane documentaire finale, pas au fil de chaque tranche sans besoin. --- ## 10. Hors périmètre strict `0.3.1` n'introduit pas : ```text D2 CORE persistence RAW -> CORE normalizer CORE replay job D3 decode/materialization journal D4 specialized projections ksp-materializer-api / lib ksp-program-lib Program account/event/return-data decoding ksp-job-api ksp-job-backfill ksp-worker-api ksp-worker-raw-retriever ksp-pipeline-raw-ingestion-lib sans réutilisation démontrée application backfill/inspection nouveau Tauri Desk transport/provider selection HTTP/WS/gRPC acquisition Config std.store par anticipation notification transport concret scheduler orchestrateur execution/policy/wallet integration ``` Également hors scope : ```text schéma PostgreSQL N2/N3/N4 processing ledger DECODE coverage declarations materialization outputs DEX/token/metadata tables analytics/OHLC ``` `0.3.2` reste propriétaire de l'extension `ksp-interface-lib` avec les wires génériques nécessaires aux acquisitions et à la future normalisation CORE. `0.3.3` reste propriétaire de `ksp-job-api` + premier backfill concret. `0.3.4` reste propriétaire de l'application backfill/inspection RAW. --- ## 11. Contraintes sécurité/API/architecture spécifiques ### 11.1 Secrets PostgreSQL DSN, user, password, TLS material et options sensibles : ```text jamais dans Debug jamais dans Display public jamais dans ErrorContext arbitraire jamais dans logs jamais dans snapshots publics ``` Les erreurs d'une dépendance PostgreSQL ne deviennent `source` de `ksp_core_lib::Error` qu'après audit de leur chaîne Debug/source conformément à `RUST-ERR-007`. ### 11.2 SQL Règles minimales : ```text bind parameters pour valeurs runtime aucune concaténation SQL avec input non fiable noms physiques de tables privés à ksp-store-lib transactions explicites pour invariants multi-opérations queries/pagination bornées ``` ### 11.3 Payloads RAW Tout payload potentiellement hostile doit être borné avant copie/allocation non bornée quand la frontière API le permet. `Debug` et erreurs ne doivent pas afficher le payload brut. Les tailles exactes ne sont pas inventées : `pre.001` les dérive des catégories réellement retenues et des limites Transport/wire existantes. ### 11.4 Observabilité `ksp-store-api` purement déclaratif n'ajoute pas Logging. `ksp-store-lib`, en tant que runtime comportemental, utilise `ksp-logging-lib` si instrumentation nécessaire et possède : ```text src/constants.rs pub(crate) const TRACING_TARGET: &str = "ksp-store-lib"; ``` Ne jamais émettre : ```text SQL brut contenant des valeurs bind values DSN credential raw payload ``` ### 11.5 API publique Conserver les règles Rust KSP : ```text aucun pub mod réexports explicites crate-root pas de use non-trait pas de type sqlx dans la façade publique pas de chemin de module interne comme API pas de default method masquant une policy critique sans justification ``` ### 11.6 Codecs `bincode` reste interdit pour les codecs wire KSP. Store ne crée pas un second owner de wire officiel : ```text wire officiel -> ksp-interface-lib persistence RAW -> ksp-store-api / ksp-store-lib ``` Un format de persistence interne éventuellement binaire ne doit pas être présenté comme un nouveau wire Solana public ni introduit sans besoin réel. ### 11.7 Idempotence La release doit prouver un comportement déterministe sur duplicate/retry. Ne pas promettre : ```text exactly-once distribué ordre global total non possédé par la source lossless pour une catégorie non couverte ``` ### 11.8 Extensibilité backend Si `ksp-store-api` définit un backend contract : ```text une crate externe doit pouvoir l'implémenter sans dépendre de ksp-store-lib sans connaître PostgreSQL sans accéder à un module privé ``` Un canari d'intégration externe doit le prouver. --- ## 12. Première mission `0.3.1-pre.001` ### 12.1 Vérifier la base réelle Inventorier : ```text workspace members workspace dependencies surface Core surface Interface surface Program API Transport models publics réellement disponibles absence actuelle de Store ROADMAP 0.3.x ``` Ne pas supposer qu'un type cité dans un ancien prompt existe encore. ### 12.2 Relire règles et architecture Produire une checklist courte des règles qui conditionnent directement le design Store. ### 12.3 Auditer kbot3 Produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` définie en section 4. Le rapport doit au minimum expliquer pourquoi les surfaces N2/N3 historiques ne rentrent pas dans `0.3.1`. ### 12.4 Auditer PostgreSQL et la crate Rust candidate Vérifier version/features actuelles et documenter : ```text candidate retenu ou non features minimales runtime requirements migration strategy support pool/transaction API error safety transitive duplicates ``` ### 12.5 Définir l'inventaire RAW minimal Pour chaque catégorie proposée : ```text source acquisition identité logique payload replayable provenance idempotence queries nécessaires reason to include now reason not to defer ``` Si le nombre de catégories dépasse le budget de session, réduire avant scaffold. ### 12.6 Définir l'ownership Produire une table : ```text concept owner public/private release d'introduction raison ``` Inclure au minimum : ```text RAW DTO persistent reference write request/outcome query filter/page health backend settings pool transaction migration notification reference transport conversion ``` ### 12.7 Proposer le dependency graph exact Cible initiale à confirmer : ```text ksp-store-api └── ksp-core-lib ksp-store-lib ├── ksp-store-api ├── ksp-core-lib ├── ksp-logging-lib └── PostgreSQL dependency ``` Justifier toute divergence. ### 12.8 Proposer l'API candidate Donner les signatures candidates essentielles sans les implémenter lourdement. Répondre explicitement : ```text traits séparés ou façade unique ? async strategy ? dyn/object safety réellement requise ? external backend implementation ? transaction abstraction publique ou backend privée ? page cursor opaque ou struct typée ? ``` ### 12.9 Proposer le schéma PostgreSQL candidat Sans l'appliquer encore, fournir : ```text tables RAW seulement colonnes PK/unique keys FK seulement si justifiées dans RAW indexes nécessaires nullability bounds/check constraints migration versioning ``` Chaque table doit correspondre à un contrat RAW réellement retenu. ### 12.10 Threat model Couvrir au minimum : ```text DSN leak SQL injection hostile payload size duplicate/retry race partial transaction schema drift migration against incompatible existing object cursor abuse unbounded query raw payload error/debug leak backend error leak cross-backend contract mismatch ``` ### 12.11 Stratégie de tests Prévoir : ```text unit tests module-local public API canaries external backend canary manifest/dependency firewall schema/migration inventory canary PostgreSQL integration tests idempotence/race tests transaction rollback test payload/error redaction tests pagination bounds release completeness ``` Les tests PostgreSQL réels peuvent être `#[ignore]`/opt-in pendant le développement si l'environnement n'est pas toujours disponible, mais un gate PostgreSQL réel doit être planifié avant la réconciliation documentaire finale. ### 12.12 Sizing et prévision recalibrée Chaque tranche intermédiaire vise environ 15–20 minutes de travail effectif. Si une tranche dépasse ce budget ou si `0.3.1` ne paraît plus clôturable dans une seule session : ```text scinder avant implémentation lourde mettre à jour le plan conserver les lanes de fermeture séparées ``` ### 12.13 Sorties documentaires de `pre.001` Créer uniquement ce qui est nécessaire au gate : ```text Cargo.toml bump prerelease si exigé par le delta 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 ``` Ne pas créer les crates fonctionnelles avant que le gate soit cohérent si le plan décide que le scaffold appartient à `pre.002`. ### Critères de sortie de `pre.001` Le gate est cohérent seulement si : ```text base stable v0.2.14 auditée archive kbot3 auditée matrice historique produite versions/dependencies PostgreSQL actuelles auditées inventaire RAW minimal décidé hors-scope CORE/DECODE/SPECIALIZED explicite ownership API/impl/composition fixé API candidate assez précise pour scaffold schema candidat RAW-only assez précis pour revue migration policy candidate documentée threat model présent stratégie PostgreSQL live présente dependency graph exact proposé prévision souple recalibrée release encore clôturable dans une session ``` Aucun repository PostgreSQL lourd ne commence avant cette sortie. --- ## 13. Prévision souple initiale des prereleases Cette prévision est **indicative**. `pre.001` doit la recalibrer selon l'inventaire RAW et l'audit PostgreSQL réel. ### `pre.001` — Audit KSP + kbot3 + RAW model + PostgreSQL + sizing Lecture, matrice historique, ownership, dépendances, API candidate, schema candidat, threat model, stratégie de tests, plan/validation. ### `pre.002` — Scaffold `ksp-store-api` + `ksp-store-lib` + dependency firewall Créer les deux crates, manifests minimaux, façades crate-root et documentation initiale sans schéma fonctionnel lourd. ### `pre.003` — Contrats RAW backend-agnostic Introduire uniquement les types RAW/provenance/références/outcomes réellement retenus par `pre.001`, avec bounds et Debug sûrs. ### `pre.004` — Capabilities Store API + backend externe canari Matérialiser read/write/query contracts nécessaires et prouver qu'un backend externe peut les implémenter sans `ksp-store-lib`. ### `pre.005` — PostgreSQL runtime foundation Settings programmatique, ouverture/pool, error mapping, health minimal, logging KSP et migration runner choisi, sans dépasser RAW. ### `pre.006` — Schéma/migrations PostgreSQL RAW Créer uniquement les tables/constraints/indexes validés par le plan. Aucun objet CORE/DECODE/SPECIALIZED. ### `pre.007` — Persistence RAW write/idempotence/atomicité Implémenter les writes, duplicate/retry semantics et rollback/transaction invariants. ### `pre.008` — Reads/query/pagination + référence de notification si retenue Implémenter les lectures nécessaires, bornes/cursors et uniquement le contrat de notification dont le besoin est démontré. ### `pre.009` — Adversarial/security/release completeness Payload hostile, redaction DSN/error, query bounds, schema drift, duplicate race, dependency/API inventory, absence de scope creep. ### `pre.010` — Gate technique PostgreSQL final Exécuter un PostgreSQL réel sur migrations + write/read/idempotence/rollback et les graphes Cargo finaux. Aucun développement fonctionnel nouveau. ### `pre.011` — Réconciliation documentaire finale README/USAGE, plan, validation, architecture/indexes réellement concernés. Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant. ### `pre.012` — Préparation de publication minimale Uniquement : ```text Cargo.toml CHANGELOG.md ROADMAP.md prompt de démarrage 0.3.2 delta pre.012 ``` ### `rel.001` — Publication stable Mécanique de publication uniquement. Si l'audit réduit ou augmente le nombre de tranches, préserver l'ordre relatif : ```text gate technique PostgreSQL -> réconciliation documentaire -> préparation de publication -> rel.001 ``` --- ## 14. Versionnement, deltas, commits et tags Respecter `docs/rules/VERSION_WORKFLOW.md`. Exemples : ```text livraison pre.001 0.3.1-pre.001 Cargo 0.3.1-pre.1 delta deltas/0.3.1/pre.001.md livraison fix 0.3.1-pre.003-fix.001 Cargo si runtime 0.3.1-pre.3.fix.1 publication 0.3.1-rel.001 Cargo stable 0.3.1 tag stable v0.3.1 ``` À partir de `0.1.x`, chaque delta est commité selon le workflow KSP. Une archive overlay contient seulement : ```text fichiers ajoutés/modifiés de la livraison + delta correspondant ``` Aucune suppression n'est implicite. Le `ROADMAP.md` ne sert pas de changelog de prerelease. Les détails vivent dans le plan/validation/deltas. --- ## 15. Procédure opérateur et validation ### 15.1 Gate standard Rust/Markdown Pour toute prerelease Rust : ```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 ``` Puis tests ciblés de la tranche. ### 15.2 Gate workspace À chaque tranche technique suffisamment complète : ```bash cargo test -p ksp-store-api cargo test -p ksp-store-lib cargo test --workspace ``` ### 15.3 Graphes Quand les manifests Store existent ou changent : ```bash cargo tree -p ksp-store-api --edges normal cargo tree -p ksp-store-lib --edges normal cargo tree --duplicates ``` Le graphe `ksp-store-api` doit rester backend-agnostic. ### 15.4 PostgreSQL live/integration Avant fermeture technique, exécuter le gate PostgreSQL réel défini par `pre.001`. Il doit prouver au minimum pour la surface retenue : ```text bootstrap/migrations sur base propre réouverture sur schema déjà valide write read idempotent duplicate/retry transaction rollback sur échec query/page bounds aucun secret dans diagnostic visible ``` Si un test volontairement destructive/schema-management existe, il doit cibler exclusivement un namespace/base de test explicitement provisionné. Aucun test ne doit toucher une base opérateur non dédiée par défaut. --- ## 16. Canaris obligatoires ### 16.1 API publique Store Un test d'intégration doit consommer la façade crate-root uniquement. ### 16.2 External backend Une implémentation de test séparée doit satisfaire les contracts publics retenus sans dépendre de `ksp-store-lib` ni de PostgreSQL. ### 16.3 Dependency firewall Verrouiller au minimum : ```text ksp-store-api -X-> ksp-store-lib ksp-store-api -X-> Transport/Program/Materializer ksp-store-lib -X-> Transport/Program/Materializer/Wallet/Config/Tauri ``` ### 16.4 RAW-only completeness Le release completeness doit détecter l'apparition accidentelle de : ```text CoreTransaction DecodedEvent MaterializationOutput SpecializedProjection Program decoder worker/job lifecycle transport client ``` ou tout équivalent qui ouvrirait D2/D3/D4. ### 16.5 PostgreSQL privacy Aucun type public de `ksp-store-api` ne doit exposer : ```text sqlx::PgPool PgConnection Transaction PostgreSQL concrete nom physique de table SQL brut ``` ### 16.6 Security Canaris pour : ```text DSN redaction payload hostile Debug/Error oversize input unbounded page size SQL value binding schema incompatibility partial write rollback concurrent duplicate ``` ### 16.7 Notification Si la référence/notification RAW est introduite : ```text format indépendant de live/backfill/import payload compact aucune donnée source du backlog dupliquée inutilement publication testée seulement après commit ``` Le mécanisme de diffusion reste absent. --- ## 17. Critères de clôture de `0.3.1` La release peut être publiée seulement si : ```text ksp-store-api existe et reste backend-agnostic ksp-store-lib existe avec PostgreSQL de référence surface durable limitée à RAW inventaire RAW décidé et documenté persistence replayable pour les catégories couvertes idempotence/duplicate semantics explicites migrations RAW-only validées aucun type PostgreSQL dans Store API backend externe canari PASS public API canari PASS dependency firewall PASS security/adversarial PASS PostgreSQL integration gate PASS cargo test -p ksp-store-api PASS cargo test -p ksp-store-lib PASS cargo test --workspace PASS graphes Cargo inspectés aucun CORE/DECODE/SPECIALIZED anticipé aucun Transport/Program/Materializer dependency creep aucune lecture Config/env directe dans Store aucun secret/payload brut dans logs/errors/debug documentation durable réconciliée CHANGELOG/ROADMAP/prompt 0.3.2 préparés dans la dernière prerelease dédiée ``` Une catégorie RAW explicitement reportée par `pre.001` n'est pas un échec si le scope réduit reste cohérent avec `0.3.3` et si le report est tracé. Un gate PostgreSQL réel manquant est en revanche bloquant pour déclarer le backend officiel validé. --- ## 18. Release/session suivante envisagée Après `0.3.1`, la séquence active prévoit : ```text 0.3.2 — étendre ksp-interface-lib avec les wires génériques nécessaires aux acquisitions et à la future normalisation CORE 0.3.3 — introduire ksp-job-api + premier backfill historique concret vers RAW 0.3.4 — introduire une application spécialisée de backfill/inspection RAW ``` Puis la couche RAW doit être complétée avec le worker/service live et les outils d'exploitation réellement nécessaires avant d'ouvrir CORE. `0.3.1` ne doit pas aspirer ces releases pour rendre Store artificiellement « complet ». Le prompt suivant préparé en fin de release sera donc consacré à `0.3.2`, sauf décision de roadmap explicitement modifiée avant la clôture. --- ## 19. Instruction d'ouverture À l'ouverture de la session `0.3.1` : 1. vérifier que la base est exactement `v0.2.14` stable ; 2. vérifier que l'archive historique `khadhroony-bot3_v0.5.3-pre.005-fix010.zip` est disponible ; 3. lire les règles et architectures des sections 3.1 et 3.2 ; 4. inventorier l'état réel du workspace et l'absence de Store actuel ; 5. auditer l'ancien `ks-store`, ses contracts RAW et ses migrations ; 6. produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` ; 7. réauditer PostgreSQL et la dépendance Rust candidate avec sources primaires actuelles ; 8. définir l'inventaire RAW minimal, les invariants d'idempotence/provenance et le scope exact de persistence ; 9. proposer ownership, API backend-agnostic, dependency graph, schema PostgreSQL candidat, threat model et stratégie de tests live ; 10. recalibrer la prévision souple et le sizing ; 11. créer seulement ensuite le plan, la validation et le delta `0.3.1-pre.001` ; 12. **ne pas commencer le scaffold fonctionnel lourd ni les migrations PostgreSQL avant que le gate `pre.001` soit cohérent**. Le premier message de travail doit commencer par l'audit de la base réelle, des règles et de l'archive historique, pas par un schéma SQL ou une API inventés depuis la mémoire.