Document Chronicle-Bytes architecture, requirements and utilities; tighten agent guidance; bump BOM

[peter-lawrey]

Functional changes

• Dependency alignment

  • Update imported net.openhft:third-party-bom from 3.27ea5 → 3.27ea7 to pick up the latest curated dependency versions used across the OpenHFT stack.

• API throws-signature clean-up (behaviour unchanged)

  • Narrow the declared exceptions on several public methods to reflect actual runtime behaviour:

    • ByteStringAppender.append(float) and append(double) now declare only BufferOverflowException and IllegalStateException (runtime) while still delegating to Bytes.append(double) for formatting.
    • Bytes.bytesForRead() no longer declares checked Chronicle-specific exceptions in its signature; it still calls throwExceptionIfReleased(this) internally and will throw as before at runtime.

  • These are source- and binary-compatible changes that do not alter logic but make the API surface more accurate.

There are no intentional behavioural changes to Bytes/BytesStore read/write, allocation, pooling, hashing or ring-buffer logic in this PR; all other code changes are documentation, Javadoc, or test-only improvements.

---

Non-functional changes

1. Agent guidance and AI-specific docs

• AGENTS.md (Chronicle-Bytes)

  • Add Chronicle-Bytes–specific preamble and documentation pointers:

    • Follow root AGENTS.md for base rules; Bytes-specific durable docs live under src/main/docs/ with README.adoc as the landing page.

  • Tighten language/character-set policy:

    • Explicitly use British English and ISO-8859-1; add a direct link to the University of Oxford style guide.
    • Clarify symbol usage and give practical tooling hints for ASCII/ISO-8859-1 validation (e.g. iconv, IDE inspections).

  • Expand build and quality expectations:

    • Require mvn -q clean verify from a clean checkout.
    • Document -P quality and -P sonar profiles, and a focused Chronicle-Bytes module run (-pl :chronicle-bytes -am clean verify).

  • Add “When to open a PR” section:

    • Require green mvn -q clean verify, linkage to issues/decision records and focused changes.
    • Re-run the build after addressing review comments.

  • Clarify Javadoc and inline comments with a good/bad example to discourage noise.

• New AI companion docs

  • CLAUDE.md: deep project overview and usage guide tailored to Claude Code, covering:

    • Chronicle Bytes architecture, build/run commands, testing conventions, Javadoc rules, Nine-Box requirements and memory-management patterns.
    • Expected AI behaviour (low allocation, British English, AsciiDoc standards).

  • GEMINI.md: high-level Chronicle Bytes analysis for Gemini:

    • Project recap, build commands (including run-benchmarks, assertions, quality, sonar profiles).
    • Development conventions (testing, docs, commit etiquette, AI usage boundaries).
    • Pointers to key files, docs, and modules to ease onboarding.

---

2. Architecture, requirements, and security documentation

• Core AsciiDoc structure and headers

  • Standardise all major docs (README.adoc, FAQ.adoc, api-guide.adoc, architecture-overview.adoc, algo-overview.adoc, decimal-rendering.adoc, domestic-overview.adoc, render-overview.adoc, util-overview.adoc, wire-integration.adoc, etc.) on:

    • :toc:, :sectnums:, :lang: en-GB, :source-highlighter: rouge where appropriate.
    • Consistent section headings, use of description lists, and British English.

  • Update README.adoc:

    • Fix links and image paths to use src/main/docs/....
    • Reference the new system-properties.adoc, project-requirements.adoc and decision-log.adoc.
    • Mark code blocks with opts=novalidate to avoid spurious validation warnings.

• New high-level docs

  • src/main/docs/decision-log.adoc

    • Introduces formal Nine-Box–style decision records (e.g. CB-FN-101 .. CB-DOC-101) explaining:

      • The Bytes/BytesStore API split and cursor model.
      • Elastic buffer growth within realCapacity.
      • Atomic ops on off-heap BytesStore.
      • Zero-copy slicing semantics and view lifecycles.
      • Encoding, alignment and pooling strategy.
      • Documentation structure and diagram approach.

  • src/main/docs/functional-requirements.adoc

    • Groups the CB-FN-* requirements from project-requirements.adoc into domains (core API & storage, encoding/utilities, pooling & lifecycle).
    • Provides a quick matrix of IDs → summary → verification, and a small Mermaid diagram tying docs to requirement domains.

  • src/main/docs/security-review.adoc

    • Consolidates security considerations around:

      • Input validation scope, bounds checking and Unsafe encapsulation (CB-NF-S-001, CB-NF-S-003).
      • Memory-mapped file sharing and file-lock semantics (CB-NF-S-002).
      • Elastic buffers and resource exhaustion, and their mitigation (CB-NF-S-004).
      • Cryptography, hashing, network security responsibilities and tooling (static analysis, dependency scanning).

  • src/main/docs/testing-strategy.adoc

    • Documents test layers (unit, integration, microbenchmarks, regression) and maps them back to CB-TEST-* and performance requirements (CB-NF-P-*).
    • Clarifies expectations for CI, regression capture and requirement traceability.

• Requirements and glossary

  • src/main/docs/project-requirements.adoc

    • Adds :sectnums: and explicit anchors ([[CB-FN-001]] etc.) for all requirements.
    • Clarifies wording (ISO-8859-1 vs ASCII-7), strengthens “must” language and improves cross-references.
    • Adds/fixes columns for non-functional/security/operability requirements, with clear verification/evidence notes.

  • Introduces/updates system property docs:

    • Removes docs/systemProperties.adoc (legacy) and replaces it with src/main/docs/system-properties.adoc under the main doc tree.
    • Documents key Chronicle-Bytes system properties (bytes.guarded, bytes.bounds.unchecked, trace.mapped.bytes, mappedFile.retain, timestamp.*, bytes.max-array-len) in a single AsciiDoc table.

• Architecture and utility guides

  • architecture-overview.adoc

    • Reworks the overview to include:

      • Mermaid diagrams showing Bytes/BytesStore relationships and container-level interactions.
      • A performance characteristics section aligned with CB-NF-P-*.
      • Trade-offs vs alternatives (ByteBuffer, Netty/Agrona, raw Unsafe).

  • memory-management.adoc

    • Adds a simple reference-counting state diagram (Mermaid).
    • Clarifies native vs mapped vs heap lifecycle and tracing behaviour, including how createdHere() is used.
    • Provides links to Queue/Wire architecture docs for broader context.

  • pool-overview.adoc

    • Explains trade-offs and alternatives for pooling (retained memory per thread vs reduced allocation).

  • algo-overview.adoc, render-overview.adoc, decimal-rendering.adoc, domestic-overview.adoc, util-overview.adoc, wire-integration.adoc

    • Improve explanations, convert citation placeholders to plain text, and add “trade-offs & alternatives” or tuning sections where helpful.

---

3. Microbenchmarks and performance docs

• microbenchmarks/README.adoc

  • Add :toc: and :source-highlighter: rouge.
  • Tighten wording and section titles (“How to run”, “Adding benchmarks”).

• JMH and cooler benchmarks

  • Add detailed Javadoc to:

    • AppendDoubleBenchmark – purpose, usage and configuration hints (-Dbytes.append.precision).
    • AppendLongCoolerMain, BytesCoolerMain, GenParseMain, DistributedUniqueTimeProviderBenchmark, ElasticBenchmarkRunner, ElasticByteBufferJmh, ElasticDirectJmh.

  • Introduce package-level docs:

    • microbenchmarks/src/main/java/net/openhft/chronicle/bytes/microbenchmarks/package-info.java
    • microbenchmarks/.../jmh/package-info.java
    • Explain that benchmarks are internal, subject to change and not part of the public API.

---

4. Javadoc and package-level documentation

• Add or expand package-info.java for most Chronicle-Bytes packages:

  • net.openhft.chronicle.bytes (core API), bytes.algo, bytes.domestic, bytes.internal, bytes.pool, bytes.ref, bytes.render, bytes.util.
  • New internal bytes.internal.migration package with an explanatory package-info.

• Enhance Javadoc on many public/internal types:

  • Core APIs: Bytes, BytesStore, BytesIn, BytesOut, StreamingDataInput, RandomDataInput, RandomDataOutput, BytesRingBuffer, RingBufferReader, RingBufferReaderStats, PageUtil, Invocation.
  • Native and mapped stores: NativeBytesStore, SingleMappedFile, NoBytesStore.
  • Utilities: AppendableUtil, ByteStringAppender, XxHash, BytesStoreHash, HashCodeEqualsUtil, ReentrantFileLock.
  • Time providers & benchmarks: DistributedUniqueTimeProvider, various perf harnesses.

• Examples and comments:

  • Tidy many tests (e.g. *Test classes) and add small comment headers to clarify their purpose (e.g. NativeBytesOverflowTest, NativeBytesStoreTest, NativeBytesStoreOpsTest, JLBH runners).

---

5. Tests and minor clean-ups

• Replace platform-default charset usage with explicit UTF_8 in tests and utility code, improving determinism and avoiding encoding-sensitive failures.

• Simplify or modernise tests:

  • Use JUnit5 assertions (assertInstanceOf, assertThrows, assertDoesNotThrow) and remove unused code/commented-out manual tests.

  • Add or clarify tests for:

    • decimal renderers and BigDecimal fallbacks;
    • reference-tracing leak detection and createdHere() coverage;
    • pooled Bytes lifecycle and release behaviour;
    • string/encoding helpers (StringUtils, LZW, EscapingStopCharTester);
    • interop utilities (e.g. method-writer builder, method-reader, ClassAliasPool, ClassLookup).

• Remove a redundant ThreadLocal<Bytes<?>> field from BytesPool that was no longer used in favour of ScopedResourcePool, reducing clutter without affecting behaviour.

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
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