# Benchmark source-archive layout — 2026-10-02 This is migration verification, with no new timing or Stage 5 grade. Development remains in private `libhft-devel/bench/`; public `libhft-benchmarks` receives generated exports. See [the migration plan](PLAN_BENCHMARK_EXPORT.md). ## Change The manifest now selects the build, clock, wire-audit and llfix readiness helpers used by real controllers. A shared layout helper discovers the source root from the canonical workload, adapter directory and shared support files. It works in development archives and stripped exports without `.git` and ignores unrelated enclosing Git markers. An incomplete archive carrying shared build support cannot borrow a missing layout helper from an enclosing checkout. The Stage 2 owner approved its header-only migration and sibling import bootstrap. The native and .NET roots use the same discovery. The Artio canonical fixture loader and retained grading-source paths support both layouts. Grading captures also retain both new layout helper files. llfix's adapter paths are portable; its exact revision, clean-source, licence and capability checks are unchanged. Build-helper changes are comments only. Optional corpus defaults are a public template; private defaults and explicit overrides remain intact. ## Verification The test materializes the manifest's exact tracked selection and templates outside the worktree. Its root is named `bench`, has no engine directory or Git marker, and is nested below an unrelated parent with both. Subprocesses clear `PYTHONPATH` and `PYTHONHOME`, run from outside the archive, and place outputs under `LIBHFT_BUILD_ROOT`. - Seven actual CLI `--help` calls cover Stage 2, native Stage 5, .NET Stage 5, QuickFIX/J and Artio observers, and both current Java physical controllers. - An explicit `importlib.util.spec_from_file_location` Stage 2 import resolves the sibling bootstrap without a preconfigured module search path. - Four canonical flows check the actual independent owner sink and fold count for twenty measured cycles each. Retained grading sources have matching hashes. - Build-root mapping, Java/.NET logical targets, external corpus overrides, clock contracts and portable llfix adapter paths pass from the archive. - A missing layout helper fails even with another helper in the enclosing tree. - Executable AST comparison confirms no build-helper logic changes. Function and class AST comparisons confirm no Stage 2 field/admission or llfix gate logic changes. Reproduce the lightweight checks from a development worktree: ```sh export LIBHFT_BUILD_ROOT="$HOME/build//libhft" PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=tools python3 -m unittest \ tools/test_benchmark_export_layout.py tools/test_libhft_benchmark_layout.py \ tools/test_libhft_toolenv.py tools/test_libhft_benchmark_clocks.py \ tools/test_check_llfix_benchmark_readiness.py ``` The 53 archive/layout/build/clock/llfix checks pass. Existing Java controller and report checks and Stage 2 clock, runtime, parity and report checks also pass. These checks use fixture executables and mocks, with no engine build. Neither verification group skips checks. The broader scenario suite exposed three existing stale source assertions for the .NET tick capture, Artio execution-report builder and NexusFIX execution type setter. Those sources and assertions match the pre-migration revision. They are recorded separately from the archive checks and remain to be repaired. Its native-root assertion was updated to call the discovery API, since checking for the removed Git-marker implementation cannot establish layout correctness. Follow-up: the three stale assertions are now repaired, and all 68 scenario checks pass with no skips. The .NET check follows the prepared snapshot into the send wrapper and requires cold capture before the tick clock and socket send. Its native task check follows the shared receive-derived reaction helper. Artio retains the no-fill return before the current execution-report builder; NexusFIX's canonical builder must emit New for both execution type and order status. No engine or driver behaviour changed in this test repair. ## Remaining gates After integrating concurrent main changes, readiness selects 685 files, 9.4 MB, with 616 scrub findings in 105 files, 115 files reaching outside the source root and six dead documentation links. The selected support directory has zero scrub findings. Engine SDKs, source overrides, includes, native libraries and runtime artifacts still need their own independent-build checks. Export release, licensing review and source pins remain open. Frozen host packages, previous evidence and all physical admission and report gates remain unchanged. The earlier support pass measured 684 files and 412 findings in 102 files. Concurrent main added a third-party boundary document and a site-nickname scrub rule before publication. Both are preserved; the higher finding count is not an engine or timing regression. ## Native and QuickFIX/n input-path follow-up The native controller now locates its C++ fixtures, adapters and measurement headers through the shared layout API. The QuickFIX/n Stage 3 project is also resolved from the harness. Real archive imports require each registered native adapter, `HftBenchRunner.h` and the QuickFIX/n project to exist. Native full-session libhft supports `LIBHFT_CPP_SOURCE`, naming the C++ source root containing `include/`. Development defaults to `engine/cpp`; standalone defaults to a sibling `libhft` tree. The microbench owner agreed to align a future Stage 2 setting with this meaning; that launcher remains unchanged here. A missing explicit source raises an input error before creating build outputs. The override grants no engine-source or timing qualification. The archive group now has five checks; all 54 combined helper checks pass. The 199 controller/scenario/focused Stage 2 checks and ten subtests pass with no skips. The exported source-layout guide has zero scrub findings and adds no dead link. Readiness selects 686 files, with 616 findings in 105 files, 116 textual escapes and the same six dead links. The guide's C++ source-layout description is the added escape; remaining engine builds and pins stay open. The [native Makefile and portable-document follow-up](RECORD_2026-10-02_benchmark_export_native.md) adds actual engine-free native build and functional verification on HP, preserves a failed tiny-buffer test and its passing fresh correction, and closes the manifest's dead documentation links. Standalone engine inputs and public release admission remain separate outstanding gates.