@digitalpaws/starr 0.0.1

package/tests/event-bus.test.ts

@@ -0,0 +1,925 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { EventBusImpl } from "../src/events/event-bus.js";
+import { createLogger } from "../src/logging/logger.js";
+import {
+  isSpineType,
+  validateSpineEmission,
+  SPINE_EVENTS,
+} from "../src/events/spine.js";
+import type { EventBus, StarrEvent } from "../src/types/plugin.js";
+
+function setup() {
+  const logger = createLogger("test", "error");
+  const impl = new EventBusImpl(logger);
+  const bus = impl.pluginBus("test-plugin");
+  return { impl, bus, logger };
+}
+
+// =========================================================================
+// §3 — StarrEvent envelope
+// =========================================================================
+describe("StarrEvent envelope", () => {
+  it("host assigns id, traceId, source, timestamp, schemaVersion", () => {
+    const { bus } = setup();
+    let received: StarrEvent | null = null;
+    bus.on("test.event", (e) => {
+      received = e;
+    });
+    bus.emit("test.event", { hello: "world" });
+
+    expect(received).not.toBeNull();
+    expect(received!.type).toBe("test.event");
+    expect(received!.id).toBeTruthy();
+    expect(received!.traceId).toBeTruthy();
+    expect(received!.source).toBe("test-plugin");
+    expect(received!.timestamp).toBeTruthy();
+    expect(new Date(received!.timestamp).toISOString()).toBe(received!.timestamp);
+    expect(received!.schemaVersion).toBe(1);
+    expect(received!.payload).toEqual({ hello: "world" });
+    expect(received!.correlationId).toBeUndefined();
+  });
+
+  it("events are immutable (Object.freeze)", () => {
+    const { bus } = setup();
+    let received: StarrEvent | null = null;
+    bus.on("test.event", (e) => {
+      received = e;
+    });
+    bus.emit("test.event", {});
+
+    expect(() => {
+      (received as any).type = "hacked";
+    }).toThrow();
+  });
+
+  it("correlationId is passed through when specified in opts", () => {
+    const { bus } = setup();
+    let received: StarrEvent | null = null;
+    bus.on("test.event", (e) => {
+      received = e;
+    });
+    bus.emit("test.event", {}, { correlationId: "my-corr-id" });
+
+    expect(received!.correlationId).toBe("my-corr-id");
+  });
+
+  it("reply() sugar copies correlationId", () => {
+    const { bus } = setup();
+    const replies: StarrEvent[] = [];
+    bus.on("test.request", (e) => {
+      e.reply("test.reply", { answer: 42 });
+    });
+    bus.on("test.reply", (e) => {
+      replies.push(e);
+    });
+
+    bus.emit("test.request", {}, { correlationId: "cid-1" });
+
+    expect(replies.length).toBe(1);
+    expect(replies[0].correlationId).toBe("cid-1");
+    expect(replies[0].payload).toEqual({ answer: 42 });
+  });
+});
+
+// =========================================================================
+// §4 — Delivery semantics
+// =========================================================================
+describe("delivery semantics", () => {
+  it("emit returns immediately; does not await handlers", () => {
+    const { bus } = setup();
+    let called = false;
+    bus.on("test.event", async () => {
+      await new Promise((r) => setTimeout(r, 100));
+      called = true;
+    });
+    bus.emit("test.event", {});
+    expect(called).toBe(false);
+  });
+
+  it("throwing handler is caught and isolated (does not crash emit)", () => {
+    const { bus } = setup();
+    const calls: string[] = [];
+    bus.on("test.event", () => {
+      calls.push("bad");
+      throw new Error("boom");
+    });
+    bus.on("test.event", () => {
+      calls.push("good");
+    });
+
+    expect(() => bus.emit("test.event", {})).not.toThrow();
+    expect(calls).toContain("bad");
+    expect(calls).toContain("good");
+  });
+
+  it("rejecting async handler is caught and isolated", async () => {
+    const { bus } = setup();
+    const calls: string[] = [];
+    bus.on("test.event", async () => {
+      calls.push("bad");
+      throw new Error("async boom");
+    });
+    bus.on("test.event", () => {
+      calls.push("good");
+    });
+
+    bus.emit("test.event", {});
+    await new Promise((r) => setTimeout(r, 10));
+    expect(calls).toContain("bad");
+    expect(calls).toContain("good");
+  });
+
+  it("event with no subscribers is silently dropped (no error)", () => {
+    const { bus } = setup();
+    expect(() => bus.emit("no.subscribers", {})).not.toThrow();
+  });
+});
+
+// =========================================================================
+// §5 — Subscription lifecycle
+// =========================================================================
+describe("subscription lifecycle", () => {
+  it("on() returns an unsubscribe handle", () => {
+    const { bus } = setup();
+    const unsub = bus.on("test.event", () => {});
+    expect(typeof unsub).toBe("function");
+  });
+
+  it("unsubscribe removes the handler", () => {
+    const { bus } = setup();
+    const calls: string[] = [];
+    const unsub = bus.on("test.event", () => calls.push("first"));
+    bus.on("test.event", () => calls.push("second"));
+
+    unsub();
+    bus.emit("test.event", {});
+
+    expect(calls).not.toContain("first");
+    expect(calls).toContain("second");
+  });
+
+  it("multiple handlers for same type all receive the event", () => {
+    const { bus } = setup();
+    const calls: string[] = [];
+    bus.on("test.event", () => calls.push("a"));
+    bus.on("test.event", () => calls.push("b"));
+    bus.on("test.event", () => calls.push("c"));
+    bus.emit("test.event", {});
+    expect(calls).toEqual(["a", "b", "c"]);
+  });
+
+  it("handlers for different types are isolated", () => {
+    const { bus } = setup();
+    let calledA = false;
+    let calledB = false;
+    bus.on("type.a", () => {
+      calledA = true;
+    });
+    bus.on("type.b", () => {
+      calledB = true;
+    });
+    bus.emit("type.a", {});
+    expect(calledA).toBe(true);
+    expect(calledB).toBe(false);
+  });
+});
+
+// =========================================================================
+// §5 PS2–PS3, §7 — Trace context propagation
+// =========================================================================
+describe("trace propagation", () => {
+  it("root emission mints a fresh traceId", () => {
+    const { bus } = setup();
+    const traceIds: string[] = [];
+    bus.on("test.event", (e) => traceIds.push(e.traceId));
+    bus.emit("test.event", {});
+    bus.emit("test.event", {});
+    expect(traceIds.length).toBe(2);
+    expect(traceIds[0]).toBeTruthy();
+    expect(traceIds[1]).toBeTruthy();
+    expect(traceIds[0]).not.toBe(traceIds[1]);
+  });
+
+  it("emit inside a handler inherits the parent traceId", () => {
+    const { bus } = setup();
+    let parentTrace: string | null = null;
+    let childTrace: string | null = null;
+
+    bus.on("parent.event", (e) => {
+      parentTrace = e.traceId;
+      bus.emit("child.event", {});
+    });
+    bus.on("child.event", (e) => {
+      childTrace = e.traceId;
+    });
+
+    bus.emit("parent.event", {});
+
+    expect(parentTrace).toBeTruthy();
+    expect(childTrace).toBe(parentTrace);
+  });
+
+  it("deeply nested emits all share the root traceId", () => {
+    const { bus } = setup();
+    const traces: string[] = [];
+
+    bus.on("level1", (e) => {
+      traces.push(`L1:${e.traceId.slice(0, 8)}`);
+      bus.emit("level2", {});
+    });
+    bus.on("level2", (e) => {
+      traces.push(`L2:${e.traceId.slice(0, 8)}`);
+      bus.emit("level3", {});
+    });
+    bus.on("level3", (e) => {
+      traces.push(`L3:${e.traceId.slice(0, 8)}`);
+    });
+
+    bus.emit("level1", {});
+
+    expect(traces.length).toBe(3);
+    const ids = traces.map((t) => t.split(":")[1]);
+    expect(new Set(ids).size).toBe(1);
+  });
+
+  it("concurrent handlers do not cross-attribute trace IDs", async () => {
+    const { bus } = setup();
+    const results: Array<{ handler: string; emittedTrace: string }> = [];
+
+    bus.on("trigger", async (e) => {
+      await new Promise((r) => setTimeout(r, 20));
+      bus.emit("nested", { from: "A" });
+    });
+
+    bus.on("trigger", async (e) => {
+      await new Promise((r) => setTimeout(r, 10));
+      bus.emit("nested", { from: "B" });
+    });
+
+    bus.on("nested", (e) => {
+      results.push({
+        handler: e.payload.from as string,
+        emittedTrace: e.traceId,
+      });
+    });
+
+    bus.emit("trigger", {});
+    bus.emit("trigger", {});
+
+    await new Promise((r) => setTimeout(r, 150));
+
+    // 2 root emissions × 2 handlers = 4 nested events
+    expect(results.length).toBe(4);
+
+    // They should form 2 groups with distinct trace IDs (one per root emission)
+    const uniqueTraces = new Set(results.map((r) => r.emittedTrace));
+    expect(uniqueTraces.size).toBe(2);
+
+    // Group by trace — each group must contain both A and B (same chain)
+    const byTrace = new Map<string, string[]>();
+    for (const r of results) {
+      const list = byTrace.get(r.emittedTrace) ?? [];
+      list.push(r.handler);
+      byTrace.set(r.emittedTrace, list);
+    }
+    for (const handlers of byTrace.values()) {
+      expect(handlers).toContain("A");
+      expect(handlers).toContain("B");
+    }
+  });
+
+  it("emit from timer (outside handler) starts a new chain", async () => {
+    const { bus } = setup();
+    let rootTrace: string | null = null;
+    let timerTrace: string | null = null;
+
+    bus.on("root.event", (e) => {
+      rootTrace = e.traceId;
+    });
+    bus.on("timer.event", (e) => {
+      timerTrace = e.traceId;
+    });
+
+    bus.emit("root.event", {});
+
+    await new Promise<void>((resolve) => {
+      setTimeout(() => {
+        bus.emit("timer.event", {});
+        resolve();
+      }, 10);
+    });
+
+    expect(rootTrace).toBeTruthy();
+    expect(timerTrace).toBeTruthy();
+    expect(timerTrace).not.toBe(rootTrace);
+  });
+
+  it("traceId is present on every event (TC1)", () => {
+    const { bus } = setup();
+    const traces: string[] = [];
+    bus.on("a", (e) => traces.push(e.traceId));
+    bus.on("b", (e) => traces.push(e.traceId));
+    bus.emit("a", {});
+    bus.emit("b", {});
+    expect(traces.length).toBe(2);
+    traces.forEach((t) => expect(t).toBeTruthy());
+  });
+});
+
+// =========================================================================
+// §9 — Custom event namespacing
+// =========================================================================
+describe("custom event namespacing", () => {
+  it("plugins can emit custom events with <pluginId>:<name> format", () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("starr-tmdb");
+    let received: StarrEvent | null = null;
+    bus.on("starr-tmdb:cache.warmed", (e) => {
+      received = e;
+    });
+    bus.emit("starr-tmdb:cache.warmed", { count: 42 });
+    expect(received).not.toBeNull();
+    expect(received!.source).toBe("starr-tmdb");
+  });
+
+  it("subscribing to another plugin's custom events works", () => {
+    const { impl } = setup();
+    const busA = impl.pluginBus("plugin-a");
+    const busB = impl.pluginBus("plugin-b");
+
+    let received: StarrEvent | null = null;
+    busB.on("plugin-a:something", (e) => {
+      received = e;
+    });
+    busA.emit("plugin-a:something", { x: 1 });
+
+    expect(received).not.toBeNull();
+    expect(received!.source).toBe("plugin-a");
+  });
+});
+
+// =========================================================================
+// §9 CE2–CE3 — Spine namespace enforcement
+// =========================================================================
+describe("spine namespace enforcement", () => {
+  it("isSpineType identifies reserved namespaces", () => {
+    expect(isSpineType("discovery.search")).toBe(true);
+    expect(isSpineType("content.requested")).toBe(true);
+    expect(isSpineType("release.found")).toBe(true);
+    expect(isSpineType("download.started")).toBe(true);
+    expect(isSpineType("item.updated")).toBe(true);
+    expect(isSpineType("import.started")).toBe(true);
+    expect(isSpineType("import.completed")).toBe(true);
+    expect(isSpineType("import.failed")).toBe(true);
+    expect(isSpineType("library.file_added")).toBe(true);
+    expect(isSpineType("starr-tmdb:cache.warmed")).toBe(false);
+    expect(isSpineType("custom.event")).toBe(false);
+  });
+
+  it("validateSpineEmission returns message for unknown spine type", () => {
+    const msg = validateSpineEmission("some-plugin", "discovery.unknown");
+    expect(msg).toBeTruthy();
+  });
+
+  it("validateSpineEmission returns null for non-spine custom events", () => {
+    const msg = validateSpineEmission("any-plugin", "starr-any:custom");
+    expect(msg).toBeNull();
+  });
+
+  it("validateSpineEmission warns when non-core source emits core-only event", () => {
+    const msg = validateSpineEmission("some-plugin", "discovery.search");
+    expect(msg).toBeTruthy();
+    expect(msg).toContain("reserved for core");
+  });
+
+  it("core can emit core-reserved events", () => {
+    const msg = validateSpineEmission("core", "discovery.search");
+    expect(msg).toBeNull();
+  });
+
+  it("emit logs warning when spine violation is detected", () => {
+    const { bus } = setup();
+    bus.on("discovery.search", () => {});
+    expect(() => bus.emit("discovery.search", {})).not.toThrow();
+  });
+
+  it("import events are recognized as spine events (core producer)", () => {
+    const msg = validateSpineEmission("core", "import.started");
+    expect(msg).toBeNull();
+
+    const msg2 = validateSpineEmission("core", "import.completed");
+    expect(msg2).toBeNull();
+
+    const msg3 = validateSpineEmission("core", "import.failed");
+    expect(msg3).toBeNull();
+
+    const msg4 = validateSpineEmission("core", "library.file_added");
+    expect(msg4).toBeNull();
+  });
+
+  it("non-core source emitting import events is warned", () => {
+    const msg = validateSpineEmission("some-plugin", "import.started");
+    expect(msg).toBeTruthy();
+    expect(msg).toContain("reserved for core");
+
+    const msg2 = validateSpineEmission("some-plugin", "library.file_added");
+    expect(msg2).toBeTruthy();
+    expect(msg2).toContain("reserved for core");
+  });
+});
+
+// =========================================================================
+// §8 — Spine schemaVersion
+// =========================================================================
+describe("spine schemaVersion", () => {
+  it("spine events carry correct schemaVersion", () => {
+    const { impl } = setup();
+    const coreBus = impl.coreBus();
+    let received: StarrEvent | null = null;
+    coreBus.on("discovery.search", (e) => {
+      received = e;
+    });
+    coreBus.emit("discovery.search", { query: "test", contentTypeIds: [] });
+    expect(received!.schemaVersion).toBe(1);
+  });
+
+  it("custom events get default schemaVersion 1", () => {
+    const { bus } = setup();
+    let received: StarrEvent | null = null;
+    bus.on("starr-tmdb:cache.warmed", (e) => {
+      received = e;
+    });
+    bus.emit("starr-tmdb:cache.warmed", {});
+    expect(received!.schemaVersion).toBe(1);
+  });
+});
+
+// =========================================================================
+// §6.1 — request/response (caller-gathers)
+// =========================================================================
+describe("request/response (caller-gathers)", () => {
+  it("collects responses within windowMs", async () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("test-plugin");
+
+    impl.pluginBus("service").on("discovery.search", (e) => {
+      e.reply("discovery.results", { items: ["a", "b"] });
+    });
+
+    const replies = await bus.request("discovery.search", { query: "test" }, {
+      responseType: "discovery.results",
+      windowMs: 500,
+    });
+
+    expect(replies.length).toBe(1);
+    expect(replies[0].payload).toEqual({ items: ["a", "b"] });
+    expect(replies[0].correlationId).toBeTruthy();
+  });
+
+  it("respects max replies", async () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("test-plugin");
+
+    impl.pluginBus("svc1").on("discovery.search", (e) => {
+      e.reply("discovery.results", { items: ["a"] });
+    });
+    impl.pluginBus("svc2").on("discovery.search", (e) => {
+      e.reply("discovery.results", { items: ["b"] });
+    });
+
+    const replies = await bus.request("discovery.search", {}, {
+      responseType: "discovery.results",
+      windowMs: 500,
+      max: 1,
+    });
+
+    expect(replies.length).toBe(1);
+  });
+
+  it("resolves with empty array if no replies arrive", async () => {
+    const { bus } = setup();
+
+    const replies = await bus.request("no.responders", {}, {
+      responseType: "no.response",
+      windowMs: 50,
+    });
+
+    expect(replies).toEqual([]);
+  });
+
+  it("late replies after windowMs are dropped", async () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("test-plugin");
+
+    impl.pluginBus("slow-svc").on("discovery.search", async (e) => {
+      await new Promise((r) => setTimeout(r, 200));
+      e.reply("discovery.results", { items: ["late"] });
+    });
+
+    const replies = await bus.request("discovery.search", {}, {
+      responseType: "discovery.results",
+      windowMs: 50,
+    });
+
+    expect(replies).toEqual([]);
+  });
+
+  it("each request gets a unique correlationId", async () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("test-plugin");
+    const ids = new Set<string>();
+
+    impl.pluginBus("svc").on("test.req", (e) => {
+      ids.add(e.correlationId!);
+      e.reply("test.res", {});
+    });
+
+    await bus.request("test.req", {}, { responseType: "test.res", windowMs: 100 });
+    await bus.request("test.req", {}, { responseType: "test.res", windowMs: 100 });
+
+    expect(ids.size).toBe(2);
+  });
+
+  it("request emissions start a new chain when called outside handler", async () => {
+    const { bus } = setup();
+    let requestTrace: string | null = null;
+
+    bus.on("test.req", (e) => {
+      requestTrace = e.traceId;
+    });
+
+    await bus.request("test.req", {}, { responseType: "test.res", windowMs: 50 });
+
+    expect(requestTrace).toBeTruthy();
+  });
+
+  it("request inside a handler inherits parent traceId", async () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("test-plugin");
+    let parentTrace: string | null = null;
+    let requestTrace: string | null = null;
+
+    bus.on("parent", (e) => {
+      parentTrace = e.traceId;
+    });
+
+    bus.on("test.req", (e) => {
+      requestTrace = e.traceId;
+    });
+
+    impl.pluginBus("svc").on("test.req", (e) => {
+      e.reply("test.res", {});
+    });
+
+    bus.on("parent", () => {
+      bus.request("test.req", {}, { responseType: "test.res", windowMs: 100 });
+    });
+
+    bus.emit("parent", {});
+
+    await new Promise((r) => setTimeout(r, 200));
+
+    expect(parentTrace).toBeTruthy();
+    // The test.req handler is inside the parent handler so trace is inherited
+    expect(requestTrace).toBe(parentTrace);
+  });
+});
+
+// =========================================================================
+// Integration: plugin workflow
+// =========================================================================
+describe("integration: plugin workflow", () => {
+  it("two plugin buses coordinate via events", async () => {
+    const { impl } = setup();
+    const tmdb = impl.pluginBus("starr-tmdb");
+    const indexer = impl.pluginBus("starr-torrent-indexer");
+    const ui = impl.coreBus();
+
+    const log: string[] = [];
+
+    tmdb.on("discovery.search", (e) => {
+      log.push(`tmdb: search for "${e.payload.query}"`);
+      e.reply("discovery.results", {
+        contentTypeId: "starr-video/movie@1",
+        items: [{ id: "tt123", title: "Dune" }],
+      });
+    });
+
+    indexer.on("content.requested", (e) => {
+      log.push(`indexer: find releases for ${e.payload.item.id}`);
+      e.reply("release.found", {
+        requestId: e.payload.requestId,
+        contentTypeId: e.payload.contentTypeId,
+        release: { title: "Dune 2021 1080p", quality: "1080p" },
+      });
+    });
+
+    const results = await ui.request("discovery.search", {
+      query: "dune",
+      contentTypeIds: ["starr-video/movie@1"],
+    }, { responseType: "discovery.results", windowMs: 500 });
+
+    expect(results.length).toBe(1);
+    expect(log).toContain('tmdb: search for "dune"');
+
+    const releases = await ui.request("content.requested", {
+      requestId: "req-001",
+      contentTypeId: "starr-video/movie@1",
+      item: { id: "tt123", title: "Dune" },
+    }, { responseType: "release.found", windowMs: 500 });
+
+    expect(releases.length).toBe(1);
+    expect(log).toContain("indexer: find releases for tt123");
+  });
+});
+
+// =========================================================================
+// request() input validation
+// =========================================================================
+describe("request input validation", () => {
+  it("throws if responseType is empty", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, { responseType: "", windowMs: 100 }),
+    ).toThrow("responseType");
+  });
+
+  it("throws if responseType is whitespace only", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, { responseType: "   ", windowMs: 100 }),
+    ).toThrow("responseType");
+  });
+
+  it("throws if windowMs is zero", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, { responseType: "test.res", windowMs: 0 }),
+    ).toThrow("windowMs");
+  });
+
+  it("throws if windowMs is negative", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, { responseType: "test.res", windowMs: -100 }),
+    ).toThrow("windowMs");
+  });
+
+  it("throws if windowMs is NaN", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, { responseType: "test.res", windowMs: NaN }),
+    ).toThrow("windowMs");
+  });
+
+  it("throws if max is zero", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, {
+        responseType: "test.res",
+        windowMs: 100,
+        max: 0,
+      }),
+    ).toThrow("max");
+  });
+
+  it("throws if max is negative", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, {
+        responseType: "test.res",
+        windowMs: 100,
+        max: -1,
+      }),
+    ).toThrow("max");
+  });
+
+  it("throws if max is not an integer", () => {
+    const { bus } = setup();
+    expect(() =>
+      bus.request("test.req", {}, {
+        responseType: "test.res",
+        windowMs: 100,
+        max: 1.5,
+      }),
+    ).toThrow("max");
+  });
+});
+
+// =========================================================================
+// §6.1 — Multiple concurrent requests within one trace
+// =========================================================================
+describe("concurrent requests", () => {
+  it("multiple concurrent requests within one trace have distinct correlationIds and don't cross-contaminate", async () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("test-plugin");
+
+    // Track which request each reply belongs to
+    const repliesA: unknown[] = [];
+    const repliesB: unknown[] = [];
+    const traceIds: string[] = [];
+
+    // Service that replies to both request types
+    impl.pluginBus("svc").on("req.a", (e) => {
+      e.reply("res.a", { from: "A" });
+    });
+    impl.pluginBus("svc").on("req.b", (e) => {
+      e.reply("res.b", { from: "B" });
+    });
+
+    // Capture trace IDs
+    bus.on("req.a", (e) => { traceIds.push(e.traceId!); });
+    bus.on("req.b", (e) => { traceIds.push(e.traceId!); });
+
+    // Fire two requests from within a single handler (same trace)
+    // Use max:1 so each promise resolves on first reply, not waiting for windowMs
+    bus.on("trigger", () => {
+      bus.request("req.a", {}, { responseType: "res.a", windowMs: 500, max: 1 })
+        .then((r) => { repliesA.push(...r.map(e => e.payload)); });
+      bus.request("req.b", {}, { responseType: "res.b", windowMs: 500, max: 1 })
+        .then((r) => { repliesB.push(...r.map(e => e.payload)); });
+    });
+
+    bus.emit("trigger", {});
+
+    // Wait for both requests to settle
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Each request got exactly its own reply type
+    expect(repliesA).toEqual([{ from: "A" }]);
+    expect(repliesB).toEqual([{ from: "B" }]);
+
+    // Both requests share the same traceId (same chain)
+    expect(traceIds.length).toBe(2);
+    expect(traceIds[0]).toBe(traceIds[1]);
+  });
+});
+
+// =========================================================================
+// §7 TC1a — correlationId: only on request rounds, not plain emit
+// =========================================================================
+describe("correlationId (TC1a)", () => {
+  it("plain emit never sets correlationId (TC1a)", () => {
+    const { bus } = setup();
+    let received: StarrEvent | null = null;
+    bus.on("plain.event", (e) => { received = e; });
+
+    // Plain emit — no opts
+    bus.emit("plain.event", { x: 1 });
+    expect(received!.correlationId).toBeUndefined();
+
+    // Another plain emit to be sure
+    let received2: StarrEvent | null = null;
+    bus.on("plain.event2", (e) => { received2 = e; });
+    bus.emit("plain.event2", { x: 2 });
+    expect(received2!.correlationId).toBeUndefined();
+  });
+
+  it("request round events carry correlationId", async () => {
+    const { impl } = setup();
+    const bus = impl.pluginBus("test-plugin");
+
+    let reqCorrelationId: string | undefined;
+    let resCorrelationId: string | undefined;
+
+    bus.on("test.req", (e) => { reqCorrelationId = e.correlationId; });
+
+    impl.pluginBus("svc").on("test.req", (e) => {
+      e.reply("test.res", { ok: true });
+    });
+
+    // Subscribe to response type to capture its correlationId
+    let resEvent: StarrEvent | null = null;
+    impl.pluginBus("svc").on("test.res", (e) => { resEvent = e; });
+
+    // Manually trigger what request() does to verify correlationId on both sides
+    // We use request() since it's the only way correlationId is minted
+    await bus.request("test.req", {}, { responseType: "test.res", windowMs: 200 });
+
+    // Both request and reply carry the same correlationId
+    expect(reqCorrelationId).toBeTruthy();
+    expect(resEvent?.correlationId).toBe(reqCorrelationId);
+  });
+});
+
+// =========================================================================
+// §6.2 — Third-party gathering (subscription + traceId grouping)
+// =========================================================================
+describe("third-party gathering by traceId", () => {
+  it("events in the same chain share the same traceId", () => {
+    // Verify the fundamental property: all events emitted (directly or
+    // indirectly) from a single root emission carry the same traceId.
+    const { bus } = setup();
+    const traceIds: string[] = [];
+
+    bus.on("step1", (e) => {
+      traceIds.push(`step1:${e.traceId}`);
+      bus.emit("step2", {});
+    });
+    bus.on("step2", (e) => {
+      traceIds.push(`step2:${e.traceId}`);
+      bus.emit("step3", {});
+    });
+    bus.on("step3", (e) => {
+      traceIds.push(`step3:${e.traceId}`);
+    });
+
+    bus.emit("step1", {}); // root emission → new trace
+
+    expect(traceIds.length).toBe(3);
+    // All three share the same trace UUID
+    const ids = traceIds.map((s) => s.split(":")[1]);
+    expect(new Set(ids).size).toBe(1);
+  });
+
+  it("a subscriber can group events by traceId", () => {
+    // Simulate the selection plugin pattern: subscribe to release.found
+    // and group by traceId. The plugin would then apply its own window
+    // and quorum policy.
+    const { impl } = setup();
+    const indexerA = impl.pluginBus("starr-torrent-indexer-a");
+    const indexerB = impl.pluginBus("starr-torrent-indexer-b");
+    const selector = impl.pluginBus("starr-basic-selection");
+
+    const grouped = new Map<string, unknown[]>();
+
+    // The "selection plugin" subscribes to release.found and groups by traceId
+    selector.on("release.found", (e) => {
+      const list = grouped.get(e.traceId) ?? [];
+      list.push(e.payload);
+      grouped.set(e.traceId, list);
+    });
+
+    // Simulate: core emits content.requested (starts a chain)
+    const coreBus = impl.coreBus();
+    let chainTraceId: string | null = null;
+
+    coreBus.on("content.requested", (e) => {
+      chainTraceId = e.traceId;
+    });
+
+    // Indexers listen for content.requested and emit release.found replies.
+    // They use emit() (not request()) and the traceId is inherited from the
+    // content.requested event's chain via AsyncLocalStorage.
+    coreBus.on("content.requested", (e) => {
+      // Indexer A responds
+      indexerA.emit("release.found", {
+        requestId: "req-1",
+        release: { title: "Dune 1080p", indexer: "A" },
+      });
+      // Indexer B responds
+      indexerB.emit("release.found", {
+        requestId: "req-1",
+        release: { title: "Dune 4K", indexer: "B" },
+      });
+    });
+
+    // Fire the request
+    coreBus.emit("content.requested", {
+      requestId: "req-1",
+      contentTypeId: "starr-video/movie@1",
+      item: { title: "Dune" },
+    });
+
+    // Verify: all release.found events were grouped by the same traceId
+    expect(chainTraceId).toBeTruthy();
+    expect(grouped.size).toBe(1);
+
+    const releases = grouped.get(chainTraceId!)!;
+    expect(releases.length).toBe(2);
+  });
+
+  it("separate chains produce separate traceId groups", () => {
+    const { impl } = setup();
+    const coreBus = impl.coreBus();
+    const selector = impl.pluginBus("starr-basic-selection");
+
+    const byTrace = new Map<string, number>();
+
+    selector.on("release.found", (e) => {
+      const count = byTrace.get(e.traceId) ?? 0;
+      byTrace.set(e.traceId, count + 1);
+    });
+
+    // Simulate: for each content.requested, an indexer emits one release.found
+    coreBus.on("content.requested", (e) => {
+      impl.pluginBus("indexer").emit("release.found", {
+        requestId: e.payload.requestId,
+        release: { title: "Test" },
+      });
+    });
+
+    // Two separate user requests → two separate chains
+    coreBus.emit("content.requested", { requestId: "req-1", item: { title: "A" } });
+    coreBus.emit("content.requested", { requestId: "req-2", item: { title: "B" } });
+
+    // Two distinct traceIds, each with one release.found
+    expect(byTrace.size).toBe(2);
+    for (const count of byTrace.values()) {
+      expect(count).toBe(1);
+    }
+  });
+});