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

Joule Code — Federated Collaboration Binding (Research)

Interface-level sub-specification of ../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 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:

• 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. A collaboration's committed (consensus-ordered) coding operations are published as MoQT objects over 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.