@reventlessdev/reventless-local 3.0.0-alpha.243 → 3.0.0-alpha.245

package/tests/LocalEventTapTest.res.mjs

@@ -0,0 +1,140 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodenet from "node:net";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as EventTapSocketFixturesMjs from "./EventTapSocketFixtures.mjs";
+import * as LocalEventTap$ReventlessLocal from "../src/adapter/LocalEventTap.res.mjs";
+
+function recordingSocket(prim) {
+  return EventTapSocketFixturesMjs.recordingSocket();
+}
+
+function throwingSocket(prim) {
+  return EventTapSocketFixturesMjs.throwingSocket();
+}
+
+function envWith(value) {
+  if (value !== undefined) {
+    return Object.fromEntries([[
+        LocalEventTap$ReventlessLocal.envVar,
+        value
+      ]]);
+  } else {
+    return {};
+  }
+}
+
+globalThis.describe("LocalEventTap.settingFromEnv", () => {
+  globalThis.test("defaults to an ephemeral socket when the var is unset", () => {
+    globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith(undefined))).toEqual("Ephemeral");
+    globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith(""))).toEqual("Ephemeral");
+  });
+  globalThis.test("takes a port when the value is one", () => {
+    globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith("4100"))).toEqual({
+      TAG: "Fixed",
+      _0: 4100
+    });
+  });
+  globalThis.test("treats a non-port value as the default, not as a port", () => {
+    globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith("ndjson"))).toEqual("Ephemeral");
+    globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith("1"))).toEqual("Ephemeral");
+    globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith("80"))).toEqual("Ephemeral");
+    globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith("70000"))).toEqual("Ephemeral");
+  });
+  globalThis.test("switches the socket off on request", () => {
+    [
+      "off",
+      "false",
+      "none"
+    ].forEach(v => {
+      globalThis.expect(LocalEventTap$ReventlessLocal.settingFromEnv(envWith(v))).toEqual("Off");
+    });
+  });
+});
+
+globalThis.describe("LocalEventTap.stdoutEnabled", () => {
+  globalThis.test("stays off unless the var is set", () => {
+    globalThis.expect(LocalEventTap$ReventlessLocal.stdoutEnabled(envWith(undefined))).toEqual(false);
+    globalThis.expect(LocalEventTap$ReventlessLocal.stdoutEnabled(envWith("ndjson"))).toEqual(true);
+    globalThis.expect(LocalEventTap$ReventlessLocal.stdoutEnabled(envWith("4100"))).toEqual(true);
+  });
+  globalThis.test("is silenced by off, along with the socket", () => {
+    globalThis.expect(LocalEventTap$ReventlessLocal.stdoutEnabled(envWith("off"))).toEqual(false);
+  });
+});
+
+globalThis.describe("LocalEventTap.broadcast", () => {
+  globalThis.test("hands every reader the line, newline-terminated", () => {
+    LocalEventTap$ReventlessLocal.resetForTests();
+    let a = EventTapSocketFixturesMjs.recordingSocket();
+    let b = EventTapSocketFixturesMjs.recordingSocket();
+    LocalEventTap$ReventlessLocal.addConnectionForTests(a.socket);
+    LocalEventTap$ReventlessLocal.addConnectionForTests(b.socket);
+    LocalEventTap$ReventlessLocal.broadcast(`@@RVLESS_EVT@@ {"seq":1}`);
+    globalThis.expect(a.written).toEqual([`@@RVLESS_EVT@@ {"seq":1}\n`]);
+    globalThis.expect(b.written).toEqual([`@@RVLESS_EVT@@ {"seq":1}\n`]);
+  });
+  globalThis.test("drops a reader whose write throws, and keeps serving the rest", () => {
+    LocalEventTap$ReventlessLocal.resetForTests();
+    let live = EventTapSocketFixturesMjs.recordingSocket();
+    LocalEventTap$ReventlessLocal.addConnectionForTests(EventTapSocketFixturesMjs.throwingSocket());
+    LocalEventTap$ReventlessLocal.addConnectionForTests(live.socket);
+    LocalEventTap$ReventlessLocal.broadcast("first");
+    LocalEventTap$ReventlessLocal.broadcast("second");
+    globalThis.expect(live.written).toEqual([
+      "first\n",
+      "second\n"
+    ]);
+  });
+  globalThis.test("is inert with no readers", () => {
+    LocalEventTap$ReventlessLocal.resetForTests();
+    LocalEventTap$ReventlessLocal.broadcast("nobody is listening");
+    globalThis.expect(LocalEventTap$ReventlessLocal.port()).toEqual(undefined);
+  });
+});
+
+globalThis.describe("LocalEventTap.start", () => {
+  globalThis.test("does not listen when the socket is switched off", () => {
+    LocalEventTap$ReventlessLocal.resetForTests();
+    LocalEventTap$ReventlessLocal.start(envWith("off"), undefined, undefined);
+    globalThis.expect(LocalEventTap$ReventlessLocal.port()).toEqual(undefined);
+  });
+  globalThis.test("binds an ephemeral port by default and reports the one it got", async () => {
+    LocalEventTap$ReventlessLocal.resetForTests();
+    let bound = await new Promise((resolve, _reject) => LocalEventTap$ReventlessLocal.start(envWith(undefined), p => resolve(p), undefined));
+    globalThis.expect(bound > 0).toEqual(true);
+    globalThis.expect(LocalEventTap$ReventlessLocal.port()).toEqual(bound);
+    return await LocalEventTap$ReventlessLocal.stopForTests();
+  });
+  globalThis.test("serves the lines it is sent on the port it was named", async () => {
+    LocalEventTap$ReventlessLocal.resetForTests();
+    let bound = await new Promise((resolve, _reject) => LocalEventTap$ReventlessLocal.start(envWith((47311).toString()), p => resolve(p), undefined));
+    globalThis.expect(bound).toEqual(47311);
+    let received = await new Promise((resolve, _reject) => {
+      let socket = Nodenet.createConnection(47311, "127.0.0.1", () => {});
+      socket.setEncoding("utf8");
+      socket.on("error", e => resolve("connect failed: " + Stdlib_Option.getOr(Stdlib_JsExn.message(e), "unknown")));
+      let ticker = {
+        contents: undefined
+      };
+      socket.on("data", chunk => {
+        Stdlib_Option.forEach(ticker.contents, prim => {
+          clearInterval(prim);
+        });
+        resolve(chunk);
+      });
+      ticker.contents = Primitive_option.some(setInterval(() => LocalEventTap$ReventlessLocal.broadcast(`@@RVLESS_EVT@@ {"seq":7}`), 5));
+    });
+    globalThis.expect(received).toEqual(`@@RVLESS_EVT@@ {"seq":7}\n`);
+    return await LocalEventTap$ReventlessLocal.stopForTests();
+  });
+});
+
+export {
+  recordingSocket,
+  throwingSocket,
+  envWith,
+}
+/*  Not a pure module */

package/tests/LocalPlatformRegistryTest.res

@@ -141,3 +141,64 @@ describe("LocalSeedTarget.storePath", () => {
     )->toEqual(true)
   })
 })
+
+describe("LocalPlatformRegistry.tapPort", () => {
+  // Optional on purpose: `list` DELETES an entry it cannot decode, so a required
+  // field would make every platform from an older build vanish from the seed
+  // tools rather than fail loudly.
+  testSync("reads an entry written before the field existed", () => {
+    let cwd = tempRoot()
+    let dir = LocalPlatformRegistry.runningDir(~cwd, ())
+    NodeFs.mkdirSync(dir, {recursive: true})
+    let path = NodePath.join([dir, "4000.json"])
+    NodeFs.writeFileSync(
+      path,
+      `{"app":"old","port":4000,"pid":${NodeProcess.pid->Int.toString},"endpoint":"http://localhost:4000/graphql","loginEndpoint":"http://localhost:4000/__inmemory/login","store":{"kind":"memory"},"startedAt":"2026-08-14T00:00:00.000Z"}`,
+    )
+
+    switch LocalPlatformRegistry.list(~cwd, ())->Array.get(0) {
+    | Some(entry) => expect(entry.tapPort)->toEqual(None)
+    | None => fail("an entry without tapPort must still be listed")
+    }
+    expect(NodeFs.existsSync(path))->toEqual(true)
+  })
+
+  // The socket binds asynchronously, so the entry is published first and the port
+  // filled in on the listen callback — which is what keeps it from ever naming a
+  // port that is not listening.
+  testSync("fills the port in on an entry already written", () => {
+    let cwd = tempRoot()
+    let _ = writeAt(~cwd, ~port=4000, ~store=memoryStore)
+    expect(LocalPlatformRegistry.list(~cwd, ())->Array.map(e => e.tapPort))->toEqual([None])
+
+    LocalPlatformRegistry.publishTapPort(~port=4000, ~tapPort=58909, ~cwd)
+
+    switch LocalPlatformRegistry.list(~cwd, ())->Array.get(0) {
+    | Some(entry) =>
+      expect(entry.tapPort)->toEqual(Some(58909))
+      // The rest of the entry survives the rewrite — a reader still finds the
+      // endpoint and store it came for.
+      expect(entry.endpoint)->toEqual("http://localhost:4000/graphql")
+      expect(entry.store.kind)->toEqual("memory")
+    | None => fail("the updated entry must still be listed")
+    }
+  })
+
+  testSync("ignores a platform that never published an entry", () =>
+    LocalPlatformRegistry.publishTapPort(~port=4000, ~tapPort=1, ~cwd=tempRoot())
+  )
+
+  testSync("round-trips the port a platform serving a tap publishes", () => {
+    let cwd = tempRoot()
+    let _ = LocalPlatformRegistry.write(
+      ~port=4000,
+      ~endpoint="http://localhost:4000/graphql",
+      ~loginEndpoint="http://localhost:4000/__inmemory/login",
+      ~store=memoryStore,
+      ~tapPort=4100,
+      ~cwd,
+    )
+
+    expect(LocalPlatformRegistry.list(~cwd, ())->Array.map(e => e.tapPort))->toEqual([Some(4100)])
+  })
+})

package/tests/LocalPlatformRegistryTest.res.mjs

@@ -25,7 +25,7 @@ let memoryStore = {
 
 function writeAt(cwd, port, store, pidOpt) {
   let pid = pidOpt !== undefined ? pidOpt : process.pid;
-  return LocalPlatformRegistry$ReventlessLocal.write(port, `http://localhost:` + port.toString() + `/graphql`, `http://localhost:` + port.toString() + `/__inmemory/login`, store, pid, cwd);
+  return LocalPlatformRegistry$ReventlessLocal.write(port, `http://localhost:` + port.toString() + `/graphql`, `http://localhost:` + port.toString() + `/__inmemory/login`, store, undefined, pid, cwd);
 }
 
 globalThis.describe("LocalPlatformRegistry", () => {
@@ -140,6 +140,46 @@ globalThis.describe("LocalSeedTarget.storePath", () => {
   });
 });
 
+globalThis.describe("LocalPlatformRegistry.tapPort", () => {
+  globalThis.test("reads an entry written before the field existed", () => {
+    let cwd = tempRoot();
+    let dir = LocalPlatformRegistry$ReventlessLocal.runningDir(cwd, undefined);
+    Nodefs.mkdirSync(dir, {
+      recursive: true
+    });
+    let path = Nodepath.join(dir, "4000.json");
+    Nodefs.writeFileSync(path, `{"app":"old","port":4000,"pid":` + process.pid.toString() + `,"endpoint":"http://localhost:4000/graphql","loginEndpoint":"http://localhost:4000/__inmemory/login","store":{"kind":"memory"},"startedAt":"2026-08-14T00:00:00.000Z"}`, "utf8");
+    let entry = LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined)[0];
+    if (entry !== undefined) {
+      globalThis.expect(entry.tapPort).toEqual(undefined);
+    } else {
+      JestGlobals.fail("an entry without tapPort must still be listed");
+    }
+    globalThis.expect(Nodefs.existsSync(path)).toEqual(true);
+  });
+  globalThis.test("fills the port in on an entry already written", () => {
+    let cwd = tempRoot();
+    writeAt(cwd, 4000, memoryStore, undefined);
+    globalThis.expect(LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined).map(e => e.tapPort)).toEqual([undefined]);
+    LocalPlatformRegistry$ReventlessLocal.publishTapPort(4000, 58909, cwd);
+    let entry = LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined)[0];
+    if (entry !== undefined) {
+      globalThis.expect(entry.tapPort).toEqual(58909);
+      globalThis.expect(entry.endpoint).toEqual("http://localhost:4000/graphql");
+      globalThis.expect(entry.store.kind).toEqual("memory");
+      return;
+    } else {
+      return JestGlobals.fail("the updated entry must still be listed");
+    }
+  });
+  globalThis.test("ignores a platform that never published an entry", () => LocalPlatformRegistry$ReventlessLocal.publishTapPort(4000, 1, tempRoot()));
+  globalThis.test("round-trips the port a platform serving a tap publishes", () => {
+    let cwd = tempRoot();
+    LocalPlatformRegistry$ReventlessLocal.write(4000, "http://localhost:4000/graphql", "http://localhost:4000/__inmemory/login", memoryStore, 4100, undefined, cwd);
+    globalThis.expect(LocalPlatformRegistry$ReventlessLocal.list(cwd, undefined).map(e => e.tapPort)).toEqual([4100]);
+  });
+});
+
 let deadPid = 2147483646;
 
 export {

package/tests/LocalPlatformStartTest.res

@@ -0,0 +1,176 @@
+// A reset used to unlink a served store at construction and only discover at the
+// bind, ~1200 lines later, that it had lost the race.
+
+@@warning("-44")
+
+open JestGlobals
+
+let tempRoot = (): string =>
+  NodeFs.mkdtempSync(NodePath.join([NodeOs.tmpdir(), "reventless-start-"]))
+
+let deadPid = 2147483646
+
+let sqliteStore = (path): LocalPlatformRegistry.store => {kind: "sqlite", path: Some(path)}
+let memoryStore: LocalPlatformRegistry.store = {kind: "memory", path: None}
+
+let writeAt = (~cwd, ~port, ~store, ~pid=NodeProcess.pid) =>
+  LocalPlatformRegistry.write(
+    ~port,
+    ~endpoint=`http://localhost:${port->Int.toString}/graphql`,
+    ~loginEndpoint=`http://localhost:${port->Int.toString}/__inmemory/login`,
+    ~store,
+    ~pid,
+    ~cwd,
+  )
+
+let withoutBypass = (f: unit => unit) => {
+  let previous = NodeProcess.env->Dict.get(LocalPlatformStart.bypassEnv)
+  NodeProcess.env->Dict.delete(LocalPlatformStart.bypassEnv)
+  let restore = () =>
+    switch previous {
+    | Some(v) => NodeProcess.env->Dict.set(LocalPlatformStart.bypassEnv, v)
+    | None => ()
+    }
+  try {
+    f()
+    restore()
+  } catch {
+  | e =>
+    restore()
+    throw(e)
+  }
+}
+
+describe("LocalPlatformStart.guardReset", () => {
+  // The exact sequence that lost data.
+  testSync("refuses a reset of a store a live platform opened, naming it", () => {
+    let cwd = tempRoot()
+    let store = NodePath.join([cwd, ".reventless", "local.db"])
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(store))
+
+    switch LocalPlatformStart.guardReset(~path=store, ~cwd, ()) {
+    | () => fail("expected the reset to be refused")
+    | exception JsExn(e) =>
+      let message = e->JsExn.message->Option.getOr("")
+      expect(message->String.includes(":4000"))->toEqual(true)
+      expect(message->String.includes(NodeProcess.pid->Int.toString))->toEqual(true)
+    }
+  })
+
+  // Entry paths are absolute; the configured one is what an operator typed.
+  testSync("matches a relative configured path against the absolute registered one", () => {
+    let cwd = tempRoot()
+    let absolute = NodePath.join([NodeProcess.cwd(), ".reventless", "guard-probe.db"])
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(absolute))
+
+    expect(
+      LocalPlatformStart.servedBy(~path="./.reventless/guard-probe.db", ~cwd, ())->Option.isSome,
+    )->toEqual(true)
+  })
+
+  testSync("lets a reset through when nothing is serving that file", () => {
+    let cwd = tempRoot()
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(NodePath.join([cwd, "other.db"])))
+
+    expect(LocalPlatformStart.servedBy(~path=NodePath.join([cwd, "local.db"]), ~cwd, ()))->toEqual(
+      None,
+    )
+    LocalPlatformStart.guardReset(~path=NodePath.join([cwd, "local.db"]), ~cwd, ())
+  })
+
+  // A `kill -9` leaves the entry behind; a guard that trusted it would never pass.
+  testSync("lets a reset through when the platform holding the store is gone", () => {
+    let cwd = tempRoot()
+    let store = NodePath.join([cwd, "local.db"])
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(store), ~pid=deadPid)
+
+    LocalPlatformStart.guardReset(~path=store, ~cwd, ())
+  })
+
+  // An in-memory platform names no path, so it can never hold a store file.
+  testSync("ignores a platform that keeps its store in memory", () => {
+    let cwd = tempRoot()
+    let _ = writeAt(~cwd, ~port=4010, ~store=memoryStore)
+
+    LocalPlatformStart.guardReset(~path=NodePath.join([cwd, "local.db"]), ~cwd, ())
+  })
+})
+
+describe("LocalPlatformStart.orAddressRunning", () => {
+  // The addressing path exits 0, so running it first would report success for a
+  // wipe that never happened.
+  testSync("refuses a reset before it addresses the platform holding the store", () => {
+    let cwd = tempRoot()
+    let relative = "./.reventless/order-probe.db"
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(NodePath.resolve([relative])))
+
+    let previousBackend = NodeProcess.env->Dict.get("REVENTLESS_LOCAL_BACKEND")
+    NodeProcess.env->Dict.set("REVENTLESS_LOCAL_BACKEND", `sqlite:${relative}?reset`)
+    let outcome = switch LocalPlatformStart.orAddressRunning(~cwd, ()) {
+    | () => "returned or exited"
+    | exception JsExn(e) => e->JsExn.message->Option.getOr("")
+    }
+    switch previousBackend {
+    | Some(v) => NodeProcess.env->Dict.set("REVENTLESS_LOCAL_BACKEND", v)
+    | None => NodeProcess.env->Dict.delete("REVENTLESS_LOCAL_BACKEND")
+    }
+
+    expect(outcome->String.includes("refusing to reset"))->toEqual(true)
+    expect(outcome->String.includes(":4000"))->toEqual(true)
+  })
+})
+
+describe("LocalPlatformStart.decide", () => {
+  testSync("starts where nothing is running", () =>
+    withoutBypass(() =>
+      expect(LocalPlatformStart.decide(~cwd=tempRoot(), ()))->toEqual(LocalPlatformStart.Start)
+    )
+  )
+
+  testSync("addresses the one platform already serving this directory", () =>
+    withoutBypass(() => {
+      let cwd = tempRoot()
+      let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(NodePath.join([cwd, "local.db"])))
+
+      switch LocalPlatformStart.decide(~cwd, ()) {
+      | Start => fail("expected the running platform to be addressed")
+      | AlreadyRunning(entries) =>
+        expect(entries->Array.map(e => e.port))->toEqual([4000])
+        let lines = LocalPlatformStart.report(entries)
+        expect(lines->Array.length)->toEqual(2)
+        expect(lines->Array.join("\n")->String.includes(":4000"))->toEqual(true)
+      }
+    })
+  )
+
+  // The state this is trying to make impossible: say so rather than pick one.
+  testSync("names all of them when two are running", () =>
+    withoutBypass(() => {
+      let cwd = tempRoot()
+      let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(NodePath.join([cwd, "local.db"])))
+      let _ = writeAt(~cwd, ~port=4010, ~store=memoryStore)
+
+      switch LocalPlatformStart.decide(~cwd, ()) {
+      | Start => fail("expected both running platforms to be reported")
+      | AlreadyRunning(entries) =>
+        let printed = LocalPlatformStart.report(entries)->Array.join("\n")
+        expect(printed->String.includes(":4000"))->toEqual(true)
+        expect(printed->String.includes(":4010"))->toEqual(true)
+      }
+    })
+  )
+
+  // The escape hatch the e2e suites and the VS Code runner already take.
+  testSync("starts anyway when REVENTLESS_DOMAIN_PORT names a port", () => {
+    let cwd = tempRoot()
+    let _ = writeAt(~cwd, ~port=4000, ~store=sqliteStore(NodePath.join([cwd, "local.db"])))
+    let previous = NodeProcess.env->Dict.get(LocalPlatformStart.bypassEnv)
+    NodeProcess.env->Dict.set(LocalPlatformStart.bypassEnv, "4010")
+    let decision = LocalPlatformStart.decide(~cwd, ())
+    switch previous {
+    | Some(v) => NodeProcess.env->Dict.set(LocalPlatformStart.bypassEnv, v)
+    | None => NodeProcess.env->Dict.delete(LocalPlatformStart.bypassEnv)
+    }
+    expect(decision)->toEqual(LocalPlatformStart.Start)
+  })
+})

package/tests/LocalPlatformStartTest.res.mjs

@@ -0,0 +1,210 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeos from "node:os";
+import * as Nodepath from "node:path";
+import * as JestGlobals from "@reventlessdev/rescript-jest/src/JestGlobals.res.mjs";
+import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as LocalPlatformStart$ReventlessLocal from "../src/LocalPlatformStart.res.mjs";
+import * as LocalPlatformRegistry$ReventlessLocal from "../src/LocalPlatformRegistry.res.mjs";
+
+function tempRoot() {
+  return Nodefs.mkdtempSync(Nodepath.join(Nodeos.tmpdir(), "reventless-start-"));
+}
+
+function sqliteStore(path) {
+  return {
+    kind: "sqlite",
+    path: path
+  };
+}
+
+let memoryStore = {
+  kind: "memory",
+  path: undefined
+};
+
+function writeAt(cwd, port, store, pidOpt) {
+  let pid = pidOpt !== undefined ? pidOpt : process.pid;
+  return LocalPlatformRegistry$ReventlessLocal.write(port, `http://localhost:` + port.toString() + `/graphql`, `http://localhost:` + port.toString() + `/__inmemory/login`, store, undefined, pid, cwd);
+}
+
+function withoutBypass(f) {
+  let previous = process.env[LocalPlatformStart$ReventlessLocal.bypassEnv];
+  Stdlib_Dict.$$delete(process.env, LocalPlatformStart$ReventlessLocal.bypassEnv);
+  let restore = () => {
+    if (previous !== undefined) {
+      process.env[LocalPlatformStart$ReventlessLocal.bypassEnv] = previous;
+      return;
+    }
+  };
+  try {
+    f();
+    return restore();
+  } catch (e) {
+    restore();
+    throw e;
+  }
+}
+
+globalThis.describe("LocalPlatformStart.guardReset", () => {
+  globalThis.test("refuses a reset of a store a live platform opened, naming it", () => {
+    let cwd = tempRoot();
+    let store = Nodepath.join(cwd, ".reventless", "local.db");
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: store
+    }, undefined);
+    let val;
+    try {
+      val = LocalPlatformStart$ReventlessLocal.guardReset(store, cwd, undefined);
+    } catch (raw_e) {
+      let e = Primitive_exceptions.internalToException(raw_e);
+      if (e.RE_EXN_ID === "JsExn") {
+        let message = Stdlib_Option.getOr(Stdlib_JsExn.message(e._1), "");
+        globalThis.expect(message.includes(":4000")).toEqual(true);
+        globalThis.expect(message.includes(process.pid.toString())).toEqual(true);
+        return;
+      }
+      throw e;
+    }
+    JestGlobals.fail("expected the reset to be refused");
+  });
+  globalThis.test("matches a relative configured path against the absolute registered one", () => {
+    let cwd = tempRoot();
+    let absolute = Nodepath.join(process.cwd(), ".reventless", "guard-probe.db");
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: absolute
+    }, undefined);
+    globalThis.expect(Stdlib_Option.isSome(LocalPlatformStart$ReventlessLocal.servedBy("./.reventless/guard-probe.db", cwd, undefined))).toEqual(true);
+  });
+  globalThis.test("lets a reset through when nothing is serving that file", () => {
+    let cwd = tempRoot();
+    let path = Nodepath.join(cwd, "other.db");
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: path
+    }, undefined);
+    globalThis.expect(LocalPlatformStart$ReventlessLocal.servedBy(Nodepath.join(cwd, "local.db"), cwd, undefined)).toEqual(undefined);
+    LocalPlatformStart$ReventlessLocal.guardReset(Nodepath.join(cwd, "local.db"), cwd, undefined);
+  });
+  globalThis.test("lets a reset through when the platform holding the store is gone", () => {
+    let cwd = tempRoot();
+    let store = Nodepath.join(cwd, "local.db");
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: store
+    }, 2147483646);
+    LocalPlatformStart$ReventlessLocal.guardReset(store, cwd, undefined);
+  });
+  globalThis.test("ignores a platform that keeps its store in memory", () => {
+    let cwd = tempRoot();
+    writeAt(cwd, 4010, memoryStore, undefined);
+    LocalPlatformStart$ReventlessLocal.guardReset(Nodepath.join(cwd, "local.db"), cwd, undefined);
+  });
+});
+
+globalThis.describe("LocalPlatformStart.orAddressRunning", () => {
+  globalThis.test("refuses a reset before it addresses the platform holding the store", () => {
+    let cwd = tempRoot();
+    let relative = "./.reventless/order-probe.db";
+    let path = Nodepath.resolve(relative);
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: path
+    }, undefined);
+    let previousBackend = process.env["REVENTLESS_LOCAL_BACKEND"];
+    process.env["REVENTLESS_LOCAL_BACKEND"] = `sqlite:` + relative + `?reset`;
+    let outcome;
+    try {
+      LocalPlatformStart$ReventlessLocal.orAddressRunning(cwd, undefined);
+      outcome = "returned or exited";
+    } catch (raw_e) {
+      let e = Primitive_exceptions.internalToException(raw_e);
+      if (e.RE_EXN_ID === "JsExn") {
+        outcome = Stdlib_Option.getOr(Stdlib_JsExn.message(e._1), "");
+      } else {
+        throw e;
+      }
+    }
+    if (previousBackend !== undefined) {
+      process.env["REVENTLESS_LOCAL_BACKEND"] = previousBackend;
+    } else {
+      Stdlib_Dict.$$delete(process.env, "REVENTLESS_LOCAL_BACKEND");
+    }
+    globalThis.expect(outcome.includes("refusing to reset")).toEqual(true);
+    globalThis.expect(outcome.includes(":4000")).toEqual(true);
+  });
+});
+
+globalThis.describe("LocalPlatformStart.decide", () => {
+  globalThis.test("starts where nothing is running", () => withoutBypass(() => {
+    globalThis.expect(LocalPlatformStart$ReventlessLocal.decide(tempRoot(), undefined)).toEqual("Start");
+  }));
+  globalThis.test("addresses the one platform already serving this directory", () => withoutBypass(() => {
+    let cwd = tempRoot();
+    let path = Nodepath.join(cwd, "local.db");
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: path
+    }, undefined);
+    let entries = LocalPlatformStart$ReventlessLocal.decide(cwd, undefined);
+    if (typeof entries !== "object") {
+      return JestGlobals.fail("expected the running platform to be addressed");
+    }
+    let entries$1 = entries._0;
+    globalThis.expect(entries$1.map(e => e.port)).toEqual([4000]);
+    let lines = LocalPlatformStart$ReventlessLocal.report(entries$1);
+    globalThis.expect(lines.length).toEqual(2);
+    globalThis.expect(lines.join("\n").includes(":4000")).toEqual(true);
+  }));
+  globalThis.test("names all of them when two are running", () => withoutBypass(() => {
+    let cwd = tempRoot();
+    let path = Nodepath.join(cwd, "local.db");
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: path
+    }, undefined);
+    writeAt(cwd, 4010, memoryStore, undefined);
+    let entries = LocalPlatformStart$ReventlessLocal.decide(cwd, undefined);
+    if (typeof entries !== "object") {
+      return JestGlobals.fail("expected both running platforms to be reported");
+    }
+    let printed = LocalPlatformStart$ReventlessLocal.report(entries._0).join("\n");
+    globalThis.expect(printed.includes(":4000")).toEqual(true);
+    globalThis.expect(printed.includes(":4010")).toEqual(true);
+  }));
+  globalThis.test("starts anyway when REVENTLESS_DOMAIN_PORT names a port", () => {
+    let cwd = tempRoot();
+    let path = Nodepath.join(cwd, "local.db");
+    writeAt(cwd, 4000, {
+      kind: "sqlite",
+      path: path
+    }, undefined);
+    let previous = process.env[LocalPlatformStart$ReventlessLocal.bypassEnv];
+    process.env[LocalPlatformStart$ReventlessLocal.bypassEnv] = "4010";
+    let decision = LocalPlatformStart$ReventlessLocal.decide(cwd, undefined);
+    if (previous !== undefined) {
+      process.env[LocalPlatformStart$ReventlessLocal.bypassEnv] = previous;
+    } else {
+      Stdlib_Dict.$$delete(process.env, LocalPlatformStart$ReventlessLocal.bypassEnv);
+    }
+    globalThis.expect(decision).toEqual("Start");
+  });
+});
+
+let deadPid = 2147483646;
+
+export {
+  tempRoot,
+  deadPid,
+  sqliteStore,
+  memoryStore,
+  writeAt,
+  withoutBypass,
+}
+/*  Not a pure module */

package/tests/adapter/EventTapTest.res

@@ -1,8 +1,7 @@
-// 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.
+// The tap's stdout sink, which is the opt-in half: REVENTLESS_EVENT_TAP puts one
+// sentinel-prefixed JSON line per published event on stdout, and stays off by
+// default so normal runs are quiet. The socket sink is default-on and covered by
+// LocalEventTapTest.
 
 open JestGlobals
 
@@ -84,8 +83,19 @@ describe("LocalBus event tap (Phase 9)", () => {
     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)
+
+    // Consecutive, not absolute: `seq` is the event's ordinal in the store (it is
+    // seeded from the persisted count at startup and counts every publish, tapped
+    // or not), so a reader that connects late still sees the real event number.
+    // The counter is module-level, so an absolute assertion here would depend on
+    // what the rest of the file published first.
+    let seqOf = line => {
+      let j = line->String.slice(~start=sentinel->String.length, ~end=line->String.length)
+      j->JSON.parseOrThrow->JSON.Decode.object->Option.getOrThrow->Dict.get("seq")
+      ->Option.flatMap(JSON.Decode.float)->Option.getOr(0.)
+    }
+    expect(seqOf(lines->Array.getUnsafe(1)) -. seqOf(first))->toEqual(1.)
   })
 
   testPromise("tap emits even when the topic has no subscribers", async () => {