128 lines
6.0 KiB
Markdown
128 lines
6.0 KiB
Markdown
<!-- file: deltas/0.3.16/pre.004.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.16-pre.004` — persistance PostgreSQL V003 des variantes RAW
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
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.
|