37 KiB
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 :
v0.2.14
La release à ouvrir est :
0.3.1 — Store RAW foundation
La première tranche est :
0.3.1-pre.001
Deux archives sont requises au démarrage de la session :
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é :
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 :
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 :
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 :
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 :
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 à :
D1 / RAW uniquement
Elle ne doit pas ouvrir prématurément :
D2 / CORE
D3 / DECODE
D4 / SPECIALIZED
Le résultat attendu à la clôture est un Store RAW suffisamment réel pour :
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 :
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.2et 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 :
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 :
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 :
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é :
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
Pour tout Markdown touché :
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 :
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 :
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 :
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 :
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 :
khadhroony-bot3_v0.5.3-pre.005-fix010.zip
Au minimum :
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 :
REPRENDRE
REDESSINER
REPORTER
REJETER
Classer au minimum :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
ProgramInstructionRecognition
ProgramInstructionDecodeOutcome<Decoded>
ProgramInstructionDecoder
La direction Program reste :
ksp-program-api -> Core + Interface
Store ne doit pas l'inverser ni s'y connecter en 0.3.1 :
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 :
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 :
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
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
PostgreSQL = backend officiel de référence de ksp-store-lib
Cette décision ne signifie pas :
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
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 :
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 :
.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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
src/constants.rs
pub(crate) const TRACING_TARGET: &str = "ksp-store-lib";
Ne jamais émettre :
SQL brut contenant des valeurs
bind values
DSN
credential
raw payload
11.5 API publique
Conserver les règles Rust KSP :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
concept
owner
public/private
release d'introduction
raison
Inclure au minimum :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
sqlx::PgPool
PgConnection
Transaction PostgreSQL concrete
nom physique de table
SQL brut
16.6 Security
Canaris pour :
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 :
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 :
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 :
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 :
- vérifier que la base est exactement
v0.2.14stable ; - vérifier que l'archive historique
khadhroony-bot3_v0.5.3-pre.005-fix010.zipest disponible ; - lire les règles et architectures des sections 3.1 et 3.2 ;
- inventorier l'état réel du workspace et l'absence de Store actuel ;
- auditer l'ancien
ks-store, ses contracts RAW et ses migrations ; - produire la matrice
REPRENDRE / REDESSINER / REPORTER / REJETER; - réauditer PostgreSQL et la dépendance Rust candidate avec sources primaires actuelles ;
- définir l'inventaire RAW minimal, les invariants d'idempotence/provenance et le scope exact de persistence ;
- proposer ownership, API backend-agnostic, dependency graph, schema PostgreSQL candidat, threat model et stratégie de tests live ;
- recalibrer la prévision souple et le sizing ;
- créer seulement ensuite le plan, la validation et le delta
0.3.1-pre.001; - ne pas commencer le scaffold fonctionnel lourd ni les migrations PostgreSQL avant que le gate
pre.001soit 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.