feat(collab): SPEC-003 realtime collaborative editing via P2P CRDTs #4

Merged

hugooconnor merged 0 commits from refs/pull/4/head into main

2026-06-21 11:25:23 +00:00

hugooconnor commented

2026-06-21 11:20:17 +00:00

(Migrated from codeberg.org)

SPEC-003: Realtime Collaborative Editing via P2P CRDTs

Turns ar-edit from a single-machine tool into a realtime, multiplayer editor: two or more instances collaborate on one project over a direct peer-to-peer connection, with no central server holding state. Implements SPEC-003.

Scale: 41 commits, 115 files, ~19.5k insertions.

What's in it

CRDT edit store (ADR-011): the edit document is a Loro CRDT — the single source of truth — with the JSON snapshot as a derived read view. Identity-preserving moves (REQ-080), LWW range trims (REQ-081), grow-only notes, durable single-writer undo over the oplog cursor (no daemon needed), and deterministic legacy migration (REQ-088).
Session daemon + IPC (ADR-014, CON-018): ar-edit daemon --edit <name> owns the canonical file; one-shot commands attach to a live host and mutate through it (one store, no divergence), failing closed if the socket is present but unresponsive (bounded by a timeout).
Per-source annotation CRDT store (ADR-015): markers and POIs are CRDT OR-sets, converging across peers; mark/poi CLI commands route through it with legacy-file migration.
Author attribution (REQ-091): every marker, POI, shot, and note records a human-readable author, autopopulated (AR_EDIT_AUTHOR → .ar-edit/author → git user.name → OS username), stored as CRDT state, shown in mark/poi/edit show.
Pairing & transport (feature-gated): SPAKE2 pairing over direct iroh, serverless phrase-keyed pkarr/Mainline-DHT discovery (ADR-009/013), content-addressed source/blob sync (REQ-075/077).

Quality

Full test matrix green — core, collab (daemon + transport on stable 1.93), binary.
Mutation-hardened (PROTO-001 mandate for AI-synthesised code): store.rs 100% kill, crdt.rs 90% (remaining survivors are equivalent/redundancy-masked), edit.rs 100%; plus property + adversarial tests, with the id-reuse blocker's proptest seed checked in.
Two independent fresh-context reviews found and fixed real blockers (id reuse after undo+reload, fail-closed IPC, deterministic migration).
PROTO-001 conformance pass — Orientation block, BCP 14, traceability matrix, READMEs.

Known caveats (read before merging as "collaboration done")

ADR-009 SPAKE2 is a no-go crypto area needing a Tier-1 review — flagged items: non-constant-time confirmation compare, raw blake3 KDF (vs HKDF), no transcript/node-key binding. Pairing policy is a deliberate 3-attempt lockout (not burn-on-first). The local/annotation paths don't depend on this.
Observability (OBS-003) not yet implemented (no tracing/metrics).
Live remote sync is gated (OQ-7) — transport is loopback-tested only; the local single-machine path is complete.
One-way on-disk format migration (event-sourced → CRDT) on first open.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XShvi51hax77hMd6wHFBTf

## SPEC-003: Realtime Collaborative Editing via P2P CRDTs Turns `ar-edit` from a single-machine tool into a realtime, multiplayer editor: two or more instances collaborate on one project over a direct peer-to-peer connection, with no central server holding state. Implements [`SPEC-003`](specs/SPEC-003-realtime-collaborative-editing.md). **Scale:** 41 commits, 115 files, ~19.5k insertions. ### What's in it - **CRDT edit store (ADR-011):** the edit document is a Loro CRDT — the single source of truth — with the JSON snapshot as a derived read view. Identity-preserving moves (REQ-080), LWW range trims (REQ-081), grow-only notes, durable single-writer undo over the oplog cursor (no daemon needed), and deterministic legacy migration (REQ-088). - **Session daemon + IPC (ADR-014, CON-018):** `ar-edit daemon --edit <name>` owns the canonical file; one-shot commands **attach** to a live host and mutate through it (one store, no divergence), failing **closed** if the socket is present but unresponsive (bounded by a timeout). - **Per-source annotation CRDT store (ADR-015):** markers and POIs are CRDT OR-sets, converging across peers; `mark`/`poi` CLI commands route through it with legacy-file migration. - **Author attribution (REQ-091):** every marker, POI, shot, and note records a human-readable author, autopopulated (`AR_EDIT_AUTHOR` → `.ar-edit/author` → git `user.name` → OS username), stored as CRDT state, shown in `mark`/`poi`/`edit show`. - **Pairing & transport (feature-gated):** SPAKE2 pairing over direct iroh, serverless phrase-keyed pkarr/Mainline-DHT discovery (ADR-009/013), content-addressed source/blob sync (REQ-075/077). ### Quality - **Full test matrix green** — core, collab (daemon + transport on stable 1.93), binary. - **Mutation-hardened** (PROTO-001 mandate for AI-synthesised code): `store.rs` 100% kill, `crdt.rs` 90% (remaining survivors are equivalent/redundancy-masked), `edit.rs` 100%; plus property + adversarial tests, with the id-reuse blocker's proptest seed checked in. - **Two independent fresh-context reviews** found and fixed real blockers (id reuse after undo+reload, fail-closed IPC, deterministic migration). - **PROTO-001 conformance pass** — Orientation block, BCP 14, traceability matrix, READMEs. ### Known caveats (read before merging as "collaboration done") - **ADR-009 SPAKE2 is a no-go crypto area needing a Tier-1 review** — flagged items: non-constant-time confirmation compare, raw `blake3` KDF (vs HKDF), no transcript/node-key binding. Pairing policy is a deliberate **3-attempt lockout** (not burn-on-first). The local/annotation paths don't depend on this. - **Observability (OBS-003) not yet implemented** (no `tracing`/metrics). - **Live remote sync is gated (OQ-7)** — transport is loopback-tested only; the local single-machine path is complete. - **One-way on-disk format migration** (event-sourced → CRDT) on first open. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01XShvi51hax77hMd6wHFBTf

No reviewers

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

anuna-research/ar-edit!4

No description provided.

Rows
Columns