foldkit-sync 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,60 +1,97 @@
1
1
  # `foldkit-sync`
2
2
 
3
- A local-first replica of a shared Foldkit projection. The application's Message
4
- union and `update` stay authoritative; sync wraps them rather than introducing a
5
- second reducer.
3
+ Keeps part of a Foldkit application's Model working offline and converging with
4
+ a server. An edit applies to the local Model immediately, is written to a
5
+ persistent outbox, and is sent to the server when the network allows. The
6
+ server decides the order; every replica replays that order and ends up with the
7
+ same state.
8
+
9
+ The trick is that it is still your application. You declare which Model fields
10
+ replicate and which Messages are durable; the shared codec, the initial
11
+ snapshot, the replay reducer, and the server journal's contract are all derived
12
+ from the `update` you already wrote. There is no second reducer to keep in sync
13
+ with the first.
14
+
15
+ **Use it when** clients must keep working offline, several devices or tabs edit
16
+ the same document, and you have (or can run) a server that orders operations —
17
+ [`foldkit-durable`](https://github.com/doeixd/foldkit-plus/tree/main/packages/durable)
18
+ is one. **Not for** peer-to-peer collaboration: this is server-ordered and
19
+ single-writer-per-document, not a CRDT mesh. Concurrent edits to the same field
20
+ resolve by server arrival order unless you opt that field into the
21
+ [last-writer-wins register](#last-writer-wins-fields-experimental) below, and
22
+ there is no operational transform for collaborative text.
23
+
24
+ It is the **client half** of [replicated Foldkit state](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md);
25
+ the [guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md)
26
+ covers the mental model and when not to use it.
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pnpm add foldkit-sync
32
+ ```
6
33
 
7
- It is the **client half** of [replicated Foldkit state](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md).
8
- Reach for it when clients must keep working offline and converge later, with
9
- `foldkit-durable` (or any server that orders operations) as the authority. The
10
- [guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md) covers the mental model and when not to use
11
- it.
34
+ `foldkit` and `effect` are peer dependencies; `foldkit-surface` comes with it.
35
+ `foldkit-durable` is the server half.
12
36
 
13
37
  ## Quick start
14
38
 
15
39
  `Sync.forApplication` is the Foldkit-facing layer. From one
16
- `Surface.application` and a writable projection it derives the shared schema, the
17
- durable Message subset, the initial snapshot, and replay, and exposes a read-only
18
- Surface over the same projection. The application's `update` stays the only
19
- reducer.
40
+ `Surface.application` and a writable projection it derives the shared schema,
41
+ the durable Message subset, the initial snapshot, and replay, and exposes a
42
+ read-only Surface over the same projection.
20
43
 
21
44
  ```ts
22
45
  import { Schema } from 'effect'
23
46
  import { defineMessageUnion } from 'foldkit/message'
24
- import { Surface } from 'foldkit-surface'
25
- import { documentId, forApplication } from 'foldkit-sync'
47
+ import type * as Update from 'foldkit/update'
48
+ import { MessageSet, Projection, Surface } from 'foldkit-surface'
49
+ import { DocumentId, Sync } from 'foldkit-sync'
26
50
 
27
51
  const Model = Schema.Struct({
28
52
  todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
29
53
  selectedTodoId: Schema.NullOr(Schema.String),
54
+ lastError: Schema.NullOr(Schema.String),
30
55
  })
56
+ type Model = typeof Model.Type
57
+
31
58
  const Message = defineMessageUnion({
32
59
  CreatedTodo: { id: Schema.String, title: Schema.String },
33
60
  RenamedTodo: { id: Schema.String, title: Schema.String },
34
61
  SelectedTodo: { id: Schema.String },
35
62
  })
36
-
37
- // `update` is the application's ordinary transition.
38
- const App = Surface.application({
39
- Model,
40
- Message,
41
- initial: { todos: [], selectedTodoId: null },
42
- update,
43
- })
44
-
45
- const Todos = Projection.pick(App.fields.todos)
46
- const TodoChanges = MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo])
47
-
48
- const TodoSync = forApplication(App).make({
49
- documentId: documentId('todos'),
50
- shared: Todos, // the shared codec, read, and write
51
- durable: TodoChanges, // the durable subset
63
+ type Message = typeof Message.Type
64
+
65
+ const initial: Model = { todos: [], selectedTodoId: null, lastError: null }
66
+
67
+ type Return = Update.Return<Model, Message>
68
+ // The application's ordinary transition. Sync does not add a second one.
69
+ const update = (model: Model, message: Message): Return =>
70
+ Message.match<Return>(message, {
71
+ CreatedTodo: ({ id, title }) => ({
72
+ model: { ...model, todos: [...model.todos, { id, title }] },
73
+ }),
74
+ RenamedTodo: ({ id, title }) => ({
75
+ model: {
76
+ ...model,
77
+ todos: model.todos.map(todo => (todo.id === id ? { ...todo, title } : todo)),
78
+ },
79
+ }),
80
+ SelectedTodo: ({ id }) => ({ model: { ...model, selectedTodoId: id } }),
81
+ })
82
+
83
+ const App = Surface.application({ Model, Message, initial, update })
84
+
85
+ const TodoSync = Sync.forApplication(App).make({
86
+ documentId: DocumentId.make('todos'),
87
+ shared: Projection.pick(App.fields.todos), // the codec, read, and write
88
+ durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
52
89
  })
53
90
  ```
54
91
 
55
- Only `todos` is replicated; `selectedTodoId` stays local. The derived `replay`
56
- installs the shared slice into the application's initial Model, applies the
57
- durable Message through `update`, and reads the shared slice back.
92
+ Only `todos` is replicated; `selectedTodoId` and `lastError` stay local. The
93
+ derived `replay` installs the shared slice into the application's initial Model,
94
+ applies the durable Message through `update`, and reads the shared slice back.
58
95
 
59
96
  A durable Message must therefore be a deterministic, state-only transition of
60
97
  the shared projection. Replay refuses one whose `update` returns a Command (a
@@ -69,14 +106,22 @@ On the server, the same contract produces the journal's codecs and reducer, so
69
106
  neither is written twice:
70
107
 
71
108
  ```ts
72
- import { makeJournal } from 'foldkit-durable'
73
-
74
- const journal = yield* makeJournal({
75
- ...TodoSync.journalContract(), // operation/snapshot codecs, empty, reduce
76
- file: 'todos.sqlite',
77
- opId: operation => operation.opId,
78
- actorId: principal => principal.actorId,
79
- })
109
+ import { Effect } from 'effect'
110
+ import { actorId, documentId, makeJournal, opId } from 'foldkit-durable'
111
+
112
+ type Principal = { readonly actorId: string }
113
+
114
+ const server = Effect.gen(function* () {
115
+ const journal = yield* makeJournal({
116
+ // Operation and snapshot codecs, `empty`, `reduce`, and `authorize` if declared.
117
+ ...TodoSync.journalContract(),
118
+ file: 'todos.sqlite',
119
+ // The two packages brand their ids separately, so re-brand at the seam.
120
+ opId: operation => opId(operation.opId),
121
+ actorId: (principal: Principal) => actorId(principal.actorId),
122
+ })
123
+ return yield* journal.load(documentId('todos'))
124
+ }).pipe(Effect.scoped)
80
125
  ```
81
126
 
82
127
  ### Mounting
@@ -87,47 +132,75 @@ persisted afterwards in a Command; the shared slice is re-installed from the
87
132
  replica when an exchange or a rejection changes it, or when a persist fails.
88
133
 
89
134
  ```ts
90
- const replica = yield* TodoSync.openReplica(replicaId('tab-1'), yield* indexedDb('todos'))
91
- const mounted = mount(App, TodoSync, {
135
+ import { Effect, Scope } from 'effect'
136
+ import { ReplicaId, Sync } from 'foldkit-sync'
137
+
138
+ const container = document.getElementById('app')! // Foldkit needs the element to have an id
139
+
140
+ const scope = Effect.runSync(Scope.make())
141
+ const storage = Effect.runSync(
142
+ Effect.provideService(Sync.indexedDb('todos/tab-1'), Scope.Scope, scope),
143
+ )
144
+ const replica = Effect.runSync(TodoSync.openReplica(ReplicaId.make('tab-1'), storage))
145
+
146
+ const mounted = Sync.mount(App, TodoSync, {
92
147
  replica,
93
- container: document.getElementById('app')!, // Foldkit needs the id
94
- view: (model, h) => ({ title: 'Todos', body: h.ul([], model.todos.map(todo => h.li([], [todo.title]))) }),
148
+ container,
149
+ view: (model, h) => ({
150
+ title: 'Todos',
151
+ body: h.ul(
152
+ [],
153
+ model.todos.map(todo => h.li([], [todo.title])),
154
+ ),
155
+ }),
95
156
  onPersistenceFailure: (model, error) => ({ ...model, lastError: error.message }),
96
157
  })
97
- mounted.dispatch(Message.CreatedTodo({ id, title: 'Milk' }))
158
+
159
+ // The exchange loop: once, then after every submit, retrying a failed exchange.
160
+ Effect.runFork(
161
+ Effect.provide(replica.start, Sync.transport.socket({ url: 'wss://example.com/sync' })),
162
+ )
163
+
164
+ mounted.dispatch(Message.CreatedTodo({ id: crypto.randomUUID(), title: 'Milk' }))
98
165
  mounted.model() // the Model after the last transition
99
166
  await mounted.dispose() // waits for in-flight persists; the replica stays open
100
167
  ```
101
168
 
102
- `url` routes the URL through the application: `init(model, url)` reduces it
103
- into the Model before the first render, `onUrlChange(url)` names the Message
104
- for every navigation, and `onUrlRequest` the Message for a link click (omitted,
105
- the mount follows the link: an internal one pushed, an external one loaded).
106
- A `foldkit-mirror` URL mirror plugs in as `url: { init: (model, url) =>
107
- Filters.reduce(model, url), onUrlChange: url => Message.UrlChanged({ url }) }`;
169
+ The optional `url` option routes the URL through the application:
170
+ `init(model, url)` reduces it into the Model before the first render,
171
+ `onUrlChange(url)` names the Message for every navigation, and `onUrlRequest`
172
+ the Message for a link click (omitted, the mount follows the link itself: an
173
+ internal one pushed, an external one loaded). A `foldkit-mirror` URL mirror
174
+ plugs in there as
175
+ `url: { init: (model, url) => Filters.reduce(model, url), onUrlChange: url => Message.UrlChanged({ url }) }`;
108
176
  `subscriptions` and `resources` carry its write entry and the store layer.
109
177
 
110
178
  `mounted.model`, `mounted.dispatch`, `mounted.subscribe`, and `mounted.observe`
111
179
  are the host an agent binds to; `observe` reports every application Message the
112
180
  runtime applies, which a capability with a `completion` contract needs. See
113
- [docs/sync-runtime-binding.md](../../docs/sync-runtime-binding.md) for what the
181
+ [docs/sync-runtime-binding.md](https://github.com/doeixd/foldkit-plus/blob/main/docs/sync-runtime-binding.md) for what the
114
182
  mount guarantees and why no Foldkit change is required.
115
183
 
116
184
  ### Fragments
117
185
 
118
- A large application declares one fragment per feature and composes them:
186
+ A large application declares one fragment per feature and composes them. `App`
187
+ below is a wider application than the quick start's: it also has a `members`
188
+ field and an `Invited` Message.
119
189
 
120
190
  ```ts
121
- const Sync = forApplication(App)
122
- const Todos = Sync.fragment({
191
+ const AppSync = Sync.forApplication(App)
192
+ const Todos = AppSync.fragment({
123
193
  shared: Projection.pick(App.fields.todos),
124
194
  durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
125
195
  })
126
- const Members = Sync.fragment({
196
+ const Members = AppSync.fragment({
127
197
  shared: Projection.pick(App.fields.members),
128
198
  durable: MessageSet.make(App, [Message.Invited]),
129
199
  })
130
- const Board = Sync.make({ documentId: documentId('board'), ...Sync.compose(Todos, Members) })
200
+ const Board = AppSync.make({
201
+ documentId: DocumentId.make('board'),
202
+ ...AppSync.compose(Todos, Members),
203
+ })
131
204
  ```
132
205
 
133
206
  `compose` merges the shared projections and the durable subsets and infers the
@@ -138,52 +211,59 @@ over the same field are a different mistake, which `Module.validate` reports.
138
211
  ### Authorization
139
212
 
140
213
  Policy attaches to the contract per durable variant and compiles into the
141
- journal contract, so the server applies it with no glue:
214
+ journal contract, so the server applies it with no glue. This is the same
215
+ `Board` as above, with a principal fixed and one rule added:
142
216
 
143
217
  ```ts
144
- const Sync = forApplication(App).withPrincipal<{ readonly role: 'admin' | 'guest' }>()
145
- const Board = Sync.make({
146
- documentId: documentId('board'),
147
- ...Sync.compose(Todos, Members),
218
+ const Authorized = Sync.forApplication(App).withPrincipal<{ readonly role: 'admin' | 'guest' }>()
219
+ const Board = Authorized.make({
220
+ documentId: DocumentId.make('board'),
221
+ ...Authorized.compose(Todos, Members),
148
222
  authorize: {
149
223
  // `message` is exactly `RenamedTodo`; `shared` is the authoritative snapshot.
150
224
  RenamedTodo: ({ principal, message, shared }) =>
151
225
  principal.role === 'admin' && shared.todos.some(todo => todo.id === message.id),
152
226
  },
153
227
  })
154
-
155
- const journal = yield* makeJournal({ ...Board.journalContract(), file, opId, actorId })
156
228
  ```
157
229
 
158
- A durable variant without a rule is allowed; a key that is not a durable tag is
159
- a compile error. The rule runs inside the append transaction against the
160
- snapshot, so keep it synchronous and local. The client does not run it: a
161
- replica has no principal, and a refused operation comes back as a rejection.
230
+ `Board.journalContract()` then carries the compiled rules in the shape
231
+ `makeJournal` takes. A durable variant without a rule is allowed; a key that is
232
+ not a durable tag is a compile error. The rule runs inside the append
233
+ transaction against the snapshot, so keep it synchronous and local. The client
234
+ does not run it: a replica has no principal, and a refused operation comes back
235
+ as a rejection.
162
236
 
163
237
  ### Lower level
164
238
 
165
- `Sync.forApplication(App).make` compiles down to `defineSync`, the protocol
166
- primitive. Use `defineSync` directly when there is no Foldkit application to
239
+ `Sync.forApplication(App).make` compiles down to `Sync.define`, the protocol
240
+ primitive. Use `Sync.define` directly when there is no Foldkit application to
167
241
  derive the contract from — a non-Foldkit client, or a hand-written projection.
168
242
 
169
243
  ```ts
170
- import { Effect } from 'effect'
171
- import { defineSync, indexedDb, layerFromPromise, replicaId } from 'foldkit-sync'
172
-
173
- const Sync = defineSync({ ... })
174
-
175
- const replica = await Effect.runPromise(
176
- Effect.gen(function* () {
177
- const storage = yield* indexedDb('todos-tab-1')
178
- return yield* Sync.openReplica(replicaId('tab-1'), storage)
179
- }),
180
- )
181
- await Effect.runPromise(
182
- replica.submit(Message.CreatedTodo({ id: crypto.randomUUID(), title: 'Milk' })),
183
- )
184
- await Effect.runPromise(Effect.provide(replica.synchronize, layerFromPromise(transport)))
244
+ import { Effect, Schema } from 'effect'
245
+ import { DocumentId, ReplicaId, Sync, type TransportClient } from 'foldkit-sync'
246
+
247
+ const Shared = Schema.Struct({ todos: Schema.Array(Schema.String) })
248
+ const Renamed = Schema.Struct({ _tag: Schema.Literal('Renamed'), title: Schema.String })
249
+ declare const transport: TransportClient // the application's own server client
250
+
251
+ const Protocol = Sync.define({
252
+ documentId: DocumentId.make('todos'),
253
+ message: Renamed,
254
+ shared: Shared,
255
+ empty: { todos: [] },
256
+ durable: () => true,
257
+ replay: (shared, message) => ({ todos: [...shared.todos, message.title] }),
258
+ })
185
259
 
186
- const shared = Effect.runSync(replica.shared)
260
+ const program = Effect.gen(function* () {
261
+ const storage = yield* Sync.indexedDb('todos-tab-1')
262
+ const replica = yield* Protocol.openReplica(ReplicaId.make('tab-1'), storage)
263
+ yield* replica.submit({ _tag: 'Renamed', title: 'Milk' })
264
+ yield* Effect.provide(replica.synchronize, Sync.transport.fromPromise(transport))
265
+ return yield* replica.shared
266
+ }).pipe(Effect.scoped)
187
267
  ```
188
268
 
189
269
  ## What it owns
@@ -194,10 +274,9 @@ const shared = Effect.runSync(replica.shared)
194
274
  declared twice. `Projection.pick`/`Projection.compose` build the writable projection;
195
275
  `TodoSync.journalContract()` builds the durable codecs and reducer.
196
276
  - The operation envelope: `replicaId:localSequence` identity, `baseCursor`, and
197
- protocol/schema versions. The wire codecs live under `Sync.codec`
198
- (`normalizeOperation`, `operationFrom`, `committedFrom`, `decodeExchange`) for a
199
- custom transport or server; a server-committed operation is a
200
- `CommittedOperation`.
277
+ protocol/schema versions. The contract's `codec` (`normalizeOperation`,
278
+ `operationFrom`, `committedFrom`, `decodeExchange`) is there for a custom
279
+ transport or server; a server-committed operation is a `CommittedOperation`.
201
280
  - A persisted outbox and optimistic projection: a durable Message is visible
202
281
  immediately and rebased onto the authoritative order.
203
282
  - Reconciliation: committed operations are replayed in order, acknowledged or
@@ -216,23 +295,23 @@ const shared = Effect.runSync(replica.shared)
216
295
  - Branded positions: `Sequence` (a committed document position) and
217
296
  `LocalSequence` (a replica's own 1-based counter) cannot be confused, so a
218
297
  client counter is never passed where a committed position is expected.
219
- - Presence (`createPresence`): an ephemeral, TTL'd peer registry, deliberately
220
- outside the durable log. A peer that stops refreshing is dropped, not
298
+ - Presence (`Sync.presence.make`): an ephemeral, TTL'd peer registry,
299
+ deliberately outside the durable log. A peer that stops refreshing is dropped, not
221
300
  replayed. It is an Effect driven by the `Clock` (so a `TestClock` makes the
222
301
  TTL deterministic), peers live in a `Ref`, and the channel is a `PubSub`.
223
302
  Every value is decoded through the required `decodeValue` before it is stored,
224
303
  so a hostile peer cannot inject a value your `Update` type does not describe.
225
- Presence can travel over a socket — `socketPresenceChannel` on the client and
226
- `servePresence` fanning through a `createPresenceHub` on the server — or
227
- in-process via `loopbackPresenceChannel`. `presence.changes` is a `Stream` that
228
- emits the current peers and re-emits them on every change, alongside the
229
- `subscribe` callback.
304
+ Presence can travel over a socket — `Sync.presence.socketChannel` on the
305
+ client and `Sync.presence.serve` fanning through a `Sync.presence.hub` on the
306
+ server — or in-process via `Sync.presence.loopbackChannel`.
307
+ `presence.changes` is a `Stream` that emits the current peers and re-emits
308
+ them on every change, alongside the `subscribe` callback.
230
309
  - The transport seam (`Transport`): an Effect service with a loopback layer, a
231
310
  bridge to and from the promise client the replica speaks, and a WebSocket
232
311
  client layer. The socket reconnects on an exponential, jittered backoff and
233
312
  re-sends queued and in-flight frames with their original ids, so a lost reply
234
313
  is answered rather than dropped; retries (`maxRetries`) and the queue
235
- (`maxQueue`) are bounded, and `serveSocket` is the server side of a
314
+ (`maxQueue`) are bounded, and `Sync.transport.serve` is the server side of a
236
315
  connection. A refusal is an exchange result; only a wire failure is a
237
316
  `TransportError`.
238
317
 
@@ -246,17 +325,17 @@ const shared = Effect.runSync(replica.shared)
246
325
  server is left to the application; the sync example shows a `ws` one for the
247
326
  transport (presence over `ws` is not wired there yet).
248
327
 
249
- ## Last-writer-wins fields (M8, experimental)
328
+ ## Last-writer-wins fields (experimental)
250
329
 
251
- Use `lwwRegister` when a field's winner should depend on a write's logical time
252
- instead of the order offline clients reconnect. It returns a schema and a pure
330
+ Use `Sync.lww.register` when a field's winner should depend on a write's
331
+ logical time instead of the order offline clients reconnect. It returns a schema and a pure
253
332
  `merge` function to call inside the application's existing `update`:
254
333
 
255
334
  ```ts
256
335
  import { Schema } from 'effect'
257
- import { lwwRegister } from 'foldkit-sync'
336
+ import { ReplicaId, Sync } from 'foldkit-sync'
258
337
 
259
- const Title = lwwRegister(Schema.String)
338
+ const Title = Sync.lww.register(Schema.String)
260
339
  const Shared = Schema.Struct({ title: Title.schema })
261
340
  const Renamed = Schema.Struct({ _tag: Schema.Literal('Renamed'), title: Title.schema })
262
341
 
@@ -267,7 +346,7 @@ const update = (model: typeof Shared.Type, message: typeof Renamed.Type) => ({
267
346
 
268
347
  const message: typeof Renamed.Type = {
269
348
  _tag: 'Renamed',
270
- title: { stamp: { counter: 1, replicaId: 'tab-a' }, value: 'Milk' },
349
+ title: { stamp: { counter: 1, replicaId: ReplicaId.make('tab-a') }, value: 'Milk' },
271
350
  }
272
351
  ```
273
352
 
@@ -276,44 +355,44 @@ order, independent of locale. This is logical ordering, not wall-clock time.
276
355
  The rule follows the total-order register model described in
277
356
  [Replicated Data Types: Specification, Verification, Optimality](https://www.microsoft.com/en-us/research/publication/replicated-data-types-specification-verification-optimality/).
278
357
 
279
- Allocate stamps **before dispatch**, never in `update` or replay. `openLwwClock`
280
- persists a counter independently of the outbox, so a rejected or unsubmitted
281
- write cannot cause timestamp reuse after reload:
358
+ Allocate stamps **before dispatch**, never in `update` or replay.
359
+ `Sync.lww.openClock` persists a counter independently of the outbox, so a
360
+ rejected or unsubmitted write cannot cause timestamp reuse after reload:
282
361
 
283
362
  ```ts
284
363
  import { Effect } from 'effect'
285
- import { indexedDb, openLwwClock } from 'foldkit-sync'
364
+ import { DocumentId, ReplicaId, Sync, type Replica } from 'foldkit-sync'
286
365
 
287
- const clock = await Effect.runPromise(
366
+ type Shared = typeof Shared.Type
367
+ type Renamed = typeof Renamed.Type
368
+
369
+ const rename = (replica: Replica<Renamed, Shared>, title: string) =>
288
370
  Effect.gen(function* () {
289
- const storage = yield* indexedDb('todos-tab-a-clock')
290
- return yield* openLwwClock({ documentId: 'todos', replicaId: 'tab-a', storage })
291
- }),
292
- )
293
- try {
294
- const stamp = await Effect.runPromise(
295
- clock.next(Effect.runSync(replica.shared).title.stamp.counter),
296
- )
297
- await Effect.runPromise(
298
- replica.submit({ _tag: 'Renamed', title: { stamp, value: 'Milk' } }),
299
- )
300
- } finally {
301
- await Effect.runPromise(clock.close)
302
- }
371
+ // A separate database from the replica's outbox; one clock per document/writer.
372
+ const storage = yield* Sync.indexedDb('todos-tab-a-clock')
373
+ const clock = yield* Sync.lww.openClock({
374
+ documentId: DocumentId.make('todos'),
375
+ replicaId: ReplicaId.make('tab-a'),
376
+ storage,
377
+ })
378
+ const shared = yield* replica.shared
379
+ const stamp = yield* clock.next(shared.title.stamp.counter)
380
+ yield* replica.submit({ _tag: 'Renamed', title: { stamp, value: title } })
381
+ yield* clock.close
382
+ }).pipe(Effect.scoped)
303
383
  ```
304
384
 
305
- Use a **separate database** from the replica's outbox, with one clock per
306
- document/writer. `next(observedCounter)` returns only after persisting a counter
307
- greater than both its saved value and the supplied observation. Pass the latest
308
- observed counter for the field being edited; when causality spans several
309
- registers, pass their maximum. Calling `next()` without an observation advances
310
- only the saved local counter. The clock does not inspect application state.
385
+ `next(observedCounter)` returns only after persisting a counter greater than
386
+ both its saved value and the supplied observation. Pass the latest observed
387
+ counter for the field being edited; when causality spans several registers, pass
388
+ their maximum. Calling `next()` without an observation advances only the saved
389
+ local counter. The clock does not inspect application state.
311
390
 
312
391
  Allocations on one handle are serialized. Separate handles use storage's
313
392
  compare-and-swap check; a stale handle fails and must be closed and reopened.
314
393
  Storage failures reject allocation without returning a stamp. Counter gaps after
315
394
  a crash or failed submission are harmless. Counters are nonnegative safe
316
- integers; exhaustion fails before writing. `close()` waits for accepted
395
+ integers; exhaustion fails before writing. `close` waits for accepted
317
396
  allocations and refuses new ones. Opening takes ownership of storage and closes
318
397
  it on initialization failure too.
319
398
 
@@ -330,9 +409,9 @@ boundaries. Transforming value codecs retain both their encoded and decoded
330
409
  types.
331
410
 
332
411
  Keep the **whole register**, including the winning stamp, in shared snapshots.
333
- For deletion, `lwwRegister(Schema.NullOr(Entity))` can retain a `null` tombstone:
334
- dropping its stamp would allow an old offline write to resurrect the value.
335
- A newer write may intentionally replace that tombstone.
412
+ For deletion, `Sync.lww.register(Schema.NullOr(Entity))` can retain a `null`
413
+ tombstone: dropping its stamp would allow an old offline write to resurrect the
414
+ value. A newer write may intentionally replace that tombstone.
336
415
 
337
416
  The journal still orders and authorizes every operation, including losing writes.
338
417
  Replica ids and counters in Messages are client-authored data, not authenticated
@@ -340,6 +419,36 @@ identity. Applications must enforce writer ownership and clock policy at admissi
340
419
  where needed. A losing write can still trigger a Command if the application's
341
420
  update produces one; this helper only resolves state.
342
421
 
343
- These M8 helpers do not change the todo example's persisted schema or claim
344
- arbitrary Messages commute. Specialized sets, counters and collaborative text
345
- remain future work.
422
+ These helpers do not claim arbitrary Messages commute. Specialized sets,
423
+ counters, and collaborative text remain future work.
424
+
425
+ ## Older spellings
426
+
427
+ `Sync` groups this package's exports; it does not wrap them. Every name is still
428
+ exported on its own with the same signature, so code written against the older
429
+ spellings keeps working:
430
+
431
+ - `forApplication`, `mount`, `indexedDb` — same names on the namespace.
432
+ - `defineSync` is `Sync.define`; `syncMetrics` is `Sync.metrics`.
433
+ - `layerSocket`, `layerLoopback`, `layerFromPromise`, `toPromise`, `serveSocket`
434
+ and `nativeSocket` are `Sync.transport.socket`, `.loopback`, `.fromPromise`,
435
+ `.toPromise`, `.serve` and `.nativeSocket`.
436
+ - `createPresence`, `createPresenceHub`, `servePresence`,
437
+ `socketPresenceChannel` and `loopbackPresenceChannel` are
438
+ `Sync.presence.make`, `.hub`, `.serve`, `.socketChannel` and
439
+ `.loopbackChannel`.
440
+ - `lwwRegister` and `openLwwClock` are `Sync.lww.register` and
441
+ `Sync.lww.openClock`.
442
+ - `documentId('todos')` and `DocumentId.make('todos')` return the same value,
443
+ and likewise for `replicaId`, `opId`, `sequence` and `localSequence`.
444
+
445
+ ## See also
446
+
447
+ - [Replicated state](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md) — the mental model, and
448
+ when not to use it.
449
+ - [Runtime binding](https://github.com/doeixd/foldkit-plus/blob/main/docs/sync-runtime-binding.md) — what
450
+ `Sync.mount` guarantees, and why no Foldkit change is required.
451
+ - [`foldkit-durable`](https://github.com/doeixd/foldkit-plus/tree/main/packages/durable) — the server half; [`foldkit-mirror`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mirror) plugs into the mount's
452
+ `url` option.
453
+ - [`examples/todo-app`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo-app) — two fragments, owner-only rules, and a browser mount;
454
+ [`examples/sync`](https://github.com/doeixd/foldkit-plus/tree/main/examples/sync) is the in-process trace.