Offline sync

Require sync access

Request the sync operation, then call connection.sync(). The returned transport is the same whether the collection authority is remote, directly connected, or reached through Connect's relay. Add "collection_kind": "hosted" only when the application specifically requires an always-online hosted authority.

Add both packages:@mdbase/connect and @mdbase/connect-sync.

Create a persistent replica

import {
  IndexedDbReplicaStore,
  OfflineReplica,
  type ReplicaData
} from "@mdbase/connect-sync";

const sync = connection.sync();
if (!sync) {
  throw new Error("Authorize the sync operation first.");
}

const initial: ReplicaData<Task> = {
  replicaId: sync.replicaId,
  records: {},
  pending: [],
  conflicts: {}
};

const store = new IndexedDbReplicaStore<Task>(
  `tasks:${sync.collectionId}`,
  initial
);

const replica = new OfflineReplica(sync.transport, store);
await replica.initialize();

The SDK keeps authority credentials and route selection private. The sync package receives only the provider-neutral transport.

Queue optimistic local mutations

const optimistic = await replica.queueCreate({
  path: "tasks/offline.md",
  frontmatter: {
    type: "task",
    title: "Written offline",
    status: "open"
  },
  types: ["task"]
});

render(await replica.records());

// Run now and again when connectivity returns.
await replica.sync();

The replica applies the local overlay immediately and keeps a durable mutation ID. Each record carries a stable record identity independent of its path. Unrelated records continue synchronizing when one record conflicts.

Make conflict resolution explicit

for (const { recordId, receipt } of await replica.conflictEntries()) {
  const choice = await askUserToResolve(receipt.conflict);
  await replica.resolveConflict(recordId, choice); // "local" or "remote"
}

await replica.sync();

Keeping the local version rebases it as a new idempotent mutation against the current authority revision. Keeping the authority version discards only that record's queued mutations. Neither choice silently affects other records.

Filesystem mirrors use the same protocol

mdbase-mirror materializes a remotely authoritative collection as Markdown, either receive-only or writable. On first connection to an existing directory it compares the complete remote snapshot before writing or uploading. Differing paths stop for explicit review.

Move remote authority to a complete local mirror

mdbase-mirror promote ./worklog-mirror

Promotion starts from a converged full writable mirror and opens a short-lived approval in Connect. Approval freezes remote writes at a final sequence. The CLI pulls through that sequence, proves the exact record and resource manifest, registers the folder with the local connector, and then advances the collection authority epoch.

Old remote grants, authority capabilities, and replicas are revoked at cutover. Applications authorize the new local authority explicitly. Cancellation or expiry before completion restores remote writes. The command is resumable after local materialization.