open-standards/joule-code/spec/collab.md

# 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 **CommunicationOS** (Ambient Mobile): 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).

- **CommunicationOS (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) — CommunicationOS's 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.