v0.3.1-pre.005
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/022-V0_3_1_STORE_RAW_PLAN.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Plan `0.3.1` — Store API RAW foundation
|
||||
|
||||
@@ -803,7 +803,7 @@ La stratégie candidate est :
|
||||
```text
|
||||
capabilities Send + Sync
|
||||
méthodes object-safe
|
||||
futures boxed KSP-owned via un alias StoreFuture<'a, T>
|
||||
futures boxed KSP-owned via un alias StoreApiFuture<'a, T>
|
||||
future ksp-store-lib::Store compose les capabilities disponibles
|
||||
```
|
||||
|
||||
@@ -813,21 +813,36 @@ Cette stratégie évite une dépendance `async-trait` uniquement pour masquer la
|
||||
|
||||
Éviter un trait monolithique exigeant tous les types de données à chaque backend.
|
||||
|
||||
La candidate est une composition fine :
|
||||
`pre.005` matérialise une composition fine par famille et par direction :
|
||||
|
||||
```text
|
||||
StoreHealth
|
||||
RawTransactionRead
|
||||
RawTransactionWrite
|
||||
RawTransactionObservationRead
|
||||
RawTransactionObservationWrite
|
||||
|
||||
future RawAccountStateRead
|
||||
future RawAccountStateWrite
|
||||
future TransactionStatus* si persistence réellement retenue
|
||||
RawAccountStateRead
|
||||
RawAccountStateWrite
|
||||
RawAccountObservationRead
|
||||
RawAccountObservationWrite
|
||||
```
|
||||
|
||||
Un modèle event-only ne crée aucune capability Store par défaut.
|
||||
Les capabilities d'écriture distinguent deux usages :
|
||||
|
||||
```text
|
||||
persist_raw_*_acquisition(raw, observation)
|
||||
= création/admission atomique du RAW + observation
|
||||
|
||||
record_raw_*_observation(observation)
|
||||
= acquisition supplémentaire d'un RAW déjà persistant
|
||||
= ne retransmet pas le payload volumineux
|
||||
```
|
||||
|
||||
Les traits sont `Send + Sync`, dyn-compatible et retournent `StoreApiFuture<'a, T>`, alias KSP basé uniquement sur `Pin<Box<dyn Future + Send>>`. Un backend externe peut donc les implémenter sans `async-trait`, `tokio`, `ksp-store-lib` ou crate backend officielle.
|
||||
|
||||
`StoreHealth`, les listes/queries et les outcomes détaillés ne sont pas artificiellement introduits dans cette tranche. `pre.006` finalise les résultats d'écriture et le lifecycle logique avant fermeture de l'API.
|
||||
|
||||
Un modèle event-only ne crée aucune capability Store par défaut. Aucun trait monolithique `StoreBackend` n'est introduit : un backend peut implémenter uniquement les familles réellement supportées.
|
||||
|
||||
La future façade `ksp-store-lib::Store` peut exposer seulement les capabilities réellement compilées/supportées et produire une erreur stable lorsqu'une opération demandée n'est pas disponible.
|
||||
|
||||
@@ -835,22 +850,25 @@ La future façade `ksp-store-lib::Store` peut exposer seulement les capabilities
|
||||
|
||||
Aucun handle de transaction SQL/public n'est exposé.
|
||||
|
||||
Les invariants multi-écritures sont exprimés par des opérations logiques communes. Candidate initiale :
|
||||
La surface matérialisée par `pre.005` commence par les opérations unitaires nécessaires :
|
||||
|
||||
```text
|
||||
persist_transaction_acquisition(transaction, observation)
|
||||
record_transaction_observation(observation)
|
||||
get_raw_transaction(reference)
|
||||
list_raw_transactions(query, page)
|
||||
list_transaction_observations(query, page)
|
||||
persist_raw_transaction_acquisition(transaction, observation)
|
||||
get_raw_transaction_observation(observation_key)
|
||||
record_raw_transaction_observation(observation)
|
||||
|
||||
future persist_account_acquisition(state, observation)
|
||||
future account reads/queries
|
||||
|
||||
health()
|
||||
get_raw_account_state(reference)
|
||||
persist_raw_account_acquisition(state, observation)
|
||||
get_raw_account_observation(observation_key)
|
||||
record_raw_account_observation(observation)
|
||||
```
|
||||
|
||||
`persist_transaction_acquisition` signifie au contrat que le RAW et son observation réussissent atomiquement ou échouent ensemble. PostgreSQL réalisera cela avec une transaction privée en `0.3.2`; un autre backend utilisera son mécanisme natif.
|
||||
Les opérations `persist_raw_*_acquisition` signifient au contrat que le RAW et son observation réussissent atomiquement ou échouent ensemble. PostgreSQL réalisera cela avec une transaction privée en `0.3.2`; un autre backend utilisera son mécanisme natif.
|
||||
|
||||
Les opérations `record_raw_*_observation` supposent que la référence RAW ciblée existe déjà et permettent de retenir une acquisition supplémentaire sans retransmettre la donnée RAW complète.
|
||||
|
||||
Les listes, queries, backlog, health commun et outcomes détaillés restent à finaliser dans `pre.006`; aucune transaction backend publique n'est nécessaire pour les exprimer.
|
||||
|
||||
### 11.5 Outcomes
|
||||
|
||||
@@ -1375,7 +1393,7 @@ Audit HTTP/WS/gRPC matérialisé. `RawAccountState`/observation sont admis avec
|
||||
|
||||
### `pre.005` — Capabilities backend extensibles
|
||||
|
||||
Implémenter les contracts read/write object-safe et l'external backend canary, sans façade runtime `Store` et sans runtime DB. Un modèle prévu n'oblige pas chaque backend à implémenter sa capability.
|
||||
Matérialiser les contracts read/write object-safe pour transaction/account et leurs observations, l'alias `StoreApiFuture`, ainsi qu'un canari backend externe. Les écritures d'acquisition imposent RAW + observation atomiques et les observations supplémentaires peuvent être enregistrées sans retransmettre le RAW. Aucune façade runtime `Store`, aucun trait monolithique backend et aucun runtime DB.
|
||||
|
||||
### `pre.006` — Queries, outcomes et lifecycle RAW
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/018-V0_3_1_STORE_RAW.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Validation `0.3.1` — Store API RAW foundation
|
||||
|
||||
@@ -181,12 +181,12 @@ crate/test backend externe
|
||||
| status surfaces artificiellement fusionnées | aucun modèle commun prématuré | `pre.004` PASS |
|
||||
| duplicate same content | `AlreadyPresent` | `pre.006` |
|
||||
| duplicate divergent content | Conflict stable | `pre.006` |
|
||||
| partial transaction+observation | interdit par atomic acquisition | `pre.005` |
|
||||
| partial transaction+observation | interdit par atomic acquisition | `pre.005` PASS |
|
||||
| event-only -> Store capability | absent par défaut | `pre.004/007` |
|
||||
| Interface/Store duplicate model | absent | `pre.007` |
|
||||
| page limit 0/>500 | rejet | `pre.006` |
|
||||
| SQL/backend cursor leak | absent | `pre.006/007` |
|
||||
| external backend | implémente API sans Store lib | `pre.005` |
|
||||
| external backend | implémente API sans Store lib | `pre.005` PASS |
|
||||
| processing `bool` comme vérité | absent ; future preuve version-aware documentée | `pre.006/007` |
|
||||
| purge sans policy/evidence | impossible par contrat | `pre.006/007` |
|
||||
| tombstone supprimé avec payload | interdit | `pre.006` |
|
||||
@@ -268,6 +268,45 @@ jsonParsed/dataSlice/bare program -> non
|
||||
|
||||
La conversion source -> modèle reste hors `ksp-store-api`; la crate ne dépend toujours que de `ksp-core-lib`.
|
||||
|
||||
### 8.3 Matérialisation `pre.005`
|
||||
|
||||
La tranche ajoute uniquement des contracts de capability backend-agnostic :
|
||||
|
||||
```text
|
||||
StoreApiFuture<'a, T>
|
||||
|
||||
RawTransactionRead
|
||||
RawTransactionWrite
|
||||
RawTransactionObservationRead
|
||||
RawTransactionObservationWrite
|
||||
|
||||
RawAccountStateRead
|
||||
RawAccountStateWrite
|
||||
RawAccountObservationRead
|
||||
RawAccountObservationWrite
|
||||
```
|
||||
|
||||
Gates matérialisés :
|
||||
|
||||
```text
|
||||
traits Send + Sync et dyn-compatible
|
||||
aucune dépendance async-trait/tokio/futures-util ajoutée
|
||||
backend externe implémentable avec std + ksp-store-api seulement
|
||||
aucun trait StoreBackend monolithique
|
||||
aucune façade runtime Store
|
||||
aucun type Config/backend/SQL public
|
||||
persist_raw_transaction_acquisition = transaction + observation atomiques
|
||||
persist_raw_account_acquisition = account state + observation atomiques
|
||||
record_*_observation = acquisition supplémentaire sans retransmettre le RAW
|
||||
get_* = référence/observation key backend-independent
|
||||
write success/failure seulement en pre.005
|
||||
outcomes/idempotence/conflict détaillés réservés à pre.006
|
||||
```
|
||||
|
||||
Le canari `tests/external_backend.rs` définit un backend mémoire externe qui implémente les huit traits sans dépendre de `ksp-store-lib`, PostgreSQL ou d'un runtime async. Il prouve également que chaque capability est utilisable derrière `dyn Trait`.
|
||||
|
||||
Aucune implémentation de persistence n'est fournie par `ksp-store-api`; les futures concrètes du canari ne servent qu'à vérifier le contrat d'extension.
|
||||
|
||||
## 9. Gates de fermeture prévus
|
||||
|
||||
### Gate technique final `pre.008`
|
||||
@@ -359,7 +398,7 @@ sécurité
|
||||
| `pre.002` | scaffold + taxonomie Store API | À FAIRE |
|
||||
| `pre.003` | primitives + RawTransaction | À FAIRE |
|
||||
| `pre.004` | admission matrix + account/status models | PRÊT après gate local |
|
||||
| `pre.005` | backend contracts/capabilities | À FAIRE |
|
||||
| `pre.005` | backend contracts/capabilities | PRÊT après gate local |
|
||||
| `pre.006` | queries/outcomes/retention/tombstone | À FAIRE |
|
||||
| `pre.007` | boundary/adversarial/completeness | À FAIRE |
|
||||
| `pre.008` | gate technique final | À FAIRE |
|
||||
|
||||
Reference in New Issue
Block a user