fix(capture): an override set to empty is an intent, not an absence

Review round 3 (P3). `if (!raw)` folded a SET-but-empty VEXA_CSRC_INACTIVE_MS
into "not set" and fell back in silence — which is exactly the ignored-knob
failure the previous commit's warning exists to prevent, and an empty value is
what a half-rendered deploy template looks like. Only `undefined` is an absence
now; everything else that cannot be honoured says so.

The default also stops being written three times; the fallback, the message and
the constant cannot drift apart any more.

Refs #150

Signed-off-by: Jacob Weinhold <jacob@philflow.io>

Author: Jacob Weinhold

core/meetings/services/bot/src/capture-bridge.ts

@@ -397,7 +397,25 @@ const TEAMS_ENABLE_CAPTIONS_ATTEMPTS = Math.max(1, Number(process.env.VEXA_TEAMS
  * this value was lost once before (#150). Overridable per deployment — and therefore per platform,
  * since each platform's bot is its own process — via VEXA_CSRC_INACTIVE_MS.
  */
-const CSRC_INACTIVE_MS = Math.max(1, Number(process.env.VEXA_CSRC_INACTIVE_MS || 800));
+/** The sensor's poll cadence (`CSRC_POLL_MS`). Not imported: this file must not pull the page-side
+ *  bundle into the Node build. Kept as the floor only, so a drift there is a slacker floor here,
+ *  never a wrong window. */
+const CSRC_MIN_INACTIVE_MS = 100;
+/** The measured window (#150). One name, so the fallback, the message and the default cannot drift. */
+const CSRC_DEFAULT_INACTIVE_MS = 800;
+export function resolveCsrcInactiveMs(raw: string | undefined, warn: (m: string) => void = () => { /* silent */ }): number {
+  // `undefined` is "no override", which is the normal case and silent. An override that was SET —
+  // including an empty or blank one, which is what a half-finished deploy template looks like — is
+  // an intent that could not be honoured, and gets said out loud.
+  if (raw === undefined) return CSRC_DEFAULT_INACTIVE_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < CSRC_MIN_INACTIVE_MS) {
+    warn(`[bot] VEXA_CSRC_INACTIVE_MS=${JSON.stringify(raw)} is not a usable window (finite, >= ${CSRC_MIN_INACTIVE_MS}ms) — using the measured ${CSRC_DEFAULT_INACTIVE_MS}ms`);
+    return CSRC_DEFAULT_INACTIVE_MS;
+  }
+  return n;
+}
+const CSRC_INACTIVE_MS = resolveCsrcInactiveMs(process.env.VEXA_CSRC_INACTIVE_MS, (m) => console.warn(m));
 
 /** Outcome of one enable attempt. `already-on` and `clicked` are successes; `failed` carries WHY,
  *  because "captions never appeared" has two very different causes — the menu path changed, or the

core/meetings/services/bot/src/csrc-wiring.test.ts

@@ -25,7 +25,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import {
-  startCaptureBridge, makeCsrcSink, makeObservationSink,
+  startCaptureBridge, makeCsrcSink, makeObservationSink, resolveCsrcInactiveMs,
   type CsrcRecord, type CsrcCapableSink, type ObservationRecord, type ObservationCapableSink,
 } from './capture-bridge.js';
 import type { Invocation } from './config.js';
@@ -87,6 +87,46 @@ const check = (name: string, cond: boolean, detail?: string) => {
     warnings.some((w) => w.includes('observation-clock-skew')) && stored[2].t >= t, warnings.join(' | '));
 }
 
+// ── the window is resolved from env, and garbage never reaches the sensor ───────────────────────
+// The sensor resolves its option with `??`, which passes NaN through, and a NaN window makes BOTH
+// of its comparisons false: every source is re-deactivated on every poll — the fragmentation this
+// value exists to end, worse and silent. So an unusable override falls back rather than propagating.
+{
+  check('window: no override ⇒ the measured 800ms', resolveCsrcInactiveMs(undefined) === 800,
+    String(resolveCsrcInactiveMs(undefined)));
+  check('window: a usable override wins', resolveCsrcInactiveMs('1200') === 1200,
+    String(resolveCsrcInactiveMs('1200')));
+  check('window: garbage falls back instead of becoming NaN',
+    resolveCsrcInactiveMs('abc') === 800, String(resolveCsrcInactiveMs('abc')));
+  check('window: zero, negative and empty fall back too — none of them is a window',
+    resolveCsrcInactiveMs('0') === 800 && resolveCsrcInactiveMs('-5') === 800 && resolveCsrcInactiveMs('') === 800,
+    `${resolveCsrcInactiveMs('0')}/${resolveCsrcInactiveMs('-5')}/${resolveCsrcInactiveMs('')}`);
+  // A window shorter than one poll is stale before the next tick — the NaN failure mode wearing an
+  // ordinary number. It is rejected at the floor, not accepted because it happens to be positive.
+  check('window: shorter than one 100ms poll is rejected, one poll exactly is kept',
+    resolveCsrcInactiveMs('1') === 800 && resolveCsrcInactiveMs('99') === 800 && resolveCsrcInactiveMs('100') === 100,
+    `${resolveCsrcInactiveMs('1')}/${resolveCsrcInactiveMs('99')}/${resolveCsrcInactiveMs('100')}`);
+  {
+    const warnings: string[] = [];
+    const used = resolveCsrcInactiveMs('abc', (m) => warnings.push(m));
+    check('window: a rejected override is SAID OUT LOUD, never silently ignored',
+      used === 800 && warnings.length === 1 && warnings[0]!.includes('VEXA_CSRC_INACTIVE_MS="abc"'),
+      JSON.stringify(warnings));
+    const quiet: string[] = [];
+    resolveCsrcInactiveMs(undefined, (m) => quiet.push(m));
+    resolveCsrcInactiveMs('1200', (m) => quiet.push(m));
+    check('window: no override and a good override are both silent — only a REJECTION warns',
+      quiet.length === 0, JSON.stringify(quiet));
+    // An empty override is what a half-rendered deploy template looks like. Treating it as "not
+    // set" is how a knob gets ignored in silence — the exact failure the warning exists to prevent.
+    const blank: string[] = [];
+    check('window: an override SET to empty or blank warns too — it is an intent, not an absence',
+      resolveCsrcInactiveMs('', (m) => blank.push(m)) === 800
+      && resolveCsrcInactiveMs('   ', (m) => blank.push(m)) === 800
+      && blank.length === 2, JSON.stringify(blank));
+  }
+}
+
 // ── The real bundle (built by build-browser-utils.mjs — turbo test depends on build) ─────────────
 const BUNDLE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'dist', 'browser-utils.global.js');
 if (!existsSync(BUNDLE)) {