khadhroony-solana-project/deltas/0.3.4/pre.002.md

Delta 0.3.4-pre.002 — registry V002 et tables RAW account minimales

1. Base requise

Base directe attendue :

0.3.4-pre.001-fix.001
workspace.package.version = 0.3.4-pre.1

Le gate opérateur fourni pour pre.001 est propre : audits Rust/Markdown, cargo check --workspace, Clippy, tests ciblés Store/Config et cargo check -p ksp-store-lib --no-default-features passent. pre.001-fix.001 est ensuite un correctif strictement documentaire ; ses audits statiques sont propres et il ne modifie pas Cargo/runtime.

2. Objectif

Matérialiser uniquement la première fondation physique V002 décidée en pre.001 :

migration logique V002 = raw_account_state
2 tables
2 primary keys
1 foreign key observation -> state

Cette tranche n'ouvre aucun repository account, aucun dispatch Store, aucun index métier et aucune contrainte de domaine/fixed-width complète.

3. Version Cargo

Cette prerelease modifie code et migration SQL. Conformément à VER-ID-009 :

workspace.package.version : 0.3.4-pre.1 -> 0.3.4-pre.2
Cargo.toml header          : 364 -> 365

4. Registry V002

EMBEDDED_MIGRATIONS contient désormais exactement trois migrations logiques ordonnées :

V000 bootstrap
V001 raw_transaction
V002 raw_account_state

V002 utilise MigrationChecksum::Resources, MigrationHook::None et V002_RESOURCES. current_migration_version() passe de 1 à 2.

Les checksums acquis restent inchangés :

V000 d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
V001 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51

Le checksum calculé sur les cinq resources V002 de cette tranche est :

30ac87496f1bb3805d816660891d7eab2127c599a636eb40c17ade5926311f55

Il est volontairement provisoire de prerelease : pre.003 doit encore ajouter les contraintes de domaine et l'index prévus, traiter explicitement la transition depuis cet état intermédiaire puis figer le checksum V002 final avant toute preuve live account persistante.

5. Ressources physiques ajoutées

migrations/v002_raw_account_state/
  tables/
    001_ksp_raw_account_states.sql
    002_ksp_raw_account_observations.sql
  constraints/
    001_pk_ksp_raw_account_states.sql
    002_pk_ksp_raw_account_observations.sql
    003_fk_ksp_raw_account_observations_state.sql

5.1 State

Colonnes matérialisées exactement selon le design pre.001 :

pubkey       BYTEA         NOT NULL
slot         NUMERIC(20,0) NOT NULL
state_hash   BYTEA         NOT NULL
lamports     NUMERIC(20,0) NOT NULL
owner        BYTEA         NOT NULL
executable   BOOLEAN       NOT NULL
rent_epoch   NUMERIC(20,0) NOT NULL
data         BYTEA         NOT NULL

PK :

(pubkey, slot, state_hash)

5.2 Observation

Les champs de provenance existants sont conservés avec les optionalités account décidées, dont :

is_startup            BOOLEAN NULL
transaction_signature BYTEA NULL
write_version          NUMERIC(20,0) NULL

PK : (observation_key).

FK :

(account_pubkey, account_slot, account_state_hash)
    -> ksp_raw_account_states(pubkey, slot, state_hash)
    ON DELETE RESTRICT

Aucune FK vers ksp_raw_transactions n'est ajoutée.

6. Scope explicitement non avancé

aucun CHECK fixed-width/u64/data/provenance account
aucun index (slot,pubkey,state_hash)
aucun index owner/provider/time/status
aucun src/raw_account.rs
aucun repository/read/write account
aucune impl RawAccount* sur PostgresBackend
aucune impl RawAccount* sur Store
aucune modification ksp-store-api
aucune retention/archive/purge account

Les contraintes et l'index sont réservés à pre.003 ; le mapping/read commence seulement à pre.004.

7. Tests/canaris ajustés

Les tests historiques qui interdisaient l'existence même de V002 sont recalibrés sans ouvrir les capabilities account :

• registry V000/V001/V002 exact et current_migration_version = 2 ;
• inventaire V002 exact 2 tables + 3 contraintes PK/FK ;
• absence de CHECK/index dans V002 pre.002 ;
• absence de module repository account et d'impl RawAccount* runtime ;
• live tests transaction/foundation existants attendent désormais migration version 2 s'ils sont exécutés.

Les canaris qui interdisent les quatre implémentations RawAccount* restent actifs.

8. Fichiers ajoutés

crates/ksp-store-postgres-lib/migrations/v002_raw_account_state/tables/001_ksp_raw_account_states.sql
crates/ksp-store-postgres-lib/migrations/v002_raw_account_state/tables/002_ksp_raw_account_observations.sql
crates/ksp-store-postgres-lib/migrations/v002_raw_account_state/constraints/001_pk_ksp_raw_account_states.sql
crates/ksp-store-postgres-lib/migrations/v002_raw_account_state/constraints/002_pk_ksp_raw_account_observations.sql
crates/ksp-store-postgres-lib/migrations/v002_raw_account_state/constraints/003_fk_ksp_raw_account_observations_state.sql
deltas/0.3.4/pre.002.md

9. Fichiers modifiés

Cargo.toml
crates/ksp-store-postgres-lib/src/lib.rs
crates/ksp-store-postgres-lib/src/migration.rs
crates/ksp-store-postgres-lib/src/schema.rs
crates/ksp-store-postgres-lib/unit_tests/migration.rs
crates/ksp-store-postgres-lib/unit_tests/schema.rs
crates/ksp-store-postgres-lib/tests/dependency_boundary.rs
crates/ksp-store-postgres-lib/tests/hardening_completeness.rs
crates/ksp-store-postgres-lib/tests/postgres_foundation_live.rs
crates/ksp-store-postgres-lib/tests/postgres_raw_transaction_live.rs
docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md
docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md

10. Fichiers supprimés

Aucun.

11. Validations exécutées dans l'environnement d'assemblage

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.4
  Markdown table audit: clean (239 table(s), 136 file(s))

assertions structurelles locales
  DIFF_SCOPE=PASS
  HEADER_VERSIONS=PASS
  V000_V001_IMMUTABLE=PASS
  V002_MINIMAL_SCOPE=PASS
  V002_CHECKSUM=30ac87496f1bb3805d816660891d7eab2127c599a636eb40c17ade5926311f55

Le checksum V002 intermédiaire a été recalculé indépendamment à partir du domaine ksp-migration-resources-v1\0, des IDs ordonnés et des bytes exacts des cinq resources.

12. Validations non exécutées dans l'environnement d'assemblage

L'exécutable cargo n'est pas disponible dans cet environnement. Après application du delta, rejouer côté opérateur :

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
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 live PostgreSQL account n'est revendiqué dans pre.002.

13. Décisions prises

• V002 reste additive et ne modifie aucun byte V000/V001.
• Les PK/FK sont des resources séparées et inspectables par le moteur existant.
• La table state porte directement les bytes D1 RAW ; aucune représentation base64 physique n'est introduite.
• transaction_signature reste metadata d'observation sans FK transaction.
• La tranche ne crée pas de deuxième vérité space, de surrogate ID, d'archive account ni de processing ledger.

14. Questions ouvertes

Aucune question de contrat nouvelle. pre.003 doit finaliser la surface physique V002 déjà décidée : contraintes de domaine/fixed-width, index de navigation, compatibilité schema et checksum final, y compris la transition depuis l'état intermédiaire de cette prerelease.