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

Delta 0.3.16-pre.002 — contrats Store API RAW multi-variantes

Base requise

0.3.16-pre.001 appliquée
0.3.16-pre.001-fix.001 appliqué
workspace.package.version = 0.3.16-pre.1

Le gate Markdown du fix précédent a été fourni propre le 20 septembre 2026 :

Markdown table audit: clean (352 table(s), 942 file(s))

Objet

Figer les contrats backend-neutral indispensables à la persistance RAW transaction multi-variantes avant d'introduire la migration PostgreSQL V003.

Cette tranche ajoute uniquement des modèles/types Store API. Elle ne modifie encore :

• aucune migration SQL ;
• aucun backend PostgreSQL ;
• aucun RawTransactionWrite existant ;
• aucun Worker ;
• aucun comparateur de contenu logMessages ;
• aucune UI Store Desk.

Version workspace

Cargo.toml :

header version : 638 -> 639
workspace      : 0.3.16-pre.1 -> 0.3.16-pre.2

Fichiers modifiés

Cargo.toml
crates/ksp-store-api/src/lib.rs
crates/ksp-store-api/src/model/raw_outcome.rs
crates/ksp-store-api/src/model/raw_transaction.rs
crates/ksp-store-api/tests/release_completeness.rs
crates/ksp-store-api/unit_tests/model/raw_transaction.rs
docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md

Fichier ajouté

deltas/0.3.16/pre.002.md

Contrats ajoutés

Identité de variante

RawTransactionVariantId
RawTransactionVariantReference

RawTransactionVariantId est un surrogate backend-neutral strictement non nul. Il ne dérive ni de content_hash, ni du provider, ni d'une clé physique SQL.

RawTransactionVariantReference conserve explicitement :

RawTransactionReference
+
RawTransactionVariantId

Le hash reste donc un attribut de contenu et jamais l'identité métier de la variante.

Origine de variante

RawTransactionVariantOrigin::Native
RawTransactionVariantOrigin::Synthetic

Les codes persistables stables sont respectivement :

native
synthetic

Une variante synthétique est seulement un contrat réservé ; aucune fusion synthétique n'est implémentée dans cette tranche.

Relation de qualité

RawTransactionVariantRelation::Exact
RawTransactionVariantRelation::CompatibleLessComplete
RawTransactionVariantRelation::CompatibleMoreComplete
RawTransactionVariantRelation::Conflict
RawTransactionVariantRelation::Incomparable

La direction du contrat est toujours :

current canonical
vs
incoming variant

Aucune heuristique provider-majority ou source authority n'est introduite.

Reason codes

RawTransactionVariantRelationReason fige les raisons backend-neutral suivantes :

ExactCanonicalContent
IncomingLogMessagesTruncated
CanonicalLogMessagesTruncated
SlotMismatch
BlockTimeMismatch
PayloadFormatMismatch
CanonicalPayloadConflict
ContentHashCollision
UnsupportedCanonicalDifference

Chaque raison possède un code() stable destiné à la persistance et aux diagnostics sûrs.

Les reason codes ne transportent ni URL, ni provider concret, ni secret, ni payload RAW.

Couple relation/reason validé

RawTransactionVariantComparison

try_new(...) refuse les couples incohérents.

Contrats actuellement admis :

Exact                  <-> ExactCanonicalContent
CompatibleLessComplete <-> IncomingLogMessagesTruncated
CompatibleMoreComplete <-> CanonicalLogMessagesTruncated
Conflict                <-> SlotMismatch | BlockTimeMismatch | CanonicalPayloadConflict | ContentHashCollision
Incomparable            <-> PayloadFormatMismatch | UnsupportedCanonicalDifference

Cette validation ne constitue pas encore le comparateur de contenu. Le comparateur pur est prévu en 0.3.16-pre.005.

Outcome de persistance variant-aware

RawTransactionVariantWriteOutcome::InsertedCanonical
RawTransactionVariantWriteOutcome::ObservedExact
RawTransactionVariantWriteOutcome::ObservedCompatibleLessComplete
RawTransactionVariantWriteOutcome::PromotedCompatibleMoreComplete
RawTransactionVariantWriteOutcome::QuarantinedConflict
RawTransactionVariantWriteOutcome::Rehydrated
RawTransactionVariantWriteOutcome::SkippedPurged

QuarantinedConflict est explicitement un succès durable Store : une divergence conservée ne doit pas être transformée en faute Transport ou en erreur terminale Worker.

Aucune capability existante ne retourne encore ce nouvel outcome dans pre.002; son adoption backend intervient après V003.

Statut minimal du conflict case

RawTransactionConflictStatus::Open
RawTransactionConflictStatus::Resolved

Le détail des actions opérateur, revisions attendues, reopen et historique append-only reste réservé au programme 0.3.17.

Compatibilité

Les contrats historiques restent intacts :

RawTransaction
RawTransactionObservation
RawTransactionReference
RawAcquisitionWriteOutcome
RawEntityWriteOutcome
RawObservationWriteOutcome
RawTransactionWrite
RawTransactionRead

pre.002 n'impose donc aucune migration immédiate aux consumers existants.

Tous les nouveaux enums évolutifs sont #[non_exhaustive] et les exports restent disponibles uniquement depuis la racine ksp-store-api conformément aux règles KSP.

Tests/canaris ajoutés ou étendus

Les tests couvrent notamment :

variant_id = 0 rejeté
variant_id non nul conservé sans encoder content_hash
référence variante conserve le scope transaction
codes Native/Synthetic stables
couples relation/reason valides acceptés
couples incohérents rejetés
codes relation/reason/status stables
outcomes variant-aware distincts
inventaire exact des exports crate-root mis à jour
nouveaux enums evolutifs maintenus #[non_exhaustive]
absence de nouveau module production dans ksp-store-api

Validation de l'assemblage

L'environnement d'assemblage ne fournit ni cargo, ni rustc, ni rustfmt. Aucun gate Rust n'est donc déclaré PASS localement.

Ont été vérifiés localement :

inventaire exact du delta
workspace.package.version = 0.3.16-pre.2
headers file/version des fichiers modifiés
newline finale
lignes Rust <= 160 caractères
absence de lockfile/cache/secret
cohérence statique exports <-> release_completeness
cohérence du plan 038 avec les noms Rust désormais figés

Gate requis après application

Comme cette tranche modifie du Rust et le manifest workspace, exécuter :

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

Ne pas exécuter npm run build pour ce gate ; aucune application Desk n'est modifiée.

Prochaine tranche

Après gate propre :

0.3.16-pre.003

Objet prévu : migration PostgreSQL V003, registre/resources et schéma minimal variant ledger + selector + conflit, avec canaris garantissant l'immuabilité byte/checksum des migrations V000/V001/V002.