0.3.16-pre.005
This commit is contained in:
77
deltas/0.3.16/pre.005-fix.001.md
Normal file
77
deltas/0.3.16/pre.005-fix.001.md
Normal file
@@ -0,0 +1,77 @@
|
||||
<!-- file: deltas/0.3.16/pre.005-fix.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.16-pre.005-fix.001` — conformité Clippy et canari de scope `pre.005`
|
||||
|
||||
## Base requise
|
||||
|
||||
```text
|
||||
0.3.16-pre.005 appliquée
|
||||
workspace.package.version = 0.3.16-pre.5
|
||||
```
|
||||
|
||||
Le gate opérateur de `pre.005` confirme que les audits Rust/export/KSP/Markdown sont propres, que `cargo check --workspace` passe et que les suites ciblées exécutées sont fonctionnellement vertes à l'exception d'un canari PostgreSQL devenu obsolète. Clippy `-D warnings` refuse toutefois treize usages de l'opérateur `?` sous la règle workspace `clippy::question_mark_used` : dix dans le scanner JSON privé du comparateur et trois dans ses helpers de tests.
|
||||
|
||||
Le seul échec de test est `v0_3_16_pre_004_keeps_comparator_and_durable_conflict_scope_deferred`, qui interdit encore toute référence à `RawTransactionVariantRelation::` alors que `pre.005` a précisément introduit le comparateur partagé et ses relations dans le chemin PostgreSQL.
|
||||
|
||||
## Version
|
||||
|
||||
Cette correction modifie du Rust :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.16-pre.5.fix.1
|
||||
```
|
||||
|
||||
## Corrections
|
||||
|
||||
Le correctif ne modifie aucune règle métier du comparateur :
|
||||
|
||||
- les dix propagations `Option` par `?` du scanner JSON privé sont remplacées par des `match` explicites qui retournent `None` sur le même chemin d'échec ;
|
||||
- les trois usages `?` des helpers de tests Store API sont remplacés par les mêmes retours explicites ;
|
||||
- aucune autorisation locale `#[allow(clippy::question_mark_used)]` n'est ajoutée ;
|
||||
- aucune dépendance runtime n'est ajoutée à `ksp-store-api` ;
|
||||
- le canari V003 hérité de `pre.004` est mis à jour pour exiger désormais l'appel à `ksp_store_api::compare_raw_transaction_variants` et les relations `CompatibleLessComplete` / `CompatibleMoreComplete` ;
|
||||
- ce même canari continue d'interdire l'écriture dans `ksp_raw_transaction_conflicts` et toute promotion du selector canonique avant les tranches prévues.
|
||||
|
||||
## Invariants conservés
|
||||
|
||||
La sémantique de `pre.005` reste inchangée :
|
||||
|
||||
```text
|
||||
Exact -> idempotence canonique
|
||||
CompatibleLessComplete -> canonique conservé, variante entrante persistée/rattachée
|
||||
CompatibleMoreComplete -> reconnue mais fail-closed jusqu'à pre.006
|
||||
Conflict / Incomparable -> conflit existant sans conflict case durable avant pre.007
|
||||
```
|
||||
|
||||
La preuve `logMessages` reste strictement bidirectionnelle, avec marqueur exact `"Log truncated"`, unique et terminal, préfixe byte-identique et matériel supplémentaire obligatoire du côté complet.
|
||||
|
||||
Aucune migration SQL, ressource V003, promotion canonique, `canonical_revision`, journal de transition ou conflit durable n'est modifié par ce fix.
|
||||
|
||||
## 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 puis sur le ZIP rejoué sur une copie fraîche de `pre.005`.
|
||||
|
||||
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-api --all-targets --all-features
|
||||
cargo test -p ksp-store-postgres-lib --all-targets --all-features
|
||||
```
|
||||
|
||||
Les trois preuves PostgreSQL live restent opt-in.
|
||||
|
||||
## Suite
|
||||
|
||||
Après gate propre : `0.3.16-pre.006` — selector canonique, promotion atomique de `CompatibleMoreComplete`, `canonical_revision`, projection V001 cohérente et conservation de l'ancien canonique.
|
||||
173
deltas/0.3.16/pre.005.md
Normal file
173
deltas/0.3.16/pre.005.md
Normal file
@@ -0,0 +1,173 @@
|
||||
<!-- file: deltas/0.3.16/pre.005.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.16-pre.005` — comparateur backend-neutral des variantes RAW
|
||||
|
||||
## Base requise
|
||||
|
||||
```text
|
||||
0.3.16-pre.004 appliquée
|
||||
workspace.package.version = 0.3.16-pre.4
|
||||
```
|
||||
|
||||
Le gate opérateur de `pre.004` est confirmé propre : audits Rust/export/KSP/Markdown, `cargo check --workspace`, Clippy `-D warnings`, 85 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 contrat Store API et son intégration PostgreSQL :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.16-pre.5
|
||||
```
|
||||
|
||||
## Portée
|
||||
|
||||
Cette tranche rend effectif le comparateur pur backend-neutral prévu depuis `pre.002`.
|
||||
|
||||
`ksp-store-api` expose désormais :
|
||||
|
||||
```text
|
||||
compare_raw_transaction_variants(canonical, incoming)
|
||||
-> RawTransactionVariantComparison
|
||||
```
|
||||
|
||||
Le comparateur produit exclusivement les relations déjà figées :
|
||||
|
||||
```text
|
||||
Exact
|
||||
CompatibleLessComplete
|
||||
CompatibleMoreComplete
|
||||
Conflict
|
||||
Incomparable
|
||||
```
|
||||
|
||||
Le comparateur n'ajoute aucune dépendance runtime à `ksp-store-api`. En particulier, `serde_json` reste interdit par le canari de dépendances existant. L'analyse du payload RAW v1 utilise un scanner JSON privé, borné en profondeur et fondé uniquement sur `std`.
|
||||
|
||||
## Ordre de décision
|
||||
|
||||
La comparaison est fail-closed et applique l'ordre suivant :
|
||||
|
||||
1. les deux variantes doivent appartenir à la même identité `network + signature`, sinon l'appel est invalide ;
|
||||
2. `slot` différent -> `Conflict / SlotMismatch` ;
|
||||
3. `block_time` différent -> `Conflict / BlockTimeMismatch` ;
|
||||
4. format id/version différent -> `Incomparable / PayloadFormatMismatch` ;
|
||||
5. payload bytes exactement égaux -> `Exact / ExactCanonicalContent` ;
|
||||
6. hash égal mais bytes différents -> `Conflict / ContentHashCollision` ;
|
||||
7. seulement ensuite, analyse structurelle du RAW v1 pour une éventuelle preuve de troncature `logMessages` ;
|
||||
8. toute autre divergence est `Conflict` ou `Incomparable` sans dominance automatique.
|
||||
|
||||
Le `content_hash` reste donc un marqueur d'intégrité/préfiltre, jamais une preuve d'égalité.
|
||||
|
||||
## Preuve `logMessages`
|
||||
|
||||
La seule dominance automatique admise reste la troncature SVM strictement prouvée.
|
||||
|
||||
Pour reconnaître une variante tronquée, toutes les conditions suivantes sont nécessaires :
|
||||
|
||||
- les autres composantes top-level sont identiques ;
|
||||
- les autres champs `meta` sont identiques ;
|
||||
- les deux `logMessages` sont des tableaux de chaînes JSON valides ;
|
||||
- le côté tronqué contient exactement un marqueur exact `"Log truncated"` ;
|
||||
- ce marqueur est le dernier élément ;
|
||||
- le côté complet ne contient aucun marqueur exact ;
|
||||
- le préfixe avant le marqueur est byte-identique ;
|
||||
- le côté complet possède au moins une ligne au-delà de ce préfixe.
|
||||
|
||||
Ainsi :
|
||||
|
||||
```text
|
||||
canonique complet + entrant tronqué -> CompatibleLessComplete
|
||||
canonique tronqué + entrant complet -> CompatibleMoreComplete
|
||||
```
|
||||
|
||||
Une liste plus courte sans marqueur, un préfixe divergent, un marqueur non exact ou du matériel placé après `"Log truncated"` ne prouve aucune dominance.
|
||||
|
||||
## Politique fail-closed des autres champs
|
||||
|
||||
Les différences de présence/omission ou `null` contre une valeur concrète ne sont pas transformées en score de qualité. Elles produisent `Incomparable / UnsupportedCanonicalDifference`.
|
||||
|
||||
Les valeurs concrètes présentes des deux côtés mais contradictoires produisent `Conflict / CanonicalPayloadConflict`.
|
||||
|
||||
Cette politique couvre notamment les champs optionnels documentés dans le plan (`innerInstructions`, `loadedAddresses`, `returnData`, unités consommées, token balances, rewards) sans inventer de hiérarchie de complétude.
|
||||
|
||||
## Intégration PostgreSQL
|
||||
|
||||
`ksp-store-postgres-lib` ne possède plus l'heuristique privée unidirectionnelle `raw_transaction_incoming_truncated_log_messages_compatible`.
|
||||
|
||||
`compare_existing_transaction` appelle désormais directement :
|
||||
|
||||
```text
|
||||
ksp_store_api::compare_raw_transaction_variants(...)
|
||||
```
|
||||
|
||||
Comportement de cette tranche :
|
||||
|
||||
- `Exact` -> idempotence canonique existante ;
|
||||
- `CompatibleLessComplete` -> conservation du canonique et persistance/rattachement de la variante entrante comme en `pre.004` ;
|
||||
- `CompatibleMoreComplete` -> relation reconnue mais encore fail-closed côté mutation, car la promotion atomique appartient à `pre.006` ;
|
||||
- `Conflict` / `Incomparable` -> conflit PostgreSQL existant, sans ouverture de conflict case durable avant `pre.007`.
|
||||
|
||||
Aucune mise à jour du selector, de `canonical_revision` ou de la projection V001 n'est ajoutée ici.
|
||||
|
||||
## Canaris
|
||||
|
||||
Les tests Store API ajoutés verrouillent :
|
||||
|
||||
- la relation bidirectionnelle `LessComplete` / `MoreComplete` ;
|
||||
- le marqueur exact, unique et terminal ;
|
||||
- le rejet d'une simple liste plus courte ;
|
||||
- le rejet d'un préfixe divergent ;
|
||||
- le rejet d'un marqueur provider non exact ;
|
||||
- le rejet de matériel après le marqueur ;
|
||||
- la politique `Incomparable` sur optionalité `null`/valeur ;
|
||||
- le `Conflict` sur valeurs concrètes contradictoires ;
|
||||
- l'égalité par bytes même si les hashes fournis diffèrent ;
|
||||
- la détection d'une collision de hash lorsque les bytes diffèrent.
|
||||
|
||||
Les canaris PostgreSQL verrouillent en plus :
|
||||
|
||||
- l'usage exclusif du comparateur Store API pour la décision de convergence ;
|
||||
- l'absence des anciens helpers privés de compatibilité ;
|
||||
- l'absence de promotion/écriture canonique dans `pre.005` ;
|
||||
- le refus temporaire de `CompatibleMoreComplete` jusqu'à `pre.006`.
|
||||
|
||||
## Hors scope maintenu
|
||||
|
||||
Cette tranche n'ajoute pas :
|
||||
|
||||
- promotion du selector canonique ;
|
||||
- incrément de `canonical_revision` ;
|
||||
- remplacement atomique de la projection V001 ;
|
||||
- journal de transition canonique ;
|
||||
- ouverture de `ksp_raw_transaction_conflicts` ;
|
||||
- outcome Worker non terminal pour les conflits ;
|
||||
- Store Desk ;
|
||||
- retry Store/Transport ;
|
||||
- politique de rétention des variantes.
|
||||
|
||||
Aucune migration SQL ni ressource V003 n'est modifiée.
|
||||
|
||||
## 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 puis sur le ZIP rejoué sur une copie fraîche de `pre.004`.
|
||||
|
||||
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-api --all-targets --all-features
|
||||
cargo test -p ksp-store-postgres-lib --all-targets --all-features
|
||||
```
|
||||
|
||||
## Suite
|
||||
|
||||
Après gate propre : `0.3.16-pre.006` — selector canonique et promotion atomique avec revision, projection V001 cohérente, conservation de l'ancien canonique et journal minimal des transitions.
|
||||
Reference in New Issue
Block a user