DEC-0054 — Atrium: the live layer over git

Reversibility: two-way door on the host (the container is portable) and even on the engine (Yjs is network-agnostic); one-way-ish only on the decision to stand up a stateful server at all — hence the sign-off gate (the single new standing-cost/standing-ops commitment, deferred to explicit human approval before Phase 2).

Specifies Atrium — the live co-working room One loop, three faces — ship an agentic Digital Experience Agency "in a box" (the Agency) plus an adoption-ladder readout product (the Ladder) over the OKF Company Brain, dogfood-first named as the agentic agency's collaboration surface and listed as an expected follow-on DEC. This closes Author the "Atrium" DEC — the live-layer-over-git co-working room (Yjs + self-hosted Y-Sweet; snapshot bridge → reconcile) and is the sibling of Agentic-agency runtime topology — compile personas from the OKF graph and activate the reserved BoardWorker over the deterministic spine (which composes Atrium with the board + reconcile() + MCP). status: active, confidence: asserted: a ratified DESIGN decision — reasoned, not yet verified by running code; the verification gate is Phase-0 implementation.

Context

The agentic agency (One loop, three faces — ship an agentic Digital Experience Agency "in a box" (the Agency) plus an adoption-ladder readout product (the Ladder) over the OKF Company Brain, dogfood-first) needs a place where humans and the agent teams act on a live shared source of truth, under the approve/ship loop — without making any third party hold that live state, and without unseating git as the owned, portable, auditable record (Adopt OKF as Dossier's canonical knowledge format). The app today is 100% static on Vercel (packages/app/svelte.config.js: every app surface prerenders; the only dynamic route is /api/subscribe), so a live collaboration surface is genuinely new infrastructure — which is what makes the host decision a real commitment rather than a default.

Decision

Atrium is the live co-working room over the git-resident OKF.

• Engine: Yjs — a network-agnostic CRDT, no central SSOT in the engine itself.
• Backend: self-hosted Y-Sweet (Jamsocket OSS), one document namespace per tenant, persisting into that tenant's OKF git — NOT a vendor store.
• Snapshot bridge (NEW): on quiesce / approve-gated "land", Yjs state → OKF atom(s) → reconcile() (The compounding merge — the per-tenant learning loop accumulates by id + confidence instead of overwriting (okf reconcile() + opt-in reconcile in extraction/runtime)) → git diff. CRDTs guarantee operational convergence, not semantic validity — so every snapshot MUST round-trip through reconcile() + OKF validation; a malformed state is rejected at the bridge, never committed.
• Agents join as server-side Yjs peers with presence.
• Git stays SSOT; Atrium is an ephemeral, replaceable cache.

Ratify now: the engine (Yjs) + the sovereignty constraint (self-hosted, persist-to-git). Defer to sign-off: the deployment host (Fly.io / Cloud Run / VM).

The host pick is GATED on explicit human cost/ops sign-off before Phase 2. This is the single new standing-cost / standing-ops commitment in the whole platform (a stateful websocket container — everything else is static on Vercel). The engine and the sovereignty constraint are ratified; the host is not chosen here.

Options considered

• Self-hosted Y-Sweet (CHOSEN). Sovereign, Yjs-native, swappable, persists to git. Holds no live state off the tenant's own infra.
• Cloudflare Durable Objects / PartyKit (named FALLBACK). Great DX, but the durable object holds live state, denting sovereignty — acceptable as a fallback, not the default.
• Plain Node ws + Yjs (rejected). Rebuilds a solved primitive.
• Liveblocks (rejected). Hosted, holds live state — a sovereignty violation.
• ElectricSQL (rejected). Postgres-sync — wrong shape for a Yjs room, and a new dependency.

Rationale

• Sovereignty. No third party holds the org's live state — the same stance Adopt OKF as Dossier's canonical knowledge format takes for the memory itself, now extended to the live layer.
• OKF-git-is-SSOT. The live layer is a replaceable cache that persists into git; delete Atrium and lose nothing durable.
• The membrane already exists. Snapshots compound through reconcile() (The compounding merge — the per-tenant learning loop accumulates by id + confidence instead of overwriting (okf reconcile() + opt-in reconcile in extraction/runtime)) — the curation guard — exactly like an extraction pass, so live edits land under the confidence ladder and orphan-flag-not-delete guarantees.
• Approve-gated, not continuous. Snapshot cadence is triggered / approve-gated (not continuous auto-commit), so a human approves the diff — consistent with the review gate that governs the board (Agentic "sprint board" architecture — a git-resident OKF task board worked by bounded, hook-governed Agent SDK loops) and the agentic executor (Agentic-agency runtime topology — compile personas from the OKF graph and activate the reserved BoardWorker over the deterministic spine Invariant 3).
• asserted, not verified. No Y-Sweet server runs, no snapshot has round-tripped — this is design conviction, validated against the existing reconcile() membrane and the static-app baseline, not field evidence.

Consequences

• Introduces the one piece of standing infra not on Vercel — a stateful websocket container — a deliberate, sign-off-gated cost (the engine/sovereignty are ratified; the host commitment waits for human cost/ops sign-off before Phase 2).
• (app)/atrium/ becomes the first and only fully-dynamic app surface; everything else stays prerendered (packages/app/svelte.config.js).
• Snapshot validity depends on OKF validation + reconcile() — the bridge is the membrane; an invalid CRDT state never reaches git.

Relation to DEC-0052

Together with Agentic-agency runtime topology — compile personas from the OKF graph and activate the reserved BoardWorker over the deterministic spine, this DEC ratifies and PROMOTES the proposed architecture mapping in One loop, three faces — ship an agentic Digital Experience Agency "in a box" (the Agency) plus an adoption-ladder readout product (the Ladder) over the OKF Company Brain, dogfood-first (its "Atrium → live co-working room" row) from proposed → ratified. DEC-0052's body is unchanged; this is one of the two follow-on DECs it named.

Review

The gate that promotes asserted → verified: Phase-0 implementation lands — a self-hosted Y-Sweet server (one namespace per tenant) runs, humans + a server-side agent peer co-edit a shared state with presence, and an approve-gated snapshot round-trips Yjs → OKF atom(s) → reconcile() → a git diff in the tenant's own history, with a deliberately malformed state rejected at the bridge (never committed). The host cost/ops sign-off is a separate human gate that must clear before Phase 2 stands up the standing infra.