Split requirements into focused docs, add ops/runbooks, tighten init ordering, and expand Core test matrix (with tuned JaCoCo gates)

[peter-lawrey]

This change elevates Chronicle Core’s documentation, operational guidance, and test coverage while making a handful of targeted correctness and determinism fixes. It replaces the monolithic project-requirements.adoc with focused specs (functional, data, operational, interface control, and system architecture), wires the docs into AGENTS.md, introduces an executable test-batch plan, and nudges quality gates to realistic, enforceable levels.

Why

• Traceability: Map behaviours to stable IDs (CORE-FN-*, CORE-DATA-*, CORE-OPS-*) that tests, ADRs, and runbooks can reference.
• Operational clarity: Provide runbooks and scenario guides so operators can resolve common issues without source spelunking.
• Deterministic boot: Ensure ChronicleInit hooks can set properties before Jvm consumes them.
• Stable gates: Align JaCoCo thresholds with current, repeatable coverage while preventing regressions.

What changed (highlights)

Documentation & developer UX

• AGENTS.md: Replace single “Project Requirements” link with a navigable suite: Functional, Data, Operational, Interface Control (ICD), and System Architecture.

• New specs:

  • functional-requirements.adoc: CORE-FN-001..055 catalogue.
  • data-requirements.adoc: CORE-DATA-* identifiers for on-wire and telemetry shape.
  • operational-requirements.adoc: CORE-OPS-* guarantees operators can rely on.
  • interface-control.adoc: API contracts tied back to CORE-FN-*.
  • system-architecture.adoc: capability map and component interactions.

• Runbooks & scenarios:

  • runbooks/system-properties.adoc, runbooks/resource-tracing.adoc, runbooks/releaser-drain.adoc, runbooks/native-affinity.adoc.
  • ops-scenarios.adoc: common failure modes → resolution breadcrumb trail.

• Security & pooling docs:

  • object-pooling-and-caching.adoc: expand with ScopedThreadLocal semantics and guard rails.
  • security-review.adoc: cross-link to thread-safety guarantees.

Decision log maintenance

• Update cross-refs from the removed project-requirements.adoc to the new functional spec; adjust notes for CORE-OPS-* entries.

Build & quality gates

• JaCoCo: set line 0.77 and branch 0.67 as project defaults and in the sonar profile to reflect current, stable coverage while keeping pressure on critical paths.
• Maven: set defaultGoal to verify under the sonar profile to drive report generation consistently.
• License plugin excludes: add surefire-buildagent/**, **/*.deferred, and system-properties-precedence*.properties to avoid false positives.

Core behaviour fixes

• Boot ordering: call ChronicleInit.init() at the top of Jvm static init so pre-init runnables can prepare or override properties before Jvm reads them.

• Resource tracing noise: gate the “resource tracing enabled” WARN behind notJUnitTest to keep CI logs clean.

• Thread-local cleanup race: synchronise CleaningThreadLocal.cleanupNonCleaningThreads() internal list manipulation; make the method robust under concurrent callers.

• Scoped pools: validate ScopedThreadLocal capacity (maxInstances > 0) early to prevent misconfiguration.

• I/O helpers:

  • IOTools.createTempDirectory(...): actually create the directory (and mark for delete-on-exit); surface IO errors.
  • IOTools.createTempFile(...): materialise a unique, target-scoped file path and ensure parent prep is safe/idempotent.

Tests & utilities

• Test batch plan: new TESTS_TODO.md with 11 reproducible command batches to exercise the most sensitive areas pre-publish.

• New/expanded tests (selected):

  • Boot/props ordering: ChronicleInitPrecedenceTest, SystemPropertiesProbeMain, SystemPropertiesPrecedenceTest.
  • Thread-locals & cleanup: CleaningThreadLocalIntegrationTest, ScopedThreadLocalLifecycleTest.
  • Reference counting & releaser: ReferenceCountingFuzzTest, ReferenceTracingIntegrationTest, BackgroundResourceReleaserTest additions.
  • OS/page size & alignment: OSPageAlignmentTest.
  • I/O: IOToolsCreateDirectoriesTest, IOToolsTempDirectoryTest.
  • Onoes: Slf4jExceptionHandlerTest fallback path, ThreadLocalisedExceptionHandlerTest, ChainedExceptionHandlerTest.
  • POM metadata: InternalPomPropertiesMatrixTest.
  • Time provider: SetTimeProviderTest concurrency, parsing, and unit conversions.

• Test resources: custom-system.properties for classpath precedence checks.

Backwards compatibility

• APIs: no public API signature changes.

• Behavioural notes:

  • Jvm now guarantees init runnables execute before property hydration. Expect earlier failures for misconfigured hooks (desirable).
  • ScopedThreadLocal will now throw if maxInstances <= 0 (fast-fail).
  • Temp helpers have stricter error handling; callers may now see clear IORuntimeException on env issues.

Operational impact

• New CORE-OPS-* requirements documented; runbooks added and linked from AGENTS.md.
• Logging of resource tracing WARNs suppressed in unit tests; unchanged in normal runtime.

[sonarqubecloud]

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
65.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud