v0.3.6-pre.012
This commit is contained in:
File diff suppressed because one or more lines are too long
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Couches et dépendances KSP
|
||||
|
||||
@@ -27,7 +27,7 @@ Les niveaux architecturaux N1–N4 décrivent les familles de composants du proj
|
||||
|
||||
- `ksp-store-api` / `ksp-store-lib` ;
|
||||
- `ksp-materializer-api` / implementations lorsque DECODE s'ouvre ;
|
||||
- `ksp-job-api` et jobs ;
|
||||
- `ksp-job-api`, `ksp-job-backfill-lib` puis les jobs concrets introduits par les couches ;
|
||||
- `ksp-worker-api` et workers ;
|
||||
- processors/pipelines spécialisés réellement réutilisés.
|
||||
|
||||
@@ -138,11 +138,11 @@ Des applications spécialisées sont ajoutées au fur et à mesure pour valider
|
||||
|
||||
## Workers et jobs
|
||||
|
||||
Un worker est un service continu/autonome ; un job est borné/terminable.
|
||||
Un worker est un service continu/autonome ; un job est borné/terminable. `ksp-job-api` porte le lifecycle commun et l'observation latest-value sans runtime concret. Le premier job, `ksp-job-backfill-lib`, fournit un runtime single-run historique vers RAW ; il compose Transport et Store sans devenir worker ni service permanent.
|
||||
|
||||
Ils utilisent des APIs lifecycle distinctes et ne s'appellent pas entre eux pour transférer les payloads du data plane.
|
||||
Workers et jobs utilisent des APIs lifecycle distinctes et ne s'appellent pas entre eux pour transférer les payloads du data plane. Un checkpoint de job peut être caller-owned sans devenir automatiquement une persistence de control plane.
|
||||
|
||||
Le Store reste le point durable de synchronisation entre couches de processing.
|
||||
Le Store reste le point durable de synchronisation des données entre couches de processing ; les snapshots Job décrivent l'état opérationnel du job et ne remplacent pas les données RAW persistées.
|
||||
|
||||
## Firewall des dépendances externes
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 12 -->
|
||||
<!-- version: 13 -->
|
||||
|
||||
# Contrats initiaux des composants KSP
|
||||
|
||||
@@ -180,13 +180,13 @@ Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program réels,
|
||||
|
||||
## Jobs
|
||||
|
||||
`ksp-job-api` est la lifecycle API des travaux déclenchés/terminables.
|
||||
`ksp-job-api` est l'API passive et runtime-neutral des travaux bornés/terminables. Elle possède `JobId`, `JobKindCode`, le lifecycle `Created/Running/Cancelling/Completed/Cancelled/Failed`, l'intention d'annulation coopérative et le contrat latest-value `JobNotification` / `JobSnapshotSource`. Sa dépendance normale reste exclusivement `ksp-core-lib`.
|
||||
|
||||
Le premier job retenu est le backfill RAW.
|
||||
Le premier job concret est `ksp-job-backfill-lib`. Il couvre un backfill historique `RawTransaction` : quatre scopes bornés, découverte/hydratation Transport observée, conversion RAW v1, persistance atomique par `ksp-store-lib`, concurrence bornée, frontier/checkpoint contigus caller-owned, annulation coopérative et snapshots complets sûrs. Il ne dépend ni de Config, ni d'un backend Store concret, ni d'un Worker.
|
||||
|
||||
Les jobs de replay suivent ensuite les frontières durables ouvertes : RAW -> CORE, CORE -> DECODE, DECODE -> SPECIALIZED.
|
||||
Les jobs de replay suivants pourront suivre les frontières durables ouvertes : RAW -> CORE, CORE -> DECODE, DECODE -> SPECIALIZED. Ils ne sont pas forcés d'adopter le contrat métier du backfill RAW ; seuls les contrats vraiment communs appartiennent à `ksp-job-api`.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue sans duplication concrète.
|
||||
Aucune `ksp-job-control-lib` n'est créée sans duplication concrète.
|
||||
|
||||
## Scenarios
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 28 -->
|
||||
<!-- version: 31 -->
|
||||
|
||||
# Inventaire initial des composants KSP
|
||||
|
||||
@@ -10,6 +10,7 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
|
||||
## Statuts
|
||||
|
||||
- `Stable` — implémenté et publié ;
|
||||
- `Implémenté` — présent et techniquement validé, en attente de publication stable ;
|
||||
- `Retenu` — composant/contrat décidé ;
|
||||
- `Pressenti` — direction décidée mais périmètre exact à confirmer ;
|
||||
- `À la demande` — créé seulement au premier besoin réel ;
|
||||
@@ -36,11 +37,11 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
|
||||
| Program API | `ksp-program-api` | API | Stable | `0.2.14` | contrats extensibles Program |
|
||||
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
|
||||
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |
|
||||
| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | RAW transaction/account, observations, queries, outcomes, rétention et capabilities backend |
|
||||
| Store runtime | `ksp-store-lib` | lib | Retenu | `0.3.2`–`0.3.4` | fondation puis conformance RAW par slices, dispatch features/config |
|
||||
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Retenu | `0.3.2`–`0.3.4` | fondation, RawTransaction puis RawAccountState/complétude |
|
||||
| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.6` | lifecycle des jobs terminables |
|
||||
| Backfill | `ksp-job-backfill-lib` | lib | Retenu | `0.3.6` | Job borné : découverte/hydratation historique vers RAW via Transport + `ksp-store-lib` |
|
||||
| Store API | `ksp-store-api` | API | Stable | `0.3.1` | RAW transaction/account, observations, queries, outcomes, rétention et capabilities backend |
|
||||
| Store runtime | `ksp-store-lib` | lib | Stable | `0.3.2`–`0.3.4` | façade backend-neutral et conformance RAW 10/10 |
|
||||
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4` | backend référence : fondation, RawTransaction et RawAccountState |
|
||||
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
|
||||
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6` | backfill `RawTransaction` borné via Transport observé + Store, checkpoint et runtime |
|
||||
| Backfill Desk | nom à fixer | app | Retenu | `0.3.7` | contrôle/inspection du backfill RAW |
|
||||
| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus |
|
||||
| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW |
|
||||
@@ -149,9 +150,8 @@ Market Desk est progressive : V1 après les DEX prioritaires, puis enrichissemen
|
||||
|
||||
## Questions restantes
|
||||
|
||||
- noms exacts de Price Desk et Backfill Desk ;
|
||||
- surface exacte Yellowstone après audit normatif de `0.2.9-pre.001` ;
|
||||
- nom exact de Backfill Desk ;
|
||||
- nécessité future d'un pool automatique WS ;
|
||||
- types exacts `ksp-program-api`/`ksp-materializer-api`/`ksp-store-api` ;
|
||||
- types exacts `ksp-materializer-api` lors de l'ouverture DECODE ;
|
||||
- nom/packaging précis du premier RAW worker et du CORE normalizer ;
|
||||
- granularité des workers DECODE/SPECIALIZED par groupe.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
|
||||
<!-- version: 19 -->
|
||||
<!-- version: 20 -->
|
||||
|
||||
# Graphe de dépendances KSP
|
||||
|
||||
@@ -375,10 +375,14 @@ ksp-job-backfill-lib
|
||||
-> ksp-core-lib
|
||||
-> ksp-logging-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-lib # façade backend-neutral ; dépendance sans feature backend imposée
|
||||
-> ksp-store-lib # default-features = false ; aucun backend imposé
|
||||
-> futures-util / tokio # runtime privé du job, jamais dans ksp-job-api
|
||||
-> serde_json / sha2 # canonicalisation RAW v1 et digest
|
||||
```
|
||||
|
||||
Il remplit RAW et ne décode aucun programme. Il ne dépend pas de Config : l'application supérieure construit explicitement Transport, Store et la requête Job. Le réseau appartient au scope/à l'identité durable ; rôle, provider, endpoint et protocole restent des choix ou provenances d'acquisition et ne deviennent jamais une clé de transaction.
|
||||
Il remplit RAW et ne décode aucun programme. Il ne dépend pas de Config : la composition supérieure construit explicitement Transport, Store et `BackfillRequest`. Le réseau appartient au scope/à l'identité durable `(network, signature)` ; rôle, provider, endpoint et protocole restent des choix ou provenances d'acquisition et ne deviennent jamais une clé de transaction.
|
||||
|
||||
`ksp-job-api` ne dépend en retour d'aucun runtime ou domaine concret. `ksp-job-backfill-lib` ne dépend ni directement de `ksp-store-api`, ni de `ksp-store-postgres-lib`; la façade Store demeure l'unique frontière runtime de persistance.
|
||||
|
||||
## Workers
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
|
||||
<!-- version: 9 -->
|
||||
<!-- version: 10 -->
|
||||
|
||||
# Acquisition, workers, jobs et pipelines spécialisés
|
||||
|
||||
@@ -78,12 +78,17 @@ D1 RAW
|
||||
|
||||
Le job :
|
||||
|
||||
- utilise `ksp-job-api` pour son lifecycle ;
|
||||
- gère scope/range/pagination/checkpoint ;
|
||||
- porte explicitement le réseau logique du Store dans le scope et dans l'identité de chaque transaction candidate ;
|
||||
- traite rôle HTTP, provider, endpoint et protocole comme sélection/provenance d'acquisition, jamais comme identité transactionnelle ;
|
||||
- n'effectue aucun décodage Program ;
|
||||
- n'écrit pas directement des faits CORE/DECODE/SPECIALIZED.
|
||||
- utilise `ksp-job-api` pour identité, lifecycle, annulation abstraite et observation latest-value ;
|
||||
- expose `LatestAddress`, `BeforeAddress`, `AfterAddress` et `ExplicitSignatures` avec bornes explicites de pages/candidats/concurrence ;
|
||||
- porte explicitement le réseau logique du Store dans le scope et dans l'identité `(network, signature)` de chaque transaction candidate ;
|
||||
- exclut rôle HTTP, provider, endpoint et protocole du fingerprint sémantique et de l'identité transactionnelle ;
|
||||
- hydrate uniquement via la voie observée `getTransaction`, afin de conserver la provenance du provider/endpoint réellement gagnant ;
|
||||
- produit un RAW v1 canonique déterministe puis persiste transaction + observation atomiquement via `ksp-store-lib` en mode normal ;
|
||||
- respecte les tombstones `Purged`, distingue missing/conflit/idempotence et ne pré-lit pas le Store avant hydratation ;
|
||||
- limite les hydrations concurrentes, avance seulement une frontier contiguë durable et retourne un checkpoint opaque caller-owned ;
|
||||
- arrête coopérativement les nouvelles admissions lors d'une annulation et draine une persistence Store déjà soumise ;
|
||||
- publie des snapshots latest-value sûrs sans payload RAW ni secrets/URLs Transport ;
|
||||
- n'effectue aucun décodage Program et n'écrit aucun fait CORE/DECODE/SPECIALIZED.
|
||||
|
||||
### Worker RAW live
|
||||
|
||||
@@ -240,31 +245,27 @@ Une capability comme `reconfigure` n'est pas imposée à tous les workers.
|
||||
|
||||
## Job API
|
||||
|
||||
`ksp-job-api` reste distinct de Worker API.
|
||||
`ksp-job-api` reste distinct de Worker API et volontairement runtime-neutral.
|
||||
|
||||
Concepts candidats :
|
||||
Contrats communs actuels :
|
||||
|
||||
```text
|
||||
JobId
|
||||
JobDescriptor
|
||||
JobKindCode
|
||||
JobState
|
||||
JobProgress
|
||||
JobOutcome
|
||||
JobCapabilities
|
||||
JobCompletion
|
||||
JobLifecycle
|
||||
JobCancellationToken
|
||||
JobNotificationSequence
|
||||
JobNotification<Snapshot>
|
||||
JobSnapshotSource
|
||||
```
|
||||
|
||||
Un job est borné/terminable et peut exposer selon besoin :
|
||||
Le lifecycle commun est borné aux transitions explicitement validées entre `Created`, `Running`, `Cancelling` et les états terminaux `Completed(Complete|Partial)`, `Cancelled`, `Failed`. Il ne définit ni `pause`, ni `resume`, ni scheduler, ni runtime d'exécution générique.
|
||||
|
||||
```text
|
||||
start
|
||||
pause
|
||||
resume
|
||||
cancel
|
||||
status
|
||||
progress
|
||||
```
|
||||
`JobSnapshotSource` suit une sémantique latest-value : un listener lit une valeur complète courante puis peut attendre une séquence plus récente ; les valeurs intermédiaires peuvent être coalescées. Le snapshot métier reste possédé par le job concret.
|
||||
|
||||
Les types exacts sont décidés à `0.3.6` avec le premier vrai backfill, après clôture des trois slices Store/PostgreSQL `0.3.2`–`0.3.4` et de la tranche Interface `0.3.5`.
|
||||
L'annulation commune est une intention coopérative. Le job concret décide quelles attentes peuvent être interrompues et quelles opérations engagées doivent être drainées.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est créée sans duplication concrète.
|
||||
|
||||
@@ -309,15 +310,11 @@ Les états exacts seront définis avec le premier processor durable, mais doiven
|
||||
|
||||
## Reprise après crash
|
||||
|
||||
Un worker/job doit reconstruire son état depuis :
|
||||
Un worker/job qui promet une reprise après crash doit reconstruire son état depuis des données durables : inputs persistés, claims/leases/outcomes lorsqu'ils existent, cursors/checkpoints et versions de processor.
|
||||
|
||||
- inputs persistés ;
|
||||
- claims/leases ;
|
||||
- outcomes ;
|
||||
- cursors/checkpoints ;
|
||||
- versions de processor.
|
||||
Le premier backfill RAW retourne un `BackfillCheckpoint` caller-owned lié au `JobId` et au fingerprint de scope. La crate ne persiste pas ce checkpoint elle-même : tant qu'un caller ne l'enregistre pas durablement, il s'agit d'une primitive de reprise contrôlée, pas d'une promesse crash-safe automatique.
|
||||
|
||||
La mémoire du processus ne constitue jamais l'unique source de reprise.
|
||||
La mémoire du processus ne constitue jamais l'unique source d'une garantie de reprise durable.
|
||||
|
||||
## Logging
|
||||
|
||||
@@ -346,7 +343,9 @@ ksp-job-backfill-lib
|
||||
-> ksp-core-lib
|
||||
-> ksp-logging-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-lib # façade Store ; aucun backend imposé par la crate Job
|
||||
-> ksp-store-lib # façade Store ; default-features=false côté Job
|
||||
-> futures-util/tokio # runtime privé de Backfill
|
||||
-> serde_json/sha2 # RAW v1 canonique + digest
|
||||
```
|
||||
|
||||
### RAW worker
|
||||
@@ -393,8 +392,7 @@ selon les capacités réellement introduites.
|
||||
|
||||
- nom final de la crate pipeline RAW si la réutilisation justifie une crate dédiée ;
|
||||
- nom final du worker RAW ;
|
||||
- contrat exact de `ksp-job-api` ;
|
||||
- modèle de claim/lease PostgreSQL ;
|
||||
- modèle de claim/lease PostgreSQL pour les futurs processors continus ;
|
||||
- taille de batch et stratégie backpressure ;
|
||||
- découpage des workers DECODE/SPECIALIZED par groupe lorsque les premiers groupes existent ;
|
||||
- mécanisme IPC des applications de contrôle futures.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Applications, services, scenarios et control plane
|
||||
|
||||
@@ -356,15 +356,13 @@ Le choix du mécanisme exact est reporté à la release fonctionnelle concernée
|
||||
|
||||
## Jobs
|
||||
|
||||
Les jobs restent distincts des workers.
|
||||
Les jobs restent distincts des workers. `ksp-job-api` fournit les contrats runtime-neutral communs ; le premier job concret `ksp-job-backfill-lib` est une bibliothèque single-run, pas un service worker autonome.
|
||||
|
||||
Une app spécialisée peut déclencher/suivre un job concret via `ksp-job-api` et la composition adaptée.
|
||||
Une app spécialisée peut construire les ressources Config/Transport/Store, créer un `BackfillJobRuntime`, conserver son `BackfillJobHandle`, observer les snapshots latest-value et demander une annulation coopérative. Elle ne réimplémente ni découverte/hydratation, ni frontier/checkpoint, ni persistance RAW.
|
||||
|
||||
Aucune `ksp-job-control-lib` générique n'est introduite.
|
||||
Aucune `ksp-job-control-lib` générique n'est introduite. Le handle concret suffit tant qu'aucune duplication entre plusieurs jobs ne justifie une couche de gouvernance commune.
|
||||
|
||||
Le fait qu'un worker soit un process/service indépendant ne force pas les jobs à adopter exactement le même modèle de déploiement.
|
||||
|
||||
Le packaging/exécution des jobs sera déterminé avec les premiers jobs réels.
|
||||
Le fait qu'un worker soit un process/service indépendant ne force pas les jobs à adopter exactement le même modèle de déploiement. Le packaging des futurs jobs reste décidé par leur besoin réel ; le premier backfill prouve qu'un runtime de bibliothèque composable est suffisant pour un job déclenché par une application.
|
||||
|
||||
## Scenarios : logique dans la bibliothèque
|
||||
|
||||
@@ -547,7 +545,7 @@ control/application adapters
|
||||
|
|
||||
+--> ksp-worker-control-lib --> ksp-worker-api --> worker service
|
||||
|
|
||||
+--> ksp-job-api -----------> concrete job
|
||||
+--> ksp-job-api -----------> ksp-job-backfill-lib / concrete jobs
|
||||
|
|
||||
+--> ksp-scenario-<domain>-lib
|
||||
```
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 70 -->
|
||||
<!-- version: 71 -->
|
||||
|
||||
# Plans KSP
|
||||
|
||||
@@ -33,6 +33,9 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
|
||||
- [`022-V0_3_1_STORE_RAW_PLAN.md`](022-V0_3_1_STORE_RAW_PLAN.md) — plan candidat réconcilié de `0.3.1 — Store API RAW foundation`; il fixe `ksp-store-api` seul, les modèles transaction/account + observations, queries/outcomes/capabilities, rétention/tombstone, la frontière event-only/Interface et le report de `ksp-store-lib` + PostgreSQL à `0.3.2`.
|
||||
- [`023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) — plan candidat réconcilié de `0.3.2 — Store/PostgreSQL runtime foundation`; il fixe le split façade/backend, `std.store` multi-target réseau-spécifique, tokio-postgres/Deadpool/Rustls, migrations metadata-only, health/readiness, live PostgreSQL et les reports des vertical slices RAW vers `0.3.3`/`0.3.4`.
|
||||
- [`024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md`](024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md) — plan candidat réconcilié de `0.3.3 — Store/PostgreSQL RawTransaction vertical slice`; il fixe V001, binding réseau, mappings entiers exacts, écritures/observations atomiques, pagination keyset/cursor, rétention/tombstone/ForceRehydrate, hardening et preuve PostgreSQL 17.
|
||||
- [`025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md`](025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md) — plan historique clôturé de `0.3.4 — Store/PostgreSQL RawAccountState + complétude RAW`; il complète le backend/façade à dix capabilities RAW et ferme V002.
|
||||
- [`026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md`](026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md) — plan historique clôturé de `0.3.5 — Interface acquisition events`; il fixe les faits passifs provider-neutral `SlotLifecycleEvent` et `TransactionExecutionEvent` sans runtime ni persistence.
|
||||
- [`027-V0_3_6_JOB_API_BACKFILL_PLAN.md`](027-V0_3_6_JOB_API_BACKFILL_PLAN.md) — plan candidat de `0.3.6 — Job API + RAW transaction backfill`; il fixe le contrat Job runtime-neutral, les quatre scopes historiques, RAW v1, provenance observée, persistance Store normale, concurrence/frontier/checkpoint et runtime latest-value annulable.
|
||||
|
||||
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md -->
|
||||
<!-- version: 24 -->
|
||||
<!-- version: 25 -->
|
||||
|
||||
# Plan v0.3.6 — Job API et premier backfill RAW
|
||||
|
||||
@@ -528,17 +528,17 @@ La tranche n'élargit aucune API de production et ne modifie aucune dépendance
|
||||
|
||||
### `pre.011` — Gate technique final
|
||||
|
||||
**Statut : matérialisé ; gate opérateur final à exécuter.**
|
||||
**Statut : réalisé ; gate opérateur final intégralement vert.**
|
||||
|
||||
Budget cible : **15-20 min**. Entrée : hardening `pre.010` intégralement vert avec 47 unitaires + 20 canaries. La tranche ne rouvre aucun code, test fonctionnel, manifeste de crate, dépendance, README/USAGE, CHANGELOG/ROADMAP ou prompt suivant ; elle synchronise uniquement la version workspace, le plan, la validation et son delta.
|
||||
|
||||
Le gate final rejoue le workspace en configuration large : format en mode check, audits Rust/Markdown, `cargo check --workspace`, Clippy `--all-targets --all-features -- -D warnings`, tests `--workspace --all-targets --all-features`, puis graphes de `ksp-job-api`, `ksp-job-backfill-lib` et doublons workspace. Les arbres sont ici justifiés par la clôture technique finale même sans nouveau changement de dépendances dans `pre.011`. Le smoke PostgreSQL reste opt-in et conditionnel à une URI dédiée explicitement disponible ; son absence ne bloque pas la preuve déterministe. Sortie attendue : preuve technique finale consignée, sans réconciliation documentaire durable avant `pre.012`.
|
||||
Le gate final rejoue le workspace en configuration large : format en mode check, audits Rust/Markdown, `cargo check --workspace`, Clippy `--all-targets --all-features -- -D warnings`, tests `--workspace --all-targets --all-features`, puis graphes de `ksp-job-api`, `ksp-job-backfill-lib` et doublons workspace. Les arbres sont ici justifiés par la clôture technique finale même sans nouveau changement de dépendances dans `pre.011`. Le gate opérateur est vert : audits propres, check/Clippy sans warning, `1_404` tests passés et `15` tests explicitement ignorés/opt-in sans aucun échec ; les graphes Job restent conformes et l'inventaire `cargo tree --duplicates` a été revu sans défaut propre au vertical Job nécessitant une correction. Le smoke PostgreSQL dédié n'a pas été exécuté faute d'URI explicitement fournie et reste non bloquant. Sortie : preuve technique finale fermée avant réconciliation documentaire.
|
||||
|
||||
### `pre.012` — Réconciliation documentaire finale
|
||||
|
||||
**Statut : planifié.**
|
||||
**Statut : matérialisé ; gate documentaire à exécuter.**
|
||||
|
||||
Budget cible : **10-15 min**. Entrée : gate technique final vert. Aligner architecture, index, README, USAGE, plan et validation sur la surface prouvée. Sortie : documentation durable cohérente, sans CHANGELOG, ROADMAP ni prompt suivant.
|
||||
Budget cible : **10-15 min**. Entrée : gate technique final vert. La tranche crée les README/USAGE durables de `ksp-job-api` et `ksp-job-backfill-lib`, réconcilie les architectures Jobs/Backfill, les index `docs/`, le README racine, ce plan et la validation sur la surface réellement prouvée. Elle documente notamment le lifecycle Job exact, la sémantique latest-value, les quatre scopes, l'identité `(network, signature)`, la provenance observée, RAW v1, la persistence Store normale, la frontier/checkpoint caller-owned, les limites de reprise crash-safe et l'annulation avec drainage Store. Sortie attendue : documentation durable cohérente et version-neutral côté USAGE, sans CHANGELOG, ROADMAP ni prompt suivant.
|
||||
|
||||
### `pre.013` — Préparation de publication minimale
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/000-README.md -->
|
||||
<!-- version: 34 -->
|
||||
<!-- version: 35 -->
|
||||
|
||||
# Validations KSP
|
||||
|
||||
@@ -29,3 +29,6 @@ Documents :
|
||||
- [`018-V0_3_1_STORE_RAW.md`](018-V0_3_1_STORE_RAW.md) — matrice candidate finale de `0.3.1 — Store API RAW foundation` : modèles transaction/account, observations, capabilities backend, pagination sans policy executor, outcomes, rétention/tombstone, hardening, gate complet `pre.008` et reports explicites vers `0.3.2+`.
|
||||
- [`019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](019-V0_3_2_STORE_POSTGRES_FOUNDATION.md) — matrice candidate finale de `0.3.2 — Store/PostgreSQL runtime foundation` : feature graph, settings/Config, pool/TLS, migrations metadata-only, health, hardening, graphes, builds Tauri et preuve PostgreSQL réelle major 17.
|
||||
- [`020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md`](020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) — matrice candidate finale de `0.3.3 — Store/PostgreSQL RawTransaction vertical slice` : six capabilities backend/façade, V001 et compatibilité schéma, atomicité/idempotence/conflit, keyset/cursor, rétention/races/rehydrate, hardening et replay PostgreSQL 17 final.
|
||||
- [`021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — matrice finale de `0.3.4 — RawAccountState + complétude RAW` : quatre capabilities account supplémentaires, V002, pagination/idempotence et conformance Store 10/10.
|
||||
- [`022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md`](022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md) — matrice finale de `0.3.5 — Interface acquisition events` : événements passifs slot/transaction, façade crate-root, bornes/debug et firewall Interface.
|
||||
- [`023-V0_3_6_JOB_API_BACKFILL.md`](023-V0_3_6_JOB_API_BACKFILL.md) — matrice candidate de `0.3.6 — Job API + RAW transaction backfill` : lifecycle/notifications runtime-neutral, scopes, provenance, RAW v1, Store/idempotence, concurrence/checkpoint, annulation/snapshots, hardening externe et gate workspace final.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/023-V0_3_6_JOB_API_BACKFILL.md -->
|
||||
<!-- version: 25 -->
|
||||
<!-- version: 26 -->
|
||||
|
||||
# Validation v0.3.6 — Job API et premier backfill RAW
|
||||
|
||||
@@ -71,7 +71,8 @@ Aucune entrée absolue, traversée, avec séparateur inversé ou lien symbolique
|
||||
- [X] Les documents d'architecture courants sont réconciliés sur `ksp-job-backfill-lib`; les anciens plans historiques restent historiques et ne sont pas réécrits.
|
||||
- [X] `ksp-job-api` et `ksp-job-backfill-lib` sont obligatoires en parallèle dans la release finale.
|
||||
- [X] Worker API, application et pipeline RAW partagé sont explicitement hors v0.3.6.
|
||||
- [ ] Architecture, README, roadmap et contrats finaux réconciliés avant publication.
|
||||
- [X] Architecture, README, index et contrats de crate durables réconciliés sur la surface finale prouvée.
|
||||
- [ ] ROADMAP et CHANGELOG synchronisés uniquement dans la lane de publication `pre.013`.
|
||||
|
||||
## 5. Contrat `ksp-job-api`
|
||||
|
||||
@@ -261,20 +262,34 @@ Les arbres Cargo sont rejoués ici au titre de la clôture technique finale, mê
|
||||
|
||||
Le smoke PostgreSQL reste conditionnel à une URI dédiée explicitement disponible. En l'absence d'environnement live fourni, il reste non exécuté et non bloquant ; aucune réussite live n'est inventée.
|
||||
|
||||
**Statut : matérialisé ; gate opérateur final à exécuter.**
|
||||
**Statut : réalisé ; gate opérateur final intégralement vert.**
|
||||
|
||||
## 16. Preuves d'intégration et fermeture
|
||||
Preuve opérateur : `cargo fmt --all -- --check`, audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, puis `cargo test --workspace --all-targets --all-features` passent. Le run agrège `1_404` tests passés, `0` échec et `15` tests ignorés explicitement opt-in/operator-only. Les graphes normal/features de `ksp-job-api` et `ksp-job-backfill-lib` sont cohérents ; `cargo tree --duplicates` a été exécuté et revu. Aucun smoke PostgreSQL dédié n'est revendiqué sans URI explicitement fournie.
|
||||
|
||||
## 16. Réconciliation documentaire finale `pre.012`
|
||||
|
||||
- [X] README racine réconcilié sans historique de prerelease.
|
||||
- [X] `ksp-job-api/README.md` et `USAGE.md` décrivent la façade runtime-neutral, le lifecycle, l'annulation et le contrat latest-value.
|
||||
- [X] `ksp-job-backfill-lib/README.md` et `USAGE.md` décrivent scopes, request bounds, runtime, provenance, Store, checkpoint, annulation et reprise sans note de version.
|
||||
- [X] Architectures Layers, Contracts, Inventory, Dependency Graph, Acquisition/Jobs et Apps/Control réconciliées sur le premier job concret.
|
||||
- [X] Index `docs/`, plans et validations synchronisés jusqu'aux documents `027` / `023`.
|
||||
- [X] Les documents durables distinguent checkpoint caller-owned et garantie de reprise crash-safe ; aucune persistence automatique du checkpoint n'est promise.
|
||||
- [X] CHANGELOG, ROADMAP et prompt suivant restent hors de cette tranche.
|
||||
|
||||
**Statut : matérialisé ; gate documentaire à exécuter.**
|
||||
|
||||
## 17. Preuves d'intégration et fermeture
|
||||
|
||||
- [X] Fake Transport et fake Store déterministes sans backend direct exécutés avec succès au gate `pre.007`; fake processor concurrent `pre.008-fix.001` exécuté avec succès.
|
||||
- [ ] Vertical découverte, hydratation, conversion, persistance et observation couvert.
|
||||
- [ ] Smoke Devnet plus PostgreSQL configuré exécuté si l'environnement explicite est disponible.
|
||||
- [ ] Aucun endpoint payant, credential ou donnée sensible requis par les tests normaux.
|
||||
- [ ] Gates technique, documentaire et de publication séparés.
|
||||
- [ ] CHANGELOG et ROADMAP alignés seulement après preuve technique.
|
||||
- [ ] Archives de release minimales et vérifiées.
|
||||
- [X] Vertical découverte, hydratation, conversion, persistance, observation, concurrence, checkpoint et runtime couvert par les gates déterministes.
|
||||
- [ ] Smoke Devnet plus PostgreSQL configuré exécuté si l'environnement explicite est disponible ; non bloquant sans environnement fourni.
|
||||
- [X] Aucun endpoint payant, credential ou donnée sensible requis par les tests normaux.
|
||||
- [X] Gates technique, documentaire et de publication séparés.
|
||||
- [ ] CHANGELOG et ROADMAP alignés seulement après preuve technique, dans `pre.013`.
|
||||
- [X] Archives de prerelease minimales et vérifiées jusqu'au gate technique final.
|
||||
- [ ] Version stable publiée uniquement après tous les critères obligatoires.
|
||||
|
||||
## 17. Règle de vérité
|
||||
## 18. Règle de vérité
|
||||
|
||||
Une case n'est cochée que par une preuve effectivement exécutée ou un audit effectivement réalisé. L'absence de `cargo`, de PostgreSQL configuré ou d'accès live est rapportée comme non exécutée ; elle n'est jamais convertie en succès implicite.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user