Snapshot

{
  "values": [
    {
      "uuidv7": "019b4f64-3a52-7000-8000-000000000001",
      "value": {
        "key": "h4tE2gk7qfP0QhF3vOVH1q2T7bPBmDOs5wv0ZrC9uQM",
        "value": { "id": "alpha", "active": true }
      },
      "predecessor": "019b4f64-3a52-7000-8000-000000000000"
    }
  ],
  "tombstones": ["019b4f64-3a52-7000-8000-000000000000"]
}
        

Runtime

{
  values: Map<ContentKey, StateEntry>,
  relations: Map<UUIDv7, ContentKey>,
  tombstones: Set<UUIDv7>,
  predecessors: Set<UUIDv7>
}
        

Consumer

[
  { "id": "alpha", "active": true },
  { "id": "beta", "active": false }
]
        

Derive Content Key

1. Let value be the supplied set value.
2. Attempt to encode value as MessagePack with deterministic map-key sorting enabled. If encoding fails, then fail with VALUE_NOT_ENCODABLE.
3. Let bytes be the resulting value byte sequence.
4. Let digest be SHA-256(bytes) [[RFC4634]] [[FIPS1804]].
5. Let key be the unpadded Base64URL encoding of digest [[RFC4648]].
6. Return key.

Create

1. Let replica be a new underlying CR-Map replica hydrated from the supplied optional snapshot according to CR-Map's create algorithm [[CRMAP]].
2. Ignore snapshot entries that the CR-Map create algorithm rejects.
3. Return replica as a CR-Set replica.

Read

1. To test membership for value, run derive content key with value.
2. Return true if the underlying live projection contains that content key; otherwise return false.
3. To enumerate values, iterate the underlying visible CR-Map state and return detached structured clones of each stored value.value.

Update

1. Run derive content key with the supplied value.
2. If the derived content key is already visible in the underlying live projection, then return no change.
3. Run CR-Map's local update algorithm with the derived content key as key and the supplied value as payload [[CRMAP]].
4. If the underlying update cannot structured-clone the value, then fail with VALUE_NOT_CLONEABLE.
5. Return the CR-Map update result as a CR-Set delta and membership change.

Delete

1. Run derive content key with the supplied value.
2. If the derived content key is not visible in the underlying live projection, then return no change.
3. Run CR-Map's keyed delete algorithm with the derived content key [[CRMAP]].
4. Return the resulting tombstone-only delta and change.

Clear

1. If the underlying live projection is empty, then return no change.
2. Run CR-Map's clear algorithm [[CRMAP]].
3. Return the resulting tombstone-only delta and membership change.

Merge

1. If the supplied candidate is not a record, then return no change.
2. Run CR-Map's merge algorithm over the underlying replica state [[CRMAP]].
3. Incoming value entries whose value.key is not a string or whose value.value cannot be structured-cloned are ignored by the transform a snapshot value entry to a state entry algorithm.
4. If merge accepts remote values or tombstones, return the visible membership change. If local state dominates incoming contenders, return any reply delta.
5. A conforming implementation MAY dispatch a reply delta, a visible change event, or both, matching the CR-Map merge result.

Acknowledge

1. Compute the underlying CR-Map acknowledgement frontier [[CRMAP]].
2. Return the largest retained valid tombstone entry, or the empty string when no valid tombstone exists.

Garbage Collect

1. If the supplied list of acknowledgement frontiers is not a list or is empty, then return.
2. Run CR-Map's garbage-collection algorithm with the supplied frontiers [[CRMAP]].
3. Remove only tombstones at or below the smallest valid supplied frontier, while preserving identifiers still referenced as live predecessors by the underlying CR-Map state.

This algorithm is only safe when the caller supplies acknowledgement frontiers covering every replica whose future convergence must still be preserved. Supplying only a partial frontier set is caller misuse and does not guarantee that an offline replica can later catch up from deltas alone.

Snapshot

1. Run CR-Map's snapshot algorithm over the underlying replica state [[CRMAP]].
2. Return a new snapshot containing all visible value entries produced by the transform a state entry to a snapshot value entry algorithm and all retained tombstones.

API Summary

callback CRSetForEachCallback = undefined (any value, CRSet set);

[Exposed=*]
interface CRSet {
  constructor(optional object snapshot = {});
  readonly attribute unsigned long size;
  undefined add(any value);
  boolean has(any value);
  undefined delete(any value);
  undefined clear();
  sequence<any> values();
  undefined merge(optional object delta = {});
  undefined acknowledge();
  undefined garbageCollect(sequence<DOMString> frontiers);
  undefined snapshot();
  undefined addEventListener(
    DOMString type,
    EventListener? listener,
    optional (AddEventListenerOptions or boolean) options = {}
  );
  undefined removeEventListener(
    DOMString type,
    EventListener? listener,
    optional (EventListenerOptions or boolean) options = {}
  );
  undefined forEach(CRSetForEachCallback callback, optional any thisArg);
  object toJSON();
  stringifier DOMString ();
  iterable<any>;
};

dictionary CRSetSnapshotValuePayload {
  required DOMString key;
  required any value;
};

dictionary CRSetSnapshotValueEntry {
  required DOMString uuidv7;
  required CRSetSnapshotValuePayload value;
  required DOMString predecessor;
};

dictionary CRSetSnapshot {
  required sequence<CRSetSnapshotValueEntry> values;
  required sequence<DOMString> tombstones;
};

dictionary CRSetDelta {
  sequence<CRSetSnapshotValueEntry> values;
  sequence<DOMString> tombstones;
};

typedef record<DOMString, any> CRSetChange;
typedef DOMString CRSetAck;
        

The constructor and merge() method are typed as taking generic objects in the coarse Web IDL summary above so that the IDL matches the permissive JavaScript ingress behavior. The expected object shapes are CRSetSnapshot and CRSetDelta as defined earlier.

The key member exposed in snapshot entries is the derived content key, not a caller-provided property. The value member holds the original set member payload.

size returns the current number of visible content keys. values(), forEach(), and for...of expose detached structured clones rather than mutable references into replica state.

When the current snapshot is JSON-compatible, JSON.stringify(set) serializes the binding through that snapshot. toString() attempts to return the JSON string form of the current snapshot.

Errors

The JavaScript binding throws CRSetError with a string code attribute for local API misuse.

VALUE_NOT_ENCODABLE

Thrown when add(), has(), or delete() receives a value that cannot be encoded as deterministic MessagePack for content-key derivation.

VALUE_NOT_CLONEABLE

Thrown when add() receives a value that can be content-keyed but cannot be copied into replica state with structured clone.

Events

The JavaScript binding maintains an internal EventTarget object as defined by DOM [[DOM]].

The binding forwards addEventListener() and removeEventListener() to that internal event target. Local mutations, merges, acknowledgement emission, and snapshot emission dispatch synthetic events through the same target.

The JavaScript binding defines four synthetic event types. Each is a CustomEvent object whose detail attribute is initialized as described below [[DOM]].

delta event

A CustomEvent whose detail is a delta. The binding dispatches this event for local writes and deletes, and for merges that emit a non-empty reply delta.

change event

A CustomEvent whose detail is a sparse visible membership patch mapping changed content key(s) to their new visible values, with deleted keys mapped to undefined.

ack event

A CustomEvent whose detail is the current acknowledgement frontier produced when acknowledge() observes at least one retained valid tombstone.

snapshot event

A CustomEvent whose detail is the full current snapshot produced when snapshot() is invoked.

add(), delete(), and clear() MUST dispatch delta event before change event when the operation changes membership. merge() MAY dispatch a delta event, a change event, or both, and when both are dispatched the delta event MUST be dispatched first. acknowledge() MUST dispatch an ack event only when the computed frontier is non-empty, and snapshot() MUST dispatch a snapshot event.

Auxiliary Algorithms

Methods