Tighten JLBH encoding policy, constructor safety, and documentation traceability

AGENTS.md

@@ -1,161 +1,8 @@
-# Guidance for AI agents, bots, and humans contributing to Chronicle Software's OpenHFT projects.
-
-LLM-based agents can accelerate development only if they respect our house rules. This file tells you:
-
-* how to run and verify the build;
-* what *not* to comment;
-* when to open pull requests.
-
-## Language & character-set policy
-
-| Requirement  | Rationale |
-|--------------|-----------|
-| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized` | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. |
-| **ASCII-7 only** (code-points 0-127). Avoid smart quotes, non-breaking spaces and accented characters. | ASCII-7 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. |
-| If a symbol is not available in ASCII-7, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. |
-
-## Javadoc guidelines
-
-**Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is
-noise and slows readers down.
-
-| Do | Don't |
-|----|-------|
-| State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name"). |
-| Keep the first sentence short; it becomes the summary line in aggregated docs. | Duplicate parameter names/ types unless more explanation is needed. |
-| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide. | Pad comments to reach a line-length target. |
-| Remove or rewrite autogenerated Javadoc for trivial getters/setters. | Leave stale comments that now contradict the code. |
-
-The principle that Javadoc should only explain what is *not* manifest from the signature is well-established in the
-wider Java community.
-
-## Build & test commands
-
-Agents must verify that the project still compiles and all unit tests pass before opening a PR:
-
-```bash
-# From repo root
-mvn -q verify
-```
-
-## Commit-message & PR etiquette
-
-1. **Subject line <= 72 chars**, imperative mood: "Fix roll-cycle offset in `ExcerptAppender`".
-2. Reference the JIRA/GitHub issue if it exists.
-3. In *body*: *root cause -> fix -> measurable impact* (latency, allocation, etc.). Use ASCII bullet points.
-4. **Run `mvn verify`** again after rebasing.
-
-## What to ask the reviewers
-
-* *Is this AsciiDoc documentation precise enough for a clean-room re-implementation?*
-* Does the Javadoc explain the code's *why* and *how* that a junior developer would not be expected to work out?
-* Are the documentation, tests and code updated together so the change is clear?
-* Does the commit point back to the relevant requirement or decision tag?
-* Would an example or small diagram help future maintainers?
-
-## Project requirements
-
-See the [Decision Log](src/main/adoc/decision-log.adoc) for the latest project decisions.
-See the [Project Requirements](src/main/adoc/project-requirements.adoc) for details on project requirements.
-
-## Elevating the Workflow with Real-Time Documentation
-
-Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to documentation.
-Ensure the relevant `.adoc` files are updated when features, requirements, implementation details, or tests change.
-This tight loop informs the AI accurately and creates immediate clarity for all team members.
-
-### Benefits of Real-Time Documentation
-
-* **Confidence in documentation**: Accurate docs prevent miscommunications that derail real-world outcomes.
-* **Reduced drift**: Real-time updates keep requirements, tests and code aligned.
-* **Faster feedback**: AI can quickly highlight inconsistencies when everything is in sync.
-* **Better quality**: Frequent checks align the implementation with the specified behaviour.
-* **Smoother onboarding**: Up-to-date AsciiDoc clarifies the system for new developers.
-* **Incremental changes**: AIDE flags newly updated files so you can keep the documentation synchronised.
-
-### Best Practices
-
-* **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area should prompt reviews and potential updates in the others.
-* **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from code/tests back to documentation, which should then be reviewed and finalised.
-* **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier for humans and AI analysis tools.
-- **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of all artefacts.
-
-## AI Agent Guidelines
-
-When using AI agents to assist with development, please adhere to the following guidelines:
-
-* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ASCII-7 guidelines outlined above.
-  Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present in the code or existing documentation.
-* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it provides additional context or clarification.
-* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's documentation standards before committing it to the repository.
-
-## Company-Wide Tagging
-
-This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use the <Scope>-<Tag>-xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different. Component-specific decisions live in their xxx-decision-log.adoc files.
-
-### Tag Taxonomy (Nine-Box Framework)
-
-To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in addition to the existing ALL prefix, which remains reserved for global decisions across every project.
-
-.Adopt a Nine-Box Requirement Taxonomy
-
-|Tag | Scope | Typical examples |
-|----|-------|------------------|
-|FN |Functional user-visible behaviour | Message routing, business rules |
-|NF-P |Non-functional - Performance | Latency budgets, throughput targets |
-|NF-S |Non-functional - Security | Authentication method, TLS version |
-|NF-O |Non-functional - Operability | Logging, monitoring, health checks |
-|TEST |Test / QA obligations | Chaos scenarios, benchmarking rigs |
-|DOC |Documentation obligations | Sequence diagrams, user guides |
-|OPS |Operational / DevOps concerns | Helm values, deployment checklist |
-|UX |Operator or end-user experience | CLI ergonomics, dashboard layouts |
-|RISK |Compliance / risk controls | GDPR retention, audit trail |
-
-`ALL-*` stays global, case-exact tags. Pick one primary tag if multiple apply.
-
-### Decision Record Template
-
-```asciidoc
-=== [Identifier] Title of Decision
-
-Date:: YYYY-MM-DD
-Context::
-* What is the issue that this decision addresses?
-* What are the driving forces, constraints, and requirements?
-Decision Statement::
-* What is the change that is being proposed or was decided?
-Alternatives Considered::
-* [Alternative 1 Name/Type]:
-** *Description:* Brief description of the alternative.
-** *Pros:* ...
-** *Cons:* ...
-* [Alternative 2 Name/Type]:
-** *Description:* Brief description of the alternative.
-** *Pros:* ...
-** *Cons:* ...
-Rationale for Decision::
-* Why was the chosen decision selected?
-* How does it address the context and outweigh the cons of alternatives?
-Impact & Consequences::
-* What are the positive and negative consequences of this decision?
-* How does this decision affect the system, developers, users, or operations?
-- What are the trade-offs made?
-Notes/Links::
-** (Optional: Links to relevant issues, discussions, documentation, proof-of-concepts)
-```
-
-## Asciidoc formatting guidelines
-
-### List Indentation
-
-Do not rely on indentation for list items in AsciiDoc documents. Use the following pattern instead:
-
-```asciidoc
-section:: Top Level Section
-* first level
-  ** nested level
-```
-
-### Emphasis and Bold Text
-
-In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.
+# Chronicle JLBH AGENTS
+
+- Follow repository `AGENTS.md` as the base rules; this file adds JLBH specifics. Durable docs live in `src/main/docs/` with the landing page at `README.adoc`.
+- Module purpose: Java Latency Benchmark Harness for running context-aware latency/throughput benchmarks with Chronicle-friendly patterns.
+- Build commands: full build `mvn -q clean verify`; module-only without tests `mvn -pl JLBH -am -DskipTests install`.
+- Quality gates: keep Checkstyle/SpotBugs clean; ensure benchmarks remain deterministic and reproducible; guard against benchmark harness changes that alter measurement accuracy.
+- Documentation: maintain Nine-Box IDs in `src/main/docs/project-requirements.adoc` and link decisions/tests/benchmarks to them; British English, ASCII/ISO-8859-1, `:source-highlighter: rouge`.
+- Guardrails: avoid introducing benchmark code that masks coordinated omission; document any new CLI options or environment knobs in the docs.

CLAUDE.md

@@ -0,0 +1,219 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+JLBH (Java Latency Benchmark Harness) is a specialised benchmarking library for measuring end-to-end latency in Java applications under realistic throughput conditions. Unlike JMH micro-benchmarks, JLBH is designed to benchmark code "in context" and account for coordinated omission. It is particularly suited for producer/consumer workloads where iteration start and completion may occur on different threads.
+
+## Build & Test Commands
+
+```bash
+# Verify build and run all tests
+mvn -q verify
+
+# Clean build from scratch
+mvn -q clean verify
+
+# Run a specific test class
+mvn -q test -Dtest=JLBHTest
+
+# Run a single test method
+mvn -q test -Dtest=JLBHTest#shouldProvideResultData
+
+# Compile only (skip tests)
+mvn -q compile
+
+# Skip tests during verify
+mvn -q verify -DskipTests
+```
+
+## Language & Character-Set Requirements
+
+**Critical**: All code and documentation must use:
+- **British English** spelling (`organisation`, `licence`) except for Java keywords like `synchronized`
+- **ISO-8859-1** character encoding only (code points 0-255)
+- **No Unicode characters**: Use ASCII equivalents like `>=` instead of special symbols
+- Verify with: `iconv -f ascii -t ascii <file>`
+
+See AGENTS.md for complete language policy and rationale.
+
+## Architecture Overview
+
+### Core Components
+
+**JLBH** (src/main/java/net/openhft/chronicle/jlbh/JLBH.java)
+- The main orchestrator that manages the entire benchmark lifecycle
+- Runs on a single thread (annotated `@SingleThreaded`)
+- Provides `sample(long durationNs)` to record end-to-end latencies
+- Provides `addProbe(String)` to create additional `NanoSampler` instances for measuring sub-stages
+- Can run standalone via `start()` or integrate with Chronicle EventLoop via `eventLoopHandler(EventLoop)`
+
+**JLBHOptions** (src/main/java/net/openhft/chronicle/jlbh/JLBHOptions.java)
+- Builder-style configuration object defining all benchmark parameters
+- Key settings: `throughput()`, `iterations()`, `runs()`, `warmUpIterations()`, `accountForCoordinatedOmission()`, `recordOSJitter()`
+- Default throughput: 10,000 ops/sec; default runs: 3
+
+**JLBHTask** (src/main/java/net/openhft/chronicle/jlbh/JLBHTask.java)
+- User-implemented interface defining the workload to benchmark
+- Lifecycle methods called by JLBH:
+  - `init(JLBH)`: Setup phase, register probes
+  - `run(long startTimeNs)`: Execute benchmark iteration (called for each iteration)
+  - `warmedUp()`: Notification after warmup completes
+  - `runComplete()`: Notification after each run
+  - `complete()`: Final cleanup
+
+**Histograms & Results**
+- Each probe (end-to-end, custom probes, OS jitter) records samples into a `Histogram` from chronicle-core
+- Histograms use logarithmic bucketing with 35-bit range and 8 significant figures
+- Immutable result objects: `JLBHResult`, `ProbeResult`, `RunResult`
+- Use `ThreadSafeJLBHResultConsumer` to retrieve results from another thread
+
+### Threading Model
+
+- **Single-threaded harness**: All JLBHTask lifecycle methods run on the single JLBH thread
+- **User code may spawn threads**: The benchmarked code within `JLBHTask.run()` can be multi-threaded
+- **Sample recording thread-safety**: Only the JLBH harness thread should call `jlbh.sample()` or probe samplers
+- **Event loop integration**: Via `eventLoopHandler()` instead of `start()` (requires coordinated omission accounting enabled)
+
+### Execution Flow
+
+1. **Initialization**: User configures `JLBHOptions`, creates `JLBH` instance, calls `JLBHTask.init()`
+2. **Warm-up**: Runs `warmUpIterations` times to allow JIT compilation (default ~12k iterations)
+3. **Measurement runs**: Executes `runs` times (default 3), each with `iterations` samples
+4. **Completion**: Prints summary, constructs immutable `JLBHResult`, calls `JLBHTask.complete()`
+
+See src/main/adoc/benchmark-lifecycle.adoc for visual flow diagram.
+
+### Coordinated Omission
+
+JLBH accounts for coordinated omission by default (`accountForCoordinatedOmission = true`):
+- `startTimeNs` passed to `run()` is the *calculated ideal start time*, not `System.nanoTime()`
+- Harness busy-waits if current time is before scheduled start time
+- Disabling this feature means start time is simply based on throughput without waiting
+
+### OS Jitter Monitoring
+
+Enabled by default via `recordOSJitter(true)`:
+- Background thread `OSJitterMonitor` repeatedly samples `System.nanoTime()` to detect scheduler delays
+- Records jitter > `recordJitterGreaterThanNs` (default: 1000ns) into separate histogram
+- Incurs overhead; disable with `recordOSJitter(false)` for minimal-overhead benchmarks
+
+## Key Design Patterns
+
+**Probes for Multi-Stage Benchmarks**
+```java
+class MyTask implements JLBHTask {
+    private JLBH jlbh;
+    private NanoSampler stage1Probe;
+
+    public void init(JLBH jlbh) {
+        this.jlbh = jlbh;
+        this.stage1Probe = jlbh.addProbe("stage1");
+    }
+
+    public void run(long startTimeNs) {
+        long stage1Start = System.nanoTime();
+        // ... stage 1 work ...
+        stage1Probe.sampleNanos(System.nanoTime() - stage1Start);
+
+        // ... remaining work ...
+        jlbh.sample(System.nanoTime() - startTimeNs);
+    }
+}
+```
+
+**Typical Benchmark Setup**
+```java
+JLBHOptions options = new JLBHOptions()
+    .warmUpIterations(100_000)
+    .iterations(1_000_000)
+    .throughput(50_000)
+    .runs(3)
+    .jlbhTask(myTask);
+new JLBH(options).start();
+```
+
+**Thread-Safe Result Retrieval**
+```java
+JLBHResultConsumer resultConsumer = JLBHResultConsumer.newThreadSafeInstance();
+JLBH jlbh = new JLBH(options, System.out, resultConsumer);
+// Run on separate thread
+new Thread(() -> jlbh.start()).start();
+// Retrieve results from main thread after completion
+JLBHResult result = resultConsumer.get();
+```
+
+## Documentation Structure
+
+All requirements and design decisions are in src/main/adoc/:
+- **project-requirements.adoc**: Formal requirements specification with tagged requirements (FN-xxx, NF-P-xxx, etc.)
+- **decision-log.adoc**: Architectural decision records (ADRs) following Nine-Box taxonomy
+- **architecture.adoc**: High-level architecture, components, execution flow, threading model
+- **benchmark-lifecycle.adoc**: Visual diagram of benchmark execution phases
+- **jlbh-cookbook.adoc**: Common usage patterns and recipes
+- **results-interpretation-guide.adoc**: How to interpret percentile output
+
+When making changes:
+1. Update relevant .adoc files first (if changing requirements/design)
+2. Update code and tests
+3. Verify all three stay synchronised in same commit
+
+## Javadoc Standards
+
+Follow guidelines from AGENTS.md:
+- Document *behavioural contracts*, edge cases, thread-safety, units, performance characteristics
+- Do NOT restate the obvious ("Gets the value")
+- First sentence must be concise (becomes summary line)
+- Remove autogenerated Javadoc for trivial getters/setters
+- Explain *why* and *how*, not just *what*
+
+## Test Examples
+
+Test files in src/test/java/net/openhft/chronicle/jlbh/ demonstrate usage:
+- `ExampleJLBHMain`: Basic command-line harness demonstration
+- `SimpleBenchmark`: Minimal benchmark example
+- `SimpleOSJitterBenchmark`: Demonstrates OS jitter recording and custom probes
+- `JLBHTest`: Unit test showing programmatic result extraction
+- `JLBHIntegrationTest`: Example integration test
+
+## Performance Requirements
+
+From project-requirements.adoc (NF-P requirements):
+- Overhead per sample: < 100 ns when no additional probes active
+- Histogram generation: Support >= 200M iterations without heap pressure
+- Warm-up rule of thumb: ~30% of run iterations (default uses JIT compile threshold * 6/5)
+
+## Dependencies
+
+Key dependencies from pom.xml:
+- **chronicle-core**: Provides `Histogram`, `NanoSampler`, threading utilities
+- **affinity**: CPU affinity control via `AffinityLock`
+- **chronicle-threads**: Event loop integration (test scope)
+
+## Common Gotchas
+
+- JLBH is `@SingleThreaded` - the harness itself runs on one thread
+- The `startTimeNs` parameter to `run()` is NOT `System.nanoTime()` - it's the calculated ideal start time
+- Warm-up iterations use ~12k by default; adjust with `warmUpIterations()` if benchmark takes long to stabilise
+- OS jitter monitoring is enabled by default and adds overhead; explicitly disable if needed
+- When using `eventLoopHandler()`, coordinated omission must remain enabled
+- CSV export: Use `JLBHResultSerializer.runResultToCSV(jlbhResult)` (writes to `result.csv` by default)
+
+## Non-Functional Quality Attributes
+
+From README.adoc summary:
+- **Performance**: < 100 ns overhead per sample, >= 200M iterations supported
+- **Reliability**: Graceful abort on interruption/timeout, immutable thread-safe results
+- **Usability**: Fluent API, runnable in <= 10 LOC, human-readable ASCII output
+- **Portability**: Pure Java, runtime-detected JDK optimisations
+- **Maintainability**: >= 80% test coverage (current: ~83% line, ~78% branch per pom.xml)
+
+## Commit & PR Guidelines
+
+From AGENTS.md:
+- Subject line <= 72 chars, imperative mood
+- Body: root cause -> fix -> measurable impact
+- Run `mvn -q verify` before opening PR
+- Keep PRs focused; avoid bundling unrelated changes
+- Re-run build after addressing review comments