khadhroony-solana-project/deltas/0.3.3/pre.001.md

Delta 0.3.3-pre.001 — audit et physical design RawTransaction PostgreSQL

1. Objet

Ouverture de :

0.3.3 — Store/PostgreSQL RawTransaction vertical slice

Cette tranche reste volontairement documentaire/conception : elle fixe l'audit, le threat model, le design physique V001 et le séquencement avant toute migration ou persistence métier.

2. Base

Base canonique :

v0.3.2

Le gate opérateur fourni pour 0.3.2 est propre : audits Rust/Markdown, workspace check, Clippy, tests Store/API/PostgreSQL foundation/Config et ksp-store-lib --no-default-features passent ; les tests live restent opt-in/ignored conformément à la fondation.

3. Version

Version workspace après overlay :

0.3.3-pre.1

Label de livraison :

0.3.3-pre.001

4. Fichiers ajoutés

docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md
docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md
deltas/0.3.3/pre.001.md

5. Fichier modifié

Cargo.toml

Modifications :

workspace.package.version : 0.3.2 -> 0.3.3-pre.1
file header version        : 347 -> 348

6. Fichiers supprimés

Aucun.

7. Audit effectué

Ont été relus avant design :

• règles générales/KSP/Rust/dépendances/docs/file contracts/version workflow/prompt structure ;
• architectures Layers/Dependencies/Store/API/Config concernées ;
• plan/validation 0.3.1 ;
• source/tests complets ksp-store-api ;
• plan/validation 0.3.2 ;
• source/tests complets ksp-store-lib et ksp-store-postgres-lib ;
• surface Config std.store ;
• archive historique kbot3 ciblée demandée par le prompt ;
• documentation PostgreSQL/tokio-postgres nécessaire aux choix numériques et de concurrence.

8. Décisions majeures

8.1 slot: u64

BIGINT est rejeté pour slot car il narrowe le domaine API. V001 utilisera :

NUMERIC(20,0)

avec conversion décimale fallible et tests jusqu'à u64::MAX.

8.2 Réseau physique

V001 introduira :

ksp_store_identity

Une base V001 est mono-réseau. Le binding est créé/validé sous le bootstrap lock afin qu'une URI pointant vers un autre réseau échoue avant exposition d'un backend prêt.

8.3 Schéma RAW minimal

Tables décidées :

ksp_store_identity
ksp_raw_transactions
ksp_raw_transaction_observations
ksp_raw_transaction_archive_payloads

Index métier additionnel unique :

(slot, signature) WHERE retention_state <> 'purged'

Aucun index provider/status/created_at/hash n'est ajouté sans requête correspondante.

8.4 Atomicité/idempotence

Le repository n'utilisera aucun has_* préalable. La stratégie est :

INSERT ... ON CONFLICT DO NOTHING RETURNING
-> si conflit : SELECT ... FOR UPDATE
-> comparaison exacte du contenu
-> AlreadyPresent ou ERROR_CODE_RAW_CONFLICT

Le canonique et son observation d'acquisition sont dans la même transaction PostgreSQL.

8.5 Pagination

Ordre total :

(slot, signature)

Cursor backend-private V1 fixe 109 octets, lié par SHA-256 au réseau, à la direction, au slot range et à la dernière clé. Aucun cap métier arbitraire n'est ajouté.

8.6 Rétention

Full, Archived et Purged sont représentables honnêtement par le backend 0.3.3 avec une relation archive séparée du hot path.

Compacted n'est pas assimilé au TOAST PostgreSQL et n'est pas simulé. Le plan 0.3.1 le qualifiait déjà d'optionnel ; aucun changement ksp-store-api n'est donc justifié. Les transitions qui l'impliquent seront rejetées avant I/O par store.postgres_retention_compaction_unsupported.

9. Audit kbot3

Classification effectuée :

• REPRENDRE : unicités, FK, keyset/index slot conceptuels ;
• REDESSINER : fixed bytes, payload opaque, u64 exact, atomicité, conflit réel, réseau, retention compare-and-transition ;
• REPORTER : indexes provider/status/time, processing/replay, batches, apps, AccountState ;
• REJETER : sqlx, has_*, JSONB canonique, narrowing i64/i32, FK SET NULL, error text SQL, caps 500/1000, processing_state RAW.

Aucun code historique n'est copié.

10. Threat model couvert

Le plan couvre explicitement :

• mauvaise URI/réseau ;
• DB bytes malformés ;
• overflow u64 ;
• observation orpheline ;
• inserts identiques/divergents concurrents ;
• collision observation ;
• cursor hostile/replay ;
• ambiguïté pagination ;
• retention race ;
• purge/read/write race ;
• ForceRehydrate race ;
• fuite SQL/server text ;
• cancellation/rollback ;
• migration mismatch.

11. Séquencement recalibré

Le forecast initial est étendu à pre.013 afin de séparer proprement :

1. généralisation du moteur de migration ;
2. V001/binding réseau ;
3. mapping/read ;
4. write/observation atomiques ;
5. pagination ;
6. rétention ;
7. façade ;
8. live PostgreSQL ;
9. hardening ;
10. gate ;
11. docs ;
12. publication.

12. Hors scope conservé

Aucun changement fonctionnel n'est apporté à :

RawAccountState
N2
workers/jobs/backfills
apps
transport
codecs wire
event bus
compression/archive worker global
autres backends

13. Validations exécutées

Audit statique de la base et de l'overlay :

python3 scripts/audit_rust_workspace_rules.py
  General Rust rule audit: clean
  Rust export completeness audit: 0 candidate(s)
  KSP workspace Rust rule audit: clean

python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.3
  Markdown table audit: clean (214 table(s), 131 file(s))

assertions structurelles locales
  workspace.package.version = 0.3.3-pre.1
  headers/version des trois nouveaux Markdown corrects
  aucune référence résiduelle au faux code API RAW_RETENTION_UNSUPPORTED

L'audit de base couvre aussi manifests/features, modules/exports, V000 et checksum, Config std.store, plans/validations 0.3.1/0.3.2, tests hardening/completeness et preuve live documentée.

14. Validations non exécutées

Le conteneur d'assemblage ne fournit pas l'exécutable cargo. Les commandes suivantes sont donc NON EXÉCUTÉES, jamais déclarées PASS :

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
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

Les tests PostgreSQL live ne sont pas exécutés non plus. pre.001 ne modifie aucun SQL/runtime métier, la preuve foundation réelle 0.3.2 est déjà acquise et le futur test RawTransaction n'existe pas encore.

15. Questions ouvertes

Aucune question de design bloquante n'est laissée ouverte par pre.001.

Les valeurs runtime retenues sont déjà fixées :

store.postgres_retention_compaction_unsupported
store.wrong_network
store.raw_reference_not_found
store.postgres_read_failed
store.postgres_write_failed
store.postgres_data_invalid
store.postgres_page_limit_unsupported

Le checksum V001 n'est pas une question de design : il sera calculé sur les bytes exacts lorsque V001__raw_transaction.sql sera créé en pre.003.

16. Gate demandé

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

Aucun test PostgreSQL live n'est requis dans cette tranche documentaire.