{"record":{"id":"7f114a32f74b9b29","repo":"clockworklabs/SpacetimeDB","slug":"fromcounterv7-uuid-counter-must-be-non-negativ","errorCode":null,"errorMessage":"`fromCounterV7` uuid `counter` must be non-negative","messagePattern":"`fromCounterV7` uuid `counter` must be non-negative","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/lib/uuid.ts","lineNumber":163,"sourceCode":"   *\n   * const uuid = Uuid.fromCounterV7(counter, now, randomBytes);\n   *\n   * console.assert(\n   *   uuid.toString() === \"0000647e-5180-7000-8000-000200000000\"\n   * );\n   * ```\n   */\n  static fromCounterV7(\n    counter: { value: number },\n    now: Timestamp,\n    randomBytes: Uint8Array\n  ): Uuid {\n    if (randomBytes.length !== 4) {\n      throw new Error('`fromCounterV7` requires `randomBytes.length == 4`');\n    }\n\n    if (counter.value < 0) {\n      throw new Error('`fromCounterV7` uuid `counter` must be non-negative');\n    }\n\n    if (now.__timestamp_micros_since_unix_epoch__ < 0) {\n      throw new Error('`fromCounterV7` `timestamp` before unix epoch');\n    }\n\n    // 31-bit monotonic counter with wraparound\n    const counterVal = counter.value;\n    counter.value = (counterVal + 1) & 0x7fff_ffff;\n\n    // 48-bit unix timestamp (ms)\n    const tsMs = now.toMillis() & 0xffff_ffff_ffffn;\n\n    const bytes = new Uint8Array(16);\n\n    // unix_ts_ms (48 bits)\n    bytes[0] = Number((tsMs >> 40n) & 0xffn);\n    bytes[1] = Number((tsMs >> 32n) & 0xffn);","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/6dee26c6efc2856793e12b148a59742964f5d783/crates/bindings-typescript/src/lib/uuid.ts#L145-L181","documentation":"fromCounterV7 embeds counter.value into a 31-bit unsigned field of the UUID, so negative values cannot be encoded and are rejected up front. The counter argument is a mutable box: after validation the method increments value and wraps it at 0x7fff_ffff, so callers read the next counter value back out of the same object.","triggerScenarios":"Calling fromCounterV7 with counter.value < 0, typically a counter initialized to -1 as a 'not yet set' sentinel, or a value loaded from a signed int32 source without sanitizing.","commonSituations":"C-style sentinel initialization (-1) carried into TypeScript; counters persisted to JSON or a signed DB column and restored negative; counters shared across modules with different signedness assumptions.","solutions":["Initialize the counter object to 0 (const counter = { value: 0 }) and keep it non-negative","Sanitize on load: counter.value = Math.max(0, counter.value)","Validate counter.value >= 0 before calling fromCounterV7 and surface your own config error"],"exampleFix":"// before\nconst counter = { value: -1 }; // sentinel\nconst id = Uuid.fromCounterV7(counter, now, rand); // throws\n\n// after\nconst counter = { value: 0 };\nconst id = Uuid.fromCounterV7(counter, now, rand);","handlingStrategy":"validation","validationCode":"if (!(counter.value >= 0)) {\n  counter.value = 0; // or throw your own config error\n}\nconst id = Uuid.fromCounterV7(counter, now, randomBytes);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Initialize counter objects as { value: 0 }, never -1 sentinels","Sanitize persisted counters on load: Math.max(0, value)","Treat the counter as unsigned 31-bit everywhere it is stored or serialized"],"tags":["uuid","typescript","argument-validation","state-management"],"backgroundTag":"invalid-argument-validation","analyzedSha":"6dee26c6efc2856793e12b148a59742964f5d783","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}