Skip to content

ADR-047-embedded-benchmark-host.md

Latest commit

 

History

History
73 lines (66 loc) · 4.91 KB

ADR-047-embedded-benchmark-host.md

File metadata and controls

73 lines (66 loc) · 4.91 KB
Raw

ADR-047: public embedded benchmark scenarios and typed executable

Status: Accepted; implementation and qualification pending. Related: REQ-BC-022, AC-EM-001..004, AC-CQ-007/008, ADR032/033/035.

BenchmarkDotNet0.15.8's generated external runner inherits the fixture. Its actual template and converter require public external visibility/methods; making an application fixture internal to satisfy CA1515 breaks that consumer. Upstream inheritance is the explicit justification for this otherwise unsealed public benchmark type. Keep compiler policy and ordinary generated-process toolchain intact.

Choose a nonpackable public KeyLoad.BenchmarkScenarios library under canonical BenchmarkComparisons ownership. Existing KeyLoad.Benchmarks remains the sole microbenchmark executable, with only a typed application runner selecting the fixture assembly. The public fixture CLR identity belongs to the library namespace; preserve the three method names/filter fragments and operation behavior. This is a benchmark tooling boundary, not a database product, cluster topology, managed dependency replacement or comparative-report change.

flowchart LR
    CLI[Existing microbenchmark executable] --> Host[Typed switcher application]
    Host --> Fixture[Public scenario library]
    Generator[BenchmarkDotNet generated child] --> Fixture
    Fixture --> Engine[Real embedded engine and ZoneTree]
    TUnit[GitHub TUnit qualification] --> CLI
    TUnit --> Fixture
    CLI --> Raw[Raw Dry qualification artifacts]
Loading

Implementation contract, accepted before writes:

  1. The new library source/csproj, the existing microbenchmark Program/csproj with a new typed runner and new EmbeddedBenchmark* TUnit sources are one coherent unit; policy, this ADR, feature/architecture and central project/solution references/inventory/CI are updated with it.
  2. Author metadata/lifetime/actual-process assertions first and archive source and tests-first hashes, then the coherent fixture move and ownership/clock/keys/XML repairs. Preserve seeding and every timed input/call/MemoryDiagnoser. Dispose acquired resources on setup error and repeated/uninitialized cleanup. Review complete failure/acquisition paths; environmental fault-path review is explicit supplemental evidence, not a fake deterministic runtime test.
  3. Add real references/inventory only after files exist and verify25-project strict policy and23 custom consumers, normal Release builds, generated registration,400/200/64/3, formatter/governance/import/diff and source provenance. Coverage and other source prerequisites stay explicitly pending.
  4. Exact-SHA GitHub TUnit invokes actual executable with Dry/full JSON. The pinned exporter supplies Method/Statistics/Measurements; all three need positive actual Workload/Result measurements and complete output/report retention. Exit0 alone is insufficient. No local runs, fake child or synthetic measurement evidence.
  5. Full required unit/recovery/Docker Aspire replicated-cluster SDK/MCP and existing gates must pass on the same delivered source. Dry results qualify runner execution only; comparative profiles/site/power-loss/endurance/production claims remain governed by their own gates. Update honest evidence before changing this ADR's status.

Dependencies retain existing centrally pinned SDK, BenchmarkDotNet and product Query/Security/Storage projects. The first actual joined restore exposed NU1608: BenchmarkDotNet's CSharp4.14.0 requires exact Common4.14.0 while the real Orleans test graph already owns Common5.0.0. Before changing central dependencies, accept only the CSharp5.0.0 peer pin, whose actual nuspec requires exact Common5.0.0 and satisfies BenchmarkDotNet's minimum. Keep the existing Common/SDK/Orleans and ManagedCode pins, analyzer SDK assets and all diagnostics unchanged. This shared configuration has a single owner; actual paired restore, enabled builds and stage4's real Dry generated consumer are required compatibility evidence. Rollback of the complete benchmark join also removes the new peer pin; removing it alone leaves the invalid graph and is not an accepted rollback. No ManagedCode release or persisted-data change follows from this compiler-package alignment. Deliver the source/library/host/test/reference changes coherently; persisted data is unchanged. Rollback removes that complete source unit while preserving strict policy, without a duplicate fixture API or diagnostic bypass. Shared contracts/configuration/docs have a single owner; independent query/storage/execution work cannot be overwritten. Accepted remains until every mapped gate succeeds.