serverpod-offline-sync/docs/shared-spaces.md

Shared spaces

Status: implemented. This records the shared-space behavior built on top of the row-ownership work in row-ownership.md. Revocation cleanup is still a deferred follow-up; where the ownership summary and this document differ, this one wins.

Summary

A user is an authentication identity; a space is the unit of replication and ownership. Each user has a personal space and may also belong to any number of shared spaces. The load-bearing requirement is:

A single sync call syncs every space the authenticated user has access to. One syncOnce cycles through all accessible spaces exactly once; a continuous session keeps cycling forever. There is no separate stream or separate call per space.

The row-ownership work keys storage, locking, HLC chains, visibility, and ownership by space, not user, so sharing is an indirection in front of offline_sync_spaces, not a re-architecture. The implemented pieces are a server-side membership relation and a sync protocol that iterates spaces.

Merges serialize one space at a time. A merge runs in exactly one space's transaction and lock, so spaces always serialize on the merge step regardless of framing. A cycle's outbound changes are instead collected in a single pass over the active spaces and carried in one combined batch, each change tagged with its uuidSpaceId; the receiver regroups by space and merges each group in its own transaction. The wire stays a near-verbatim repetition of today's frames, now space-tagged.

The server is the authority on membership; the client follows. The set of spaces a session syncs is computed server-side from offline_sync_space_members and re-resolved at the start of every sync cycle, so access changes take effect mid-session. The server dictates the set; the client adopts spaces it announces and stops cycling the ones it omits. The reconciliation is directional — not a set operation toggled by a flag — and membership itself is never synced. Local data cleanup for omitted spaces is a separate revocation policy, not part of the sync loop.

Row ownership is unchanged. Every row still has exactly one owning spaceId, (table, uuidRowId) stays globally identified, and every enforcement rule in row-ownership.md survives untouched. Sharing adds a membership layer in front of spaces; it does not touch row ownership.

Goals and constraints

1. One call, every space. The public client API (syncOnce, syncContinuously) does not change shape: callers pass a session, never a space. A device with only a personal space behaves exactly as today.
2. Smallest protocol delta. The exchanged frames are today's, plus a per-cycle space-set exchange and a space tag on each frame. collectNextBatch demultiplexes a cycle's combined batch, collectPendingChanges collects every active space in one pass, and mergeInboundBatch applies each inbound space group while atomically persisting received progress for every author.
3. Chunked streaming. Outbound changes are collected in a single pass over the active spaces and streamed in syncBatchSize chunks, so the wire payload stays bounded regardless of space count. The collection step itself materializes a cycle's pending rows across the active spaces (one spaceId IN (…) query per change kind), so peak memory tracks a cycle's pending rows rather than being held strictly one space at a time. See outbound and rebuild behavior for snapshot guarantees and capture costs.
4. Membership cannot be forged. The server computes its own space set from offline_sync_space_members (plus the implicit personal space) and never widens it from anything the client sends. A space the user is not a member of is never synced, even if the client names it.
5. One space per transaction. Reads are membership-wide; writes stay pinned to exactly one space. This is deliberate honesty about CRDT semantics: two spaces' chains replicate independently and a remote replica can never observe a cross-space write atomically.
6. Roles are closed CRDT access roles. The package stores and projects non-null OfflineSyncSpaceRole values in space grants and shared memberships: readWrite allows CRDT writes and readOnly blocks them. The implicit personal space is announced as a readWrite grant, so single-tenant servers and multi-account devices remain the same code path with different space counts.

Membership

The offline_sync_space_members table

class: OfflineSyncSpaceMember
table: offline_sync_space_members
database: all
fields:
  space: OfflineSyncSpace?, relation(onDelete=Cascade)
  userUuid: UuidValue
  role: OfflineSyncSpaceRole
indexes:
  offline_sync_space_member_unique_idx:
    fields: userUuid, spaceId
    unique: true

• The table is database: all but not in syncTables. It exists on every node so membership resolves with the same code on both ends, but it is never CRDT-replicated by this package. The server is the authoritative writer; a client copy (once populated) is a read-only cache for UI and offline role checks — see The client membership table.
• The index leads with userUuid so the per-cycle WHERE userUuid = ? resolution is index-covered.
• Rows are managed through session.offlineSync.spaces (OfflineSyncSpaces). Invitations, acceptance, and authorization policy remain app domain.
• Personal-space membership is implicit. By convention a user's personal space has the user's own UUID (already true: the space UUID keys the chain), so no offline_sync_space_members row is stored for it. Shared spaces are offline_sync_spaces rows whose UUID is no user's id, with explicit membership rows.
• role is a required CRDT access enum. Shared memberships always store an explicit role: readWrite allows writes, while readOnly denies shared-space writes.

Members vs. nodes

offline_sync_space_members and the nodes list on a space are orthogonal layers and both stay:

• A member is an authorization fact: a user identity allowed to access a space. It answers who may sync, read, and write.
• A node (crdt_nodes) is a stable CRDT replica identity. A space's nodes relation points at offline_sync_space_nodes, which records that replica's participation and checkpoint state in that space. Together they answer whose changes, up to which HLC and are what per-(space, node) checkpoints key on.

They do not map one-to-one and neither replaces the other. One member may have many nodes (one per replica/database install). The server is a node in every space it syncs but is not a member row. A freshly invited member has zero space-node rows until their first device syncs. Nodes and space-node rows are created implicitly by space initialization and inbound merge; membership rows are managed through session.offlineSync.spaces from application endpoints. Removing the nodes list would break checkpointing and causal filtering — it is the chain topology, not the access list.

The client membership table

offline_sync_space_members is database: all, so the table exists on the client and is populated as a read-only projection of the server's authoritative grants — without being bidirectionally CRDT-synced:

• The client's projected offline_sync_space_members rows plus the implicit personal space are its membership view for membership gating: a membership-wide read filters over projected membership, and a local offline_sync_spaces row by itself does not grant access. The members table also carries roles, which the client consults before local writes.
• The authoritative OfflineSyncSpaceSet carries OfflineSyncSpaceGrants — (uuidSpaceId, role) — not bare UUIDs. Every grant has an explicit role; the personal space is announced as readWrite but remains implicit in storage. When the follower receives an announcement, projectFollowerMembership reconciles the local table from it: upsert a row per shared grant (the personal space is skipped), delete rows whose space is no longer granted. Since the authoritative peer announces only when its grants change, projection runs only on change and an idle session writes nothing.
• This is a server-authored, client-read-only projection, never a synced members table: the client never writes membership the server reads, so it cannot self-grant. The server stays the security boundary and re-verifies on sync.
• A revoke takes effect for sync as soon as the server omits the space from a cycle's SpaceSet: the client stops cycling it and discards in-memory checkpoint state for it. The space row and domain rows may remain stored locally until the deferred revocation cleanup policy decides whether to purge or keep them, but membership-wide reads stop returning those rows.
• Writes are bounded by projected membership and by the projected role. They are re-verified by the server on sync, which remains the security boundary. Client-side checks are early-failure UX, not the enforcement point.

Role write access

The package exposes a closed CRDT access role enum rather than free-form role strings:

enum OfflineSyncSpaceRole {
  readOnly,
  readWrite,
}

Only readWrite allows writes. readOnly denies writes. The implicit personal space has no stored membership row, but its authoritative grant and role lookup resolve to readWrite.

Roles gate writes only. Reads stay membership-wide and role-independent. The authoritative server enforces role writes before applying inbound changes: for each accepted inbound space group, it resolves the authenticated user's role from offline_sync_space_members; if the role is not readWrite, the server records OfflineSyncIntegrityViolation(type: unauthorizedWrite) and fails the sync session before opening the merge transaction for that space. The rejected change is not applied and checkpoints do not advance past it.

The client uses the same enum as early UX: transactionForUser(userId, fn, spaceId: sharedSpace) resolves the projected role and throws OfflineSyncSpaceRoleException before any local write when the role cannot write. A follower also omits non-writable shared spaces from outbound pending-change collection while still receiving inbound changes for those spaces. This avoids repeatedly streaming local read-only changes; the server enforcement remains the security boundary for stale, misconfigured, or hostile clients.

Space enumeration (server is the authority)

At the start of each sync cycle the server resolves the authoritative set:

memberGrants(userUuid) =
    { personal space = userUuid, role = readWrite }
  ∪ { (s.uuidSpaceId, m.role)
      : offline_sync_space_members m
        join offline_sync_spaces s on s.id = m.spaceId
        where m.userUuid = <auth user> }

This grant set bounds everything the cycle may sync and carries the role used by followers for outbound filtering. The client never expands it; it only learns of additions through what the server announces.

Sync: one call syncs every accessible space

One sync, two cadences: bounded once, idle-silent continuous

Merge is inherently one space at a time: a merge runs in exactly one space's transaction and lock, so the spaces always serialize regardless of framing. A single sync method serves both syncOnce and syncContinuously, branching on once only where they genuinely differ — read discipline and termination — so there is no duplicated send/merge logic:

1. Establishment (shared, lockstep). After Connect, both peers exchange the SpaceSet. Doing this before the loop is what removes the announce/adopt offset that would otherwise make a follower act before it knows the agreed set.
2. Data loop (shared, idle-silent). Each cycle is one combined batch: the space announcement (only when this peer's grants changed), a SinceHlc for each newly active space, and merge chunks whose changes carry their space, all closed by a single EndOfBatch. Continuous mode omits the terminator when nothing was sent. The receive phase demultiplexes the peer's batch by type until that terminator or — when the peer was idle — an idle timeout. An idle continuous cycle therefore sends nothing and idles out once, regardless of space count.

once stays in the data loop until every active space has exchanged SinceHlc and had one sendable data cycle, then performs the symmetric Close handshake. continuous loops instead, with no per-cycle chatter; it handshakes its initial spaces in the first cycle and absorbs membership changes as they are announced (a newly granted space is announced, adopted, and established over the following cycles — its data deferred until its SinceHlc round-trips).

Protocol frames

Connect opens the session once. After that the frames are the same in both cadences; only when they are sent differs (once: a fixed sequence per space; continuous: only on change, inside one combined batch). Frame changes (regenerated models + a migration on both client and server schemas):

• OfflineSyncConnect { syncTablesHash, localNodeId } — sent once by each peer. The schema hash is validated once, before any space work. localNodeId identifies this peer's CRDT node for the whole session. The space list is dynamic and exchanged per cycle.
• OfflineSyncSpaceSet { spaces: List<OfflineSyncSpaceGrant> } (each grant a uuidSpaceId + role) — the server's content is authoritative (resolved from offline_sync_space_members, roles included). Followers send an empty set because the authoritative peer never widens access from follower-reported state. In once it is exchanged exactly once. In continuous a peer re-announces it only when its own grant set changed since the last announcement — this is the frame that carries access changes mid-session, and gating it on change is what keeps an idle session silent while still letting a grant or revoke take effect.
• OfflineSyncSinceHlc { uuidSpaceId, nodeCheckpoints } — per space. Carries that space's per-node checkpoints. Exchanged when a space first becomes active (and again if a dropped space is later re-adopted); checkpoints then live in memory for the rest of the session.
• OfflineSyncMergeChunk { changes } — each change carries uuidSpaceId, letting a combined batch carry every space's changes and regroup them on receive.
• OfflineSyncEndOfBatch, OfflineSyncClose, OfflineSyncIdleTimeout — unchanged. A single EndOfBatch terminates a cycle's combined batch (and is itself omitted when nothing was sent, so an idle peer resolves to an empty batch instead). Close ends the streaming session. Because it is an intentional peer control frame, it may arrive even after frames for a partial cycle; the receiver discards that partial cycle and records no checkpoint progress for it.

The data cycle's receive uses collectNextBatch, which demultiplexes one cycle's frames by type into { spaceSet?, sinceHlcs, changes }, returning on the single EndOfBatch, on Close with a closed result, or — when the peer was idle — on the idle timeout. A raw transport close without a Close frame is stricter: it is graceful only between continuous-session batches and is treated as truncation once a partial batch has arrived.

The session state machine

handshake (both cadences):
  send Connect(syncTablesHash, localNodeId); read peer Connect; validate
  syncTablesHash; store peer localNodeId

establishment (both cadences, lockstep):
  send SpaceSet(myGrants); read peer SpaceSet → adopt → activeSpaces
  follower: materialize activeSpaces, project membership
data loop (both cadences, one combined batch per cycle):
  loop:
    resolve activeSpaces      (authoritative: my set; follower: adopted peerGrants)
    discard state for spaces no longer active
    # send phase — emit only what changed; track whether any frame was sent
    if myGrants != announcedGrants: send SpaceSet(myGrants)
    for space in activeSpaces not yet sinceHlcSent: send SinceHlc(space)
    if peer checkpoints exist: send MergeChunk(changes)*  # follower skips non-writable spaces
    if anything was sent (or once): send EndOfBatch
    # receive phase
    batch = collectNextBatch(allowCloseBeforeBatch: !once)   # {spaceSet?, sinceHlcs, changes} | idle | closed
    if closed: return
    adopt batch.spaceSet (follower: materialize + project); store sinceHlcs;
      group changes by uuidSpaceId; mergeInboundBatch each group
    if once: send Close; read Close; drain; return
    delay continuousSyncInterval

The shared establishment exchanges the space set so a follower never acts before it knows the agreed set. Both cadences handshake initial and newly added spaces through the loop's own SinceHlc exchange.

collectPendingChanges, mergeInboundBatch, and the ownership-violation internals (_streamInserts/Updates/Deletes, _fetchDomainRow, the durable-violation path) are space-parameterized and merge each inbound space group in its own transactionForUser/lock, including its per-author checkpoints; any space's merge failure (for example an ownership collision or unauthorized role write) records the durable violation and fails the session, preserving today's fail-fast semantics.

Because continuous defers a space's data until both peers have exchanged its SinceHlc, a newly active space is established over the following cycles rather than in lockstep — the deliberate trade for keeping the steady state silent. A peer only honors inbound SinceHlc/MergeChunk frames for spaces it authorizes (authoritative: its own membership; follower: the announced set), so the combined batch tolerates a peer's informational extras without widening access.

onMergeSuccess becomes space-aware: Function(UuidValue spaceUuid, Hlc hlc). This touches three test call sites and the example app's demo_controller.

Space-set reconciliation and lockstep

Both peers must cycle the same ordered space set or send/receive desyncs. Membership is asymmetric — the client trusts the server's membership claims, the server trusts none of the client's — so the reconciliation is directional, not a symmetric set operation:

• Union is wrong (insecure): a client could name a space the user is not a member of and force the server to sync it.
• Intersection is wrong (cannot adopt): a brand-new share is not in the client's set yet, so it would never enter the intersection and never sync — the client cannot hold what it has not synced, and cannot sync what it does not hold.

The correct operation is neither: the server dictates its set; the client conforms. Each cycle:

• Server: orderedSpaces = sort(memberGrants(userUuid).uuidSpaceId), computed from offline_sync_space_members plus the implicit personal grant. It never reads the client's SpaceSet for authority (constraint 4).
• Client: takes the server's SpaceSet as the set to cycle — getOrCreate (OfflineSyncSpaceManager) any space it lacks, ignore any local space the server omitted for this cycle — then orderedSpaces = sort(peer spaceIds).

This asymmetry is expressed by a OfflineSyncPeerMode enum (authoritative / follower) passed at the call site: the server endpoint passes authoritative, the client driver passes follower. Membership is resolved from the same shared offline_sync_space_members table (via OfflineSyncSpaceMembership); the mode varies only the cycle direction — authoritative dictates its own set, follower adopts the peer's. Once the data is unified, a closed enum is the right shape: there is no per-role enumeration callback left to inject. Security does not rest on the enum — a malicious client passing authoritative only fails to adopt the peer's set; writes are still gated server-side by OfflineSyncSpaceMembership.roleOf(...).canWrite against the authoritative table.

In once, the client adopts straight from the cycle's SpaceSet before it iterates, so a newly granted space syncs in that same round. In continuous, adoption happens when the announcement arrives and the space's data follows over the next cycles once its SinceHlc round-trips. Sorting by space UUID makes the order deterministic on both sides with no extra negotiation. Frames carry uuidSpaceId so a receiver groups each chunk into the right space and fails loud on an unauthorized tag rather than merging a batch into the wrong space.

Re-resolving memberGrants every cycle is an indexed offline_sync_space_members lookup on the server only; it may be throttled or invalidated by an application hook if per-cycle querying becomes hot, at the cost of slower propagation of access changes.

Checkpoints, once vs. continuous

Checkpoint rows stay per (space, node) in offline_sync_space_nodes, while crdt_nodes stores the stable replica identity. The same local replica node can participate in multiple spaces, with separate lastReceivedHlc values per space. SinceHlc is exchanged once per space on first visit; later cycles reuse the in-memory nodeCheckpoints[space], advanced as chunks are sent and as inbound batches merge — the multi-space analogue of today's single-space continuous loop, which already keeps checkpoints in memory across rounds.

The continuous interval delay moves to after each full cycle, not after each space, to keep per-space latency low while still preventing a busy loop when idle.

Access changes during a session

Because the authoritative space set is re-resolved every cycle and re-announced whenever it changes (not pinned at Connect), a continuous session absorbs membership changes without reconnecting:

• Grant. The server re-announces a SpaceSet that includes the new space; the client adopts and materializes it, then handshakes and syncs it over the next cycles. (The server detects the grant on its next cycle, so propagation is bounded by one idle poll plus the handshake round-trip.)
• Revoke. The server re-announces a SpaceSet that omits the space; both sides stop cycling it and discard its in-memory checkpoint state, and the follower's projectFollowerMembership deletes its members-table row. The device can still store the revoked space's rows locally, but membership-wide reads no longer return them. Purging stored rows (and the fate of any unsynced local changes) is the deferred revocation question, not a sync-loop concern.
• Demote. The server re-announces the same space with a different role; the follower projection updates the cached role. The next local write consults the new role and fails early if it is read-only. Pending local changes already authored before demotion are not silently applied by the server: if streamed, they are rejected and recorded as unauthorizedWrite. Whether the client purges, surfaces, or keeps skipped pending changes is part of the deferred revocation-cleanup design.

The authoritative peer originates every set change, so both sides converge on the same active set from the same announcement and stay in step across it. A one-shot syncOnce captures the set once; the next syncOnce call picks up any change.

Transaction API

transactionForUser keeps its name and user-first semantics and gains an optional space:

db.transactionForUser(userId, fn);                  // acts in the personal space
db.transactionForUser(userId, fn, spaceId: listId); // acts in a shared space

• Without spaceId, the space resolves to the user's personal space — userId itself by convention — which is exactly today's behavior.
• With spaceId, the package resolves the member role with OfflineSyncSpaceMembership.roleOf — no injected validator. On the server that table is authoritative; on a persistent client it is the server-projected membership cache. A missing role throws OfflineSyncSpaceMembershipException; anything other than readWrite throws OfflineSyncSpaceRoleException before the transaction starts.
• A transaction acts in exactly one space (constraint 5). The write path — stamp-or-assert, the space-scoped WHERE, spaceId immutability — is unchanged beyond which space is resolved.

Read path: membership-wide

A user-space-scoped read in a sharing world means "rows in any space I am a member of". The single-space resolver becomes a set:

• mergeWhereWithTombstone isolates space-scoped reads with spaceId IN (<member space ids>) through OfflineSyncSpaceIdsResolver. For writes, the resolver supplies the single acting space. For reads, both server sessions and persistent clients resolve the set from OfflineSyncSpaceMembership.memberSpaces (authoritative on the server, projected on the client); unscoped admin reads still pass no space filter.
• The visibility probe is the row-keyed form for the multi-space case, so sharing simplifies the predicate matrix rather than growing it: reads differ only in their membership filter (one space, a user's spaces, or none for admin).
• This is the shape of a Postgres row-level-security policy (spaceId IN (SELECT spaceId FROM offline_sync_space_members WHERE userUuid = …)); the package's application-level filter and RLS become two enforcements of one predicate.

Writes stay space-pinned (above); only reads widen.

What sharing does not change

Every enforcement rule in row-ownership.md survives unchanged: (table, uuidRowId) stays globally identified; rows have exactly one owning space; merge-insert ownership checks compare spaces; unique conflict groups form within a space; ordinary global unique indexes stay rejected; stamp-or-assert applies with the transaction's resolved space; the durable offline_sync_integrity_violations contract now also records unauthorized role writes. The merge, FK, and unique engines already key on the space the merge runs in and need no ownership changes for sharing.

Implementation status

The implementation landed in independently green phases. Tests should continue to run with --concurrency=1.

• Phase 1 — membership foundation. Implemented offline_sync_space_members (database: all, unsynced) and its migration. Added the shared OfflineSyncSpaceMembership helpers (memberGrants, memberSpaces, roleOf, isMember, and the follower projection path). No behavior change yet: a personal-space-only set reproduces today's single-space sync exactly.
• Phase 2 — sequential multi-space sync (the requirement). Implemented protocol model changes (Connect with session localNodeId, new per-cycle OfflineSyncSpaceSet, per-space SinceHlc, MergeChunk.uuidSpaceId) plus generate/migrate. Outer cycle loop in OfflineSyncEngine.sync with per-cycle SpaceSet exchange with role-carrying OfflineSyncSpaceGrants, per-space handshake-on-first-visit, in-memory per-space checkpoints, and the once/continuous cadence. Reconciliation via a OfflineSyncPeerMode enum: the server endpoint passes authoritative (cycles OfflineSyncSpaceMembership.memberGrants); the client driver passes follower (adopts the server's set). Space-aware onMergeSuccess. A personal-space-only device behaves identically to today.
• Phase 3 — transaction API. Implemented transactionForUser(userId, fn, {spaceId}) with the membership assertion; one space per transaction.
• Phase 4 — membership-wide reads. Implemented the space-scoped read filter as spaceId IN (…) over the user's member spaces.
• Phase 5 — lifecycle and docs. Documented client adoption of newly announced shares; reconcile with the space-purge semantics in sync-non-sync-relations.md. Revocation cleanup is deferred (see Follow-ups).
• Phase 6 — idle-silent sync, one method. Reworked the single sync method (no separate once/continuous bodies) into a shared lockstep establishment plus a shared combined data loop: each cycle coalesces into one space-scoped-change batch terminated by a single EndOfBatch, with SpaceSet/SinceHlc/MergeChunk sent only on change and read via collectNextBatch. An idle continuous session now sends zero frames and idles out once per cycle regardless of space count (Phase 2's loop re-announced the set and an EndOfBatch per space every tick). once runs one data cycle then closes; mid-session continuous spaces are deferred until their SinceHlc round-trips, and inbound frames are honored only for authorized spaces.
• Phase 7 — roles within a space. Implemented the closed OfflineSyncSpaceRole enum (readOnly, readWrite) on server and client. readWrite is the only shared-space write grant. Added authoritative inbound enforcement that records unauthorizedWrite and fails before merge, client-side OfflineSyncSpaceRoleException early rejection, and follower outbound skipping for non-writable shared spaces while reads remain membership-wide.
• Phase 8 — space management service. Implemented the server-side session.offlineSync.spaces service (create, createFor, grant, grantAll, revoke, members) with transaction/savepoint threading. Single grants reuse the bulk-grant path; unknown-space grants throw OfflineSyncSpaceNotFoundException. Invitations, acceptance, and authorization policy stay in app endpoints.

Test plan

Because no code branches on space count or deployment role, mechanisms are tested once, not per combination.

• Regression. Every existing single-space suite passes unchanged on the personal-space-only path.
• Protocol. Connect/SinceHlc round-trip a multi-space list; merge chunks route to the correct space by uuidSpaceId; per-space checkpoints advance independently across cycles.
• One call, every space. A single syncOnce converges N spaces in one pass; a continuous session keeps cycling. Outbound changes for the active spaces are collected in one pass and streamed in syncBatchSize chunks; the receive groups a cycle's inbound chunks by space before merging each in its own transaction.
• Idle silence. A continuous session with no pending changes settles and then emits no further frames — neither peer re-announces the space set nor sends an EndOfBatch while idle.
• Membership. The server syncs personal + shared spaces; a client-announced non-member space is refused and never streamed; a newly granted space is adopted and syncs within the same syncOnce call.
• Roles. readOnly can still read shared rows, local writes fail before mutation, readWrite syncs normally, a follower skips outbound pending changes for non-writable spaces while still receiving inbound changes, and a stale or hostile client write is rejected and recorded by the server as unauthorizedWrite. Personal spaces remain writable through their implicit readWrite grant.
• Access changes mid-session. During a continuous session, a grant added to offline_sync_space_members appears and syncs on the next cycle; a revoke stops cycling that space without dropping the session.
• Isolation under sharing. Two users sharing space X both converge on X while their personal spaces stay isolated; an ownership collision in one space records a durable violation and fails the session without corrupting another space's merge.
• Smoke. One withServerpod round-trip with one personal plus one shared space, proving the end-to-end wiring (mirrors sync_flow_test.dart).

Resolved during review

• Combined sync batch: merges serialize regardless, so combining spaces is not a throughput optimization. Both cadences use the same combined batch shape: each change carries its uuidSpaceId, and receive groups changes by space before merging each space group. Continuous mode omits idle frames so idle latency is constant in space count.
• Membership authority: the server, from offline_sync_space_members. The reconciliation is directional — server dictates, client conforms — and is neither union (insecure) nor intersection (cannot adopt). It is a OfflineSyncPeerMode enum (authoritative / follower): membership still resolves through OfflineSyncSpaceMembership, so the only residual variation is cycle direction — a closed enum, not a callback. The enum is not the security boundary; server-side OfflineSyncSpaceMembership.roleOf(...).canWrite gates every applied write regardless of the client's declared mode.
• Space set is dynamic, not pinned at connect: the authoritative peer re-resolves its set every cycle and re-announces a SpaceSet whenever it changed, so grants and revokes take effect mid-session without reconnecting. In syncOnce the client adopts from the initial SpaceSet, exchanges SinceHlc, then runs the sendable data cycle; in syncContinuously a newly announced space is adopted then established over the next cycles as its SinceHlc round-trips.
• Members vs. nodes: orthogonal layers, both kept. Members are authorization (who); nodes are CRDT causality (whose changes, up to which HLC). One member maps to many nodes; the server is a node but not a member; a new member has no node until first sync.
• Client membership table: database: all puts the table on the client, populated as a read-only projection. The OfflineSyncSpaceSet carries OfflineSyncSpaceGrants (uuidSpaceId + role), and each follower cycle reconciles the local table from the announcement (upsert granted, delete revoked; only when the set changed). The projected members table drives shared-space membership gating and roles for UI and offline role-gated writes; local offline_sync_spaces rows alone do not grant access. It is a server-authored, client-read-only projection — never a bidirectionally-synced members table, so a client cannot self-grant.
• Iteration order: sorted space UUIDs, so both peers stay in lockstep without negotiation. Each merge change carries its space UUID, so receive can regroup a combined batch deterministically.
• One space per transaction: kept. Cross-space writes need separate transactions; remote replicas cannot observe a cross-space write atomically anyway.
• Membership table is database: all but unsynced: the schema exists on every node, yet it is server-authoritative app state, never CRDT-replicated.
• Idle chatter removed: continuous sync has one combined data loop per cycle. When neither peer has grants, handshakes, or changes to send, it emits no SpaceSet, SinceHlc, MergeChunk, or EndOfBatch; collectNextBatch resolves the idle cycle from the timeout once per session cycle, not once per space.
• Initial-sync ordering is not a current concern: a device joining many spaces cycles them one at a time on first sync. Prioritizing recently active spaces in the iteration order is a compatible refinement if cold-start latency over large space counts ever matters, but it is not a present worry.

Follow-ups

Deferred work needing its own design pass. It does not block the implemented role enforcement above.

1. Membership revocation. When a user loses membership, the server omits the space from the next cycle's SpaceSet and both sides stop syncing it promptly. The device may still store the space's data and unsynced local changes, though membership-wide reads no longer expose revoked rows. Purge-vs-keep policy, and whether revoked or demoted unsynced changes are surfaced, dropped, or kept pending locally, need their own design. (Carried from row-ownership.md open question 3.)