foldkit-sync 0.2.0 → 0.3.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/dist/index.mjs CHANGED
@@ -1,4 +1,10 @@
1
- import { Clock, Context, Duration, Effect, Exit, Fiber, Layer, Metric, PubSub, Ref, Schedule, Schema, Stream, SynchronizedRef } from "effect";
1
+ import { Clock, Context, Duration, Effect, Exit, Fiber, Layer, Metric, PubSub, Queue, Ref, Schedule, Schema, Stream, SynchronizedRef } from "effect";
2
+ import * as Navigation from "foldkit/navigation";
3
+ import * as Port from "foldkit/port";
4
+ import * as Runtime from "foldkit/runtime";
5
+ import * as Subscription from "foldkit/subscription";
6
+ import * as Url from "foldkit/url";
7
+ import { MessageSet, Projection, Surface } from "foldkit-surface";
2
8
  //#region src/errors.ts
3
9
  /** The persisted storage could not be read or written. */
4
10
  var StorageError = class extends Schema.TaggedError()("StorageError", {
@@ -21,6 +27,11 @@ var InvalidReplicaHistoryError = class extends Schema.TaggedError()("InvalidRepl
21
27
  message: Schema.String,
22
28
  cause: Schema.optional(Schema.Unknown)
23
29
  }) {};
30
+ /** The server's exchange response did not match the protocol schema. */
31
+ var InvalidExchangeError = class extends Schema.TaggedError()("InvalidExchangeError", {
32
+ message: Schema.String,
33
+ cause: Schema.optional(Schema.Unknown)
34
+ }) {};
24
35
  /** A persisted pending operation could not have been produced by this replica. */
25
36
  var InvalidOutboxError = class extends Schema.TaggedError()("InvalidOutboxError", { message: Schema.String }) {};
26
37
  /** The server sent a checkpoint older than the replica's cursor. */
@@ -40,6 +51,15 @@ var ForeignRejectionError = class extends Schema.TaggedError()("ForeignRejection
40
51
  opId: Schema.String,
41
52
  message: Schema.String
42
53
  }) {};
54
+ /**
55
+ * The server answered an operation this request never sent, or both
56
+ * acknowledged and rejected it. Acting on either would let a faulty or hostile
57
+ * server delete local work.
58
+ */
59
+ var ForeignAcknowledgementError = class extends Schema.TaggedError()("ForeignAcknowledgementError", {
60
+ opId: Schema.String,
61
+ message: Schema.String
62
+ }) {};
43
63
  /** The replica was closed while work was still being submitted. */
44
64
  var ReplicaClosedError = class extends Schema.TaggedError()("ReplicaClosedError", { message: Schema.String }) {};
45
65
  /** The stored replica state targets a protocol or schema version this build does not support. */
@@ -48,6 +68,14 @@ var UnsupportedReplicaVersionError = class extends Schema.TaggedError()("Unsuppo
48
68
  schemaVersion: Schema.NullOr(Schema.Number),
49
69
  message: Schema.String
50
70
  }) {};
71
+ /**
72
+ * `replay` threw for a submitted Message, so it could never be applied here or
73
+ * on any other replica; nothing was written.
74
+ */
75
+ var ReplayError = class extends Schema.TaggedError()("ReplayError", {
76
+ message: Schema.String,
77
+ cause: Schema.optional(Schema.Unknown)
78
+ }) {};
51
79
  //#endregion
52
80
  //#region src/indexedDb.ts
53
81
  const storageError = (message, cause) => new StorageError({
@@ -65,8 +93,8 @@ const openDatabase = (name, factory) => Effect.tryPromise({
65
93
  catch: (cause) => storageError("Could not open the storage", cause)
66
94
  });
67
95
  /** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
68
- const indexedDb = (name, factory = globalThis.indexedDB) => Effect.gen(function* () {
69
- const databaseName = typeof name === "string" ? name : yield* name.pipe(Effect.mapError((cause) => storageError("Could not read the storage name", cause)));
96
+ const indexedDb = Effect.fn("Storage.indexedDb")(function* (name, factory = globalThis.indexedDB) {
97
+ const databaseName = typeof name === "string" ? name : yield* name.pipe(Effect.catchTag("ConfigError", (cause) => Effect.fail(storageError("Could not read the storage name", cause))));
70
98
  const database = yield* Effect.acquireRelease(openDatabase(databaseName, factory), (database) => Effect.sync(() => database.close()));
71
99
  database.onversionchange = () => database.close();
72
100
  return {
@@ -102,300 +130,161 @@ const indexedDb = (name, factory = globalThis.indexedDB) => Effect.gen(function*
102
130
  };
103
131
  });
104
132
  //#endregion
105
- //#region src/ids.ts
106
- /** Identifies the replicated document a replica or operation belongs to. */
107
- const DocumentId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/DocumentId"));
108
- /** Identifies one replica (writer identity) within a document. */
109
- const ReplicaId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/ReplicaId"));
110
- /** The stable identity of one operation within a document. */
111
- const OpId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/OpId"));
112
- const documentId = (value) => Schema.decodeUnknownSync(DocumentId)(value);
113
- const replicaId = (value) => Schema.decodeUnknownSync(ReplicaId)(value);
114
- const opId = (value) => Schema.decodeUnknownSync(OpId)(value);
115
- //#endregion
116
- //#region src/lww.ts
117
- /** A logical write time; replica ids break concurrent ties using UTF-16 order. */
118
- const Stamp = Schema.Struct({
119
- counter: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)),
120
- replicaId: ReplicaId
121
- });
122
- /** The persisted clock format. A bump must handle the older value explicitly. */
123
- const CLOCK_SCHEMA_VERSION = 1;
124
- const ClockState = Schema.Struct({
125
- schemaVersion: Schema.Literal(CLOCK_SCHEMA_VERSION),
126
- documentId: DocumentId,
127
- replicaId: ReplicaId,
128
- revision: Stamp.fields.counter
129
- });
130
- const decodeClock = Schema.decodeUnknownSync(ClockState, { onExcessProperty: "error" });
131
- const decodeCounter = Schema.decodeUnknownSync(Stamp.fields.counter);
132
- const clockError = (message, cause) => new StorageError({
133
- message: `${message}: ${cause instanceof Error ? cause.message : String(cause)}`,
134
- cause
135
- });
136
- const VersionProbe = Schema.Struct({ schemaVersion: Schema.optional(Schema.Number) });
137
- /**
138
- * Tells a version this build does not understand apart from malformed data, so
139
- * the caller gets an actionable failure and the stored state is preserved.
140
- */
141
- const unsupportedVersion = (input) => {
142
- let found;
143
- try {
144
- found = Schema.decodeUnknownSync(VersionProbe)(input);
145
- } catch {
146
- return;
147
- }
148
- if (found.schemaVersion === CLOCK_SCHEMA_VERSION) return void 0;
149
- return new UnsupportedClockVersionError({
150
- schemaVersion: found.schemaVersion ?? null,
151
- message: `Stored clock uses schema ${found.schemaVersion ?? "?"}; this build supports ${CLOCK_SCHEMA_VERSION}`
152
- });
153
- };
154
- /**
155
- * Opens a durable clock over the caller's storage.
156
- *
157
- * Allocations are serialized through a `SynchronizedRef` and each persists before
158
- * its stamp is returned. A crash after the save may skip a timestamp but never
159
- * reuse one. Storage is owned by the caller; a failed open closes it so a partial
160
- * initialization does not leak the connection.
161
- */
162
- const openLwwClock = (options) => Effect.gen(function* () {
163
- const { documentId, replicaId, storage } = options;
164
- yield* Effect.annotateCurrentSpan({
165
- documentId,
166
- replicaId
167
- });
168
- const initial = decodeClock({
169
- schemaVersion: CLOCK_SCHEMA_VERSION,
170
- documentId,
171
- replicaId,
172
- revision: 0
173
- });
174
- const saved = yield* storage.load();
175
- const state = yield* Effect.try({
176
- try: () => saved === void 0 ? initial : decodeClock(saved),
177
- catch: (cause) => unsupportedVersion(saved) ?? clockError("Stored clock state is invalid", cause)
178
- });
179
- if (state.documentId !== documentId || state.replicaId !== replicaId) return yield* new StorageError({ message: "Wrong clock storage" });
180
- if (saved === void 0) yield* storage.save(state, null);
181
- const stateRef = yield* SynchronizedRef.make(state);
182
- const closed = yield* Ref.make(false);
183
- const next = (observedCounter = 0) => Effect.gen(function* () {
184
- if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
185
- return yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
186
- if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
187
- const allocated = yield* Effect.try({
188
- try: () => decodeClock({
189
- ...current,
190
- revision: Math.max(current.revision, decodeCounter(observedCounter)) + 1
191
- }),
192
- catch: (cause) => clockError("Invalid clock allocation", cause)
193
- });
194
- yield* storage.save(allocated, current.revision);
195
- return [{
196
- counter: allocated.revision,
197
- replicaId
198
- }, allocated];
199
- }));
200
- }).pipe(Effect.withSpan("Lww.next"));
201
- return {
202
- next,
203
- close: Effect.gen(function* () {
204
- if (yield* Ref.modify(closed, (current) => [current, true])) return;
205
- yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.succeed([void 0, current]));
206
- yield* storage.close;
207
- }).pipe(Effect.withSpan("Lww.close"))
208
- };
209
- }).pipe(Effect.withSpan("Lww.openClock"), Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : options.storage.close.pipe(Effect.ignore)));
210
- /**
211
- * A schema and reducer helper for a last-writer-wins register.
212
- * Allocate a unique stamp per write before dispatch, and retain it in the Message.
213
- * Merge is for decoded values; the application's schema validates wire input.
214
- */
215
- const lwwRegister = (value) => {
216
- const schema = Schema.Struct({
217
- stamp: Stamp,
218
- value
219
- });
220
- const equivalent = Schema.toEquivalence(value);
221
- const merge = (left, right) => {
222
- if (left.stamp.counter !== right.stamp.counter) return left.stamp.counter > right.stamp.counter ? left : right;
223
- if (left.stamp.replicaId !== right.stamp.replicaId) return left.stamp.replicaId > right.stamp.replicaId ? left : right;
224
- if (!equivalent(left.value, right.value)) throw new Error("Conflicting LWW write identity");
225
- return left;
226
- };
227
- return {
228
- schema,
229
- merge
230
- };
231
- };
232
- //#endregion
233
- //#region src/presence.ts
133
+ //#region src/mount.ts
234
134
  /**
235
- * Tracks ephemeral peers with a time-to-live.
135
+ * `Sync.mount`: runs a Foldkit application over a replica with one reducer.
236
136
  *
237
- * Nothing here touches the durable log: presence is state a peer refreshes, and
238
- * a peer that stops refreshing is dropped, not replayed. Time comes from the
239
- * `Clock`, so a `TestClock` drives the TTL deterministically.
137
+ * A durable Message is a state-only, deterministic transition of the shared
138
+ * projection (the derived replay enforces it), so the application's own `update`
139
+ * is applied at once and the Message is persisted afterwards in a Command. The
140
+ * shared slice is re-installed from the replica when an exchange changes it or
141
+ * a persist fails, through one private Message the application never sees.
240
142
  */
241
- const createPresence = (options) => Effect.gen(function* () {
242
- const ttl = Duration.toMillis(options.ttl);
243
- const peers = yield* Ref.make(/* @__PURE__ */ new Map());
244
- const closed = yield* Ref.make(false);
245
- const listeners = /* @__PURE__ */ new Set();
246
- /** A subscriber must never fail an update. */
247
- const notify = () => {
248
- for (const listener of [...listeners]) try {
249
- listener();
250
- } catch {}
143
+ const REFRESH = "foldkit-sync/Refresh";
144
+ const PERSISTED = "foldkit-sync/Persisted";
145
+ const FAILED = "foldkit-sync/PersistenceFailed";
146
+ const NAVIGATE = "foldkit-sync/Navigate";
147
+ const NAVIGATED = "foldkit-sync/Navigated";
148
+ /** Exchanges and rejections change what the replica holds; a submit only echoes a local edit. */
149
+ const sharedChanged = (previous, next) => previous === void 0 || previous.cursor !== next.cursor || previous.rejected.length !== next.rejected.length || previous.rejected.some((id, index) => id !== next.rejected[index]);
150
+ const mount = (app, sync, options) => {
151
+ if (options.container.id === "") throw new Error("Sync.mount: the container needs an id (`container.id = \"app\"`)");
152
+ const { replica } = options;
153
+ const durable = new Set(sync.contract.messages);
154
+ const install = (model) => sync.projection.set(model, Effect.runSync(replica.shared));
155
+ const inFlight = /* @__PURE__ */ new Set();
156
+ let latest = install(app.initial);
157
+ const modelListeners = /* @__PURE__ */ new Set();
158
+ const messageListeners = /* @__PURE__ */ new Set();
159
+ const update = (model, message) => {
160
+ switch (message._tag) {
161
+ case REFRESH: return { model: install(model) };
162
+ case PERSISTED: return { model };
163
+ case FAILED: {
164
+ const { error } = message;
165
+ const reverted = install(model);
166
+ return { model: options.onPersistenceFailure?.(reverted, error) ?? reverted };
167
+ }
168
+ case NAVIGATE: {
169
+ const { request } = message;
170
+ return {
171
+ model,
172
+ commands: [{
173
+ name: "foldkit-sync/navigate",
174
+ effect: (request._tag === "Internal" ? Navigation.pushUrl(Url.toString(request.url)) : Navigation.load(request.href)).pipe(Effect.as({ _tag: NAVIGATED }))
175
+ }]
176
+ };
177
+ }
178
+ case NAVIGATED: return { model };
179
+ default: {
180
+ for (const listener of messageListeners) listener(message);
181
+ const result = app.update(model, message);
182
+ if (!durable.has(message._tag)) return result;
183
+ const persist = {
184
+ name: "foldkit-sync/persist",
185
+ effect: Effect.gen(function* () {
186
+ let settle;
187
+ const done = new Promise((resolve) => {
188
+ settle = resolve;
189
+ });
190
+ inFlight.add(done);
191
+ const outcome = yield* Effect.result(replica.submit(message));
192
+ inFlight.delete(done);
193
+ settle();
194
+ return outcome._tag === "Success" ? { _tag: PERSISTED } : {
195
+ _tag: FAILED,
196
+ error: outcome.failure
197
+ };
198
+ })
199
+ };
200
+ return {
201
+ model: result.model,
202
+ commands: [...result.commands ?? [], persist]
203
+ };
204
+ }
205
+ }
251
206
  };
252
- const expired = (peer, at) => at - peer.updatedAt > ttl;
253
- const put = (id, value, at) => Ref.update(peers, (map) => {
254
- const next = new Map(map);
255
- next.set(id, {
256
- id,
257
- value,
258
- updatedAt: at
259
- });
260
- return next;
261
- });
262
- const remove = (id) => Ref.modify(peers, (map) => {
263
- if (!map.has(id)) return [false, map];
264
- const next = new Map(map);
265
- next.delete(id);
266
- return [true, next];
267
- });
268
- const receive = (update) => Effect.gen(function* () {
269
- if (update.id === options.id) return;
270
- if (update.value === null) {
271
- if (yield* remove(update.id)) notify();
272
- return;
207
+ const ports = { inbound: { message: Port.inbound(app.Message) } };
208
+ const own = Subscription.make()(() => ({
209
+ message: Port.subscription(ports.inbound.message, (message) => message),
210
+ refresh: Subscription.persistent(replica.statusChanges.pipe(Stream.mapAccum(() => void 0, (previous, status) => [status, sharedChanged(previous, status) ? [{ _tag: REFRESH }] : []]))),
211
+ latest: {
212
+ dependenciesSchema: Schema.Struct({}),
213
+ modelToDependencies: (model) => {
214
+ latest = model;
215
+ for (const listener of modelListeners) listener();
216
+ return {};
217
+ },
218
+ dependenciesToStream: () => Stream.never
273
219
  }
274
- let value;
275
- try {
276
- value = options.decodeValue(update.value);
277
- } catch {
278
- return;
220
+ }));
221
+ const subscriptions = options.subscriptions === void 0 ? own : Subscription.aggregate()(options.subscriptions, own);
222
+ const view = (model, h) => options.view(model, h);
223
+ const common = {
224
+ Model: app.Model,
225
+ container: options.container,
226
+ ports,
227
+ update,
228
+ subscriptions,
229
+ ...options.resources === void 0 ? {} : { resources: options.resources },
230
+ view
231
+ };
232
+ const url = options.url;
233
+ const program = url === void 0 ? Runtime.makeApplication({
234
+ ...common,
235
+ init: () => ({ model: latest })
236
+ }) : Runtime.makeApplication({
237
+ ...common,
238
+ routing: {
239
+ onUrlChange: (at) => url.onUrlChange(at),
240
+ onUrlRequest: (request) => url.onUrlRequest === void 0 ? {
241
+ _tag: NAVIGATE,
242
+ request
243
+ } : url.onUrlRequest(request)
244
+ },
245
+ init: (at) => {
246
+ latest = url.init === void 0 ? latest : url.init(latest, at);
247
+ return { model: latest };
279
248
  }
280
- yield* put(update.id, value, yield* Clock.currentTimeMillis);
281
- notify();
282
249
  });
283
- const channel = options.channel;
284
- const consuming = channel === void 0 ? void 0 : yield* Stream.runForEach(Stream.fromPubSub(channel.updates), receive).pipe(Effect.forkScoped);
285
- const set = (value) => Effect.gen(function* () {
286
- if (yield* Ref.get(closed)) return;
287
- yield* put(options.id, value, yield* Clock.currentTimeMillis);
288
- if (channel !== void 0) yield* channel.publish({
289
- id: options.id,
290
- value
291
- });
292
- notify();
293
- }).pipe(Effect.withSpan("Presence.set"));
250
+ const handle = Runtime.embed(program);
294
251
  return {
295
- set,
296
- leave: Effect.gen(function* () {
297
- if (yield* Ref.get(closed)) return;
298
- yield* remove(options.id);
299
- if (channel !== void 0) yield* channel.publish({
300
- id: options.id,
301
- value: null
302
- });
303
- notify();
304
- }).pipe(Effect.withSpan("Presence.leave")),
305
- peers: Effect.gen(function* () {
306
- const at = yield* Clock.currentTimeMillis;
307
- return [...(yield* Ref.get(peers)).values()].filter((peer) => !expired(peer, at)).map((peer) => ({ ...peer }));
308
- }),
309
- prune: Effect.gen(function* () {
310
- if (yield* Ref.get(closed)) return;
311
- const at = yield* Clock.currentTimeMillis;
312
- if (yield* Ref.modify(peers, (map) => {
313
- let removed = false;
314
- const next = new Map(map);
315
- for (const [id, peer] of map) if (expired(peer, at)) {
316
- next.delete(id);
317
- removed = true;
318
- }
319
- return [removed, next];
320
- })) notify();
321
- }).pipe(Effect.withSpan("Presence.prune")),
252
+ dispatch: (message) => handle.ports.message.send(message),
253
+ model: () => latest,
322
254
  subscribe: (listener) => {
323
- listeners.add(listener);
324
- return () => listeners.delete(listener);
255
+ modelListeners.add(listener);
256
+ return () => modelListeners.delete(listener);
325
257
  },
326
- close: Effect.gen(function* () {
327
- if (yield* Ref.get(closed)) return;
328
- yield* Ref.set(closed, true);
329
- if (consuming !== void 0) yield* Fiber.interrupt(consuming);
330
- yield* Effect.sync(() => listeners.clear());
331
- }).pipe(Effect.withSpan("Presence.close"))
332
- };
333
- }).pipe(Effect.withSpan("Presence.create"));
334
- /** An in-process channel, for tests and single-process demos. */
335
- const loopbackPresenceChannel = () => Effect.gen(function* () {
336
- const updates = yield* PubSub.unbounded();
337
- return {
338
- updates,
339
- publish: (update) => PubSub.publish(updates, update)
340
- };
341
- });
342
- const createPresenceHub = () => {
343
- const peers = /* @__PURE__ */ new Set();
344
- return {
345
- join: (send) => {
346
- peers.add(send);
347
- return () => peers.delete(send);
258
+ observe: (listener) => {
259
+ messageListeners.add(listener);
260
+ return () => messageListeners.delete(listener);
348
261
  },
349
- publish: (update) => {
350
- for (const send of [...peers]) try {
351
- send(update);
352
- } catch {}
262
+ dispose: async () => {
263
+ await Promise.all([...inFlight]);
264
+ handle.dispose();
353
265
  }
354
266
  };
355
267
  };
356
- const frameType = "presence";
357
- /** Decodes a presence frame, ignoring anything else a socket may carry. */
358
- const decodePresence = (data) => {
359
- let frame;
360
- try {
361
- frame = JSON.parse(data);
362
- } catch {
363
- return;
364
- }
365
- const value = frame[frameType];
366
- if (typeof value !== "object" || value === null) return void 0;
367
- const { id, value: payload } = value;
368
- if (typeof id !== "string") return void 0;
369
- return {
370
- id,
371
- value: payload ?? null
372
- };
373
- };
374
- /** A presence channel fed by frames arriving on a socket, sent back over it. */
375
- const socketPresenceChannel = (socket) => Effect.gen(function* () {
376
- const updates = yield* PubSub.unbounded();
377
- yield* Effect.acquireRelease(Effect.sync(() => socket.onMessage((data) => {
378
- const update = decodePresence(data);
379
- if (update !== void 0) PubSub.publishUnsafe(updates, update);
380
- })), (off) => Effect.sync(off));
381
- return {
382
- updates,
383
- publish: (update) => Effect.sync(() => socket.send(JSON.stringify({ [frameType]: update })))
384
- };
385
- });
386
- /** Serves presence frames on an accepted socket, fanning them through the hub. */
387
- const servePresence = (socket, hub) => {
388
- const send = (update) => socket.send(JSON.stringify({ [frameType]: update }));
389
- const leave = hub.join(send);
390
- const off = socket.onMessage((data) => {
391
- const update = decodePresence(data);
392
- if (update !== void 0) hub.publish(update);
393
- });
394
- return () => {
395
- off();
396
- leave();
397
- };
398
- };
268
+ //#endregion
269
+ //#region src/ids.ts
270
+ /** Identifies the replicated document a replica or operation belongs to. */
271
+ const DocumentId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/DocumentId"));
272
+ /** Identifies one replica (writer identity) within a document. */
273
+ const ReplicaId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/ReplicaId"));
274
+ /** The stable identity of one operation within a document. */
275
+ const OpId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/OpId"));
276
+ /**
277
+ * A position in the committed document order. `0` is the start; a committed
278
+ * operation's `serverSequence` and a replica's `cursor` are the same family.
279
+ */
280
+ const Sequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)).pipe(Schema.brand("@foldkit-sync/Sequence"));
281
+ /** A replica's own operation counter within a document; 1-based. */
282
+ const LocalSequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)).pipe(Schema.brand("@foldkit-sync/LocalSequence"));
283
+ const documentId = (value) => Schema.decodeUnknownSync(DocumentId)(value);
284
+ const replicaId = (value) => Schema.decodeUnknownSync(ReplicaId)(value);
285
+ const opId = (value) => Schema.decodeUnknownSync(OpId)(value);
286
+ const sequence = (value) => Schema.decodeUnknownSync(Sequence)(value);
287
+ const localSequence = (value) => Schema.decodeUnknownSync(LocalSequence)(value);
399
288
  //#endregion
400
289
  //#region src/transport.ts
401
290
  /** The wire failure of a transport. A refusal is a result, not an error. */
@@ -416,7 +305,7 @@ const layerLoopback = (handler) => Layer.succeed(Transport, { exchange: (cursor,
416
305
  }) });
417
306
  /** Wraps the promise-based client the replica already speaks. */
418
307
  const layerFromPromise = (transport) => Layer.succeed(Transport, { exchange: (cursor, pending) => Effect.tryPromise({
419
- try: () => transport.exchange(cursor, pending),
308
+ try: () => transport.exchange(sequence(cursor), pending),
420
309
  catch: failure
421
310
  }) });
422
311
  /** Bridges the service back to the promise client the replica consumes. */
@@ -514,7 +403,7 @@ const nativeSocket = (url) => {
514
403
  * with a `TransportError`; a queue over `maxQueue` fails new exchanges with
515
404
  * backpressure. The socket is released when the layer's scope ends.
516
405
  */
517
- const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* () {
406
+ const layerSocket = (options) => Layer.effect(Transport, Effect.fn("Transport.layerSocket")(function* () {
518
407
  const makeSocket = options.makeSocket ?? nativeSocket;
519
408
  const maxQueue = options.maxQueue ?? 64;
520
409
  const retry = Schedule.exponential(options.retryBase ?? "50 millis").pipe(Schedule.jittered, Schedule.upTo({ times: options.maxRetries ?? 5 }));
@@ -524,6 +413,7 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
524
413
  let ready = false;
525
414
  let nextId = 0;
526
415
  let disposed = false;
416
+ let terminalError;
527
417
  const send = (entry) => {
528
418
  inFlight.set(entry.id, entry);
529
419
  socket?.send(JSON.stringify({
@@ -580,7 +470,9 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
580
470
  catch: () => new TransportError({ message: "transport closed" })
581
471
  });
582
472
  yield* Effect.forkScoped(connect.pipe(Effect.retry(retry), Effect.catch((error) => Effect.sync(() => {
583
- if (!disposed) failAll(error.message);
473
+ if (disposed) return;
474
+ terminalError = error;
475
+ failAll(error.message);
584
476
  }))));
585
477
  yield* Effect.addFinalizer(() => Effect.sync(() => {
586
478
  disposed = true;
@@ -589,11 +481,15 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
589
481
  socket = void 0;
590
482
  failAll("transport closed");
591
483
  }));
592
- return { exchange: (cursor, pending) => Effect.callback((resume) => {
484
+ return Transport.of({ exchange: (cursor, pending) => Effect.callback((resume) => {
593
485
  if (disposed) {
594
486
  resume(Effect.fail(new TransportError({ message: "transport closed" })));
595
487
  return;
596
488
  }
489
+ if (terminalError !== void 0) {
490
+ resume(Effect.fail(terminalError));
491
+ return;
492
+ }
597
493
  if (queued.length + inFlight.size >= maxQueue) {
598
494
  resume(Effect.fail(new TransportError({ message: "transport queue full" })));
599
495
  return;
@@ -606,11 +502,15 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
606
502
  };
607
503
  if (ready) send(entry);
608
504
  else queued.push(entry);
609
- }) };
610
- }));
505
+ return Effect.sync(() => {
506
+ const queuedIndex = queued.indexOf(entry);
507
+ if (queuedIndex >= 0) queued.splice(queuedIndex, 1);
508
+ if (inFlight.get(entry.id) === entry) inFlight.delete(entry.id);
509
+ });
510
+ }) });
511
+ })());
611
512
  //#endregion
612
513
  //#region src/sync.ts
613
- const Sequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
614
514
  /** Wire and persisted-format versions. A bump must handle the older value explicitly. */
615
515
  const PROTOCOL_VERSION = 1;
616
516
  const SCHEMA_VERSION = 1;
@@ -620,7 +520,7 @@ const OperationSchema = Schema.Struct({
620
520
  schemaVersion: Schema.Literal(SCHEMA_VERSION),
621
521
  documentId: DocumentId,
622
522
  replicaId: ReplicaId,
623
- localSequence: Sequence,
523
+ localSequence: LocalSequence,
624
524
  opId: OpId,
625
525
  baseCursor: Sequence,
626
526
  message: Schema.Unknown
@@ -658,13 +558,15 @@ const defineSync = (definition) => {
658
558
  const documentId = definition.documentId;
659
559
  const decodeMessage = Schema.decodeUnknownSync(definition.message, { onExcessProperty: "error" });
660
560
  const encodeMessage = Schema.encodeSync(definition.message);
561
+ const decodeShared = Schema.decodeUnknownSync(definition.shared, { onExcessProperty: "error" });
562
+ const encodeShared = Schema.encodeSync(definition.shared);
661
563
  const ReplicaStateSchema = Schema.Struct({
662
564
  protocolVersion: Schema.Literal(PROTOCOL_VERSION),
663
565
  schemaVersion: Schema.Literal(SCHEMA_VERSION),
664
566
  documentId: DocumentId,
665
567
  replicaId: ReplicaId,
666
- revision: Sequence,
667
- nextLocalSequence: Sequence,
568
+ revision: Schema.Number,
569
+ nextLocalSequence: LocalSequence,
668
570
  cursor: Sequence,
669
571
  committed: definition.shared,
670
572
  committedIds: Schema.Array(Schema.String),
@@ -681,6 +583,7 @@ const defineSync = (definition) => {
681
583
  checkpoint: Schema.optional(CheckpointSchema)
682
584
  });
683
585
  const decodeState = Schema.decodeUnknownSync(ReplicaStateSchema, { onExcessProperty: "error" });
586
+ const encodeState = Schema.encodeSync(ReplicaStateSchema);
684
587
  const VersionProbe = Schema.Struct({
685
588
  protocolVersion: Schema.optional(Schema.Number),
686
589
  schemaVersion: Schema.optional(Schema.Number)
@@ -707,7 +610,7 @@ const defineSync = (definition) => {
707
610
  };
708
611
  const decodeExchange = (input) => Schema.decodeUnknownSync(ExchangeSchema, { onExcessProperty: "error" })(input);
709
612
  const checkIdentity = (operation) => {
710
- if (operation.localSequence < 1 || operation.opId !== `${operation.replicaId}:${operation.localSequence}`) throw new Error("Invalid operation identity");
613
+ if (operation.opId !== `${operation.replicaId}:${operation.localSequence}`) throw new Error("Invalid operation identity");
711
614
  };
712
615
  const decodeDurable = (message) => {
713
616
  const decoded = decodeMessage(message);
@@ -741,8 +644,24 @@ const defineSync = (definition) => {
741
644
  };
742
645
  };
743
646
  const committedFrom = (input, key) => decodeCommittedOperation(input, key).committed;
647
+ const journalContract = () => ({
648
+ operation: {
649
+ encode: (operation) => operation,
650
+ decode: normalizeOperation
651
+ },
652
+ snapshot: {
653
+ encode: encodeShared,
654
+ decode: decodeShared
655
+ },
656
+ empty: () => definition.empty,
657
+ reduce: (snapshot, operation) => definition.replay(snapshot, decodeMessage(operation.message))
658
+ });
744
659
  const optimistic = (state) => state.pending.reduce((model, operation) => definition.replay(model, decodeMessage(operation.message)), state.committed);
745
- const openReplica = (replicaId, storage) => Effect.gen(function* () {
660
+ const openReplica = Effect.fn("Sync.openReplica")(function* (replicaId, storage) {
661
+ yield* Effect.annotateCurrentSpan({
662
+ documentId,
663
+ replicaId
664
+ });
746
665
  const saved = yield* storage.load();
747
666
  const initial = {
748
667
  protocolVersion: PROTOCOL_VERSION,
@@ -750,8 +669,8 @@ const defineSync = (definition) => {
750
669
  documentId,
751
670
  replicaId,
752
671
  revision: 0,
753
- nextLocalSequence: 1,
754
- cursor: 0,
672
+ nextLocalSequence: localSequence(1),
673
+ cursor: sequence(0),
755
674
  committed: definition.empty,
756
675
  committedIds: [],
757
676
  pending: []
@@ -779,71 +698,118 @@ const defineSync = (definition) => {
779
698
  if (operation.replicaId !== replicaId || operation.localSequence >= state.nextLocalSequence || committedIds.has(operation.opId) || pendingIds.has(operation.opId)) return yield* new InvalidOutboxError({ message: "Invalid outbox" });
780
699
  pendingIds.add(operation.opId);
781
700
  }
782
- if (saved === void 0) yield* storage.save(state, null);
701
+ const store = Effect.fn("Sync.store")(function* (next, expectedRevision) {
702
+ const encoded = yield* Effect.try({
703
+ try: () => encodeState(next),
704
+ catch: (cause) => new InvalidReplicaHistoryError({
705
+ message: "Could not encode the replica state",
706
+ cause
707
+ })
708
+ });
709
+ yield* storage.save(encoded, expectedRevision);
710
+ });
711
+ if (saved === void 0) yield* store(state, null);
783
712
  const stateRef = yield* SynchronizedRef.make(state);
784
713
  const closed = yield* Ref.make(false);
785
714
  const lastError = yield* Ref.make(void 0);
786
715
  const rejectedOps = yield* Ref.make([]);
716
+ const wake = yield* Queue.sliding(1);
717
+ const statusSignals = yield* PubSub.sliding(1);
787
718
  const projection = yield* Ref.make(void 0);
788
- const shared = Effect.gen(function* () {
719
+ const snapshot = Effect.fn("Sync.snapshot")(function* () {
789
720
  const current = yield* SynchronizedRef.get(stateRef);
790
721
  const cached = yield* Ref.get(projection);
791
- if (cached !== void 0 && cached.state === current) return cached.shared;
792
- const projected = optimistic(current);
793
- yield* Ref.set(projection, {
794
- state: current,
722
+ let projected;
723
+ if (cached !== void 0 && cached.state === current) projected = cached.shared;
724
+ else {
725
+ projected = optimistic(current);
726
+ yield* Ref.set(projection, {
727
+ state: current,
728
+ shared: projected
729
+ });
730
+ }
731
+ return {
732
+ status: {
733
+ pending: current.pending.length,
734
+ cursor: current.cursor,
735
+ lastError: yield* Ref.get(lastError),
736
+ rejected: yield* Ref.get(rejectedOps)
737
+ },
795
738
  shared: projected
739
+ };
740
+ })();
741
+ const shared = Effect.map(snapshot, (value) => value.shared);
742
+ const status = Effect.map(snapshot, (value) => value.status);
743
+ const persist = (next, current) => store(next, current.revision);
744
+ const submit = Effect.fn("Sync.submit")(function* (message) {
745
+ yield* Effect.annotateCurrentSpan({
746
+ documentId,
747
+ replicaId
796
748
  });
797
- return projected;
798
- });
799
- const persist = (next, current) => storage.save(next, current.revision);
800
- const submit = (message) => SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
801
- if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
802
- const operation = yield* Effect.try({
803
- try: () => operationFrom({
804
- protocolVersion: PROTOCOL_VERSION,
805
- schemaVersion: SCHEMA_VERSION,
806
- documentId,
807
- replicaId,
808
- localSequence: current.nextLocalSequence,
809
- opId: `${replicaId}:${current.nextLocalSequence}`,
810
- baseCursor: current.cursor,
811
- message: encodeMessage(message)
812
- }, documentId),
813
- catch: () => new InvalidOutboxError({ message: "Invalid outbox" })
814
- });
815
- const next = yield* Effect.try({
816
- try: () => decodeState({
749
+ const result = yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
750
+ if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
751
+ const operation = yield* Effect.try({
752
+ try: () => operationFrom({
753
+ protocolVersion: PROTOCOL_VERSION,
754
+ schemaVersion: SCHEMA_VERSION,
755
+ documentId,
756
+ replicaId,
757
+ localSequence: current.nextLocalSequence,
758
+ opId: `${replicaId}:${current.nextLocalSequence}`,
759
+ baseCursor: current.cursor,
760
+ message: encodeMessage(message)
761
+ }, documentId),
762
+ catch: () => new InvalidOutboxError({ message: "Invalid outbox" })
763
+ });
764
+ const cached = yield* Ref.get(projection);
765
+ const replayed = yield* Effect.try({
766
+ try: () => definition.replay(cached !== void 0 && cached.state === current ? cached.shared : optimistic(current), message),
767
+ catch: (cause) => new ReplayError({
768
+ message: cause instanceof Error ? cause.message : "Replay failed",
769
+ cause
770
+ })
771
+ });
772
+ const next = {
817
773
  ...current,
818
774
  revision: current.revision + 1,
819
- nextLocalSequence: current.nextLocalSequence + 1,
775
+ nextLocalSequence: localSequence(current.nextLocalSequence + 1),
820
776
  pending: [...current.pending, operation]
821
- }),
822
- catch: (cause) => new InvalidReplicaHistoryError({
823
- message: "Invalid replica state",
824
- cause
825
- })
826
- });
827
- yield* persist(next, current);
828
- return [void 0, next];
829
- })).pipe(Effect.withSpan("Sync.submit", { attributes: {
830
- documentId,
831
- replicaId
832
- } }));
833
- const synchronize = Effect.gen(function* () {
777
+ };
778
+ yield* persist(next, current);
779
+ yield* Ref.set(projection, {
780
+ state: next,
781
+ shared: replayed
782
+ });
783
+ yield* Queue.offer(wake, void 0);
784
+ return [void 0, next];
785
+ }));
786
+ yield* PubSub.publish(statusSignals, void 0);
787
+ return result;
788
+ });
789
+ const synchronize = Effect.fn("Sync.synchronize")(function* () {
790
+ yield* Effect.annotateCurrentSpan({ documentId });
834
791
  const transport = yield* Transport;
835
792
  if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
836
793
  const sent = yield* SynchronizedRef.get(stateRef);
837
794
  yield* Metric.update(syncMetrics.exchanges, 1);
838
795
  yield* Metric.update(syncMetrics.exchangePending, sent.pending.length);
839
- const response = decodeExchange(yield* transport.exchange(sent.cursor, sent.pending).pipe(Effect.tapError((error) => Effect.gen(function* () {
796
+ const response = yield* Effect.gen(function* () {
797
+ const raw = yield* transport.exchange(sent.cursor, sent.pending);
798
+ return yield* Effect.try({
799
+ try: () => decodeExchange(raw),
800
+ catch: (cause) => new InvalidExchangeError({
801
+ message: "Invalid sync exchange response",
802
+ cause
803
+ })
804
+ });
805
+ }).pipe(Effect.tapError((error) => Effect.gen(function* () {
840
806
  yield* Effect.logWarning("sync exchange failed", {
841
807
  documentId,
842
808
  replicaId,
843
809
  error: error.message
844
810
  });
845
811
  yield* Ref.set(lastError, error.message);
846
- }))));
812
+ })));
847
813
  yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
848
814
  if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
849
815
  let cursor = current.cursor;
@@ -867,10 +833,20 @@ const defineSync = (definition) => {
867
833
  const acknowledged = new Set(response.acknowledged ?? []);
868
834
  const rejected = new Set(response.rejected);
869
835
  const sentIds = new Set(sent.pending.map((operation) => operation.opId));
870
- for (const id of rejected) if (!sentIds.has(id)) return yield* new ForeignRejectionError({
836
+ for (const id of acknowledged) if (!sentIds.has(id)) return yield* new ForeignAcknowledgementError({
871
837
  opId: id,
872
- message: "Server rejected an operation that was not sent"
838
+ message: "Server acknowledged an operation that was not sent"
873
839
  });
840
+ for (const id of rejected) {
841
+ if (!sentIds.has(id)) return yield* new ForeignRejectionError({
842
+ opId: id,
843
+ message: "Server rejected an operation that was not sent"
844
+ });
845
+ if (acknowledged.has(id)) return yield* new ForeignAcknowledgementError({
846
+ opId: id,
847
+ message: "Server both acknowledged and rejected an operation"
848
+ });
849
+ }
874
850
  let applied = 0;
875
851
  for (const raw of response.operations) {
876
852
  const { committed: operation, message } = yield* Effect.try({
@@ -892,60 +868,499 @@ const defineSync = (definition) => {
892
868
  applied += 1;
893
869
  }
894
870
  if (applied > 0) yield* Metric.update(syncMetrics.applied, applied);
895
- const next = yield* Effect.try({
896
- try: () => decodeState({
897
- ...current,
898
- revision: current.revision + 1,
899
- committed,
900
- cursor,
901
- committedIds: [...ids].slice(-1024),
902
- pending: current.pending.filter((operation) => !ids.has(operation.opId) && !acknowledged.has(operation.opId) && !rejected.has(operation.opId))
903
- }),
904
- catch: (cause) => new InvalidReplicaHistoryError({
905
- message: "Invalid replica state",
906
- cause
907
- })
908
- });
871
+ const next = {
872
+ ...current,
873
+ revision: current.revision + 1,
874
+ committed,
875
+ cursor,
876
+ committedIds: [...ids].slice(-1024),
877
+ pending: current.pending.filter((operation) => !ids.has(operation.opId) && !acknowledged.has(operation.opId) && !rejected.has(operation.opId))
878
+ };
909
879
  yield* persist(next, current);
910
880
  return [void 0, next];
911
881
  }));
912
882
  yield* Ref.set(lastError, void 0);
913
883
  if (response.rejected.length > 0) yield* Ref.update(rejectedOps, (previous) => [...response.rejected, ...previous].slice(0, 32));
914
- }).pipe(Effect.withSpan("Sync.synchronize", { attributes: { documentId } }));
884
+ yield* PubSub.publish(statusSignals, void 0);
885
+ })();
886
+ const start = Effect.gen(function* () {
887
+ yield* synchronize.pipe(Effect.catch(() => Effect.void));
888
+ while (!(yield* Ref.get(closed))) {
889
+ yield* Queue.take(wake);
890
+ if (yield* Ref.get(closed)) return;
891
+ yield* synchronize.pipe(Effect.catch(() => Effect.void));
892
+ }
893
+ });
915
894
  return {
916
895
  shared,
917
896
  pending: Effect.map(SynchronizedRef.get(stateRef), (state) => state.pending),
918
897
  cursor: Effect.map(SynchronizedRef.get(stateRef), (state) => state.cursor),
919
- status: Effect.gen(function* () {
920
- const state = yield* SynchronizedRef.get(stateRef);
921
- return {
922
- pending: state.pending.length,
923
- cursor: state.cursor,
924
- lastError: yield* Ref.get(lastError),
925
- rejected: yield* Ref.get(rejectedOps)
926
- };
927
- }),
898
+ status,
899
+ statusChanges: Stream.concat(Stream.fromEffect(status), Stream.fromPubSub(statusSignals).pipe(Stream.mapEffect(() => status))),
900
+ changes: Stream.concat(Stream.fromEffect(snapshot), Stream.fromPubSub(statusSignals).pipe(Stream.mapEffect(() => snapshot))),
928
901
  submit,
929
902
  synchronize,
930
- close: Effect.gen(function* () {
903
+ start,
904
+ close: Effect.fn("Sync.close")(function* () {
931
905
  yield* Ref.set(closed, true);
906
+ yield* Queue.offer(wake, void 0);
932
907
  yield* storage.close;
933
- })
908
+ })()
934
909
  };
935
- }).pipe(Effect.withSpan("Sync.openReplica", { attributes: {
936
- documentId,
937
- replicaId
938
- } }));
910
+ }, (effect, _replicaId, storage) => effect.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : storage.close.pipe(Effect.ignore))));
939
911
  return {
940
912
  documentId,
941
- normalizeOperation,
942
- operationFrom,
943
- committedFrom,
944
- decodeExchange,
913
+ codec: {
914
+ normalizeOperation,
915
+ operationFrom,
916
+ committedFrom,
917
+ decodeExchange
918
+ },
919
+ journalContract,
945
920
  openReplica
946
921
  };
947
922
  };
948
923
  //#endregion
949
- export { CheckpointRegressionError, CommittedOrderError, DocumentId, ForeignRejectionError, InvalidOutboxError, InvalidReplicaHistoryError, OpId, ReplicaClosedError, ReplicaId, StorageError, Transport, TransportError, UnsupportedClockVersionError, UnsupportedReplicaVersionError, WrongReplicaStorageError, createPresence, createPresenceHub, defineSync, documentId, indexedDb, layerFromPromise, layerLoopback, layerSocket, loopbackPresenceChannel, lwwRegister, nativeSocket, opId, openLwwClock, replicaId, servePresence, serveSocket, socketPresenceChannel, syncMetrics, toPromise };
924
+ //#region src/make.ts
925
+ /**
926
+ * The Foldkit-facing sync layer: `Sync.forApplication(App).make(config)`
927
+ * compiles an application, a writable projection, and a durable Message subset
928
+ * into the low-level `defineSync` contract, and exposes a read-only Surface over
929
+ * the same projection.
930
+ */
931
+ /** Reads the tag off a Foldkit Message constructor without constructing one. */
932
+ const messageTag = (constructor) => {
933
+ const literal = constructor.fields?._tag?.ast?.literal;
934
+ return typeof literal === "string" ? literal : void 0;
935
+ };
936
+ /**
937
+ * Replay derived from the application's own `update`: install the shared slice
938
+ * into the initial Model, apply the Message, and read the slice back.
939
+ *
940
+ * A durable Message must be a deterministic, state-only transition of the shared
941
+ * projection. Replay refuses one that returns a Command (a live effect cannot be
942
+ * replayed) or that changes a Model field outside the projection (the change
943
+ * would be silently lost), so a Message that needs either stays local and emits
944
+ * a durable fact once the effect settles.
945
+ */
946
+ const derivedReplay = (app, shared) => {
947
+ const { initial, update } = app;
948
+ const owned = new Set(shared.dependencies.filter((path) => path.length === 1).map((path) => path[0]));
949
+ const fields = Object.entries(app.Model.fields).filter(([key]) => !owned.has(key)).map(([key, field]) => [key, Schema.toEquivalence(field)]);
950
+ return (value, message) => {
951
+ const result = update(shared.set(initial, value), message);
952
+ const tag = message._tag;
953
+ if (result.commands !== void 0 && result.commands.length > 0) throw new Error(`Sync.forApplication: durable "${tag}" returned ${result.commands.length} Command(s); a durable transition is state-only`);
954
+ const next = shared.get(result.model);
955
+ const written = shared.set(initial, next);
956
+ const actual = result.model;
957
+ const changed = fields.filter(([key, equal]) => !equal(actual[key], written[key]));
958
+ if (changed.length > 0) throw new Error(`Sync.forApplication: durable "${tag}" changed Model fields outside the shared projection: ${changed.map(([key]) => key).join(", ")}`);
959
+ return next;
960
+ };
961
+ };
962
+ /**
963
+ * Merges fragments into one. The primitives reject a conflicting field, a
964
+ * duplicate tag, and a subset from another application.
965
+ */
966
+ const composeFragments = (fragments) => {
967
+ const compose = Projection.compose;
968
+ const union = MessageSet.union;
969
+ return {
970
+ shared: compose(...fragments.map((fragment) => fragment.shared)),
971
+ durable: union(...fragments.map((fragment) => fragment.durable))
972
+ };
973
+ };
974
+ /**
975
+ * Specializes the sync constructors to a `Surface.application`, so
976
+ * `Sync.forApplication(App).make({ documentId, shared, durable })` derives the
977
+ * shared codec, the initial snapshot, the durable predicate, and replay from
978
+ * the application, and refuses a subset that belongs to another application.
979
+ * `defineSync` remains the protocol primitive when there is no application to
980
+ * derive from.
981
+ */
982
+ const forApplication = (app) => build(app);
983
+ const build = (app) => {
984
+ const decodeMessage = Schema.decodeUnknownSync(app.Message);
985
+ const make = (options) => {
986
+ const { shared, durable } = options;
987
+ if (durable.owner !== app.owner) throw new Error("Sync.make: the durable subset belongs to a different application");
988
+ const replay = options.replay === void 0 ? derivedReplay(app, shared) : (value, message) => options.replay(value, message);
989
+ const durableTags = new Set(durable.constructors.map(messageTag).filter((tag) => tag !== void 0));
990
+ const sync = defineSync({
991
+ documentId: options.documentId,
992
+ message: app.Message,
993
+ shared: shared.schema,
994
+ empty: shared.get(app.initial),
995
+ durable: (message) => {
996
+ const tag = message._tag;
997
+ return tag !== void 0 && durableTags.has(tag);
998
+ },
999
+ replay
1000
+ });
1001
+ const rules = options.authorize;
1002
+ const journalContract = () => {
1003
+ const base = sync.journalContract();
1004
+ if (rules === void 0) return base;
1005
+ return {
1006
+ ...base,
1007
+ authorize: ({ principal, operation, snapshot }) => {
1008
+ const message = decodeMessage(operation.message);
1009
+ const rule = rules[message._tag];
1010
+ return rule === void 0 ? true : rule({
1011
+ principal,
1012
+ message,
1013
+ shared: snapshot
1014
+ });
1015
+ }
1016
+ };
1017
+ };
1018
+ const readOnly = {
1019
+ Model: shared.schema,
1020
+ dependencies: shared.dependencies,
1021
+ requirements: [],
1022
+ connections: [],
1023
+ read: shared.get
1024
+ };
1025
+ const surface = Surface.make(app, options.name ?? String(options.documentId), {
1026
+ model: () => readOnly,
1027
+ messages: durable.constructors
1028
+ });
1029
+ const contract = {
1030
+ kind: "sync",
1031
+ name: surface.name,
1032
+ owner: app.owner,
1033
+ owns: shared.dependencies,
1034
+ observes: shared.dependencies,
1035
+ messages: [...durable.tags],
1036
+ requirements: []
1037
+ };
1038
+ return {
1039
+ ...sync,
1040
+ journalContract,
1041
+ surface,
1042
+ projection: shared,
1043
+ messages: durable.constructors,
1044
+ contract
1045
+ };
1046
+ };
1047
+ return {
1048
+ withPrincipal: () => build(app),
1049
+ fragment: (config) => {
1050
+ if (config.durable.owner !== app.owner) throw new Error("Sync.fragment: the durable subset belongs to a different application");
1051
+ return {
1052
+ shared: config.shared,
1053
+ durable: config.durable
1054
+ };
1055
+ },
1056
+ compose: ((...fragments) => composeFragments(fragments)),
1057
+ make
1058
+ };
1059
+ };
1060
+ //#endregion
1061
+ //#region src/lww.ts
1062
+ /** A logical write time; replica ids break concurrent ties using UTF-16 order. */
1063
+ const Stamp = Schema.Struct({
1064
+ counter: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)),
1065
+ replicaId: ReplicaId
1066
+ });
1067
+ /** The persisted clock format. A bump must handle the older value explicitly. */
1068
+ const CLOCK_SCHEMA_VERSION = 1;
1069
+ const ClockState = Schema.Struct({
1070
+ schemaVersion: Schema.Literal(CLOCK_SCHEMA_VERSION),
1071
+ documentId: DocumentId,
1072
+ replicaId: ReplicaId,
1073
+ revision: Stamp.fields.counter
1074
+ });
1075
+ const decodeClock = Schema.decodeUnknownSync(ClockState, { onExcessProperty: "error" });
1076
+ const decodeCounter = Schema.decodeUnknownSync(Stamp.fields.counter);
1077
+ const clockError = (message, cause) => new StorageError({
1078
+ message: `${message}: ${cause instanceof Error ? cause.message : String(cause)}`,
1079
+ cause
1080
+ });
1081
+ const VersionProbe = Schema.Struct({ schemaVersion: Schema.optional(Schema.Number) });
1082
+ /**
1083
+ * Tells a version this build does not understand apart from malformed data, so
1084
+ * the caller gets an actionable failure and the stored state is preserved.
1085
+ */
1086
+ const unsupportedVersion = (input) => {
1087
+ let found;
1088
+ try {
1089
+ found = Schema.decodeUnknownSync(VersionProbe)(input);
1090
+ } catch {
1091
+ return;
1092
+ }
1093
+ if (found.schemaVersion === CLOCK_SCHEMA_VERSION) return void 0;
1094
+ return new UnsupportedClockVersionError({
1095
+ schemaVersion: found.schemaVersion ?? null,
1096
+ message: `Stored clock uses schema ${found.schemaVersion ?? "?"}; this build supports ${CLOCK_SCHEMA_VERSION}`
1097
+ });
1098
+ };
1099
+ /**
1100
+ * Opens a durable clock over the caller's storage.
1101
+ *
1102
+ * Allocations are serialized through a `SynchronizedRef` and each persists before
1103
+ * its stamp is returned. A crash after the save may skip a timestamp but never
1104
+ * reuse one. Storage is owned by the caller; a failed open closes it so a partial
1105
+ * initialization does not leak the connection.
1106
+ */
1107
+ const openLwwClock = Effect.fn("Lww.openClock")(function* (options) {
1108
+ const { documentId, replicaId, storage } = options;
1109
+ yield* Effect.annotateCurrentSpan({
1110
+ documentId,
1111
+ replicaId
1112
+ });
1113
+ const initial = decodeClock({
1114
+ schemaVersion: CLOCK_SCHEMA_VERSION,
1115
+ documentId,
1116
+ replicaId,
1117
+ revision: 0
1118
+ });
1119
+ const saved = yield* storage.load();
1120
+ const state = yield* Effect.try({
1121
+ try: () => saved === void 0 ? initial : decodeClock(saved),
1122
+ catch: (cause) => unsupportedVersion(saved) ?? clockError("Stored clock state is invalid", cause)
1123
+ });
1124
+ if (state.documentId !== documentId || state.replicaId !== replicaId) return yield* new StorageError({ message: "Wrong clock storage" });
1125
+ if (saved === void 0) yield* storage.save(state, null);
1126
+ const stateRef = yield* SynchronizedRef.make(state);
1127
+ const closed = yield* Ref.make(false);
1128
+ return {
1129
+ next: Effect.fn("Lww.next")(function* (observedCounter = 0) {
1130
+ if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
1131
+ return yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
1132
+ if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
1133
+ const allocated = yield* Effect.try({
1134
+ try: () => decodeClock({
1135
+ ...current,
1136
+ revision: Math.max(current.revision, decodeCounter(observedCounter)) + 1
1137
+ }),
1138
+ catch: (cause) => clockError("Invalid clock allocation", cause)
1139
+ });
1140
+ yield* storage.save(allocated, current.revision);
1141
+ return [{
1142
+ counter: allocated.revision,
1143
+ replicaId
1144
+ }, allocated];
1145
+ }));
1146
+ }),
1147
+ close: Effect.fn("Lww.close")(function* () {
1148
+ if (yield* Ref.modify(closed, (current) => [current, true])) return;
1149
+ yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.succeed([void 0, current]));
1150
+ yield* storage.close;
1151
+ })()
1152
+ };
1153
+ }, (effect, options) => effect.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : options.storage.close.pipe(Effect.ignore))));
1154
+ /**
1155
+ * A schema and reducer helper for a last-writer-wins register.
1156
+ * Allocate a unique stamp per write before dispatch, and retain it in the Message.
1157
+ * Merge is for decoded values; the application's schema validates wire input.
1158
+ */
1159
+ const lwwRegister = (value) => {
1160
+ const schema = Schema.Struct({
1161
+ stamp: Stamp,
1162
+ value
1163
+ });
1164
+ const equivalent = Schema.toEquivalence(value);
1165
+ const merge = (left, right) => {
1166
+ if (left.stamp.counter !== right.stamp.counter) return left.stamp.counter > right.stamp.counter ? left : right;
1167
+ if (left.stamp.replicaId !== right.stamp.replicaId) return left.stamp.replicaId > right.stamp.replicaId ? left : right;
1168
+ if (!equivalent(left.value, right.value)) throw new Error("Conflicting LWW write identity");
1169
+ return left;
1170
+ };
1171
+ return {
1172
+ schema,
1173
+ merge
1174
+ };
1175
+ };
1176
+ //#endregion
1177
+ //#region src/presence.ts
1178
+ /**
1179
+ * Tracks ephemeral peers with a time-to-live.
1180
+ *
1181
+ * Nothing here touches the durable log: presence is state a peer refreshes, and
1182
+ * a peer that stops refreshing is dropped, not replayed. Time comes from the
1183
+ * `Clock`, so a `TestClock` drives the TTL deterministically.
1184
+ */
1185
+ const createPresence = Effect.fn("Presence.create")(function* (options) {
1186
+ const ttl = Duration.toMillis(options.ttl);
1187
+ const peers = yield* Ref.make(/* @__PURE__ */ new Map());
1188
+ const closed = yield* Ref.make(false);
1189
+ const signals = yield* PubSub.sliding(1);
1190
+ const listeners = /* @__PURE__ */ new Set();
1191
+ /** A subscriber must never fail an update. */
1192
+ const notify = () => Effect.gen(function* () {
1193
+ for (const listener of [...listeners]) try {
1194
+ listener();
1195
+ } catch {}
1196
+ yield* PubSub.publish(signals, void 0);
1197
+ });
1198
+ const expired = (peer, at) => at - peer.updatedAt > ttl;
1199
+ const put = (id, value, at) => Ref.update(peers, (map) => {
1200
+ const next = new Map(map);
1201
+ next.set(id, {
1202
+ id,
1203
+ value,
1204
+ updatedAt: at
1205
+ });
1206
+ return next;
1207
+ });
1208
+ const remove = (id) => Ref.modify(peers, (map) => {
1209
+ if (!map.has(id)) return [false, map];
1210
+ const next = new Map(map);
1211
+ next.delete(id);
1212
+ return [true, next];
1213
+ });
1214
+ const receive = Effect.fn("Presence.receive")(function* (update) {
1215
+ if (update.id === options.id) return;
1216
+ if (update.value === null) {
1217
+ if (yield* remove(update.id)) yield* notify();
1218
+ return;
1219
+ }
1220
+ let value;
1221
+ try {
1222
+ value = options.decodeValue(update.value);
1223
+ } catch {
1224
+ return;
1225
+ }
1226
+ yield* put(update.id, value, yield* Clock.currentTimeMillis);
1227
+ yield* notify();
1228
+ });
1229
+ const channel = options.channel;
1230
+ const consuming = channel === void 0 ? void 0 : yield* Stream.runForEach(Stream.fromPubSub(channel.updates), receive).pipe(Effect.forkScoped);
1231
+ const set = Effect.fn("Presence.set")(function* (value) {
1232
+ if (yield* Ref.get(closed)) return;
1233
+ yield* put(options.id, value, yield* Clock.currentTimeMillis);
1234
+ if (channel !== void 0) yield* channel.publish({
1235
+ id: options.id,
1236
+ value
1237
+ });
1238
+ yield* notify();
1239
+ });
1240
+ const leave = Effect.fn("Presence.leave")(function* () {
1241
+ if (yield* Ref.get(closed)) return;
1242
+ yield* remove(options.id);
1243
+ if (channel !== void 0) yield* channel.publish({
1244
+ id: options.id,
1245
+ value: null
1246
+ });
1247
+ yield* notify();
1248
+ })();
1249
+ const peerList = Effect.fn("Presence.peers")(function* () {
1250
+ const at = yield* Clock.currentTimeMillis;
1251
+ return [...(yield* Ref.get(peers)).values()].filter((peer) => !expired(peer, at)).map((peer) => ({ ...peer }));
1252
+ })();
1253
+ const prune = Effect.fn("Presence.prune")(function* () {
1254
+ if (yield* Ref.get(closed)) return;
1255
+ const at = yield* Clock.currentTimeMillis;
1256
+ if (yield* Ref.modify(peers, (map) => {
1257
+ let removed = false;
1258
+ const next = new Map(map);
1259
+ for (const [id, peer] of map) if (expired(peer, at)) {
1260
+ next.delete(id);
1261
+ removed = true;
1262
+ }
1263
+ return [removed, next];
1264
+ })) yield* notify();
1265
+ })();
1266
+ const close = Effect.fn("Presence.close")(function* () {
1267
+ if (yield* Ref.get(closed)) return;
1268
+ yield* Ref.set(closed, true);
1269
+ if (consuming !== void 0) yield* Fiber.interrupt(consuming);
1270
+ yield* Effect.sync(() => listeners.clear());
1271
+ yield* PubSub.shutdown(signals);
1272
+ })();
1273
+ return {
1274
+ set,
1275
+ leave,
1276
+ peers: peerList,
1277
+ prune,
1278
+ subscribe: (listener) => {
1279
+ listeners.add(listener);
1280
+ return () => listeners.delete(listener);
1281
+ },
1282
+ changes: Stream.concat(Stream.fromEffect(peerList), Stream.fromPubSub(signals).pipe(Stream.mapEffect(() => peerList))),
1283
+ close
1284
+ };
1285
+ });
1286
+ /** An in-process channel, for tests and single-process demos. */
1287
+ const loopbackPresenceChannel = Effect.fn("Presence.loopbackChannel")(function* () {
1288
+ const updates = yield* PubSub.unbounded();
1289
+ return {
1290
+ updates,
1291
+ publish: (update) => PubSub.publish(updates, update)
1292
+ };
1293
+ });
1294
+ const createPresenceHub = () => {
1295
+ const peers = /* @__PURE__ */ new Set();
1296
+ return {
1297
+ join: (send) => {
1298
+ peers.add(send);
1299
+ return () => peers.delete(send);
1300
+ },
1301
+ publish: (update) => {
1302
+ for (const send of [...peers]) try {
1303
+ send(update);
1304
+ } catch {}
1305
+ }
1306
+ };
1307
+ };
1308
+ const frameType = "presence";
1309
+ /** Decodes a presence frame, ignoring anything else a socket may carry. */
1310
+ const decodePresence = (data) => {
1311
+ let frame;
1312
+ try {
1313
+ frame = JSON.parse(data);
1314
+ } catch {
1315
+ return;
1316
+ }
1317
+ const payload = frame[frameType];
1318
+ if (typeof payload !== "object" || payload === null) return void 0;
1319
+ const { id, value } = payload;
1320
+ return {
1321
+ id: typeof id === "string" ? id : void 0,
1322
+ value: value ?? null
1323
+ };
1324
+ };
1325
+ /**
1326
+ * A presence channel fed by stamped frames from the server, sent back without an
1327
+ * id: the server owns peer identity, so a client cannot assert another's.
1328
+ */
1329
+ const socketPresenceChannel = (socket) => Effect.gen(function* () {
1330
+ const updates = yield* PubSub.unbounded();
1331
+ yield* Effect.acquireRelease(Effect.sync(() => socket.onMessage((data) => {
1332
+ const frame = decodePresence(data);
1333
+ if (frame === void 0 || frame.id === void 0) return;
1334
+ PubSub.publishUnsafe(updates, {
1335
+ id: frame.id,
1336
+ value: frame.value
1337
+ });
1338
+ })), (off) => Effect.sync(off));
1339
+ return {
1340
+ updates,
1341
+ publish: (update) => Effect.sync(() => socket.send(JSON.stringify({ [frameType]: { value: update.value } })))
1342
+ };
1343
+ });
1344
+ /** Serves presence frames on an accepted socket, stamping the connection's identity. */
1345
+ const servePresence = (socket, hub, options) => {
1346
+ const send = (update) => socket.send(JSON.stringify({ [frameType]: {
1347
+ id: update.id,
1348
+ value: update.value
1349
+ } }));
1350
+ const leave = hub.join(send);
1351
+ const off = socket.onMessage((data) => {
1352
+ const frame = decodePresence(data);
1353
+ if (frame !== void 0) hub.publish({
1354
+ id: options.peerId,
1355
+ value: frame.value
1356
+ });
1357
+ });
1358
+ return () => {
1359
+ off();
1360
+ leave();
1361
+ };
1362
+ };
1363
+ //#endregion
1364
+ export { CheckpointRegressionError, CommittedOrderError, DocumentId, ForeignAcknowledgementError, ForeignRejectionError, InvalidExchangeError, InvalidOutboxError, InvalidReplicaHistoryError, LocalSequence, OpId, ReplayError, ReplicaClosedError, ReplicaId, Sequence, StorageError, Transport, TransportError, UnsupportedClockVersionError, UnsupportedReplicaVersionError, WrongReplicaStorageError, createPresence, createPresenceHub, defineSync, documentId, forApplication, indexedDb, layerFromPromise, layerLoopback, layerSocket, localSequence, loopbackPresenceChannel, lwwRegister, mount, nativeSocket, opId, openLwwClock, replicaId, sequence, servePresence, serveSocket, socketPresenceChannel, syncMetrics, toPromise };
950
1365
 
951
1366
  //# sourceMappingURL=index.mjs.map