Queue test backlog kickoff, CLI/doc polish, and realistic coverage gates — plus a small builder enhancement

[peter-lawrey]

This PR seeds a Chronicle Queue test programme with concrete, high-value cases; adds a light docs polish for CLI users; tunes JaCoCo gates to today’s achieved coverage; and introduces a fluent builder helper for QueueOffsetSpec. Together, these changes tighten behaviour around named tailers, file growth/rolls, CLI usage, async buffering, and raw/size-prefixed frames.

Why

• Close gaps identified during cross-repo reviews (Logger, Queue-Enterprise, CLI, Network).
• Make CLI behaviours and options discoverable where users look first.
• Lock in invariants that downstream modules already depend on (offset specs, zero-length frames, method-writer payload stability).
• Keep CI green with thresholds that reflect current reality (and can ratchet up).

---

What changed

Planning & Coverage

• NEW_TESTS.md: in-flight research notes mapping real-world issues to test assertions (Logger knobs, async buffering, pretoucher, failover).
• TESTS_TODO.md: concrete Queue test batches (A–M) with scopes, targets, and acceptance criteria.
• JaCoCo gates (pom.xml): line 0.7888, branch 0.6989 (also in sonar profile) and defaultGoal=verify under the profile.

Builder/API

• SingleChronicleQueueBuilder#queueOffsetSpec(QueueOffsetSpec): fluent setter that applies the spec (spec.apply(this)) and returns the builder. Useful for tests, named-tailer fixtures, and config plumbing.

  • Backwards-compatible; no existing behaviour changed.

Tests — highlights

Async buffering & two-thread runs

• ChronicleQueueTwoThreadsTest

  • Short, CI-friendly runs.
  • Variants for BufferMode.Asynchronous vs None, heap vs direct Bytes for tailer/appender.
  • Auto-downgrade when enterprise buffering isn’t available (graceful assumeTrue).

CLI realism

• ChronicleReaderMainCliTest

  • -n <index> start-from support (decimal/hex).
  • -r + -g snapshot to assert MessageHistory inclusion and WireType selection.

• ChronicleWriterMainCliTest

  • Accept multiple YAML files in a single invocation (ordered writes).

Method-writer payload stability

• MethodReaderObjectReuseTest

  • Heap and direct DTOs: mutating the source after write does not corrupt the consumed payload.
  • Deterministic construction counters reset per test.

Raw access & size-prefixed frames

• RawAccessJavaTest

  • Validates size prefix equals payload length (no C++ needed).
  • Zero-length size-prefixed document is readable and does not block the next entry.

Write path ergonomics

• WriteBytesTest

  • Reuse a direct buffer across appends and validate readback.
  • Roll-cycle capacity remains stable across rolls.

Builder parity & reopen semantics

• SingleChronicleQueueBuilderTest

  • Mirrors Logger knobs: blockSize, bufferCapacity, rollCycle, sourceId, wireType.
  • Reopen queue and assert metadata/roll cycle/sourceId survive restarts.

Offset spec coverage

• QueueOffsetSpecTest

  • EPOCH format/parse round-trip; NONE is a no-op; bad types throw; invalid TZ fails validate().
  • Uses the new builder.queueOffsetSpec(spec).

Reader/tailer with file growth & rolls

• issue/ReaderResizesFileTest

  • Tailer ref-count stability while appender grows.
  • Holding a document across a roll does not resize the old cycle.
  • Zero-length document treated as “present, empty” and doesn’t consume the next message.

Named tailers

• namedtailer/NamedTailerVersioningTest

  • toStart() rewind works as expected.
  • moveToIndex() resumes at stored index after restart.

Pretoucher ergonomics

• PretouchUtilTest

  • Event handler creation on OSS remains safe.
  • action() on a closed queue does not explode (either no-op or expected InvalidEventHandlerException).

Docs (Antora)

• Appending / CLI / Tailing / Utilities

  • ChronicleWriterMain: multiple YAML files per invocation (batching).
  • ChronicleReaderMain: -n accepts decimal or hex, -g shows MessageHistory with -r.
  • Cross-links (TIP:) to the canonical CLI reference to reduce drift.
  • Utilities: document parity of queue_reader.sh switches with Maven runner.