SY-4149: preserve bigint channel precision through the float32 GL render pipeline

values above 2^53 (timestamps, int64, uint64) were quantizing to multiples of the float32 ULP at display time; route bigint offsets through bigint arithmetic and preserve bigint precision in stringifyNumber's standard branch

Author: sy-nico

pluto/src/telem/aether/convertSeries.spec.ts

@@ -0,0 +1,114 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { DataType, Series } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import {
+  convertSeriesToSupportedGL,
+  resolveGLDataType,
+} from "@/telem/aether/convertSeries";
+
+describe("convertSeriesToSupportedGL", () => {
+  it("returns the original series for variable data types", () => {
+    const series = new Series({
+      data: ["a", "b", "c"],
+      dataType: DataType.STRING,
+    });
+    expect(convertSeriesToSupportedGL(series)).toBe(series);
+  });
+
+  it("returns the original series for UINT8", () => {
+    const series = new Series({
+      data: new Uint8Array([1, 2, 3]),
+      dataType: DataType.UINT8,
+    });
+    expect(convertSeriesToSupportedGL(series)).toBe(series);
+  });
+
+  it("converts a FLOAT64 series to FLOAT32 with no offset", () => {
+    const series = new Series({
+      data: new Float64Array([1.5, 2.5, 3.5]),
+      dataType: DataType.FLOAT64,
+    });
+    const result = convertSeriesToSupportedGL(series);
+    expect(result.dataType.equals(DataType.FLOAT32)).toBe(true);
+    expect(result.at(0)).toBe(1.5);
+    expect(result.at(1)).toBe(2.5);
+    expect(result.at(2)).toBe(3.5);
+  });
+
+  it("defaults the offset to the first sample for INT64 to preserve precision above 2^53", () => {
+    const first = 1778020940471336960n;
+    const series = new Series({
+      data: [first, first + 1n, first + 2n],
+      dataType: DataType.INT64,
+    });
+    const result = convertSeriesToSupportedGL(series);
+    expect(result.dataType.equals(DataType.FLOAT32)).toBe(true);
+    expect(result.sampleOffset).toBe(first);
+    expect(result.at(0)).toBe(first);
+    expect(result.at(1)).toBe(first + 1n);
+    expect(result.at(2)).toBe(first + 2n);
+  });
+
+  it("defaults the offset to the first sample for UINT64 to preserve precision above 2^53", () => {
+    const first = 1778020940471336960n;
+    const series = new Series({
+      data: [first, first + 1n, first + 2n],
+      dataType: DataType.UINT64,
+    });
+    const result = convertSeriesToSupportedGL(series);
+    expect(result.dataType.equals(DataType.FLOAT32)).toBe(true);
+    expect(result.sampleOffset).toBe(first);
+    expect(result.at(0)).toBe(first);
+  });
+
+  it("defaults the offset to the first sample for TIMESTAMP to preserve precision above 2^53", () => {
+    const first = 1778020940471336960n;
+    const series = new Series({
+      data: [first, first + 1n, first + 2n],
+      dataType: DataType.TIMESTAMP,
+    });
+    const result = convertSeriesToSupportedGL(series);
+    expect(result.dataType.equals(DataType.FLOAT32)).toBe(true);
+    expect(result.sampleOffset).toBe(first);
+    expect(result.at(0)).toBe(first);
+  });
+
+  it("respects an explicitly provided offset for bigint series", () => {
+    const offset = 1778020940471336000n;
+    const first = 1778020940471336960n;
+    const series = new Series({
+      data: [first, first + 1n, first + 2n],
+      dataType: DataType.INT64,
+    });
+    const result = convertSeriesToSupportedGL(series, offset);
+    expect(result.sampleOffset).toBe(offset);
+  });
+});
+
+describe("resolveGLDataType", () => {
+  it("returns variable data types unchanged", () => {
+    expect(resolveGLDataType(DataType.STRING).equals(DataType.STRING)).toBe(true);
+    expect(resolveGLDataType(DataType.JSON).equals(DataType.JSON)).toBe(true);
+  });
+
+  it("returns UINT8 unchanged", () => {
+    expect(resolveGLDataType(DataType.UINT8).equals(DataType.UINT8)).toBe(true);
+  });
+
+  it("returns FLOAT32 for any other fixed-density data type", () => {
+    expect(resolveGLDataType(DataType.FLOAT64).equals(DataType.FLOAT32)).toBe(true);
+    expect(resolveGLDataType(DataType.INT64).equals(DataType.FLOAT32)).toBe(true);
+    expect(resolveGLDataType(DataType.UINT64).equals(DataType.FLOAT32)).toBe(true);
+    expect(resolveGLDataType(DataType.TIMESTAMP).equals(DataType.FLOAT32)).toBe(true);
+    expect(resolveGLDataType(DataType.INT32).equals(DataType.FLOAT32)).toBe(true);
+  });
+});

pluto/src/telem/aether/convertSeries.ts

@@ -16,9 +16,11 @@ import { DataType, type math, type Series } from "@synnaxlabs/x";
  * offset applied.
  *
  * @param series - The series to convert.
- * @param offset - An optional offset to apply to the series. If the series is a timestamp
- * series, the default offset is applied to the first value in the series. This helps fix
- * issues with reducing precision from uint64s to float32s at high nanosecond values.
+ * @param offset - An optional offset to apply to the series. If the series uses bigint
+ * storage (timestamp, int64, uint64) and no offset is provided, the first sample is used
+ * as the default offset. This preserves precision when narrowing 64-bit integers to
+ * float32, which would otherwise quantize values above 2^53 to multiples of the float32
+ * ULP at that magnitude.
  * @returns The converted series.
  */
 export const convertSeriesToSupportedGL = (
@@ -27,8 +29,7 @@ export const convertSeriesToSupportedGL = (
 ): Series => {
   if (series.dataType.isVariable || series.dataType.equals(DataType.UINT8))
     return series;
-  if (offset == null && series.dataType.equals(DataType.TIMESTAMP))
-    offset = BigInt(series.data[0]);
+  if (offset == null && series.dataType.usesBigInt) offset = BigInt(series.data[0]);
   return series.convert(DataType.FLOAT32, offset);
 };
 

pluto/src/telem/aether/transformers.spec.ts

@@ -10,7 +10,13 @@
 import { DataType, MultiSeries, Series, TimeRange } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 
-import { SeriesDownsampler } from "@/telem/aether/transformers";
+import { TestSource } from "@/telem/aether/test/source";
+import {
+  RollingAverage,
+  ScaleNumber,
+  SeriesDownsampler,
+  StringifyNumber,
+} from "@/telem/aether/transformers";
 
 describe("SeriesDownsampler", () => {
   describe("decimate mode", () => {
@@ -443,3 +449,63 @@ describe("SeriesDownsampler", () => {
     });
   });
 });
+
+describe("StringifyNumber", () => {
+  it("formats a number value with prefix and suffix", () => {
+    const t = new StringifyNumber({ precision: 2, prefix: "$", suffix: " USD" });
+    t.setSources({ in: new TestSource(42) });
+    expect(t.value()).toBe("$42.00 USD");
+  });
+
+  it("preserves full precision for a bigint value above 2^53 in standard notation", () => {
+    const t = new StringifyNumber({ precision: 0, notation: "standard" });
+    t.setSources({ in: new TestSource(1778020940471336960n) });
+    expect(t.value()).toBe("1778020940471336960");
+  });
+
+  it("does not crash and returns a finite string for a bigint value", () => {
+    const t = new StringifyNumber({ precision: 2, notation: "scientific" });
+    t.setSources({ in: new TestSource(1778020940471336960n) });
+    expect(t.value()).toBe("1.78ᴇ18");
+  });
+
+  it("returns an empty string for NaN", () => {
+    const t = new StringifyNumber({ precision: 2 });
+    t.setSources({ in: new TestSource(NaN) });
+    expect(t.value()).toBe("");
+  });
+});
+
+describe("RollingAverage", () => {
+  it("returns the value unchanged when windowSize is less than 2", () => {
+    const t = new RollingAverage({ windowSize: 1 });
+    t.setSources({ in: new TestSource(42) });
+    expect(t.value()).toBe(42);
+  });
+
+  it("coerces a bigint value to a number", () => {
+    const t = new RollingAverage({ windowSize: 1 });
+    t.setSources({ in: new TestSource(123n) });
+    expect(t.value()).toBe(123);
+  });
+});
+
+describe("ScaleNumber", () => {
+  it("applies the scale and offset to a number value", () => {
+    const t = new ScaleNumber({ scale: { scale: 2, offset: 3 } });
+    t.setSources({ in: new TestSource(10) });
+    expect(t.value()).toBe(23);
+  });
+
+  it("coerces a bigint value to a number before scaling", () => {
+    const t = new ScaleNumber({ scale: { scale: 2, offset: 0 } });
+    t.setSources({ in: new TestSource(50n) });
+    expect(t.value()).toBe(100);
+  });
+
+  it("returns NaN when given NaN", () => {
+    const t = new ScaleNumber({ scale: { scale: 2, offset: 3 } });
+    t.setSources({ in: new TestSource(NaN) });
+    expect(Number.isNaN(t.value())).toBe(true);
+  });
+});

pluto/src/telem/aether/transformers.ts

@@ -12,6 +12,7 @@ import {
   bounds,
   color,
   id,
+  type math,
   MultiSeries,
   notation,
   scale,
@@ -177,16 +178,16 @@ export const stringifyNumberProps = z.object({
 });
 
 export class StringifyNumber extends UnarySourceTransformer<
-  number,
+  math.Numeric,
   string,
   typeof stringifyNumberProps
 > {
   static readonly TYPE = "stringify-number";
   static readonly propsZ = stringifyNumberProps;
   schema = StringifyNumber.propsZ;
 
-  protected transform(value: number): string {
-    if (isNaN(value)) return "";
+  protected transform(value: math.Numeric): string {
+    if (typeof value === "number" && isNaN(value)) return "";
     const { precision, prefix, suffix, notation: pNotation } = this.props;
     return `${prefix}${notation.stringifyNumber(value, precision, pNotation)}${suffix}`;
   }
@@ -206,7 +207,7 @@ export const rollingAverageProps = z.object({
 });
 
 export class RollingAverage extends UnarySourceTransformer<
-  number,
+  math.Numeric,
   number,
   typeof rollingAverageProps
 > {
@@ -215,15 +216,16 @@ export class RollingAverage extends UnarySourceTransformer<
   schema = rollingAverageProps;
   private values: number[] = [];
 
-  protected transform(value: number): number {
-    if (this.props.windowSize < 2 || isNaN(value)) return value;
+  protected transform(value: math.Numeric): number {
+    const num = Number(value);
+    if (this.props.windowSize < 2 || isNaN(num)) return num;
     return this.values.reduce((a, b) => a + b, 0) / this.values.length;
   }
 
-  protected shouldNotify(value: number): boolean {
+  protected shouldNotify(value: math.Numeric): boolean {
     if (this.props.windowSize < 2) return true;
     if (this.values.length > this.props.windowSize) this.values = [];
-    this.values.push(value);
+    this.values.push(Number(value));
     return this.values.length === this.props.windowSize;
   }
 }
@@ -269,18 +271,19 @@ export const scaleNumberProps = z.object({
 });
 
 export class ScaleNumber extends UnarySourceTransformer<
-  number,
+  math.Numeric,
   number,
   typeof scaleNumberProps
 > {
   static readonly TYPE = "scale-number";
   static readonly propsZ = scaleNumberProps;
   schema = ScaleNumber.propsZ;
 
-  protected transform(value: number): number {
-    if (isNaN(value)) return value;
+  protected transform(value: math.Numeric): number {
+    const num = Number(value);
+    if (isNaN(num)) return num;
     const { offset, scale } = this.props.scale;
-    return value * scale + offset;
+    return num * scale + offset;
   }
 }
 

pluto/src/telem/client/cache/dynamic.spec.ts

@@ -146,6 +146,35 @@ describe("DynamicCache", () => {
         expect(flushed.series[0]).toBe(allocated.series[0]);
         expect(allocated).toHaveLength(6);
       });
+      it("should allocate the buffer with a bigint sampleOffset for bigint data types", () => {
+        const nowTs = TimeStamp.seconds(1);
+        const cache = new Dynamic({
+          dynamicBufferSize: 100,
+          dataType: DataType.INT64,
+          now: () => nowTs,
+        });
+        const ser = new Series({
+          data: [nowTs.valueOf(), nowTs.valueOf() + 1n, nowTs.valueOf() + 2n],
+          dataType: DataType.INT64,
+        });
+        const { allocated } = cache.write(new MultiSeries([ser]));
+        expect(allocated.series).toHaveLength(1);
+        expect(allocated.series[0].sampleOffset).toBe(nowTs.valueOf());
+        expect(allocated.series[0].dataType.equals(DataType.FLOAT32)).toBe(true);
+      });
+      it("should allocate the buffer with a numeric sampleOffset for non-bigint data types", () => {
+        const cache = new Dynamic({
+          dynamicBufferSize: 100,
+          dataType: DataType.FLOAT32,
+        });
+        const ser = new Series({
+          data: new Float32Array([1, 2, 3]),
+          dataType: DataType.FLOAT32,
+        });
+        const { allocated } = cache.write(new MultiSeries([ser]));
+        expect(allocated.series).toHaveLength(1);
+        expect(allocated.series[0].sampleOffset).toBe(0);
+      });
       it("should allocate a buffer properly using a TimeSpan", () => {
         let nowF = () => TimeStamp.seconds(1);
         const now = () => nowF();

pluto/src/telem/client/cache/dynamic.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import {
-  DataType,
+  type DataType,
   math,
   MultiSeries,
   Series,
@@ -120,12 +120,11 @@ export class Dynamic {
   private allocate(capacity: number, alignment: bigint, start: TimeStamp): Series {
     this.counter++;
     const isVariable = this.props.dataType.isVariable;
-    const isTimestamp = this.props.dataType.equals(DataType.TIMESTAMP);
     return Series.alloc({
       capacity: isVariable ? capacity * VARIABLE_DT_MULTIPLIER : capacity,
       dataType: resolveGLDataType(this.props.dataType),
       timeRange: start.range(TimeStamp.MAX),
-      sampleOffset: isTimestamp ? start.valueOf() : 0,
+      sampleOffset: this.props.dataType.usesBigInt ? start.valueOf() : 0,
       glBufferUsage: "dynamic",
       alignment,
       key: `dynamic-${this.counter}`,