Sasedev/khadhroony-solana-project

Fork 0

Files

SinuS Von SifriduS 66d5b03495 v0.3.3-pre.013

2026-08-30 18:03:06 +02:00

35 KiB

Raw Blame History

Prompt de démarrage `0.3.4` — Store/PostgreSQL `RawAccountState` + complétude RAW

1. Identité de la release et base exacte requise

La release à ouvrir est :

0.3.4 — Store/PostgreSQL RawAccountState + complétude/conformance RAW

La base autoritaire attendue est exclusivement la release stable :

v0.3.3
workspace.package.version = 0.3.3

L'archive/repository v0.3.3 fournie par l'opérateur prévaut sur toute mémoire, snippet, ancien artefact ou hypothèse de cette session.

La première tranche est :

0.3.4-pre.001

Elle reste obligatoirement une tranche de lecture + audit + brainstorming + threat model + design physique + sizing + planification. Ne pas créer V002, les tables account ni les repositories SQL lourds avant la sortie cohérente de ce gate.

2. Mission et résultat attendu

0.3.4 termine la couche RAW physique PostgreSQL ouverte par les trois releases précédentes :

0.3.1  contrats backend-agnostic ksp-store-api
0.3.2  façade/runtime + backend PostgreSQL foundation
0.3.3  vertical slice RawTransaction complète
0.3.4  vertical slice RawAccountState + conformance RAW cross-family finale

La release étend le couple existant :

ksp-store-lib
ksp-store-postgres-lib

avec les quatre capabilities account déjà stables dans ksp-store-api :

RawAccountStateRead
RawAccountStateWrite
RawAccountObservationRead
RawAccountObservationWrite

Le résultat attendu à la clôture est que :

PostgresBackend implémente les quatre capabilities RawAccount*
Store implémente/dispatch les quatre capabilities RawAccount*
les six capabilities RawTransaction acquises en 0.3.3 restent intactes
PostgresBackend et Store satisfont donc les dix capabilities RAW de ksp-store-api
RawAccountState est persisté sans perte de bytes ni narrowing entier
RawAccountState + observation initiale sont atomiques
une référence account déjà présente avec contenu identique est idempotente
une même référence avec contenu divergent retourne ERROR_CODE_RAW_CONFLICT
plusieurs états distincts d'un même pubkey dans un même slot restent représentables lorsque state_hash diffère
une observation supplémentaire est idempotente et ne crée jamais implicitement son state
get/list respectent RawAccountStateQuery et un ordre total déterministe
le cursor account est opaque, borné et impossible à rejouer comme cursor transaction ou contre une autre query
les optional Yellowstone metadata restent observation-only
V000/V001 restent immuables et la nouvelle persistence est additive
aucun index owner/provider/time n'est ajouté sans query réellement exposée
aucun SQL/type PostgreSQL ne fuit par ksp-store-lib
le tout est prouvé sur PostgreSQL réel avec coexistence RawTransaction + RawAccountState

Cette release ferme la complétude RAW Store/PostgreSQL, mais elle n'ouvre ni STRUCTURAL, ni Interface events, ni jobs/workers/backfill.

La release suivante reste :

0.3.5 — ksp-interface-lib : modèles passifs/events réellement partagés par les premiers consumers d'acquisition

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 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

Un fix strictement documentaire ne modifie pas workspace.package.version. Une prerelease non-fix, y compris une tranche de publication, synchronise en revanche la version Cargo conformément à VER-ID-009.

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 :

RAW -> STRUCTURAL -> DECODED -> DOMAIN
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 :

RawAccountStateReference
RawAccountState
RawAccountObservation
RawAccountStateQuery
RawPage / RawPageRequest / RawPageCursor / RawPageLimit
RawSlotRange / RawSortDirection
RawAcquisitionWriteOutcome
RawEntityWriteOutcome
RawObservationWriteOutcome
RawAcquisitionProvenance
RawObservationKey
RawContentHash
RawTransactionSignature
MAX_RAW_ACCOUNT_DATA_BYTES
les quatre capabilities RawAccount*
les six capabilities RawTransaction*

Ne pas redessiner ksp-store-api pour simplifier PostgreSQL. Une modification de l'API n'est recevable que si pre.001 démontre un gap backend-agnostic réel, bloquant et cross-backend.

3.4 Fondation runtime/backend `0.3.2`

Lire :

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/src/**
crates/ksp-store-lib/tests/**

crates/ksp-store-postgres-lib/Cargo.toml
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

3.5 Vertical slice `RawTransaction` stable `0.3.3`

Lire ensuite intégralement :

docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md
docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md

crates/ksp-store-lib/README.md
crates/ksp-store-lib/USAGE.md
crates/ksp-store-postgres-lib/README.md
crates/ksp-store-postgres-lib/USAGE.md

crates/ksp-store-lib/src/**
crates/ksp-store-lib/tests/**
crates/ksp-store-postgres-lib/src/**
crates/ksp-store-postgres-lib/unit_tests/**
crates/ksp-store-postgres-lib/tests/**
crates/ksp-store-postgres-lib/migrations/**

Les patterns acquis de 0.3.3 sont des précédents à réutiliser lorsque la sémantique account est réellement équivalente, pas une invitation à copier chaque détail transaction.

Préserver notamment :

V000/V001 checksummés et immuables
migration logique découpée en ressources typées backend-private
schema introspection Compatible/Missing/Incompatible
network binding via ksp_store_identity
u64 exact en NUMERIC(20,0) lorsque nécessaire
BYTEA fixed-width validé pour signatures/hashes/keys
transactions SQL atomiques
INSERT ... ON CONFLICT DO NOTHING puis comparaison exacte sous lock
keyset pagination sans OFFSET
cursor opaque lié à la query
PostgresBackendError = kind + phase statique/sûre
façade Store sans SQL/type physique

Lire enfin :

CHANGELOG.md
ROADMAP.md

Créer en pre.001 :

docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md
docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md

4. Audit historique kbot3 obligatoire et ciblé

L'archive historique requise est :

khadhroony-bot3_v0.5.3-pre.005-fix010.zip

Elle doit être disponible au pre.001 parce que 0.3.4 ouvre la seconde famille métier PostgreSQL et doit comparer l'ancienne persistence account/observation avant de figer V002.

Réauditer uniquement les surfaces historiques pertinentes :

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/contracts/dto/account_state.rs
ks-store/src/contracts/dto/core.rs
ks-store/src/contracts/entity/core.rs

ks-store/src/postgres/query/account_state_queries.rs
ks-store/src/postgres/repository/account_state_repository.rs

ks-store/migrations/postgres/schema/tables/create_table_if_not_exists_k_sol_obs_account_observations.sql
ks-store/migrations/postgres/schema/tables/create_table_if_not_exists_k_sol_core_account_states.sql
ks-store/migrations/postgres/schema/constraints/*account_observations*
ks-store/migrations/postgres/schema/constraints/*account_states*
ks-store/migrations/postgres/schema/indexes/*account_observations*
ks-store/migrations/postgres/schema/indexes/*account_states*

docs/guides/POSTGRES_STORAGE.md
docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md

Classer explicitement chaque idée sous :

REPRENDRE
REDESSINER
REPORTER
REJETER

Points de comparaison obligatoires :

identité account physique
pubkey/slot/hash
data bytes vs base64/text
lamports/rent_epoch exacts
owner/executable
observation identity/provenance
write_version Yellowstone
transaction_signature Yellowstone
is_startup Yellowstone
atomicité state + observation
idempotence observation
ordre/list/indexes
schema constraints
processing/normalization coupling
error mapping

Attention particulière : l'ancien k_sol_core_account_states appartient à une ancienne logique CORE/normalization, alors que le RawAccountState KSP actuel est un modèle D1 RAW complet. Ne pas traiter l'ancienne table CORE comme schéma de référence de V002.

Ne pas reprendre automatiquement :

SQLx
ancien monolithe Store
processing ledger/stage dans la persistence RAW
MAX_ACCOUNT_STATE_SELECTION_ROWS ou autre batch-size worker/job
base64 comme représentation physique obligatoire des bytes RAW
BIGINT signé pour u64
ON CONFLICT DO UPDATE silencieux
status/error_message de processing dans les observations RAW
indexes owner/provider/method/time sans query KSP correspondante
maintenance destructive publique
IDs BIGSERIAL comme identité publique

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 V002/indexes account définitifs

5. Sources externes à réauditer lorsque nécessaire

0.3.4 n'est pas une release de mise à jour de dépendances.

Avant tout changement de version/feature, vérifier la version stable réellement courante et la documentation primaire des dépendances déjà utilisées :

tokio-postgres
deadpool-postgres
tokio-postgres-rustls
rustls
sha2
PostgreSQL

Réauditer les sources PostgreSQL/tokio-postgres seulement lorsque le design l'exige, notamment pour :

NUMERIC(20,0) et conversion exacte u64
BYTEA / length constraints
transactions et row locking
INSERT ... ON CONFLICT
FK/UNIQUE/CHECK
keyset pagination composite
NULL et optional metadata
catalog introspection / pg_get_constraintdef
cancellation/rollback
statement/parameter size pour account data jusqu'à la borne KSP

Ne pas ajouter ORM, query builder, codec wire ou SDK externe par habitude.

RawAccountState::data() fournit déjà des bytes canoniques. Aucun bincode n'est autorisé et aucun codec wire n'est requis pour cette persistence.

6. État validé `0.3.3` à préserver

6.1 `ksp-store-api`

La base stable possède 10 capabilities RAW :

6 RawTransaction*
4 RawAccount*

Les quatre capabilities account existent déjà et sont object-safe ; 0.3.4 doit les implémenter, pas les réinventer.

6.2 Façade `ksp-store-lib`

La base stable possède notamment :

feature default = postgres
Store::open / runtime_snapshot / health / close
1 Store = 1 RawNetworkId + 1 backend
six capabilities RawTransaction dispatchées
validation réseau pré-I/O
mapping d'erreurs backend vers codes Store/API stables
compilation --no-default-features
aucun type PostgreSQL public

6.3 Backend `ksp-store-postgres-lib`

La base stable possède notamment :

tokio-postgres + Deadpool + Rustls
moteur migration privé
V000 bootstrap
V001 RawTransaction
ksp_store_identity mono-network
schema resource compatibility + safe additive repair
PostgresBackendError kind + phase sûre
RawTransaction read/write/observation/retention complets
cursor transaction V1 opaque
live PostgreSQL 17 vert

Checksums immuables acquis :

V000 d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
V001 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51

0.3.4 ne modifie jamais les bytes de V000/V001 pour ajouter les comptes. Toute nouvelle structure physique est additive, normalement sous une nouvelle migration logique V002 si le gate pre.001 confirme ce design.

7. Contrat `RawAccountState` à respecter exactement

7.1 Référence canonique

L'identité backend-agnostic est :

RawAccountStateReference
    network
    pubkey
    slot
    state_hash

Le commentaire API est structurant : plusieurs écritures d'un même compte peuvent exister dans le même slot lorsque les transports communs n'exposent pas write_version. Par conséquent :

même pubkey + même slot + state_hash différent
!= conflit automatique

Ce sont potentiellement deux états canoniques distincts.

En revanche :

même RawAccountStateReference + contenu complet divergent
=> ERROR_CODE_RAW_CONFLICT

Le hash ne dispense jamais de comparer exactement les champs canoniques en cas de collision.

7.2 Contenu canonique

RawAccountState contient exactement :

reference
lamports: u64
owner: Pubkey
executable: bool
rent_epoch: u64
data: complete bytes

Les bytes doivent rester complets, non jsonParsed, non sliced et non convertis en base64 comme contrat physique obligatoire.

Borne KSP :

MAX_RAW_ACCOUNT_DATA_BYTES = 16 MiB

Cette borne est une admission Store, pas une affirmation de limite protocolaire Solana.

7.3 Observation

RawAccountObservation contient :

observation_key
account reference
provenance
is_startup: Option<bool>
transaction_signature: Option<RawTransactionSignature>
write_version: Option<u64>

Les trois champs optionnels sont observation metadata. Ils ne modifient jamais l'identité canonique account.

Ne pas inventer de valeur lorsque HTTP/WS ne l'expose pas.

7.4 Query

RawAccountStateQuery expose :

network
optional pubkey
inclusive slot range
direction
page/cursor

Ne pas ajouter un index ou une query owner, provider, commitment, timestamp ou write_version si aucun contrat public ne le demande réellement.

8. Décisions déjà acquises et questions réellement ouvertes

8.1 Acquis

PostgreSQL est le backend de référence
V000/V001 sont immuables
schema additions passent par le moteur de migrations existant
Store reste mono-network
u64 ne doit jamais être narrow vers BIGINT signé
pubkey/hash/observation key/signature ont des tailles exactes connues
canonical + observation initiale doivent être atomiques
idempotence identical / conflit divergent sont obligatoires
pagination Store reste policy-free
backend/facade ne lisent pas l'environnement
aucune erreur SQL/server brute ne traverse l'API

8.2 À décider en `pre.001`

Décider explicitement :

forme et nom exacts de V002
ressources physiques exactes account state / observation
clé primaire/unique minimale
ordre total de RawAccountStateQuery
format/version du cursor account
liaison anti-replay cross-family transaction <-> account
indexes strictement nécessaires aux queries publiques
représentation PostgreSQL exacte de pubkey/hash/data/u64/optional u64
FK observation -> canonical account state
algorithme de collision canonical
algorithme d'idempotence observation
comportement concurrent identical/divergent
mapping d'erreurs account
stratégie live cross-family

Ne pas décider arbitrairement une rétention account : aucune capability RawAccountRetention* n'existe dans ksp-store-api.

Ne pas réutiliser RawTransactionRetention* pour les accounts.

9. Design physique attendu — contraintes de conception, pas schéma imposé

pre.001 doit proposer puis figer un schéma minimal capable de représenter sans perte :

RawAccountState
RawAccountObservation

Le design doit au minimum étudier :

9.1 Canonical account state

Candidats de représentation à auditer :

pubkey           BYTEA exact 32 bytes
slot             NUMERIC(20,0)
state_hash       BYTEA exact 32 bytes
lamports         NUMERIC(20,0)
owner            BYTEA exact 32 bytes
executable       BOOLEAN
rent_epoch       NUMERIC(20,0)
data             BYTEA

Ce ne sont pas des noms de colonnes imposés ; le gate doit en revanche justifier toute représentation différente.

9.2 Observation

Candidats à auditer :

observation_key        BYTEA exact 32 bytes
account reference      FK/colonnes exactes vers canonical
provenance             mêmes codes/timestamps sûrs que RawTransactionObservation
is_startup             BOOLEAN NULL
transaction_signature  BYTEA exact 64 bytes NULL
write_version          NUMERIC(20,0) NULL

9.3 Uniqueness et idempotence

Le design doit préserver :

RawAccountStateReference unique
RawObservationKey unique globalement dans la famille account au minimum
observation référence exactement un canonical existant
pas de silent overwrite

Auditer si l'unicité RawObservationKey doit rester séparée par famille physique ou si un invariant cross-family est nécessaire. Ne pas changer ksp-store-api sans raison backend-agnostic.

9.4 Indexes

Partir des queries réelles :

get by full reference
list optional pubkey + slot range + direction + cursor
get observation by observation_key

Le nombre d'indexes doit rester minimal et justifié par ces surfaces.

Les indexes kbot3 suivants ne sont pas automatiquement justifiés :

owner
provider/method
received_at
status

10. Atomicité, idempotence et concurrence

10.1 Acquisition state + observation

persist_raw_account_acquisition(state, observation) est une opération logique atomique :

canonical state durable + observation durable
ou
aucun des deux

Valider avant I/O :

network du state == network du backend
observation.account == state.reference

10.2 Collision canonical

La stratégie doit reprendre le principe validé en transaction lorsque compatible :

INSERT ... ON CONFLICT DO NOTHING RETURNING
si insert absent -> lock/read canonical existant
comparaison exacte de tous les champs
identique -> AlreadyPresent
divergent -> Conflict

Le state_hash n'est pas une preuve suffisante d'égalité des bytes et champs en cas de collision.

10.3 Observation

Pour une observation supplémentaire :

canonical absent -> ReferenceNotFound
observation key nouvelle -> Inserted
observation key existante + contenu complet identique -> AlreadyPresent
observation key existante + contenu divergent -> Conflict

Ne pas créer le canonical par effet de bord.

10.4 Concurrence

Prouver au minimum :

deux acquisitions identiques concurrentes
même référence + contenu divergent concurrent
collision observation key entre deux acquisitions
annulation après insert canonical mais avant observation
observation supplémentaire concurrente

Les outcomes exacts doivent être déterministes ou, lorsque deux winners sont possibles, l'ensemble d'outcomes attendu doit être explicitement borné.

11. Pagination et cursor account

Le list account doit définir un ordre total, stable et compatible avec :

optional pubkey filter
slot range
Ascending
Descending
continuation sans duplicate/skip

Le cursor reste backend-private et transporté uniquement via RawPageCursor.

Il doit être lié au minimum à :

family = account
network
pubkey filter présent/absent + valeur
slot range
direction
last total-order key
cursor format/version

Un cursor transaction ne doit jamais être accepté comme cursor account, et inversement.

Ne pas utiliser :

OFFSET
cursor JSON public
codec wire de ksp-interface-lib
bincode
batch-size worker caché

La limite demandée par RawPageLimit n'est pas une policy de worker. Seule une vraie borne physique PostgreSQL peut être refusée explicitement.

12. Complétude/conformance RAW cross-family

La release ne se limite pas à « ajouter deux tables ». Elle doit fermer la surface PostgreSQL RAW complète.

À la fin :

PostgresBackend implémente exactement les 10 capabilities ksp-store-api
Store implémente exactement les mêmes 10 capabilities
RawTransaction reste non régressé
RawAccountState est complet
feature postgres default reste correcte
--no-default-features reste compilable/testable
aucun backend physique ne fuite
error mapping couvre toutes les classes nécessaires aux deux familles
migrations V000/V001/V002 sont cohérentes et vérifiables
schema compatibility/hardening couvre toutes les ressources gérées

Auditer les canaris de pre.009/pre.010 de 0.3.3 : certains interdisent volontairement RawAccount* et devront être mis à jour au moment exact où le scope devient légitime, jamais supprimés globalement sans remplacement.

13. Threat model obligatoire

Couvrir au minimum :

wrong-network input avant I/O
wrong-network database URI
pubkey/hash/observation key/signature malformés dans DB
u64 overflow/narrowing slot/lamports/rent_epoch/write_version
account data > MAX_RAW_ACCOUNT_DATA_BYTES
row data corrompue
observation orphan
canonical orphan après rollback
même pubkey+slot avec hashes distincts légitimes
même full reference avec contenu divergent
identical concurrent insert
divergent concurrent insert
observation-key collision
cursor hostile
cursor replay avec autre network
cursor replay avec autre pubkey filter/range/direction
cursor transaction rejoué sur account
pagination duplicate/skip sous ordre ambigu
optional Yellowstone metadata NULL/non-NULL mal mappées
SQL/server error leak
pool cancellation pendant transaction
V002 checksum/history mismatch
schema resource missing/incompatible
V000/V001 mutation accidentelle
index excessif/non justifié

14. Première mission `pre.001`

14.1 Lecture et inventaire

Avant toute modification fonctionnelle :

vérifier que la base est bien v0.3.3 stable ;
lire toutes les sources internes listées ci-dessus ;
inventorier V000/V001 et recalculer leurs checksums ;
inventorier les 10 capabilities et confirmer que 6/10 sont déjà implémentées physiquement ;
inventorier tous les canaris qui interdisent encore RawAccount* ;
inspecter RawAccountState, RawAccountObservation et RawAccountStateQuery champ par champ ;
auditer l'archive kbot3 ciblée ;
vérifier les dépendances actuelles seulement si le design en dépend.

14.2 Matrice des quatre capabilities

Produire une matrice explicite :

capability
input
output
network guard
SQL/transaction requis
idempotence
conflit
absence/reference behavior
pagination/cursor éventuel
error mapping
live proof

14.3 Matrice modèle -> physique

Pour chaque champ account :

champ API
type Rust
cardinalité/optionality
représentation PostgreSQL
borne/constraint
mapping read
mapping write
risque de narrowing/perte

14.4 Audit historique

Classer l'héritage kbot3 sous :

REPRENDRE
REDESSINER
REPORTER
REJETER

Documenter explicitement pourquoi l'ancien CoreAccountState n'est pas le nouveau RawAccountState.

14.5 Design V002

Proposer :

migration logical version/name
resource tree tables/constraints/indexes
identité canonical
observation FK/unicity
u64 representation
byte fixed-width checks
account data representation
indexes minimaux
schema compatibility contract

Ne pas écrire les ressources SQL avant validation cohérente du design.

14.6 Cursor/order

Décider l'ordre total account et un format cursor backend-private avec anti-replay cross-family.

14.7 Concurrence

Écrire les algorithmes d'acquisition/observation et leurs états de course avant le code SQL.

14.8 Threat model

Produire la matrice décrite en section 13.

14.9 Sizing

Chaque tranche prévue au-delà d'environ 15 à 20 minutes de travail effectif doit être scindée.

Si RawAccountState + conformance RAW n'est plus clôturable dans cette session, redécouper avant V002 lourd. Ne jamais aspirer 0.3.5 dans 0.3.4.

14.10 Documents de gate

Créer :

docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md
docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md

14.11 Critères de sortie de `pre.001`

pre.001 est terminé seulement si :

base v0.3.3 vérifiée
V000/V001 immuables vérifiés
quatre capabilities account auditées
10-capability cross-family inventory établi
kbot3 account audit classé
Core historique != RawAccount actuel explicitement documenté
V002 proposé
mapping exact de tous les champs décidé
u64/bytes/optionality décidés
identity/unicity/FK décidés
atomicité/idempotence/conflit décidés
ordre total/cursor anti-replay décidé
indexes minimaux justifiés par query
error taxonomy décidée
threat model complet
stratégie live cross-family définie
plan 025 créé
validation 021 créée
prévision souple recalibrée
aucune persistence account lourde créée prématurément

15. Prévision souple initiale des prereleases

Cette prévision peut être scindée/recalibrée par pre.001.

`pre.001` — Audit contrats, kbot3, V002, cursor, concurrence et sizing

Lectures, inventaire 10 capabilities, audit account historique, design physique, threat model, plan/validation.

`pre.002` — V002 + schéma/indexes account

Ajouter uniquement les ressources physiques account réellement nécessaires via le moteur de migrations existant. V000/V001 restent byte-identiques. Tests registry/checksum/schema compatibility.

`pre.003` — Mapping physique + lectures account

Mappings rows/API privés, get_raw_account_state, get_raw_account_observation, hostile rows, wrong-network pré-I/O.

`pre.004` — Persistence account atomique + observations

persist_raw_account_acquisition et record_raw_account_observation, idempotence/conflit, exact compare, rollback et concurrence unitaire/intégration sans live externe.

`pre.005` — List/query + cursor account

RawAccountStateQuery, ordre total, optional pubkey, ranges, directions, cursor opaque/versionné et anti-replay cross-family.

`pre.006` — Façade + conformance des quatre capabilities account

Implémenter/dispatcher les quatre traits sur PostgresBackend et Store, network guard, error mapping, feature mismatch. Verrouiller la surface totale à 10 capabilities.

`pre.007` — PostgreSQL integration réelle `RawAccountState`

Gate opt-in sur database dédiée : V000+V001+V002, state+observation atomic, idempotence, conflit, observations, concurrence, pagination, cancellation/rollback et petite preuve de coexistence transaction/account.

`pre.008` — Hardening/completeness RAW cross-family

Exact modules/exports/capabilities, hostile rows/cursors, no-secret/no-SQL-leak, migration resource completeness, canaris transaction non régressés, aucun scope STRUCTURAL/Interface/job.

`pre.009` — Gate technique/live final

Workspace complet, --no-default-features, cargo test --workspace, graphes/features/duplicates, replay des preuves PostgreSQL nécessaires et vérification finale des migrations V000/V001/V002.

`pre.010` — Réconciliation documentaire finale

README/USAGE Store/backend, plan 025, validation 021, indexes docs et autres références durables réellement impactées. USAGE.md reste un guide d'utilisation durable avec exemples ; aucune preuve de gate/chronologie de prerelease n'y est ajoutée. Ne pas toucher CHANGELOG.md, ROADMAP.md ni au prompt suivant.

`pre.011` — Préparation de publication minimale

Uniquement :

Cargo.toml
CHANGELOG.md
ROADMAP.md
prompts/024-V0_3_5_START_PROMPT.md
deltas/0.3.4/pre.011.md

`rel.001` — Publication stable

Version finale + delta uniquement.

16. Versionnement, deltas, commits et tags

Respecter docs/rules/VERSION_WORKFLOW.md.

Rappels :

workspace.package.version prerelease : 0.3.4-pre.N
livraison : 0.3.4-pre.NNN
fix code/runtime/config : Cargo 0.3.4-pre.N.fix.M
fix strictement documentaire : Cargo inchangé
prerelease non-fix documentaire/publication : Cargo synchronisé
chaque delta commité
tag stable final : v0.3.4

Chaque delta contient au minimum :

base requise
objectif
fichiers ajoutés
fichiers modifiés
fichiers 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.

17. 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.4
cargo check --workspace
cargo clippy --workspace --all-targets

Tests ciblés typiques :

cargo test -p ksp-store-api
cargo test -p ksp-store-lib
cargo test -p ksp-store-postgres-lib
cargo test -p ksp-config-lib
cargo check -p ksp-store-lib --no-default-features

Lorsque la façade/account conformance change :

cargo test -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 des builds Tauri sans changement de resources/config/packaging desktop démontré.

18. Validation PostgreSQL réelle spécifique

La release doit disposer d'une preuve account opt-in sur une database PostgreSQL dédiée.

Le test doit refuser de démarrer si le jeu d'objets KSP qu'il pourrait détruire existe déjà. Il ne doit jamais afficher l'URI.

Couvrir au minimum :

PostgreSQL >= 15
bootstrap V000 + V001 + V002
health Ready
wrong network rejeté
persist state + observation
read state exact, bytes inclus
read observation exacte
re-persist identique -> AlreadyPresent
même full reference + contenu divergent -> Conflict
même pubkey + même slot + state_hash différent -> deux states distincts admis
observation supplémentaire
observation idempotente
observation-key collision divergente
optional is_startup/transaction_signature/write_version round-trip
concurrence identical/divergent
list avec/sans pubkey filter
Ascending/Descending
slot range
plusieurs pages
cursor hostile/cross-query rejeté
cursor transaction -> account rejeté
annulation/rollback sans canonical orphelin
petit canari RawTransaction après V002
close borné
cleanup uniquement des tables KSP dont l'absence initiale a été prouvée

Le test ne doit pas :

lire l'environnement depuis Store/backend
afficher URI/credentials
DROP database/schema non créé par lui
exiger endpoint Solana HTTP/WS/gRPC
introduire worker/job/processing ledger

19. Critères de clôture de `0.3.4`

La release stable est prête seulement si :

V000/V001 restent byte-identiques
V002 account est versionnée/checksummée et additive
schema physique représente RawAccountState sans perte/narrowing
PostgresBackend satisfait les 4 capabilities RawAccount
Store satisfait/dispatch les 4 capabilities RawAccount
PostgresBackend + Store satisfont les 10 capabilities RAW
RawTransaction reste intégralement vert
wrong-network est rejeté avant I/O
state+observation est atomique
identical est idempotent
divergent même full reference -> ERROR_CODE_RAW_CONFLICT
states distincts même pubkey+slot avec hash différent restent possibles
observations supplémentaires sont idempotentes
optional Yellowstone metadata round-trip exactement
get state/observation fonctionnent
list account est total/déterministe/cursorisé
cursor account est lié à sa family/query
aucun batch/backlog/policy n'est introduit
aucun index sans query réelle n'est ajouté
aucun SQL/type physique ne fuit
aucun secret/data/SQL distant ne fuite dans erreurs/logs
ksp-store-api reste backend-agnostic
aucune rétention account inventée
PostgreSQL live account/cross-family est vert
workspace/Clippy/tests/graphes sont verts
README/USAGE/plan/validation sont réconciliés selon leur rôle documentaire
prompt 0.3.5 est prêt

20. Hors périmètre explicite

Ne pas ouvrir dans 0.3.4 :

nouvelles familles RAW
RawAccount retention/tombstone non contracté
STRUCTURAL persistence
Program decode/materialization
ksp-interface-lib events de 0.3.5
ksp-job-api/backfill de 0.3.6
application backfill/inspection de 0.3.7
worker RAW live
notification bus dédié
nouveau backend SQL/NoSQL
Store Desk
wire codec
policy de batch/priorité/retry

21. Release suivante et instruction d'ouverture

La release suivante envisagée est :

0.3.5 — Interface events/acquisitions partagés si consumer réel

Instruction d'ouverture

À réception de la base stable v0.3.3 et de l'archive kbot3 requise :

vérifier la base exacte et recalculer V000/V001 ;
lire règles, architecture, plans/validations 0.3.1 à 0.3.3 ;
inventorier les 10 capabilities et confirmer que seules les quatre RawAccount* restent sans implémentation physique ;
auditer RawAccountState, RawAccountObservation et RawAccountStateQuery champ par champ ;
réauditer kbot3 uniquement sur account observation/state/indexes et séparer RAW actuel de l'ancien CORE ;
figer V002, identity/unicity/FK, u64/bytes, atomicité, cursor/order, error mapping et indexes ;
produire threat model, sizing, plan 025 et validation 021 ;
ne pas écrire V002 ni le repository account lourd avant validation cohérente de pre.001 ;
ne pas ouvrir STRUCTURAL, Interface events, jobs/workers/backfill ou application dans 0.3.4.

35 KiB Raw Blame History

Prompt de démarrage 0.3.4 — Store/PostgreSQL RawAccountState + complétude RAW