@mh-gg/protocol 0.1.1-alpha.20260613T085325975Z

package/test/operation-identity.test.cjs

@@ -0,0 +1,101 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+  advanceHlc,
+  codePointCompare,
+  compareHlc,
+  createHlcClock,
+  ensureOperationIdentity,
+  formatHlc,
+  operationContentHash,
+  operationIdMatchesContent,
+  parseHlc,
+  validateHlc,
+  validateRoomOperation
+} = require("../src/index.cjs");
+
+function baseOperation(overrides = {}) {
+  return {
+    roomId: "room",
+    appPackId: "app",
+    appPackHash: "sha256-app",
+    pluginId: "plugin",
+    type: "thing.create",
+    actor: { memberId: "alice", deviceId: "dev_alice", role: "admin" },
+    seq: 1,
+    createdAt: 1000,
+    payload: { name: "A" },
+    auth: { credentialId: "cred", signature: "sig" },
+    ...overrides
+  };
+}
+
+test("HLC formatting, parsing, and advancement preserve causal order", () => {
+  const first = formatHlc({ physical: 1000, logical: 0, nodeId: "dev" });
+  assert.equal(first, "000000000001000:000000:dev");
+  assert.deepEqual(parseHlc(first), { physical: 1000, logical: 0, nodeId: "dev", value: first });
+  const next = advanceHlc(first, { now: 999, nodeId: "dev" });
+  assert.equal(next, "000000000001000:000001:dev");
+  assert.equal(compareHlc(first, next), -1);
+
+  const clock = createHlcClock({ nodeId: "node-b", now: () => 1001 });
+  clock.observe(next);
+  assert.equal(clock.next(), "000000000001001:000000:node-b");
+});
+
+test("operation ids are content hashes bound to HLC and payload", () => {
+  const op = ensureOperationIdentity(baseOperation(), { now: 1000, nodeId: "dev_alice" });
+  assert.equal(op.id, operationContentHash(op));
+  assert.equal(operationIdMatchesContent(op), true);
+  validateRoomOperation(op, { now: 1000 });
+
+  const tampered = { ...op, payload: { name: "B" } };
+  assert.equal(operationIdMatchesContent(tampered), false);
+  assert.throws(() => validateRoomOperation(tampered, { now: 1000 }), /operation.id/);
+});
+
+test("operation HLC is required and bounded by local future skew", () => {
+  assert.throws(() => validateRoomOperation({ ...baseOperation(), id: "sha256:bad" }, { now: 1000 }), /operation.hlc/);
+  const okay = ensureOperationIdentity(baseOperation({ hlc: formatHlc({ physical: 1000 + 60_000, logical: 0, nodeId: "dev" }) }), { now: 1000, nodeId: "dev" });
+  validateRoomOperation(okay, { now: 1000 });
+  const tooFar = ensureOperationIdentity(baseOperation({ hlc: formatHlc({ physical: 1000 + 600_000, logical: 0, nodeId: "dev" }) }), { now: 1000, nodeId: "dev" });
+  assert.throws(() => validateRoomOperation(tooFar, { now: 1000 }), /future skew/);
+});
+
+test("byte comparison is locale-independent for operation ordering inputs", () => {
+  const values = ["é", "e\u0301", "Z", "a"].sort(codePointCompare);
+  assert.deepEqual(values, ["Z", "a", "e\u0301", "é"]);
+  const oldLocale = process.env.LC_ALL;
+  process.env.LC_ALL = "sv_SE.UTF-8";
+  try {
+    assert.deepEqual(["é", "e\u0301", "Z", "a"].sort(codePointCompare), values);
+  } finally {
+    if (oldLocale === undefined) delete process.env.LC_ALL;
+    else process.env.LC_ALL = oldLocale;
+  }
+});
+
+test("HLC helpers cover invalid, empty, and function-now branches", () => {
+  assert.equal(parseHlc("bad"), undefined);
+  assert.throws(() => formatHlc({ physical: -1, logical: 0, nodeId: "dev" }), /physical/);
+  assert.throws(() => formatHlc({ physical: 1, logical: 0, nodeId: "bad node" }), /nodeId/);
+  assert.equal(validateHlc("bad", { now: () => 1 }).ok, false);
+  assert.equal(validateHlc(formatHlc({ physical: 1, logical: 0, nodeId: "dev" }), { now: () => 1 }).ok, true);
+  assert.equal(validateHlc(formatHlc({ physical: 12, logical: 0, nodeId: "dev" }), { now: 1, maxFutureSkewMs: 20 }).ok, true);
+  assert.equal(validateHlc(formatHlc({ physical: 12, logical: 0, nodeId: "dev" }), { now: 1, maxFutureSkewMs: 1 }).ok, false);
+  assert.equal(advanceHlc(undefined, { now: "not-number", nodeId: "dev" }), "000000000000000:000000:dev");
+});
+
+test("operation identity helpers cover empty and mismatch branches", () => {
+  const a = formatHlc({ physical: 1, logical: 0, nodeId: "a" });
+  const b = formatHlc({ physical: 2, logical: 0, nodeId: "b" });
+  assert.equal(require("../src/index.cjs").maxHlc("", b), b);
+  assert.equal(require("../src/index.cjs").maxHlc(a, ""), a);
+  assert.equal(require("../src/index.cjs").maxHlc(a, b), b);
+  const assigned = require("../src/index.cjs").assignOperationId(baseOperation({ hlc: a }));
+  assert.equal(assigned.id, operationContentHash(assigned));
+  assert.equal(operationIdMatchesContent(null), false);
+  assert.equal(operationIdMatchesContent({ ...assigned, id: "sha256:wrong" }), false);
+  assert.equal(require("../src/index.cjs").unsignedOperationBodyForId(undefined).id, undefined);
+});

package/test/room-device-signing-roundtrip.test.cjs

@@ -0,0 +1,267 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+const {
+  MATTERHORN_DEVICE_SIGNATURE_NOSTR_KIND,
+  MATTERHORN_ROOM_DEVICE_SIGNING_ALG,
+  MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME,
+  unsignedRoomOperationForDeviceSignature,
+  validateRoomDeviceSignedOperationAuth,
+  validateRoomMemberKeyClaim,
+  verifyRoomDeviceKeyClaim,
+  verifyRoomDeviceOperationSignature,
+  verifyRoomDeviceSignedOperation,
+  verifyRoomMemberKeyClaim
+} = require("../src/index.cjs");
+
+let nostr;
+try {
+  nostr = require("nostr-tools");
+} catch {
+  nostr = undefined;
+}
+
+function bytes(hex) {
+  return nostr.utils.hexToBytes(hex);
+}
+
+function eventForSignature({ purpose, roomName, memberId, deviceId, keyId, publicKey, content, createdAt = 1700000000 }) {
+  return {
+    kind: MATTERHORN_DEVICE_SIGNATURE_NOSTR_KIND,
+    created_at: createdAt,
+    tags: [
+      ["protocol", "matterhorn-sdk"],
+      ["scheme", MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME],
+      ["purpose", purpose],
+      ["room", roomName],
+      ["member", memberId],
+      ["device", deviceId],
+      ["key", keyId]
+    ],
+    content,
+    pubkey: publicKey,
+    id: "",
+    sig: ""
+  };
+}
+
+function unsignedClaim(claim) {
+  const next = JSON.parse(JSON.stringify(claim));
+  delete next.proof;
+  delete next.rootProof;
+  return next;
+}
+
+function unsignedOperation(operation) {
+  const next = JSON.parse(JSON.stringify(operation));
+  if (next.auth) {
+    delete next.auth.signature;
+    delete next.auth.signatureEventId;
+    delete next.auth.eventId;
+    delete next.auth.signedAt;
+  }
+  delete next.committedRoomVersion;
+  delete next.committedAt;
+  delete next.receivedAt;
+  delete next.relayId;
+  return next;
+}
+
+function copy(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function buildClaim() {
+  const rootPrivateKey = "1".repeat(64);
+  const devicePrivateKey = "2".repeat(64);
+  const rootPublicKey = nostr.getPublicKey(bytes(rootPrivateKey));
+  const publicKey = nostr.getPublicKey(bytes(devicePrivateKey));
+  const claim = {
+    kind: "matterhorn.member-key-claim",
+    type: "matterhorn/member-key/v1",
+    version: 1,
+    scheme: MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME,
+    alg: MATTERHORN_ROOM_DEVICE_SIGNING_ALG,
+    roomId: "room",
+    roomName: "room",
+    memberId: "alice",
+    deviceId: "device-a",
+    keyId: "rk_test_device_a",
+    rootPublicKey,
+    publicKey,
+    publicKeyFingerprint: "sha256:" + "a".repeat(64),
+    encryptionAlg: "x25519",
+    encryptionKeyId: "rkx_test_device_a",
+    encryptionPublicKey: Buffer.from("encryption-public-key").toString("base64url"),
+    createdAt: 1700000000000
+  };
+  const content = canonicalJson(unsignedClaim(claim));
+  const rootEvent = nostr.finalizeEvent(eventForSignature({ purpose: "member-key", roomName: "room", memberId: "alice", deviceId: "device-a", keyId: claim.keyId, publicKey: rootPublicKey, content }), bytes(rootPrivateKey));
+  const deviceEvent = nostr.finalizeEvent(eventForSignature({ purpose: "member-key", roomName: "room", memberId: "alice", deviceId: "device-a", keyId: claim.keyId, publicKey, content }), bytes(devicePrivateKey));
+  claim.rootProof = { alg: MATTERHORN_ROOM_DEVICE_SIGNING_ALG, eventId: rootEvent.id, sig: rootEvent.sig, createdAt: rootEvent.created_at };
+  claim.proof = { alg: MATTERHORN_ROOM_DEVICE_SIGNING_ALG, eventId: deviceEvent.id, sig: deviceEvent.sig, createdAt: deviceEvent.created_at };
+  return { claim, devicePrivateKey };
+}
+
+function buildSignedOperation(claim, devicePrivateKey) {
+  const operation = {
+    id: "sha256:test",
+    roomId: "room",
+    appPackId: "app",
+    appPackHash: "sha256-app",
+    pluginId: "plugin",
+    type: "todo.add",
+    actor: { memberId: "alice", deviceId: "device-a", role: "member" },
+    seq: 1,
+    createdAt: 1700000000001,
+    hlc: "001700000000001:000000:device-a",
+    payload: { text: "ship" },
+    auth: {
+      kind: "matterhorn.operation-device-signature",
+      version: 1,
+      scheme: MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME,
+      alg: MATTERHORN_ROOM_DEVICE_SIGNING_ALG,
+      credentialId: claim.keyId,
+      memberId: claim.memberId,
+      deviceId: claim.deviceId,
+      keyId: claim.keyId,
+      rootPublicKey: claim.rootPublicKey,
+      publicKey: claim.publicKey,
+      publicKeyFingerprint: claim.publicKeyFingerprint,
+      claim,
+      issuedAt: 1700000000001
+    }
+  };
+  const event = nostr.finalizeEvent(eventForSignature({ purpose: "operation", roomName: "room", memberId: "alice", deviceId: "device-a", keyId: claim.keyId, publicKey: claim.publicKey, content: canonicalJson(unsignedOperation(operation)), createdAt: 1700000000 }), bytes(devicePrivateKey));
+  operation.auth.signature = event.sig;
+  operation.auth.signatureEventId = event.id;
+  operation.auth.eventId = event.id;
+  operation.auth.signedAt = event.created_at;
+  return operation;
+}
+
+test("room-device member key claims and operations verify end to end", { skip: !nostr && "nostr-tools is not installed in this sandbox" }, () => {
+  const { claim, devicePrivateKey } = buildClaim();
+  assert.equal(verifyRoomMemberKeyClaim(claim).ok, true);
+
+  const operation = buildSignedOperation(claim, devicePrivateKey);
+  assert.equal(verifyRoomDeviceSignedOperation(operation, claim).ok, true);
+
+  const tampered = { ...operation, payload: { text: "tampered" } };
+  assert.equal(verifyRoomDeviceSignedOperation(tampered, claim).ok, false);
+
+  const wrongActor = { ...operation, actor: { ...operation.actor, memberId: "mallory" } };
+  assert.equal(verifyRoomDeviceSignedOperation(wrongActor, claim).ok, false);
+});
+
+test("room-device signing validators reject malformed claims and auth", { skip: !nostr && "nostr-tools is not installed in this sandbox" }, () => {
+  const { claim, devicePrivateKey } = buildClaim();
+  const operation = buildSignedOperation(claim, devicePrivateKey);
+
+  assert.equal(verifyRoomDeviceKeyClaim(claim), true);
+  assert.equal(verifyRoomDeviceOperationSignature(operation, claim).ok, true);
+  assert.equal(verifyRoomDeviceSignedOperation(operation).ok, true);
+
+  const withoutSignatureEventId = copy(operation);
+  delete withoutSignatureEventId.auth.signatureEventId;
+  assert.equal(verifyRoomDeviceSignedOperation(withoutSignatureEventId).ok, true);
+
+  assert.deepEqual(validateRoomMemberKeyClaim(null), { ok: false, error: "member key claim is required" });
+  for (const [field, value, error] of [
+    ["kind", "bad", "member key claim kind is invalid"],
+    ["type", "bad", "member key claim type is invalid"],
+    ["version", 2, "member key claim version is invalid"],
+    ["scheme", "bad", "member key claim scheme is invalid"],
+    ["alg", "bad", "member key claim alg is invalid"],
+    ["memberId", "", "member key claim memberId is required"],
+    ["roomName", "", "member key claim room is required"],
+    ["rootPublicKey", "bad", "member key claim rootPublicKey is invalid"],
+    ["publicKey", "bad", "member key claim publicKey is invalid"],
+    ["encryptionAlg", "bad", "member key claim encryptionAlg is invalid"],
+    ["encryptionKeyId", "", "member key claim encryptionKeyId is required"],
+    ["encryptionPublicKey", "", "member key claim encryptionPublicKey is required"],
+    ["createdAt", "bad", "member key claim createdAt is invalid"]
+  ]) {
+    const candidate = copy(claim);
+    if (field === "roomName") delete candidate.roomId;
+    candidate[field] = value;
+    assert.deepEqual(validateRoomMemberKeyClaim(candidate), { ok: false, error });
+  }
+
+  for (const [proofField, patch, error] of [
+    ["rootProof", undefined, "member key root proof is required"],
+    ["rootProof", { ...claim.rootProof, alg: "bad" }, "member key root proof alg is invalid"],
+    ["rootProof", { ...claim.rootProof, eventId: "bad" }, "member key root proof shape is invalid"],
+    ["proof", undefined, "member key device proof is required"],
+    ["proof", { ...claim.proof, alg: "bad" }, "member key device proof alg is invalid"],
+    ["proof", { ...claim.proof, sig: "bad" }, "member key device proof shape is invalid"]
+  ]) {
+    const candidate = copy(claim);
+    candidate[proofField] = patch;
+    assert.deepEqual(validateRoomMemberKeyClaim(candidate), { ok: false, error });
+  }
+
+  const badRootProof = copy(claim);
+  badRootProof.rootProof.sig = "0".repeat(128);
+  assert.deepEqual(verifyRoomMemberKeyClaim(badRootProof), { ok: false, error: "member key root proof is invalid" });
+
+  const badDeviceProof = copy(claim);
+  badDeviceProof.proof.sig = "0".repeat(128);
+  assert.deepEqual(verifyRoomMemberKeyClaim(badDeviceProof), { ok: false, error: "member key device proof is invalid" });
+
+  assert.deepEqual(validateRoomDeviceSignedOperationAuth(null), { ok: false, error: "operation is required" });
+  for (const [mutate, error] of [
+    [(candidate) => { delete candidate.auth; }, "operation auth is required"],
+    [(candidate) => { candidate.auth.scheme = "bad"; }, "operation auth scheme is invalid"],
+    [(candidate) => { candidate.auth.alg = "bad"; }, "operation auth alg is invalid"],
+    [(candidate) => { candidate.auth.kind = "bad"; }, "operation auth kind is invalid"],
+    [(candidate) => { candidate.auth.signature = ""; }, "operation auth signature is required"],
+    [(candidate) => { candidate.auth.signature = "bad"; }, "operation device signature shape is invalid"],
+    [(candidate) => { candidate.auth.issuedAt = "bad"; }, "operation auth issuedAt is invalid"],
+    [(candidate) => { candidate.auth.signedAt = "bad"; }, "operation auth signedAt is invalid"],
+    [(candidate) => { candidate.auth.credentialId = "other"; }, "operation auth credentialId must match keyId"],
+    [(candidate) => { candidate.actor.memberId = "mallory"; }, "operation auth member mismatch"],
+    [(candidate) => { candidate.actor.deviceId = "device-b"; }, "operation auth device mismatch"]
+  ]) {
+    const candidate = copy(operation);
+    mutate(candidate);
+    assert.deepEqual(validateRoomDeviceSignedOperationAuth(candidate), { ok: false, error });
+  }
+
+  for (const [mutate, error] of [
+    [(candidate) => { candidate.auth.keyId = "other"; candidate.auth.credentialId = "other"; }, "operation key does not match member key claim"],
+    [(candidate) => { candidate.auth.memberId = "mallory"; candidate.actor.memberId = "mallory"; }, "operation actor does not match member key claim"],
+    [(candidate) => { candidate.auth.rootPublicKey = "0".repeat(64); }, "operation root public key does not match member key claim"],
+    [(candidate) => { candidate.auth.publicKeyFingerprint = "sha256:" + "b".repeat(64); }, "operation public key does not match member key claim"]
+  ]) {
+    const candidate = copy(operation);
+    mutate(candidate);
+    assert.deepEqual(verifyRoomDeviceSignedOperation(candidate, claim), { ok: false, error });
+  }
+
+  const unsigned = unsignedRoomOperationForDeviceSignature({
+    ...operation,
+    ledgerId: "740755850904834048",
+    snowflakeId: "740755850904834048",
+    committedRoomVersion: 2,
+    committedAt: 3,
+    receivedAt: 4,
+    relayId: "relay"
+  });
+  assert.equal(unsigned.auth.signature, undefined);
+  assert.equal(unsigned.ledgerId, undefined);
+  assert.equal(unsigned.snowflakeId, undefined);
+  assert.equal(unsigned.committedRoomVersion, undefined);
+});
+
+test("room-device operation signatures survive host-assigned ledger ids", { skip: !nostr && "nostr-tools is not installed in this sandbox" }, () => {
+  const { claim, devicePrivateKey } = buildClaim();
+  const operation = buildSignedOperation(claim, devicePrivateKey);
+  const withHostLedger = {
+    ...operation,
+    ledgerId: "740755850904834048",
+    snowflakeId: "740755850904834048"
+  };
+
+  assert.equal(verifyRoomDeviceSignedOperation(withHostLedger, claim).ok, true);
+});

package/test/snowflake.test.cjs

@@ -0,0 +1,119 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+  DEFAULT_SNOWFLAKE_EPOCH,
+  SNOWFLAKE_MAX_SEQUENCE,
+  compareEntityIdsBySnowflake,
+  compareMaybeSnowflakeIds,
+  compareSnowflakeIds,
+  createSnowflakeGenerator,
+  extractSnowflakeId,
+  isSnowflakeId,
+  parseSnowflakeId,
+  prefixedSnowflakeId,
+  snowflakeBoundsForTimestamp,
+  snowflakeIdForOperation,
+  snowflakeIdFromParts,
+  snowflakeIdFromTimestamp,
+  snowflakeTimestamp,
+  stableSnowflakeNodeId,
+  stableSnowflakeSequence
+} = require("../src/operations/snowflake.cjs");
+
+test("snowflake IDs are decimal, parseable, and sortable by timestamp/sequence", () => {
+  const generator = createSnowflakeGenerator({ epoch: 0, nodeId: 7, now: () => 1000 });
+  const first = generator.next();
+  const second = generator.next();
+  const later = generator.next(1001);
+
+  assert.equal(isSnowflakeId(first), true);
+  assert.equal(compareSnowflakeIds(first, second), -1);
+  assert.equal(compareSnowflakeIds(second, later), -1);
+  assert.deepEqual(parseSnowflakeId(first, { epoch: 0 }), { id: first, timestampMs: 1000, nodeId: 7, sequence: 0, epoch: 0 });
+  assert.deepEqual(parseSnowflakeId(second, { epoch: 0 }), { id: second, timestampMs: 1000, nodeId: 7, sequence: 1, epoch: 0 });
+});
+
+test("operation snowflakes prefer assigned ledger IDs and support prefixed entity IDs", () => {
+  const existing = "4194304000";
+  assert.equal(snowflakeIdForOperation({ ledgerId: existing }), existing);
+  assert.equal(snowflakeIdForOperation({ snowflakeId: existing }), existing);
+  assert.equal(prefixedSnowflakeId("task", existing), `task_${existing}`);
+  assert.equal(prefixedSnowflakeId("bad prefix!", existing), `bad_prefix__${existing}`);
+
+  const generated = snowflakeIdForOperation({ createdAt: 1000, actor: { deviceId: "device_a" }, id: "sha256:abc" });
+  assert.equal(isSnowflakeId(generated), true);
+});
+
+test("snowflake helpers reject invalid input and expose timestamp bounds", () => {
+  assert.equal(isSnowflakeId(null), false);
+  assert.equal(isSnowflakeId(""), false);
+  assert.equal(isSnowflakeId("01"), false);
+  assert.equal(isSnowflakeId("-1"), false);
+  assert.equal(isSnowflakeId("9223372036854775808"), false);
+  assert.equal(parseSnowflakeId("not-a-snowflake"), undefined);
+  assert.equal(snowflakeTimestamp("not-a-snowflake"), undefined);
+
+  assert.throws(() => snowflakeIdFromParts({ timestampMs: DEFAULT_SNOWFLAKE_EPOCH - 1 }), /before the Snowflake epoch/);
+  assert.throws(() => snowflakeIdFromParts({ timestampMs: "bad" }), /timestampMs must be an integer/);
+  assert.throws(() => stableSnowflakeNodeId(1024), /nodeId must be between/);
+  assert.throws(() => stableSnowflakeSequence(4096), /sequence must be between/);
+
+  const bounds = snowflakeBoundsForTimestamp(DEFAULT_SNOWFLAKE_EPOCH + 10);
+  assert.equal(isSnowflakeId(bounds.min), true);
+  assert.equal(isSnowflakeId(bounds.max), true);
+  assert.equal(compareSnowflakeIds(bounds.min, bounds.max), -1);
+});
+
+test("snowflake comparisons fall back predictably when ids are mixed", () => {
+  const first = snowflakeIdFromTimestamp(DEFAULT_SNOWFLAKE_EPOCH + 10_000_000, { nodeId: 1 });
+  const second = snowflakeIdFromTimestamp(DEFAULT_SNOWFLAKE_EPOCH + 10_000_001, { nodeId: 1 });
+
+  assert.equal(extractSnowflakeId(`task_${first}`), first);
+  assert.equal(extractSnowflakeId("task_without_id"), undefined);
+  assert.equal(compareEntityIdsBySnowflake(`task_${first}`, `task_${second}`), -1);
+  assert.equal(compareEntityIdsBySnowflake(`task_${first}`, "plain"), -1);
+  assert.equal(compareEntityIdsBySnowflake("plain", `task_${second}`), 1);
+  assert.equal(compareEntityIdsBySnowflake("alpha", "beta"), -1);
+  assert.equal(compareMaybeSnowflakeIds(first, second), -1);
+  assert.equal(compareMaybeSnowflakeIds("beta", "alpha"), 1);
+  assert.equal(compareMaybeSnowflakeIds("", ""), 0);
+});
+
+test("snowflake defaults and malformed values take documented fallback paths", () => {
+  const generated = snowflakeIdFromParts();
+  assert.equal(isSnowflakeId(generated), true);
+  assert.equal(isSnowflakeId({}), false);
+  assert.equal(parseSnowflakeId({}), undefined);
+  assert.equal(stableSnowflakeNodeId(""), stableSnowflakeNodeId(""));
+  assert.equal(stableSnowflakeSequence(""), stableSnowflakeSequence(""));
+  assert.equal(compareMaybeSnowflakeIds("same", "same"), 0);
+  assert.equal(compareEntityIdsBySnowflake("same", "same"), 0);
+  assert.equal(prefixedSnowflakeId("", undefined).startsWith("id_"), true);
+
+  const fromRoom = snowflakeIdForOperation({ createdAt: DEFAULT_SNOWFLAKE_EPOCH + 5, roomId: "room-a", type: "messageSend" });
+  const fromFallback = snowflakeIdForOperation({ createdAt: DEFAULT_SNOWFLAKE_EPOCH + 5 });
+  assert.equal(isSnowflakeId(fromRoom), true);
+  assert.equal(isSnowflakeId(fromFallback), true);
+});
+
+test("snowflake generator handles clock rollback and sequence rollover", () => {
+  let now = DEFAULT_SNOWFLAKE_EPOCH + 20;
+  const generator = createSnowflakeGenerator({ nodeId: "node-a", now: () => now });
+  const first = generator.next();
+  now -= 10;
+  const rollback = generator.next();
+  assert.equal(generator.inspect(first).timestampMs, DEFAULT_SNOWFLAKE_EPOCH + 20);
+  assert.equal(generator.inspect(rollback).timestampMs, DEFAULT_SNOWFLAKE_EPOCH + 20);
+  assert.equal(compareSnowflakeIds(first, rollback), -1);
+
+  let rollover = rollback;
+  for (let index = 0; index < SNOWFLAKE_MAX_SEQUENCE; index += 1) rollover = generator.next(DEFAULT_SNOWFLAKE_EPOCH + 20);
+  const inspected = generator.inspect(rollover);
+  assert.equal(inspected.timestampMs, DEFAULT_SNOWFLAKE_EPOCH + 21);
+  assert.equal(generator.fromTimestamp(DEFAULT_SNOWFLAKE_EPOCH + 30, 7), snowflakeIdFromParts({
+    timestampMs: DEFAULT_SNOWFLAKE_EPOCH + 30,
+    nodeId: generator.nodeId,
+    sequence: 7
+  }));
+});