perf(voiceclaw-realtime, server-maintenance): audit-driven hot-path wins

SAGE · SAGE · commit 8c60fb4013aa · 2026-05-03T05:05:15.000-07:00
Acted on the SAGE-side optimization audit (~/Documents/sage/self-improvement-audit/report.md, openclaw section). #1 — xai-realtime.ts:719 — replace per-overflow O(n) `.shift()` with batched 25% splice. Hot voice path; under sustained overflow the old shift-per-push was N*overflow_count. Batch trim drops 25% in one splice so amortized per-push cost is O(1) (audio overflow always meant data loss anyway; trimming a quarter at once is cleaner than dropping one frame at a time). #7 — server-maintenance.ts:93 — `[...map.entries()].toSorted(...)` allocates two distinct copies (spread + toSorted internal). Switched to single Array.from(...) + in-place .sort(). Drops one allocation per maintenance tick. #8 — xai-realtime.ts:698 + isValidXaiVoice — `.find()` / `.includes()` over the const XAI_VOICES tuple was O(N) per voice resolution. Pre-built `_XAI_VOICE_SET = new Set(XAI_VOICES)`; lookups are now O(1). Skipped #2 (audit suggested merging 4 server-maintenance Map iterations into one — they touch DIFFERENT collections; merging would be artificial code, not real perf). Multi-day refactors of attempt.ts / loader.ts / chat.ts deferred per audit recommendation.
diff --git a/src/gateway/server-maintenance.ts b/src/gateway/server-maintenance.ts
@@ -90,8 +90,13 @@ export function startGatewayMaintenanceTimers(params: {
       }
     }
     if (params.dedupe.size > DEDUPE_MAX) {
-      const entries = [...params.dedupe.entries()].toSorted((a, b) => a[1].ts - b[1].ts);
-      for (let i = 0; i < params.dedupe.size - DEDUPE_MAX; i++) {
+      // pt 235n (audit #7) — was [...map.entries()].toSorted(...).
+      // Both spread + toSorted allocate distinct copies. Single
+      // Array.from + in-place sort drops one allocation per tick.
+      const entries = Array.from(params.dedupe.entries());
+      entries.sort((a, b) => a[1].ts - b[1].ts);
+      const target = params.dedupe.size - DEDUPE_MAX;
+      for (let i = 0; i < target; i++) {
         params.dedupe.delete(entries[i][0]);
       }
     }
diff --git a/src/gateway/voiceclaw-realtime/xai-realtime.ts b/src/gateway/voiceclaw-realtime/xai-realtime.ts
@@ -27,6 +27,10 @@ const DEFAULT_OUTPUT_AUDIO_FORMAT = "pcm16";
 // https://docs.x.ai/developers/model-capabilities/audio/voice-agent
 export const XAI_VOICES = ["eve", "ara", "rex", "sal", "leo"] as const;
 export type XaiVoice = (typeof XAI_VOICES)[number];
+
+// pt 235n (audit #8) — Set lookup avoids the per-voice-resolution
+// linear .find() / .includes() walk over the const tuple.
+const _XAI_VOICE_SET: ReadonlySet<string> = new Set(XAI_VOICES);
 export const DEFAULT_XAI_VOICE: XaiVoice = "ara";
 
 type XaiMessage = Record<string, unknown>;
@@ -695,12 +699,13 @@ export function resolveXaiVoice(voice?: string): XaiVoice {
     return DEFAULT_XAI_VOICE;
   }
   const normalized = voice.toLowerCase();
-  const match = XAI_VOICES.find((candidate) => candidate === normalized);
-  return match ?? DEFAULT_XAI_VOICE;
+  // pt 235n — O(1) Set lookup
+  return _XAI_VOICE_SET.has(normalized) ? (normalized as XaiVoice) : DEFAULT_XAI_VOICE;
 }
 
 export function isValidXaiVoice(voice: string): boolean {
-  return (XAI_VOICES as readonly string[]).includes(voice.toLowerCase());
+  // pt 235n — O(1) Set lookup
+  return _XAI_VOICE_SET.has(voice.toLowerCase());
 }
 
 function queueBounded(
@@ -716,7 +721,12 @@ function queueBounded(
   }
   if (kind === "audio") {
     if (queues.audio.length >= MAX_PENDING_AUDIO) {
-      queues.audio.shift();
+      // pt 235n (audit #1) — was .shift() per overflow which is
+      // O(n) array shift. Hot voice path; under sustained
+      // overflow that's N*shift_count. Batch-trim 25% in a
+      // single splice so the amortized per-push cost is O(1).
+      const drop = Math.max(1, Math.floor(MAX_PENDING_AUDIO / 4));
+      queues.audio.splice(0, drop);
     }
     queues.audio.push(payload);
     return;

Original file line number	Diff line number	Diff line change
`@@ -90,8 +90,13 @@ export function startGatewayMaintenanceTimers(params: {`
`90`	`90`	`}`
`91`	`91`	`}`
`92`	`92`	`if (params.dedupe.size > DEDUPE_MAX) {`
`93`		`- const entries = [...params.dedupe.entries()].toSorted((a, b) => a[1].ts - b[1].ts);`
`94`		`- for (let i = 0; i < params.dedupe.size - DEDUPE_MAX; i++) {`
	`93`	`+ // pt 235n (audit #7) — was [...map.entries()].toSorted(...).`
	`94`	`+ // Both spread + toSorted allocate distinct copies. Single`
	`95`	`+ // Array.from + in-place sort drops one allocation per tick.`
	`96`	`+ const entries = Array.from(params.dedupe.entries());`
	`97`	`+ entries.sort((a, b) => a[1].ts - b[1].ts);`
	`98`	`+ const target = params.dedupe.size - DEDUPE_MAX;`
	`99`	`+ for (let i = 0; i < target; i++) {`
`95`	`100`	`params.dedupe.delete(entries[i][0]);`
`96`	`101`	`}`
`97`	`102`	`}`