Architecture docs and small robustness fixes for Chronicle Queue

[peter-lawrey]

This PR is mostly documentation and developer-experience focused:

• Adds LLM-specific guides (CLAUDE.md, GEMINI.md) so agents interact safely and correctly with this repo.
• Introduces a Chronicle Queue architecture pack: architecture-overview.adoc, decision-log.adoc, project-requirements.adoc, security-review.adoc, testing-strategy.adoc.
• Normalises and tidies existing docs (British English, AsciiDoc conventions, µs notation, internal cross-links).
• Bumps the Chronicle third-party BOM to 3.27ea7.

Along the way, a few small but real behavioural/functional changes were made — these are called out explicitly below.

---

Functional / Behavioural Changes

1. CLI and help output now explicitly use UTF-8

Changed:

• ChronicleHistoryReaderMain.printHelpAndExit(...)
• ChronicleReaderMain.printHelpAndExit(...)
• internal.writer.ChronicleWriterMain.printHelpAndExit(...)
• internal.main.InternalDumpMain.dump(...)

Behavioural impact:

• Help text and dump output are now written using OutputStreamWriter(..., StandardCharsets.UTF_8) rather than the platform default encoding.
• This prevents mojibake / broken characters when option descriptions or output contain non-ASCII characters.

Breaking risk: low – only affects console encoding; content is the same, just consistently UTF-8.

---

2. Index checking flag is now final + configurable via helper

Changed:

• QueueSystemProperties:

  • public static boolean CHECK_INDEX → public static final boolean CHECK_INDEX = checkIndex();

  • New internal state: private static volatile boolean checkIndexEnabled.

  • New methods:

    • public static boolean checkIndex()
    • public static void setCheckIndex(boolean enabled)

• Call sites now use QueueSystemProperties.checkIndex() in assertions rather than accessing a mutable static field directly.

Behavioural impact:

• Semantics at runtime are unchanged by default:

  • CHECK_INDEX still reflects the queue.check.index system property at startup.

• Tests (and tooling) can temporarily override index-check behaviour via QueueSystemProperties.setCheckIndex(boolean) rather than mutating a public static field.

Breaking risk: very low – the constant remains; only code that mutated CHECK_INDEX directly is now broken and should be switched to setCheckIndex(...).

---

3. Better directory handling and warnings in SingleChronicleQueue / builder

Changed:

• SingleChronicleQueue constructor:

  • On init, if builder.readOnly() is false and the target path does not exist:

    • It now attempts path.mkdirs() and logs a warning via Jvm.warn if the directory still does not exist.

• SingleChronicleQueueBuilder.builder(File file, WireType wireType):

  • If the supplied file.toString() is "" (empty string):

    • Logs a warning saying the current directory is being used.
    • Falls back to new File(".") as the base path.

• SingleChronicleQueueBuilder.metapath():

  • When creating QUEUE_METADATA_FILE, uses path.mkdirs() and logs a warning if it cannot create the directory.

Behavioural impact:

• Misconfigured paths now show up as log warnings instead of failing silently or relying on later IOException.
• The special-case where users accidentally pass new File("") becomes explicit and noisy, nudging them towards a dedicated queue directory.

Breaking risk: low – previously this was largely silent; now you get safer behaviour plus extra logging.

---

4. Safer OS/file APIs and fallbacks

Changed:

• InternalFileUtil.state(File):

  • Previously assumed getAllOpenFilesIsSupportedOnOS() and would throw UnsupportedOperationException on unsupported OSes if misused.

  • Now:

    • If getAllOpenFilesIsSupportedOnOS() is false, it falls back to stateWindows(file).

• SingleChronicleQueue.dump() debug block (Linux):

  • /proc/self/maps is now read using StandardCharsets.UTF_8.

Behavioural impact:

• state(File) no longer surprises callers with UnsupportedOperationException on non-Linux platforms; it delegates to the Windows-specific implementation where needed.
• Debug map reading is robust against locale/encoding.

Breaking risk: very low – behaviour becomes more consistent across platforms.

---

5. Tailer direction sanity check and store accessor contract

Changed:

• StoreTailer.incrementIndex():

  • switch (direction) now has a default case that throws IllegalStateException("Unsupported direction " + direction) instead of doing nothing if an unknown direction appears.

• StoreTailer.store():

  • Now annotated as @Nullable (behaviour unchanged; just acknowledges that it may return null if no store is active).

Behavioural impact:

• Improper or future tailer directions will now fail fast instead of falling through silently.
• This makes tailer behaviour more robust to misuse or misconfiguration.

Breaking risk: low – this will only surface if external code has been feeding invalid TailerDirection values into the tailer.

---

6. Miscellaneous small behaviour/robustness tweaks

• MicroToucher:

  • Now explicitly ignores any Throwable during page touching with a comment, clarifying that pretouching is a best-effort optimisation.

• AbstractTSQueueLock.toString():

  • Includes tableStore in toString(), improving logging/debugging.

• ChronicleReader.asMethodReader(String):

  • Fixes a small logic issue so that entryHandlerFactory is set correctly when a non-empty interface name is supplied; the dummy handler is only used when the name is empty.

• ChronicleHistoryReader.printPercentilesSummary():

  • Counter for percentile lines is now initialised close to usage, but output is unchanged.

• ChronicleHistoryReaderMain, ChronicleReaderMain, ChronicleWriterMain:

  • Help printing now uses UTF-8-aware writers; ChronicleWriterMain also writes an error message to stderr when exiting due to invalid arguments.

---

Non-functional / Docs / DX Changes

These are non-functional from the queue’s point of view but worth noting:

• New LLM agent guides:

  • CLAUDE.md – detailed repo guide for Claude Code (build commands, queue lifecycle, architecture, performance knobs).
  • GEMINI.md – high-level Chronicle Queue overview and build/run notes for Gemini.

• New architectural and process docs:

  • src/main/docs/architecture-overview.adoc
  • src/main/docs/decision-log.adoc
  • src/main/docs/project-requirements.adoc
  • src/main/docs/security-review.adoc
  • src/main/docs/testing-strategy.adoc

• Docs normalisation:

  • Added :lang: en-GB and :source-highlighter: rouge consistently.
  • Converted “microseconds” to µs in latency/benchmark sections.
  • Clarified guidance on roll cycles, retention, async mode, queue utilities, and performance pages.
  • Removed the obsolete docs/antora/modules/demos/pages/demos.adoc.

• Dependencies:

  • net.openhft:third-party-bom upgraded 3.27ea5 → 3.27ea7.

[sonarqubecloud]

Quality Gate passed

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