Studio · Real-Time Collaboration Substrate

Purpose#

Operate the real-time collaboration substrate as a live, admin-scoped BFF console. The workspace (StudioRealTimeCollaborationSubstrateWorkspace) wires a single CRDT Merge Lane to the real LWW-Element-Set (Last-Writer-Wins Element-Set) CRDT via /v1/admin/studio/crdt-merge: it folds replica operation logs into the convergent shared state. Each element is present when its latest add is not superseded by a later remove, and the converged state is the same regardless of operation order. This is a real domain computation, not a simulation.

Entry points#

• Studio root (/studio) — discoverable as a collaboration workspace
• Quick-action links from sibling collaboration workspaces (presence, commenting, review/approval, activity/change feeds, notification center, audit/compliance surfaces)
• Direct URL / bookmark — yes

Layout regions#

page.tsx mounts ShellLayout active="studio", renders StudioRealTimeCollaborationSubstrateWorkspace, then a single panel containing 6 sibling quickAction links. There is no Route Map panel on this page.

• Shell header — from ShellLayout
• Workspace <h1> — "Studio Real-Time Collaboration Substrate" (WorkspaceHeading), followed by a data-realtime-collaboration-summary paragraph describing the merge semantics
• CRDT Merge Lane (<h2> data-cr-lane-heading "CRDT Merge Lane") — the catalog/loading/unauthorized/error states, the merge form, and the result
• Quick-actions panel — panel with 6 quickAction links to sibling workspaces (no self-link, no Route Map)

States#

• Loading — data-cr-loading "Loading CRDT merger…" while the GET catalog request is in flight (outcome === null)
• Unauthorized — data-cr-unauthorized "Access restricted." when the catalog GET returns 401/403 (admin scope required); shows the BFF message or "Studio admin scope required to merge CRDT state."
• Error — data-cr-error "Could not load the CRDT merger." on any non-OK catalog response or network failure
• Ready (form) — catalog loaded; data-cr-enums shows {crdtType} · {opKinds.length} op kinds, and the data-cr-form merge form renders
• Result — after a successful POST, data-cr-result renders the converged headline + per-element table
• Merge validation error — data-cr-merge-error for invalid JSON, network unavailable, or a non-200 POST (shows the POST detail)
• Anonymous user — redirected to /welcome?redirect=%2Fstudio%2Freal-time-collaboration-substrate before the workspace root renders

Interactions#

CRDT Merge Lane form#

• Operations (textarea data-cr-payload, aria-label operations json) — JSON { operations[{ replicaId, element, op, timestamp }] }; seeded with a default payload
• Merge replicas (button data-cr-submit, type="submit") — submitMerge parses the JSON (rejecting invalid JSON with data-cr-merge-error) and POSTs to /v1/admin/studio/crdt-merge/merge
• Client-side malformed JSON block — invalid JSON surfaces "Payload must be valid JSON." and does not send a POST
• Live BFF invalid payload branch — valid JSON with operations: [] reaches the BFF and surfaces detail "operations must be a non-empty array"
• LWW tie semantics — a shuffled payload where tie has add/remove at timestamp 7 renders data-present="true", proving the add-biased tie-breaker over the real BFF merge route

Result#

• Headline (data-cr-headline) — renders: converged: <data-cr-converged> plus {presentCount} present and {removedCount} removed
• Elements table (data-cr-elements) — one data-cr-element-row per element with data-element, data-present, plus data-cr-add-ts / data-cr-remove-ts cells

Quick actions#

• Open Presence and Cursor Systems workspace
• Open Commenting and Annotation System workspace
• Open Review and Approval Workflows workspace
• Back to Activity and Change Feeds workspace
• Back to Notification Center workspace
• Back to Audit and Compliance Surfaces workspace

Data & contracts#

• GET catalog: /v1/admin/studio/crdt-merge — fetched on mount with buildBffAuthHeaders() and cache: 'no-store'; returns { opKinds[], crdtType }
• POST verb: /v1/admin/studio/crdt-merge/merge with body { operations[{ replicaId, element, op, timestamp }] } → { result: { elements[], converged[], summary{ presentCount, removedCount } } } (200) or a detail error
• Realtime: none — request/response only
• Client fetch: direct fetch with cache: 'no-store'; no client-side caching
• Auth/role check: admin-scoped, fail-closed at the BFF (admin:* | admin:studio; 401 missing auth, 403 missing scope); reached through the signed-in + studio route gate

Cross-references#

• Parent: ../studio-overview.md
• Sibling: studio-presence-cursor-systems.md, studio-commenting-annotation-system.md, studio-review-approval-workflows.md
• Component: apps/oshun/web/src/components/studio/StudioRealTimeCollaborationSubstrateWorkspace.tsx
• BFF route: apps/oshun/bff/src/routes/admin-studio-crdt-merge.ts
• BFF store: apps/oshun/bff/src/studio/crdt-lww-store.ts

E2E coverage#

• apps/oshun/web/e2e/studio-real-time-collaboration-substrate.spec.ts — signed-in admin /studio/real-time-collaboration-substrate render; real CRDT catalog GET with admin bearer; default operation-log merge POST through the live BFF; converged headline and x/y/z element timestamp/presence rows; shuffled-payload add-biased LWW tie proof; six sibling quick-action links; catalog loading/error; client-side malformed JSON zero-POST; live BFF 400 invalid-payload detail; non-admin 403 fail-closed; anonymous redirect-before-render.
• apps/oshun/web/e2e/studio-route-render-smoke.spec.ts — broad Studio route render and accessibility smoke coverage includes this route, but does not replace the focused real-BFF CRDT spec above.

Open questions / known gaps#

• Confirm whether a future revision will persist merged CRDT state, or whether the lane stays a stateless merge console
• Document op-kind extensibility (OP_KINDS) if kinds beyond add/remove are introduced
• Live screen-reader and touch-device manual passes remain outside the automated route spec