32 KiB
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 :
0.3.3 — Store/PostgreSQL RawTransaction vertical slice
La base autoritaire attendue est exclusivement la release stable :
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 :
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 :
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 :
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 :
ksp-store-lib
ksp-store-postgres-lib
avec la première vertical slice métier PostgreSQL complète de ksp-store-api :
RawTransaction
RawTransactionObservation
RawTransaction query/pagination
RawTransaction retention/tombstone/force-rehydrate
Les six capabilities ksp-store-api concernées sont :
RawTransactionRead
RawTransactionWrite
RawTransactionObservationRead
RawTransactionObservationWrite
RawTransactionRetentionRead
RawTransactionRetentionWrite
Le résultat attendu à la clôture est que :
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 à :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
CHANGELOG.md
ROADMAP.md
Créer en pre.001 :
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 :
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 :
REPRENDRE
REDESSINER
REPORTER
REJETER
L'audit doit notamment comparer :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
Pool
Client
Row
Statement
Transaction SQL
config driver
TLS internals
6.3 Migrations
La fondation stable possède :
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 à :
V001
pre.001 doit confirmer la convention exacte avant création.
6.4 Config et réseaux
std.store possède les targets :
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 :
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 :
PostgreSQL major 17
La policy de fondation supportée reste :
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 :
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
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 :
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 :
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 :
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 :
SELECT/has puis INSERT séparé sans garantie transactionnelle
Pagination/cursor
Figer :
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 :
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 :
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 :
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 :
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 :
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é
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 :
input.network == Store.network
Sinon :
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
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 :
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 :
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 :
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
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
- vérifier la base exacte et les migrations réellement présentes ;
- lire règles, architecture, plans/validations
0.3.1et0.3.2, puis les sources des trois crates Store ; - auditer les six capabilities
RawTransactionune par une ; - réauditer kbot3 uniquement sur son ancienne vertical slice RAW transaction/observation ;
- figer V001, network binding, représentation u64/u32, idempotence/concurrence, cursor et rétention ;
- produire threat model, sizing, plan
024et validation020; - ne pas créer la migration métier ni le repository lourd avant validation cohérente de
pre.001; - ne pas ouvrir
RawAccountState, STRUCTURAL, jobs/workers ou application d'inspection dans0.3.3.