docs(roadmap): spécification technique V3 — runtime natif distribué - #282
Merged
Merged
Conversation
Nouveau roadmap/V3_NATIVE_RUNTIME_SPEC.md : architecture cible pour V3 (Distribution) — Python reste le plan de contrôle (plugins, SDK, API, orchestration), un nouveau runtime natif Rust (xcore-runtime, embarqué via PyO3) prend en charge l'appartenance au cluster, le transport inter-nœuds, le routage, le volet distribué de XBus, le circuit breaker et le failover. Couvre : modèle de nœud, fédération statique, FederatedHandler, protocole de sérialisation versionné, sémantique de livraison des events (at-least-once), politique de retry/backpressure, frontière Python↔Rust (PyO3/maturin), stratégie de migration en 7 phases, definition of done. Rien n'est implémenté — c'est un document de spécification pour du travail qui commencera une fois la fenêtre de maintenance V2 terminée. Cross-référencé depuis la section V3 des deux fichiers roadmap (ROADMAP_PROGRESS.md / executed_roadmap.md), chaque ligne du tableau V3 correspond désormais à une section de la spec.
Contributor
Reviewer's GuideCe PR ajoute une spécification d’architecture détaillée pour XCore V3 : Python reste le plan de contrôle, tandis qu’un runtime Rust prend en charge le transport, le routage, la fédération, les événements distribués et la résilience. Les deux roadmaps sont mises à jour pour référencer cette cible, sans introduire d’implémentation ni de changement de comportement. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Contributor
|
|
Contributor
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 3 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="roadmap/V3_NATIVE_RUNTIME_SPEC.md" line_range="364-375" />
<code_context>
## 🌐 V3 — Distribution
**Goal: Scale out beyond a single process.**
+**Technical specification (2026-09-28)**: `roadmap/V3_NATIVE_RUNTIME_SPEC.md` — Python stays the control plane (plugins, SDK, API, orchestration); a new Rust native runtime (`xcore-runtime`, embedded via PyO3) owns cluster membership, inter-node transport, routing, the distributed side of XBus, circuit breaking, and failover. Every row below maps to a section of that spec — none of it is implemented yet, this is the target architecture for when the V2 maintenance window ends.
+
</code_context>
<issue_to_address>
**issue (bug_risk):** The membership state machine has no transition from DEGRADED, UNAVAILABLE, or REMOVED back to READY, but the failover requirements later require restoring the original route when a node recovers. A recovered node therefore has no specified path back into the eligible routing state.
**Triggers:** When a node temporarily fails and then recovers.
**Suggested fix:** Define explicit recovery transitions, including the conditions for returning from UNAVAILABLE or DEGRADED to READY, and specify whether REMOVED nodes can rejoin.
</issue_to_address>
### Comment 2
<location path="roadmap/ROADMAP_PROGRESS.md" line_range="60" />
<code_context>
## 🌐 V3 — Distribution
**Goal: Scale out beyond a single process.**
+**Technical specification (2026-09-28)**: `roadmap/V3_NATIVE_RUNTIME_SPEC.md` — Python stays the control plane (plugins, SDK, API, orchestration); a new Rust native runtime (`xcore-runtime`, embedded via PyO3) owns cluster membership, inter-node transport, routing, the distributed side of XBus, circuit breaking, and failover. Every row below maps to a section of that spec — none of it is implemented yet, this is the target architecture for when the V2 maintenance window ends.
+
| Feature | State | Location / Note |
</code_context>
<issue_to_address>
**nitpick:** The roadmap annotations state that every V3 table row maps to a section of the specification, but the table rows for AgentBase IA, Hot Reload Plugins, and Service Hot-Swap have no corresponding sections in `V3_NATIVE_RUNTIME_SPEC.md`. This makes the cross-reference claim false and leaves those roadmap items undocumented by the referenced specification.
**Suggested fix:** Either add sections covering those three roadmap items or change the annotation to say that only the distributed-runtime rows map to the specification.
```suggestion
**Technical specification (2026-09-28)**: `roadmap/V3_NATIVE_RUNTIME_SPEC.md` — Python stays the control plane (plugins, SDK, API, orchestration); a new Rust native runtime (`xcore-runtime`, embedded via PyO3) owns cluster membership, inter-node transport, routing, the distributed side of XBus, circuit breaking, and failover. Only the distributed-runtime rows below map to a section of that spec — none of it is implemented yet, this is the target architecture for when the V2 maintenance window ends.
```
</issue_to_address>
### Comment 3
<location path="roadmap/V3_NATIVE_RUNTIME_SPEC.md" line_range="561" />
<code_context>
+* topic;
+* tenant scope;
+* source node;
+* event ID;
+* timestamp;
+* trace context;
+* delivery metadata.
+
+Example:
+
+```text
+Event
+├── event_id
+├── topic
+├── tenant_id
+├── source
+├── timestamp
+├── trace_context
+└── payload
+```
+
+Events MUST NOT accidentally cross tenant boundaries.
+
+---
+
+# 18. Delivery Semantics
+
+V3 MUST explicitly define event delivery semantics.
+
+Initial implementation:
+
+```text
+At-least-once delivery
+```
+
+Consumers MUST therefore be designed to tolerate duplicate delivery.
+
+The runtime should expose event identifiers allowing consumers to implement idempotency.
+
+Exactly-once semantics MUST NOT be assumed.
</code_context>
<issue_to_address>
**issue (bug_risk):** Distributed events are declared to MUST support an event ID, but the delivery section only says the runtime 'should' expose event identifiers. An implementation can therefore conform to the delivery section while omitting the identifier consumers need for deduplication, contradicting the stated at-least-once contract.
**Suggested fix:** Make event-ID generation and propagation a MUST, including its uniqueness and persistence scope across retries and redelivery.
```suggestion
The runtime MUST generate and propagate a unique event identifier for each event. The identifier MUST persist unchanged across retries and redelivery.
```
</issue_to_address>Sourcery assessment
Approval pending. 2 findings to address first.
Blocking findings: roadmap/V3_NATIVE_RUNTIME_SPEC.md:375, roadmap/V3_NATIVE_RUNTIME_SPEC.md:561
Comment on lines
+364
to
+375
|
|
||
| ```text | ||
| JOINING | ||
| ↓ | ||
| READY | ||
| ↓ | ||
| DEGRADED | ||
| ↓ | ||
| UNAVAILABLE | ||
| ↓ | ||
| REMOVED | ||
| ``` |
Contributor
There was a problem hiding this comment.
issue (bug_risk): The membership state machine has no transition from DEGRADED, UNAVAILABLE, or REMOVED back to READY, but the failover requirements later require restoring the original route when a node recovers. A recovered node therefore has no specified path back into the eligible routing state.
Triggers: When a node temporarily fails and then recovers.
Suggested fix: Define explicit recovery transitions, including the conditions for returning from UNAVAILABLE or DEGRADED to READY, and specify whether REMOVED nodes can rejoin.
| ## 🌐 V3 — Distribution | ||
| **Goal: Scale out beyond a single process.** | ||
|
|
||
| **Technical specification (2026-09-28)**: `roadmap/V3_NATIVE_RUNTIME_SPEC.md` — Python stays the control plane (plugins, SDK, API, orchestration); a new Rust native runtime (`xcore-runtime`, embedded via PyO3) owns cluster membership, inter-node transport, routing, the distributed side of XBus, circuit breaking, and failover. Every row below maps to a section of that spec — none of it is implemented yet, this is the target architecture for when the V2 maintenance window ends. |
Contributor
There was a problem hiding this comment.
nitpick: The roadmap annotations state that every V3 table row maps to a section of the specification, but the table rows for AgentBase IA, Hot Reload Plugins, and Service Hot-Swap have no corresponding sections in V3_NATIVE_RUNTIME_SPEC.md. This makes the cross-reference claim false and leaves those roadmap items undocumented by the referenced specification.
Suggested fix: Either add sections covering those three roadmap items or change the annotation to say that only the distributed-runtime rows map to the specification.
Suggested change
| **Technical specification (2026-09-28)**: `roadmap/V3_NATIVE_RUNTIME_SPEC.md` — Python stays the control plane (plugins, SDK, API, orchestration); a new Rust native runtime (`xcore-runtime`, embedded via PyO3) owns cluster membership, inter-node transport, routing, the distributed side of XBus, circuit breaking, and failover. Every row below maps to a section of that spec — none of it is implemented yet, this is the target architecture for when the V2 maintenance window ends. | |
| **Technical specification (2026-09-28)**: `roadmap/V3_NATIVE_RUNTIME_SPEC.md` — Python stays the control plane (plugins, SDK, API, orchestration); a new Rust native runtime (`xcore-runtime`, embedded via PyO3) owns cluster membership, inter-node transport, routing, the distributed side of XBus, circuit breaking, and failover. Only the distributed-runtime rows below map to a section of that spec — none of it is implemented yet, this is the target architecture for when the V2 maintenance window ends. |
|
|
||
| Consumers MUST therefore be designed to tolerate duplicate delivery. | ||
|
|
||
| The runtime should expose event identifiers allowing consumers to implement idempotency. |
Contributor
There was a problem hiding this comment.
issue (bug_risk): Distributed events are declared to MUST support an event ID, but the delivery section only says the runtime 'should' expose event identifiers. An implementation can therefore conform to the delivery section while omitting the identifier consumers need for deduplication, contradicting the stated at-least-once contract.
Suggested fix: Make event-ID generation and propagation a MUST, including its uniqueness and persistence scope across retries and redelivery.
Suggested change
| The runtime should expose event identifiers allowing consumers to implement idempotency. | |
| The runtime MUST generate and propagate a unique event identifier for each event. The identifier MUST persist unchanged across retries and redelivery. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Résumé
Nouveau
roadmap/V3_NATIVE_RUNTIME_SPEC.md— spécification technique pour XCore V3 (Distribution).Principe architectural : Python reste le plan de contrôle (plugins, SDK, API, orchestration) ; un nouveau runtime natif Rust (
xcore-runtime, embarqué via PyO3) prend en charge tout ce qui exige latence prédictible, concurrence et isolation de panne — appartenance au cluster, transport inter-nœuds, routage, volet distribué de XBus, circuit breaker, failover.Couvre notamment :
FederatedHandler, transparence de localisation des pluginsRien n'est implémenté — c'est un document de spécification pour du travail qui commencera une fois la fenêtre de maintenance V2 terminée (voir
roadmap/ROADMAP_PROGRESS.md).Cross-référencé depuis la section V3 des deux fichiers roadmap (
ROADMAP_PROGRESS.md/executed_roadmap.md) — chaque ligne du tableau V3 correspond désormais à une section de la spec.Test plan
make lint-check/tests non affectés.Summary by Sourcery
Define the XCore V3 native distributed runtime architecture and phased migration plan without implementing the runtime.
Enhancements:
Documentation:
V3_NATIVE_RUNTIME_SPEC.mdtechnical specification and cross-reference it from both roadmap documents.