Tighten JLBH encoding policy, constructor safety, and documentation traceability

[peter-lawrey]

This PR aligns JLBH with Chronicle’s encoding and documentation conventions, strengthens harness safety around resource tracing, and improves test determinism and requirements traceability.

Functional changes

• Fail fast when intrusive JVM resource tracing is enabled

  • JLBH now checks the jvm.resource.tracing system property in the constructor and throws an IllegalStateException instead of calling System.exit(-1) when it is set (empty or true).
  • This prevents the harness from silently terminating the host JVM while still protecting benchmark integrity when intrusive tracing is enabled.
  • New systemProperties.adoc documents this behaviour and the property semantics.

• Thread-safe tracking of sample count for watchdog logic

  • Replaced the volatile long noResultsReturned counter with an AtomicLong.
  • All reads/writes in sample(long), checkSampleTimeout(), and endOfRun(...) now use atomic operations.
  • This makes the interaction between the sampling thread and the timeout watchdog deterministic and avoids racy reads when checking for stalled benchmarks.

• Deterministic CSV output encoding

  • JLBHResultSerializer.runResultToCSV(...) now writes via an OutputStreamWriter with ISO_8859_1, instead of relying on platform-default encoding.
  • Ensures CSV output is stable across platforms and consistent with the documented character-set policy.

• BOM upgrade

  • Bumped net.openhft:third-party-bom from 3.27ea5 to 3.27ea7 to align with the latest dependency set (logging/test stack, etc.) used across Chronicle modules.

Non-functional changes

• Encoding & language policy and tooling

  • In AGENTS.md:

    • Clarified the character-set policy from “ASCII-7 only” to “ISO-8859-1 (code-points 0-255)”, while still advising against smart quotes, non-breaking spaces, and accented characters.
    • Linked to the University of Oxford style guide for British English spelling.
    • Added guidance and tooling hints (iconv and IDE settings) to detect non-compliant characters.
    • Updated AI-agent guidance to reference the ISO-8859-1 policy.

• Security review guidance

  • Added a “Security checklist” section to AGENTS.md:

    • Explicit reminder to run a security pass on every PR (validation, authN/authZ, encoding, overflow, resource exhaustion, timing attacks).
    • Clear “never commit secrets” rules and recommendations (env vars, Vault, cloud secret managers).
    • Guidance to document intentional security trade-offs and hot-spots in Javadoc/AsciiDoc (e.g. unchecked casts for performance).

• Commit / PR etiquette and workflow

  • Tweaked examples in the “Commit-message & PR etiquette” section to avoid unnecessary quoting around the subject line.

  • Added a “When to open a PR” subsection, clarifying:

    • PRs should be opened once mvn -q clean verify passes.
    • PRs must be linked to issues/decision records.
    • PRs should stay focused and avoid bundling unrelated refactors.

• Documentation structure, numbering, and traceability

  • Added :lang: en-GB and :source-highlighter: rouge to key .adoc files (README.adoc, architecture, SRS, guides).

  • Enabled :sectnums: and removed manual numeric prefixes from section titles in:

    • architecture.adoc
    • benchmark-lifecycle.adoc
    • project-requirements.adoc
    • jlbh-cookbook.adoc
    • results-interpretation-guide.adoc

  • Tidied up minor wording and link issues:

    • “microbenchmark” → “micro-benchmark”.
    • Fixed trailing punctuation in external-link labels.
    • Updated glossary anchor from #_7-glossary to #_glossary.

• Decision log and requirements cross-references

  • Expanded decision-log.adoc with a decision index and new JL-scoped decisions (FN / NF-P / OPS / DOC, Nine-Box tagging).

  • Added detailed records for:

    • Single-threaded harness and JLBHTask lifecycle.
    • Default coordinated-omission compensation and histogram design.
    • OS jitter tracking as an optional probe.
    • Additional probes and NanoSampler API.
    • CSV serialisation and result retention.
    • TeamCity CI integration via statistics.

  • Linked feature requirements in project-requirements.adoc back to the corresponding decisions (e.g. FN-001 → JL-FN-002, FN-004 → JL-OPS-004, etc.), improving traceability from requirements → design decisions → implementation.

• Javadoc and inline-comment hygiene

  • In AGENTS.md, clarified the principle that Javadoc and inline comments should only explain what is not manifest from the signature or code.
  • Added concrete examples of “bad” vs “good” inline comments to reduce noise and encourage comments that explain subtle behaviour, not restate field names.

• Sample code and examples

  • Updated SimpleBenchmark, SimpleOSJitterBenchmark, and SimpleResultSerializerBenchmark:

    • Clarified commentary around startTimeNS vs System.nanoTime() and the impact on what is actually measured.
    • Highlighted coordinated-omission options as explicit, commented-out configuration.

  • Simplified ExampleJLBHMain to remove unused Math.sin work and use Jvm.safepoint() only as a placeholder for minimal in-loop work.

• Encoding-stable tests and small clean-ups

  • Standardised test harnesses (JLBHTest, JLBHIntegrationTest, JLBHAdditionalCoverageTest, etc.) to:

    • Create PrintStreams with explicit "UTF-8" encodings.
    • Decode ByteArrayOutputStream contents using "UTF-8" and normalise line endings, making tests deterministic across platforms.

  • Minor internal refactors:

    • Renamed JLBHOptions.SKIP_FIRST_RUN → JLBHOptions.SkipFirstRun and updated tests accordingly.
    • Simplified JLBHOptions.toString() implementation.
    • Reduced unnecessary fields and state in deterministic fixtures to keep tests clear and side-effect free.
    • Relaxed the visibility of JLBH.addPrToPrint(...) for test inspection via reflection (still package-private API).

Overall, the PR tightens encoding and documentation conventions, improves safety and thread-safety in the core harness, and makes both CSV output and tests more predictable across different environments.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud