@reventlessdev/reventless-local 3.0.0-alpha.113

package/tests/adapter/EventCollectorChannelTest.res

@@ -0,0 +1,166 @@
+// Unit tests for LocalEventCollectorChannel.
+// Verifies resource collection in make() and subscriber wiring in connect().
+
+open JestGlobals
+
+let _ = TestRunner.setup()
+
+let testMeta: Reventless.Message.meta = {
+  service: "test",
+  time: "",
+  ip: "",
+  user: "test",
+  msgId: "",
+  correlationId: "",
+}
+
+// ─────────────────────────────────────────────────────────────
+// Helper: build a minimal runtime with a completed handler Deferred
+// ─────────────────────────────────────────────────────────────
+
+let makeRuntime = (
+  handler: LocalRuntimeEnvironment.handler,
+): ReventlessCore.Runtime.environment<LocalRuntimeEnvironment.parts> => {
+  let handlerDeferred: Deferred.t<LocalRuntimeEnvironment.handler, unit> =
+    Deferred.make()->Effect.runSync
+  Deferred.succeed(handlerDeferred, handler)->Effect.runSync->ignore
+  {
+    parts: {
+      handlerDeferred,
+      subscriptionLatch: Effect.makeLatch(false)->Effect.runSync,
+    },
+    resources: [],
+  }
+}
+
+describe("LocalEventCollectorChannel", () => {
+  describe("make", () => {
+    testPromise("collects all event topic resources as channel resources", async () => {
+      module TestBus = LocalBus.Make()
+      module TestPublisher = LocalEventTopicPublisher.Make(TestBus)
+      module TestCollector = LocalEventCollectorChannel.Make(TestBus)
+      let pubA = TestPublisher.make(~name="topicA", ~storageResources=[], ~opts={})
+      let pubB = TestPublisher.make(~name="topicB", ~storageResources=[], ~opts={})
+      let eventTopics = Dict.fromArray([
+        ("topicA", {ReventlessInfra.EventTopic.resources: pubA.resources}),
+        ("topicB", {ReventlessInfra.EventTopic.resources: pubB.resources}),
+      ])
+      let ch = TestCollector.make(~name="collector", ~eventTopics, ~opts={})
+      // Each publisher returns 1 resource, so 2 total
+      expect(ch.resources->Array.length)->toBe(2)
+    })
+
+    testPromise("empty eventTopics produces empty resources", async () => {
+      module TestBus = LocalBus.Make()
+      module TestCollector = LocalEventCollectorChannel.Make(TestBus)
+      let ch = TestCollector.make(~name="collector", ~eventTopics=Dict.make(), ~opts={})
+      expect(ch.resources->Array.length)->toBe(0)
+    })
+  })
+
+  describe("connect", () => {
+    testPromise("subscribes to event topic; published events reach the handler", async () => {
+      module TestBus = LocalBus.Make()
+      module TestPublisher = LocalEventTopicPublisher.Make(TestBus)
+      module TestCollector = LocalEventCollectorChannel.Make(TestBus)
+      let received: ref<int> = ref(0)
+      let runtime = makeRuntime(async (_, _ctx) => {
+        received := received.contents + 1
+      })
+      let pub = TestPublisher.make(~name="eventA", ~storageResources=[], ~opts={})
+      let eventTopics = Dict.fromArray([
+        ("eventA", {ReventlessInfra.EventTopic.resources: pub.resources}),
+      ])
+      let ch = TestCollector.make(~name="collector", ~eventTopics, ~opts={})
+      let channelSpec: ReventlessCore.EventCollector_Adapter.channelSpec<JSON.t, unit, unit> = {
+        channel: ch,
+        eventTopics,
+        resources: [],
+      }
+      let _ = TestCollector.connect(
+        ~name="collector",
+        ~channelSpecs=[channelSpec],
+        ~runtime,
+        ~opts={},
+      )
+      // Await the subscriptionLatch — opens after Output.apply fires and subscription registers
+      await runtime.parts.subscriptionLatch->Latch.await_->Effect.runPromise
+      let publishFn = await pub.publishJson->TestRunner.resolve
+      await publishFn("svc", testMeta, JSON.Null)
+      expect(received.contents)->toBe(1)
+    })
+
+    testPromise("multiple event topics all deliver to the same handler", async () => {
+      module TestBus = LocalBus.Make()
+      module TestPublisher = LocalEventTopicPublisher.Make(TestBus)
+      module TestCollector = LocalEventCollectorChannel.Make(TestBus)
+      let received: ref<int> = ref(0)
+      let runtime = makeRuntime(async (_, _) => {
+        received := received.contents + 1
+      })
+      let pub1 = TestPublisher.make(~name="topicX", ~storageResources=[], ~opts={})
+      let pub2 = TestPublisher.make(~name="topicY", ~storageResources=[], ~opts={})
+      let eventTopics = Dict.fromArray([
+        ("topicX", {ReventlessInfra.EventTopic.resources: pub1.resources}),
+        ("topicY", {ReventlessInfra.EventTopic.resources: pub2.resources}),
+      ])
+      let ch = TestCollector.make(~name="collector", ~eventTopics, ~opts={})
+      let channelSpec: ReventlessCore.EventCollector_Adapter.channelSpec<JSON.t, unit, unit> = {
+        channel: ch,
+        eventTopics,
+        resources: [],
+      }
+      let _ = TestCollector.connect(
+        ~name="collector",
+        ~channelSpecs=[channelSpec],
+        ~runtime,
+        ~opts={},
+      )
+      // Wait for both subscriptions via the publish functions (each Output resolves per-topic)
+      let pub1Fn = await pub1.publishJson->TestRunner.resolve
+      let pub2Fn = await pub2.publishJson->TestRunner.resolve
+      await pub1Fn("svc", testMeta, JSON.Null)
+      await pub2Fn("svc", testMeta, JSON.Null)
+      expect(received.contents)->toBe(2)
+    })
+
+    testPromise("unresolved Deferred does not crash on event delivery", async () => {
+      module TestBus = LocalBus.Make()
+      module TestPublisher = LocalEventTopicPublisher.Make(TestBus)
+      module TestCollector = LocalEventCollectorChannel.Make(TestBus)
+      // Deferred left incomplete — bus callback starts a pending Effect (no crash)
+      let handlerDeferred: Deferred.t<LocalRuntimeEnvironment.handler, unit> =
+        Deferred.make()->Effect.runSync
+      let runtime: ReventlessCore.Runtime.environment<LocalRuntimeEnvironment.parts> = {
+        parts: {
+          handlerDeferred,
+          subscriptionLatch: Effect.makeLatch(false)->Effect.runSync,
+        },
+        resources: [],
+      }
+      let pub = TestPublisher.make(~name="noHandlerTopic", ~storageResources=[], ~opts={})
+      let eventTopics = Dict.fromArray([
+        ("noHandlerTopic", {ReventlessInfra.EventTopic.resources: pub.resources}),
+      ])
+      let ch = TestCollector.make(~name="collector", ~eventTopics, ~opts={})
+      let channelSpec: ReventlessCore.EventCollector_Adapter.channelSpec<JSON.t, unit, unit> = {
+        channel: ch,
+        eventTopics,
+        resources: [],
+      }
+      let _ = TestCollector.connect(
+        ~name="collector",
+        ~channelSpecs=[channelSpec],
+        ~runtime,
+        ~opts={},
+      )
+      await runtime.parts.subscriptionLatch->Latch.await_->Effect.runPromise
+      let publishFn = await pub.publishJson->TestRunner.resolve
+      // Fire-and-forget — the Deferred.await_ will stay pending
+      publishFn("svc", testMeta, JSON.Null)->ignore
+      expect(true)->toBe(true)
+      // Complete the Deferred to avoid open handle
+      Deferred.succeed(handlerDeferred, async (_, _) => ())->Effect.runSync->ignore
+    })
+  })
+})

package/tests/adapter/EventCollectorChannelTest.res.mjs

@@ -0,0 +1,178 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as LocalBus$ReventlessLocal from "../../src/adapter/LocalBus.res.mjs";
+import * as TestRunner$ReventlessLocal from "../../src/test/TestRunner.res.mjs";
+import * as LocalEventTopicPublisher$ReventlessLocal from "../../src/adapter/EventTopic/LocalEventTopicPublisher.res.mjs";
+import * as LocalEventCollectorChannel$ReventlessLocal from "../../src/adapter/EventCollector/LocalEventCollectorChannel.res.mjs";
+
+TestRunner$ReventlessLocal.setup();
+
+let testMeta = {
+  service: "test",
+  time: "",
+  ip: "",
+  user: "test",
+  msgId: "",
+  correlationId: ""
+};
+
+function makeRuntime(handler) {
+  let handlerDeferred = Effect.runSync(Deferred.make());
+  Effect.runSync(Deferred.succeed(handlerDeferred, handler));
+  return {
+    parts: {
+      handlerDeferred: handlerDeferred,
+      subscriptionLatch: Effect.runSync(Effect.makeLatch(false))
+    },
+    resources: []
+  };
+}
+
+globalThis.describe("LocalEventCollectorChannel", () => {
+  globalThis.describe("make", () => {
+    globalThis.test("collects all event topic resources as channel resources", async () => {
+      let TestBus = LocalBus$ReventlessLocal.Make({});
+      let TestPublisher = LocalEventTopicPublisher$ReventlessLocal.Make(TestBus);
+      let TestCollector = LocalEventCollectorChannel$ReventlessLocal.Make(TestBus);
+      let pubA = TestPublisher.make("topicA", [], {});
+      let pubB = TestPublisher.make("topicB", [], {});
+      let eventTopics = Object.fromEntries([
+        [
+          "topicA",
+          {
+            resources: pubA.resources
+          }
+        ],
+        [
+          "topicB",
+          {
+            resources: pubB.resources
+          }
+        ]
+      ]);
+      let ch = TestCollector.make("collector", eventTopics, {});
+      globalThis.expect(ch.resources.length).toBe(2);
+    });
+    globalThis.test("empty eventTopics produces empty resources", async () => {
+      let TestBus = LocalBus$ReventlessLocal.Make({});
+      let TestCollector = LocalEventCollectorChannel$ReventlessLocal.Make(TestBus);
+      let ch = TestCollector.make("collector", {}, {});
+      globalThis.expect(ch.resources.length).toBe(0);
+    });
+  });
+  globalThis.describe("connect", () => {
+    globalThis.test("subscribes to event topic; published events reach the handler", async () => {
+      let TestBus = LocalBus$ReventlessLocal.Make({});
+      let TestPublisher = LocalEventTopicPublisher$ReventlessLocal.Make(TestBus);
+      let TestCollector = LocalEventCollectorChannel$ReventlessLocal.Make(TestBus);
+      let received = {
+        contents: 0
+      };
+      let runtime = makeRuntime(async (param, _ctx) => {
+        received.contents = received.contents + 1 | 0;
+      });
+      let pub = TestPublisher.make("eventA", [], {});
+      let eventTopics = Object.fromEntries([[
+          "eventA",
+          {
+            resources: pub.resources
+          }
+        ]]);
+      let ch = TestCollector.make("collector", eventTopics, {});
+      let channelSpec_resources = [];
+      let channelSpec = {
+        channel: ch,
+        eventTopics: eventTopics,
+        resources: channelSpec_resources
+      };
+      TestCollector.connect("collector", [channelSpec], runtime, {});
+      await Effect.runPromise(runtime.parts.subscriptionLatch.await);
+      let publishFn = await TestRunner$ReventlessLocal.resolve(pub.publishJson);
+      await publishFn("svc", testMeta, null);
+      globalThis.expect(received.contents).toBe(1);
+    });
+    globalThis.test("multiple event topics all deliver to the same handler", async () => {
+      let TestBus = LocalBus$ReventlessLocal.Make({});
+      let TestPublisher = LocalEventTopicPublisher$ReventlessLocal.Make(TestBus);
+      let TestCollector = LocalEventCollectorChannel$ReventlessLocal.Make(TestBus);
+      let received = {
+        contents: 0
+      };
+      let runtime = makeRuntime(async (param, param$1) => {
+        received.contents = received.contents + 1 | 0;
+      });
+      let pub1 = TestPublisher.make("topicX", [], {});
+      let pub2 = TestPublisher.make("topicY", [], {});
+      let eventTopics = Object.fromEntries([
+        [
+          "topicX",
+          {
+            resources: pub1.resources
+          }
+        ],
+        [
+          "topicY",
+          {
+            resources: pub2.resources
+          }
+        ]
+      ]);
+      let ch = TestCollector.make("collector", eventTopics, {});
+      let channelSpec_resources = [];
+      let channelSpec = {
+        channel: ch,
+        eventTopics: eventTopics,
+        resources: channelSpec_resources
+      };
+      TestCollector.connect("collector", [channelSpec], runtime, {});
+      let pub1Fn = await TestRunner$ReventlessLocal.resolve(pub1.publishJson);
+      let pub2Fn = await TestRunner$ReventlessLocal.resolve(pub2.publishJson);
+      await pub1Fn("svc", testMeta, null);
+      await pub2Fn("svc", testMeta, null);
+      globalThis.expect(received.contents).toBe(2);
+    });
+    globalThis.test("unresolved Deferred does not crash on event delivery", async () => {
+      let TestBus = LocalBus$ReventlessLocal.Make({});
+      let TestPublisher = LocalEventTopicPublisher$ReventlessLocal.Make(TestBus);
+      let TestCollector = LocalEventCollectorChannel$ReventlessLocal.Make(TestBus);
+      let handlerDeferred = Effect.runSync(Deferred.make());
+      let runtime_parts = {
+        handlerDeferred: handlerDeferred,
+        subscriptionLatch: Effect.runSync(Effect.makeLatch(false))
+      };
+      let runtime_resources = [];
+      let runtime = {
+        parts: runtime_parts,
+        resources: runtime_resources
+      };
+      let pub = TestPublisher.make("noHandlerTopic", [], {});
+      let eventTopics = Object.fromEntries([[
+          "noHandlerTopic",
+          {
+            resources: pub.resources
+          }
+        ]]);
+      let ch = TestCollector.make("collector", eventTopics, {});
+      let channelSpec_resources = [];
+      let channelSpec = {
+        channel: ch,
+        eventTopics: eventTopics,
+        resources: channelSpec_resources
+      };
+      TestCollector.connect("collector", [channelSpec], runtime, {});
+      await Effect.runPromise(runtime_parts.subscriptionLatch.await);
+      let publishFn = await TestRunner$ReventlessLocal.resolve(pub.publishJson);
+      publishFn("svc", testMeta, null);
+      globalThis.expect(true).toBe(true);
+      Effect.runSync(Deferred.succeed(handlerDeferred, async (param, param$1) => {}));
+    });
+  });
+});
+
+export {
+  testMeta,
+  makeRuntime,
+}
+/*  Not a pure module */

package/tests/adapter/EventLogStorageSqliteTest.res

@@ -0,0 +1,105 @@
+// Round-trip test for EventLogStorage_Sqlite.
+// Mirrors the shape of the Memory variant but uses an in-memory SQLite database.
+
+open JestGlobals
+
+let _ = TestRunner.setup()
+let opts: Pulumi.CustomResourceOptions.t = {}
+
+let makeFreshDb = () => SqliteDriver.openDb(~path=":memory:")
+
+describe("EventLogStorage_Sqlite", () => {
+  testPromise("append + replay round-trips events in order", async () => {
+    module TestBus = LocalBus.Make()
+    module DbProvider = {
+      let db = makeFreshDb()
+    }
+    module Storage = EventLogStorage_Sqlite.Make(TestBus, DbProvider)
+
+    let s = Storage.make(~name="agg", ~opts)
+    let ops = await s.operations->TestRunner.resolve
+
+    let event1 = JSON.Encode.object(
+      Dict.fromArray([("tag", JSON.Encode.string("Created"))]),
+    )
+    let event2 = JSON.Encode.object(
+      Dict.fromArray([("tag", JSON.Encode.string("Renamed"))]),
+    )
+
+    let r1 = await ops.append(0, "id-1", [event1])
+    expect(r1)->toEqual(Ok())
+
+    let r2 = await ops.append(1, "id-1", [event2])
+    expect(r2)->toEqual(Ok())
+
+    let replayed = await ops.replay("id-1")
+    expect(replayed->Array.length)->toBe(2)
+    expect(replayed->Array.getUnsafe(0))->toEqual(event1)
+    expect(replayed->Array.getUnsafe(1))->toEqual(event2)
+  })
+
+  testPromise("append detects concurrency conflicts via PK collision", async () => {
+    module TestBus = LocalBus.Make()
+    module DbProvider = {
+      let db = makeFreshDb()
+    }
+    module Storage = EventLogStorage_Sqlite.Make(TestBus, DbProvider)
+
+    let s = Storage.make(~name="agg", ~opts)
+    let ops = await s.operations->TestRunner.resolve
+
+    let e = JSON.Encode.object(Dict.fromArray([("t", JSON.Encode.string("X"))]))
+    let _ = await ops.append(0, "id-c", [e])
+
+    // Caller re-uses seqNr=0 — conflict.
+    let result = await ops.append(0, "id-c", [e])
+    switch result {
+    | Error(_) => expect(true)->toBe(true)
+    | Ok() => expect("expected conflict")->toBe("actual Ok")
+    }
+  })
+
+  testPromise("replay returns empty array for unknown id", async () => {
+    module TestBus = LocalBus.Make()
+    module DbProvider = {
+      let db = makeFreshDb()
+    }
+    module Storage = EventLogStorage_Sqlite.Make(TestBus, DbProvider)
+
+    let s = Storage.make(~name="agg", ~opts)
+    let ops = await s.operations->TestRunner.resolve
+
+    let replayed = await ops.replay("not-there")
+    expect(replayed->Array.length)->toBe(0)
+  })
+
+  testPromise("events persist across a reopen of the database file", async () => {
+    let path = `/tmp/reventless-test-eventlog-${Float.toString(Date.now())}.db`
+
+    // Session 1: write
+    {
+      module TestBus = LocalBus.Make()
+      module DbProvider = {
+        let db = SqliteDriver.openDb(~path)
+      }
+      module Storage = EventLogStorage_Sqlite.Make(TestBus, DbProvider)
+      let s = Storage.make(~name="persist", ~opts)
+      let ops = await s.operations->TestRunner.resolve
+      let ev = JSON.Encode.object(Dict.fromArray([("v", JSON.Encode.int(42))]))
+      let _ = await ops.append(0, "id-p", [ev])
+      DbProvider.db->SqliteDriver.close
+    }
+
+    // Session 2: read back
+    module TestBus2 = LocalBus.Make()
+    module DbProvider2 = {
+      let db = SqliteDriver.openDb(~path)
+    }
+    module Storage2 = EventLogStorage_Sqlite.Make(TestBus2, DbProvider2)
+    let s2 = Storage2.make(~name="persist", ~opts)
+    let ops2 = await s2.operations->TestRunner.resolve
+    let replayed = await ops2.replay("id-p")
+    expect(replayed->Array.length)->toBe(1)
+    DbProvider2.db->SqliteDriver.close
+  })
+})

package/tests/adapter/EventLogStorageSqliteTest.res.mjs

@@ -0,0 +1,116 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as LocalBus$ReventlessLocal from "../../src/adapter/LocalBus.res.mjs";
+import * as TestRunner$ReventlessLocal from "../../src/test/TestRunner.res.mjs";
+import * as SqliteDriver$ReventlessLocal from "../../src/adapter/SqliteDriver.res.mjs";
+import * as EventLogStorage_Sqlite$ReventlessLocal from "../../src/adapter/EventLog/EventLogStorage_Sqlite.res.mjs";
+
+TestRunner$ReventlessLocal.setup();
+
+let opts = {};
+
+function makeFreshDb() {
+  return SqliteDriver$ReventlessLocal.openDb(":memory:");
+}
+
+globalThis.describe("EventLogStorage_Sqlite", () => {
+  globalThis.test("append + replay round-trips events in order", async () => {
+    let TestBus = LocalBus$ReventlessLocal.Make({});
+    let db = SqliteDriver$ReventlessLocal.openDb(":memory:");
+    let DbProvider = {
+      db: db
+    };
+    let Storage = EventLogStorage_Sqlite$ReventlessLocal.Make(TestBus)(DbProvider);
+    let s = Storage.make("agg", opts);
+    let ops = await TestRunner$ReventlessLocal.resolve(s.operations);
+    let event1 = Object.fromEntries([[
+        "tag",
+        "Created"
+      ]]);
+    let event2 = Object.fromEntries([[
+        "tag",
+        "Renamed"
+      ]]);
+    let r1 = await ops.append(0, "id-1", [event1]);
+    globalThis.expect(r1).toEqual({
+      TAG: "Ok",
+      _0: undefined
+    });
+    let r2 = await ops.append(1, "id-1", [event2]);
+    globalThis.expect(r2).toEqual({
+      TAG: "Ok",
+      _0: undefined
+    });
+    let replayed = await ops.replay("id-1");
+    globalThis.expect(replayed.length).toBe(2);
+    globalThis.expect(replayed[0]).toEqual(event1);
+    globalThis.expect(replayed[1]).toEqual(event2);
+  });
+  globalThis.test("append detects concurrency conflicts via PK collision", async () => {
+    let TestBus = LocalBus$ReventlessLocal.Make({});
+    let db = SqliteDriver$ReventlessLocal.openDb(":memory:");
+    let DbProvider = {
+      db: db
+    };
+    let Storage = EventLogStorage_Sqlite$ReventlessLocal.Make(TestBus)(DbProvider);
+    let s = Storage.make("agg", opts);
+    let ops = await TestRunner$ReventlessLocal.resolve(s.operations);
+    let e = Object.fromEntries([[
+        "t",
+        "X"
+      ]]);
+    await ops.append(0, "id-c", [e]);
+    let result = await ops.append(0, "id-c", [e]);
+    if (result.TAG === "Ok") {
+      globalThis.expect("expected conflict").toBe("actual Ok");
+      return;
+    }
+    globalThis.expect(true).toBe(true);
+  });
+  globalThis.test("replay returns empty array for unknown id", async () => {
+    let TestBus = LocalBus$ReventlessLocal.Make({});
+    let db = SqliteDriver$ReventlessLocal.openDb(":memory:");
+    let DbProvider = {
+      db: db
+    };
+    let Storage = EventLogStorage_Sqlite$ReventlessLocal.Make(TestBus)(DbProvider);
+    let s = Storage.make("agg", opts);
+    let ops = await TestRunner$ReventlessLocal.resolve(s.operations);
+    let replayed = await ops.replay("not-there");
+    globalThis.expect(replayed.length).toBe(0);
+  });
+  globalThis.test("events persist across a reopen of the database file", async () => {
+    let path = `/tmp/reventless-test-eventlog-` + Date.now().toString() + `.db`;
+    let TestBus = LocalBus$ReventlessLocal.Make({});
+    let db = SqliteDriver$ReventlessLocal.openDb(path);
+    let DbProvider = {
+      db: db
+    };
+    let Storage = EventLogStorage_Sqlite$ReventlessLocal.Make(TestBus)(DbProvider);
+    let s = Storage.make("persist", opts);
+    let ops = await TestRunner$ReventlessLocal.resolve(s.operations);
+    let ev = Object.fromEntries([[
+        "v",
+        42
+      ]]);
+    await ops.append(0, "id-p", [ev]);
+    SqliteDriver$ReventlessLocal.close(db);
+    let TestBus2 = LocalBus$ReventlessLocal.Make({});
+    let db$1 = SqliteDriver$ReventlessLocal.openDb(path);
+    let DbProvider2 = {
+      db: db$1
+    };
+    let Storage2 = EventLogStorage_Sqlite$ReventlessLocal.Make(TestBus2)(DbProvider2);
+    let s2 = Storage2.make("persist", opts);
+    let ops2 = await TestRunner$ReventlessLocal.resolve(s2.operations);
+    let replayed = await ops2.replay("id-p");
+    globalThis.expect(replayed.length).toBe(1);
+    return SqliteDriver$ReventlessLocal.close(db$1);
+  });
+});
+
+export {
+  opts,
+  makeFreshDb,
+}
+/*  Not a pure module */

package/tests/adapter/EventTapTest.res

@@ -0,0 +1,102 @@
+// Tests for the opt-in NDJSON domain-event tap (features plan Phase 9 — the VS
+// Code local platform runner). The tap lives in LocalBus.publishEvent: when
+// REVENTLESS_EVENT_TAP is set it emits one sentinel-prefixed JSON line per
+// published event to stdout (console.log), with the event's real topic name and
+// payload. Off by default so normal runs stay quiet.
+
+open JestGlobals
+
+let _ = TestRunner.setup()
+
+let defaultMeta: Reventless.Message.meta = {
+  service: "test",
+  time: "",
+  ip: "",
+  user: "test",
+  msgId: "",
+  correlationId: "",
+}
+
+@val external processEnv: Dict.t<string> = "process.env"
+
+type consoleObj = {mutable log: string => unit}
+@val external console: consoleObj = "console"
+
+let sentinel = "@@RVLESS_EVT@@ "
+
+// Run `fn` with console.log captured; returns every logged line, restoring the
+// original console.log even if `fn` throws.
+let captureLogs = async (fn: unit => promise<unit>): array<string> => {
+  let captured: array<string> = []
+  let original = console.log
+  console.log = s => captured->Array.push(s)
+  let result = try {
+    await fn()
+    Ok()
+  } catch {
+  | e => Error(e)
+  }
+  console.log = original
+  switch result {
+  | Ok() => captured
+  | Error(e) => throw(e)
+  }
+}
+
+let tapLines = (logs: array<string>): array<string> =>
+  logs->Array.filter(l => l->String.startsWith(sentinel))
+
+describe("LocalBus event tap (Phase 9)", () => {
+  // Each test owns the env flag; always clear it afterwards so cases don't leak.
+  let clearEnv = () => processEnv->Dict.delete("REVENTLESS_EVENT_TAP")
+
+  testPromise("tap off → no sentinel line is emitted", async () => {
+    clearEnv()
+    module TestBus = LocalBus.MakeSilent()
+    let logs = await captureLogs(async () => {
+      await TestBus.publishEvent("SomeTopic", "svc", defaultMeta, JSON.parseOrThrow(`{"a":1}`))
+    })
+    expect(tapLines(logs)->Array.length)->toBe(0)
+  })
+
+  testPromise("tap on → one well-formed line per published event", async () => {
+    processEnv->Dict.set("REVENTLESS_EVENT_TAP", "ndjson")
+    module TestBus = LocalBus.MakeSilent()
+    let logs = await captureLogs(async () => {
+      await TestBus.publishEvent(
+        "CatalogEventTopic",
+        "CatalogDcbEventLog",
+        defaultMeta,
+        JSON.parseOrThrow(`{"event":{"TAG":"ProductAdded","productId":"p-1"}}`),
+      )
+      await TestBus.publishEvent("OrderingEventTopic", "svc", defaultMeta, JSON.parseOrThrow(`{}`))
+    })
+    clearEnv()
+    let lines = tapLines(logs)
+    expect(lines->Array.length)->toBe(2)
+
+    // First line decodes to the expected envelope: event="domainEvent", the real
+    // topic name, and the payload passed to publishEvent (no topic-name guessing).
+    let first = lines->Array.getUnsafe(0)
+    let json =
+      first->String.slice(~start=sentinel->String.length, ~end=first->String.length)->JSON.parseOrThrow
+    let obj = json->JSON.Decode.object->Option.getOrThrow
+    expect(obj->Dict.get("event")->Option.flatMap(JSON.Decode.string))->toEqual(Some("domainEvent"))
+    expect(obj->Dict.get("topic")->Option.flatMap(JSON.Decode.string))->toEqual(
+      Some("CatalogEventTopic"),
+    )
+    expect(obj->Dict.get("seq")->Option.flatMap(JSON.Decode.float))->toEqual(Some(1.0))
+    expect(obj->Dict.get("payload")->Option.isSome)->toBe(true)
+  })
+
+  testPromise("tap emits even when the topic has no subscribers", async () => {
+    processEnv->Dict.set("REVENTLESS_EVENT_TAP", "ndjson")
+    module TestBus = LocalBus.MakeSilent()
+    let logs = await captureLogs(async () => {
+      // No subscribeToEvents call — the tap fires before the subscriber-count gate.
+      await TestBus.publishEvent("Lonely", "svc", defaultMeta, JSON.Null)
+    })
+    clearEnv()
+    expect(tapLines(logs)->Array.length)->toBe(1)
+  })
+})