Document Chronicle-Core architecture, requirements and internal helpers

[peter-lawrey]

This change set is a documentation and developer-experience sweep across Chronicle-Core. It aligns the module with the DOCS_PLAYBOOK (Nine-Box taxonomy, requirements/ADRs, runbooks), clarifies AI-agent guidance, and adds missing Javadoc/package-info coverage for many internal packages. There are no intentional runtime behaviour changes.

---

Functional changes

• Benchmarks:

  • Add an explicit package benchmarks; declaration to MapBenchMain and a matching root package-info.java so the standalone benchmark launcher sits in a real package and can be imported/run consistently.
  • Add Javadoc to several JLBH/JMH benchmark classes (AsDoubleImplementationPerfJLBH, Interrupted, TimeProviders, etc.) to clarify intent and usage; benchmark logic is unchanged.

• Assertions & checked-exceptions modules:

  • Add package-info.java for net.openhft.chronicle.assertions (assertions enabled/disabled variants) and for the checked-exceptions overlays (java.lang, java.nio) to document how profiles select “assertions on/off” and “checked exception” variants.
  • Clarify AssertUtil examples and spacing so that SKIP_ASSERTIONS-guarded code continues to compile down to no-ops in the assertions-disabled profile.

• Time & init hooks:

  • Add Javadoc to ChronicleInitRunnable and TimeProvider/LongTime, documenting when init hooks run and pointing readers to UniqueMicroTimeProvider for monotonic microsecond timestamps (behaviour unchanged).

• Minor structural clean-ups:

  • Re-order a few static inner holder classes (Jvm.MaxMemoryHolder, OS.*Holder) so constants are defined before private constructors; no code paths or values change.
  • Replace a few “assert false;” test statements with explicit throw new AssertionError() in test-only code to avoid depending on JVM -ea for correctness.

Overall, no public API signatures or runtime semantics are changed; functional impact is limited to benchmark packaging and test robustness.

---

Non-functional changes

1. AI agent & contributor guidance

• AGENTS.md (Chronicle-Core flavour):

  • Clarify that repository-level AGENTS.md provides base rules, with this file documenting Chronicle-Core specifics and pointing at src/main/docs/README.adoc as the durable doc landing page.

  • Tighten language/character-set guidance:

    • Keep British English spelling, now with an explicit link to the University of Oxford style guide.
    • Re-emphasise ISO-8859-1 usage and remove low-value detail about “8-bit ASCII variants”.
    • Add examples and tooling hints for ASCII/ISO-8859-1 compliance (e.g. iconv and IDE inspections).

  • Extend Javadoc guidance with an inline-comment “BAD vs GOOD” example to discourage noise comments.

  • Add a “When to open a PR” section: require mvn -q clean verify to pass, link to issue/decision IDs, and encourage focused, single-concern PRs.

  • Add guidance for AsciiDoc section numbering (:sectnums:) and discourage manually numbered headings; show a minimal header template.

• New AI-assistant guides:

  • CLAUDE.md: in-depth Claude Code guide describing Chronicle-Core’s role, architecture, build commands (tests, benchmarks, assertions profile), resource management patterns, and documentation standards (Nine-Box tags, requirements/ADRs, security review).
  • GEMINI.md: equivalent guidance for Gemini, including project overview, key features, build/test/benchmark commands, doc-first expectations, Javadoc rules, and commit-message etiquette.

---

2. Documentation structure and content

• README & top-level docs

  • README.adoc:

    • Normalise the header: add :toc:, :sectnums:, :lang: en-GB, :source-highlighter: rouge.
    • Switch inline section headings (e.g. OS calls, JVM access, memory-mapped files, deterministic resource management) to proper AsciiDoc sections and use opts=novalidate on code fences to avoid validation noise.
    • Fix anchors (e.g. [#system-properties-from-file], [#os-calls], etc.) and correct the system-properties link to src/main/docs/system-properties.adoc.
    • Note that operator runbooks now live under src/main/docs/runbooks/, each linked back to CORE-* requirements.

• New / restructured AsciiDoc set under src/main/docs/

  • New files:

    • architecture-overview.adoc: Chronicle-Core capability map, component diagram (PlantUML), interactions with downstream modules (Queue, Bytes, Threads, Wire), external dependencies (JNA, SLF4J, Posix), and evolution guard-rails tied to Nine-Box tags.
    • performance-targets.adoc: qualitative performance expectations (zero/near-zero allocations on hot paths, bounded overhead for tracing and BackgroundResourceReleaser), and how to validate them (benchmarks, decision records).
    • testing-strategy.adoc: testing layers, traceability to CORE-FN/CORE-OPS/CORE-NF-*, recent CI snapshot (Java 8 & 21 runs), and a backlog of planned tests (especially for CORE-NF-P-* and CORE-RISK-003).
    • system-properties.adoc: replaces the deleted docs/systemProperties.adoc with a Chronicle-Core–scoped AsciiDoc table of system properties, defaults, and backing static fields.

  • Major existing doc updates:

    • functional-requirements.adoc and project-requirements.adoc:

      • Add anchors for each functional area and expand prose so requirements are easier to link from ADRs/runbooks.
      • Introduce non-functional performance (CORE-NF-P-001..003, 006) and security (CORE-NF-S-001..003) requirements, aligning with the new performance and security docs.

    • decision-log.adoc:

      • Add new decisions:

        • CORE-NF-P-006 documenting UniqueMicroTimeProvider’s monotonic microsecond semantics and CAS loop behaviour.
        • CORE-DOC-007 consolidating CI evidence and runbook documentation into AsciiDoc, deprecating scattered Markdown sidecars.

      • Tighten Nine-Box wording and use emphasised text instead of bold for identifiers.

    • deterministic-resource-management.adoc, memory-management-guide.adoc, object-pooling-and-caching.adoc, common-pitfalls-and-debugging.adoc, thread-safety-guarantees.adoc, jvm-and-os-utilities.adoc, exception-overview.adoc, advanced-maths-functions.adoc:

      • Enable :sectnums: where missing and standardise headings, anchors and description lists.

      • Rework lists into AsciiDoc description lists for clarity (e.g. “Failing to release()” → explanation/example/debugging steps).

      • Clarify subtle points like:

        • behaviour of BackgroundResourceReleaser flags and when releasePendingResources() is required;
        • safe use of UniqueMicroTimeProvider in tests with SetTimeProvider;
        • alignment pitfalls on ARM and how to use OS.pageAlign/OS.mapAlign.

  • Operational / runbook updates:

    • operational-requirements.adoc: add a CI data-collection checklist (build/test artefacts, coverage, security scans, docs snapshot, environment metadata).

    • ops-scenarios.adoc: standardise layout and wording, maintain quarterly review reminder.

    • Runbooks (native-affinity.adoc, releaser-drain.adoc, resource-tracing.adoc, system-properties.adoc):

      • Add “Signals and metrics”, edge cases, and more explicit preconditions and verification steps.
      • Clarify how to diagnose missing JNA/native affinity, stuck background releaser queues, and property-override precedence (system.properties vs -D flags).

• Traceability

  • New src/main/docs/requirement-test-map.csv mapping requirements (CORE-FN, CORE-NF-P, CORE-OPS, CORE-RISK) to concrete tests or CI jobs, with a status column (covered vs planned) and short notes on what each test asserts.
  • system-architecture.adoc extended with a “Documentation audit snapshot” summarising the current AsciiDoc set, runbooks, traceability map, and CI expectations.

---

3. Javadoc and package-info coverage

• Add or expand package-info.java across many packages to improve Javadoc coverage and IDE hover docs:

  • Core APIs: net.openhft.chronicle.core, core.io, core.util, core.values, core.time, core.threads, core.pool, core.scoped, core.shutdown, core.onoes, core.pom.
  • Internal namespaces: core.internal, core.internal.analytics, core.internal.announcer, core.internal.cleaner, core.internal.pom, core.internal.util, core.internal.invariant.ints, core.internal.invariant.longs, core.domestic, core.analytics, core.announcer, core.cleaner, core.cleaner.spi, core.cooler.

• Add focused Javadoc to internal helpers to explain intent without altering behaviour, for example:

  • CpuClass, DirectBufferUtil, MapUtil, RangeUtil, ThreadConfinementLifecycle, VanillaThreadConfinementAsserter, NopThreadConfinementAsserter.
  • Analytics plumbing: MuteAnalytics, MuteBuilder, ReflectiveAnalytics, ReflectiveBuilder, ReflectionUtil, StandardMaps.
  • Buffer cleaning: Jdk9ByteBufferCleanerService, ReflectionBasedByteBufferCleanerService.
  • Invariants and assertion helpers: IntCondition, LongCondition, SimpleCleaner, WeakIdentityHashMap.
  • Resource tracking: TracingReferenceCounted, VanillaReferenceCounted, ValidatableUtil, IOTools, Wget, ThreadConfinementAsserter.
  • Event/threading helpers: VanillaEventHandler, CleaningThreadLocal, ScopedThreadLocal (including explanation of the “discard newest when full” policy), StrongReferenceScopedResource, WeakReferenceScopedResource.
  • Value interfaces and time providers: LongTime, TimeProvider, Value interface guide, with updated package-level documentation.

• Clean up and standardise imports, comments and test code formatting across test sources (JUnit 4/5 mix), without changing assertions’ intent.

[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