{"record":{"id":"78cb1952aeff4ed9","repo":"ruvnet/ruflo","slug":"label-exceeds-unsigned-64-bit-range","errorCode":null,"errorMessage":"${label} exceeds unsigned 64-bit range","messagePattern":"(.+?) exceeds unsigned 64-bit range","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/codex/src/harness/unsigned-integer.ts","lineNumber":11,"sourceCode":"const CANONICAL_UNSIGNED = /^(?:0|[1-9][0-9]*)$/;\nconst MAX_UNSIGNED_64 = (1n << 64n) - 1n;\n\n/** Parse a decimal unsigned integer without accepting aliases such as +1, 01, hex, or whitespace. */\nexport function parseCanonicalUnsigned(value: string, label: string): bigint {\n  if (!CANONICAL_UNSIGNED.test(value)) {\n    throw new Error(`${label} must be a canonical unsigned decimal integer`);\n  }\n  const parsed = BigInt(value);\n  if (parsed > MAX_UNSIGNED_64) {\n    throw new Error(`${label} exceeds unsigned 64-bit range`);\n  }\n  return parsed;\n}\n","sourceCodeStart":1,"sourceCodeEnd":15,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/codex/src/harness/unsigned-integer.ts#L1-L15","documentation":"parseCanonicalUnsigned() enforces a 64-bit ceiling: values that match the canonical decimal grammar but exceed 2^64-1 throw '<label> exceeds unsigned 64-bit range'. The cap keeps ids/versions safely representable across languages and wire formats.","triggerScenarios":"Passing a lease version or sequence like '18446744073709551616' (2^64) or larger — e.g. timestamps-in-nanoseconds far in the future, ids derived from random 128-bit values, or corrupted/garbage numeric strings.","commonSituations":"Generators use Date.now()*1e6 or uuid-derived integers; upstream systems send 128-bit ids; fuzzing feeds huge strings into protocol fields.","solutions":["Identify the field via the label and fix the generator to stay within uint64","Use a different id scheme (hex string uuid) for values that legitimately exceed 2^64-1","Validate your inputs against the same ceiling before sending (BigInt(value) > (1n<<64n)-1n)"],"exampleFix":"// before\nversion: String(Number.MAX_SAFE_INTEGER * 1000); // ~9e18*1e3 > 2^64-1? no; use explicit example\nversion: '340282366920938463463374607431768211455'; // 2^128-1 -> throws\n// after\nconst MAX = (1n << 64n) - 1n;\nversion: (BigInt(counter) & MAX).toString();","handlingStrategy":"type-guard","validationCode":"const MAX_U64 = (1n << 64n) - 1n;\nfunction withinU64(v: string): boolean {\n  return /^(?:0|[1-9][0-9]*)$/.test(v) && BigInt(v) <= MAX_U64;\n}","typeGuard":"const MAX_U64 = (1n << 64n) - 1n;\nfunction isU64String(v: unknown): v is string {\n  return typeof v === 'string' && /^(?:0|[1-9][0-9]*)$/.test(v) && BigInt(v) <= MAX_U64;\n}","tryCatchPattern":"try { parseCanonicalUnsigned(value, label); } catch (e) { if (/exceeds unsigned 64-bit/.test(String(e))) throw new RangeError(`${label} out of range`); throw e; }","preventionTips":["Keep sequence/version counters as monotonic uint64 from the start","Never build ids from 128-bit randoms or far-future nanosecond timestamps","Mask or reject at the boundary: BigInt(v) > (1n<<64n)-1n"],"tags":["validation","integer-overflow","protocol","typescript"],"backgroundTag":"integer-overflow","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}