fix(realtime): post-review polish from final branch review

Five fixes surfaced by the branch-wide code review on the realtime layer:

- server.ts: replace dynamic `import("@repo/auth/di/container")` with a
  static top-of-file import. The dynamic-import workaround from 6a0ac63 is
  no longer needed once the root tsconfig + TSX_TSCONFIG_PATH expose
  decorator metadata to tsx; verified by booting `pnpm dev` clean.
- server.ts: correct the inline structural type for `validateSession` to
  match the real `IAuthenticationService` contract (non-nullable, throws
  on invalid session) and wrap the call in try/catch so unauthenticated
  bubbles to a `null` return instead of dead-code `result ? ... : null`.
- bind-production.ts: extract `maybeRegisterRealtimePing()` that wraps the
  built-in ping inbound handler in the same `withSpan(withCapture(...))`
  sandwich the realtime-handler generator emits (R41–R44), so the
  proof-of-life channel models the convention rather than registering raw.
- bind-production.test.ts: add 4 tests for the `REALTIME_PING_DISABLED`
  env-gate (registered when unset in both binders, not registered when
  "true", treated as enabled when "1").
- docs/guides/realtime.md: correct the integration-test reference at
  line 285 — the test does not call `bindAllDevSeed()`; it builds the
  Socket.IO server inline and exercises gates 1+2 only (gates 3+4 live in
  socket-io-realtime-server.test.ts).
- adr-016: add a "Known follow-ups" section recording 6 lower-priority
  refinements deferred from this branch (bridge stub test scaffolding,
  registry register/registerChannel precedence, channel-template dot
  constraint, server bare catch{}, BindAllDeps Partial widening, AGENTS.md
  anchor count phrasing).

CI gates: lint 0 errors / 4 warnings (pre-existing turbo.json warnings),
typecheck clean, 24 web-next tests pass (was 20; 4 new env-gate tests),
boundaries 0 issues across 504 files.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/web-next/src/server/bind-production.test.ts

@@ -192,6 +192,48 @@ describe("bindAll dispatcher", () => {
   });
 });
 
+describe("realtime-ping registration (REALTIME_PING_DISABLED env-gate)", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("registers realtime.ping when REALTIME_PING_DISABLED is unset (production)", async () => {
+    const { bindAllProduction } = await import("./bind-production");
+    const deps = makeDeps();
+    await bindAllProduction(deps);
+    expect(deps.realtimeRegistry.listChannels().map((d) => d.name)).toContain("realtime.ping");
+  });
+
+  it("registers realtime.ping when REALTIME_PING_DISABLED is unset (dev seed)", async () => {
+    const { bindAllDevSeed } = await import("./bind-production");
+    const deps = makeDeps();
+    await bindAllDevSeed(deps);
+    expect(deps.realtimeRegistry.listChannels().map((d) => d.name)).toContain("realtime.ping");
+  });
+
+  it("does NOT register realtime.ping when REALTIME_PING_DISABLED='true'", async () => {
+    vi.stubEnv("REALTIME_PING_DISABLED", "true");
+    const { bindAllProduction } = await import("./bind-production");
+    const deps = makeDeps();
+    await bindAllProduction(deps);
+    expect(deps.realtimeRegistry.listChannels().map((d) => d.name)).not.toContain("realtime.ping");
+  });
+
+  it("treats REALTIME_PING_DISABLED='1' as not-disabled (only literal 'true' disables)", async () => {
+    vi.stubEnv("REALTIME_PING_DISABLED", "1");
+    const { bindAllDevSeed } = await import("./bind-production");
+    const deps = makeDeps();
+    await bindAllDevSeed(deps);
+    expect(deps.realtimeRegistry.listChannels().map((d) => d.name)).toContain("realtime.ping");
+  });
+});
+
 describe("bindAll instrumentation orthogonality (Rule 0, R47)", () => {
   beforeEach(() => {
     vi.resetModules();

apps/web-next/src/server/bind-production.ts

@@ -7,6 +7,8 @@ import config from "@repo/core-cms";
 import {
   bindNoopInstrumentation,
   bindSentryInstrumentation,
+  withCapture,
+  withSpan,
   type ITracer,
   type ILogger,
 } from "@repo/core-shared/instrumentation";
@@ -121,9 +123,7 @@ export async function bindAllProduction(deps: BindAllDeps): Promise<void> {
   bindProductionMarketingPages(resolvedConfig, tracer, logger, bus, queue, realtime, realtimeRegistry); // Phase E task 20
   bindProductionNavigation(resolvedConfig, tracer, logger, bus, queue, realtime, realtimeRegistry); // Phase E task 21
   bindProductionMedia(resolvedConfig, tracer, logger, bus, queue, realtime, realtimeRegistry); // Phase E task 22
-  if (process.env.REALTIME_PING_DISABLED !== "true") {
-    realtimeRegistry.register(realtimePingInboundDescriptor(realtime));
-  }
+  maybeRegisterRealtimePing(realtimeRegistry, realtime, tracer, logger);
   bindRealtimeBridge(bus, realtime);
 }
 
@@ -143,9 +143,7 @@ export async function bindAllDevSeed(deps: BindAllDeps): Promise<void> {
   await bindDevSeedMarketingPages(tracer, logger, bus, queue, realtime, realtimeRegistry); // Phase E task 20
   await bindDevSeedNavigation(tracer, logger, bus, queue, realtime, realtimeRegistry); // Phase E task 21
   await bindDevSeedMedia(tracer, logger, bus, queue, realtime, realtimeRegistry); // Phase E task 22
-  if (process.env.REALTIME_PING_DISABLED !== "true") {
-    realtimeRegistry.register(realtimePingInboundDescriptor(realtime));
-  }
+  maybeRegisterRealtimePing(realtimeRegistry, realtime, tracer, logger);
   bindRealtimeBridge(bus, realtime);
 }
 
@@ -181,6 +179,30 @@ export async function bindAll(deps?: Partial<BindAllDeps>): Promise<void> {
   await bindAllDevSeed(resolvedDeps);
 }
 
+// Wraps the built-in realtime-ping inbound handler in the same span+capture
+// sandwich the realtime-handler generator emits (R41–R44), so the
+// proof-of-life channel models the convention rather than registering raw.
+// Skipped entirely when REALTIME_PING_DISABLED === "true".
+function maybeRegisterRealtimePing(
+  registry: IRealtimeHandlerRegistry,
+  realtime: IRealtimeBroadcaster,
+  tracer: ITracer,
+  logger: ILogger,
+): void {
+  if (process.env.REALTIME_PING_DISABLED === "true") return;
+  const { descriptor, handler } = realtimePingInboundDescriptor(realtime);
+  const wrappedHandler = withSpan(
+    tracer,
+    { name: "core-realtime.realtimePing", op: "realtime-handler" },
+    withCapture(
+      logger,
+      { feature: "core-realtime", layer: "realtime-handler", name: "core-realtime.realtimePing" },
+      handler,
+    ),
+  );
+  registry.register({ descriptor, handler: wrappedHandler });
+}
+
 function bindRealtimeBridge(_bus: IEventBus, _broadcaster: IRealtimeBroadcaster): void {
   // v1 ships with an empty allowlist. The dashboard PR adds the first entries here.
   // Example shape (commented out so v1 doesn't try to use it):