b3afd4e766
Some checks failed
joule-moq-remote host agent / joule-moq-remote · does this change touch it (push) Successful in 23s
joule-moq-room room service / joule-moq-room · does this change touch it (push) Successful in 28s
joule-moq-web browser client / joule-moq-web · does this change touch it (push) Successful in 28s
wai-app and Create / wai-app · does this change touch it (push) Successful in 28s
wai-fleet service / does this change touch it (push) Successful in 28s
joule-code conformance gate / joule-moq-relay, its own energy on a counter (macos) (push) Successful in 40s
joule-moq-remote host agent / joule-moq-remote, every target (macos) (push) Successful in 48s
wai-fleet service / service · macos (push) Successful in 38s
wai-app and Create / wai-app · Create, browser end-to-end (macos) (push) Successful in 5m2s
wai-app and Create / wai-app · tests, clippy, the line language's verifier (linux) (push) Successful in 38s
joule-code conformance gate / Build + round-trip C1-C4 vectors (push) Successful in 2m55s
joule-moq-web browser client / joule-moq-web · browser end-to-end (macos) (push) Successful in 17m6s
wai-fleet service / service · linux (push) Successful in 3m32s
joule-moq-remote host agent / joule-moq-remote, every target (linux-arm64) (push) Has been cancelled
joule-moq-room room service / joule-moq-room, every target (push) Has been cancelled
repository checks / lockfiles, advisories, tests in CI, workflow hygiene, spec and section references, public text (push) Has been cancelled
joule-code conformance gate / joule-moq-relay, every target (push) Has been cancelled
joule-code conformance gate / joule-moq-ingest, every target (push) Has been cancelled
communicationOS consolidated into WAI, and its site is retired. Where these texts meant the transport they now say WAI or MoQT, and joule-moq's description, the Joule Code docs and the Three Faces tables follow. The transport example names joule-moq, which it uses, and its test drops the old name. Changelog: none Co-Authored-By: Claude Opus 5.5 <[email protected]>
41 lines
5.5 KiB
Markdown
41 lines
5.5 KiB
Markdown
# Joule Code — Federated Collaboration Binding (Research)
|
|
|
|
Interface-level sub-specification of [`../SPEC.md`](../SPEC.md) §7. CC-BY-4.0.
|
|
|
|
> **Readiness: Research.** This binding is specified at the interface level only. It is **not** required for v0.1 conformance; a single-endpoint runtime is fully conformant without it. This document fixes the shape so the cargo and receipt designs do not foreclose it, and so a future conformance-bearing version (ROADMAP) has a target.
|
|
|
|
## 1. The thesis
|
|
|
|
A cloud-collaborative coding environment with **no tie to a single private company** cannot route every change through one vendor's server. Joule Code achieves ownerless collaboration by composing existing substrate faces rather than introducing a central authority:
|
|
|
|
- A **coding operation is a [Smart Byte](../../smart-byte/) envelope** whose cargo is the `CodingOp` (cargo.md). It inherits content-addressed identity, signed transitions, and lockstep replication unchanged.
|
|
- **Consistency** is lockstep deterministic simulation with BFT supermajority commit among a known, signed-membership cluster of collaborators — the same mechanism Smart Byte uses for value, applied to coding operations. The substrate scales by federating bounded clusters (one per project/session), not by growing one.
|
|
- **Transport, session, and presence** bind to **WAI**: MLS group state for the collaborating set, FROST threshold signing for operations that require multi-party authorization (e.g. a protected-branch commit), MoQT tracks for live cursors and audio.
|
|
- **Shared interactive sessions** (pair programming, screen handoff) bind to **RemoteOS**: end-to-end-encrypted, with its hash-chained auth ledger providing an offline-verifiable record of who joined and acted.
|
|
|
|
## 2. What is open at the interface
|
|
|
|
```
|
|
collab.submit(op: SignedOp) -> CommitOutcome // propose an op to the cluster
|
|
collab.subscribe() -> stream<Committed> // ordered, agreed operations
|
|
collab.membership() -> SignedMembership // who is in the cluster
|
|
```
|
|
|
|
A committed operation carries its receipt (receipt.md), so the **energy ledger of a collaboration is itself auditable** — every accepted change across all collaborators has a signed joule cost, re-walkable offline by anyone holding the log.
|
|
|
|
The reference library implements this interface in [`joule-code-collab`](../joule-code-rs/crates/joule-code-collab/):
|
|
|
|
- `Collab` + a single-node `LocalCluster` that enforces the log invariants (ordered, de-duplicated, signature- and membership-checked).
|
|
- `LockstepCluster` — the **consensus core**: a multi-node *lockstep deterministic simulation with BFT supermajority commit*. `n` nodes step in rounds; an operation commits only when at least `2f+1` of `n = 3f+1` honest nodes independently validate it, and committed ops are ordered by `op_id`, so every honest node derives a byte-identical log. Safety holds with up to `f` Byzantine nodes; liveness is lost only beyond `f`. This is the genuine agreement protocol, in-process and deterministic.
|
|
|
|
- `protected` — **FROST threshold authorization** of protected operations: a `t`-of-`n` FROST (Ed25519) signature over an op's `op_id`, verifiable against the cluster's single group key. No member holds the whole key; fewer than `t` cannot authorize. The crate carries the ownerless verification side; the dealer-keygen + two-round signing flow is exercised in tests.
|
|
|
|
- **MLS group keying** (RFC 9420, via `openmls`) — the collaborating set forms an MLS group and derives a **shared group key** with no central server, so collaboration traffic (coding operations / Smart Byte envelopes) is end-to-end encrypted among members; adding a member advances the epoch and the new member derives the same key, while past epochs stay forward-secret. Demonstrated in `tests/mls_keying.rs` (a dev-dependency, so the library's runtime deps stay light).
|
|
|
|
- **MoQT transport** — the network wire carrier between members, demonstrated in [`examples/transport-moqt`](../examples/transport-moqt/). A collaboration's committed (consensus-ordered) coding operations are published as MoQT objects over [`inv-moq`](../../../joulesperbit/crates/inv-moq) — the MoQT (Media over QUIC Transport) protocol with its JWP receipt extension. Each object carries a real Ed25519/BLAKE3 **signed receipt**; a subscriber receives every op, verifies the receipts against the publisher's key, and recovers the original `SignedOp` intact — and a receipt-requiring subscriber rejects any group whose signed receipt does not chain to a trusted key (ownerless authenticity, no central authority). Driven through `inv-moq`'s in-process `MockFabric` (real signatures, real BLAKE3 merkle receipts, no QUIC); the crate's `quic` feature is the real-wire path behind an identical trait surface. A standalone workspace, so the library's runtime deps stay light.
|
|
|
|
With consensus, protected-op threshold authorization, group keying, **and** transport now all implemented and tested, the four federation layers of this binding are complete in-process; what remains for graduation from Research is the conformance pack (§3, ROADMAP) and hardening the real-QUIC wire path and concurrent-edit conflict handling.
|
|
|
|
## 3. Why it is deferred
|
|
|
|
Lockstep BFT over edit streams, MLS/FROST session management, and conflict handling for concurrent edits to overlapping anchors are genuine research-and-engineering surface. Shipping them behind a stable single-endpoint v0.1 — rather than blocking the standard on them — is the readiness discipline (SPEC §9). When the binding stabilizes it earns its own conformance pack and graduates from Research to Engineering.
|