@reicek/neataptic-ts 0.1.27 → 0.1.29

package/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-When generating, modifying, or suggesting code that touches files under `src/` or `test/`, follow the project `STYLEGUIDE.md` rules and perform the quick validations listed below before returning suggestions.
+When generating, modifying, or suggesting code that touches files under `src/`, `testing/`, `benchmarks/`, or `examples/`, follow the project `STYLEGUIDE.md` rules and perform the quick validations listed below before returning suggestions.
 
 ## Educational docs preference (JSDoc)
 
@@ -70,7 +70,7 @@ a compressed plan plus matching log.
 
 For split or refactor work with meaningful documentation scope, let `solid-split` own the boundary work and `educational-docs` own documentation quality.
 
-When you touch code under `src/` or `test/`, prefer improving JSDoc so the generated docs are:
+When you touch code under `src/`, `testing/`, `benchmarks/`, or `examples/`, prefer improving JSDoc so the generated docs are:
 
 - **Interesting and explanatory**, not just type signatures.
 - **Example-driven**: include small examples in the main description (prefer fenced code blocks like ```ts) so the docs generator preserves them.
@@ -109,7 +109,7 @@ When a task touches `.github/workflows/**`, `package.json`, `package-lock.json`,
 
 Because JSDoc is auto-compiled into each folder's `README.md`, those README files are the fastest condensed overview of a module's purpose, exported surface, neighboring files, and intended usage.
 
-Before exploring or editing a folder in `src/` or `test/`, agents should:
+Before exploring or editing a folder in `src/`, `examples/`, `benchmarks/`, or `testing/`, agents should:
 
 1. Read the nearest folder `README.md` first.
    - Example: before changing `src/architecture/network/genetic/*`, read `src/architecture/network/genetic/README.md`.
@@ -137,7 +137,7 @@ belong in that skill.
 
 ## Demo-first library gap policy (critical)
 
-Examples and demos in `test/examples/` are not places to normalize library ergonomics gaps. They are probes that should reveal where the public API, defaults, or runtime contracts fall short of world-class expectations.
+Examples and demos in `examples/` are not places to normalize library ergonomics gaps. They are probes that should reveal where the public API, defaults, or runtime contracts fall short of world-class expectations.
 
 When demo work exposes a mismatch between obvious user intent and the library behavior:
 
@@ -206,7 +206,7 @@ Avoid (legacy/less clear):
 
 ## Standard architecture for project files
 
-When splitting medium or large modules in `src/` or `test/`, prefer a dedicated folder-based module boundary instead of accumulating many sibling files at the parent level.
+When splitting medium or large modules in `src/`, `examples/`, `benchmarks/`, or `testing/`, prefer a dedicated folder-based module boundary instead of accumulating many sibling files at the parent level.
 
 Use this naming convention for a module named `module`:
 
@@ -243,7 +243,7 @@ Architecture rules:
 - Avoid one-off naming patterns during refactors; once a module is folderized, keep all follow-up files in the same naming scheme.
 - Replace broad catch-all files with narrower module-owned `*.types.ts`, `*.services.ts`, or `*.utils.ts` files rather than recreating another hub.
 
-## Strict rules to enforce (apply to any suggestion touching `src/` or `test/`)
+## Strict rules to enforce (apply to any suggestion touching `src/`, `testing/`, `benchmarks/`, or `examples/`)
 
 1. Naming: avoid short local identifiers. Do not use these short names for non-trivial locals: `dx`, `dy`, `d`, `i`, `a`, `b`, `c`, `p`, `o`, `cand`, `tries`, `idx`.
    - If the original code uses a short name in a tiny loop (1–3 lines) and it is clearly idiomatic, allow `i`, `j` only.
@@ -251,7 +251,7 @@ Architecture rules:
 
 2. JSDoc: exported classes/functions/constants and public methods must have JSDoc with `@param` and `@returns` where appropriate. Add short `@example` when behavior is non-obvious.
 
-   JSDoc-for-constants rule: All exported or shared default constants in `src/` and `test/` must include a concise educational JSDoc explaining what the value controls (e.g., decay factor meaning, floor rates). Keep descriptions short and clarifying.
+  JSDoc-for-constants rule: All exported or shared default constants in `src/`, `testing/`, `benchmarks/`, and `examples/` must include a concise educational JSDoc explaining what the value controls (e.g., decay factor meaning, floor rates). Keep descriptions short and clarifying.
 
 3. Tests: follow the single-expect rule. Each `it()` (or `test()`) must have exactly one top-level `expect(...)` statement. If multiple assertions are needed, split into multiple `it()` cases or use helper assertions.
 
@@ -261,7 +261,7 @@ Architecture rules:
 
 6. Lookup tables and enums: prefer a single table/enum for small fixed mappings (for example direction deltas) and helper methods like `#opposite(direction)` rather than scattered arithmetic.
 
-7. Types: avoid `any` and `unknown` in `src/` and `test/`. Use precise types or `// eslint-disable-next-line @typescript-eslint/no-explicit-any` with a short justification comment.
+7. Types: avoid `any` and `unknown` in `src/`, `testing/`, `benchmarks/`, and `examples/`. Use precise types or `// eslint-disable-next-line @typescript-eslint/no-explicit-any` with a short justification comment.
 
 8. Local helper structure preference:
    - For new or refactored functions that introduce internal helpers, order the function as:
@@ -272,7 +272,7 @@ Architecture rules:
    - Helpers should be small and pure where practical, with step-level inline comments and JSDoc.
 
 9. Mandatory implementation pattern (always; keep cognitive complexity low):
-   - Applies to all new code and any modified/refactored code in `src/` and `test/`.
+  - Applies to all new code and any modified/refactored code in `src/`, `testing/`, `benchmarks/`, and `examples/`.
    - Prefer a _declarative top-level flow_ ("collect → transform → fold/return") over deeply nested control flow.
    - Avoid ternary chains (especially nested) for multi-branch fallback logic; use named resolver helpers with early returns instead.
    - When normalizing legacy/loose data, isolate type assertions/casting into a single helper and keep the rest strongly typed.
@@ -332,7 +332,7 @@ type Output = unknown;
 
 ## Automated validations to run before finalizing a suggestion
 
-When you modify or create files under `src/` or `test/`, run (or advise running) these quick validations. If you cannot run them, still make sure your suggestion would pass them.
+When you modify or create files under `src/`, `testing/`, `benchmarks/`, or `examples/`, run (or advise running) these quick validations. If you cannot run them, still make sure your suggestion would pass them.
 
 1. TypeScript diagnostics
 
@@ -340,7 +340,7 @@ When you modify or create files under `src/` or `test/`, run (or advise running)
 
    ## Purpose
 
-   Give brief, actionable guidance so suggestions touching `src/` or `test/` prioritize compliance with `STYLEGUIDE.md`.
+  Give brief, actionable guidance so suggestions touching `src/`, `testing/`, `benchmarks/`, or `examples/` prioritize compliance with `STYLEGUIDE.md`.
 
    Keep it light: prefer small, automated checks and a short validation summary with every patch.
 

package/.github/skills/educational-docs/SKILL.md

@@ -72,7 +72,7 @@ better teaching choice.
 - A generated folder README has become so large or monolithic that the better
   fix is to invoke `solid-split` and break the boundary into smaller chapter
   folders before continuing the docs pass.
-- A folder under `src/` or `test/` needs richer JSDoc so doc generation becomes
+- A folder under `src/`, `examples/`, `benchmarks/`, or `testing/` needs richer JSDoc so doc generation becomes
   more useful.
 - A split or refactor changed a module boundary and the documentation story now
   lags behind the code.

package/.github/skills/educational-docs/assets/readme-tone-model.md

@@ -1,7 +1,7 @@
 # README Tone Model
 
 Use this rubric when shaping JSDoc so generated README output feels closer to
-`test/examples/flappy_bird/README.md` and farther from a dry symbol dump.
+`examples/flappy_bird/README.md` and farther from a dry symbol dump.
 
 ## What Makes The Flappy Bird README Strong
 

package/.github/skills/educational-docs/assets/visual-style-guide.md

@@ -24,7 +24,7 @@ poster.
 ## Canonical Palette
 
 Anchor the look to the Astro Bird constants in
-`test/examples/flappy_bird/constants/constants.palette.ts`.
+`examples/flappy_bird/constants/constants.palette.ts`.
 
 Primary colors:
 

package/.github/skills/solid-split/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: solid-split
-description: 'Plan and execute repo-consistent SOLID splits in NeatapticTS across src/ or test/, starting from a user-specified root such as #file:flappy_bird. Use when folderizing a module, thinning a compatibility facade, improving JSDoc so generated README files read naturally, or continuing an incremental split pass with stable imports.'
+description: 'Plan and execute repo-consistent SOLID splits in NeatapticTS across src/, examples/, benchmarks/, or testing/ surfaces, starting from a user-specified root such as #file:flappy_bird. Use when folderizing a module, thinning a compatibility facade, improving JSDoc so generated README files read naturally, or continuing an incremental split pass with stable imports.'
 argument-hint: 'Describe the split root, target module or folder, any relevant plan file, and optional detail about the next boundary to extract.'
 user-invocable: true
 disable-model-invocation: false
@@ -9,8 +9,8 @@ disable-model-invocation: false
 # Solid Split Playbook
 
 Use this skill to run the NeatapticTS house style for deliberate, resumable,
-documentation-aware SOLID splits in either library code under `src/` or demos
-and examples under `test/`.
+documentation-aware SOLID splits in either library code under `src/` or
+supporting surfaces under `examples/`, `benchmarks/`, and `testing/`.
 
 This skill is designed to complement the existing `solid-split` custom agent.
 The skill defines the repository-specific split protocol, documentation bar,
@@ -170,7 +170,7 @@ one-pass rewrites.
 - Keep top-level flows declarative: collect, transform, fold, return.
 - Use descriptive names and ES2023-first style where the touched code benefits.
 
-For demos under `test/examples/`, treat DX gaps as library/runtime evidence
+For demos under `examples/`, treat DX gaps as library/runtime evidence
 first. Do not normalize demo-specific workarounds if the real issue is a shared
 API, default, or runtime contract.
 
@@ -247,8 +247,8 @@ small-chapter split pattern.
 - A good split outcome is one where a new reader can discover the boundary by
   drilling down through a few concise README pages rather than one monolithic
   README.
-- Apply this standard everywhere the split skill is used: `src/`, `test/`,
-  `test/examples/`, `scripts/`, browser/demo surfaces, tooling folders, and any
+- Apply this standard everywhere the split skill is used: `src/`, `examples/`,
+  `benchmarks/`, `testing/`, `scripts/`, browser/demo surfaces, tooling folders, and any
   other project area that has become too broad for one file or one folder README.
 - Do not treat examples, scripts, or support tooling as exceptions. If they are
   large enough to need a SOLID split, they should follow the same direct-path,

package/.github/skills/trace-audit-reporting/SKILL.md

@@ -99,7 +99,7 @@ surface for the library rather than the final destination for a workaround.
 
 - This repository already includes `scripts/analyze-trace/analyze-trace.ts` for compact,
   thread-aware trace audits.
-- For work in `src/` or `test/`, consult the nearest folder `README.md` before
+- For work in `src/`, `examples/`, `benchmarks/`, or `testing/`, consult the nearest folder `README.md` before
   deep file reads.
 - For substantial architecture findings, align the report with the relevant
   `plans/` document when one exists.

package/.github/skills/trace-audit-reporting/references/trace-analysis-workflow.md

@@ -23,7 +23,7 @@ npm run trace:analyze -- <trace-path> --top=15
 Example:
 
 ```bash
-npm run trace:analyze -- test/examples/flappy_bird/Trace-20260309T191949.json --top=15
+npm run trace:analyze -- examples/flappy_bird/Trace-20260309T191949.json --top=15
 ```
 
 ## What the Analyzer Produces

package/.github/workflows/ci.yml

@@ -18,6 +18,8 @@ jobs:
           node-version: '24'
       - name: Install dependencies
         run: npm ci
+      - name: Run lint
+        run: npm run lint
       - name: Run tests
         run: npm test
       - name: Check for coverage file

package/.github/workflows/publish.yml

@@ -75,6 +75,10 @@ jobs:
         if: ${{ env.LOOP_SKIP == 'false' }}
         run: npm ci
 
+      - name: Lint
+        if: ${{ env.LOOP_SKIP == 'false' }}
+        run: npm run lint
+
       - name: Test
         if: ${{ env.LOOP_SKIP == 'false' }}
         run: npm test
@@ -85,8 +89,8 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           set -e
-          PKG_NAME=$(node -p "require('./package.json').name")
-          CURR_VER=$(node -p "require('./package.json').version")
+          PKG_NAME=$(node --input-type=module -e "import fs from 'node:fs'; const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8')); console.log(pkg.name);")
+          CURR_VER=$(node --input-type=module -e "import fs from 'node:fs'; const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8')); console.log(pkg.version);")
           echo "Current version: $CURR_VER"
           if npm view "$PKG_NAME@$CURR_VER" version >/dev/null 2>&1; then
             echo "Version exists on registry; bumping patch.";
@@ -119,7 +123,7 @@ jobs:
         run: |
           echo "npm registry: $(npm config get registry)"
           echo "npm whoami:"; npm whoami || echo "not authenticated"
-          echo "package:" $(node -p "require('./package.json').name + '@' + require('./package.json').version")
+          echo "package:" $(node --input-type=module -e "import fs from 'node:fs'; const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8')); console.log(pkg.name + '@' + pkg.version);")
           echo "masked ~/.npmrc:";
           if [ -f ~/.npmrc ]; then sed -E 's/(:_authToken=).*/\1***REDACTED***/' ~/.npmrc || true; else echo "no ~/.npmrc"; fi
 
@@ -157,7 +161,7 @@ jobs:
         shell: bash
         run: |
           set -e
-          VER=$(node -p "require('./package.json').version")
+          VER=$(node --input-type=module -e "import fs from 'node:fs'; const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8')); console.log(pkg.version);")
           echo "version=$VER" >> "$GITHUB_OUTPUT"
 
       - name: Ensure git user (for tagging)

package/CONTRIBUTING.md

@@ -43,7 +43,7 @@ npm run docs
 
 - Keep changes small and focused. Prefer many small PRs over one large PR.
 - Follow TypeScript types and avoid `any` unless necessary; include type updates where relevant.
-- Add or update tests for behavioral changes. Tests live in `test/` and run with `npm test`.
+- Add or update tests for behavioral changes. Most behavioral tests now live alongside their owners in `src/**/*.test.ts`, the shared global Jest setup lives in `testing/jest-setup.ts`, and longer-running suites live in `examples/` and `benchmarks/`; run them with `npm test`.
 
 ---
 

package/README.md

@@ -35,9 +35,9 @@ If you want a library you can inspect, modify, and learn from while still runnin
 | Goal | Best place to start |
 | --- | --- |
 | Read the architecture from the source side | [src/README.md](./src/README.md) |
-| Study the strongest end-to-end example | [test/examples/flappy_bird/README.md](./test/examples/flappy_bird/README.md) |
-| Study curriculum learning and reward shaping | [test/examples/asciiMaze/README.md](./test/examples/asciiMaze/README.md) |
-| Browse runnable example source directly | [test/examples](./test/examples) |
+| Study the strongest end-to-end example | [examples/flappy_bird/README.md](./examples/flappy_bird/README.md) |
+| Study curriculum learning and reward shaping | [examples/asciiMaze/README.md](./examples/asciiMaze/README.md) |
+| Browse runnable example source directly | [examples](./examples) |
 | Review contribution standards | [CONTRIBUTING.md](./CONTRIBUTING.md) and [STYLEGUIDE.md](./STYLEGUIDE.md) |
 
 ## Reading paths
@@ -47,13 +47,13 @@ If you want a library you can inspect, modify, and learn from while still runnin
 1. Read [docs/index.html](./docs/index.html).
 2. Read [src/README.md](./src/README.md).
 3. Open one example:
-	 - [test/examples/flappy_bird/README.md](./test/examples/flappy_bird/README.md)
-	 - [test/examples/asciiMaze/README.md](./test/examples/asciiMaze/README.md)
+	 - [examples/flappy_bird/README.md](./examples/flappy_bird/README.md)
+	 - [examples/asciiMaze/README.md](./examples/asciiMaze/README.md)
 
 ### If you want runnable source first
 
-- [test/examples/flappy_bird](./test/examples/flappy_bird) for the clearest full-system example.
-- [test/examples/asciiMaze](./test/examples/asciiMaze) for evolution orchestration, telemetry, and visualization.
+- [examples/flappy_bird](./examples/flappy_bird) for the clearest full-system example.
+- [examples/asciiMaze](./examples/asciiMaze) for evolution orchestration, telemetry, and visualization.
 
 ### If you want library internals
 
@@ -66,7 +66,7 @@ If you want a library you can inspect, modify, and learn from while still runnin
 
 ### Flappy Bird
 
-[test/examples/flappy_bird](./test/examples/flappy_bird) is the best single example if you want to understand how NeatapticTS feels in a real project.
+[examples/flappy_bird](./examples/flappy_bird) is the best single example if you want to understand how NeatapticTS feels in a real project.
 
 It combines:
 
@@ -78,7 +78,7 @@ It combines:
 
 ### ASCII Maze
 
-[test/examples/asciiMaze](./test/examples/asciiMaze) is the best companion example if you want to study curriculum progression, compact observations, reward shaping, and browser plus terminal visualization.
+[examples/asciiMaze](./examples/asciiMaze) is the best companion example if you want to study curriculum progression, compact observations, reward shaping, and browser plus terminal visualization.
 
 ## Install
 
@@ -117,7 +117,7 @@ For options, telemetry, and subsystem details, continue in [docs/index.html](./d
 | Path | Purpose |
 | --- | --- |
 | [src](./src) | Core library code and generated module docs |
-| [test/examples](./test/examples) | Educational examples and demos |
+| [examples](./examples) | Educational examples and demos |
 | [docs](./docs) | Generated documentation site and example assets |
 | [scripts](./scripts) | Build and docs tooling |
 | [plans](./plans) | Architecture and roadmap material |

package/STYLEGUIDE.md

@@ -429,7 +429,7 @@ All tests in the repository must follow these rules to keep examples, tutorials,
 - Aim for 100% coverage on logic you change or add. For legacy modules where 100% isn't feasible in one pass, document missing coverage areas and add tests incrementally.
 
 - Check existing tests and folder patterns before creating a new test file:
-  - Use existing folders (e.g. `test/neat/`) and file naming conventions as a guide.
+  - Use existing folders (e.g. `src/neat/`, `benchmarks/`, or `examples/`) and file naming conventions as a guide.
   - Reuse and extend existing fixtures/helpers instead of adding new duplicate files.
 
 Example test layout:
@@ -508,6 +508,6 @@ Use this regex to find likely candidates to rename (review results manually):
 
 ---
 
-If you want, I can run a repo-wide scan and propose a patchset that renames short locals automatically (I will not apply bulk renames without your approval). If you'd like that, say which folders to prioritize (suggestion: `test/examples/asciiMaze/` then `src/`).
+If you want, I can run a repo-wide scan and propose a patchset that renames short locals automatically (I will not apply bulk renames without your approval). If you'd like that, say which folders to prioritize (suggestion: `examples/asciiMaze/` then `src/`).
 
 Thank you — I'll keep the guide updated as we iterate on modernization and educational docs. <3

package/benchmarks/asciiMaze.micro.bench.ts

@@ -0,0 +1,10 @@
+/**
+ * Placeholder CLI entrypoint for the standalone ASCII Maze micro-benchmark.
+ *
+ * `npm run bench:asciiMaze` historically pointed at a missing legacy file.
+ * Packet 10 preserves the command as a documented compatibility seam until a
+ * dedicated non-Jest benchmark harness is implemented.
+ */
+console.info(
+  '[bench:asciiMaze] Standalone ASCII Maze micro-benchmark harness is not implemented yet.',
+);

package/benchmarks/benchmark.asciiMaze.micro.bench.test.ts

@@ -0,0 +1,12 @@
+/**
+ * Placeholder for a future standalone ASCII Maze micro-benchmark harness.
+ *
+ * Packet 10 moves the benchmark lane to `benchmarks/**` but does not invent a
+ * new harness where none exists yet. This explicit skipped test keeps the
+ * benchmark suite structurally honest and prevents an empty-file failure.
+ */
+describe('benchmark.asciiMaze.micro placeholder', () => {
+  it.skip('tracks the standalone ASCII Maze micro-benchmark seam', () => {
+    expect(true).toBe(true);
+  });
+});

package/{test/benchmarks → benchmarks}/benchmark.browser.headless.test.ts

@@ -50,6 +50,15 @@ interface BrowserRunRecord {
   } | null;
 }
 
+/**
+ * Captures both the benchmark records and the temporary files created while
+ * loading the generated bundles in a browser page.
+ */
+interface HeadlessRunResult {
+  runs: BrowserRunRecord[];
+  cleanupPaths: string[];
+}
+
 /**
  * Builds development & production browser bundles with esbuild.
  *
@@ -67,9 +76,8 @@ const buildBundles = async (): Promise<{
   devPath: string;
   prodPath: string;
 }> => {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const esbuild = require('esbuild');
-  const benchDir = path.resolve(__dirname, '../..', 'bench-browser');
+  const esbuild = await import('esbuild');
+  const benchDir = path.resolve(__dirname, '..', 'bench-browser');
   const entry = path.join(benchDir, 'bench-entry.ts');
   if (!fs.existsSync(entry)) throw new Error('bench-entry.ts missing');
   const ts = Date.now();
@@ -119,17 +127,17 @@ const buildBundles = async (): Promise<{
 const runHeadless = async (paths: {
   devPath: string;
   prodPath: string;
-}): Promise<BrowserRunRecord[]> => {
-  let puppeteer;
+}): Promise<HeadlessRunResult> => {
+  let puppeteerModule;
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    puppeteer = require('puppeteer');
+    puppeteerModule = await import('puppeteer');
   } catch {
-    return [];
+    return { runs: [], cleanupPaths: [] };
   }
-  const benchDir = path.resolve(__dirname, '../..', 'bench-browser');
+  const puppeteer = puppeteerModule.default ?? puppeteerModule;
+  const benchDir = path.resolve(__dirname, '..', 'bench-browser');
   const templatePath = path.join(benchDir, 'index.html');
-  if (!fs.existsSync(templatePath)) return [];
+  if (!fs.existsSync(templatePath)) return { runs: [], cleanupPaths: [] };
   const template = fs.readFileSync(templatePath, 'utf-8');
   const bundles = [
     { mode: 'dev', path: paths.devPath },
@@ -137,10 +145,11 @@ const runHeadless = async (paths: {
   ];
   // Launch headless browser; tolerate launch failures (return empty results).
   const browser = await puppeteer
-    .launch({ headless: 'new', args: ['--no-sandbox'] })
+    .launch({ headless: true, args: ['--no-sandbox'] })
     .catch(() => null);
-  if (!browser) return [];
+  if (!browser) return { runs: [], cleanupPaths: [] };
   const runs: BrowserRunRecord[] = [];
+  const cleanupPaths: string[] = [];
   for (const b of bundles) {
     if (!b.path || !fs.existsSync(b.path)) continue;
     const fileName = path.basename(b.path);
@@ -151,6 +160,7 @@ const runHeadless = async (paths: {
       try {
         if (!fs.existsSync(localCopy)) {
           fs.copyFileSync(b.path, localCopy);
+          cleanupPaths.push(localCopy);
         }
       } catch {
         // Ignore file copy errors; bundle may already exist
@@ -162,6 +172,7 @@ const runHeadless = async (paths: {
       .replace(/__BUNDLE__/g, fileName);
     const tmpPath = path.join(benchDir, `jest-${b.mode}.${fileName}.html`);
     fs.writeFileSync(tmpPath, html, 'utf-8');
+    cleanupPaths.push(tmpPath);
     const page = await browser.newPage();
     await page.goto(`file://${tmpPath}`);
     // Poll the page for the benchmark payload with a hard timeout.
@@ -208,7 +219,7 @@ const runHeadless = async (paths: {
     await page.close();
   }
   await browser.close();
-  return runs;
+  return { runs, cleanupPaths };
 };
 
 /**
@@ -247,17 +258,20 @@ describe('browser headless benchmark integration', () => {
   let runs: BrowserRunRecord[] = [];
   let devPath = '';
   let prodPath = '';
+  let cleanupPaths: string[] = [];
 
   beforeAll(async () => {
     const built = await buildBundles();
     devPath = built.devPath;
     prodPath = built.prodPath;
-    runs = await runHeadless(built);
+    const headlessRun = await runHeadless(built);
+    runs = headlessRun.runs;
+    cleanupPaths = headlessRun.cleanupPaths;
     mergeResults(runs);
   });
 
   afterAll(() => {
-    [devPath, prodPath].forEach((f) => {
+    Array.from(new Set([devPath, prodPath, ...cleanupPaths])).forEach((f) => {
       try {
         fs.unlinkSync(f);
       } catch {

package/{test/benchmarks → benchmarks}/benchmark.fieldAudit.test.ts

@@ -5,7 +5,7 @@
  */
 import fs from 'fs';
 import path from 'path';
-import Node from '../../src/architecture/node';
+import Node from '../src/architecture/node';
 
 /**
  * Runtime interface for benchmark results with field audit data.

package/{test/benchmarks → benchmarks}/benchmark.memory.test.ts

@@ -10,12 +10,12 @@
  *  - Persist an evolving `benchmark.results.json` artifact (≤10 history entries) with
  *    provenance (git commit, dist bundle hash) and optional regression annotations.
  *
- * NOTE: This file intentionally lives under `test/` to leverage Jest's execution & coverage
+ * NOTE: This file intentionally lives under `benchmarks/` to leverage Jest's execution & coverage
  * while remaining framework-agnostic for future extraction into a standalone CLI harness.
  */
-import { memoryStats } from '../../src/utils/memory';
-import Network from '../../src/architecture/network';
-import NeatapticNode from '../../src/architecture/node';
+import { memoryStats } from '../src/utils/memory';
+import Network from '../src/architecture/network';
+import NeatapticNode from '../src/architecture/node';
 import type { BenchAggregateGroup } from './benchmark.report.test';
 import { aggregateBenchMeasurements } from './benchmark.report.test';
 import * as fs from 'fs';
@@ -560,7 +560,7 @@ describe('benchmark.memory dist-only', () => {
         exists: false,
       };
       try {
-        const distPath = path.resolve(__dirname, '../../dist/neataptic.js');
+        const distPath = path.resolve(__dirname, '../dist/neataptic.js');
         if (fs.existsSync(distPath)) {
           const stat = fs.statSync(distPath);
           // Hash only when file reasonably small (<25MB) to avoid CI slowdown (practical upper bound here is tiny)

package/benchmarks/benchmark.neat.evaluate.hotspot.test.ts

@@ -0,0 +1,11 @@
+/**
+ * Placeholder for a future NEAT evaluation hotspot benchmark.
+ *
+ * The benchmark tree migration keeps this seam visible without pretending the
+ * hotspot harness already exists.
+ */
+describe('benchmark.neat.evaluate.hotspot placeholder', () => {
+  it.skip('tracks the evaluation hotspot benchmark seam', () => {
+    expect(true).toBe(true);
+  });
+});

package/{test/benchmarks → benchmarks}/benchmark.nodePool.determinism.test.ts

@@ -1,5 +1,5 @@
-import Network from '../../src/architecture/network';
-import { config } from '../../src/config';
+import Network from '../src/architecture/network';
+import { config } from '../src/config';
 
 /**
  * Runtime interface for mutable config properties in tests.

package/{test/benchmarks → benchmarks}/benchmark.nodePool.memory.test.ts

@@ -1,10 +1,10 @@
-import { memoryStats } from '../../src/utils/memory';
+import { memoryStats } from '../src/utils/memory';
 import {
   acquireNode,
   releaseNode,
   resetNodePool,
-} from '../../src/architecture/nodePool';
-import { config } from '../../src/config';
+} from '../src/architecture/nodePool';
+import { config } from '../src/config';
 
 /**
  * Runtime interface for mutable config properties in tests.

package/{test/benchmarks → benchmarks}/benchmark.nodePool.removeRelease.test.ts

@@ -1,7 +1,7 @@
-import Network from '../../src/architecture/network';
-import { config } from '../../src/config';
-import { nodePoolStats, resetNodePool } from '../../src/architecture/nodePool';
-import type Node from '../../src/architecture/node';
+import Network from '../src/architecture/network';
+import { config } from '../src/config';
+import { nodePoolStats, resetNodePool } from '../src/architecture/nodePool';
+import type Node from '../src/architecture/node';
 
 /**
  * Runtime interface for mutable config properties in tests.

package/{test/benchmarks → benchmarks}/benchmark.nodePool.stress.test.ts

@@ -11,8 +11,8 @@ import {
   releaseNode,
   nodePoolStats,
   resetNodePool,
-} from '../../src/architecture/nodePool';
-import type Node from '../../src/architecture/node';
+} from '../src/architecture/nodePool';
+import type Node from '../src/architecture/node';
 
 describe('benchmark.nodePool.stress', () => {
   it('achieves recycledRatio >=0.5 with stable highWaterMark tail', () => {

package/{test/benchmarks → benchmarks}/benchmark.poolStats.persist.test.ts

@@ -4,7 +4,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { memoryStats } from '../../src/utils/memory';
+import { memoryStats } from '../src/utils/memory';
 
 describe('benchmark.poolStats.persist', () => {
   it('injects meta.poolStats.nodePool snapshot (single expectation)', () => {

package/{test/benchmarks → benchmarks}/benchmark.serialization.gater.test.ts

@@ -4,15 +4,15 @@
  * both compact tuple and verbose JSON serialization round-trips.
  * Single expectation style aggregating all checks.
  */
-import Network from '../../src/architecture/network';
-import type Node from '../../src/architecture/node';
-import type Connection from '../../src/architecture/connection';
+import Network from '../src/architecture/network';
+import type Node from '../src/architecture/node';
+import type Connection from '../src/architecture/connection';
 import {
   serialize as serializeTuple,
   deserialize as deserializeTuple,
   toJSONImpl,
   fromJSONImpl,
-} from '../../src/architecture/network/network.utils';
+} from '../src/architecture/network/network.utils';
 
 /**
  * Runtime interface for Network with internal properties and methods.

package/{test/benchmarks → benchmarks}/benchmark.slab.fragmentation.bounds.test.ts

@@ -2,10 +2,10 @@
  * benchmark.slab.fragmentation.bounds.test.ts
  * Ensures fragmentation percentage stays within [0,100] and responds to growth+prune cycles.
  */
-import Network from '../../src/architecture/network';
-import { memoryStats } from '../../src/utils/memory';
-import { config } from '../../src/config';
-import type Node from '../../src/architecture/node';
+import Network from '../src/architecture/network';
+import { memoryStats } from '../src/utils/memory';
+import { config } from '../src/config';
+import type Node from '../src/architecture/node';
 
 /**
  * Runtime interface for Network with slab management methods.

package/{test/benchmarks → benchmarks}/benchmark.slab.fragmentation.trend.test.ts

@@ -4,10 +4,10 @@
  * Scenario: grow network to expand slab capacity, capture low fragmentation state, prune nodes to induce higher
  * fragmentation (capacity retained, used shrinks), then regrow slightly. Verifies fragmentationPct increases after prune.
  */
-import Network from '../../src/architecture/network';
-import { memoryStats } from '../../src/utils/memory';
-import { config } from '../../src/config';
-import type Node from '../../src/architecture/node';
+import Network from '../src/architecture/network';
+import { memoryStats } from '../src/utils/memory';
+import { config } from '../src/config';
+import type Node from '../src/architecture/node';
 
 /**
  * Runtime interface for Network with slab management methods.