ADR-0013: Collaboration Data & the Social Layer
Extended by ADR-0021: the embedded-Dolt warehouse decided here is the concrete rail for knowledge bases (KBs) — the queryable compounding-memory graph (ADR-0019). ADR-0021 keeps this ADR's line intact (trajectories & skills stay in git, never Dolt) and binds each
.stettier to 1:N KBs that are composable, importable, and governable.
Status
Proposed / exploring. Captured during ideation on 2026-07-04; the core storage directions were decided in review the same day (marked DECIDED). Revisit for promotion after the core loop (SPEC-0001..0003) is standing.
Context and Problem Statement
Stet's markup — comments, emoji verb reactions, review threads, resolution state, and votes (ADR-0014) — is relational, high-churn, multi-user, and concurrently edited. To make Stet social (teammates and their agents commenting/reacting/voting on the same PR, changes syncing and merging without conflict), that data needs a shared, versioned, mergeable home. This ADR decides how the social/collaboration layer is stored and synced.
The layered decision
Two layers, each doing what it is best at.
DECIDED — Forge (GitHub/Gitea) is the social backbone
The forge provides identity (OAuth, ADR-0007), a shared surface, and baseline social interop: PR comments and emoji reactions that teammates who are not running Stet can still see and participate in. Stet maps its simpler markup onto forge-native comments/reactions so collaboration is never Stet-only.
DECIDED — Embedded Dolt is the rich versioned substrate
Stet's richer, Stet-native collaboration data (verb reactions, anchored ranges, scribble/voice markup, tour-stop anchors, review/resolution state, and votes per ADR-0014) — plus the distillation outcomes warehouse (ADR-0012) — lives in Dolt ("Git for data": a version-controlled, MySQL-compatible database with cell-wise merge). This is where Dolt's model genuinely wins: concurrent reactions/votes on the same artifact merge cleanly, where git text files would conflict-storm.
- Embedded & bundled. Stet bundles Dolt and runs it locally (a managed
dolt sql-serversubprocess over localhost, or the Go embedded driver bridged to Swift). Bundling a Go engine is an accepted trade-off for a macOS dev tool. - Self-host setting. A settings option lets a user point at their own instance (a self-hosted DoltLab or a shared remote) for team sync. Local-first by default; bring-your-own-remote for teams.
- Sync. Dolt syncs via a shared remote — either over the forge (Dolt's Git-remote support) or a self-hosted DoltLab — so the "forge is the backend" principle and the Dolt substrate compose rather than compete.
DECIDED — Trajectories & skills stay in git, not Dolt
Reaffirmed from ADR-0011/0012: trajectories and skills are document-shaped artifacts
coupled to the code's commit graph (a trajectory is the branch's final commit).
They remain git-in-repo under .stet/. Dolt holds collaboration/relational data,
not the code-coupled artifacts.
What lives where
| Data | Home | Why |
|---|---|---|
| Code | git repo | — |
| Trajectories, skills | git repo (.stet/) | code-coupled, document-shaped (ADR-0011/0012) |
| Baseline comments + emoji | forge (GitHub/Gitea) | identity + interop with non-Stet users |
| Rich markup, threads, resolution, votes | embedded Dolt | relational, concurrent, cell-merge |
| Distillation outcomes / skill efficacy | embedded Dolt | versioned + SQL-queryable (ADR-0012) |
Considered and set aside
- SQLite + custom sync — natively embeddable but rebuilds versioning/merge; loses the reason Dolt is attractive.
- CRDT (Automerge/Yjs) + sync service — real-time live collab, but heaviest infra and furthest from the async, editorial review posture. May revisit if live collaboration is wanted later.
- Forge-only (no rich store) — too lossy for Stet's rich markup and votes.
Open questions
- Exact split: which markup maps onto forge comments/reactions vs. lives only in Dolt.
- Dolt embedding mechanics: bundled
dolt sql-serversubprocess vs. Go-driver bridge; binary size and lifecycle management. - Default sync topology: Dolt-over-forge-remote vs. DoltLab; what ships as default vs. self-host setting.
- Collaboration schema (comments, threads, reactions, votes) as a versioned contract.
- Notifications + presence (the rest of "social" beyond the store).
Consequences (tentative)
- Introduces a
CollaborationStoreseam with a forge-native path (baseline) and an embedded-Dolt path (rich data + votes + outcomes warehouse). - Ships a bundled Dolt engine + a self-hosted-instance setting.
- Keeps trajectories/skills in git (reaffirms ADR-0011/0012).
- Provides the store that ADR-0014 (agent voting) and ADR-0012 (distillation) build on.
More Information
Dolt: https://github.com/dolthub/dolt · embedded Go driver: https://github.com/dolthub/driver · Dolt Git-remote support (2026-02): https://www.dolthub.com/blog/2026-02-13-announcing-git-remote-support-in-dolt/ · DoltLab (self-hosted): https://www.doltlab.com/ · voting: ADR-0014.