---
type: Axis
title: collaboration (multi-writer axis)
description: The collaboration/multi-writer architecture axis — how multiple writers concurrently edit the same logical document (single-writer → optimistic-multi → CRDT/OT). A system-singleton axis whose commitment surface is durable runtime state. DEEP (RFC #75 5A.4 / P1 #851 → promoted 4.5.0a6 #856); worked example is the deliberate single-writer canonical store (the per-project daemon serializes all writes; the #769 spawn-race split-brain fix is the operational guard that keeps it single-writer).
tags: [axis, architecture, collaboration, multi-writer, crdt, ot, rfc-75, deep]
timestamp: 2026-06-18T00:00:00Z
---

# Collaboration (multi-writer axis)

> **DEEP axis (P1 #851 → 4.5.0a6 #856).** Full §6 depth with a worked example
> from the skill's own history — the canonical store is single-writer by design
> (the per-project daemon serializes every write; the #769 spawn-race split-brain
> fix is the flock guard that keeps it single-writer), and the one place
> concurrency surfaced was a multi-host illusion, not real co-editing. Distinct
> from consistency: consistency reconciles writes to a *row*; collaboration is
> concurrent editing of the same *logical document*.

## Concept

Collaboration is the **multi-writer** axis (RFC #75 §3): how multiple writers
concurrently edit the same logical document/state and have their edits merge.
The ladder runs single-writer (only one writer at a time; others are blocked or
serialized) → optimistic-multi (writers edit in parallel + a conflict is
detected + resolved on merge, possibly manually) → CRDT/OT (edits are designed
to merge automatically + commutatively, no manual conflict resolution). Its
**commitment surface is durable runtime state** (§4): merge state, edit logs,
and replica state are runtime state. Its **scope is system-singleton** (§5).

## Why it is an axis (discriminator test — §2)

1. **Ordered tiers** — each rung admits more concurrent writers with automatic
   merge.
2. **Cross-cutting bundle** — a rung dictates the edit representation (whole-doc
   vs operations vs CRDT), the merge algorithm, the conflict UX, and the
   convergence tests.
3. **Asymmetric migration cost** — moving to CRDT/OT means re-representing every
   edit as a commutative operation — a wholesale change to the data model.
4. **Requirement-keyed selection** — falsifiable probes pick the rung.

## Schema view (the §6 entry — validated by `axis_catalog`)

```yaml
id: collaboration
kind: architecture-axis
scope: system-singleton
selection:
  probes:
    - "Does only one writer ever edit a document at a time? → single-writer."
    - "Do multiple writers edit in parallel + occasional conflicts can be surfaced/merged? → optimistic-multi."
    - "Must concurrent edits merge AUTOMATICALLY with no conflict prompt (real-time co-editing)? → CRDT/OT."
    - "Did two parallel edits silently lose one writer's change? → the current rung lacks the merge the requirement needs."
composes_with:
  - "conflict resolution = consistency × collaboration"
applies_when: []
tiers:
  - tier: single-writer
    commitment_delta:
      surface: durable-runtime-state
      delta: "one writer edits a document at a time; concurrent writers are blocked, queued, or rejected. No merge needed."
    admin_tool: "edit-lock / who-is-editing indicator."
    enforcement:
      - "a document edit acquires exclusive write access; others wait or are read-only."
    tests:
      - "a second concurrent writer is blocked/rejected; no edit is lost."
    forecloses: "real concurrent editing."
    migration_cost_to_next: "medium — let writers edit in parallel + detect/merge conflicts."
  - tier: optimistic-multi
    commitment_delta:
      surface: durable-runtime-state
      delta: "writers edit in parallel; on merge, non-overlapping edits combine + overlapping ones surface a conflict for resolution (auto or manual)."
    admin_tool: "conflict-resolution UI; merge history."
    enforcement:
      - "merges combine disjoint edits; a true conflict is surfaced, never silently dropped."
    tests:
      - "two disjoint edits both land; an overlapping pair raises a resolvable conflict."
    forecloses: "conflict-free assumptions; a merge step + conflict UX are required."
    migration_cost_to_next: "high — represent edits as commutative operations that merge automatically (CRDT/OT)."
  - tier: crdt-ot
    commitment_delta:
      surface: durable-runtime-state
      delta: "edits are commutative operations (CRDT) or transformed against concurrent ones (OT); replicas converge automatically without manual conflict resolution."
    admin_tool: "convergence monitor; operation-log inspector."
    enforcement:
      - "every edit is a mergeable operation; concurrent replicas converge to the same state."
    tests:
      - "any interleaving of concurrent edits converges to one state across replicas."
    forecloses: "whole-document write semantics; everything is operation-based."
    migration_cost_to_next: "n/a — top of the ladder."
examples:
  - "The skill sits firmly at SINGLE-WRITER, and that is a deliberate architectural choice the daemon design enforces, not an accident. The per-project daemon owns the canonical store and serializes every write through one process: a single conversation is the one editing session, and the daemon is the exclusive writer to the sqlite DB. The architectural pressure on this axis came not from a desire to co-edit but from a FAILURE to stay single-writer: the #769 spawn-race split-brain, where two daemon instances raced to open the same store (an 82MB WAL, a poisoned projection), was exactly the 'two writers silently clobbering' failure this axis's lowest rung is supposed to prevent — and the fix (a flock boot-lock so the store is opened spawn-once-then-poll, plus a WAL-truncate watchdog) is the enforcement obligation of single-writer made real: not 'let writers merge' but 'guarantee there is only ever one writer.' The OPTIMISTIC-MULTI rung is where a future hosted/multi-operator deployment would land (parallel edits to the same issue body with a conflict surfaced on merge), and CRDT/OT is unreachable without re-representing every recorded turn/edit as a commutative operation — a wholesale data-model change the append-only action-log does not currently support. The skill has never paid that migration cost because single-writer-per-project is sufficient and is structurally cheaper to keep correct."
```

## Selection procedure (§8)

Bidirectional check; chosen once. Recorded in the system architecture record.

## Composition (§5)

Collaboration × consistency = **conflict resolution** — the merge step must
respect the row-level concurrency model. Rule authored in 5A.3.
