@kuralle-syrinx/core 4.0.0 → 4.2.0

package/src/iu-ledger.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Incremental-Unit ledger (IU substrate, RFC incremental-unit-substrate)
+
+import type { IncrementalUnit, IncrementalUnitId, IuState } from "./incremental-unit.js";
+
+export interface IuLedger {
+  add(iu: IncrementalUnit): void;
+  commit(id: IncrementalUnitId, prefix?: { chars?: number; ms?: number }): void;
+  revoke(id: IncrementalUnitId): void;
+  get(id: IncrementalUnitId): IncrementalUnit | undefined;
+  latest(contextId: string, kind: IncrementalUnit["kind"]): IncrementalUnit | undefined;
+  clear(contextId: string): void;
+}
+
+export type IuLedgerAnomaly =
+  | { readonly kind: "terminal_op"; readonly op: "commit" | "revoke"; readonly id: IncrementalUnitId; readonly state: IuState }
+  | { readonly kind: "unknown_iu"; readonly op: "commit" | "revoke"; readonly id: IncrementalUnitId };
+
+export class InMemoryIuLedger implements IuLedger {
+  private readonly byCtx = new Map<string, Map<string, IncrementalUnit>>();
+
+  constructor(
+    private readonly onEvent: (a: IuLedgerAnomaly) => void = () => {},
+    private readonly maxContexts: number = 256,
+  ) {}
+
+  add(iu: IncrementalUnit): void {
+    const ctx = iu.id.contextId;
+    if (!this.byCtx.has(ctx) && this.byCtx.size >= this.maxContexts) {
+      const oldest = this.byCtx.keys().next().value;
+      if (oldest !== undefined) this.byCtx.delete(oldest);
+    }
+    this.ctxMap(ctx).set(iu.id.iuId, iu);
+  }
+
+  commit(id: IncrementalUnitId, prefix?: { chars?: number; ms?: number }): void {
+    const ctxMap = this.byCtx.get(id.contextId);
+    if (!ctxMap) {
+      this.onEvent({ kind: "unknown_iu", op: "commit", id });
+      return;
+    }
+    const iu = ctxMap.get(id.iuId);
+    if (!iu) {
+      this.onEvent({ kind: "unknown_iu", op: "commit", id });
+      return;
+    }
+    if (iu.state !== "hypothesized") {
+      this.onEvent({ kind: "terminal_op", op: "commit", id, state: iu.state });
+      return;
+    }
+    iu.state = "committed";
+    if (prefix) {
+      iu.committedPrefix = prefix;
+    }
+  }
+
+  revoke(id: IncrementalUnitId): void {
+    const ctxMap = this.byCtx.get(id.contextId);
+    if (!ctxMap) {
+      this.onEvent({ kind: "unknown_iu", op: "revoke", id });
+      return;
+    }
+    const iu = ctxMap.get(id.iuId);
+    if (!iu) {
+      this.onEvent({ kind: "unknown_iu", op: "revoke", id });
+      return;
+    }
+    if (iu.state !== "hypothesized") {
+      this.onEvent({ kind: "terminal_op", op: "revoke", id, state: iu.state });
+      return;
+    }
+    iu.state = "revoked";
+  }
+
+  get(id: IncrementalUnitId): IncrementalUnit | undefined {
+    const ctxMap = this.byCtx.get(id.contextId);
+    if (!ctxMap) {
+      return undefined;
+    }
+    return ctxMap.get(id.iuId);
+  }
+
+  latest(contextId: string, kind: IncrementalUnit["kind"]): IncrementalUnit | undefined {
+    const ctxMap = this.byCtx.get(contextId);
+    if (!ctxMap) {
+      return undefined;
+    }
+    let found: IncrementalUnit | undefined;
+    for (const iu of ctxMap.values()) {
+      if (iu.kind === kind) {
+        found = iu;
+      }
+    }
+    return found;
+  }
+
+  clear(contextId: string): void {
+    this.byCtx.delete(contextId);
+  }
+
+  private ctxMap(contextId: string): Map<string, IncrementalUnit> {
+    let map = this.byCtx.get(contextId);
+    if (!map) {
+      map = new Map();
+      this.byCtx.set(contextId, map);
+    }
+    return map;
+  }
+}

package/src/packet-factories.test.ts

@@ -2,7 +2,26 @@
 
 import { describe, expect, it } from "vitest";
 
-import { reasoningResume, reasoningSuspended } from "./packet-factories.js";
+import { reasoningResume, reasoningSuspended, sttPartial } from "./packet-factories.js";
+
+describe("sttPartial", () => {
+  it("returns a stt.partial packet with optional wordTimings", () => {
+    const timings = [{ word: "hello", startMs: 100, endMs: 250, confidence: 0.9 }];
+    expect(sttPartial("ctx-1", 1000, "hello world", timings)).toEqual({
+      kind: "stt.partial",
+      contextId: "ctx-1",
+      timestampMs: 1000,
+      text: "hello world",
+      wordTimings: timings,
+    });
+    expect(sttPartial("ctx-1", 1000, "hello")).toEqual({
+      kind: "stt.partial",
+      contextId: "ctx-1",
+      timestampMs: 1000,
+      text: "hello",
+    });
+  });
+});
 
 describe("reasoningSuspended", () => {
   it("returns a reasoning.suspended packet with the expected shape", () => {

package/src/packet-factories.ts

@@ -7,6 +7,7 @@
 // definition and call sites need no `as` assertion — illegal packet shapes are
 // unrepresentable at construction instead of asserted-valid by a cast (CR-05).
 
+import type { WordTiming } from "./interaction-policy.js";
 import { ErrorCategory } from "./packets.js";
 import type {
   ConversationMetricPacket,
@@ -21,7 +22,9 @@ import type {
   SpeechToTextAudioPacket,
   EndOfSpeechAudioPacket,
   EndOfSpeechPacket,
+  SttPartialPacket,
   SttResultPacket,
+  FinalizeSttPacket,
   UserInputPacket,
   TextToSpeechTextPacket,
   TextToSpeechDonePacket,
@@ -39,6 +42,7 @@ import type {
   StartIdleTimeoutPacket,
   StopIdleTimeoutPacket,
   ModeSwitchRequestedPacket,
+  InteractionBackchannelPacket,
 } from "./packets.js";
 
 const DTMF_DIGITS = new Set<DtmfDigit>(["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#"]);
@@ -115,6 +119,17 @@ export function sttAudio(contextId: string, timestampMs: number, audio: Uint8Arr
   return { kind: "stt.audio", contextId, timestampMs, audio };
 }
 
+export function sttPartial(
+  contextId: string,
+  timestampMs: number,
+  text: string,
+  wordTimings?: readonly WordTiming[],
+): SttPartialPacket {
+  return wordTimings
+    ? { kind: "stt.partial", contextId, timestampMs, text, wordTimings }
+    : { kind: "stt.partial", contextId, timestampMs, text };
+}
+
 export function eosAudio(contextId: string, timestampMs: number, audio: Uint8Array): EndOfSpeechAudioPacket {
   return { kind: "eos.audio", contextId, timestampMs, audio };
 }
@@ -128,6 +143,10 @@ export function eosTurnComplete(
   return { kind: "eos.turn_complete", contextId, timestampMs, text, transcripts };
 }
 
+export function finalizeStt(contextId: string, timestampMs: number): FinalizeSttPacket {
+  return { kind: "stt.finalize", contextId, timestampMs };
+}
+
 export function userInput(
   contextId: string,
   timestampMs: number,
@@ -241,3 +260,11 @@ export function modeSwitchRequested(
 ): ModeSwitchRequestedPacket {
   return { kind: "mode.switch_requested", contextId, timestampMs, mode };
 }
+
+export function interactionBackchannel(
+  contextId: string,
+  timestampMs: number,
+  cue: string,
+): InteractionBackchannelPacket {
+  return { kind: "interaction.backchannel", contextId, timestampMs, cue };
+}

package/src/packets.ts

@@ -9,6 +9,8 @@
 //   Errors:                 SttError, TtsError, LlmError
 //   Lifecycle:              InitStepCompleted, InitFailed, InitCompleted
 
+import type { WordTiming } from "./interaction-policy.js";
+
 // =============================================================================
 // Base Types
 // =============================================================================
@@ -44,7 +46,7 @@ export enum ErrorCategory {
 
 export interface VoiceErrorPacket extends VoicePacket {
   /** Which component emitted the error. */
-  readonly component: "stt" | "tts" | "vad" | "eos" | "denoiser" | "llm" | "bridge" | "pipeline";
+  readonly component: "stt" | "tts" | "vad" | "eos" | "denoiser" | "llm" | "bridge" | "pipeline" | "iu_ledger";
   /** Machine-readable error category. */
   readonly category: ErrorCategory;
   /** Original error. May contain provider-specific details. */
@@ -120,8 +122,10 @@ export interface AudioFormat {
 
 export interface UserAudioReceivedPacket extends VoicePacket {
   readonly kind: "user.audio_received";
-  /** Raw PCM audio (16-bit, mono, 16kHz). */
+  /** Raw PCM audio (16-bit, mono). Rate given by `sampleRateHz` (defaults to 16kHz). */
   readonly audio: Uint8Array;
+  /** Sample rate of `audio` in Hz. Omitted means 16000 (the legacy default). */
+  readonly sampleRateHz?: number;
 }
 
 export interface UserTextReceivedPacket extends VoicePacket {
@@ -176,6 +180,12 @@ export interface SttInterimPacket extends VoicePacket {
   readonly text: string;
 }
 
+export interface SttPartialPacket extends VoicePacket {
+  readonly kind: "stt.partial";
+  readonly text: string;
+  readonly wordTimings?: readonly WordTiming[];
+}
+
 export interface SttResultPacket extends VoicePacket {
   readonly kind: "stt.result";
   readonly text: string;
@@ -211,6 +221,16 @@ export interface InterimEndOfSpeechPacket extends VoicePacket {
   readonly text: string;
 }
 
+/**
+ * Retraction of a prior `eos.interim` for the same context: the endpoint model
+ * signalled a likely turn end, then the user kept speaking (Deepgram Flux
+ * `TurnResumed` semantics). Consumers doing speculative work off `eos.interim`
+ * must cancel it.
+ */
+export interface EndOfSpeechRetractedPacket extends VoicePacket {
+  readonly kind: "eos.retracted";
+}
+
 // =============================================================================
 // User Input (processed — feeds LLM)
 // =============================================================================
@@ -276,7 +296,7 @@ export interface LlmResponseDonePacket extends VoicePacket {
 
 export interface LlmErrorPacket extends VoicePacket, VoiceErrorPacket {
   readonly kind: "llm.error";
-  readonly component: "llm" | "bridge";
+  readonly component: "llm" | "bridge" | "iu_ledger";
 }
 
 export interface LlmToolCallPacket extends VoicePacket {
@@ -450,6 +470,16 @@ export interface RecordAssistantAudioTruncatePacket extends VoicePacket {
 
 export type RecordAssistantAudioPacket = RecordAssistantAudioDataPacket | RecordAssistantAudioTruncatePacket;
 
+// =============================================================================
+// Interaction Policy Packets
+// =============================================================================
+
+/** Pre-cached backchannel cue id rendered by the outbound mixer (IP-C3). */
+export interface InteractionBackchannelPacket extends VoicePacket {
+  readonly kind: "interaction.backchannel";
+  readonly cue: string;
+}
+
 // =============================================================================
 // Behavior Packets
 // =============================================================================
@@ -550,12 +580,14 @@ export type InputPacket =
   | VadSpeechActivityPacket
   | SpeechToTextAudioPacket
   | SttInterimPacket
+  | SttPartialPacket
   | SttResultPacket
   | FinalizeSttPacket
   | SttErrorPacket
   | EndOfSpeechAudioPacket
   | EndOfSpeechPacket
   | InterimEndOfSpeechPacket
+  | EndOfSpeechRetractedPacket
   | UserInputPacket;
 
 /** All interruption packets (Critical route). */

package/src/policies/defer.test.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect } from "vitest";
+import type { InteractionObservation, InteractionPolicy } from "../interaction-policy.js";
+import { DeferInteractionPolicy } from "./defer.js";
+
+const OBSERVATIONS: InteractionObservation[] = [
+  {
+    kind: "vad_speech_started",
+    contextId: "user",
+    timestampMs: 1000,
+    confidence: 0.99,
+    interruptedContextId: "assistant-turn",
+  },
+  {
+    kind: "vad_speech_activity",
+    contextId: "user",
+    timestampMs: 1300,
+  },
+  {
+    kind: "vad_speech_ended",
+    contextId: "user",
+    timestampMs: 2000,
+    hasActiveTts: true,
+  },
+  {
+    kind: "vad_barge_in_audio",
+    contextId: "user",
+    timestampMs: 1500,
+    audio: new Uint8Array([1, 2, 3]),
+  },
+  {
+    kind: "stt_partial",
+    contextId: "user",
+    timestampMs: 1600,
+    text: "hello",
+    confidence: 0.9,
+    interruptedContextId: "assistant-turn",
+  },
+  {
+    kind: "stt_final",
+    contextId: "user",
+    timestampMs: 2000,
+    text: "hello there",
+    confidence: 0.95,
+    interruptedContextId: "assistant-turn",
+  },
+  {
+    kind: "audio_frame",
+    contextId: "user",
+    timestampMs: 1700,
+    audio: new Int16Array([1, 2, 3]),
+  },
+  {
+    kind: "playout_tick",
+    contextId: "assistant-turn",
+    timestampMs: 1800,
+    playedOutMs: 500,
+    ttsActive: true,
+  },
+  {
+    kind: "delegate_state",
+    contextId: "turn-1",
+    timestampMs: 1900,
+    delegateInFlight: true,
+  },
+];
+
+describe("DeferInteractionPolicy", () => {
+  it("implements InteractionPolicy", () => {
+    const policy: InteractionPolicy = new DeferInteractionPolicy();
+    expect(policy).toBeInstanceOf(DeferInteractionPolicy);
+  });
+
+  it("observe returns [] for every observation kind", () => {
+    const policy = new DeferInteractionPolicy();
+    for (const obs of OBSERVATIONS) {
+      expect(policy.observe(obs)).toEqual([]);
+    }
+  });
+
+  it("reset is a no-op", () => {
+    const policy = new DeferInteractionPolicy();
+    expect(() => policy.reset("any-context")).not.toThrow();
+  });
+});

package/src/policies/defer.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+
+import type { InteractionDecision, InteractionObservation, InteractionPolicy } from "../interaction-policy.js";
+
+/**
+ * The front owns full-duplex interaction (turn-taking, barge-in, backchannels). This policy takes no
+ * action — it observes only, so the coordinator drives nothing and the front's own decisions (surfaced
+ * by its adapter/bridge as interrupt.detected / eos.turn_complete) stand. RFC InteractionPolicy REQ-4.
+ */
+export class DeferInteractionPolicy implements InteractionPolicy {
+  observe(_obs: InteractionObservation): readonly InteractionDecision[] {
+    return [];
+  }
+  reset(_contextId: string): void {}
+}

package/src/policies/rule-based.test.ts

@@ -0,0 +1,269 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect } from "vitest";
+import { PipelineBusImpl } from "../pipeline-bus.js";
+import { RuleBasedInteractionPolicy } from "./rule-based.js";
+import { PrimarySpeakerGate } from "../primary-speaker-gate.js";
+import { TtsPlayoutClock } from "../tts-playout-clock.js";
+
+async function createPolicy(minInterruptionMs = 280) {
+  const bus = new PipelineBusImpl();
+  void bus.start();
+  const ttsPlayout = new TtsPlayoutClock();
+  const policy = new RuleBasedInteractionPolicy({
+    bus,
+    primarySpeakerGate: new PrimarySpeakerGate(),
+    ttsPlayout,
+    minInterruptionMs,
+  });
+  return { bus, ttsPlayout, policy };
+}
+
+function metricNames(bus: PipelineBusImpl): string[] {
+  const names: string[] = [];
+  bus.on("metric.conversation", (pkt) => {
+    names.push((pkt as unknown as { name: string }).name);
+  });
+  return names;
+}
+
+async function drainBus(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe("RuleBasedInteractionPolicy", () => {
+  it("parity vector: sustained speech commits interrupt at activity frame", async () => {
+    const { ttsPlayout, policy } = await createPolicy(280);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    const t0 = 2000;
+    expect(
+      policy.observe({
+        kind: "vad_speech_started",
+        contextId: "user",
+        timestampMs: t0,
+        confidence: 0.99,
+        interruptedContextId: "assistant-turn",
+      }),
+    ).toEqual([]);
+
+    expect(
+      policy.observe({
+        kind: "vad_speech_activity",
+        contextId: "user",
+        timestampMs: t0 + 300,
+      }),
+    ).toEqual([{ kind: "interrupt", interruptedContextId: "assistant-turn" }]);
+  });
+
+  it("suppresses short speech blip without interrupt decision", async () => {
+    const { bus, ttsPlayout, policy } = await createPolicy(280);
+    const metrics = metricNames(bus);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    const t0 = 3000;
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: t0,
+      confidence: 0.99,
+      interruptedContextId: "assistant-turn",
+    });
+    policy.observe({
+      kind: "vad_speech_activity",
+      contextId: "user",
+      timestampMs: t0 + 90,
+    });
+    const decisions = policy.observe({
+      kind: "vad_speech_ended",
+      contextId: "user",
+      timestampMs: t0 + 130,
+      hasActiveTts: true,
+    });
+    await drainBus();
+
+    expect(decisions).toEqual([]);
+    expect(metrics).toContain("interrupt.suppressed_short_speech");
+  });
+
+  it("suppresses backchannel interim without interrupt decision", async () => {
+    const { bus, ttsPlayout, policy } = await createPolicy(280);
+    const metrics = metricNames(bus);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: 2000,
+      confidence: 0.99,
+      interruptedContextId: "assistant-turn",
+    });
+    policy.observe({
+      kind: "stt_partial",
+      contextId: "user",
+      timestampMs: 2050,
+      text: "uh huh",
+    });
+    const decisions = policy.observe({
+      kind: "vad_speech_activity",
+      contextId: "user",
+      timestampMs: 2300,
+    });
+    await drainBus();
+
+    expect(decisions).toEqual([]);
+    expect(metrics).toContain("interrupt.suppressed_backchannel");
+  });
+
+  it("IP-C3: emits no backchannel on VAD/user-pause observations", async () => {
+    const { policy } = await createPolicy();
+
+    expect(
+      policy.observe({
+        kind: "vad_speech_ended",
+        contextId: "user",
+        timestampMs: 5000,
+        hasActiveTts: false,
+      }),
+    ).toEqual([]);
+    expect(
+      policy.observe({
+        kind: "vad_speech_activity",
+        contextId: "user",
+        timestampMs: 5100,
+      }),
+    ).toEqual([]);
+  });
+
+  it("IP-C3: emits exactly one cue on started → delayed and clears on complete", async () => {
+    const { policy } = await createPolicy();
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([{ kind: "backchannel", cue: "mm_hmm" }]);
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3200,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 4000,
+      toolCallPhase: "complete",
+    });
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 5000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 7000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([{ kind: "backchannel", cue: "mm_hmm" }]);
+  });
+
+  it("IP-C3: suppresses backchannel when TTS is active or the user is speaking", async () => {
+    const { ttsPlayout, policy } = await createPolicy();
+    ttsPlayout.noteAudio("assistant-turn", 500, 1000);
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+
+    ttsPlayout.release("assistant-turn");
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-2",
+      timestampMs: 4000,
+      toolCallPhase: "started",
+    });
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: 4100,
+      confidence: 0.9,
+      interruptedContextId: "",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-2",
+        timestampMs: 6000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+  });
+
+  it("IP-C3: reset clears delegate-gap backchannel state", async () => {
+    const { policy } = await createPolicy();
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    policy.reset("turn-1");
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+  });
+
+  it("reset clears pending state", async () => {
+    const { ttsPlayout, policy } = await createPolicy(280);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    const t0 = 4000;
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: t0,
+      confidence: 0.99,
+      interruptedContextId: "assistant-turn",
+    });
+    policy.reset("user");
+
+    const decisions = policy.observe({
+      kind: "vad_speech_activity",
+      contextId: "user",
+      timestampMs: t0 + 300,
+    });
+    expect(decisions).toEqual([]);
+  });
+});