khadhroony-solana-project/deltas/0.3.16/pre.004.md

Delta 0.3.16-pre.004 — persistance PostgreSQL V003 des variantes RAW

Base requise

0.3.16-pre.003-fix.002 appliquée
workspace.package.version = 0.3.16-pre.3.fix.2

Le gate opérateur de la base est confirmé propre : audits Rust/export/KSP/Markdown, cargo check --workspace, Clippy -D warnings, 82 tests unitaires ksp-store-postgres-lib et toutes les suites d'intégration ciblées passent. Les trois preuves PostgreSQL live restent opt-in.

Version

Cette tranche modifie le runtime PostgreSQL :

workspace.package.version = 0.3.16-pre.4

Portée

Cette tranche branche la persistance RAW existante sur les surfaces V003 créées par pre.003, sans introduire encore le comparateur backend-neutral de pre.005, la promotion canonique de pre.006 ni le dossier de conflit durable de pre.007.

Le backend PostgreSQL fournit désormais :

• un bootstrap paresseux V003 sous le verrou transactionnel de l'identité V001 ;
• une variante bootstrap variant_id = 1 représentant l'état canonique réellement disponible lorsqu'aucun selector V003 n'existe encore ;
• un selector canonique initial de revision 1 créé atomiquement avec cette variante ;
• la réutilisation d'une variante native uniquement après comparaison exacte de slot, block_time, format, version, content_hash et payload ;
• content_hash comme préfiltre de recherche, jamais comme preuve d'égalité ;
• une allocation monotone et bornée du prochain variant_id sous le verrou de l'identité ;
• le rattachement atomique de toute nouvelle observation persistée à la variante réellement reçue ;
• le rattachement des observations supplémentaires sans payload au selector canonique courant ;
• la conservation explicite des observations legacy déjà présentes mais sans mapping V003 : aucune association historique n'est fabriquée ;
• la réhydratation de la variante canonique bootstrap lorsqu'un tombstone legacy V001 est réhydraté avec preuve d'identité/hash existante.

Le cas de compatibilité étroit déjà admis en 0.3.15, ActiveIncomingTruncatedLogs, matérialise maintenant l'entrant tronqué comme variante native distincte et rattache son observation à cette variante sans modifier le canonique.

Atomicité et concurrence

L'acquisition reste une seule transaction PostgreSQL :

BEGIN
insert/collision V001
lock identité V001 FOR UPDATE
bootstrap selector/variant V003 si absent
comparaison canonique existante
réutilisation/insertion exacte de variante native si nécessaire
insertion/idempotence observation
rattachement observation -> variante
COMMIT

Le verrou de l'identité sérialise l'allocation de variant_id et empêche deux writers concurrents de créer deux variantes pour un même contenu exact.

Une preuve PostgreSQL live existante est étendue : après deux acquisitions identiques concurrentes, elle exige exactement une variante, un selector canonique, un mapping d'observation et l'égalité entre la variante mappée et le selector.

Rétention

Cette tranche ne met pas encore le ledger V003 sous une politique de rétention indépendante.

Une variante native déjà matérialisée peut donc conserver ses bytes full même si la projection V001 canonique passe ensuite archived ou purged. Ce comportement est volontaire : la rétention, les pins, les purge guards et le rollback local des variantes sont réservés à 0.3.17-pre.003.

Pour une identité legacy bootstrapée alors que V001 est déjà archived ou purged, la variante bootstrap reflète uniquement l'état réellement disponible et ne prétend pas reconstruire des bytes perdus.

Hors scope maintenu

Cette tranche n'ajoute pas :

• RawTransactionVariantRelation dans le backend PostgreSQL ;
• dominance CompatibleLessComplete / CompatibleMoreComplete générique ;
• promotion ou remplacement du selector canonique ;
• écriture dans ksp_raw_transaction_conflicts ;
• dossier de conflit durable non terminal ;
• Store retry Worker ;
• inspection/résolution Store Desk ;
• rétention propre aux variantes.

Aucune ressource SQL V003 et aucun fichier historique migration.rs / schema.rs ne sont modifiés.

Tests et canaris

Les tests unitaires ajoutés verrouillent :

• allocation variant_id monotone et bornée ;
• recherche exacte incluant le payload et ne reposant pas sur le hash seul ;
• absence de ON CONFLICT masquant une collision d'identité de variante ;
• absence de fabrication de mapping pour une observation legacy.

Le canari d'intégration v003_variant_persistence.rs verrouille :

• l'ordre lock -> bootstrap -> comparaison ;
• l'ordre observation -> mapping -> commit ;
• la comparaison exacte avant réutilisation ;
• l'absence de promotion canonique et de conflit durable avant leurs tranches dédiées.

Les trois tests PostgreSQL live existants sont alignés sur migration_version = 3 et nettoient désormais aussi les quatre tables V003.

Validation exécutée lors de la génération

Les scripts Python réels du checkout complet sont exécutés sur l'état final du delta avant archivage.

Le toolchain Rust n'est pas disponible dans l'environnement de génération ; les gates Cargo restent opérateur.

Validation opérateur demandée

cargo fmt --all
cargo fmt --all -- --check

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

cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test -p ksp-store-postgres-lib --all-targets --all-features

La preuve PostgreSQL réelle reste opt-in et peut être exécutée séparément sur une base dédiée lorsque souhaité.

Suite

Après gate propre : 0.3.16-pre.005 — comparateur partagé backend-neutral Exact | CompatibleLessComplete | CompatibleMoreComplete | Conflict | Incomparable, avec canaris logMessages bidirectionnels et politique fail-closed sur les autres champs.