foldkit-sync 0.1.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,47 +1,21 @@
1
- import { Context, Effect, Layer, Metric, Ref, Schedule, Schema, SynchronizedRef } from "effect";
2
- //#region src/indexedDb.ts
3
- /** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
4
- const indexedDb = async (name, factory = globalThis.indexedDB) => {
5
- const database = await new Promise((resolve, reject) => {
6
- const request = factory.open(name, 1);
7
- request.onupgradeneeded = () => request.result.createObjectStore("replica");
8
- request.onsuccess = () => resolve(request.result);
9
- request.onerror = () => reject(request.error);
10
- });
11
- database.onversionchange = () => database.close();
12
- return {
13
- load: () => new Promise((resolve, reject) => {
14
- const transaction = database.transaction("replica", "readonly");
15
- const request = transaction.objectStore("replica").get("state");
16
- transaction.oncomplete = () => resolve(request.result);
17
- transaction.onabort = () => reject(transaction.error ?? /* @__PURE__ */ new Error("IndexedDB read aborted"));
18
- }),
19
- save: (state, expectedRevision) => new Promise((resolve, reject) => {
20
- const transaction = database.transaction("replica", "readwrite", { durability: "strict" });
21
- const store = transaction.objectStore("replica");
22
- const request = store.get("state");
23
- let conflict = false;
24
- request.onsuccess = () => {
25
- if ((request.result?.revision ?? null) !== expectedRevision) {
26
- conflict = true;
27
- transaction.abort();
28
- return;
29
- }
30
- store.put(state, "state");
31
- };
32
- transaction.oncomplete = () => resolve();
33
- transaction.onabort = () => reject(conflict ? /* @__PURE__ */ new Error("Replica was changed by another writer") : transaction.error ?? /* @__PURE__ */ new Error("IndexedDB write aborted"));
34
- }),
35
- close: () => database.close()
36
- };
37
- };
38
- //#endregion
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";
39
8
  //#region src/errors.ts
40
9
  /** The persisted storage could not be read or written. */
41
10
  var StorageError = class extends Schema.TaggedError()("StorageError", {
42
11
  message: Schema.String,
43
12
  cause: Schema.optional(Schema.Unknown)
44
13
  }) {};
14
+ /** The stored clock state targets a schema version this build does not support. */
15
+ var UnsupportedClockVersionError = class extends Schema.TaggedError()("UnsupportedClockVersionError", {
16
+ schemaVersion: Schema.NullOr(Schema.Number),
17
+ message: Schema.String
18
+ }) {};
45
19
  /** The storage holds a different replica's state. */
46
20
  var WrongReplicaStorageError = class extends Schema.TaggedError()("WrongReplicaStorageError", {
47
21
  documentId: Schema.String,
@@ -53,6 +27,11 @@ var InvalidReplicaHistoryError = class extends Schema.TaggedError()("InvalidRepl
53
27
  message: Schema.String,
54
28
  cause: Schema.optional(Schema.Unknown)
55
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
+ }) {};
56
35
  /** A persisted pending operation could not have been produced by this replica. */
57
36
  var InvalidOutboxError = class extends Schema.TaggedError()("InvalidOutboxError", { message: Schema.String }) {};
58
37
  /** The server sent a checkpoint older than the replica's cursor. */
@@ -72,237 +51,240 @@ var ForeignRejectionError = class extends Schema.TaggedError()("ForeignRejection
72
51
  opId: Schema.String,
73
52
  message: Schema.String
74
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
+ }) {};
75
63
  /** The replica was closed while work was still being submitted. */
76
64
  var ReplicaClosedError = class extends Schema.TaggedError()("ReplicaClosedError", { message: Schema.String }) {};
65
+ /** The stored replica state targets a protocol or schema version this build does not support. */
66
+ var UnsupportedReplicaVersionError = class extends Schema.TaggedError()("UnsupportedReplicaVersionError", {
67
+ protocolVersion: Schema.NullOr(Schema.Number),
68
+ schemaVersion: Schema.NullOr(Schema.Number),
69
+ message: Schema.String
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
+ }) {};
77
79
  //#endregion
78
- //#region src/lww.ts
79
- /** A logical write time; replica ids break concurrent ties using UTF-16 order. */
80
- const Stamp = Schema.Struct({
81
- counter: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)),
82
- replicaId: Schema.NonEmptyString
80
+ //#region src/indexedDb.ts
81
+ const storageError = (message, cause) => new StorageError({
82
+ message: `${message}: ${cause instanceof Error ? cause.message : String(cause)}`,
83
+ cause
83
84
  });
84
- const ClockState = Schema.Struct({
85
- schemaVersion: Schema.Literal(1),
86
- documentId: Schema.NonEmptyString,
87
- replicaId: Stamp.fields.replicaId,
88
- revision: Stamp.fields.counter
85
+ const openDatabase = (name, factory) => Effect.tryPromise({
86
+ try: () => new Promise((resolve, reject) => {
87
+ const request = factory.open(name, 1);
88
+ request.onupgradeneeded = () => request.result.createObjectStore("replica");
89
+ request.onsuccess = () => resolve(request.result);
90
+ request.onerror = () => reject(request.error);
91
+ request.onblocked = () => reject(/* @__PURE__ */ new Error("IndexedDB upgrade is blocked by another connection"));
92
+ }),
93
+ catch: (cause) => storageError("Could not open the storage", cause)
89
94
  });
90
- const decodeClock = Schema.decodeUnknownSync(ClockState, { onExcessProperty: "error" });
91
- const decodeCounter = Schema.decodeUnknownSync(Stamp.fields.counter);
92
- /** Opens a durable clock in its own storage, taking ownership even if opening fails. */
93
- const openLwwClock = async ({ documentId, replicaId, storage }) => {
94
- let state;
95
- try {
96
- const initial = decodeClock({
97
- schemaVersion: 1,
98
- documentId,
99
- replicaId,
100
- revision: 0
101
- });
102
- const saved = await storage.load();
103
- state = saved === void 0 ? initial : decodeClock(saved);
104
- if (state.documentId !== documentId || state.replicaId !== replicaId) throw new Error("Wrong clock storage");
105
- if (saved === void 0) await storage.save(state, null);
106
- } catch (error) {
107
- storage.close();
108
- throw error;
109
- }
110
- let tail = Promise.resolve();
111
- let closing;
95
+ /** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
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))));
98
+ const database = yield* Effect.acquireRelease(openDatabase(databaseName, factory), (database) => Effect.sync(() => database.close()));
99
+ database.onversionchange = () => database.close();
112
100
  return {
113
- next: (observedCounter = 0) => {
114
- if (closing !== void 0) return Promise.reject(/* @__PURE__ */ new Error("Clock is closed"));
115
- const allocation = tail.then(async () => {
116
- const next = decodeClock({
117
- ...state,
118
- revision: Math.max(state.revision, decodeCounter(observedCounter)) + 1
119
- });
120
- await storage.save(next, state.revision);
121
- state = next;
122
- return {
123
- counter: next.revision,
124
- replicaId
101
+ load: () => Effect.tryPromise({
102
+ try: () => new Promise((resolve, reject) => {
103
+ const transaction = database.transaction("replica", "readonly");
104
+ const request = transaction.objectStore("replica").get("state");
105
+ transaction.oncomplete = () => resolve(request.result);
106
+ transaction.onabort = () => reject(transaction.error ?? /* @__PURE__ */ new Error("IndexedDB read aborted"));
107
+ }),
108
+ catch: (cause) => storageError("Could not read the replica", cause)
109
+ }),
110
+ save: (state, expectedRevision) => Effect.tryPromise({
111
+ try: () => new Promise((resolve, reject) => {
112
+ const transaction = database.transaction("replica", "readwrite", { durability: "strict" });
113
+ const store = transaction.objectStore("replica");
114
+ const request = store.get("state");
115
+ let conflict = false;
116
+ request.onsuccess = () => {
117
+ if ((request.result?.revision ?? null) !== expectedRevision) {
118
+ conflict = true;
119
+ transaction.abort();
120
+ return;
121
+ }
122
+ store.put(state, "state");
125
123
  };
126
- });
127
- tail = allocation.then(() => {}, () => {});
128
- return allocation;
129
- },
130
- close: () => closing ??= tail.then(() => storage.close())
131
- };
132
- };
133
- /**
134
- * A schema and reducer helper for a last-writer-wins register.
135
- * Allocate a unique stamp per write before dispatch, and retain it in the Message.
136
- * Merge is for decoded values; the application's schema validates wire input.
137
- */
138
- const lwwRegister = (value) => {
139
- const schema = Schema.Struct({
140
- stamp: Stamp,
141
- value
142
- });
143
- const equivalent = Schema.toEquivalence(value);
144
- const merge = (left, right) => {
145
- if (left.stamp.counter !== right.stamp.counter) return left.stamp.counter > right.stamp.counter ? left : right;
146
- if (left.stamp.replicaId !== right.stamp.replicaId) return left.stamp.replicaId > right.stamp.replicaId ? left : right;
147
- if (!equivalent(left.value, right.value)) throw new Error("Conflicting LWW write identity");
148
- return left;
149
- };
150
- return {
151
- schema,
152
- merge
124
+ transaction.oncomplete = () => resolve();
125
+ transaction.onabort = () => reject(conflict ? /* @__PURE__ */ new Error("Replica was changed by another writer") : transaction.error ?? /* @__PURE__ */ new Error("IndexedDB write aborted"));
126
+ }),
127
+ catch: (cause) => storageError("Could not save the replica", cause)
128
+ }),
129
+ close: Effect.sync(() => database.close())
153
130
  };
154
- };
131
+ });
155
132
  //#endregion
156
- //#region src/presence.ts
133
+ //#region src/mount.ts
157
134
  /**
158
- * Tracks ephemeral peers with a time-to-live.
135
+ * `Sync.mount`: runs a Foldkit application over a replica with one reducer.
159
136
  *
160
- * Nothing here touches the durable log: presence is state a peer refreshes, and
161
- * a peer that stops refreshing is dropped, not replayed.
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.
162
142
  */
163
- const createPresence = (options) => {
164
- const now = options.now ?? (() => Date.now());
165
- const peers = /* @__PURE__ */ new Map();
166
- const listeners = /* @__PURE__ */ new Set();
167
- /** A subscriber must never fail an update. */
168
- const notify = () => {
169
- for (const listener of [...listeners]) try {
170
- listener();
171
- } catch {}
172
- };
173
- const expired = (peer, at) => at - peer.updatedAt > options.ttl;
174
- const receive = (update) => {
175
- if (update.id === options.id) return;
176
- if (update.value === null) {
177
- if (peers.delete(update.id)) notify();
178
- return;
179
- }
180
- let value;
181
- try {
182
- value = options.decodeValue(update.value);
183
- } catch {
184
- return;
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
+ }
185
205
  }
186
- peers.set(update.id, {
187
- id: update.id,
188
- value,
189
- updatedAt: now()
190
- });
191
- notify();
192
206
  };
193
- const unsubscribe = options.channel?.subscribe(receive);
194
- return {
195
- set: (value) => {
196
- peers.set(options.id, {
197
- id: options.id,
198
- value,
199
- updatedAt: now()
200
- });
201
- options.channel?.publish({
202
- id: options.id,
203
- value
204
- });
205
- notify();
206
- },
207
- leave: () => {
208
- peers.delete(options.id);
209
- options.channel?.publish({
210
- id: options.id,
211
- value: null
212
- });
213
- notify();
214
- },
215
- peers: () => {
216
- const at = now();
217
- return [...peers.values()].filter((peer) => !expired(peer, at)).map((peer) => ({ ...peer }));
218
- },
219
- prune: () => {
220
- const at = now();
221
- let changed = false;
222
- for (const [id, peer] of peers) if (expired(peer, at)) {
223
- peers.delete(id);
224
- changed = true;
225
- }
226
- if (changed) notify();
227
- },
228
- subscribe: (listener) => {
229
- listeners.add(listener);
230
- return () => listeners.delete(listener);
231
- },
232
- close: () => {
233
- unsubscribe?.();
234
- listeners.clear();
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
235
219
  }
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
236
231
  };
237
- };
238
- /** An in-process channel, for tests and single-process demos. */
239
- const loopbackPresenceChannel = () => {
240
- const listeners = /* @__PURE__ */ new Set();
241
- return {
242
- publish: (update) => {
243
- for (const listener of [...listeners]) try {
244
- listener(update);
245
- } catch {}
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)
246
244
  },
247
- subscribe: (listener) => {
248
- listeners.add(listener);
249
- return () => listeners.delete(listener);
245
+ init: (at) => {
246
+ latest = url.init === void 0 ? latest : url.init(latest, at);
247
+ return { model: latest };
250
248
  }
251
- };
252
- };
253
- const createPresenceHub = () => {
254
- const peers = /* @__PURE__ */ new Set();
249
+ });
250
+ const handle = Runtime.embed(program);
255
251
  return {
256
- join: (send) => {
257
- peers.add(send);
258
- return () => peers.delete(send);
252
+ dispatch: (message) => handle.ports.message.send(message),
253
+ model: () => latest,
254
+ subscribe: (listener) => {
255
+ modelListeners.add(listener);
256
+ return () => modelListeners.delete(listener);
259
257
  },
260
- publish: (update) => {
261
- for (const send of [...peers]) try {
262
- send(update);
263
- } catch {}
258
+ observe: (listener) => {
259
+ messageListeners.add(listener);
260
+ return () => messageListeners.delete(listener);
261
+ },
262
+ dispose: async () => {
263
+ await Promise.all([...inFlight]);
264
+ handle.dispose();
264
265
  }
265
266
  };
266
267
  };
267
- const frameType = "presence";
268
- /** Decodes a presence frame, ignoring anything else a socket may carry. */
269
- const decodePresence = (data) => {
270
- let frame;
271
- try {
272
- frame = JSON.parse(data);
273
- } catch {
274
- return;
275
- }
276
- const value = frame[frameType];
277
- if (typeof value !== "object" || value === null) return void 0;
278
- const { id, value: payload } = value;
279
- if (typeof id !== "string") return void 0;
280
- return {
281
- id,
282
- value: payload ?? null
283
- };
284
- };
285
- /** A presence channel carried on a socket, alongside exchange frames. */
286
- const socketPresenceChannel = (socket) => ({
287
- publish: (update) => socket.send(JSON.stringify({ [frameType]: update })),
288
- subscribe: (listener) => socket.onMessage((data) => {
289
- const update = decodePresence(data);
290
- if (update !== void 0) listener(update);
291
- })
292
- });
293
- /** Serves presence frames on an accepted socket, fanning them through the hub. */
294
- const servePresence = (socket, hub) => {
295
- const send = (update) => socket.send(JSON.stringify({ [frameType]: update }));
296
- const leave = hub.join(send);
297
- const off = socket.onMessage((data) => {
298
- const update = decodePresence(data);
299
- if (update !== void 0) hub.publish(update);
300
- });
301
- return () => {
302
- off();
303
- leave();
304
- };
305
- };
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);
306
288
  //#endregion
307
289
  //#region src/transport.ts
308
290
  /** The wire failure of a transport. A refusal is a result, not an error. */
@@ -323,7 +305,7 @@ const layerLoopback = (handler) => Layer.succeed(Transport, { exchange: (cursor,
323
305
  }) });
324
306
  /** Wraps the promise-based client the replica already speaks. */
325
307
  const layerFromPromise = (transport) => Layer.succeed(Transport, { exchange: (cursor, pending) => Effect.tryPromise({
326
- try: () => transport.exchange(cursor, pending),
308
+ try: () => transport.exchange(sequence(cursor), pending),
327
309
  catch: failure
328
310
  }) });
329
311
  /** Bridges the service back to the promise client the replica consumes. */
@@ -421,7 +403,7 @@ const nativeSocket = (url) => {
421
403
  * with a `TransportError`; a queue over `maxQueue` fails new exchanges with
422
404
  * backpressure. The socket is released when the layer's scope ends.
423
405
  */
424
- const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* () {
406
+ const layerSocket = (options) => Layer.effect(Transport, Effect.fn("Transport.layerSocket")(function* () {
425
407
  const makeSocket = options.makeSocket ?? nativeSocket;
426
408
  const maxQueue = options.maxQueue ?? 64;
427
409
  const retry = Schedule.exponential(options.retryBase ?? "50 millis").pipe(Schedule.jittered, Schedule.upTo({ times: options.maxRetries ?? 5 }));
@@ -431,6 +413,7 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
431
413
  let ready = false;
432
414
  let nextId = 0;
433
415
  let disposed = false;
416
+ let terminalError;
434
417
  const send = (entry) => {
435
418
  inFlight.set(entry.id, entry);
436
419
  socket?.send(JSON.stringify({
@@ -487,7 +470,9 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
487
470
  catch: () => new TransportError({ message: "transport closed" })
488
471
  });
489
472
  yield* Effect.forkScoped(connect.pipe(Effect.retry(retry), Effect.catch((error) => Effect.sync(() => {
490
- if (!disposed) failAll(error.message);
473
+ if (disposed) return;
474
+ terminalError = error;
475
+ failAll(error.message);
491
476
  }))));
492
477
  yield* Effect.addFinalizer(() => Effect.sync(() => {
493
478
  disposed = true;
@@ -496,11 +481,15 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
496
481
  socket = void 0;
497
482
  failAll("transport closed");
498
483
  }));
499
- return { exchange: (cursor, pending) => Effect.callback((resume) => {
484
+ return Transport.of({ exchange: (cursor, pending) => Effect.callback((resume) => {
500
485
  if (disposed) {
501
486
  resume(Effect.fail(new TransportError({ message: "transport closed" })));
502
487
  return;
503
488
  }
489
+ if (terminalError !== void 0) {
490
+ resume(Effect.fail(terminalError));
491
+ return;
492
+ }
504
493
  if (queued.length + inFlight.size >= maxQueue) {
505
494
  resume(Effect.fail(new TransportError({ message: "transport queue full" })));
506
495
  return;
@@ -513,19 +502,26 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
513
502
  };
514
503
  if (ready) send(entry);
515
504
  else queued.push(entry);
516
- }) };
517
- }));
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
+ })());
518
512
  //#endregion
519
513
  //#region src/sync.ts
520
- const Sequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
514
+ /** Wire and persisted-format versions. A bump must handle the older value explicitly. */
515
+ const PROTOCOL_VERSION = 1;
516
+ const SCHEMA_VERSION = 1;
521
517
  /** A client-authored operation envelope. `message` is the application's encoded Message. */
522
518
  const OperationSchema = Schema.Struct({
523
- protocolVersion: Schema.Literal(1),
524
- schemaVersion: Schema.Literal(1),
525
- documentId: Schema.NonEmptyString,
526
- replicaId: Schema.NonEmptyString,
527
- localSequence: Sequence,
528
- opId: Schema.NonEmptyString,
519
+ protocolVersion: Schema.Literal(PROTOCOL_VERSION),
520
+ schemaVersion: Schema.Literal(SCHEMA_VERSION),
521
+ documentId: DocumentId,
522
+ replicaId: ReplicaId,
523
+ localSequence: LocalSequence,
524
+ opId: OpId,
529
525
  baseCursor: Sequence,
530
526
  message: Schema.Unknown
531
527
  });
@@ -551,11 +547,6 @@ const syncMetrics = {
551
547
  1024
552
548
  ] })
553
549
  };
554
- /** Keeps the storage driver's message visible on the typed failure. */
555
- const storageError = (context, cause) => new StorageError({
556
- message: `${context}: ${cause instanceof Error ? cause.message : String(cause)}`,
557
- cause
558
- });
559
550
  /**
560
551
  * Binds the replicated-state protocol to one application contract.
561
552
  *
@@ -567,13 +558,15 @@ const defineSync = (definition) => {
567
558
  const documentId = definition.documentId;
568
559
  const decodeMessage = Schema.decodeUnknownSync(definition.message, { onExcessProperty: "error" });
569
560
  const encodeMessage = Schema.encodeSync(definition.message);
561
+ const decodeShared = Schema.decodeUnknownSync(definition.shared, { onExcessProperty: "error" });
562
+ const encodeShared = Schema.encodeSync(definition.shared);
570
563
  const ReplicaStateSchema = Schema.Struct({
571
- protocolVersion: Schema.Literal(1),
572
- schemaVersion: Schema.Literal(1),
573
- documentId: Schema.NonEmptyString,
574
- replicaId: Schema.NonEmptyString,
575
- revision: Sequence,
576
- nextLocalSequence: Sequence,
564
+ protocolVersion: Schema.Literal(PROTOCOL_VERSION),
565
+ schemaVersion: Schema.Literal(SCHEMA_VERSION),
566
+ documentId: DocumentId,
567
+ replicaId: ReplicaId,
568
+ revision: Schema.Number,
569
+ nextLocalSequence: LocalSequence,
577
570
  cursor: Sequence,
578
571
  committed: definition.shared,
579
572
  committedIds: Schema.Array(Schema.String),
@@ -585,14 +578,39 @@ const defineSync = (definition) => {
585
578
  });
586
579
  const ExchangeSchema = Schema.Struct({
587
580
  operations: Schema.Array(Schema.Unknown),
588
- rejected: Schema.Array(Schema.NonEmptyString),
589
- acknowledged: Schema.optional(Schema.Array(Schema.NonEmptyString)),
581
+ rejected: Schema.Array(OpId),
582
+ acknowledged: Schema.optional(Schema.Array(OpId)),
590
583
  checkpoint: Schema.optional(CheckpointSchema)
591
584
  });
592
585
  const decodeState = Schema.decodeUnknownSync(ReplicaStateSchema, { onExcessProperty: "error" });
586
+ const encodeState = Schema.encodeSync(ReplicaStateSchema);
587
+ const VersionProbe = Schema.Struct({
588
+ protocolVersion: Schema.optional(Schema.Number),
589
+ schemaVersion: Schema.optional(Schema.Number)
590
+ });
591
+ /**
592
+ * Tells a version this build does not understand apart from malformed data,
593
+ * so the caller gets an actionable failure and the stored state is preserved.
594
+ */
595
+ const unsupportedVersion = (input) => {
596
+ let found;
597
+ try {
598
+ found = Schema.decodeUnknownSync(VersionProbe)(input);
599
+ } catch {
600
+ return;
601
+ }
602
+ if (found.protocolVersion === PROTOCOL_VERSION && found.schemaVersion === SCHEMA_VERSION) return void 0;
603
+ const protocolVersion = found.protocolVersion ?? null;
604
+ const schemaVersion = found.schemaVersion ?? null;
605
+ return new UnsupportedReplicaVersionError({
606
+ protocolVersion,
607
+ schemaVersion,
608
+ message: `Stored replica uses protocol ${protocolVersion ?? "?"} / schema ${schemaVersion ?? "?"}; this build supports ${PROTOCOL_VERSION}/${SCHEMA_VERSION}`
609
+ });
610
+ };
593
611
  const decodeExchange = (input) => Schema.decodeUnknownSync(ExchangeSchema, { onExcessProperty: "error" })(input);
594
612
  const checkIdentity = (operation) => {
595
- 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");
596
614
  };
597
615
  const decodeDurable = (message) => {
598
616
  const decoded = decodeMessage(message);
@@ -626,27 +644,40 @@ const defineSync = (definition) => {
626
644
  };
627
645
  };
628
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
+ });
629
659
  const optimistic = (state) => state.pending.reduce((model, operation) => definition.replay(model, decodeMessage(operation.message)), state.committed);
630
- const openReplica = (replicaId, storage) => Effect.gen(function* () {
631
- const saved = yield* Effect.tryPromise({
632
- try: () => storage.load(),
633
- catch: (cause) => storageError("Could not read the replica", cause)
660
+ const openReplica = Effect.fn("Sync.openReplica")(function* (replicaId, storage) {
661
+ yield* Effect.annotateCurrentSpan({
662
+ documentId,
663
+ replicaId
634
664
  });
665
+ const saved = yield* storage.load();
635
666
  const initial = {
636
- protocolVersion: 1,
637
- schemaVersion: 1,
667
+ protocolVersion: PROTOCOL_VERSION,
668
+ schemaVersion: SCHEMA_VERSION,
638
669
  documentId,
639
670
  replicaId,
640
671
  revision: 0,
641
- nextLocalSequence: 1,
642
- cursor: 0,
672
+ nextLocalSequence: localSequence(1),
673
+ cursor: sequence(0),
643
674
  committed: definition.empty,
644
675
  committedIds: [],
645
676
  pending: []
646
677
  };
647
678
  const state = saved === void 0 ? initial : yield* Effect.try({
648
679
  try: () => decodeState(saved),
649
- catch: (cause) => new InvalidReplicaHistoryError({
680
+ catch: (cause) => unsupportedVersion(saved) ?? new InvalidReplicaHistoryError({
650
681
  message: "Stored replica state is invalid",
651
682
  cause
652
683
  })
@@ -667,60 +698,118 @@ const defineSync = (definition) => {
667
698
  if (operation.replicaId !== replicaId || operation.localSequence >= state.nextLocalSequence || committedIds.has(operation.opId) || pendingIds.has(operation.opId)) return yield* new InvalidOutboxError({ message: "Invalid outbox" });
668
699
  pendingIds.add(operation.opId);
669
700
  }
670
- if (saved === void 0) yield* Effect.tryPromise({
671
- try: () => storage.save(state, null),
672
- catch: (cause) => storageError("Could not save the replica", cause)
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);
673
710
  });
711
+ if (saved === void 0) yield* store(state, null);
674
712
  const stateRef = yield* SynchronizedRef.make(state);
675
713
  const closed = yield* Ref.make(false);
676
- const persist = (next, current) => Effect.tryPromise({
677
- try: () => storage.save(next, current.revision),
678
- catch: (cause) => storageError("Could not save the replica", cause)
679
- });
680
- const submit = (message) => SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
681
- if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
682
- const operation = yield* Effect.try({
683
- try: () => operationFrom({
684
- protocolVersion: 1,
685
- schemaVersion: 1,
686
- documentId,
687
- replicaId,
688
- localSequence: current.nextLocalSequence,
689
- opId: `${replicaId}:${current.nextLocalSequence}`,
690
- baseCursor: current.cursor,
691
- message: encodeMessage(message)
692
- }, documentId),
693
- catch: () => new InvalidOutboxError({ message: "Invalid outbox" })
714
+ const lastError = yield* Ref.make(void 0);
715
+ const rejectedOps = yield* Ref.make([]);
716
+ const wake = yield* Queue.sliding(1);
717
+ const statusSignals = yield* PubSub.sliding(1);
718
+ const projection = yield* Ref.make(void 0);
719
+ const snapshot = Effect.fn("Sync.snapshot")(function* () {
720
+ const current = yield* SynchronizedRef.get(stateRef);
721
+ const cached = yield* Ref.get(projection);
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
+ },
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
694
748
  });
695
- const next = yield* Effect.try({
696
- 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 = {
697
773
  ...current,
698
774
  revision: current.revision + 1,
699
- nextLocalSequence: current.nextLocalSequence + 1,
775
+ nextLocalSequence: localSequence(current.nextLocalSequence + 1),
700
776
  pending: [...current.pending, operation]
701
- }),
702
- catch: (cause) => new InvalidReplicaHistoryError({
703
- message: "Invalid replica state",
704
- cause
705
- })
706
- });
707
- yield* persist(next, current);
708
- return [void 0, next];
709
- })).pipe(Effect.withSpan("Sync.submit", { attributes: {
710
- documentId,
711
- replicaId
712
- } }));
713
- 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 });
714
791
  const transport = yield* Transport;
715
792
  if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
716
793
  const sent = yield* SynchronizedRef.get(stateRef);
717
794
  yield* Metric.update(syncMetrics.exchanges, 1);
718
795
  yield* Metric.update(syncMetrics.exchangePending, sent.pending.length);
719
- const response = decodeExchange(yield* transport.exchange(sent.cursor, sent.pending).pipe(Effect.tapError((error) => Effect.logWarning("sync exchange failed", {
720
- documentId,
721
- replicaId,
722
- error: error.message
723
- }))));
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* () {
806
+ yield* Effect.logWarning("sync exchange failed", {
807
+ documentId,
808
+ replicaId,
809
+ error: error.message
810
+ });
811
+ yield* Ref.set(lastError, error.message);
812
+ })));
724
813
  yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
725
814
  if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
726
815
  let cursor = current.cursor;
@@ -744,10 +833,20 @@ const defineSync = (definition) => {
744
833
  const acknowledged = new Set(response.acknowledged ?? []);
745
834
  const rejected = new Set(response.rejected);
746
835
  const sentIds = new Set(sent.pending.map((operation) => operation.opId));
747
- 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({
748
837
  opId: id,
749
- message: "Server rejected an operation that was not sent"
838
+ message: "Server acknowledged an operation that was not sent"
750
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
+ }
751
850
  let applied = 0;
752
851
  for (const raw of response.operations) {
753
852
  const { committed: operation, message } = yield* Effect.try({
@@ -769,49 +868,499 @@ const defineSync = (definition) => {
769
868
  applied += 1;
770
869
  }
771
870
  if (applied > 0) yield* Metric.update(syncMetrics.applied, applied);
772
- const next = yield* Effect.try({
773
- try: () => decodeState({
774
- ...current,
775
- revision: current.revision + 1,
776
- committed,
777
- cursor,
778
- committedIds: [...ids].slice(-1024),
779
- pending: current.pending.filter((operation) => !ids.has(operation.opId) && !acknowledged.has(operation.opId) && !rejected.has(operation.opId))
780
- }),
781
- catch: (cause) => new InvalidReplicaHistoryError({
782
- message: "Invalid replica state",
783
- cause
784
- })
785
- });
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
+ };
786
879
  yield* persist(next, current);
787
880
  return [void 0, next];
788
881
  }));
789
- }).pipe(Effect.withSpan("Sync.synchronize", { attributes: { documentId } }));
882
+ yield* Ref.set(lastError, void 0);
883
+ if (response.rejected.length > 0) yield* Ref.update(rejectedOps, (previous) => [...response.rejected, ...previous].slice(0, 32));
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
+ });
790
894
  return {
791
- shared: Effect.map(SynchronizedRef.get(stateRef), optimistic),
895
+ shared,
792
896
  pending: Effect.map(SynchronizedRef.get(stateRef), (state) => state.pending),
793
897
  cursor: Effect.map(SynchronizedRef.get(stateRef), (state) => state.cursor),
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))),
794
901
  submit,
795
902
  synchronize,
796
- close: Effect.gen(function* () {
903
+ start,
904
+ close: Effect.fn("Sync.close")(function* () {
797
905
  yield* Ref.set(closed, true);
798
- yield* Effect.sync(() => storage.close());
799
- })
906
+ yield* Queue.offer(wake, void 0);
907
+ yield* storage.close;
908
+ })()
800
909
  };
801
- }).pipe(Effect.withSpan("Sync.openReplica", { attributes: {
802
- documentId,
803
- replicaId
804
- } }));
910
+ }, (effect, _replicaId, storage) => effect.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : storage.close.pipe(Effect.ignore))));
805
911
  return {
806
912
  documentId,
807
- normalizeOperation,
808
- operationFrom,
809
- committedFrom,
810
- decodeExchange,
913
+ codec: {
914
+ normalizeOperation,
915
+ operationFrom,
916
+ committedFrom,
917
+ decodeExchange
918
+ },
919
+ journalContract,
811
920
  openReplica
812
921
  };
813
922
  };
814
923
  //#endregion
815
- export { CheckpointRegressionError, CommittedOrderError, ForeignRejectionError, InvalidOutboxError, InvalidReplicaHistoryError, ReplicaClosedError, StorageError, Transport, TransportError, WrongReplicaStorageError, createPresence, createPresenceHub, defineSync, indexedDb, layerFromPromise, layerLoopback, layerSocket, loopbackPresenceChannel, lwwRegister, nativeSocket, openLwwClock, 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 };
816
1365
 
817
1366
  //# sourceMappingURL=index.mjs.map