Tighten provider bootstrap, du//proc handling and add quality+architecture docs

[peter-lawrey]

1. More robust du helper in PosixAPI

   • PosixAPI.du(String filename) now:

     • Uses InputStreamReader with StandardCharsets.UTF_8 instead of the platform default.
     • Explicitly checks that du produces at least one line of output; if not, it throws an IOException rather than failing later with a NullPointerException or NumberFormatException.

   • Behavioural impact:

     • CLI encoding for du output is now deterministic (UTF-8).
     • Callers that previously saw obscure parse errors on empty output will now get a clear checked error (IOException: du produced no output for ...).

2. ProcMaps now reads /proc/*/maps with explicit UTF-8 and NIO APIs

   • ProcMaps constructor switched from new FileReader(...) to Files.newBufferedReader(Paths.get(...), StandardCharsets.UTF_8).

   • Behavioural impact:

     • Charset used to parse /proc/.../maps is now explicit and consistent.
     • Otherwise semantics are unchanged: the same Mapping objects are produced for valid lines and an invalid line will still fail fast.

3. Thread-safe initialisation and switching of PosixAPI provider

   • PosixAPIHolder now:

     • Declares POSIX_API as volatile.
     • Synchronises loadPosixApi() and useNoOpPosixApi() to ensure only one active provider instance is selected under concurrent access.

   • Behavioural impact:

     • Removes potential race conditions where multiple threads could initialise different providers concurrently.
     • Guarantee that PosixAPI.posix() always returns a consistent singleton even under heavy multi-threaded startup.

4. Clarified default behaviour for mlockall

   • PosixAPI.mlockall(int flags) default implementation remains a no-op for providers that do not support mlockall, but is now explicitly documented as such and acknowledges the parameter to avoid warnings.

   • Behavioural impact:

     • No change in behaviour, but the contract is now clearer: unsupported providers are allowed to ignore mlockall calls instead of failing, and this is intentional.

5. Minor JNR implementation refinements

   • JNRPosixAPI:

     • Caches get_nprocs_conf in cachedNprocsConf (same lazy caching semantics, clearer naming).
     • Renames the internal mlock2_ helper to mlock2Native(...) and continues to fall back to plain mlock on unsupported platforms or flags.
     • Adds explicit catch-and-ignore comments for the fallocate64 and posix_fallocate fallbacks; behaviour remains the same (fall back to plain fallocate or return -1 on error).

   • Behavioural impact:

     • No functional change intended; these are internal clean-ups to make the code easier to reason about and to keep SpotBugs happy.

6. Behavioural contract strengthened and covered by tests

   • New tests validate and lock in behaviour that was previously implicit:

     • NoOpPosixAPITest and NoOpConcurrencyTest verify that:

       • Safe operations in NoOpPosixAPI return neutral values or false as per the documented contract.
       • Unsupported operations throw PosixRuntimeException with a consistent message rather than failing silently.
       • lastError() always returns 0, even under multi-threaded access.

     • PosixAPIDefaultsTest verifies that:

       • The lseek and mmap enum overloads correctly delegate to the integer/bit-mask variants.
       • Default mlock / mlockall implementations behave as described (no-op, no exceptions).

     • PosixAPIHolderTest checks:

       • Initialisation is idempotent.
       • useNoOpPosixApi() replaces the current provider with a NoOpPosixAPI.
       • Concurrent calls to loadPosixApi() converge on a single provider instance.

   • Behavioural impact:

     • No new behaviour, but the previously informal contracts are now exercised by tests and less likely to regress.

---

Non-functional changes

1. Build and quality profiles

   • BOM update:

     • net.openhft:third-party-bom bumped from 3.27ea5 to 3.27ea7.
     • This can pull in newer dependency versions across the module; behaviour should be checked in downstream integration, but there are no direct API changes inside Posix tied to this bump.

   • New quality Maven profile:

     • Adds maven-checkstyle-plugin (3.6.0) configured with:

       • chronicle-quality-rules Checkstyle configuration.
       • failOnViolation=true, logViolationsToConsole=true, and includeTestSourceDirectory=true.

     • Adds spotbugs-maven-plugin (4.9.8.1) with:

       • Effort = Max, threshold = Low, includeTests=true.
       • Shared include/exclude filters from chronicle-quality-rules.
       • Bound to process-test-classes with the check goal, so SpotBugs findings gate the build.

     • Usage:

       • mvn -P quality clean verify will now run the stricter quality gates for this module.

   • Impact:

     • CI and local builds using -P quality will now fail on Checkstyle or SpotBugs issues, raising the non-functional bar for new changes.
     • No runtime impact; this is purely build-time quality enforcement.

2. Architecture, requirements, security and system-properties documentation

   • New docs under src/main/docs:

     • architecture-overview.adoc – module architecture, role in Chronicle stack, provider selection and performance expectations.
     • decision-log.adoc – Posix-specific decisions and a small set of shared ALL-* decisions, now aligned with the Nine-Box taxonomy.
     • project-requirements.adoc – moved from src/main/adoc/ to src/main/docs/, slightly tightened wording and cross-references.
     • security-review.adoc – threat model and secure coding considerations for Posix.

   • New top-level docs:

     • systemProperties.adoc – documents Posix-relevant system properties (for example mlockall.dump, jvm.isarm).
     • TODO.md – module-local TODO, aligned with the global ARCH_TODO / ISO-alignment work.

   • README and licence header updates:

     • README.adoc/LICENSE.adoc now include standard AsciiDoc front-matter (:toc:, :lang: en-GB, :source-highlighter: rouge) and updated links to the new src/main/docs locations.

3. Agent guidance and documentation style

   • AGENTS.md extended to include Posix-specific guidance:

     • Module purpose, build commands, and quality expectations.
     • Requirements to maintain Nine-Box IDs and traceability in src/main/docs.
     • Stronger guidelines on Javadoc/comments and AsciiDoc style (section numbering via :sectnums:, use of :: lists, British English, ISO-8859-1 only).
     • Security review checklist for every PR and “when to open a PR” expectations.

4. Checkstyle-related clean-ups

   • Minor code style updates (comments, whitespace, CHECKSTYLE:OFF/ON guards) across:

     • ClockId, MMapProt, Mapping, PosixAPI, various JNR interfaces and tests.

   • These are purely cosmetic and aimed at keeping the new quality profile clean.

---

Testing

• New and existing unit tests have been added/updated to cover:

  • No-Op provider behaviour and concurrency (NoOpPosixAPITest, NoOpConcurrencyTest).
  • Provider bootstrap (PosixAPIHolderTest).
  • Default method delegation and contracts (PosixAPIDefaultsTest).
  • Mapping and /proc parsing (MappingTest, ProcMapsTest, ProcMapsEdgeCaseTest).
  • Exception behaviour (PosixRuntimeExceptionTest).
  • JNR time/clock tests (JNRPosixAPITest minor improvements).