@kuralle-syrinx/aisdk 4.1.0 → 4.2.0

package/package.json

@@ -1,16 +1,34 @@
 {
   "name": "@kuralle-syrinx/aisdk",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "private": false,
-  "type": "module",
+  "description": "Vercel AI SDK bridge for Syrinx — drive any ai@6 model or agent as the voice pipeline's reasoner, with opt-in speculative generation",
+  "keywords": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "ai-sdk",
+    "vercel-ai"
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/aisdk"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
     "@ai-sdk/openai": "^3.0.67",
     "ai": "^6.0.0",
     "zod": "^4.1.8",
-    "@kuralle-syrinx/core": "4.1.0"
+    "@kuralle-syrinx/core": "4.2.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",

package/src/heard-prefix-commit.test.ts

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import {
+  PipelineBusImpl,
+  Route,
+  type EndOfSpeechPacket,
+  type InMemoryIuLedger,
+  type IncrementalUnitId,
+  type InterruptLlmPacket,
+  type TextToSpeechPlayoutProgressPacket,
+  type TextToSpeechTextPacket,
+  type TextToSpeechWordTimestampsPacket,
+  type TtsWordTimestamp,
+} from "@kuralle-syrinx/core";
+import type { FinishReason, TextStreamPart, ToolSet } from "ai";
+import { fromStreamFactory } from "./from-ai-sdk.js";
+import { ReasoningBridge } from "./index.js";
+
+const ZERO_USAGE = {
+  inputTokens: 0,
+  inputTokenDetails: { noCacheTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+  outputTokens: 0,
+  outputTokenDetails: { textTokens: 0, reasoningTokens: 0 },
+  totalTokens: 0,
+};
+
+type BridgeLedgerAccess = {
+  iuLedger: InMemoryIuLedger;
+};
+
+function bridgeLedger(plugin: ReasoningBridge): BridgeLedgerAccess {
+  return plugin as unknown as BridgeLedgerAccess;
+}
+
+function assistantId(contextId: string, epoch = 1): IncrementalUnitId {
+  return { contextId, iuId: `${contextId}#assistant`, epoch };
+}
+
+function userTurnId(contextId: string, epoch = 1): IncrementalUnitId {
+  return { contextId, iuId: contextId, epoch };
+}
+
+describe("ReasoningBridge heard-prefix commit (S2-01)", () => {
+  it("commits assistant IU with word-boundary prefix on barge-in during playback", async () => {
+    const packets: Array<{ packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Hello world foo bar.");
+        yield finish("stop");
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-word";
+
+    bus.push(Route.Main, turnComplete(ctx, "first question"));
+    await waitFor(() => hasPacket(packets, "llm.done", ctx));
+
+    bus.push(Route.Main, wordTimestamps(ctx, [
+      { word: "Hello", startMs: 0, endMs: 200 },
+      { word: "world", startMs: 220, endMs: 400 },
+      { word: "foo", startMs: 420, endMs: 600 },
+      { word: "bar.", startMs: 620, endMs: 800 },
+    ]));
+    bus.push(Route.Main, playoutProgress(ctx, 450));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    bus.push(Route.Critical, interruptLlm(ctx));
+    await waitFor(() => hasMetric(packets, "llm.history_truncated_to_spoken"));
+
+    const spoken = "Hello world";
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix?.chars).toBe(spoken.length);
+    expect(iu.committedPrefix?.ms).toBe(450);
+    expect(iu.committedPrefix?.chars).toBeLessThan("Hello world foo bar.".length);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("commits assistant IU with spokenByContext prefix when word timestamps are absent", async () => {
+    const packets: Array<{ packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Sentence one. Sentence two.");
+        yield finish("stop");
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-fallback";
+
+    bus.push(Route.Main, turnComplete(ctx, "first question"));
+    await waitFor(() => hasPacket(packets, "llm.done", ctx));
+
+    bus.push(Route.Main, ttsText(ctx, "Sentence one."));
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    bus.push(Route.Critical, interruptLlm(ctx));
+    await waitFor(() => hasMetric(packets, "llm.history_truncated_to_spoken"));
+
+    const spoken = "Sentence one.";
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix?.chars).toBe(spoken.length);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("commits heard prefix on mid-stream interrupt without losing streamed packets", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* ({ signal }) {
+        yield textDelta("Hello");
+        await new Promise<void>((resolve) => {
+          if (signal.aborted) {
+            resolve();
+            return;
+          }
+          signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-mid";
+
+    bus.push(Route.Main, turnComplete(ctx, "first question"));
+    await waitFor(() =>
+      packets.some(
+        ({ packet }) =>
+          (packet as { kind?: string }).kind === "llm.delta" &&
+          (packet as { text?: string }).text === "Hello",
+      ),
+    );
+
+    bus.push(Route.Main, ttsText(ctx, "Hello"));
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    bus.push(Route.Critical, interruptLlm(ctx));
+    await waitFor(() => hasMetric(packets, "llm.history_truncated_to_spoken"));
+
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix?.chars).toBe("Hello".length);
+
+    expect(packets).toContainEqual({
+      route: Route.Main,
+      packet: expect.objectContaining({ kind: "llm.delta", contextId: ctx, text: "Hello" }),
+    });
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("commits assistant IU fully on clean completion without a truncated prefix", async () => {
+    const packets: Array<{ packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Clean answer.");
+        yield finish("stop");
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-clean";
+
+    bus.push(Route.Main, turnComplete(ctx, "question"));
+    await waitFor(() => hasPacket(packets, "llm.done", ctx));
+
+    const iu = ledger.iuLedger.get(assistantId(ctx))!;
+    expect(iu.state).toBe("committed");
+    expect(iu.committedPrefix).toBeUndefined();
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("keeps distinct assistant and user-turn IUs in the ledger for one contextId", async () => {
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Answer.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: () => {} });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+    const ctx = "turn-dual";
+
+    bus.push(Route.Main, eosInterim(ctx, "hello"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    const userIu = ledger.iuLedger.get(userTurnId(ctx));
+    const assistantIu = ledger.iuLedger.get(assistantId(ctx));
+    expect(userIu?.kind).toBe("user_turn");
+    expect(assistantIu?.kind).toBe("assistant_response");
+    expect(userIu?.id.iuId).toBe(ctx);
+    expect(assistantIu?.id.iuId).toBe(`${ctx}#assistant`);
+    expect(userIu?.id.epoch).toBe(assistantIu?.id.epoch);
+
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+});
+
+function baseConfig(): Record<string, unknown> {
+  return {
+    api_key: "test-key",
+    model: "gpt-test",
+    system_prompt: "test",
+    retry_max_attempts: 1,
+    timeout_ms: 1000,
+  };
+}
+
+function turnComplete(contextId: string, text: string): EndOfSpeechPacket {
+  return { kind: "eos.turn_complete", contextId, timestampMs: Date.now(), text, transcripts: [] };
+}
+
+function eosInterim(contextId: string, text: string): { kind: "eos.interim"; contextId: string; timestampMs: number; text: string } {
+  return { kind: "eos.interim", contextId, timestampMs: Date.now(), text };
+}
+
+function ttsText(contextId: string, text: string): TextToSpeechTextPacket {
+  return { kind: "tts.text", contextId, timestampMs: Date.now(), text };
+}
+
+function wordTimestamps(contextId: string, words: TtsWordTimestamp[]): TextToSpeechWordTimestampsPacket {
+  return { kind: "tts.word_timestamps", contextId, timestampMs: Date.now(), words };
+}
+
+function playoutProgress(contextId: string, playedOutMs: number): TextToSpeechPlayoutProgressPacket {
+  return { kind: "tts.playout_progress", contextId, timestampMs: Date.now(), playedOutMs, complete: false };
+}
+
+function interruptLlm(contextId: string): InterruptLlmPacket {
+  return { kind: "interrupt.llm", contextId, timestampMs: Date.now() };
+}
+
+function textDelta(text: string): TextStreamPart<ToolSet> {
+  return { type: "text-delta", id: "0", text, providerMetadata: undefined } as TextStreamPart<ToolSet>;
+}
+
+function finish(finishReason: FinishReason): TextStreamPart<ToolSet> {
+  return {
+    type: "finish",
+    finishReason,
+    totalUsage: ZERO_USAGE,
+    usage: ZERO_USAGE,
+    providerMetadata: undefined,
+    response: {},
+  } as unknown as TextStreamPart<ToolSet>;
+}
+
+function hasPacket(packets: Array<{ packet: unknown }>, kind: string, contextId: string): boolean {
+  return packets.some(
+    ({ packet }) =>
+      (packet as { kind?: string }).kind === kind &&
+      (packet as { contextId?: string }).contextId === contextId,
+  );
+}
+
+function hasMetric(packets: Array<{ packet: unknown }>, name: string): boolean {
+  return packets.some(({ packet }) => (packet as { name?: string }).name === name);
+}
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const started = Date.now();
+  while (!predicate()) {
+    if (Date.now() - started > 2000) throw new Error("Timed out waiting for condition");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}

package/src/index.ts

@@ -20,12 +20,14 @@ import {
   type ReasonerSessionStore,
   type ReasonerTurn,
   type TtsWordTimestamp,
+  type IncrementalUnitId,
   categorizeLlmError,
   isRecoverable,
   readRetryConfig,
   waitForRetryDelay,
   ErrorCategory,
   type RetryConfig,
+  InMemoryIuLedger,
 } from "@kuralle-syrinx/core";
 
 export {
@@ -60,8 +62,6 @@ export interface RunStore {
  * simply dropped — the generation was never observable.
  */
 interface SpeculativeHold {
-  promoted: boolean;
-  failed: boolean;
   buffered: Array<() => void>;
 }
 
@@ -77,7 +77,11 @@ export class ReasoningBridge implements VoicePlugin {
     userText: string;
     controller: AbortController;
     hold: SpeculativeHold;
+    id: IncrementalUnitId;
   } | null = null;
+  private iuLedger!: InMemoryIuLedger;
+  private readonly epochByContext = new Map<string, number>();
+  private turnEpochCounter = 0;
   private retryConfig: RetryConfig = readRetryConfig({});
   private disposers: Array<() => void> = [];
   // G2/G25: per-turn state so a barged-in turn is remembered as what the user HEARD,
@@ -134,6 +138,21 @@ export class ReasoningBridge implements VoicePlugin {
 
   async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
     this.bus = bus;
+    this.iuLedger = new InMemoryIuLedger((a) => {
+      const detail =
+        a.kind === "terminal_op"
+          ? `${a.op} on ${a.state} IU`
+          : `${a.op} on unknown IU`;
+      this.bus?.push(Route.Background, {
+        kind: "llm.error",
+        contextId: a.id.contextId,
+        timestampMs: Date.now(),
+        component: "iu_ledger",
+        category: ErrorCategory.InternalFault,
+        cause: new Error(`iu_ledger anomaly: ${a.kind} ${detail}`),
+        isRecoverable: true,
+      });
+    });
     this.timeoutMs = readPositiveIntegerConfig(config["timeout_ms"], 30_000);
     this.maxHistoryTurns = readPositiveIntegerConfig(config["max_history_turns"], 12);
     this.retryConfig = readRetryConfig(config);
@@ -165,10 +184,10 @@ export class ReasoningBridge implements VoicePlugin {
           draft.contextId === eos.contextId &&
           draft.userText === eos.text &&
           !draft.controller.signal.aborted &&
-          !draft.hold.failed
+          this.iuLedger.get(draft.id)?.state === "hypothesized"
         ) {
+          this.iuLedger.commit(draft.id);
           this.speculativeDraft = null;
-          draft.hold.promoted = true;
           for (const flush of draft.hold.buffered.splice(0)) flush();
           return;
         }
@@ -240,17 +259,41 @@ export class ReasoningBridge implements VoicePlugin {
   /** Start (or restart, if a newer eager endpoint supersedes) the speculative draft. */
   private async runDraft(userText: string, contextId: string): Promise<void> {
     this.discardDraft();
+    const id = this.iuIdFor(contextId);
+    this.iuLedger.add({ id, kind: "user_turn", state: "hypothesized" });
     const controller = new AbortController();
-    const hold: SpeculativeHold = { promoted: false, failed: false, buffered: [] };
-    this.speculativeDraft = { contextId, userText, controller, hold };
-    await this.processTurn(userText, contextId, hold, controller);
+    const hold: SpeculativeHold = { buffered: [] };
+    this.speculativeDraft = { contextId, userText, controller, hold, id };
+    await this.processTurn(userText, contextId, hold, controller, id);
+  }
+
+  private iuIdFor(contextId: string): IncrementalUnitId {
+    let epoch = this.epochByContext.get(contextId);
+    if (epoch === undefined) {
+      epoch = ++this.turnEpochCounter;
+      this.epochByContext.set(contextId, epoch);
+    }
+    return { contextId, iuId: contextId, epoch };
+  }
+
+  private assistantIuIdFor(contextId: string): IncrementalUnitId {
+    let epoch = this.epochByContext.get(contextId);
+    if (epoch === undefined) {
+      epoch = ++this.turnEpochCounter;
+      this.epochByContext.set(contextId, epoch);
+    }
+    return { contextId, iuId: `${contextId}#assistant`, epoch };
   }
 
   private discardDraft(): void {
     const draft = this.speculativeDraft;
     if (!draft) return;
     this.speculativeDraft = null;
-    if (!draft.hold.promoted) draft.controller.abort();
+    const committed = this.iuLedger.get(draft.id)?.state === "committed";
+    if (!committed) {
+      this.iuLedger.revoke(draft.id);
+      draft.controller.abort();
+    }
   }
 
   private async processTurn(
@@ -258,6 +301,7 @@ export class ReasoningBridge implements VoicePlugin {
     contextId: string,
     hold?: SpeculativeHold,
     presetController?: AbortController,
+    iuId?: IncrementalUnitId,
   ): Promise<void> {
     if (!this.bus) return;
 
@@ -268,21 +312,27 @@ export class ReasoningBridge implements VoicePlugin {
     this.activeGeneration?.controller.abort();
     const controller = presetController ?? new AbortController();
     this.activeGeneration = { contextId, controller };
+    const aid = this.assistantIuIdFor(contextId);
+    this.iuLedger.add({ id: aid, kind: "assistant_response", state: "hypothesized" });
     const signal = controller.signal;
 
     // R2: while a speculative hold is unpromoted, every push/mutation buffers.
     // Packets are constructed eagerly (their timestamps are event time); only
     // delivery is deferred. Promotion replays in order, then later effects run live.
+    const isBuffering = (): boolean =>
+      hold !== undefined &&
+      iuId !== undefined &&
+      this.iuLedger.get(iuId)?.state !== "committed";
     const push = <T extends Parameters<PipelineBus["push"]>[1]>(route: Route, packet: T): void => {
-      if (hold && !hold.promoted) {
-        if ((packet as { kind?: string }).kind === "llm.error") hold.failed = true;
-        hold.buffered.push(() => this.bus?.push(route, packet));
+      if (isBuffering()) {
+        if ((packet as { kind?: string }).kind === "llm.error" && iuId) this.iuLedger.revoke(iuId);
+        hold!.buffered.push(() => this.bus?.push(route, packet));
         return;
       }
       this.bus?.push(route, packet);
     };
     const defer = (fn: () => void): void => {
-      if (hold && !hold.promoted) hold.buffered.push(fn);
+      if (isBuffering()) hold!.buffered.push(fn);
       else fn();
     };
 
@@ -393,8 +443,8 @@ export class ReasoningBridge implements VoicePlugin {
                 if (this.opts.runStore) {
                   const store = this.opts.runStore;
                   const runId = part.runId;
-                  if (hold && !hold.promoted) {
-                    hold.buffered.push(() => void Promise.resolve(store.save(contextId, runId)).catch(() => undefined));
+                  if (isBuffering()) {
+                    hold!.buffered.push(() => void Promise.resolve(store.save(contextId, runId)).catch(() => undefined));
                   } else {
                     await Promise.resolve(store.save(contextId, runId));
                   }
@@ -513,6 +563,7 @@ export class ReasoningBridge implements VoicePlugin {
     const assistantMsg = { role: "assistant" as const, content: assistantText };
     this.history.push({ role: "user", content: userText }, assistantMsg);
     this.assistantMsgByContext.set(contextId, assistantMsg);
+    this.iuLedger.commit(this.assistantIuIdFor(contextId));
     this.trimHistory();
     this.persistHistory();
   }
@@ -558,6 +609,15 @@ export class ReasoningBridge implements VoicePlugin {
    */
   private commitInterruptedHistory(contextId: string): void {
     const spoken = this.computeSpokenPrefix(contextId);
+    const aid = this.assistantIuIdFor(contextId);
+    const ms = this.playedOutMsByContext.get(contextId);
+    const prefix = { chars: spoken.length, ms };
+    const assistantIu = this.iuLedger.get(aid);
+    if (assistantIu?.state === "hypothesized") {
+      this.iuLedger.commit(aid, prefix);
+    } else if (assistantIu?.state === "committed") {
+      assistantIu.committedPrefix = prefix;
+    }
     const existing = this.assistantMsgByContext.get(contextId);
     if (existing) {
       if (spoken) {
@@ -597,6 +657,10 @@ export class ReasoningBridge implements VoicePlugin {
   }
 
   private clearTurnState(contextId: string): void {
+    const aid = this.assistantIuIdFor(contextId);
+    if (this.iuLedger.get(aid)?.state === "hypothesized") {
+      this.iuLedger.revoke(aid);
+    }
     this.spokenByContext.delete(contextId);
     this.turnUserText.delete(contextId);
     this.assistantMsgByContext.delete(contextId);

package/src/speculative-on-ledger.test.ts

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import {
+  PipelineBusImpl,
+  Route,
+  type EndOfSpeechPacket,
+  type InMemoryIuLedger,
+  type IncrementalUnitId,
+} from "@kuralle-syrinx/core";
+import type { FinishReason, TextStreamPart, ToolSet } from "ai";
+import { fromStreamFactory } from "./from-ai-sdk.js";
+import { ReasoningBridge } from "./index.js";
+
+const ZERO_USAGE = {
+  inputTokens: 0,
+  inputTokenDetails: { noCacheTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+  outputTokens: 0,
+  outputTokenDetails: { textTokens: 0, reasoningTokens: 0 },
+  totalTokens: 0,
+};
+
+type BridgeLedgerAccess = {
+  iuLedger: InMemoryIuLedger;
+  speculativeDraft: { id: IncrementalUnitId } | null;
+};
+
+function bridgeLedger(plugin: ReasoningBridge): BridgeLedgerAccess {
+  return plugin as unknown as BridgeLedgerAccess;
+}
+
+describe("ReasoningBridge speculative-on-ledger", () => {
+  it("eos.interim adds a hypothesized IU and matching eos.turn_complete commits it", async () => {
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Answer.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: () => {} });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+
+    bus.push(Route.Main, eosInterim("turn-1", "hello"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    const draftId = ledger.speculativeDraft?.id;
+    expect(draftId).toEqual({ contextId: "turn-1", iuId: "turn-1", epoch: 1 });
+    expect(ledger.iuLedger.get(draftId!)?.state).toBe("hypothesized");
+
+    bus.push(Route.Main, turnComplete("turn-1", "hello"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(ledger.iuLedger.get(draftId!)?.state).toBe("committed");
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("eos.retracted revokes the hypothesized IU", async () => {
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Draft.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: () => {} });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+
+    bus.push(Route.Main, eosInterim("turn-1", "book a"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    const draftId = ledger.speculativeDraft?.id;
+    expect(ledger.iuLedger.get(draftId!)?.state).toBe("hypothesized");
+
+    bus.push(Route.Main, eosRetracted("turn-1"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(ledger.iuLedger.get(draftId!)?.state).toBe("revoked");
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("double-commit fires an iu_ledger anomaly on the bus", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Answer.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+
+    bus.push(Route.Main, eosInterim("turn-1", "hello"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    const draftId = ledger.speculativeDraft?.id;
+    expect(draftId).toBeDefined();
+
+    bus.push(Route.Main, turnComplete("turn-1", "hello"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(ledger.iuLedger.get(draftId!)?.state).toBe("committed");
+
+    ledger.iuLedger.commit(draftId!);
+    await waitFor(() =>
+      packets.some(
+        ({ packet }) =>
+          (packet as { kind?: string; component?: string }).kind === "llm.error" &&
+          (packet as { component?: string }).component === "iu_ledger",
+      ),
+    );
+
+    expect(packets).toContainEqual({
+      route: Route.Background,
+      packet: expect.objectContaining({
+        kind: "llm.error",
+        component: "iu_ledger",
+        contextId: "turn-1",
+        isRecoverable: true,
+      }),
+    });
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+
+  it("assigns monotonic epoch across distinct contextIds", async () => {
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Answer.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: () => {} });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+    const ledger = bridgeLedger(plugin);
+
+    bus.push(Route.Main, eosInterim("ctx-a", "first"));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    const idA = ledger.speculativeDraft?.id;
+    bus.push(Route.Main, turnComplete("ctx-a", "first"));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    bus.push(Route.Main, eosInterim("ctx-b", "second"));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    const idB = ledger.speculativeDraft?.id;
+
+    expect(idA?.epoch).toBe(1);
+    expect(idB?.epoch).toBe(2);
+    expect(idB!.epoch).toBeGreaterThan(idA!.epoch);
+    bus.stop();
+    await drain;
+    await plugin.close();
+  });
+});
+
+function baseConfig(): Record<string, unknown> {
+  return {
+    api_key: "test-key",
+    model: "gpt-test",
+    system_prompt: "test",
+    retry_max_attempts: 1,
+    timeout_ms: 1000,
+  };
+}
+
+function turnComplete(contextId: string, text: string): EndOfSpeechPacket {
+  return { kind: "eos.turn_complete", contextId, timestampMs: Date.now(), text, transcripts: [] };
+}
+
+function eosInterim(contextId: string, text: string): { kind: "eos.interim"; contextId: string; timestampMs: number; text: string } {
+  return { kind: "eos.interim", contextId, timestampMs: Date.now(), text };
+}
+
+function eosRetracted(contextId: string): { kind: "eos.retracted"; contextId: string; timestampMs: number } {
+  return { kind: "eos.retracted", contextId, timestampMs: Date.now() };
+}
+
+function textDelta(text: string): TextStreamPart<ToolSet> {
+  return { type: "text-delta", id: "0", text, providerMetadata: undefined } as TextStreamPart<ToolSet>;
+}
+
+function finish(finishReason: FinishReason, rawFinishReason?: string): TextStreamPart<ToolSet> {
+  return {
+    type: "finish",
+    finishReason,
+    rawFinishReason,
+    totalUsage: ZERO_USAGE,
+    usage: ZERO_USAGE,
+    providerMetadata: undefined,
+    response: {},
+  } as TextStreamPart<ToolSet>;
+}
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const started = Date.now();
+  while (!predicate()) {
+    if (Date.now() - started > 1000) throw new Error("Timed out waiting for packet");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}

package/src/speculative-post-promotion.test.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+//
+// Regression guard (S1-01, RFC C2): when a speculative draft is promoted MID-STREAM,
+// deltas produced AFTER the promotion must go live, not stay buffered. The speculative
+// side-effect gate must re-check commit state per push — hoisting it to a single value
+// captured at generation start loses the post-promotion tail (incl. llm.done).
+
+import { describe, expect, it } from "vitest";
+import { PipelineBusImpl, Route } from "@kuralle-syrinx/core";
+import type { EndOfSpeechPacket } from "@kuralle-syrinx/core";
+import type { FinishReason, TextStreamPart, ToolSet } from "ai";
+import { fromStreamFactory } from "./from-ai-sdk.js";
+import { ReasoningBridge } from "./index.js";
+
+const ZERO_USAGE = {
+  inputTokens: 0,
+  inputTokenDetails: { noCacheTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+  outputTokens: 0,
+  outputTokenDetails: { reasoningTokens: 0 },
+  totalTokens: 0,
+  reasoningTokens: 0,
+  cachedInputTokens: 0,
+} as unknown as Record<string, unknown>;
+
+function textDelta(text: string): TextStreamPart<ToolSet> {
+  return { type: "text-delta", id: "0", text, providerMetadata: undefined } as TextStreamPart<ToolSet>;
+}
+function finish(finishReason: FinishReason): TextStreamPart<ToolSet> {
+  return { type: "finish", finishReason, totalUsage: ZERO_USAGE, usage: ZERO_USAGE, providerMetadata: undefined, response: {} } as unknown as TextStreamPart<ToolSet>;
+}
+function eosInterim(contextId: string, text: string) {
+  return { kind: "eos.interim" as const, contextId, timestampMs: Date.now(), text };
+}
+function turnComplete(contextId: string, text: string): EndOfSpeechPacket {
+  return { kind: "eos.turn_complete", contextId, timestampMs: Date.now(), text, transcripts: [] };
+}
+function baseConfig(): Record<string, unknown> {
+  return { api_key: "test-key", model: "gpt-test", system_prompt: "test", retry_max_attempts: 1, timeout_ms: 1000 };
+}
+async function waitFor(predicate: () => boolean): Promise<void> {
+  for (let i = 0; i < 200; i++) {
+    if (predicate()) return;
+    await new Promise((r) => setTimeout(r, 10));
+  }
+  throw new Error("waitFor timed out");
+}
+
+describe("S1 repro — post-promotion streaming", () => {
+  it("a delta streamed AFTER a mid-stream promotion must still reach the bus", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    let release!: () => void;
+    const gate = new Promise<void>((r) => { release = r; });
+
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("first ");   // buffered while hypothesized
+        await gate;                  // still streaming — pause BEFORE promotion completes
+        yield textDelta("second");   // streamed AFTER promotion
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+
+    bus.push(Route.Main, eosInterim("turn-1", "hello there"));
+    await new Promise((r) => setTimeout(r, 50)); // "first " buffered; generator paused at gate
+
+    bus.push(Route.Main, turnComplete("turn-1", "hello there")); // promote (commit) mid-stream
+    await new Promise((r) => setTimeout(r, 20));
+    release(); // now let the generator stream the post-promotion delta
+
+    await waitFor(() => packets.some((p) => (p.packet as { kind: string }).kind === "llm.done"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    const deltaTexts = packets
+      .filter((p) => (p.packet as { kind: string }).kind === "llm.delta")
+      .map((p) => (p.packet as { text: string }).text);
+
+    // The post-promotion "second" delta MUST have reached the bus.
+    expect(deltaTexts).toContain("second");
+  });
+});