Improve Chronicle Bytes documentation, Java 8 buffer compatibility, and edge-case handling

AGENTS.md

@@ -1,161 +1,53 @@
-# Guidance for AI agents, bots, and humans contributing to Chronicle Software's OpenHFT projects.
+# Chronicle-Bytes contributor guide
 
-LLM-based agents can accelerate development only if they respect our house rules. This file tells you:
+Specifics for this module. Authoritative docs live in `src/main/docs/` (landing page: `README.adoc`).
 
-* how to run and verify the build;
-* what *not* to comment;
-* when to open pull requests.
+## Language and character set
 
-## Language & character-set policy
+* British English (`organisation`, `behaviour`, `licence`); keep US technical terms (`synchronized`).
+* ISO-8859-1 only. No smart quotes, en-dashes, non-breaking spaces, or accented characters.
+* Where a symbol is unavailable, write it out: `>=`, `<=`, `:alpha:`.
+* Verify with `iconv -f ascii -t ascii < file`.
 
-| Requirement                                                                                                                                                                       | Rationale |
-|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
-| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized`                                       | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. |
-| **ISO-8859-1** (code-points 0-255), except in string literals. Avoid smart quotes, non-breaking spaces and accented characters.                                                   | ISO-8859-1 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. |
-| If a symbol is not available in ISO-8859-1, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. |
+## Javadoc
 
-## Javadoc guidelines
+Document what is *not* obvious from the signature: behavioural contracts, edge cases, thread-safety,
+units, performance, and checked exceptions.
 
-**Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is
-noise and slows readers down.
+* No restating the obvious (`Gets the value`, `Sets the name`).
+* First sentence is the summary line; keep it short.
+* Drop autogenerated comments on trivial getters and setters rather than keeping them as filler.
 
-| Do | Don't |
-|----|-------|
-| State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name"). |
-| Keep the first sentence short; it becomes the summary line in aggregated docs. | Duplicate parameter names/ types unless more explanation is needed. |
-| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide. | Pad comments to reach a line-length target. |
-| Remove or rewrite autogenerated Javadoc for trivial getters/setters. | Leave stale comments that now contradict the code. |
-
-The principle that Javadoc should only explain what is *not* manifest from the signature is well-established in the
-wider Java community.
-
-## Build & test commands
-
-Agents must verify that the project still compiles and all unit tests pass before opening a PR:
+## Build
 
 ```bash
-# From repo root
-mvn -q verify
+mvn -q clean verify             # must exit 0 before opening a PR
+mvn -q -P quality clean verify  # Checkstyle + SpotBugs (gating on Java 11+)
+mvn -q -P sonar   clean verify  # JaCoCo coverage and SonarCloud inputs
+mvn -Dtest=BytesTest#someMethod test  # single test
 ```
 
-## Commit-message & PR etiquette
-
-1. **Subject line <= 72 chars**, imperative mood: Fix roll-cycle offset in `ExcerptAppender`.
-2. Reference the JIRA/GitHub issue if it exists.
-3. In *body*: *root cause -> fix -> measurable impact* (latency, allocation, etc.). Use ASCII bullet points.
-4. **Run `mvn verify`** again after rebasing.
-
-## What to ask the reviewers
-
-* *Is this AsciiDoc documentation precise enough for a clean-room re-implementation?*
-* Does the Javadoc explain the code's *why* and *how* that a junior developer would not be expected to work out?
-* Are the documentation, tests and code updated together so the change is clear?
-* Does the commit point back to the relevant requirement or decision tag?
-* Would an example or small diagram help future maintainers?
-
-## Project requirements
-
-See the [Decision Log](src/main/docs/decision-log.adoc) for the latest project decisions.
-See the [Project Requirements](src/main/docs/project-requirements.adoc) for details on project requirements.
-
-## Elevating the Workflow with Real-Time Documentation
-
-Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to documentation.
-Ensure the relevant `.adoc` files are updated when features, requirements, implementation details, or tests change.
-This tight loop informs the AI accurately and creates immediate clarity for all team members.
-
-### Benefits of Real-Time Documentation
-
-* **Confidence in documentation**: Accurate docs prevent miscommunications that derail real-world outcomes.
-* **Reduced drift**: Real-time updates keep requirements, tests and code aligned.
-* **Faster feedback**: AI can quickly highlight inconsistencies when everything is in sync.
-* **Better quality**: Frequent checks align the implementation with the specified behaviour.
-* **Smoother onboarding**: Up-to-date AsciiDoc clarifies the system for new developers.
-* **Incremental changes**: AIDE flags newly updated files so you can keep the documentation synchronised.
-
-### Best Practices
-
-* **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area should prompt reviews and potential updates in the others.
-* **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from code/tests back to documentation, which should then be reviewed and finalised.
-* **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier for humans and AI analysis tools.
-- **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of all artefacts.
-
-## AI Agent Guidelines
-
-When using AI agents to assist with development, please adhere to the following guidelines:
-
-* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ISO-8859-1 guidelines outlined above.
-Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present in the code or existing documentation.
-* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it provides additional context or clarification.
-* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's documentation standards before committing it to the repository.
-
-## Company-Wide Tagging
-
-This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use the <Scope>-<Tag>-xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different. Component-specific decisions live in their xxx-decision-log.adoc files.
-
-### Tag Taxonomy (Nine-Box Framework)
-
-To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in addition to the existing ALL prefix, which remains reserved for global decisions across every project.
-
-.Adopt a Nine-Box Requirement Taxonomy
-
-|Tag | Scope | Typical examples |
-|----|-------|------------------|
-|FN |Functional user-visible behaviour | Message routing, business rules |
-|NF-P |Non-functional - Performance | Latency budgets, throughput targets |
-|NF-S |Non-functional - Security | Authentication method, TLS version |
-|NF-O |Non-functional - Operability | Logging, monitoring, health checks |
-|TEST |Test / QA obligations | Chaos scenarios, benchmarking rigs |
-|DOC |Documentation obligations | Sequence diagrams, user guides |
-|OPS |Operational / DevOps concerns | Helm values, deployment checklist |
-|UX |Operator or end-user experience | CLI ergonomics, dashboard layouts |
-|RISK |Compliance / risk controls | GDPR retention, audit trail |
-
-`ALL-*` stays global, case-exact tags. Pick one primary tag if multiple apply.
-
-### Decision Record Template
-
-```asciidoc
-=== [Identifier] Title of Decision
-
-Date:: YYYY-MM-DD
-Context::
-* What is the issue that this decision addresses?
-* What are the driving forces, constraints, and requirements?
-Decision Statement::
-* What is the change that is being proposed or was decided?
-Alternatives Considered::
-* [Alternative 1 Name/Type]:
-** *Description:* Brief description of the alternative.
-** *Pros:* ...
-** *Cons:* ...
-* [Alternative 2 Name/Type]:
-** *Description:* Brief description of the alternative.
-** *Pros:* ...
-** *Cons:* ...
-Rationale for Decision::
-* Why was the chosen decision selected?
-* How does it address the context and outweigh the cons of alternatives?
-Impact & Consequences::
-* What are the positive and negative consequences of this decision?
-* How does this decision affect the system, developers, users, or operations?
-- What are the trade-offs made?
-Notes/Links::
-** (Optional: Links to relevant issues, discussions, documentation, proof-of-concepts)
-```
+## Commits and PRs
 
-## Asciidoc formatting guidelines
+* Subject line `<= 72` chars, imperative mood, reference JIRA/GitHub issue if one exists.
+* Body: root cause -> fix -> measurable impact.
+* Keep PRs focused; do not bundle unrelated refactors.
+* Re-run `mvn -q clean verify` after rebase or review changes.
 
-### List Indentation
+## AsciiDoc conventions
 
-Do not rely on indentation for list items in AsciiDoc documents. Use the following pattern instead:
+* Header includes `:toc:`, `:sectnums:`, `:lang: en-GB`, `:source-highlighter: rouge`.
+* Use `:sectnums:` for numbering; do not prefix titles with manual numbers.
+* `_text_` is emphasis, `*text*` is bold.
+* Use markup for nesting, not indentation:
 
 ```asciidoc
-section:: Top Level Section
 * first level
-  ** nested level
+** nested level
 ```
 
-### Emphasis and Bold Text
+## Requirement and decision tags
 
-In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.
+Use the Nine-Box taxonomy (`FN`, `NF-P`, `NF-S`, `NF-O`, `TEST`, `DOC`, `OPS`, `UX`, `RISK`).
+`ALL-*` is reserved for cross-project decisions. Pick one primary tag if multiple apply.
+See `src/main/docs/project-requirements.adoc` for the canonical list.

CLAUDE.md

@@ -0,0 +1,34 @@
+# Claude Code notes
+
+Read `AGENTS.md` first. This file only adds what Claude needs that AGENTS.md does not cover.
+
+## What this library is
+
+Chronicle Bytes is a low-level off-heap memory access library: a `ByteBuffer` alternative with
+63-bit sizes, reference-counted cleanup, and rich primitive/string/struct APIs.
+
+* `Bytes` is elastic and tracks read/write positions; `BytesStore` is fixed-size with no positions.
+* Off-heap allocations are reference-counted: every `allocateElasticDirect()` needs `releaseLast()`
+  (or use try-with-resources). Tests assert this with `assertReferencesReleased()` from
+  `chronicle-test-framework`.
+* `Bytes` is not thread-safe. `BytesStore` may be shared if writes are externally synchronised.
+  Atomic CAS / volatile ops exist on `int`, `long`, `float`, `double`.
+* `writePosition` is also the `readLimit`; you do not flip between modes.
+
+## Where things live
+
+* Production code: `src/main/java/net/openhft/chronicle/bytes/` (sub-packages `algo`, `internal`,
+  `pool`, `ref`, `render`, `util`, `domestic`).
+* Documentation: `src/main/docs/*.adoc` (canonical). `system-properties.adoc` is the full property
+  reference.
+* Tests: JUnit 5 preferred; `*Test` suffix; `forkCount=4, reuseForks=true`.
+* Dependencies are pinned via `chronicle-bom` / `third-party-bom`; do not hard-code versions.
+
+## Things that bite
+
+* Forgetting `releaseLast()` on direct `Bytes`.
+* Using `Bytes` from multiple threads.
+* Pasting Unicode (smart quotes, em-dashes) into source or `.adoc` files; the build will accept it
+  but it violates the ISO-8859-1 rule in AGENTS.md.
+* Adding `@Deprecated` to public API based on this repo's test usage alone: downstream
+  (Chronicle-Wire, Chronicle-Queue, customers) almost certainly uses it.