fix: expose physical aliasing and delayed arrivals

packages/acoustics-core/math.js

@@ -1,5 +1,34 @@
 export const TAU = Math.PI * 2;
 
+/**
+ * Ceil a sample position while keeping an analytically integral boundary on
+ * that integer. IEEE-754 roundoff from expressions such as (0.1 + 0.2) * 1000
+ * must not add a physically nonexistent sample of latency.
+ */
+export function ceilSamplePosition(samplePosition) {
+  if (!Number.isFinite(samplePosition)) {
+    throw new TypeError("sample position must be finite.");
+  }
+  const nearestInteger = Math.round(samplePosition);
+  const tolerance =
+    16 * Number.EPSILON * Math.max(1, Math.abs(samplePosition));
+  const result = Math.abs(samplePosition - nearestInteger) <= tolerance
+    ? nearestInteger
+    : Math.ceil(samplePosition);
+  if (!Number.isSafeInteger(result)) {
+    throw new RangeError("sample position exceeds the safe integer range.");
+  }
+  return result;
+}
+
+export function ceilSampleIndex(timeSeconds, sampleRate) {
+  if (!Number.isFinite(timeSeconds)) throw new TypeError("time must be finite.");
+  if (!(sampleRate > 0) || !Number.isFinite(sampleRate)) {
+    throw new TypeError("sampleRate must be finite and positive.");
+  }
+  return ceilSamplePosition(timeSeconds * sampleRate);
+}
+
 export function distance3(a, b) {
   return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 }