@reventlessdev/reventless-local 3.0.0-alpha.244 → 3.0.0-alpha.246

package/tests/LocalEventTapTest.res

@@ -0,0 +1,154 @@
+// The tap's second sink. A tool that did not spawn the platform has no stdout to
+// read, so an attached runner's timeline is dark without this.
+
+@@warning("-44")
+
+open JestGlobals
+
+type recorder = {socket: NodeNet.socket, written: array<string>}
+
+@module("./EventTapSocketFixtures.mjs")
+external recordingSocket: unit => recorder = "recordingSocket"
+
+@module("./EventTapSocketFixtures.mjs")
+external throwingSocket: unit => NodeNet.socket = "throwingSocket"
+
+let envWith = (value: option<string>): dict<string> =>
+  switch value {
+  | Some(v) => Dict.fromArray([(LocalEventTap.envVar, v)])
+  | None => Dict.make()
+  }
+
+describe("LocalEventTap.settingFromEnv", () => {
+  // The default is the point: the runner attaches to whatever `pnpm run serve`
+  // started, and a tap nobody remembered to switch on is a dark timeline.
+  testSync("defaults to an ephemeral socket when the var is unset", () => {
+    expect(LocalEventTap.settingFromEnv(~env=envWith(None)))->toEqual(LocalEventTap.Ephemeral)
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some(""))))->toEqual(LocalEventTap.Ephemeral)
+  })
+
+  testSync("takes a port when the value is one", () =>
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("4100"))))->toEqual(
+      LocalEventTap.Fixed(4100),
+    )
+  )
+
+  // `ndjson` is what the runner has passed since the tap existed, and `=1` means
+  // "on" to anyone who writes it — never port 1. Both take the default socket.
+  testSync("treats a non-port value as the default, not as a port", () => {
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("ndjson"))))->toEqual(
+      LocalEventTap.Ephemeral,
+    )
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("1"))))->toEqual(LocalEventTap.Ephemeral)
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("80"))))->toEqual(LocalEventTap.Ephemeral)
+    expect(LocalEventTap.settingFromEnv(~env=envWith(Some("70000"))))->toEqual(
+      LocalEventTap.Ephemeral,
+    )
+  })
+
+  testSync("switches the socket off on request", () =>
+    ["off", "false", "none"]->Array.forEach(v =>
+      expect(LocalEventTap.settingFromEnv(~env=envWith(Some(v))))->toEqual(LocalEventTap.Off)
+    )
+  )
+})
+
+describe("LocalEventTap.stdoutEnabled", () => {
+  // The half with a visible cost keeps its opt-in: a line per event would drown
+  // `pnpm run serve`, which is the command the socket default exists to serve.
+  testSync("stays off unless the var is set", () => {
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(None)))->toEqual(false)
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(Some("ndjson"))))->toEqual(true)
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(Some("4100"))))->toEqual(true)
+  })
+
+  testSync("is silenced by off, along with the socket", () =>
+    expect(LocalEventTap.stdoutEnabled(~env=envWith(Some("off"))))->toEqual(false)
+  )
+})
+
+describe("LocalEventTap.broadcast", () => {
+  testSync("hands every reader the line, newline-terminated", () => {
+    LocalEventTap.resetForTests()
+    let a = recordingSocket()
+    let b = recordingSocket()
+    LocalEventTap.addConnectionForTests(a.socket)
+    LocalEventTap.addConnectionForTests(b.socket)
+
+    LocalEventTap.broadcast(`@@RVLESS_EVT@@ {"seq":1}`)
+
+    expect(a.written)->toEqual([`@@RVLESS_EVT@@ {"seq":1}\n`])
+    expect(b.written)->toEqual([`@@RVLESS_EVT@@ {"seq":1}\n`])
+  })
+
+  // A write to a closed peer throws. One dead reader must not cost the others
+  // their events, or the platform its run.
+  testSync("drops a reader whose write throws, and keeps serving the rest", () => {
+    LocalEventTap.resetForTests()
+    let live = recordingSocket()
+    LocalEventTap.addConnectionForTests(throwingSocket())
+    LocalEventTap.addConnectionForTests(live.socket)
+
+    LocalEventTap.broadcast("first")
+    LocalEventTap.broadcast("second")
+
+    expect(live.written)->toEqual(["first\n", "second\n"])
+  })
+
+  testSync("is inert with no readers", () => {
+    LocalEventTap.resetForTests()
+    LocalEventTap.broadcast("nobody is listening")
+    expect(LocalEventTap.port())->toEqual(None)
+  })
+})
+
+describe("LocalEventTap.start", () => {
+  testSync("does not listen when the socket is switched off", () => {
+    LocalEventTap.resetForTests()
+    LocalEventTap.start(~env=envWith(Some("off")), ())
+    expect(LocalEventTap.port())->toEqual(None)
+  })
+
+  // The default path, and the one that matters: no env var at all, a port the OS
+  // picks, reported only once it is actually bound.
+  test("binds an ephemeral port by default and reports the one it got", async () => {
+    LocalEventTap.resetForTests()
+    let bound = await Promise.make((resolve, _reject) =>
+      LocalEventTap.start(~env=envWith(None), ~onBound=p => resolve(p), ())
+    )
+    expect(bound > 0)->toEqual(true)
+    // What the registry entry will carry — the real port, not a hoped-for one.
+    expect(LocalEventTap.port())->toEqual(Some(bound))
+    await LocalEventTap.stopForTests()
+  })
+
+  // The round trip the runner will make: connect to the advertised port, read
+  // the same sentinel-prefixed lines it reads off stdout today.
+  test("serves the lines it is sent on the port it was named", async () => {
+    LocalEventTap.resetForTests()
+    let port = 47311
+    let bound = await Promise.make((resolve, _reject) =>
+      LocalEventTap.start(~env=envWith(Some(port->Int.toString)), ~onBound=p => resolve(p), ())
+    )
+    expect(bound)->toEqual(port)
+
+    let received = await Promise.make((resolve, _reject) => {
+      let socket = NodeNet.connect(port, "127.0.0.1", () => ())
+      socket->NodeNet.setEncoding("utf8")
+      socket->NodeNet.onSocketError(e =>
+        resolve("connect failed: " ++ e->JsExn.message->Option.getOr("unknown"))
+      )
+      // Re-sent until it lands: the server's accept and the client's connect are
+      // separate events, so a single broadcast could beat the connection.
+      let ticker = ref(None)
+      socket->NodeNet.onSocketData(chunk => {
+        ticker.contents->Option.forEach(clearInterval)
+        resolve(chunk)
+      })
+      ticker := Some(setInterval(() => LocalEventTap.broadcast(`@@RVLESS_EVT@@ {"seq":7}`), 5))
+    })
+
+    expect(received)->toEqual(`@@RVLESS_EVT@@ {"seq":7}\n`)
+    await LocalEventTap.stopForTests()
+  })
+})

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)
+  })
+})