{"record":{"id":"4a5202e6ceec9d15","repo":"agalwood/Motrix","slug":"current-exceeds-the-signed-int64-range","errorCode":null,"errorMessage":"current exceeds the signed int64 range","messagePattern":"current exceeds the signed int64 range","errorType":"validation","errorClass":"RangeError","httpStatus":null,"severity":"critical","filePath":"src/core/inspector-activity/validators.ts","lineNumber":95,"sourceCode":"export function normalizeSpeed(value: number, label: string): number {\n  if (!Number.isFinite(value) || value < 0) {\n    throw new RangeError(`${label} must be finite and non-negative`)\n  }\n  const normalized = Math.round(value)\n  if (!Number.isSafeInteger(normalized)) {\n    throw new RangeError(`${label} exceeds the JavaScript safe integer range`)\n  }\n  return normalized\n}\n\nexport function saturatingAddSignedInt64(\n  current: bigint,\n  delta: bigint\n): { value: bigint; saturated: boolean } {\n  assertNonNegativeBigInt(current, 'current')\n  assertNonNegativeBigInt(delta, 'delta')\n  if (current > MAX_SIGNED_SQLITE_INTEGER) {\n    throw new RangeError('current exceeds the signed int64 range')\n  }\n  if (delta > MAX_SIGNED_SQLITE_INTEGER - current) {\n    return { value: MAX_SIGNED_SQLITE_INTEGER, saturated: true }\n  }\n  return { value: current + delta, saturated: false }\n}\n\nexport function saturatingAddSafeInteger(\n  current: number,\n  delta: number\n): { value: number; saturated: boolean } {\n  assertNonNegativeSafeInteger(current, 'current')\n  assertNonNegativeSafeInteger(delta, 'delta')\n  if (delta > MAX_SAFE_SQLITE_INTEGER - current) {\n    return { value: MAX_SAFE_SQLITE_INTEGER, saturated: true }\n  }\n  return { value: current + delta, saturated: false }\n}","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/inspector-activity/validators.ts#L77-L113","documentation":"`saturatingAddSignedInt64` adds a non-negative bigint `delta` to a non-negative bigint `current` and saturates at `MAX_SIGNED_SQLITE_INTEGER` (2^63-1, ~9.22e18). It throws this `RangeError` *before* adding if `current` alone already exceeds that bound — meaning the running counter is in a corrupted state the saturating helper was designed to prevent. Because `current` passed the immediately-preceding `assertNonNegativeBigInt`, a hit here indicates the counter was already poisoned upstream. The guard keeps SQLite 8-byte `INTEGER` columns in range.","triggerScenarios":"Calling `saturatingAddSignedInt64(current, delta)` where `current` is a bigint byte-counter (e.g. an `estimatedDownloadBytesDelta` accumulator) greater than `9_223_372_036_854_775_807n` (~8 EiB). Both inputs already passed the non-negative-bigint precondition, so this fires only when the cumulative counter is astronomically — and almost certainly wrongly — large.","commonSituations":"An upstream double-counting bug that increments the lifetime byte counter twice per sample; persisted state restored from a corrupted row; tests feeding a synthetic 2^64-scale value through without saturation; arithmetic that confused bytes with bits and shifted the magnitude.","solutions":["Audit every code path that mutates the `current` accumulator — `saturatingAddSignedInt64` should be the only mutator.","Recompute the corrupted counter from durable source-of-truth data (engine snapshot) and replace it before calling again.","If the value legitimately could be that large, reconsider the storage type — the SQLite INTEGER column is the binding constraint.","Add a regression test that drives the counter toward saturation and asserts it clamps rather than throws."],"exampleFix":"// before\ntotalBytes = totalBytes + delta  // totalBytes already > 2^63-1\n// after\nconst { value } = saturatingAddSignedInt64(totalBytes, delta)\ntotalBytes = value","handlingStrategy":"validation","validationCode":"import { MAX_SIGNED_SQLITE_INTEGER } from '@core/inspector-activity/validators'\nfunction guardAdd(current: bigint, delta: bigint): bigint {\n  if (current > MAX_SIGNED_SQLITE_INTEGER)\n    throw new RangeError(`current already corrupted: ${current}`)\n  return current + delta\n}","typeGuard":"import { MAX_SIGNED_SQLITE_INTEGER } from '@core/inspector-activity/validators'\nfunction isSignedInt64Bigint(v: unknown): v is bigint {\n  return typeof v === 'bigint' && v >= 0n && v <= MAX_SIGNED_SQLITE_INTEGER\n}","tryCatchPattern":"try {\n  saturatingAddSignedInt64(current, delta)\n} catch (err) {\n  if (err instanceof RangeError && err.message === 'current exceeds the signed int64 range') {\n    // recompute current from durable source before retrying\n  } else throw err\n}","preventionTips":["Route every mutation of the byte counter through `saturatingAddSignedInt64` — never add to it directly.","Treat a hit as data corruption, not a recoverable input error; recompute from durable state.","Log the corrupted value to telemetry so the upstream double-count can be traced."],"tags":["validation","range-error","bigint","sqlite","data-integrity"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}