@kuralle-syrinx/core 2.1.0

package/src/pipeline-bus.test.ts

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect, vi } from "vitest";
+import { PipelineBusImpl, Route, type PipelineBusConfig } from "../src/pipeline-bus.js";
+import type { VoicePacket } from "../src/packets.js";
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function pkt(kind: string, contextId = "ctx-1"): VoicePacket {
+  return { kind, contextId, timestampMs: Date.now() };
+}
+
+function createBus(config?: PipelineBusConfig): PipelineBusImpl {
+  return new PipelineBusImpl(config);
+}
+
+/** Start bus, run fn, stop bus, await drain completion. */
+async function withBus(
+  config: PipelineBusConfig | undefined,
+  fn: (bus: PipelineBusImpl) => void | Promise<void>,
+): Promise<void> {
+  const bus = createBus(config);
+  const startP = bus.start();
+  // Give the start loop a tick to begin
+  await new Promise((r) => setTimeout(r, 5));
+  await fn(bus);
+  // Allow pending dispatches to complete
+  await new Promise((r) => setTimeout(r, 20));
+  bus.stop();
+  await startP;
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("PipelineBusImpl", () => {
+  describe("push and drain order", () => {
+    it("drains Critical before Main", async () => {
+      const processed: string[] = [];
+      await withBus(undefined, (bus) => {
+        bus.on("critical.event", () => { processed.push("critical"); });
+        bus.on("main.event", () => { processed.push("main"); });
+        bus.push(Route.Main, pkt("main.event"));
+        bus.push(Route.Critical, pkt("critical.event"));
+      });
+      expect(processed).toEqual(["critical", "main"]);
+    });
+
+    it("drains Main before Background", async () => {
+      const processed: string[] = [];
+      await withBus(undefined, (bus) => {
+        bus.on("main.event", () => { processed.push("main"); });
+        bus.on("bg.event", () => { processed.push("bg"); });
+        bus.push(Route.Background, pkt("bg.event"));
+        bus.push(Route.Main, pkt("main.event"));
+      });
+      expect(processed).toEqual(["main", "bg"]);
+    });
+
+    it("batches Critical up to criticalBatchSize before yielding", async () => {
+      const processed: string[] = [];
+      await withBus({ criticalBatchSize: 3 }, (bus) => {
+        bus.on("critical.event", () => { processed.push("c"); });
+        for (let i = 0; i < 5; i++) {
+          bus.push(Route.Critical, pkt("critical.event"));
+        }
+      });
+      expect(processed.length).toBeGreaterThanOrEqual(5);
+    });
+  });
+
+  describe("capacity and overflow", () => {
+    it("drops oldest Background on overflow", async () => {
+      const dropped: VoicePacket[] = [];
+      const metrics: string[] = [];
+      await withBus(
+        { bgCapacity: 2, onBackgroundDrop: (d: VoicePacket) => { dropped.push(d); } },
+        (bus) => {
+          bus.on("metric.conversation", (pkt: any) => {
+            metrics.push(pkt.name);
+          });
+          bus.push(Route.Background, pkt("bg.1", "id-1"));
+          bus.push(Route.Background, pkt("bg.2", "id-2"));
+          bus.push(Route.Background, pkt("bg.3", "id-3"));
+        },
+      );
+      expect(dropped.length).toBeGreaterThanOrEqual(1);
+      if (dropped.length > 0) {
+        expect(dropped[0]!.contextId).toBe("id-1");
+      }
+      expect(metrics).toContain("pipeline.bus.background.dropped");
+    });
+
+    it("throws on Main overflow", () => {
+      const bus = createBus({ mainCapacity: 1 });
+      bus.push(Route.Main, pkt("main.1"));
+      expect(() => bus.push(Route.Main, pkt("main.2"))).toThrow("Main queue full");
+    });
+
+    it("Critical never overflows", () => {
+      const bus = createBus();
+      for (let i = 0; i < 10000; i++) {
+        bus.push(Route.Critical, pkt("critical.event"));
+      }
+      expect(true).toBe(true);
+    });
+  });
+
+  describe("handler registration", () => {
+    it("calls matching handler for packet kind", async () => {
+      const fn = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", fn);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not call handler for different kind", async () => {
+      const fn = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", fn);
+        bus.push(Route.Main, pkt("other.event"));
+      });
+      expect(fn).not.toHaveBeenCalled();
+    });
+
+    it("unsubscribe removes handler", async () => {
+      const fn = vi.fn();
+      await withBus(undefined, (bus) => {
+        const unsub = bus.on("test.event", fn);
+        unsub();
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn).not.toHaveBeenCalled();
+    });
+
+    it("multiple handlers for same kind all fire", async () => {
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", fn1);
+        bus.on("test.event", fn2);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn1).toHaveBeenCalledTimes(1);
+      expect(fn2).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("allPackets", () => {
+    it("publishes every pushed packet with its route", async () => {
+      const bus = createBus();
+      const reader = bus.allPackets.getReader();
+      bus.push(Route.Main, pkt("main.event", "main-1"));
+      bus.push(Route.Critical, pkt("critical.event", "critical-1"));
+
+      const first = await reader.read();
+      const second = await reader.read();
+      reader.releaseLock();
+
+      expect(first.value).toMatchObject({
+        route: Route.Main,
+        packet: { kind: "main.event", contextId: "main-1" },
+      });
+      expect(second.value).toMatchObject({
+        route: Route.Critical,
+        packet: { kind: "critical.event", contextId: "critical-1" },
+      });
+    });
+  });
+
+  describe("error handling", () => {
+    it("handler error pushes VoiceErrorPacket to Critical", async () => {
+      const errorHandler = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", () => { throw new Error("boom"); });
+        bus.on("pipeline.error", errorHandler);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(errorHandler).toHaveBeenCalled();
+    });
+
+    it("handler error does not stop other handlers", async () => {
+      const fn2 = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", () => { throw new Error("boom"); });
+        bus.on("test.event", fn2);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn2).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/pipeline-bus.ts

@@ -0,0 +1,369 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Priority Pipeline Bus
+//
+// Three priority channels (Critical, Main, Background) with strict drain order.
+// All pipeline components push packets into the bus. The bus dispatches to
+// registered handlers. Handlers are registered by packet kind (discriminated string).
+//
+// Design decisions (per RFC Q1 resolution):
+//   - Uses setTimeout(fn, 0) for the drain loop to yield to I/O between iterations.
+//   - Critical channel batches up to 4 packets per tick before yielding.
+//   - Main queue is bounded at 4096 packets; throws on overflow.
+//   - Background queue is bounded at 2048 packets; drops oldest on overflow.
+//   - Pipeline handler errors emit VoiceErrorPacket on Critical route — bus continues.
+
+import type { VoicePacket, AsyncPacket, VoiceErrorPacket } from "./packets.js";
+import { ErrorCategory, type ConversationMetricPacket, type PipelineErrorPacket } from "./packets.js";
+
+// =============================================================================
+// Public Types
+// =============================================================================
+
+export enum Route {
+  Critical = 0,   // interrupts, turn changes — drained first, never bounded
+  Main = 1,       // pipeline flow: audio in, STT results, LLM deltas, TTS audio
+  Background = 2, // metrics, debug events, DB writes — drained last, droppable
+}
+
+export type PacketHandler<T extends VoicePacket = VoicePacket> = (
+  pkt: T,
+) => void | Promise<void>;
+
+export interface PipelineBus {
+  /** Push one or more packets into a priority route. */
+  push<T extends readonly VoicePacket[]>(route: Route, ...packets: T): void;
+
+  /**
+   * Register a handler for a specific packet kind. Returns unsubscribe function.
+   *
+   * By default handlers are awaited in registration order (consumer semantics — the
+   * handler's state mutations are visible to the next packet's handlers). Pass
+   * `{ concurrent: true }` for a long-running PRODUCER handler (e.g. an LLM-generation
+   * loop that emits its own packets over time): it is dispatched fire-and-forget so it
+   * does not park the drain loop and defer subsequent Main packets / Critical interrupts
+   * behind it. Concurrent handler errors are surfaced as `pipeline.error`, like async packets.
+   */
+  on<T extends VoicePacket>(
+    kind: T["kind"],
+    handler: PacketHandler<T>,
+    opts?: { concurrent?: boolean },
+  ): () => void;
+
+  /** Start draining the bus. Resolves when stop() is called and final drain completes. */
+  start(): Promise<void>;
+
+  /** Stop draining. Flushes Critical+Main, discards Background. */
+  stop(): void;
+
+  /** Readonly stream of every packet pushed into the bus, before route dispatch. */
+  readonly allPackets: ReadableStream<{ route: Route; packet: VoicePacket }>;
+}
+
+// =============================================================================
+// Internal
+// =============================================================================
+
+interface QueueEntry {
+  route: Route;
+  packet: VoicePacket;
+}
+
+/**
+ * Configuration for PipelineBusImpl.
+ * Critical is always unbounded. Main and Background can be configured.
+ */
+export interface PipelineBusConfig {
+  /** Maximum Main queue size. Default 4096. Throws on overflow. */
+  mainCapacity?: number;
+  /** Maximum Background queue size. Default 2048. Drops oldest on overflow. */
+  bgCapacity?: number;
+  /** Maximum Critical packets to batch per tick before yielding to I/O. Default 4. */
+  criticalBatchSize?: number;
+  /** Called when a Background packet is dropped. For metrics emission. */
+  onBackgroundDrop?: (dropped: VoicePacket) => void;
+  /** Called for every packet pushed into the bus. */
+  onPacket?: (route: Route, packet: VoicePacket) => void;
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+export class PipelineBusImpl implements PipelineBus {
+  private critical: VoicePacket[] = [];
+  private main: VoicePacket[] = [];
+  private background: VoicePacket[] = [];
+  private handlers = new Map<string, Set<PacketHandler>>();
+  private concurrentHandlers = new Set<PacketHandler>();
+  private running = false;
+  private resolver: (() => void) | null = null;
+  private drainedCount = 0;
+  private allPacketsController:
+    | ReadableStreamDefaultController<{ route: Route; packet: VoicePacket }>
+    | null = null;
+
+  readonly allPackets: ReadableStream<{ route: Route; packet: VoicePacket }>;
+
+  private readonly mainCapacity: number;
+  private readonly bgCapacity: number;
+  private readonly criticalBatchSize: number;
+  private readonly onBgDrop: ((dropped: VoicePacket) => void) | undefined;
+  private readonly onPacket: ((route: Route, packet: VoicePacket) => void) | undefined;
+
+  constructor(config?: PipelineBusConfig) {
+    this.mainCapacity = config?.mainCapacity ?? 4096;
+    this.bgCapacity = config?.bgCapacity ?? 2048;
+    this.criticalBatchSize = config?.criticalBatchSize ?? 4;
+    this.onBgDrop = config?.onBackgroundDrop;
+    this.onPacket = config?.onPacket;
+    this.allPackets = new ReadableStream<{ route: Route; packet: VoicePacket }>({
+      start: (controller) => {
+        this.allPacketsController = controller;
+      },
+      cancel: () => {
+        this.allPacketsController = null;
+      },
+    });
+
+    if (this.mainCapacity < 1) throw new Error("mainCapacity must be >= 1");
+    if (this.bgCapacity < 1) throw new Error("bgCapacity must be >= 1");
+    if (this.criticalBatchSize < 1) throw new Error("criticalBatchSize must be >= 1");
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  push<T extends readonly VoicePacket[]>(route: Route, ...packets: T): void {
+    for (const p of packets) {
+      this.publishAllPackets(route, p);
+      const q = this.queueFor(route);
+      let droppedForMetric: VoicePacket | null = null;
+      if (q.length >= this.capacityFor(route)) {
+        if (route === Route.Background) {
+          const dropped = q.shift();
+          if (dropped && this.onBgDrop) {
+            this.onBgDrop(dropped);
+          }
+          if (dropped) {
+            droppedForMetric = dropped;
+          }
+          // continue — push after dropping oldest
+        } else if (route === Route.Main) {
+          throw new Error(
+            `PipelineBus: Main queue full (${this.mainCapacity}). ` +
+              `Backpressure required — slow down producers or increase capacity.`,
+          );
+        }
+        // Critical is never bounded
+      }
+      q.push(p);
+      if (droppedForMetric) {
+        this.enqueueBackgroundDropMetric(droppedForMetric);
+      }
+    }
+    // Wake the drain loop
+    this.resolver?.();
+    this.resolver = null;
+  }
+
+  on<T extends VoicePacket>(
+    kind: T["kind"],
+    handler: PacketHandler<T>,
+    opts?: { concurrent?: boolean },
+  ): () => void {
+    let set = this.handlers.get(kind);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(kind, set);
+    }
+    const h = handler as PacketHandler;
+    set.add(h);
+    if (opts?.concurrent) this.concurrentHandlers.add(h);
+    return () => {
+      set!.delete(h);
+      this.concurrentHandlers.delete(h);
+      if (set!.size === 0) {
+        this.handlers.delete(kind);
+      }
+    };
+  }
+
+  async start(): Promise<void> {
+    this.running = true;
+    while (this.running) {
+      const batch = this.dequeueBatch();
+      if (batch.length === 0) {
+        // Yield to I/O — wait for next push()
+        await new Promise<void>((resolve) => {
+          this.resolver = resolve;
+        });
+        continue;
+      }
+
+      for (const entry of batch) {
+        await this.dispatch(entry.packet);
+        this.drainedCount++;
+      }
+    }
+  }
+
+  stop(): void {
+    this.running = false;
+    // Drain remaining Critical then Main (synchronous — stop is a shutdown path)
+    while (this.critical.length > 0) {
+      const pkt = this.critical.shift()!;
+      void this.dispatchSync(pkt);
+    }
+    while (this.main.length > 0) {
+      const pkt = this.main.shift()!;
+      void this.dispatchSync(pkt);
+    }
+    // Discard Background
+    this.background.length = 0;
+    this.resolver?.();
+    this.resolver = null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+
+  private queueFor(r: Route): VoicePacket[] {
+    if (r === Route.Critical) return this.critical;
+    if (r === Route.Main) return this.main;
+    return this.background;
+  }
+
+  private publishAllPackets(route: Route, packet: VoicePacket): void {
+    this.onPacket?.(route, packet);
+    if (!this.allPacketsController) return;
+    try {
+      this.allPacketsController.enqueue({ route, packet });
+    } catch {
+      this.allPacketsController = null;
+    }
+  }
+
+  private enqueueBackgroundDropMetric(dropped: VoicePacket): void {
+    const metric: ConversationMetricPacket = {
+      kind: "metric.conversation",
+      contextId: dropped.contextId,
+      timestampMs: Date.now(),
+      name: "pipeline.bus.background.dropped",
+      value: dropped.kind,
+    };
+
+    this.publishAllPackets(Route.Background, metric);
+    if (this.background.length >= this.bgCapacity) {
+      this.background.shift();
+    }
+    this.background.push(metric);
+  }
+
+  private capacityFor(r: Route): number {
+    if (r === Route.Critical) return Infinity;
+    if (r === Route.Main) return this.mainCapacity;
+    return this.bgCapacity;
+  }
+
+  /**
+   * Dequeue a batch of packets. Always drains Critical first.
+   * Critical batches up to `criticalBatchSize` per tick before yielding to I/O.
+   * Main and Background drain one packet per tick.
+   */
+  private dequeueBatch(): QueueEntry[] {
+    // 1. Critical — batch up to N
+    if (this.critical.length > 0) {
+      const batch: QueueEntry[] = [];
+      const count = Math.min(this.critical.length, this.criticalBatchSize);
+      for (let i = 0; i < count; i++) {
+        batch.push({
+          route: Route.Critical,
+          packet: this.critical.shift()!,
+        });
+      }
+      return batch;
+    }
+
+    // 2. Main — one packet per tick
+    if (this.main.length > 0) {
+      return [{ route: Route.Main, packet: this.main.shift()! }];
+    }
+
+    // 3. Background — one packet per tick
+    if (this.background.length > 0) {
+      return [{ route: Route.Background, packet: this.background.shift()! }];
+    }
+
+    return [];
+  }
+
+  /** Dispatch one packet to registered handlers. */
+  private async dispatch(pkt: VoicePacket): Promise<void> {
+    const matches = this.handlers.get(pkt.kind);
+    if (!matches || matches.size === 0) return;
+
+    // Async packets: fire-and-forget, don't await
+    if ("isAsync" in pkt && (pkt as unknown as AsyncPacket).isAsync) {
+      for (const h of matches) {
+        void (async () => {
+          try {
+            await (h as PacketHandler)(pkt);
+          } catch {
+            // Fire-and-forget errors are intentionally swallowed.
+            // AsyncPackets are for non-critical telemetry/events.
+          }
+        })();
+      }
+      return;
+    }
+
+    // Sync packets: await each consumer handler in registration order. Concurrent
+    // (producer) handlers are fired fire-and-forget so a long-running handler does
+    // not park the drain loop and defer subsequent Main/Critical packets behind it.
+    for (const h of matches) {
+      const handler = h as PacketHandler;
+      if (this.concurrentHandlers.has(handler)) {
+        void (async () => {
+          try {
+            await handler(pkt);
+          } catch (err) {
+            this.emitHandlerError(pkt, err);
+          }
+        })();
+        continue;
+      }
+      try {
+        await handler(pkt);
+      } catch (err) {
+        // Handler error → emit PipelineErrorPacket on Critical.
+        // Continue processing other handlers — don't abort the bus.
+        this.emitHandlerError(pkt, err);
+      }
+    }
+  }
+
+  private emitHandlerError(pkt: VoicePacket, err: unknown): void {
+    const errorPkt: PipelineErrorPacket = {
+      kind: "pipeline.error",
+      contextId: pkt.contextId,
+      timestampMs: Date.now(),
+      component: "pipeline",
+      category: ErrorCategory.InternalFault,
+      cause: err instanceof Error ? err : new Error(String(err)),
+      isRecoverable: true,
+    };
+    this.push(Route.Critical, errorPkt);
+  }
+
+  /** Synchronous dispatch for drain-on-stop. Swallows errors. */
+  private async dispatchSync(pkt: VoicePacket): Promise<void> {
+    try {
+      await this.dispatch(pkt);
+    } catch {
+      // Drain phase — silence errors
+    }
+  }
+}

package/src/plugin-contract.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Plugin Contract
+//
+// Every pipeline plugin (STT, TTS, VAD, EOS, Denoiser, Bridge) implements
+// this interface. Plugins receive the PipelineBus on initialization and
+// push all output (transcripts, audio, errors, events) into the bus.
+//
+// Breaking change from v0.1: plugins now accept PipelineBus directly.
+// No callbacks, no adapters. Clean contract, one code path.
+
+import type { PipelineBus } from "./pipeline-bus.js";
+
+// =============================================================================
+// Contract
+// =============================================================================
+
+export type EndpointingOwner = "provider_stt" | "smart_turn";
+
+export interface EndpointingCapability {
+  readonly owner: EndpointingOwner;
+  readonly disableConfig?: PluginConfig;
+}
+
+export interface VoicePlugin {
+  readonly endpointingCapability?: EndpointingCapability;
+
+  /**
+   * Initialize the plugin. Called during the init chain.
+   * Connect to provider, start streams, register bus handlers if needed.
+   *
+   * @param bus — The session's PipelineBus. Push all output packets here.
+   * @param config — Plugin-specific configuration (API keys, model IDs, etc.).
+   */
+  initialize(bus: PipelineBus, config: PluginConfig): Promise<void>;
+
+  /**
+   * Tear down the plugin. Called during the finalize chain (reverse order).
+   * Close connections, flush buffers, release resources.
+   */
+  close(): Promise<void>;
+}
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+/**
+ * Plugin configuration — a flat key-value bag.
+ * Plugins extract the keys they need (e.g., "api_key", "model_id", "voice_id").
+ */
+export type PluginConfig = Record<string, unknown>;
+
+/**
+ * Convenience: extract a string config value, throwing if missing.
+ */
+export function requireStringConfig(
+  config: PluginConfig,
+  key: string,
+): string {
+  const value = config[key];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Plugin config missing required key: ${key}`);
+  }
+  return value;
+}
+
+/**
+ * Convenience: extract an optional string config value.
+ */
+export function optionalStringConfig(
+  config: PluginConfig,
+  key: string,
+): string | undefined {
+  const value = config[key];
+  return typeof value === "string" && value.trim().length > 0
+    ? value
+    : undefined;
+}

package/src/primary-speaker-fixtures.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+//
+// Synthetic PCM fixtures for primary-speaker gate tests.
+
+import { pcm16BytesToSamples, pcm16SamplesToBytes } from "./audio/pcm.js";
+
+export function synthesizeTonePcm16(options: {
+  frequencyHz: number;
+  durationMs: number;
+  sampleRateHz?: number;
+  amplitude?: number;
+  phaseRad?: number;
+}): Uint8Array {
+  const sampleRateHz = options.sampleRateHz ?? 16000;
+  const amplitude = options.amplitude ?? 0.35;
+  const phaseRad = options.phaseRad ?? 0;
+  const sampleCount = Math.max(1, Math.round((options.durationMs * sampleRateHz) / 1000));
+  const samples = new Int16Array(sampleCount);
+  const omega = (2 * Math.PI * options.frequencyHz) / sampleRateHz;
+  for (let i = 0; i < sampleCount; i += 1) {
+    const value = Math.sin(omega * i + phaseRad) * amplitude * 32767;
+    samples[i] = Math.max(-32768, Math.min(32767, Math.round(value)));
+  }
+  return pcm16SamplesToBytes(samples);
+}
+
+export function mixPcm16(chunks: Uint8Array[], weights: number[]): Uint8Array {
+  if (chunks.length === 0) return new Uint8Array(0);
+  const maxLen = Math.max(...chunks.map((c) => c.byteLength));
+  const out = new Int16Array(maxLen / 2);
+  for (let c = 0; c < chunks.length; c += 1) {
+    const chunk = chunks[c]!;
+    const weight = weights[c] ?? 1;
+    const samples = pcm16BytesToSamples(chunk);
+    for (let i = 0; i < samples.length; i += 1) {
+      const mixed = (out[i] ?? 0) + samples[i]! * weight;
+      out[i] = Math.max(-32768, Math.min(32767, Math.round(mixed)));
+    }
+  }
+  return pcm16SamplesToBytes(out);
+}
+
+export const PRIMARY_SPEAKER_TONE_HZ = 280;
+export const BYSTANDER_SPEAKER_TONE_HZ = 2100;
+export const ASSISTANT_ECHO_TONE_HZ = 520;