@hydranium/core 1.0.0-next.10 → 1.0.0-next.103

package/src/testing/make-noop-shared-services.ts

@@ -9,6 +9,8 @@
 
 import { type Clock, DefaultTracer, type Logger, NoopLogger, SystemClock, type Tracer } from '@hydranium/protocol';
 import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 
 /**
  * Overrides for {@link makeNoopSharedServices}. The three observability slots
@@ -29,6 +31,18 @@ export interface NoopSharedServicesOverrides {
    Logger?: Logger;
    /** Bound on the top-level `Tracer` slot. Default: a `DefaultTracer` over `Logger` + `Clock`. */
    Tracer?: Tracer;
+   /** Factory for the `ServerLocale` slot. Default: a real one, reporting no locale. */
+   ServerLocale?: (services: ServerSharedServicesMinimal) => ServerLocale;
+   /**
+    * Factory for the `MessageRenderer` slot. Default: the real
+    * {@link DefaultMessageRenderer}, whose no-catalogue behaviour is a
+    * pass-through — so the default is the framework's own behaviour, not a stub.
+    *
+    * A factory rather than an instance, because a renderer reads the tree it is
+    * bound into. Both slots are resolved lazily, so an override is honoured
+    * however late the caller reads them.
+    */
+   MessageRenderer?: (services: ServerSharedServicesMinimal) => MessageRenderer;
    /** Per-slot `workspace` overrides. Slots left out resolve to `undefined`. */
    workspace?: Record<string, unknown>;
    /** Any other minimal slot (`ServiceRegistry`, `AstReflection`, `additionalDocuments`, …). */
@@ -63,11 +77,21 @@ export interface NoopSharedServicesOverrides {
 export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = ServerSharedServicesMinimal>(
    overrides: NoopSharedServicesOverrides = {}
 ): T {
-   const { Clock: clock, Logger: logger, Tracer: tracer, workspace, additionalDocuments, ...restTop } = overrides;
+   const {
+      Clock: clock,
+      Logger: logger,
+      Tracer: tracer,
+      ServerLocale: serverLocale,
+      MessageRenderer: messageRenderer,
+      workspace,
+      additionalDocuments,
+      ...restTop
+   } = overrides;
    const resolvedClock = clock ?? new SystemClock();
    const resolvedLogger = logger ?? new NoopLogger();
    const resolvedTracer = tracer ?? new DefaultTracer(resolvedLogger, resolvedClock);
-   return {
+   // Assembled in two steps, because both defaults read the tree they belong to.
+   const services = {
       Clock: resolvedClock,
       Logger: resolvedLogger,
       Tracer: resolvedTracer,
@@ -75,4 +99,28 @@ export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = S
       ...restTop,
       workspace: { ...(workspace ?? {}) }
    } as unknown as T;
+   // Lazy, like Langium's own per-slot construction — and load-bearing here:
+   // both services emit an `instantiated` trace, so building them eagerly puts
+   // two lines into the capture of every test that passes a capturing logger
+   // and asserts on emptiness.
+   defineLazySlot(services, 'ServerLocale', () => serverLocale?.(services) ?? new DefaultServerLocale(services));
+   defineLazySlot(services, 'MessageRenderer', () => messageRenderer?.(services) ?? new DefaultMessageRenderer(services));
+   return services;
+}
+
+/** Install `name` as a memoized getter, so nothing is constructed until it is read. */
+function defineLazySlot(target: object, name: string, create: () => unknown): void {
+   let resolved: unknown;
+   let built = false;
+   Object.defineProperty(target, name, {
+      configurable: true,
+      enumerable: true,
+      get: () => {
+         if (!built) {
+            resolved = create();
+            built = true;
+         }
+         return resolved;
+      }
+   });
 }

package/src/testing/make-test-services.ts

@@ -18,11 +18,14 @@ import {
    type TransferDiagnostic,
    type TransferElement
 } from '@hydranium/protocol';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 import type { Harness } from '@hydranium/protocol/testing';
 import { type AstNode, type AstNodeDescription, type WorkspaceLock } from '@hydranium/langium';
 import type { ModelService, ModelServiceOptions } from '../langium/model-service/model-service.js';
 import type { ServerSharedServices } from '../langium/module.js';
-import { TransferEncoder } from '../langium/transfer/transfer-encoder.js';
+import type { AstDiagnostic } from '../langium/validation/document-validator.js';
+import { DefaultTransferEncoder, type TransferEncoder } from '../langium/transfer/transfer-encoder.js';
 import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
 import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
 import type { FakeDocumentOptions } from './fake-document.js';
@@ -46,12 +49,21 @@ import { makeStubWritableFileSystem, type StubWritableFileSystem } from './stub-
  * to `ServerSharedServices` in {@link makeTestServices} is therefore the
  * single named place where the "stub stands in for the full service tree"
  * assertion happens.
+ *
+ * **`TDiagnostic` and `TTransferDiagnostic` are the two ends of a conversion
+ * and must stay separate.** The first is what the build left on
+ * `LangiumDocument.diagnostics` and what `ModelService` hands back on an
+ * `AstDocument`; the second is what `TransferEncoder.toTransferDiagnostic`
+ * produces for the wire. One parameter serving both makes the tree
+ * unbindable for an adopter who extends either shape, since extending one
+ * says nothing about the other.
  */
 export interface TestSharedServices<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
    readonly Clock: Clock;
    readonly Logger: Logger;
@@ -90,17 +102,27 @@ export interface TestSharedServices<
       WorkspaceLock: WorkspaceLock;
    };
    readonly model: {
-      TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+      TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
    };
+   /**
+    * The REAL services, not stubs — the framework renderer's no-catalogue
+    * behaviour is a pass-through, so the stub tree agrees with a production one
+    * unless a test installs a catalogue. Bound rather than omitted because
+    * `HydraniumDocumentBuilder` renders through the renderer on every
+    * `Validated` phase, where an omitted slot is a `TypeError`.
+    */
+   readonly ServerLocale: ServerLocale;
+   readonly MessageRenderer: MessageRenderer;
 }
 
 /** Optional configuration for {@link makeTestServices}. */
 export interface MakeTestServicesOptions<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
    /**
     * Serialiser used by the bundled `StubModelService`. The stub tree
@@ -112,6 +134,14 @@ export interface MakeTestServicesOptions<
     * for tests that don't assert on the produced text.
     */
    serialize?: (uri: string, root: TTransfer) => string;
+   /**
+    * Renderer bound on `MessageRenderer`. Default: the framework's own, which
+    * passes every sentence through unchanged. Supply one to install a catalogue
+    * or to drive the throwing path.
+    */
+   messageRenderer?: (services: ServerSharedServices<TProject>) => MessageRenderer;
+   /** Locale handed to the bundle's {@link ServerLocale}. Default: none, i.e. the framework's English. */
+   locale?: string;
    /**
     * Languages to register on a {@link StubServiceRegistry} bound on the
     * `ServiceRegistry` slot. This is how a test gets multi-language routing:
@@ -187,7 +217,7 @@ export interface MakeTestServicesOptions<
     * Override the {@link TransferEncoder} factory. Default: framework
     * {@link TransferEncoder} with no overrides.
     */
-   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<unknown, TDiagnostic>;
+   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<TTransferDiagnostic>;
 }
 
 /**
@@ -205,9 +235,10 @@ export interface MakeTestServicesOptions<
  */
 export interface TestServicesBundle<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > extends Harness {
    readonly services: ServerSharedServices<TProject>;
    readonly documents: StubLangiumDocuments<TAst, TDiagnostic>;
@@ -229,10 +260,18 @@ export interface TestServicesBundle<
     */
    readonly indexManager: StubIndexManager | undefined;
    readonly modelService: ModelService<TAst, TDiagnostic, TTransfer>;
-   readonly transferEncoder: TransferEncoder<unknown, TDiagnostic>;
+   readonly transferEncoder: TransferEncoder<TTransferDiagnostic>;
    readonly logger: Logger;
    /** The clock bound on the `Clock` slot — a `makeFakeClock()` if one was passed. */
    readonly clock: Clock;
+   /**
+    * The service bound on `ServerLocale`, so a test can hand over a locale
+    * mid-run — which is also how it verifies the renderer reads the locale per
+    * render rather than caching it at construction.
+    */
+   readonly serverLocale: ServerLocale;
+   /** The renderer bound on `MessageRenderer` — the framework's own unless one was supplied. */
+   readonly messageRenderer: MessageRenderer;
 }
 
 /**
@@ -247,12 +286,13 @@ export interface TestServicesBundle<
  */
 export function makeTestServices<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 >(
-   options: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject> = {}
-): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject> {
+   options: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> = {}
+): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> {
    const documents = makeStubLangiumDocuments<TAst, TDiagnostic>(options.seedDocuments);
    const textDocuments = makeStubHydraniumTextDocuments();
    const documentBuilder = makeStubDocumentBuilder();
@@ -289,7 +329,7 @@ export function makeTestServices<
    // (after the factories run); the literal uses unsafe casts to
    // partially-built objects to satisfy TestSharedServices, then patches
    // them in.
-   const services: TestSharedServices<TAst, TDiagnostic, TTransfer, TProject> = {
+   const services: TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> = {
       Clock: clock,
       Logger: logger,
       Tracer: tracer,
@@ -311,20 +351,33 @@ export function makeTestServices<
          ...(indexManager ? { IndexManager: indexManager } : {}),
          WorkspaceLock: new HydraniumWorkspaceLock()
       },
-      model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject>['model']
+      model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic>['model'],
+      ServerLocale: {} as ServerLocale,
+      MessageRenderer: {} as DefaultMessageRenderer
    };
    const sharedServices = services as unknown as ServerSharedServices<TProject>;
 
+   // Patched in after the literal, like `model` below: both read the tree they
+   // belong to, and the renderer reads the locale service.
+   const mutableMessages = services as { ServerLocale: ServerLocale; MessageRenderer: MessageRenderer };
+   const serverLocale = new DefaultServerLocale(sharedServices);
+   if (options.locale) {
+      serverLocale.accept(options.locale);
+   }
+   mutableMessages.ServerLocale = serverLocale;
+   const messageRenderer = options.messageRenderer?.(sharedServices) ?? new DefaultMessageRenderer(sharedServices);
+   mutableMessages.MessageRenderer = messageRenderer;
+
    const serialize = options.serialize ?? ((_uri: string, root: TTransfer) => JSON.stringify(root));
    const transferEncoder = options.transferEncoder
       ? options.transferEncoder(sharedServices)
-      : new TransferEncoder<unknown, TDiagnostic>(sharedServices);
+      : new DefaultTransferEncoder<unknown, TTransferDiagnostic>(sharedServices);
    const modelService = options.modelService
       ? options.modelService(sharedServices)
       : makeStubModelService<TAst, TDiagnostic, TTransfer>(sharedServices, serialize, options.modelServiceOptions);
 
    const mutableModel = services.model as {
-      TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+      TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
    };
    mutableModel.TransferEncoder = transferEncoder;
@@ -346,6 +399,8 @@ export function makeTestServices<
       transferEncoder,
       logger,
       clock,
+      serverLocale,
+      messageRenderer,
       dispose: () => {
          // No-op: the bundled stubs hold only in-memory state (maps, arrays),
          // released with the bundle when it goes out of scope. The hook exists

package/src/testing/node/scratch-workspace.ts

@@ -21,8 +21,8 @@
  * committed sample workspace can **rewrite the sample files**, after which
  * every later run asserts against already-repaired input: a suite that passes
  * while testing nothing. The same applies to a fixture built in place, which
- * additionally loses its explanatory comments, because the write-back goes
- * through the serializer.
+ * additionally comes back in the serializer's layout, because the write-back
+ * goes through it.
  *
  * The second reason is cleanup. Hand-rolled `mkdtempSync` without a matching
  * `rmSync` leaks a directory per test run into the OS temp dir, which nobody
@@ -49,7 +49,7 @@
  */
 
 import { URI } from '@hydranium/langium';
-import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 
@@ -106,7 +106,12 @@ export interface ScratchWorkspace {
  * returned {@link ScratchWorkspace.dispose} with an `afterEach`.
  */
 export function makeScratchWorkspace(options: ScratchWorkspaceOptions = {}): ScratchWorkspace {
-   const root = mkdtempSync(path.join(tmpdir(), options.prefix ?? 'hydranium-scratch-'));
+   // RESOLVED, because `tmpdir()` can itself be a symlink — on macOS it answers
+   // `/tmp`, which links to `/private/tmp`. A root the server canonicalises to a
+   // different path than the one it was handed registers documents under one
+   // spelling and reads them under the other, failing initialization with an
+   // ENOENT that names neither the link nor this call.
+   const root = realpathSync(mkdtempSync(path.join(tmpdir(), options.prefix ?? 'hydranium-scratch-')));
    if (options.seed) {
       cpSync(options.seed, root, { recursive: true });
    }

package/src/testing/node/spawned-server.ts

@@ -203,6 +203,37 @@ export interface SpawnedServer extends Harness {
    dispose(): Promise<number | null>;
 }
 
+/**
+ * Every server started and not yet disposed, so {@link disposeSpawnedServers}
+ * can reach one a test forgot.
+ *
+ * Holds the server — and through it the `ChildProcess` — rather than a pid. A
+ * pid identifies a process only while that process is alive: once it exits the
+ * OS may reissue the number, and Windows does so within seconds. A teardown
+ * that signalled a recorded pid would therefore reach whatever holds it now,
+ * which on a concurrent build is another task's compiler or test runner.
+ */
+const liveServers = new Set<SpawnedServer>();
+
+/**
+ * Terminate every server this module started that has not been disposed, and
+ * forget them.
+ *
+ * Safe to call when none are outstanding, and safe to call twice. Nothing here
+ * can reach a process this module did not spawn, because every kill goes
+ * through the `ChildProcess` handle libuv holds and libuv will not signal a
+ * child it has already reaped.
+ *
+ * A suite that disposes each server as it finishes needs this only as a net; a
+ * suite that does not needs it, because an orphan holding a port or a pipe
+ * makes the NEXT run's verdict meaningless.
+ */
+export async function disposeSpawnedServers(): Promise<void> {
+   const outstanding = [...liveServers];
+   liveServers.clear();
+   await Promise.all(outstanding.map(server => server.dispose()));
+}
+
 /** The captured streams, quoted into a boot-failure message. */
 function bootDiagnosis(stdoutPrefix: string, stderr: string): string {
    return (
@@ -390,7 +421,7 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
       return exitCode;
    }
 
-   return {
+   const server: SpawnedServer = {
       connection,
       pid: child.pid,
       initializeResult,
@@ -440,8 +471,11 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
          });
       },
       dispose(): Promise<number | null> {
+         liveServers.delete(server);
          disposal ??= terminate();
          return disposal;
       }
    };
+   liveServers.add(server);
+   return server;
 }

package/src/testing/playwright/flaky-network-proxy.ts

@@ -0,0 +1,240 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import { connect, createServer as createTcpServer, type Server as TcpServer, type Socket } from 'node:net';
+
+/**
+ * A TCP proxy that can half-close a connection, so an e2e suite can reproduce a
+ * flaky network against a real browser session.
+ *
+ * Toggling the browser offline is not enough. On localhost the server sees the
+ * close immediately and reaps the socket before the browser reconnects, so the
+ * window where both sides disagree about the session — the one where reconnect
+ * defects live — never opens. Reaching it needs the browser's socket to die
+ * while the server still believes it is alive, and nothing inside the app or in
+ * Playwright's offline emulation can produce that asymmetry: both close cleanly
+ * at both ends.
+ *
+ * The proxy holds both halves of every connection and lets a test kill them
+ * independently:
+ *
+ *   `break`    destroy the BROWSER-side sockets, keep the server-side ones open.
+ *              The browser reconnects through a fresh pair while the server
+ *              still holds the old one.
+ *   `release`  destroy the orphaned server-side sockets `break` left. The
+ *              server's disconnect handler fires at once, rather than whenever
+ *              its next heartbeat write would have failed.
+ */
+
+/** Where the proxy listens, and the application it fronts. */
+export interface FlakyNetworkProxyOptions {
+   /** Port the browser connects to. */
+   readonly listenPort: number;
+   /** Port of the application being proxied. */
+   readonly targetPort: number;
+   /** Host of the application being proxied. Defaults to loopback. */
+   readonly targetHost?: string;
+   /** Port the HTTP control channel listens on. Defaults to `listenPort + 1000`. */
+   readonly controlPort?: number;
+}
+
+/** The commands the control channel accepts, and the proxy's own vocabulary. */
+export type FlakyNetworkCommand = 'break' | 'release' | 'status';
+
+/** Drives a running proxy. Implemented both in-process and over HTTP. */
+export interface FlakyNetworkControl {
+   /** Kill the browser side of every live connection; leave the server side up. */
+   break(): Promise<string>;
+   /** Kill the server side of every connection `break` orphaned. */
+   release(): Promise<string>;
+   /** How many connections are live and how many are orphaned. */
+   status(): Promise<string>;
+}
+
+export interface FlakyNetworkProxy extends FlakyNetworkControl {
+   /** Base URL a browser should be pointed at, i.e. Playwright's `baseURL`. */
+   readonly url: string;
+   /** Control channel, for workers that cannot reach this object directly. */
+   readonly controlUrl: string;
+   close(): Promise<void>;
+}
+
+interface ConnectionPair {
+   readonly id: number;
+   readonly browserSocket: Socket;
+   readonly targetSocket: Socket;
+   orphaned: boolean;
+}
+
+/**
+ * Starts the proxy in the calling process.
+ *
+ * Call it from a Playwright config, which runs in the main process before any
+ * worker forks. Workers are separate processes and cannot reach the returned
+ * object, which is what {@link controlUrl} and {@link flakyNetworkControlClient}
+ * are for.
+ */
+export async function startFlakyNetworkProxy(options: FlakyNetworkProxyOptions): Promise<FlakyNetworkProxy> {
+   const targetHost = options.targetHost ?? '127.0.0.1';
+   const controlPort = options.controlPort ?? options.listenPort + 1000;
+   const pairs = new Set<ConnectionPair>();
+   let sequence = 0;
+   let transcript: string[] = [];
+
+   const log = (message: string): void => {
+      transcript.push(message);
+      console.log(`[flaky-network] ${message}`);
+   };
+
+   const proxyServer: TcpServer = createTcpServer(browserSocket => {
+      const id = ++sequence;
+      const targetSocket = connect(options.targetPort, targetHost);
+      const pair: ConnectionPair = { id, browserSocket, targetSocket, orphaned: false };
+      pairs.add(pair);
+
+      // Forwarded by hand rather than with `pipe()`, so killing one side does not
+      // tear the other down — which is the entire point of the proxy.
+      browserSocket.on('data', chunk => {
+         if (!targetSocket.destroyed) {
+            targetSocket.write(chunk);
+         }
+      });
+      targetSocket.on('data', chunk => {
+         if (!pair.orphaned && !browserSocket.destroyed) {
+            browserSocket.write(chunk);
+         }
+      });
+
+      const teardown = (origin: 'browser' | 'target'): void => {
+         if (pair.orphaned && origin === 'browser') {
+            // Expected: `break` killed this side deliberately. The server side
+            // stays up until `release`.
+            return;
+         }
+         pairs.delete(pair);
+         browserSocket.destroy();
+         targetSocket.destroy();
+      };
+
+      browserSocket.on('close', () => teardown('browser'));
+      targetSocket.on('close', () => teardown('target'));
+      // A half-killed pair reliably raises ECONNRESET on the surviving side; an
+      // unhandled 'error' would take the whole runner down with it.
+      browserSocket.on('error', () => undefined);
+      targetSocket.on('error', () => undefined);
+   });
+
+   const commands: Record<FlakyNetworkCommand, () => void> = {
+      break: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned);
+         if (live.length === 0) {
+            log('nothing to break');
+            return;
+         }
+         for (const pair of live) {
+            pair.orphaned = true;
+            pair.browserSocket.destroy();
+         }
+         log(`${live.length} connection(s) broken; the browser should reconnect shortly`);
+      },
+      release: () => {
+         const orphans = [...pairs].filter(pair => pair.orphaned);
+         if (orphans.length === 0) {
+            log('no orphaned connections; run `break` first');
+            return;
+         }
+         for (const pair of orphans) {
+            pairs.delete(pair);
+            pair.targetSocket.destroy();
+         }
+         log(`${orphans.length} orphaned connection(s) destroyed; their late disconnect fires now`);
+      },
+      status: () => {
+         const live = [...pairs].filter(pair => !pair.orphaned).length;
+         const orphaned = pairs.size - live;
+         log(`${live} live, ${orphaned} orphaned`);
+      }
+   };
+
+   const run = (name: string): string => {
+      transcript = [];
+      const command = commands[name as FlakyNetworkCommand];
+      if (command) {
+         command();
+      } else {
+         log(`unknown command '${name}'; use: ${Object.keys(commands).join(' | ')}`);
+      }
+      return transcript.join('\n');
+   };
+
+   const controlServer: HttpServer = createHttpServer((request, response) => {
+      const output = run((request.url ?? '').replace(/^\//, '').split('?')[0]);
+      response.writeHead(200, { 'content-type': 'text/plain' });
+      response.end(`${output}\n`);
+   });
+
+   await Promise.all([listen(proxyServer, options.listenPort), listen(controlServer, controlPort)]);
+   // Neither server keeps the process alive, so a runner that starts one from a
+   // config does not need a teardown hook to exit — and a caller that wants a
+   // deterministic shutdown still has `close()`.
+   proxyServer.unref();
+   controlServer.unref();
+
+   return {
+      url: `http://localhost:${options.listenPort}`,
+      controlUrl: `http://localhost:${controlPort}`,
+      break: async () => run('break'),
+      release: async () => run('release'),
+      status: async () => run('status'),
+      close: async () => {
+         for (const pair of pairs) {
+            pair.browserSocket.destroy();
+            pair.targetSocket.destroy();
+         }
+         pairs.clear();
+         await Promise.all([close(proxyServer), close(controlServer)]);
+      }
+   };
+}
+
+/**
+ * Drives a proxy running in another process, over its control channel.
+ *
+ * This is what a spec uses: Playwright workers are separate processes from the
+ * config that started the proxy.
+ */
+export function flakyNetworkControlClient(controlUrl: string): FlakyNetworkControl {
+   const send = async (command: FlakyNetworkCommand): Promise<string> => {
+      const response = await fetch(`${controlUrl}/${command}`);
+      if (!response.ok) {
+         throw new Error(`flaky-network proxy rejected '${command}': ${response.status}`);
+      }
+      return (await response.text()).trim();
+   };
+   return {
+      break: () => send('break'),
+      release: () => send('release'),
+      status: () => send('status')
+   };
+}
+
+function listen(server: TcpServer | HttpServer, port: number): Promise<void> {
+   return new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, () => {
+         server.off('error', reject);
+         resolve();
+      });
+   });
+}
+
+function close(server: TcpServer | HttpServer): Promise<void> {
+   return new Promise(resolve => server.close(() => resolve()));
+}

package/src/testing/playwright/index.ts

@@ -11,6 +11,7 @@
 // `@hydranium/core/testing` barrel) so importing the framework's unit-test
 // helpers never pulls in `@playwright/test` — which is an OPTIONAL peer here.
 export * from './e2e-profiling.js';
+export * from './flaky-network-proxy.js';
 export * from './browser-capture-bridge.js';
 export * from './server-log-capture.js';
 export * from './server-log-fixture.js';

package/src/testing/playwright/server-log-capture.ts

@@ -160,16 +160,28 @@ export function serverLogSpecName(file: string): string {
  * Rename each `<token>.log` (backend) and `<token>.browser.log` (forwarded
  * browser console) to the spec name recorded in its `<token>.spec` sidecar
  * (written by {@link markServerLog}), then delete the sidecar. Colliding names —
- * a spec that opened more than one workspace — get a `-2`, `-3`, … suffix. Token
- * logs without a sidecar are left untouched. Run once, after all server processes
- * have exited (e.g. a reporter's `onEnd`). Best-effort.
+ * a spec that opened more than one workspace — get a `-2`, `-3`, … suffix. Run
+ * once, after all server processes have exited (e.g. a reporter's `onEnd`).
+ * Best-effort.
+ *
+ * Returns the workspace tokens left UNATTRIBUTED — a log the capture wrote that
+ * no test claimed, because that spec never reached
+ * {@link markServerLog} (no `serverLog` fixture, no `beforeEach` call).
+ *
+ * **Returned rather than ignored, because the unattributed state is the
+ * misleading one.** Such a log still exists, still has content, and is named by
+ * an opaque token with no test boundaries in it — so a capture run that covered
+ * nothing looks exactly like one that covered everything, and the logs are
+ * there to be read. A caller that can warn should warn.
  */
-export function renameServerLogs(dir: string): void {
+export function renameServerLogs(dir: string): string[] {
    let entries: string[];
    try {
       entries = readdirSync(dir);
    } catch {
-      return;
+      // An unreadable capture dir has nothing to report — including nothing
+      // unattributed, since no log was observed at all.
+      return [];
    }
    // Per suffix (`.log`, `.browser.log`) a `taken` set guards collisions, so the
    // backend and browser logs for one spec share the same friendly base name.
@@ -190,6 +202,11 @@ export function renameServerLogs(dir: string): void {
          // ignore
       }
    };
+   // Every token the capture produced a backend log for, so the ones no sidecar
+   // claims can be reported rather than silently left behind.
+   const unattributed = new Set(
+      entries.filter(entry => entry.endsWith('.log') && !entry.endsWith('.browser.log')).map(entry => entry.slice(0, -'.log'.length))
+   );
    for (const entry of entries) {
       if (!entry.endsWith('.spec')) {
          continue;
@@ -210,9 +227,11 @@ export function renameServerLogs(dir: string): void {
       if (!name) {
          continue;
       }
+      unattributed.delete(token);
       rename(token, name, '.log');
       rename(token, name, '.browser.log');
    }
+   return [...unattributed];
 }
 
 /**