@evolu/common 6.0.1-preview.3 → 6.0.1-preview.31

package/dist/src/Evolu/Sync.js

@@ -1,29 +1,450 @@
-import { createWebSocket } from "../WebSocket.js";
-export const createWebSocketSync = (_deps) => (config) => {
+import { firstInArray, isNonEmptyReadonlyArray, } from "../Array.js";
+import { assert } from "../Assert.js";
+import { eqArrayNumber } from "../Eq.js";
+import { createTransferableError } from "../Error.js";
+import { constFalse, constTrue } from "../Function.js";
+import { objectToEntries } from "../Object.js";
+import { createResources } from "../Resources.js";
+import { err, ok } from "../Result.js";
+import { sql } from "../Sqlite.js";
+import { createMutex } from "../Task.js";
+import { idBytesToId, idToIdBytes } from "../Type.js";
+import { ownerIdBytesToOwnerId, ownerIdToOwnerIdBytes, } from "./Owner.js";
+import { applyProtocolMessageAsClient, createProtocolMessageForSync, createProtocolMessageForUnsubscribe, createProtocolMessageFromCrdtMessages, decryptAndDecodeDbChange, encodeAndEncryptDbChange, SubscriptionFlags, } from "./Protocol.js";
+import { createBaseSqliteStorage, getOwnerUsage, getTimestampInsertStrategy, updateOwnerUsage, } from "./Storage.js";
+import { createInitialTimestamp, receiveTimestamp, sendTimestamp, timestampBytesToTimestamp, timestampToTimestampBytes, timestampToTimestampString, } from "./Timestamp.js";
+export const createSync = (deps) => (config) => {
+    let isDisposed = false;
+    /** Returns owner data only if actively assigned to at least one transport. */
+    const getSyncOwner = (ownerId) => {
+        if (isDisposed)
+            return null;
+        return transports.getConsumer(ownerId);
+    };
+    const storageResult = createClientStorage({
+        ...deps,
+        getSyncOwner,
+    })(config);
+    if (!storageResult.ok)
+        return storageResult;
+    const storage = storageResult.value;
+    const createResource = (transportConfig) => {
+        const transportKey = createTransportKey(transportConfig);
+        deps.console.log("[sync]", "createWebSocket", {
+            transportKey,
+            url: transportConfig.url,
+        });
+        return deps.createWebSocket(transportConfig.url, {
+            binaryType: "arraybuffer",
+            onOpen: () => {
+                if (isDisposed)
+                    return;
+                const webSocket = transports.getResource(transportKey);
+                if (!webSocket)
+                    return;
+                const ownerIds = transports.getConsumersForResource(transportKey);
+                deps.console.log("[sync]", "onOpen", { transportKey, ownerIds });
+                for (const ownerId of ownerIds) {
+                    const message = createProtocolMessageForSync({ storage })(ownerId, SubscriptionFlags.Subscribe);
+                    if (!message)
+                        continue;
+                    deps.console.log("[sync]", "send", { message });
+                    webSocket.send(message);
+                }
+            },
+            onClose: (event) => {
+                deps.console.log("[sync]", "onClose", {
+                    transportKey,
+                    code: event.code,
+                    reason: event.reason,
+                    wasClean: event.wasClean,
+                });
+            },
+            onError: (error) => {
+                deps.console.warn("[sync]", "onError", { transportKey, error });
+            },
+            onMessage: (data) => {
+                // Only handle ArrayBuffer data for sync messages
+                if (isDisposed || !(data instanceof ArrayBuffer))
+                    return;
+                const webSocket = transports.getResource(transportKey);
+                if (!webSocket)
+                    return;
+                const input = new Uint8Array(data);
+                deps.console.log("[sync]", "onMessage", {
+                    transportKey,
+                    message: input,
+                });
+                applyProtocolMessageAsClient({ storage })(input, {
+                    // No write key, no sync (for a case when an owner was unused).
+                    getWriteKey: (ownerId) => getSyncOwner(ownerId)?.writeKey ?? null,
+                })
+                    .then((message) => {
+                    if (!message.ok) {
+                        config.onError(message.error);
+                        return;
+                    }
+                    switch (message.value.type) {
+                        case "response":
+                            webSocket.send(message.value.message);
+                            break;
+                        case "no-response":
+                            // Sync complete, no response needed
+                            break;
+                        case "broadcast":
+                            // This was a broadcast message, don't affect sync counter
+                            break;
+                    }
+                })
+                    .catch((error) => {
+                    config.onError(createTransferableError(error));
+                });
+            },
+        });
+    };
+    const transports = createResources({
+        createResource,
+        getResourceKey: createTransportKey,
+        getConsumerId: (owner) => owner.id,
+        disposalDelay: config.disposalDelayMs ?? 100,
+        onConsumerAdded: (owner, webSocket) => {
+            deps.console.log("[sync]", "onConsumerAdded", {
+                ownerId: owner.id,
+                isOpen: webSocket.isOpen(),
+            });
+            // The onOpen handler will sync it.
+            if (!webSocket.isOpen())
+                return;
+            const message = createProtocolMessageForSync({ storage })(owner.id, SubscriptionFlags.Subscribe);
+            if (message)
+                webSocket.send(message);
+        },
+        onConsumerRemoved: (owner, webSocket) => {
+            deps.console.log("[sync]", "onConsumerRemoved", {
+                ownerId: owner.id,
+                isOpen: webSocket.isOpen(),
+            });
+            const message = createProtocolMessageForUnsubscribe(owner.id);
+            webSocket.send(message);
+        },
+    });
     const sync = {
-        send: (message) => {
-            /**
-             * We don't need an in-memory queue; apps can be offline for a long time,
-             * and mutations are stored in SQLite. Dropped CRDT messages are synced
-             * when the web socket connection is open.
-             */
-            if (socket.getReadyState() !== "open")
+        useOwner: (use, owner) => {
+            if (isDisposed) {
+                deps.console.warn("[sync]", "useOwner called on disposed Sync instance", { owner });
                 return;
-            socket.send(message);
+            }
+            deps.console.log("[sync]", "useOwner", { use, owner });
+            const transportsToUse = owner.transports ?? config.transports;
+            if (use) {
+                transports.addConsumer(owner, transportsToUse);
+            }
+            else {
+                const result = transports.removeConsumer(owner, transportsToUse);
+                if (!result.ok) {
+                    deps.console.warn("[sync]", "Failed to remove consumer", {
+                        transportsToUse,
+                        ownerId: owner.id,
+                        error: result.error,
+                    });
+                }
+            }
+        },
+        applyChanges: (changes) => {
+            deps.console.log("[sync]", "applyChanges", { changes });
+            let clockTimestamp = deps.clock.get();
+            const ownerMessages = new Map();
+            for (const change of changes) {
+                const nextTimestamp = sendTimestamp(deps)(clockTimestamp);
+                if (!nextTimestamp.ok)
+                    return nextTimestamp;
+                clockTimestamp = nextTimestamp.value;
+                const { ownerId = config.appOwner.id, ...dbChange } = change;
+                const message = { timestamp: clockTimestamp, change: dbChange };
+                const messages = ownerMessages.get(ownerId);
+                if (messages)
+                    messages.push(message);
+                else
+                    ownerMessages.set(ownerId, [message]);
+            }
+            for (const [ownerId, messages] of ownerMessages) {
+                const result = applyMessages({ ...deps, storage })(ownerId, messages);
+                if (!result.ok)
+                    return result;
+                const owner = getSyncOwner(ownerId);
+                if (!owner?.writeKey)
+                    continue;
+                const message = createProtocolMessageFromCrdtMessages(deps)({
+                    id: owner.id,
+                    encryptionKey: owner.encryptionKey,
+                    writeKey: owner.writeKey,
+                }, messages);
+                const transportsToUse = owner.transports ?? config.transports;
+                // Send message to all transports for this owner
+                for (const transportConfig of transportsToUse) {
+                    const transportKey = createTransportKey(transportConfig);
+                    const webSocket = transports.getResource(transportKey);
+                    if (!webSocket)
+                        continue;
+                    if (webSocket.isOpen()) {
+                        deps.console.log("[sync]", "send", { transportKey, message });
+                        webSocket.send(message);
+                    }
+                }
+            }
+            return deps.clock.save(clockTimestamp);
+        },
+        [Symbol.dispose]: () => {
+            if (isDisposed)
+                return;
+            isDisposed = true;
+            transports[Symbol.dispose]();
         },
     };
-    const socket = createWebSocket(config.syncUrl, {
-        binaryType: "arraybuffer",
-        onOpen: () => {
-            config.onOpen(sync.send);
+    return ok(sync);
+};
+export const createClock = (deps) => (initialTimestamp = createInitialTimestamp(deps)) => {
+    let currentTimestamp = initialTimestamp;
+    return {
+        get: () => currentTimestamp,
+        save: (timestamp) => {
+            currentTimestamp = timestamp;
+            const timestampString = timestampToTimestampString(timestamp);
+            const result = deps.sqlite.exec(sql.prepared `
+          update evolu_config set "clock" = ${timestampString};
+        `);
+            if (!result.ok)
+                return result;
+            return ok();
         },
-        onMessage: (data) => {
-            if (data instanceof ArrayBuffer) {
-                const messages = new Uint8Array(data);
-                config.onMessage(messages, sync.send);
+    };
+};
+const createClientStorage = (deps) => (config) => {
+    const sqliteStorageBase = createBaseSqliteStorage(deps)({
+        onStorageError: config.onError,
+        isOwnerWithinQuota: constTrue, // Clients don't have quota limits
+    });
+    // TODO: Mutex per OwnerId
+    const mutex = createMutex();
+    const storage = {
+        ...sqliteStorageBase,
+        // Not implemented yet.
+        validateWriteKey: constFalse,
+        setWriteKey: constFalse,
+        writeMessages: async (ownerIdBytes, encryptedMessages) => {
+            const ownerId = ownerIdBytesToOwnerId(ownerIdBytes);
+            // Everything is sync now, but we will need async crypto in the future.
+            const writeResult = await mutex.withLock(async () => {
+                const owner = deps.getSyncOwner(ownerId);
+                // Owner can be removed during syncing.
+                // `ok(true)` means success, we just skipped the write.
+                if (!owner)
+                    return ok(true);
+                // TODO: Add quota checking for collaborative scenarios.
+                // When receiving messages from other owners via relay broadcast,
+                // check if this owner is within quota before accepting the data.
+                // This prevents an owner from exceeding storage limits when receiving
+                // data shared by other collaborators.
+                const messages = [];
+                for (const message of encryptedMessages) {
+                    const change = decryptAndDecodeDbChange(deps)(message, owner.encryptionKey);
+                    if (!change.ok)
+                        return change;
+                    messages.push({
+                        timestamp: message.timestamp,
+                        change: change.value,
+                    });
+                }
+                const transaction = deps.sqlite.transaction(() => {
+                    let clockTimestamp = deps.clock.get();
+                    for (const message of messages) {
+                        const nextTimestamp = receiveTimestamp(deps)(clockTimestamp, message.timestamp);
+                        if (!nextTimestamp.ok)
+                            return nextTimestamp;
+                        clockTimestamp = nextTimestamp.value;
+                    }
+                    if (isNonEmptyReadonlyArray(messages)) {
+                        const applyMessagesResult = applyMessages({ ...deps, storage })(owner.id, messages);
+                        if (!applyMessagesResult.ok)
+                            return applyMessagesResult;
+                    }
+                    // // Apply local mutations atomically with approved messages
+                    // for (const change of localMutations) {
+                    //   const result = applyLocalOnlyChange(deps)(change);
+                    //   if (!result.ok) return result;
+                    // }
+                    return deps.clock.save(clockTimestamp);
+                });
+                if (!transaction.ok)
+                    return transaction;
+                return ok(true);
+            })();
+            if (!writeResult.ok) {
+                if (writeResult.error.type !== "AbortError") {
+                    config.onError(writeResult.error);
+                }
+                return err({ type: "StorageWriteError", ownerId });
             }
+            config.onReceive();
+            return ok();
         },
-    });
-    return sync;
+        readDbChange: (ownerId, timestamp) => {
+            const owner = deps.getSyncOwner(ownerIdBytesToOwnerId(ownerId));
+            // Owner can be removed to stop syncing.
+            if (!owner)
+                return null;
+            const result = deps.sqlite.exec(sql `
+          select "table", "id", "column", "value"
+          from evolu_history
+          where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
+        `);
+            if (!result.ok) {
+                config.onError(result.error);
+                return null;
+            }
+            const { rows } = result.value;
+            assert(rows.length > 0, "Rows must not be empty");
+            const { table, id } = rows[0];
+            const values = {};
+            for (const r of rows) {
+                assert(r.table === table, "All rows must have the same table");
+                assert(eqArrayNumber(r.id, id), "All rows must have the same Id");
+                values[r.column] = r.value;
+            }
+            const message = {
+                timestamp: timestampBytesToTimestamp(timestamp),
+                change: {
+                    table: rows[0].table,
+                    id: idBytesToId(rows[0].id),
+                    values,
+                },
+            };
+            return encodeAndEncryptDbChange(deps)(message, owner.encryptionKey);
+        },
+    };
+    return ok(storage);
+};
+/** Creates a unique identifier for a transport configuration. */
+const createTransportKey = (transportConfig) => {
+    return `${transportConfig.type}:${transportConfig.url}`;
+};
+export const applyLocalOnlyChange = (deps) => (change) => {
+    const dbChange = {
+        table: change.table,
+        id: change.id,
+        values: change.values,
+    };
+    const isDeletion = "isDeleted" in dbChange.values && dbChange.values.isDeleted === 1;
+    if (isDeletion) {
+        const result = deps.sqlite.exec(sql `
+        delete from ${sql.identifier(dbChange.table)}
+        where id = ${dbChange.id};
+      `);
+        if (!result.ok)
+            return result;
+    }
+    else {
+        const date = new Date(deps.time.now()).toISOString();
+        for (const [column, value] of objectToEntries(dbChange.values)) {
+            const result = deps.sqlite.exec(sql.prepared `
+          insert into ${sql.identifier(dbChange.table)}
+            ("id", ${sql.identifier(column)}, createdAt, updatedAt)
+          values (${dbChange.id}, ${value}, ${date}, ${date})
+          on conflict ("id") do update
+            set
+              ${sql.identifier(column)} = ${value},
+              updatedAt = ${date};
+        `);
+            if (!result.ok)
+                return result;
+        }
+    }
+    return ok();
+};
+const applyMessages = (deps) => (ownerId, messages) => {
+    const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
+    const usageResult = getOwnerUsage(deps)(ownerIdBytes, timestampToTimestampBytes(firstInArray(messages).timestamp));
+    if (!usageResult.ok)
+        return usageResult;
+    let { firstTimestamp, lastTimestamp } = usageResult.value;
+    for (const message of messages) {
+        const result1 = applyMessageToAppTable(deps)(ownerIdBytes, message);
+        if (!result1.ok)
+            return result1;
+        const timestamp = timestampToTimestampBytes(message.timestamp);
+        let strategy;
+        [strategy, firstTimestamp, lastTimestamp] = getTimestampInsertStrategy(timestamp, firstTimestamp, lastTimestamp);
+        const result2 = applyMessageToTimestampAndHistoryTables(deps)(ownerIdBytes, message, strategy);
+        if (!result2.ok)
+            return result2;
+    }
+    /**
+     * TODO: Implement proper storedBytes tracking for client using encrypted
+     * message sizes (need to figure out how to reuse received or postpone
+     * client...).
+     */
+    const updateUsage = updateOwnerUsage(deps)(ownerIdBytes, 1, // Placeholder until proper tracking implemented
+    firstTimestamp, lastTimestamp);
+    if (!updateUsage.ok)
+        return updateUsage;
+    return ok();
+};
+const applyMessageToAppTable = (deps) => (ownerId, message) => {
+    const timestamp = timestampToTimestampBytes(message.timestamp);
+    const updatedAt = new Date(message.timestamp.millis).toISOString();
+    for (const [column, value] of objectToEntries(message.change.values)) {
+        const result = deps.sqlite.exec(sql.prepared `
+        with
+          existingTimestamp as (
+            select 1
+            from evolu_history
+            where
+              "ownerId" = ${ownerId}
+              and "table" = ${message.change.table}
+              and "id" = ${idToIdBytes(message.change.id)}
+              and "column" = ${column}
+              and "timestamp" >= ${timestamp}
+            limit 1
+          )
+        insert into ${sql.identifier(message.change.table)}
+          ("id", ${sql.identifier(column)}, updatedAt)
+        select ${message.change.id}, ${value}, ${updatedAt}
+        where not exists (select 1 from existingTimestamp)
+        on conflict ("id") do update
+          set
+            ${sql.identifier(column)} = ${value},
+            updatedAt = ${updatedAt}
+          where not exists (select 1 from existingTimestamp);
+      `);
+        if (!result.ok)
+            return result;
+    }
+    return ok();
+};
+export const applyMessageToTimestampAndHistoryTables = (deps) => (ownerId, message, strategy) => {
+    const timestamp = timestampToTimestampBytes(message.timestamp);
+    const id = idToIdBytes(message.change.id);
+    const result = deps.storage.insertTimestamp(ownerId, timestamp, strategy);
+    if (!result.ok)
+        return result;
+    for (const [column, value] of Object.entries(message.change.values)) {
+        const result = deps.sqlite.exec(sql.prepared `
+        insert into evolu_history
+          ("ownerId", "table", "id", "column", "value", "timestamp")
+        values
+          (
+            ${ownerId},
+            ${message.change.table},
+            ${id},
+            ${column},
+            ${value},
+            ${timestamp}
+          )
+        on conflict do nothing;
+      `);
+        if (!result.ok)
+            return result;
+    }
+    return ok();
 };
 export const initialSyncState = { type: "SyncStateInitial" };

package/dist/src/Evolu/Timestamp.d.ts

@@ -1,8 +1,9 @@
-import { NanoIdLibDep } from "../NanoId.js";
+import { Brand } from "../Brand.js";
+import { RandomBytesDep } from "../Crypto.js";
 import { Order } from "../Order.js";
 import { Result } from "../Result.js";
 import { TimeDep } from "../Time.js";
-import { Brand } from "../Types.js";
+import { InferType } from "../Type.js";
 export interface TimestampConfig {
     /**
      * Maximum physical clock drift allowed in ms.
@@ -14,7 +15,7 @@ export interface TimestampConfig {
 export interface TimestampConfigDep {
     readonly timestampConfig: TimestampConfig;
 }
-export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError;
+export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError;
 export interface TimestampDriftError {
     readonly type: "TimestampDriftError";
     readonly next: Millis;
@@ -23,10 +24,6 @@ export interface TimestampDriftError {
 export interface TimestampCounterOverflowError {
     readonly type: "TimestampCounterOverflowError";
 }
-export interface TimestampDuplicateNodeError {
-    readonly type: "TimestampDuplicateNodeError";
-    readonly nodeId: NodeId;
-}
 export interface TimestampTimeOutOfRangeError {
     readonly type: "TimestampTimeOutOfRangeError";
 }
@@ -42,11 +39,11 @@ export interface TimestampTimeOutOfRangeError {
  *
  * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
  */
-export declare const Millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+export declare const Millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
 export type Millis = typeof Millis.Type;
 export declare const minMillis: Millis;
 export declare const maxMillis: Millis;
-export declare const Counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+export declare const Counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
 export type Counter = typeof Counter.Type;
 export declare const minCounter: Counter;
 export declare const maxCounter: Counter;
@@ -63,14 +60,17 @@ export declare const maxCounter: Counter;
  *
  * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
  *
- * What will happen if a different device generates the same NodeId?
+ * What happens if different devices generate the same NodeId?
  *
- * If the device belongs to a different owner, nothing will happen because
- * different owner have different owner IDs. Timestamps are partitioned by
- * OwnerId.
+ * If devices with the same NodeId use different owners, no issues occur.
  *
- * If the device belongs to the same owner, the other device will return
- * {@link TimestampDuplicateNodeError}.
+ * If devices with the same NodeId use the same owner, problems only arise when
+ * they generate CRDT messages with identical timestamps (same millis, counter,
+ * and NodeId). In this case, the protocol sync algorithm treats them as the
+ * same message: the first will be synced with the relay, while the affected
+ * message will not be delivered. The affected devices will see different data
+ * yet they will think they are synced. This is extremely rare and can be
+ * resolved by resetting one device to generate a new NodeId.
  */
 export declare const NodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
 export type NodeId = typeof NodeId.Type;
@@ -79,28 +79,86 @@ export declare const maxNodeId: NodeId;
 /**
  * Hybrid Logical Clock timestamp.
  *
+ * Timestamps serve as globally unique, causally ordered identifiers for CRDT
+ * messages in Evolu's sync protocol.
+ *
+ * ### Why Hybrid Logical Clocks
+ *
+ * Evolu uses Hybrid Logical Clocks (HLC), which combine physical time (millis)
+ * with a logical counter. This hybrid approach preserves causality like logical
+ * clocks while staying close to physical time for better human
+ * interpretability.
+ *
+ * The counter component ensures causality is maintained even when physical
+ * clocks are imperfect. When clocks drift or operations occur concurrently, the
+ * counter increments to establish a total order. This means Evolu achieves
+ * well-defined, eventually-consistent behavior regardless of physical clock
+ * accuracy.
+ *
+ * Vector clocks can accurately track causality and detect concurrent
+ * operations, but they require unbounded space in peer-to-peer systems and
+ * crucially, still don't solve our fundamental problem: when they detect
+ * operations as concurrent, we still need a deterministic way to choose a
+ * winner. Additionally, any deterministic conflict resolution can be gamed by
+ * malicious actors.
+ *
+ * HLC timestamps work well in practice because modern device clocks accurately
+ * reflect the order of sequential edits in the common case. Evolu's `maxDrift`
+ * configuration protects against buggy clocks and prevents problematic
+ * future-dated entries from propagating through the network.
+ *
+ * ### References
+ *
  * - https://muratbuffalo.blogspot.com/2014/07/hybrid-logical-clocks.html
  * - https://sergeiturukin.com/2017/06/26/hybrid-logical-clocks.html
  * - https://jaredforsyth.com/posts/hybrid-logical-clocks/
+ * - https://willowprotocol.org/more/timestamps_really/index.html
+ *
+ * ### Privacy Considerations
+ *
+ * Timestamps are metadata visible to relays and collaborators. While it can be
+ * considered a privacy leak, let us explain why it's necessary, and how to
+ * avoid it if maximum privacy is required.
+ *
+ * With real-time communication, participants always see activity (receiving
+ * bytes). We cannot trust anyone not to store that information, so explicitly
+ * exposing timestamps doesn't add additional risk.
+ *
+ * If we really want not to leak user activity, we can implement a local write
+ * queue:
+ *
+ * 1. Write changes immediately to a local-only table
+ * 2. Periodically/randomly flush messages to sync tables
+ * 3. This decouples user activity from sync timing
+ *
+ * Tradeoff: It breaks real-time collaboration.
  */
 export declare const Timestamp: import("../Type.js").ObjectType<{
-    millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
-    counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+    millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+    counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").IntError | import("../Type.js").NumberError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").NumberError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
     nodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
 }>;
-export type Timestamp = typeof Timestamp.Type;
+export interface Timestamp extends InferType<typeof Timestamp> {
+}
+/** Equality function for comparing {@link Timestamp}. */
+export declare const eqTimestamp: import("../Eq.js").Eq<{
+    readonly millis: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<`LessThanOrEqualTo${number}`> & Brand<"Millis">;
+    readonly counter: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"LessThanOrEqualTo65535"> & Brand<"Counter">;
+    readonly nodeId: string & Brand<"NodeId">;
+}>;
 export declare const createTimestamp: ({ millis, counter, nodeId, }?: Partial<Timestamp>) => Timestamp;
-export declare const createInitialTimestamp: (deps: NanoIdLibDep) => Timestamp;
-/** TimestampString is a sortable string version of {@link Timestamp}. */
+export declare const createInitialTimestamp: (deps: RandomBytesDep) => Timestamp;
+/** Sortable string representation of {@link Timestamp}. */
 export type TimestampString = string & Brand<"TimestampString">;
 export declare const timestampToTimestampString: (t: Timestamp) => TimestampString;
 export declare const timestampStringToTimestamp: (timestampString: TimestampString) => Timestamp;
 export declare const sendTimestamp: (deps: TimeDep & TimestampConfigDep) => (timestamp: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError>;
-export declare const receiveTimestamp: (deps: TimeDep & TimestampConfigDep) => (local: Timestamp, remote: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError>;
-/** BinaryTimestamp is a binary and sortable version of {@link Timestamp} for DB. */
-export type BinaryTimestamp = Uint8Array & Brand<"BinaryTimestamp">;
-export declare const binaryTimestampLength: number & Brand<"Int"> & Brand<"NonNegative">;
-export declare const timestampToBinaryTimestamp: (timestamp: Timestamp) => BinaryTimestamp;
-export declare const binaryTimestampToTimestamp: (timestamp: BinaryTimestamp) => Timestamp;
-export declare const orderBinaryTimestamp: Order<BinaryTimestamp>;
+export declare const receiveTimestamp: (deps: TimeDep & TimestampConfigDep) => (local: Timestamp, remote: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError>;
+/** Sortable bytes representation of {@link Timestamp}. */
+export declare const TimestampBytes: import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, "TimestampBytes", import("../Type.js").BrandWithoutRefineError<"TimestampBytes", import("../Type.js").Uint8ArrayError>, never>;
+export type TimestampBytes = typeof TimestampBytes.Type;
+export declare const timestampBytesLength: number & Brand<"Int"> & Brand<"NonNegative">;
+export declare const timestampToTimestampBytes: (timestamp: Timestamp) => TimestampBytes;
+export declare const timestampBytesToTimestamp: (timestamp: TimestampBytes) => Timestamp;
+export declare const orderTimestampBytes: Order<TimestampBytes>;
 //# sourceMappingURL=Timestamp.d.ts.map