Document AI/agent contribution workflow and architecture; align Queue docs and internal API boundaries

[peter-lawrey]

This PR adds repository-wide guidance for AI-assisted contributions, improves Chronicle Queue’s documentation set, and clarifies internal vs public API boundaries via package-level docs and Javadoc. The only behavioural change is a small robustness tweak in file-state detection for non-Linux platforms; all other changes are documentation or annotation/metadata only.

---

Changes

1. AI/agent guidance and model-specific docs

• Add AGENTS.md at the repo root:

  • Defines language and character-set policy (British English, ISO-8859-1, no smart quotes).
  • Gives Javadoc and inline-comment rules (only document non-obvious behaviour, contracts, edge cases).
  • Standardises build verification for contributors and bots (mvn -q clean verify from a clean checkout).
  • Describes commit/PR etiquette (≤72 char imperative subject, root-cause → fix → measurable impact, link to JIRA/GitHub).
  • Adds a per-PR security checklist (validation, authn/z, encoding/escaping, resource exhaustion, timing).
  • Introduces company-wide Nine-Box tag taxonomy (FN, NF-P, NF-S, NF-O, TEST, DOC, OPS, UX, RISK) and an ADR template.
  • Documents AsciiDoc house rules (:sectnums:, list formatting patterns, bold/emphasis).

• Add CLAUDE.md:

  • Claude Code–focused guide to the Chronicle Queue codebase: core abstractions, packages, and design principles (off-heap, single-writer, flyweights).
  • Practical build/run recipes (full build, tests, benchmarks, CLI tools).
  • Testing patterns and common test utilities (QueueTestCommon, IOTools.deleteDirWithFiles, etc.).
  • Notes on locking model, indexing, wire formats, and resource management.

• Add GEMINI.md:

  • High-level Chronicle Queue overview for multi-model tooling (project summary, key features, architecture layers).
  • Basic Maven build/benchmark commands.
  • Brief development conventions (testing, concurrency model, documentation layout).

These files are documentation-only and do not affect runtime behaviour.

---

2. New architecture, requirements, and security docs

• src/main/docs/architecture-overview.adoc

  • Explains Chronicle Queue’s role in the Chronicle stack, core concepts (append-only roll files, roll cycles, tiered indexing, pretoucher), concurrency model, durability/flush expectations, and operational considerations (retention, monitoring).

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

  • Introduces CQ-* decision records:

    • CQ-FN-101 – Queue file format and roll-cycle model.
    • CQ-FN-102 – Appender and tailer concurrency model (single-writer style, independent tailers).
    • CQ-NF-P-201 – Durability, flush policy and recovery behaviour.
    • CQ-NF-O-401 – Retention and roll-file cleanup as operational responsibility.

  • Cross-references existing docs under docs/.

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

  • Captures QUEUE-FN-* and QUEUE-NF-* requirements using the Nine-Box taxonomy for Chronicle Queue (functional behaviour, performance, security, operability).
  • Provides a requirements-to-tests mapping table to link each requirement to representative tests/benchmarks.

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

  • Summarises Chronicle Queue’s security posture:

    • Trust zone assumptions (Core/Zone B).
    • Encryption boundary for data at rest (not encrypted by default; rely on FS/volume or application-layer encryption).
    • Expectations for off-heap/mmap safety via Chronicle-Bytes.
    • Retention/roll-file responsibilities and logging/diagnostics considerations.

  • References the QUEUE-NF-S-* and QUEUE-NF-O-* requirements and CQ-NF-S-301 / CQ-NF-O-401 decisions.

All four documents are AsciiDoc-only and formalise existing behaviour and design decisions.

---

3. Documentation clean-up and consistency

• README and docs alignment

  • Set AsciiDoc headers consistently (:lang: en-GB, :source-highlighter: rouge) across README.adoc and many docs/*.adoc and Antora pages.
  • Replace textual “microseconds” with µs where appropriate (e.g. latency guarantees and benchmark descriptions).
  • Fix typos and grammar (e.g. “Chornicle” → “Chronicle”, “What technology does Chronicle Queue using?” → “use?”).

• System-properties doc rename and link fix

  • Rename docs/systemProperties.adoc → docs/system-properties.adoc.
  • Update all references, including in README.adoc, to the new path.
  • Add a document title and :toc: to system-properties.adoc and tighten the table options ([cols=4*,options="header"]).

• AsciiDoc structural improvements

  • Remove inlined binary cq4 dumps from documentation sections in favour of prose that explains the binary format and how to dump via tools.
  • Add missing :toc: or :sectnums: and fix section levels where appropriate (e.g. MigratingToV4.adoc headings).
  • Normalise list and section formatting (no indentation-dependent lists; consistent subsection naming and anchors).
  • Clarify JDK build instructions and encourage explicit JAVA_HOME usage in FAQ/quick-start/command-line docs.
  • Update demo prerequisites (Maven 3.8.x instead of 3.6.x) and remove outdated IDE/git walkthrough that is no longer maintained.

These are purely documentation changes; they do not alter code behaviour.

---

4. Public vs internal API boundaries and Javadoc

• New package-info.java files:

  • net.openhft.chronicle.queue – describes the core public API and emphasises single-writer semantics and non-thread-safe appenders/tailers.
  • net.openhft.chronicle.queue.impl, .impl.single, .impl.table – mark implementation classes (storage, roll-cycle, indexing, table store) as internal/non-API.
  • net.openhft.chronicle.queue.rollcycles – describes roll-cycle definitions as configuration primitives.
  • net.openhft.chronicle.queue.reader, .reader.comparator – documents reader tools as operational/diagnostic utilities rather than core APIs.
  • net.openhft.chronicle.queue.internal.* (and subpackages .domestic, .main, .reader, .writer, .util) – explicitly state that these are strictly internal, not to be used via casting/reflection/serialization, and subject to change without notice.

• Javadoc enhancements:

  • Add or expand Javadoc on:

    • ChronicleQueue.indexForId(String) – describes return value as the LongValue tracking a named tailer’s position.
    • ChronicleQueue.createPretoucherEventHandler() – clarifies that it creates an EventHandler to drive pretouching.
    • ExcerptCommon<E> – documents the type parameter for fluent chaining and clarifies the semantics of currentFile() and sync().
    • TailerDirection and TailerState enums – each constant now has descriptive Javadoc.
    • ExcerptContext – documented as a short-lived view over read/write Wire and timeout.
    • Internals such as RollingResourcesCache, SingleTableBuilder, NoOpWriteLock, and several reader/writer helper classes.

• Constructor visibility improvements:

  • ChronicleHistoryReaderMain and ChronicleReaderMain now have explicit public no-arg constructors for easier testability and embedding.
  • CLI entrypoints (BenchmarkMain, DumpMain, HistoryMain, PingPongMain, ReaderMain, RefreshMain, RemovableRollFileCandidatesMain, UnlockMain, ChronicleWriterMain) now have private constructors annotated via comments as “utility holders” to make non-instantiability explicit.

These changes are descriptive/metadata-only and do not change method semantics.

---

Functional / behavioural impact

The code changes are intentionally minimal and low-risk:

• NoOpCondition.await(long, TimeUnit) signature:

  • Method no longer declares throws InterruptedException. The implementation already never threw and always returns true, so this narrows the declared contract without changing behaviour.

• Deprecation markers (API surface only, no immediate behaviour change):

  • Mark several legacy/testing-only methods and constants as @Deprecated with a comment indicating removal in or after 2027, for example:

    • ChronicleQueue.dumpLastHeader()
    • ExcerptAppender.wire()
    • NoMessageHistory enum
    • ExcerptContext.timeoutMS()
    • WireStore.indexable(long)
    • WireStoreSupplier.CreateStrategy.canBeReused(...)
    • SingleChronicleQueue.DISK_SPACE_CHECKER_NAME
    • SingleChronicleQueueBuilder.DEFAULT_SPARSE_CAPACITY
    • PrecreatedFiles.preCreatedFileForStoreFile(...)
    • WriteLock.isLockedByCurrentProcess(LongConsumer)
    • Reader lifecycle/testing hooks (Reader.stop(), ChronicleReader.withDocumentPollMethod(...))

  • These are signature-only changes for now; runtime behaviour is unchanged. Callers will see new deprecation warnings and can begin migrating away.

• Tests and minor method signatures:

  • A few test methods drop unused checked exceptions from signatures (throws IOException removed where not thrown).
  • Some overrides and suppressions are added to satisfy static analysis and make intent explicit (no behavioural changes).

[sonarqubecloud]

Quality Gate passed

Issues
40 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