actor-ts 0.9.0

package/dist/crdt/DistributedData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DistributedData.d.ts","sourceRoot":"","sources":["../../src/crdt/DistributedData.ts"],"names":[],"mappings":"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"}

package/dist/crdt/DistributedData.js

@@ -0,0 +1,658 @@
+import { match, P } from 'ts-pattern';
+import { Actor } from '../Actor.js';
+import { extensionId } from '../Extension.js';
+import { DEFAULT_ASK_TIMEOUT_MS } from '../util/Constants.js';
+import { Props } from '../Props.js';
+import { MemberRemoved, MemberUp } from '../cluster/ClusterEvents.js';
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import { DurableDistributedDataStore } from './DurableDistributedDataStore.js';
+import { GCounter } from './GCounter.js';
+import { GCounterMap } from './GCounterMap.js';
+import { PNCounter } from './PNCounter.js';
+import { GSet } from './GSet.js';
+import { ORSet } from './ORSet.js';
+import { ORMap } from './ORMap.js';
+import { LWWRegister } from './LWWRegister.js';
+import { LWWMap } from './LWWMap.js';
+import { MVRegister } from './MVRegister.js';
+/**
+ * Reconstruct a CRDT from its `toJSON()` payload.  Dispatches on the
+ * `kind` discriminator each impl writes — adding a new CRDT type is
+ * one more case here.  Returned as `Crdt<unknown>` because the
+ * concrete type is only known at the call site that asked for the
+ * key in the first place.
+ *
+ * Exported so containers like `ORMap` (whose values are themselves
+ * CRDTs of arbitrary kind) can wire it as their inner-value decoder.
+ *
+ * ## Reference example: discriminated-union dispatch
+ *
+ * This function is the **codebase's reference shape** for
+ * dispatching on a closed string-literal-discriminator union.  Two
+ * properties matter:
+ *
+ *   1. **No `default` arm** — the switch lists every kind explicitly.
+ *      The `default` branch's `const _exhaustive: never = json`
+ *      assertion gives compile-time exhaustiveness: TypeScript
+ *      narrows `json` to `never` after all real arms; adding a new
+ *      variant to `CrdtJson` without a matching `case` makes
+ *      `json` *not* assignable to `never` and the file fails to
+ *      compile.
+ *
+ *   2. **`throw` inside the default** — defensive belt-and-braces
+ *      for the type-erasure boundary (legacy wire data, force-casts).
+ *      Unreachable from well-typed callers.
+ *
+ * Equivalent shape: `match(json).with({ kind: 'X' }, ...).exhaustive()`
+ * from `ts-pattern`.  Used elsewhere in the codebase when the
+ * discriminator is more complex than a string literal (e.g. nominal
+ * type via `instanceof`).  Both forms achieve compile-time
+ * exhaustiveness; pick the more readable one per site.
+ *
+ * **Do not** add a permissive `default` case that returns a stub —
+ * it defeats the exhaustiveness check and turns missing variants
+ * into silent runtime bugs.
+ */
+export function decodeCrdt(json) {
+    switch (json.kind) {
+        case 'GCounter': return GCounter.fromJSON(json);
+        case 'PNCounter': return PNCounter.fromJSON(json);
+        case 'GSet': return GSet.fromJSON(json);
+        case 'ORSet': return ORSet.fromJSON(json);
+        case 'LWWRegister': return LWWRegister.fromJSON(json);
+        case 'GCounterMap': return GCounterMap.fromJSON(json);
+        case 'LWWMap': return LWWMap.fromJSON(json);
+        case 'MVRegister': return MVRegister.fromJSON(json);
+        case 'ORMap': return ORMap.fromJSON(json, 
+        // Inner CRDTs decode through the same dispatcher — a value can
+        // be any of the registered CRDT kinds.
+        (inner) => decodeCrdt(inner));
+        default: {
+            const _exhaustive = json;
+            void _exhaustive;
+            throw new Error(`decodeCrdt: unknown CRDT kind`);
+        }
+    }
+}
+/* ============================== extension ============================== */
+const dataActorPath = (systemName) => `actor-ts://${systemName}/user/distributed-data`;
+/**
+ * Cluster-wide replicated key-value store of CRDTs.  Each node hosts
+ * one local replica.  `update(key, ...)` mutates the local replica
+ * (idempotent, conflict-free), and gossip fans the state out so
+ * every replica eventually agrees on `merge(...)` of all updates.
+ *
+ * **Lifecycle:** call `extension(DistributedDataId).start(cluster)`
+ * once per process to spawn the internal gossip actor.  Subsequent
+ * calls return the same handle.
+ *
+ *   const dd = system.extension(DistributedDataId).start(cluster);
+ *   dd.update('cart-42', () => ORSet.empty<string>(),
+ *     (cart) => cart.add(cluster.selfAddress.toString(), 'apple'));
+ *   const cart = dd.get<ORSet<string>>('cart-42');
+ *
+ * **Limits / non-goals (v1):**
+ *   - Full-state push on every gossip tick — fine for small stores.
+ *   - No durable persistence: the store lives in memory.
+ *   - No tombstone delete; `delete(key)` is best-effort and can be
+ *     undone by an in-flight gossip from a peer who still has the
+ *     key.  Plan a workload-specific tombstone pattern (typically
+ *     embed deletion in the CRDT — e.g. `ORSet.remove`).
+ */
+export class DistributedData {
+    system;
+    _handle = null;
+    _cluster = null;
+    constructor(system) {
+        this.system = system;
+    }
+    start(cluster, settings = {}) {
+        if (this._handle && this._cluster === cluster)
+            return this._handle;
+        if (this._handle) {
+            throw new Error('DistributedData is already bound to a different cluster');
+        }
+        this._cluster = cluster;
+        // The extension exposes a synchronous API; the internal actor owns
+        // the state and the gossip loop.  We hand the actor a setter for a
+        // shared "view" the public handle reads, so callers don't have to
+        // ask().
+        const view = { state: new Map(), listeners: new Map() };
+        const ref = this.system.spawn(Props.create(() => new DistributedDataActor({ cluster, settings, view })), 'distributed-data');
+        // Register wire handlers SYNCHRONOUSLY here — `spawn` returns
+        // before the actor's async `preStart` has run, but quorum
+        // writes/reads need every peer to already be routing inbound
+        // requests by the time the originator sends them.  Forwarding via
+        // `ref.tell(...)` instead of `self.tell(...)` is safe: messages
+        // queued before preStart completes wait in the mailbox.
+        const unsubs = [];
+        for (const kind of [
+            'ddata-gossip',
+            'ddata-write-request',
+            'ddata-write-ack',
+            'ddata-read-request',
+            'ddata-read-response',
+        ]) {
+            unsubs.push(cluster._onWire(kind, (msg) => {
+                ref.tell(msg);
+            }));
+        }
+        this._handle = new DistributedDataHandle(ref, view, cluster, unsubs);
+        return this._handle;
+    }
+    /** Tear down the wire-handler subscriptions (test/shutdown only). */
+    stop() {
+        if (this._handle) {
+            this._handle._stopWireHandlers();
+        }
+    }
+    get() {
+        if (!this._handle) {
+            throw new Error('DistributedData.start(cluster) must be called first');
+        }
+        return this._handle;
+    }
+    isStarted() { return this._handle !== null; }
+}
+export const DistributedDataId = extensionId('actor-ts/crdt/distributed-data', (system) => new DistributedData(system));
+/**
+ * Public handle returned from `extension.start(cluster)`.  Holds a
+ * ref to the internal actor + a synchronously-readable view of the
+ * replicated state.
+ */
+export class DistributedDataHandle {
+    ref;
+    view;
+    cluster;
+    wireUnsubs;
+    constructor(ref, view, cluster, wireUnsubs = []) {
+        this.ref = ref;
+        this.view = view;
+        this.cluster = cluster;
+        this.wireUnsubs = wireUnsubs;
+    }
+    /** @internal — called by the extension's `stop()`. */
+    _stopWireHandlers() {
+        for (const u of this.wireUnsubs)
+            u();
+        this.wireUnsubs = [];
+    }
+    /** Synchronously read the local replica's view of `key`. */
+    get(key) {
+        return this.view.state.get(key);
+    }
+    /**
+     * Mutate `key` via `fn`.  If the key doesn't exist yet, `factory()`
+     * is called to seed a fresh CRDT.  The mutation runs on the actor
+     * thread so concurrent local callers serialize cleanly.
+     */
+    update(key, factory, fn) {
+        this.ref.tell({
+            t: 'ddata-update', key,
+            factory: factory,
+            fn: fn,
+        });
+    }
+    /**
+     * Quorum-write variant of {@link update}.  Returns a promise that
+     * resolves only after the requested number of replicas have
+     * acknowledged the merge.  Self always counts as the first ack, so
+     * single-node clusters and `consistency: 'local'` resolve as soon as
+     * the local apply is done.
+     *
+     * Rejects with a timeout error if not enough acks arrive within
+     * `timeoutMs` (default `gossipIntervalMs × 5`).  A timeout does NOT
+     * roll the local write back — the value is already applied locally
+     * and will continue to gossip; the rejection only signals "I'm not
+     * sure enough replicas saw it".
+     *
+     *   await dd.updateAsync<GCounter>('hits', GCounter.empty,
+     *     (c) => c.increment(dd.selfReplicaId(), 1),
+     *     { consistency: 'majority' });
+     */
+    updateAsync(key, factory, fn, opts = {
+        consistency: 'local',
+    }) {
+        return new Promise((resolve, reject) => {
+            const pendingId = nextPendingId();
+            const timeoutMs = opts.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS;
+            this.ref.tell({
+                t: 'ddata-update', key,
+                factory: factory,
+                fn: fn,
+                quorum: {
+                    pendingId, consistency: opts.consistency, timeoutMs,
+                    resolve, reject,
+                },
+            });
+        });
+    }
+    /**
+     * Quorum-read variant of {@link get}.  Sends a read request to peers
+     * matching the consistency target, merges all incoming responses
+     * (plus the local replica), and resolves with the merged value.
+     * `undefined` if no replica knows the key.
+     *
+     * Self always counts as the first response — `'local'` returns
+     * immediately with whatever's in the local view.  Timeout default is
+     * the same as {@link updateAsync}.
+     *
+     *   const cart = await dd.getAsync<ORSet<string>>('cart-42',
+     *     { consistency: 'majority' });
+     */
+    getAsync(key, opts = {
+        consistency: 'local',
+    }) {
+        return new Promise((resolve, reject) => {
+            const pendingId = nextPendingId();
+            const timeoutMs = opts.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS;
+            this.ref.tell({
+                t: 'ddata-read', key, pendingId,
+                consistency: opts.consistency, timeoutMs,
+                resolve: resolve,
+                reject,
+            });
+        });
+    }
+    /**
+     * Best-effort delete.  Forgets `key` on this replica only — peers
+     * may re-introduce it via gossip.  See class header for the
+     * tombstone story.
+     */
+    delete(key) {
+        this.ref.tell({ t: 'ddata-delete', key });
+    }
+    /**
+     * Subscribe to changes for `key`.  Listener fires synchronously
+     * after every successful update / merge that changes the local
+     * value (deep-equal check via the CRDT's own `toJSON`).  Returns
+     * an unsubscribe function.
+     */
+    subscribe(key, listener) {
+        let set = this.view.listeners.get(key);
+        if (!set) {
+            set = new Set();
+            this.view.listeners.set(key, set);
+        }
+        const wrapper = listener;
+        set.add(wrapper);
+        // Replay current value so a late subscriber catches up immediately.
+        const current = this.view.state.get(key);
+        if (current) {
+            try {
+                wrapper(current);
+            }
+            catch (e) { /* ignore in tests */
+                void e;
+            }
+        }
+        return () => {
+            const s = this.view.listeners.get(key);
+            if (s) {
+                s.delete(wrapper);
+                if (s.size === 0)
+                    this.view.listeners.delete(key);
+            }
+        };
+    }
+    /** Snapshot of every key currently known on the local replica. */
+    keys() {
+        return Array.from(this.view.state.keys());
+    }
+    /** ReplicaId used when seeding ops (delegated from `cluster.selfAddress`). */
+    selfReplicaId() {
+        return this.cluster.selfAddress.toString();
+    }
+}
+class DistributedDataActor extends Actor {
+    settings;
+    cluster;
+    view;
+    gossipIntervalMs;
+    durable;
+    gossipTimer = null;
+    unsubscribeCluster = null;
+    /** Set while a durable save is in flight; subsequent changes set
+     *  `_durableDirty = true` so the in-flight save is followed by a
+     *  catch-up save instead of multiple overlapping saves. */
+    durableSaveInFlight = false;
+    durableDirty = false;
+    /** Outstanding quorum-write requests, keyed by pendingId. */
+    pendingWrites = new Map();
+    /** Outstanding quorum-read requests, keyed by pendingId. */
+    pendingReads = new Map();
+    constructor(settings) {
+        super();
+        this.settings = settings;
+        this.cluster = settings.cluster;
+        this.view = settings.view;
+        this.gossipIntervalMs = settings.settings.gossipIntervalMs ?? 1_000;
+        this.durable = settings.settings.durableStore
+            ? new DurableDistributedDataStore(settings.settings.durableStore, this.cluster.selfAddress.toString())
+            : null;
+    }
+    async preStart() {
+        // Wire handlers are registered in the extension's `start()` so they're
+        // ready BEFORE the user can issue the first quorum write — registering
+        // them here would race with `updateAsync` called immediately after
+        // `extension.start()` returns.
+        this.unsubscribeCluster = this.cluster.subscribe((evt) => match(evt)
+            .with(P.instanceOf(MemberUp), () => {
+            this.gossipTick();
+        })
+            .with(P.instanceOf(MemberRemoved), () => { })
+            .otherwise(() => { }));
+        this.gossipTimer = this.system.scheduler.scheduleAtFixedRateFn(this.gossipIntervalMs, this.gossipIntervalMs, () => this.gossipTick());
+        if (this.durable) {
+            // Load + populate the in-memory view BEFORE accepting any
+            // user-issued updates.  Subscribers registered after preStart
+            // will see the recovered values via the handle's replay
+            // mechanism (subscribe() fires once with the current value).
+            try {
+                const loaded = await this.durable.load();
+                for (const [key, crdt] of loaded) {
+                    this.applyMerged(key, null, crdt);
+                }
+            }
+            catch (err) {
+                this.log.warn(`DistributedData: durable load failed`, err);
+            }
+        }
+    }
+    postStop() {
+        this.unsubscribeCluster?.();
+        this.gossipTimer?.cancel();
+        // Reject any still-pending quorum requests so callers don't hang.
+        for (const w of this.pendingWrites.values()) {
+            w.timer.cancel();
+            w.reject(new Error(`DistributedData stopped before quorum write on "${w.key}" completed`));
+        }
+        this.pendingWrites.clear();
+        for (const r of this.pendingReads.values()) {
+            r.timer.cancel();
+            r.reject(new Error(`DistributedData stopped before quorum read on "${r.key}" completed`));
+        }
+        this.pendingReads.clear();
+    }
+    onReceive(msg) {
+        match(msg)
+            .with({ t: 'ddata-update' }, (m) => this.handleUpdate(m))
+            .with({ t: 'ddata-delete' }, (m) => this.handleDelete(m))
+            .with({ t: 'ddata-read' }, (m) => this.handleRead(m))
+            .with({ t: 'ddata-gossip' }, (m) => this.handleGossip(m))
+            .with({ t: 'ddata-write-request' }, (m) => this.handleWriteRequest(m))
+            .with({ t: 'ddata-write-ack' }, (m) => this.handleWriteAck(m))
+            .with({ t: 'ddata-read-request' }, (m) => this.handleReadRequest(m))
+            .with({ t: 'ddata-read-response' }, (m) => this.handleReadResponse(m))
+            .exhaustive();
+    }
+    handleUpdate(msg) {
+        const current = this.view.state.get(msg.key) ?? msg.factory();
+        const next = msg.fn(current);
+        this.applyMerged(msg.key, current, next);
+        if (!msg.quorum)
+            return;
+        // Quorum write: self-vote counts as the first ack.  If only self
+        // is needed (single-node, or 'local'), resolve immediately;
+        // otherwise broadcast a write-request to peers and arm a timer.
+        const peers = this.cluster.upMembers()
+            .filter((m) => !m.address.equals(this.cluster.selfAddress));
+        const totalN = 1 + peers.length;
+        const required = clampQuorum(msg.quorum.consistency, totalN);
+        const acks = new Set([this.cluster.selfAddress.toString()]);
+        if (acks.size >= required) {
+            msg.quorum.resolve();
+            return;
+        }
+        const timer = this.system.scheduler.scheduleOnceFn(msg.quorum.timeoutMs, () => {
+            const pending = this.pendingWrites.get(msg.quorum.pendingId);
+            if (!pending)
+                return;
+            this.pendingWrites.delete(msg.quorum.pendingId);
+            pending.reject(new Error(`DistributedData quorum write on "${msg.key}" timed out after ${msg.quorum.timeoutMs}ms ` +
+                `(${pending.acks.size}/${pending.required} acks)`));
+        });
+        this.pendingWrites.set(msg.quorum.pendingId, {
+            kind: 'write', key: msg.key, required, acks, timer,
+            resolve: msg.quorum.resolve, reject: msg.quorum.reject,
+        });
+        const wire = {
+            t: 'ddata-write-request',
+            from: this.cluster.selfAddress.toJSON(),
+            pendingId: msg.quorum.pendingId,
+            key: msg.key,
+            value: next.toJSON(),
+        };
+        for (const peer of peers) {
+            this.cluster.transport.send(peer.address, wire);
+        }
+    }
+    handleRead(msg) {
+        const peers = this.cluster.upMembers()
+            .filter((m) => !m.address.equals(this.cluster.selfAddress));
+        const totalN = 1 + peers.length;
+        const required = clampQuorum(msg.consistency, totalN);
+        const localValue = this.view.state.get(msg.key);
+        const responses = new Set([this.cluster.selfAddress.toString()]);
+        if (responses.size >= required) {
+            msg.resolve(localValue);
+            return;
+        }
+        const timer = this.system.scheduler.scheduleOnceFn(msg.timeoutMs, () => {
+            const pending = this.pendingReads.get(msg.pendingId);
+            if (!pending)
+                return;
+            this.pendingReads.delete(msg.pendingId);
+            // Best-effort: resolve with whatever we've merged so far rather
+            // than rejecting outright.  Reads are forgiving — a partial
+            // answer is more useful than no answer for most workloads.  If
+            // *nothing* came back (not even local), keep undefined.
+            pending.resolve(pending.merged);
+        });
+        this.pendingReads.set(msg.pendingId, {
+            kind: 'read', key: msg.key, required, responses, timer,
+            merged: localValue,
+            resolve: msg.resolve, reject: msg.reject,
+        });
+        const wire = {
+            t: 'ddata-read-request',
+            from: this.cluster.selfAddress.toJSON(),
+            pendingId: msg.pendingId,
+            key: msg.key,
+        };
+        for (const peer of peers) {
+            this.cluster.transport.send(peer.address, wire);
+        }
+    }
+    handleWriteRequest(msg) {
+        // Merge the incoming value into our local replica (same merge
+        // semantics as gossip) and ack back.
+        const incoming = decodeCrdt(msg.value);
+        const current = this.view.state.get(msg.key);
+        const merged = current ? current.merge(incoming) : incoming;
+        this.applyMerged(msg.key, current ?? null, merged);
+        const sender = NodeAddress.fromJSON(msg.from);
+        const ack = {
+            t: 'ddata-write-ack',
+            from: this.cluster.selfAddress.toJSON(),
+            pendingId: msg.pendingId,
+            key: msg.key,
+        };
+        this.cluster.transport.send(sender, ack);
+    }
+    handleWriteAck(msg) {
+        const pending = this.pendingWrites.get(msg.pendingId);
+        if (!pending)
+            return; // late ack after timeout / already resolved
+        const senderAddr = NodeAddress.fromJSON(msg.from).toString();
+        if (pending.acks.has(senderAddr))
+            return; // dedupe
+        pending.acks.add(senderAddr);
+        if (pending.acks.size >= pending.required) {
+            pending.timer.cancel();
+            this.pendingWrites.delete(msg.pendingId);
+            pending.resolve();
+        }
+    }
+    handleReadRequest(msg) {
+        const local = this.view.state.get(msg.key);
+        const sender = NodeAddress.fromJSON(msg.from);
+        const response = {
+            t: 'ddata-read-response',
+            from: this.cluster.selfAddress.toJSON(),
+            pendingId: msg.pendingId,
+            key: msg.key,
+            value: local ? local.toJSON() : null,
+        };
+        this.cluster.transport.send(sender, response);
+    }
+    handleReadResponse(msg) {
+        const pending = this.pendingReads.get(msg.pendingId);
+        if (!pending)
+            return;
+        const senderAddr = NodeAddress.fromJSON(msg.from).toString();
+        if (pending.responses.has(senderAddr))
+            return; // dedupe
+        pending.responses.add(senderAddr);
+        if (msg.value !== null) {
+            const incoming = decodeCrdt(msg.value);
+            pending.merged = pending.merged ? pending.merged.merge(incoming) : incoming;
+        }
+        if (pending.responses.size >= pending.required) {
+            pending.timer.cancel();
+            this.pendingReads.delete(msg.pendingId);
+            // Also apply the merged value locally so the next sync `get`
+            // sees the freshest view — a quorum read effectively pulls the
+            // latest state to this replica without waiting for gossip.
+            if (pending.merged) {
+                const current = this.view.state.get(pending.key);
+                this.applyMerged(pending.key, current ?? null, current ? current.merge(pending.merged) : pending.merged);
+            }
+            pending.resolve(pending.merged);
+        }
+    }
+    handleDelete(msg) {
+        if (this.view.state.delete(msg.key)) {
+            // Notify subscribers with a best-effort signal — we synthesise
+            // a fresh CRDT via the most-recently-seen factory.  Since we
+            // don't track factories per key, listeners just get nothing
+            // for now; they'll see the next merge bring the key back if
+            // a peer gossips it.
+            this.scheduleDurableSave();
+        }
+    }
+    handleGossip(msg) {
+        const sender = NodeAddress.fromJSON(msg.from);
+        if (sender.equals(this.cluster.selfAddress))
+            return; // shouldn't happen but harmless
+        for (const [key, json] of Object.entries(msg.entries)) {
+            const incoming = decodeCrdt(json);
+            const current = this.view.state.get(key);
+            const merged = current ? current.merge(incoming) : incoming;
+            this.applyMerged(key, current ?? null, merged);
+        }
+    }
+    applyMerged(key, prev, next) {
+        // Skip the listener fan-out if the merge was a no-op.  Compare by
+        // JSON shape — every CRDT's toJSON is a stable structural form.
+        const prevJson = prev ? JSON.stringify(prev.toJSON()) : null;
+        const nextJson = JSON.stringify(next.toJSON());
+        this.view.state.set(key, next);
+        if (prevJson === nextJson)
+            return;
+        // Persist the change.  If we're recovering from durable load
+        // (preStart loop), this re-saves the same state we just loaded
+        // — harmless and keeps the code path uniform.
+        this.scheduleDurableSave();
+        const listeners = this.view.listeners.get(key);
+        if (!listeners)
+            return;
+        for (const l of listeners) {
+            try {
+                l(next);
+            }
+            catch (e) {
+                this.log.warn(`DistributedData: subscriber for "${key}" threw`, e);
+            }
+        }
+    }
+    /**
+     * Fire a durable save off the actor mailbox.  Coalesces overlapping
+     * requests: if a save is already in flight, we mark `durableDirty`
+     * and the in-flight save's `.finally` handler kicks off a follow-up.
+     * Net effect: a burst of mutations produces 1-2 disk writes, not N.
+     */
+    scheduleDurableSave() {
+        if (!this.durable)
+            return;
+        if (this.durableSaveInFlight) {
+            this.durableDirty = true;
+            return;
+        }
+        this.durableSaveInFlight = true;
+        const snapshot = new Map(this.view.state);
+        void this.durable.save(snapshot)
+            .catch((err) => {
+            this.log.warn(`DistributedData: durable save failed`, err);
+        })
+            .finally(() => {
+            this.durableSaveInFlight = false;
+            if (this.durableDirty) {
+                this.durableDirty = false;
+                this.scheduleDurableSave();
+            }
+        });
+    }
+    gossipTick() {
+        const peers = this.cluster.upMembers()
+            .filter((m) => !m.address.equals(this.cluster.selfAddress));
+        if (peers.length === 0)
+            return;
+        const entries = {};
+        for (const [key, crdt] of this.view.state) {
+            entries[key] = crdt.toJSON();
+        }
+        if (Object.keys(entries).length === 0)
+            return;
+        const payload = {
+            t: 'ddata-gossip',
+            from: this.cluster.selfAddress.toJSON(),
+            entries,
+        };
+        const target = peers[Math.floor(Math.random() * peers.length)];
+        this.cluster.transport.send(target.address, payload);
+    }
+}
+void dataActorPath; // currently unused — reserved for envelope-routing variants
+/* ============================== helpers ============================== */
+let _pendingCounter = 0;
+function nextPendingId() {
+    _pendingCounter = (_pendingCounter + 1) >>> 0;
+    return `p${Date.now()}-${_pendingCounter}`;
+}
+/**
+ * Translate a {@link WriteConsistency} / {@link ReadConsistency} value
+ * into the integer ack count required, given the current up-member
+ * cluster size `N` (incl. self).
+ *
+ *   - `'local'`     → 1            (just self)
+ *   - `'majority'`  → floor(N/2)+1
+ *   - `'all'`       → N
+ *   - `{ from: K }` → clamp(K, 1, N)
+ */
+function clampQuorum(c, totalN) {
+    if (c === 'local')
+        return 1;
+    if (c === 'majority')
+        return Math.floor(totalN / 2) + 1;
+    if (c === 'all')
+        return totalN;
+    // { from: K }
+    const k = Math.trunc(c.from);
+    if (!Number.isFinite(k) || k < 1)
+        return 1;
+    if (k > totalN)
+        return totalN;
+    return k;
+}
+//# sourceMappingURL=DistributedData.js.map