6.5 KiB
Delta 0.3.4-pre.001 — audit et physical design RawAccountState PostgreSQL
1. Objet
Ouverture de :
0.3.4 — Store/PostgreSQL RawAccountState + complétude/conformance RAW
Cette tranche reste volontairement un gate de lecture/audit/design/sizing. Aucun SQL V002, aucune table account, aucun repository account et aucune impl capability account ne sont ajoutés.
2. Base
Base canonique :
v0.3.3
workspace.package.version = 0.3.3
Le gate opérateur fourni avec la reprise est propre sur audits Rust/Markdown, checks, Clippy et suites ciblées/workspace de la release stable ; les live tests restent opt-in/ignored.
3. Version
Version workspace après overlay :
0.3.4-pre.1
Label de livraison :
0.3.4-pre.001
4. Fichiers ajoutés
docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md
docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md
deltas/0.3.4/pre.001.md
5. Fichier modifié
Cargo.toml
Modifications :
workspace.package.version : 0.3.3 -> 0.3.4-pre.1
file header version : 363 -> 364
6. Fichiers supprimés
Aucun.
7. Audit effectué
Ont été relus avant design : règles globales/KSP/Rust/dépendances/docs/versioning ; architectures Store/data/execution/workers ; plans/validations 0.3.1, 0.3.2, 0.3.3 ; source/tests Store API/façade/backend ; Config std.store ; migrations V000/V001 ; archive kbot3 ciblée account.
Inventaire confirmé :
10 capabilities RAW contractuelles
6 RawTransaction implémentées physiquement dans PostgresBackend + Store
4 RawAccount encore non implémentées et explicitement fermées par canaries 0.3.3
Checksums recalculés :
V000 = d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
V001 = 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51
8. Décisions majeures
8.1 V002
V002 sera additive, sous migrations/v002_raw_account_state/, avec seulement :
ksp_raw_account_states
ksp_raw_account_observations
V000/V001 restent byte-immutables.
8.2 Identité state
network API + (pubkey, slot, state_hash)
Le réseau est le binding DB existant. PK physique (pubkey, slot, state_hash). Pubkey/owner/hash en BYTEA fixed-width ; slot/lamports/rent_epoch en NUMERIC(20,0). Data account en BYTEA complet, vide autorisé, maximum 16 MiB.
8.3 Observation
L'observation référence le state par FK composite et conserve provenance + is_startup + transaction_signature + write_version. Ces metadata restent observation-only. Aucune FK transaction n'est ajoutée.
8.4 Atomicité/idempotence
Pattern retenu : transaction PostgreSQL, INSERT ... ON CONFLICT DO NOTHING RETURNING, puis SELECT ... FOR UPDATE et comparaison exacte sur collision. Aucun ON CONFLICT DO UPDATE, aucun has_*, aucun overwrite silencieux.
record_raw_account_observation vérifie le state préexistant et ne le crée jamais implicitement.
8.5 Pagination
Ordre total :
(slot, pubkey, state_hash)
Cursor V1 account fixe 109 bytes, magic KSPA, domaine KSP/raw-account-state-cursor/v1, digest lié au réseau, filtre pubkey, range, direction et dernière clé. Le cursor transaction KSPT est donc non rejouable.
Index métier additionnel unique :
(slot, pubkey, state_hash)
Aucun index owner/provider/time/status.
9. Audit kbot3
Classification :
- REPRENDRE : invariants unicité/FK et principe d'index account+slot ; NUMERIC pour valeurs monétaires ;
- REDESSINER : identité durable, BYTEA fixed-width, bytes complets, u64 exact, observation séparée, atomicité/conflict/cursor ;
- REPORTER : normalisation CORE, processing ledger, batch 1000, indexes owner/provider/time/status ;
- REJETER : sqlx/monolithe, BIGSERIAL comme identité publique, base64 physique, BIGINT narrowing, status/error RAW, maintenance destructive comme comportement normal.
Aucun code historique n'est copié.
10. Threat model
Le plan couvre mauvaise DB/réseau, fixed-width hostile, overflow u64, 16 MiB, observation orpheline, rollback partiel, même pubkey+slot multi-state, conflits exacts, collisions observation, races, cursor hostile/cross-query/cross-family, ordre pagination, metadata Yellowstone, fuite SQL/server text, cancellation et migration mismatch.
11. Sizing recalibré
Le forecast est étendu à pre.013 afin de séparer V002 registry/tables de ses contraintes/schema compatibility, puis acquisition write de la concurrence/observation supplémentaire. Le gate technique final reste suivi d'une lane documentaire et d'une lane publication distinctes.
12. Hors scope conservé
ksp-store-api redesign
account retention/archive/purge
STRUCTURAL/CORE/DECODED/DOMAIN persistence
Interface events
workers/jobs/backfills
batch/priorité/backlog policy
nouveaux indexes sans query
nouveaux backends/apps
13. Questions ouvertes
Aucune question de contrat bloquante après pre.001. Les numéros exacts de ressources SQL et le découpage de helpers privés sont laissés à pre.002/pre.003 sans pouvoir modifier les invariants figés.
14. Validations exécutées
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 (240 table(s), 134 file(s))
assertions structurelles locales
workspace.package.version = 0.3.4-pre.1
Cargo.toml header version = 364
plan 025 / validation 021 / delta pre.001 présents
aucun répertoire migrations/v002_raw_account_state
aucun module backend raw_account créé
15. Validations non exécutées dans le conteneur d'assemblage
L'exécutable cargo n'est pas disponible dans cet environnement. L'appel cargo fmt --all s'arrête donc immédiatement avec cargo: command not found; aucune commande Cargo post-overlay n'est déclarée PASS.
À exécuter côté opérateur :
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
Le gate opérateur de la base v0.3.3 fourni avec la reprise était intégralement vert avant cet overlay. Cet historique ne remplace pas le gate post-overlay ci-dessus.