@libraz/libsonare 1.7.2 → 1.8.0

package/src/worklet/mixer-processor.ts

@@ -1,7 +1,7 @@
 import type { MixerRealtimeBuffer } from '../index';
 import { Mixer } from '../index';
 import type { WorkletInput, WorkletOutput } from './audio_types';
-import { isWorkletMessage } from './guards';
+import { isWorkletMessage, requireIntegerOption } from './guards';
 import type {
   SonareWorkletMessage,
   SonareWorkletProcessorOptions,
@@ -19,7 +19,6 @@ import {
   type SonareWorkletMeterSnapshot,
   type SonareWorkletSpectrumSnapshot,
   spectrumRingFromSharedBuffer,
-  toDb,
 } from './protocol';
 
 /**
@@ -43,6 +42,30 @@ export class SonareWorkletProcessor {
   private lastSpectrumFrame = 0;
   private transport?: WorkletTransport;
   private meterRing?: SharedMeterRingWriter;
+  /**
+   * Reused meter record, so a publish writes fields instead of allocating one.
+   *
+   * `targetId` is always the master and the four LUFS / gain-reduction fields
+   * are always unavailable here — the mixer worklet does not run the
+   * K-weighting filters, and a floor value would read as silence — so both are
+   * set once rather than per interval.
+   */
+  private readonly meterScratch: SonareWorkletMeterSnapshot = {
+    type: 'meter',
+    targetId: 0,
+    frame: 0,
+    peakDbL: 0,
+    peakDbR: 0,
+    rmsDbL: 0,
+    rmsDbR: 0,
+    correlation: 0,
+    truePeakDbL: 0,
+    truePeakDbR: 0,
+    momentaryLufs: Number.NaN,
+    shortTermLufs: Number.NaN,
+    integratedLufs: Number.NaN,
+    gainReductionDb: Number.NaN,
+  };
   private spectrumRing?: SharedSpectrumRingWriter;
   private spectrumBands: Float32Array;
 
@@ -52,10 +75,20 @@ export class SonareWorkletProcessor {
     }
     this.sampleRate = options.sampleRate ?? 48000;
     this.blockSize = options.blockSize ?? 128;
-    this.meterIntervalFrames = Math.max(0, Math.floor(options.meterIntervalFrames ?? 2048));
-    this.spectrumIntervalFrames = Math.max(0, Math.floor(options.spectrumIntervalFrames ?? 0));
+    // Zero is the off switch for both publications, so the floor is 0.
+    this.meterIntervalFrames = requireIntegerOption(
+      options.meterIntervalFrames,
+      2048,
+      'meterIntervalFrames',
+      0,
+    );
+    this.spectrumIntervalFrames = requireIntegerOption(
+      options.spectrumIntervalFrames,
+      0,
+      'spectrumIntervalFrames',
+      0,
+    );
     this.transport = transport;
-    this.meterIntervalFrames = Math.max(0, Math.floor(options.meterIntervalFrames ?? 2048));
     this.meterRing = options.meterSharedBuffer
       ? meterRingFromSharedBuffer(options.meterSharedBuffer, options.meterRingCapacity)
       : undefined;
@@ -76,6 +109,10 @@ export class SonareWorkletProcessor {
       throw new Error('stripCount must match the scene strip count.');
     }
     this.realtime = this.mixer.createRealtimeBuffer();
+    // The mixer meters the master it just produced, so the true-peak filter sees
+    // every block without the worklet copying the output back in. 4x is the
+    // BS.1770-4 Annex 2 minimum.
+    this.mixer.configureMeter(this.meterIntervalFrames > 0, 4);
   }
 
   process(inputs: WorkletInput, outputs: WorkletOutput): boolean {
@@ -132,10 +169,7 @@ export class SonareWorkletProcessor {
       }
     }
     this.processedFrames += usable;
-    this.publishMeter(
-      this.realtime.outLeft.subarray(0, usable),
-      this.realtime.outRight.subarray(0, usable),
-    );
+    this.publishMeter();
     this.publishSpectrum(
       this.realtime.outLeft.subarray(0, usable),
       this.realtime.outRight.subarray(0, usable),
@@ -152,7 +186,15 @@ export class SonareWorkletProcessor {
       return;
     }
     if (message.type === 'setMeterInterval') {
-      this.meterIntervalFrames = Math.max(0, Math.floor(message.frames));
+      const frames = Math.max(0, Math.floor(message.frames));
+      // Toggling metering also toggles the mixer's meter, so a disabled meter
+      // costs nothing per block. Re-enabling restarts it: the filter history and
+      // the published snapshot are from before the gap, and carrying them
+      // forward would report a peak the caller never asked to be measured.
+      if (frames > 0 !== this.meterIntervalFrames > 0) {
+        this.mixer.configureMeter(frames > 0, 4);
+      }
+      this.meterIntervalFrames = frames;
       return;
     }
     if (message.type === 'scheduleInsertAutomation') {
@@ -174,8 +216,10 @@ export class SonareWorkletProcessor {
     }
   }
 
-  private publishMeter(left: Float32Array, right: Float32Array): void {
-    if (!this.transport || this.meterIntervalFrames <= 0) {
+  private publishMeter(): void {
+    // Symmetric with the engine processor: a ring-only configuration still has
+    // meters to publish, so the absence of a transport alone must not skip it.
+    if ((!this.transport && !this.meterRing) || this.meterIntervalFrames <= 0) {
       return;
     }
     if (this.processedFrames - this.lastMeterFrame < this.meterIntervalFrames) {
@@ -183,50 +227,64 @@ export class SonareWorkletProcessor {
     }
     this.lastMeterFrame = this.processedFrames;
 
-    let peakL = 0;
-    let peakR = 0;
-    let sumL = 0;
-    let sumR = 0;
-    let sumLR = 0;
-    for (let i = 0; i < left.length; i++) {
-      const l = left[i] ?? 0;
-      const r = right[i] ?? 0;
-      const absL = Math.abs(l);
-      const absR = Math.abs(r);
-      if (absL > peakL) {
-        peakL = absL;
-      }
-      if (absR > peakR) {
-        peakR = absR;
-      }
-      sumL += l * l;
-      sumR += r * r;
-      sumLR += l * r;
+    // Latch the reading into the mixer's own scratch and read the seven fields
+    // back as numbers. `meterSnapshot()` returns a fresh embind object, so
+    // calling it here would allocate on the render thread once per interval —
+    // about 23 per second at the default — no matter what this file then does
+    // with the result. Scratch field order, shared with the engine's
+    // meterScratchValue: 0 peakDbL, 1 peakDbR, 2 rmsDbL, 3 rmsDbR,
+    // 4 correlation, 5 truePeakDbL, 6 truePeakDbR.
+    if (!this.mixer.latchMeterSnapshot()) {
+      // The meter has never been enabled, so there is no reading to publish.
+      return;
+    }
+    if (this.meterRing) {
+      // Fill the reusable record and serialise it straight into the ring, which
+      // exists precisely so this thread allocates and posts nothing. The record
+      // never escapes, so reuse is safe here in a way it is not on the
+      // postMessage path below.
+      const meter = this.meterScratch;
+      meter.frame = this.processedFrames;
+      meter.peakDbL = this.mixer.meterScratchValue(0);
+      meter.peakDbR = this.mixer.meterScratchValue(1);
+      meter.rmsDbL = this.mixer.meterScratchValue(2);
+      meter.rmsDbR = this.mixer.meterScratchValue(3);
+      meter.correlation = this.mixer.meterScratchValue(4);
+      meter.truePeakDbL = this.mixer.meterScratchValue(5);
+      meter.truePeakDbR = this.mixer.meterScratchValue(6);
+      this.writeMeterRing(meter);
+      return;
     }
-    const rmsL = Math.sqrt(sumL / Math.max(1, left.length));
-    const rmsR = Math.sqrt(sumR / Math.max(1, right.length));
-    const denominator = Math.sqrt(sumL * sumR);
+    // No ring: this is the structured-clone fallback, already off the
+    // zero-allocation contract, and a listener may retain what it is handed. It
+    // still reads the latched scalars rather than `meterSnapshot()`, so the one
+    // object it does build is the one it posts.
     const meter: SonareWorkletMeterSnapshot = {
       type: 'meter',
       targetId: 0,
       frame: this.processedFrames,
-      peakDbL: toDb(peakL),
-      peakDbR: toDb(peakR),
-      rmsDbL: toDb(rmsL),
-      rmsDbR: toDb(rmsR),
-      correlation: denominator > 0 ? sumLR / denominator : 0,
-      truePeakDbL: toDb(peakL),
-      truePeakDbR: toDb(peakR),
+      peakDbL: this.mixer.meterScratchValue(0),
+      peakDbR: this.mixer.meterScratchValue(1),
+      rmsDbL: this.mixer.meterScratchValue(2),
+      rmsDbR: this.mixer.meterScratchValue(3),
+      correlation: this.mixer.meterScratchValue(4),
+      truePeakDbL: this.mixer.meterScratchValue(5),
+      truePeakDbR: this.mixer.meterScratchValue(6),
+      // Declared unavailable rather than floored: the mixer worklet does not run
+      // the K-weighting filters, and a floor value would read as silence.
       momentaryLufs: Number.NaN,
       shortTermLufs: Number.NaN,
       integratedLufs: Number.NaN,
       gainReductionDb: Number.NaN,
     };
-    this.transport.onMeter?.(meter);
-    if (this.meterRing) {
-      this.writeMeterRing(meter);
+    // Alternative channels for one record, not a broadcast pair: a transport
+    // that supplies both (the engine registration resolves both to
+    // `port.postMessage`) would otherwise deliver every record twice and double
+    // the host's peak-hold decay rate.
+    if (this.transport?.onMeter) {
+      this.transport.onMeter(meter);
     } else {
-      this.transport.postMessage?.(meter);
+      this.transport?.postMessage?.(meter);
     }
   }
 
@@ -277,8 +335,12 @@ export class SonareWorkletProcessor {
       frame: this.processedFrames,
       bands: new Float32Array(this.spectrumBands),
     };
-    this.transport?.onSpectrum?.(spectrum);
-    this.transport?.postMessage?.(spectrum);
+    // One record, one delivery -- see publishMeter above.
+    if (this.transport?.onSpectrum) {
+      this.transport.onSpectrum(spectrum);
+    } else {
+      this.transport?.postMessage?.(spectrum);
+    }
   }
 
   private computeSpectrum(left: Float32Array, right: Float32Array): void {

package/src/worklet/playback-processor.ts

@@ -0,0 +1,300 @@
+import { HrtfSet, PlaybackRenderer } from '../index';
+import type { PlaybackRendererConfig } from '../public_types_playback';
+import type { WasmPlaybackRenderer } from '../sonare.js';
+import { copyPlanesToOutput, type WorkletInput, type WorkletOutput } from './audio_types';
+import { isPlaybackMessage, requireIntegerOption } from './guards';
+import type {
+  SonarePlaybackDiagnosticsReplyMessage,
+  SonarePlaybackErrorMessage,
+  SonarePlaybackMessage,
+  SonarePlaybackNodeOptions,
+  SonarePlaybackWorkletProcessorOptions,
+  WorkletPort,
+} from './messages';
+
+/** Largest input channel count any layout accepts (7.1). */
+const MAX_INPUT_CHANNELS = 8;
+const SPEAKER_LAYOUT_CHANNELS: Readonly<Record<string, number>> = { stereo: 2, '5.1': 6, '7.1': 8 };
+
+function configObject(config: PlaybackRendererConfig | string | undefined): PlaybackRendererConfig {
+  if (config === undefined) {
+    return {};
+  }
+  return typeof config === 'string' ? (JSON.parse(config) as PlaybackRendererConfig) : config;
+}
+
+/** The target's channel count, known before any renderer exists (headphones: 2). */
+function outputChannelCount(config: PlaybackRendererConfig): number {
+  if (config.target?.kind !== 'speakers') {
+    return 2;
+  }
+  const count = SPEAKER_LAYOUT_CHANNELS[config.target.layout ?? ''];
+  if (count === undefined) {
+    throw new RangeError('target.layout must be "stereo", "5.1" or "7.1" for a speakers target');
+  }
+  return count;
+}
+
+/**
+ * The playback renderer inside an AudioWorklet.
+ *
+ * `inputs[0].length` is the block's input channel count, so a
+ * `MediaElementAudioSourceNode` whose channel count follows the media drives
+ * `input.layout: "auto"` directly. A block with no input channels (no active
+ * connection: paused, ended, loading) renders silence on the active layout. A
+ * block whose channel count the renderer refuses renders silence the same way
+ * and counts toward `unsupported_input_blocks`; either way the renderer
+ * advances by the block, so the timeline never shifts. Nothing throws on the
+ * audio thread.
+ *
+ * Every buffer is allocated in the constructor: `process()` copies into WASM
+ * heap planes and allocates nothing.
+ */
+export class SonarePlaybackWorkletProcessor {
+  private static warnedBlockOverflow = false;
+  private readonly renderer: PlaybackRenderer;
+  private readonly native: WasmPlaybackRenderer;
+  private readonly port?: WorkletPort;
+  private readonly maxBlockSize: number;
+  private readonly outputChannels: number;
+  private inputPlanes: Float32Array[] = [];
+  private outputPlanes: Float32Array[] = [];
+  private unsupportedInputBlocks = 0;
+  private destroyed = false;
+
+  constructor(options: SonarePlaybackWorkletProcessorOptions = {}, port?: WorkletPort) {
+    this.port = port;
+    this.maxBlockSize = requireIntegerOption(options.maxBlockSize, 128, 'maxBlockSize', 1);
+    const scopeRate = (globalThis as { sampleRate?: unknown }).sampleRate;
+    const sampleRate = options.sampleRate ?? (typeof scopeRate === 'number' ? scopeRate : 48000);
+    const hrtf = options.hrtf ? HrtfSet.fromBytes(new Uint8Array(options.hrtf)) : undefined;
+    try {
+      this.renderer = new PlaybackRenderer({
+        config: options.config ?? {},
+        hrtf,
+        sampleRate,
+        maxBlockSize: this.maxBlockSize,
+      });
+    } finally {
+      // The renderer keeps its own copy of the set.
+      hrtf?.delete();
+    }
+    // One reviewed read of the facade's private handle, for the heap-plane path.
+    this.native = (this.renderer as unknown as { native: WasmPlaybackRenderer }).native;
+    this.outputChannels = this.native.outputChannels();
+    this.acquirePlanes();
+  }
+
+  /**
+   * Handles a control-plane message. AudioWorklet port handlers run on the
+   * rendering thread between `process()` calls, which is what makes `reset`
+   * safe here. A refused message is answered with an `error` message.
+   */
+  receiveMessage(message: SonarePlaybackMessage): void {
+    if (this.destroyed) {
+      return;
+    }
+    try {
+      switch (message.type) {
+        case 'config':
+          this.renderer.setConfig(message.config);
+          break;
+        case 'orientation':
+          this.renderer.setHeadOrientation(message.yaw, message.pitch ?? 0, message.roll ?? 0);
+          break;
+        case 'reset':
+          this.renderer.reset();
+          break;
+        case 'diagnostics':
+          this.port?.postMessage?.({
+            type: 'diagnostics',
+            diagnostics: this.diagnostics(),
+          } satisfies SonarePlaybackDiagnosticsReplyMessage);
+          break;
+        case 'destroy':
+          this.destroy();
+          break;
+      }
+    } catch (error) {
+      this.port?.postMessage?.({
+        type: 'error',
+        request: message.type,
+        message: error instanceof Error ? error.message : String(error),
+      } satisfies SonarePlaybackErrorMessage);
+    }
+  }
+
+  /** The renderer's diagnostics plus `unsupported_input_blocks`, as a plain object. */
+  diagnostics(): SonarePlaybackDiagnosticsReplyMessage['diagnostics'] {
+    return {
+      ...this.renderer.diagnostics(),
+      unsupported_input_blocks: this.unsupportedInputBlocks,
+    };
+  }
+
+  process(inputs: WorkletInput, outputs: WorkletOutput): boolean {
+    if (this.destroyed) {
+      return false;
+    }
+    const output = outputs[0];
+    const requested = output?.[0]?.length ?? 0;
+    if (!output || requested === 0) {
+      return true;
+    }
+    const frames = this.clampFrames(requested);
+    // Heap views detach when WASM linear memory grows; the storage behind them
+    // never moves, so re-acquiring is allocation-free on the native side.
+    if (this.inputPlanes[0]?.byteLength === 0 || this.outputPlanes[0]?.byteLength === 0) {
+      this.acquirePlanes();
+    }
+
+    const input = inputs[0];
+    const inChannels = input?.length ?? 0;
+    let code: number;
+    if (inChannels === 0) {
+      code = this.native.processPreparedSilence(frames);
+    } else if (inChannels > MAX_INPUT_CHANNELS) {
+      this.unsupportedInputBlocks++;
+      code = this.native.processPreparedSilence(frames);
+    } else {
+      for (let ch = 0; ch < inChannels; ch++) {
+        const source = input[ch];
+        const plane = this.inputPlanes[ch];
+        const copied = Math.min(frames, source.length);
+        plane.set(copied === source.length ? source : source.subarray(0, copied));
+        if (copied < frames) {
+          plane.fill(0, copied, frames);
+        }
+      }
+      code = this.native.processPrepared(inChannels, frames);
+      if (code !== 0) {
+        // A refused block leaves the renderer untouched; render silence instead.
+        this.unsupportedInputBlocks++;
+        code = this.native.processPreparedSilence(frames);
+      }
+    }
+    if (code === 0) {
+      copyPlanesToOutput(output, this.outputPlanes, frames);
+    } else {
+      for (const channel of output) {
+        channel.fill(0);
+      }
+    }
+    return true;
+  }
+
+  destroy(): void {
+    if (this.destroyed) {
+      return;
+    }
+    this.destroyed = true;
+    this.renderer.delete();
+  }
+
+  private acquirePlanes(): void {
+    this.inputPlanes = [];
+    for (let ch = 0; ch < MAX_INPUT_CHANNELS; ch++) {
+      this.inputPlanes.push(this.native.inputPlane(ch));
+    }
+    this.outputPlanes = [];
+    for (let ch = 0; ch < this.outputChannels; ch++) {
+      this.outputPlanes.push(this.native.outputPlane(ch));
+    }
+  }
+
+  // Frames past the construction-time capacity are left silent rather than
+  // reallocating on the audio thread.
+  private clampFrames(frames: number): number {
+    if (frames <= this.maxBlockSize) {
+      return frames;
+    }
+    if (!SonarePlaybackWorkletProcessor.warnedBlockOverflow) {
+      SonarePlaybackWorkletProcessor.warnedBlockOverflow = true;
+      // biome-ignore lint/suspicious/noConsole: realtime-safety diagnostic.
+      console.warn(
+        `SonarePlaybackWorkletProcessor: requested ${frames} frames exceeds maxBlockSize ` +
+          `${this.maxBlockSize}; clamping.`,
+      );
+    }
+    return this.maxBlockSize;
+  }
+}
+
+export function registerSonarePlaybackWorkletProcessor(name = 'sonare-playback-processor'): void {
+  const scope = globalThis as unknown as {
+    AudioWorkletProcessor?: new () => object;
+    registerProcessor?: (processorName: string, processorCtor: unknown) => void;
+  };
+  if (!scope.AudioWorkletProcessor || !scope.registerProcessor) {
+    throw new Error('AudioWorkletProcessor is not available in this context.');
+  }
+  const Base = scope.AudioWorkletProcessor;
+  class RegisteredSonarePlaybackWorkletProcessor extends Base {
+    private bridge: SonarePlaybackWorkletProcessor;
+    readonly port?: WorkletPort;
+
+    constructor(options?: { processorOptions?: SonarePlaybackWorkletProcessorOptions }) {
+      super();
+      const port = this.port;
+      this.bridge = new SonarePlaybackWorkletProcessor(options?.processorOptions ?? {}, port);
+      const onMessage = (event: { data: unknown }) => {
+        if (isPlaybackMessage(event.data)) {
+          this.bridge.receiveMessage(event.data);
+        }
+      };
+      if (port?.addEventListener) {
+        port.addEventListener('message', onMessage);
+        port.start?.();
+      } else if (port) {
+        port.onmessage = onMessage;
+      }
+    }
+
+    process(inputs: WorkletInput, outputs: WorkletOutput): boolean {
+      return this.bridge.process(inputs, outputs);
+    }
+  }
+  scope.registerProcessor(name, RegisteredSonarePlaybackWorkletProcessor);
+}
+
+/**
+ * Creates the AudioWorkletNode for a processor registered with
+ * {@link registerSonarePlaybackWorkletProcessor}. The node's input follows its
+ * source's channel count without any browser up/down mix
+ * (`channelCountMode: "max"`, `channelInterpretation: "discrete"`), and its
+ * output carries the target's channel count. The configuration is serialized
+ * here, on the main thread.
+ *
+ * @example
+ * ```ts
+ * await context.audioWorklet.addModule(playbackWorkletUrl);
+ * const hrtf = await (await fetch(hrtfUrl)).arrayBuffer();
+ * const node = createSonarePlaybackNode(context, { config: {}, hrtf });
+ * context.createMediaElementSource(video).connect(node).connect(context.destination);
+ * video.addEventListener('seeking', () => node.port.postMessage({ type: 'reset' }));
+ * ```
+ */
+export function createSonarePlaybackNode(
+  context: BaseAudioContext,
+  options: SonarePlaybackNodeOptions = {},
+): AudioWorkletNode {
+  const config = configObject(options.config);
+  const factory =
+    options.nodeFactory ??
+    ((ctx: BaseAudioContext, name: string, nodeOptions: AudioWorkletNodeOptions) =>
+      new AudioWorkletNode(ctx, name, nodeOptions));
+  const processorOptions: SonarePlaybackWorkletProcessorOptions = {
+    config: JSON.stringify(config),
+    hrtf: options.hrtf,
+    maxBlockSize: options.maxBlockSize,
+    sampleRate: options.sampleRate ?? context.sampleRate,
+  };
+  return factory(context, options.processorName ?? 'sonare-playback-processor', {
+    numberOfInputs: 1,
+    numberOfOutputs: 1,
+    outputChannelCount: [outputChannelCount(config)],
+    channelCountMode: 'max',
+    channelInterpretation: 'discrete',
+    processorOptions,
+  });
+}

package/src/worklet/protocol.ts

@@ -25,7 +25,17 @@ export interface SonareWorkletMeterSnapshot {
   rmsDbL: number;
   rmsDbR: number;
   correlation: number;
+  /**
+   * Left-channel inter-sample (true) peak in dB, from the ITU-R BS.1770-4
+   * polyphase reconstruction at 4x. A streaming measurement, and the render
+   * quantum makes that visible here: the centered reconstruction stencil needs a
+   * few future samples a realtime path does not have, so each block's last
+   * samples read marginally low (about 0.1 dB across 64..8192-sample blocks on a
+   * near-Nyquist tone, always under-reading). Use `meteringTruePeakDb` over the
+   * whole signal for an exact dBTP number.
+   */
   truePeakDbL: number;
+  /** Right-channel inter-sample (true) peak in dB. See {@link truePeakDbL}. */
   truePeakDbR: number;
   momentaryLufs: number;
   shortTermLufs: number;
@@ -140,6 +150,7 @@ export enum SonareEngineTelemetryError {
   MetronomeOverflow = 18,
   InvalidCommand = 19,
   MaxChannelsExceeded = 20,
+  ParameterBaseOverflow = 21,
 }
 
 export interface SonareMeterRingBuffer {
@@ -307,8 +318,24 @@ export interface SharedSpectrumRingWriter {
   recordFloats: number;
 }
 
+/**
+ * Shared finite dB floor (`sonare::constants::kFloorDb`). Every level-in-dB
+ * field on a worklet snapshot bottoms out here rather than at `-Infinity`.
+ */
+export const SONARE_FLOOR_DB = -120;
+
+/**
+ * Magnitude to dB with the shared finite floor.
+ *
+ * `-Infinity` is not a usable value for a meter reading: it propagates NaN
+ * through the usual `(db + 60) / 60 * height` bar geometry, serializes to
+ * `null` through `JSON.stringify`, and poisons `Math.min`/`Math.max`
+ * aggregation. The native meters have always floored at `kFloorDb`, so a
+ * producer emitting `-Infinity` also made the two worklets disagree about
+ * silence.
+ */
 export function toDb(value: number): number {
-  return value > 0 ? 20 * Math.log10(value) : Number.NEGATIVE_INFINITY;
+  return value > 0 ? Math.max(20 * Math.log10(value), SONARE_FLOOR_DB) : SONARE_FLOOR_DB;
 }
 
 export function isRecord(value: unknown): value is Record<string, unknown> {
@@ -948,6 +975,27 @@ function recordOffset(index: number, capacity: number, recordBytes: number): num
   return (index % capacity) * recordBytes;
 }
 
+/**
+ * The domain of a uint32 record slot: no fraction, no sign, no overflow.
+ *
+ * `setUint32` folds anything outside it into a legal value, so a negative id
+ * becomes a large one and 2**32 becomes 0. An absent value is out of domain;
+ * a slot with a default resolves it before asking.
+ */
+export function isUint32Slot(value: number | undefined): boolean {
+  return (
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 0xffff_ffff
+  );
+}
+
+function toUint32Slot(value: number | undefined, fallback: number, name: string): number {
+  const resolved = value ?? fallback;
+  if (!isUint32Slot(resolved)) {
+    throw new RangeError(`${name} must be an integer within [0, 4294967295]`);
+  }
+  return resolved;
+}
+
 function toSafeInteger(value: number | bigint | undefined, fallback: number): number {
   const resolved = typeof value === 'bigint' ? Number(value) : value;
   if (resolved === undefined) {
@@ -976,8 +1024,10 @@ function writeEngineCommandRecord(
   offset: number,
   command: SonareEngineCommandRecord,
 ): void {
-  view.setUint32(offset, command.type, true);
-  view.setUint32(offset + 4, command.targetId ?? 0, true);
+  // Both slots are uint32 and the readers are unsigned, so the writer holds
+  // them to that domain; the command vocabulary itself is the node's check.
+  view.setUint32(offset, toUint32Slot(command.type, 0, 'type'), true);
+  view.setUint32(offset + 4, toUint32Slot(command.targetId, 0, 'targetId'), true);
   writeInt64Words(view, offset + 8, toSafeInteger(command.sampleTime, -1));
   // argFloat occupies a full 8-byte Float64 slot (replacing the old Float32 +
   // 4-byte pad) so PPQ scalars carried here keep full double precision over the