perf: harden realtime localization pipeline

packages/acoustics-core/frequency-response.js

@@ -2,6 +2,33 @@ import { dbToLinear } from "./math.js";
 
 export const MAX_FREQUENCY_RESPONSE_POINTS = 64;
 export const MAX_FREQUENCY_RESPONSE_HZ = 1_000_000;
+export const DEFAULT_MAX_COMPENSATION_DB = 24;
+export const MAX_COMPENSATION_DB = 120;
+
+export function requireMaxCompensationDb(
+  value = DEFAULT_MAX_COMPENSATION_DB,
+  label = "maxCompensationDb",
+) {
+  if (!Number.isFinite(value) || value < 0 || value > MAX_COMPENSATION_DB) {
+    throw new RangeError(`${label} must lie inside 0..${MAX_COMPENSATION_DB} dB.`);
+  }
+  return value;
+}
+
+/**
+ * Return the inverse response gain in dB while limiting only positive boost.
+ * Attenuation remains exact because it cannot amplify a response notch or the
+ * microphone self-noise that occupies it.
+ */
+export function inverseResponseGainDb(responseGainDb, maxCompensationDb) {
+  if (!Number.isFinite(responseGainDb)) {
+    throw new RangeError("responseGainDb must be finite.");
+  }
+  return Math.min(
+    -responseGainDb,
+    requireMaxCompensationDb(maxCompensationDb),
+  );
+}
 
 function phaseAt(point) {
   return point.phaseDeg ?? 0;