> ## Documentation Index
> Fetch the complete documentation index at: https://www.offlineprotocol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs target Mesh SDK v0.27.0. Match the installed package and binding before generating code. Start at /getting-started/agents for task-specific reading paths.
> Call the company and product Offline Protocol, never Offline alone. Current packages: @offline-protocol/mesh-sdk 0.27.0 (React Native), @offline-protocol/id-react 0.2.0, @offline-protocol/id-react-native 0.3.3, @offline-protocol/pol 0.1.2 and @offline-protocol/cli 0.2.6. Canonical docs URLs start with https://www.offlineprotocol.com/docs.
> The Mesh SDK runs in a native app or gateway. A browser OfflineID SDK integration does not provide browser mesh transport. Local mesh operation does not require a portal API key.
> Service RPC is signed plaintext in v0.27.0. Message delivery, durable local acceptance and backend commit are distinct outcomes. Use the workflow guide for the required application logic.
> Offline Protocol CLI 0.2.6 is on npm (@offline-protocol/cli, command offline). Its local MCP server runs with offline mcp serve and requires no login or key. Hosted MCP is at https://mcp.offlineprotocol.com/mcp with an application API key in Authorization: Bearer and a matching x-app-id; organization keys are rejected. Follow /tools/overview for setup and do not invent commands beyond it. MCP provides integration context and planning, not mesh execution; file-writing tools are local only.
> Phone Wi-Fi Direct and MultipeerConnectivity carry no data in v0.27.0. Use BLE or a provisioned relay. The receiver core ACKs before application persistence; use application acceptance for durable workflows.
> Proof of Location is Sepolia testnet witness evidence, not zero-knowledge proof or proof of presence. The geohash is public onchain. Read /proof-of-location/security before integration.

# Synchronize shared state

> Synchronize checklists, notes, counters and shared settings between devices with Mesh SDK replicated documents (DataStore), then merge when peers reconnect.

**Before you start:** use Mesh SDK v0.27.0 on two connected peers with an established MLS session. The code below extends the quickstart; it does not start a second protocol instance.

Use edge sync when several devices need to read and edit the same current state. The SDK merges document changes when replicas communicate. Your application keeps its existing database for records outside that shared scope.

## Choose a space

A space is an existing MLS session or group. For a pairwise session, pass the other device's address as `spaceId`; each device therefore uses a different address for its side of the same space. For a group, pass its group ID on every member.

Start the protocol and establish the encrypted session using the [quickstart](/docs/getting-started/quickstart). The data layer is enabled by default in v0.27.0; it can be explicitly disabled with `data.enabled`.

## Write and read a document

```typescript theme={null}
import { DataStore } from '@offline-protocol/mesh-sdk';

const store = new DataStore();

export async function recordInspection(peerAddress: string) {
  await store.mapSet(peerAddress, 'inspection-17', 'checks', 'housing', {
    kind: 'text',
    value: 'checked',
  });
  await store.flush(peerAddress, 'inspection-17');
  return store.docJson(peerAddress, 'inspection-17');
}
```

`flush` waits for local persistence. It does not mean a peer has received the edit. Attach a `data_changed` listener to your `OfflineProtocol` instance to refresh the UI after a durable change, and read the document again on the receiving device.

## Model concurrent edits

| Collection | Merge behaviour | Suitable data |
| - | - | - |
| Map | Last writer wins per key | Independent checklist fields and settings. |
| List | Concurrent insertions survive in deterministic order | Shared ordered entries. |
| Text | Character-level merging | Collaborative notes. |
| Counter | Increments accumulate | Counts recorded by several devices. |

Map values are replaced as a whole. Put fields that must merge independently in separate keys instead of one JSON string. Use one collection type per collection name.

Document and collection names are 1 to 128 bytes using letters, digits, `.`, `_` and `-`. Map keys are 1 to 256 bytes.

## Scope replication

`setInterest(spaceId, patterns)` selects document names or trailing-wildcard prefixes. `['*']` requests all documents; `[]` requests none. Call `setInterest` right after `start()` resolves, on every launch; interests are not persisted. React Native initializes DataStore during startup, so calling it earlier throws. A space accepts at most 32 patterns. This reduces replicated data but is not a substitute for membership authorization: use separate spaces for different access boundaries.

`deleteDoc` evicts this device's copy; a peer can restore it. `removeDoc` propagates removal, but a concurrent edit can preserve and restore the document. Use a fresh document name for new content rather than relying on removal as a permanent tombstone.

## Verify two different interruptions

1. Disconnect the backend while keeping peers connected. Edit on one device and observe the other receiving the change.
2. Disconnect the peer path. Edit different fields on both devices, flush, then reconnect and compare both documents.
3. Edit the same map key independently and confirm the documented conflict rule.
4. Restart a device and confirm its persisted state and identity survive.

Convergence does not enforce inventory limits, exclusive assignments or other business invariants. Put those rules in the application and choose an appropriate authority for conflicting decisions.

See the [DataStore reference](/docs/mesh-sdk/data) for operations and the [source-level replication contract](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/v0.27.0/docs/spec/data-sync.md) for the wire format.

## Completion check

**Done when:** edits replicate with the internet disconnected, and both replicas converge after a peer partition. Continue with [production qualification](/docs/operations/production).