Silence the edge-runtime complaint by giving it nothing to complain about

The dev server flagged instrumentation.ts on every compile: Next builds the
instrumentation hook for its edge runtime as well as Node, and the edge
compiler statically flags any node: import it can see, including one sitting
inside the NEXT_RUNTIME guard's untaken branch. Moving the imports inside the
function was not enough; the file itself has to be import-free.

It now is. The hook guards and dynamically imports instrumentation-node.ts,
which calls runtime(), the same idempotent door every route handler already
uses, so startup and first-request initialisation are one code path. That
also closed a real hole: the SSE events route called jobManager() directly,
bypassing the door, and would have thrown if a stream were the first request
after a restart. It goes through runtime() now.

Proving the fix caught a false pass on the way. The first retest showed a
clean log because the old dev server was still holding the port and answering
with the old code; the new one had died on EADDRINUSE and the clean log
proved nothing. Verified properly: stale listener killed, fresh server
confirmed Ready, both routes served, zero edge warnings.

The production build's tracer warnings are down from three to one. The
migrations folder joined from import.meta.url up to the repository root was a
real cause and carries the documented turbopackIgnore comment now. The
survivor is the engine's per-review log streams, whose paths only exist at
run time and cannot be static; its consequence is confined to the
standalone-output manifest, which this app does not use. Accepted and
recorded in DECISIONS.md with a re-check trigger: adopting output
"standalone" voids the acceptance.

Author: Poolchaos

docs/DECISIONS.md

@@ -614,3 +614,26 @@ verified evidence, in writing, here.
 - 2026-07-31 DECIDED (W7): no colour in the demo output. Escape sequences are
   control characters, which the house style gate refuses, and the output is
   written to a file as evidence where escapes are noise rather than emphasis.
+- 2026-07-31 FIXED: the dev server flagged instrumentation.ts on every
+  compile ("A Node.js module is loaded ('node:os') which is not supported in
+  the Edge Runtime"). Next compiles the instrumentation hook for its edge
+  runtime as well as Node, and the edge compiler statically flags any node:
+  import it can see, including one inside the NEXT_RUNTIME guard's untaken
+  branch. The hook now imports nothing: it guards, then dynamically imports
+  instrumentation-node.ts, which simply calls runtime(), the same idempotent
+  door every route handler uses. The SSE events route previously bypassed
+  that door by calling jobManager() directly, and would have thrown if it
+  were the first request after a restart; it goes through runtime() now.
+- 2026-07-31 ACCEPTED: one Turbopack build warning remains ("Encountered
+  unexpected file in NFT list"). Root cause established, not assumed: the
+  engine's process spawner opens per-review log streams at paths only known
+  at run time, and Next's file tracer treats a filesystem operation with a
+  dynamic path as "the whole project might ship", so the standalone output
+  manifest over-includes. The paths cannot be static, because they live
+  under the user's data directory per review. The consequence is confined
+  to the standalone-output file manifest, which this app does not use: it
+  runs with next start from the repository. A second cause, the migrations
+  folder joined from import.meta.url up to the repository root, was real
+  and is fixed with the documented turbopackIgnore comment. Re-check
+  trigger: if the app ever adopts output "standalone", this acceptance is
+  void and the warning must be resolved.

src/app/api/reviews/[id]/events/route.ts

@@ -5,8 +5,8 @@
  * SQLite handle and spawns processes, neither of which the edge runtime can do.
  */
 
-import { jobManager } from "@/server/jobs/manager";
 import { reviewEventStream } from "@/server/jobs/stream";
+import { runtime as appRuntime } from "@/server/runtime";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
@@ -16,5 +16,7 @@ export async function GET(
   context: { params: Promise<{ id: string }> },
 ): Promise<Response> {
   const { id } = await context.params;
-  return reviewEventStream(jobManager(), id, request);
+  // Through runtime() like every other handler, so a stream opened as the
+  // first request after a restart still finds an initialised manager.
+  return reviewEventStream(appRuntime().manager, id, request);
 }

src/instrumentation-node.ts

@@ -0,0 +1,14 @@
+/**
+ * The Node side of startup.
+ *
+ * Imported dynamically from `instrumentation.ts` only when the runtime is
+ * Node, so the edge compilation of the instrumentation hook never sees a
+ * node: import. The work itself is `runtime()`, the same idempotent door
+ * every route handler uses: it opens the database once per process, migrates,
+ * and recovers orphaned reviews, and calling it here simply makes that happen
+ * at server start instead of at the first request.
+ */
+
+import { runtime } from "@/server/runtime";
+
+runtime();

src/instrumentation.ts

@@ -1,29 +1,20 @@
 /**
  * What runs once, when the server starts.
  *
- * Next calls `register()` a single time per server process, which is the only
- * hook that fits work that must not run per request: opening the database,
- * migrating it, and recovering reviews that a previous process left marked as
- * running. A review in that state cannot be running, because nothing survived
- * the restart that could be running it, and until it is recovered it can
- * neither be started nor cancelled.
+ * Next compiles this file for its edge runtime as well as for Node, and the
+ * edge compiler statically flags any node: import it can see, including one
+ * inside an unreached branch. So this file imports nothing at all: the guard
+ * decides the runtime, and the Node-only work lives in `instrumentation-node`,
+ * reached through a dynamic import the edge build does not follow.
  *
- * Every import is inside the function and behind the runtime check. Next builds
- * this file for its edge runtime as well, where none of it can load, and a
- * top-level import of anything touching node:path fails that build.
+ * The work itself is opening the database, migrating it, and recovering
+ * reviews a previous process left marked as running. A review in that state
+ * cannot be running, because nothing survived the restart that could be
+ * running it, and until it is recovered it can neither be started nor
+ * cancelled.
  */
 
 export async function register(): Promise<void> {
   if (process.env.NEXT_RUNTIME !== "nodejs") return;
-
-  const { homedir } = await import("node:os");
-  const { dbPath, resolveDataDir } = await import("@/lib/paths");
-  const { createDb } = await import("@/server/db/client");
-  const { runMigrations } = await import("@/server/db/migrate");
-  const { jobManager } = await import("@/server/jobs/manager");
-
-  const dataDir = resolveDataDir(process.env, homedir());
-  const db = createDb(dbPath(dataDir));
-  runMigrations(db);
-  jobManager().init({ db, dataDir });
+  await import("./instrumentation-node");
 }

src/server/db/migrate.ts

@@ -13,9 +13,12 @@ import type { Db } from "./client";
 
 // Assembled from parts rather than written as one URL literal, because a
 // bundler reads `new URL("../../../drizzle", import.meta.url)` as a module it
-// should resolve and fails the build. This is a directory read at run time.
+// should resolve and fails the build. The ignore comment stops Turbopack's
+// file tracer from reading a join that reaches the repository root as "the
+// whole repository ships": this is a directory read at run time, never
+// bundled.
 const MIGRATIONS_FOLDER = join(
-  dirname(fileURLToPath(import.meta.url)),
+  /* turbopackIgnore: true */ dirname(fileURLToPath(import.meta.url)),
   "..",
   "..",
   "..",