Document AI contribution rules and modernise hashing + test suite in Chronicle-Algorithms

.gitignore

@@ -9,7 +9,8 @@
 *.iml
 *.ipr
 *.iws
-.idea
+.idea/
+.claude/
 compat_reports
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
@@ -25,4 +26,4 @@ target
 
 # tests
 *.bin
-*.deleteme
+*.deleteme

AGENTS.md

@@ -0,0 +1,161 @@
+# Guidance for AI agents, bots, and humans contributing to Chronicle Software's OpenHFT projects.
+
+LLM-based agents can accelerate development only if they respect our house rules. This file tells you:
+
+* how to run and verify the build;
+* what *not* to comment;
+* when to open pull requests.
+
+## Language & character-set policy
+
+| 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 guidelines
+
+**Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is
+noise and slows readers down.
+
+| 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:
+
+```bash
+# From repo root
+mvn -q verify
+```
+
+## 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)
+```
+
+## Asciidoc formatting guidelines
+
+### List Indentation
+
+Do not rely on indentation for list items in AsciiDoc documents. Use the following pattern instead:
+
+```asciidoc
+section:: Top Level Section
+* first level
+  ** nested level
+```
+
+### Emphasis and Bold Text
+
+In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.

CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Chronicle-Algorithms is a zero-allocation, high-performance Java library providing efficient algorithms for:
+- Hashing (CityHash, MurmurHash, XxHash)
+- Bit set operations
+- Raw byte access to data types
+- Off-heap locking mechanisms
+
+Part of the OpenHFT Chronicle suite, this library focuses on performance-critical operations with minimal memory allocation.
+
+## Build and Test Commands
+
+### Building
+```bash
+mvn clean install
+```
+
+### Running Tests
+```bash
+# Run all tests
+mvn test
+
+# Run a single test class
+mvn test -Dtest=BitSetTest
+
+# Run a specific test method
+mvn test -Dtest=BitSetTest#testFlip
+```
+
+### Code Coverage
+The project uses JaCoCo for code coverage with targets defined in pom.xml:
+- Line coverage: 57.9%
+- Branch coverage: 36.4%
+
+## Architecture
+
+### Package Structure
+
+The codebase is organized into four main functional areas under `net.openhft.chronicle.algo`:
+
+#### 1. Hashing (`algo.hashing`)
+- **LongHashFunction**: Abstract base class for all hash function implementations. Subclasses should implement methods for single primitives, `hashVoid()`, and the core `hash(Object, ReadAccess, long, long)` method. All other methods delegate to these.
+- Hash implementations: `CityHash_1_1`, `MurmurHash_3`, `XxHash_r39`
+- All hash functions produce cross-platform consistent results (same output on little-endian and big-endian systems), though performance favors little-endian platforms
+
+#### 2. Bytes Access (`algo.bytes`)
+- **Access Pattern**: The core abstraction for reading/writing raw bytes from various data sources
+  - `ReadAccess<T>`: Read operations on type T
+  - `WriteAccess<T>`: Write operations on type T
+  - `Access<T>`: Combines both read and write capabilities
+  - `AccessCommon<T>`: Base interface with common metadata operations
+- **Accessor Pattern**: Converts between source types and Access handles
+  - `Accessor<S, T, A>`: Maps source type S to target type T with access strategy A
+  - Implementations for arrays, ByteBuffer, BytesStore, CharSequence
+- **Key implementations**:
+  - `NativeAccess`: Direct native memory access
+  - `ByteBufferAccess`: Access ByteBuffer contents
+  - `BytesAccesses`: Access Chronicle Bytes BytesStore
+  - Array accessors for all primitive types
+- The Access/Accessor pattern enables uniform byte-level operations across heterogeneous data sources (heap arrays, direct buffers, off-heap memory)
+
+#### 3. Bit Sets (`algo.bitset`)
+- **BitSet**: Main interface with rigid `logicalSize()` (unlike java.util.BitSet which has dynamic capacity)
+- **BitSetAlgorithm**: Static utility methods operating on raw memory via Access pattern
+- **BitSetFrame**: Combines BitSet interface with Access-based implementation
+  - `SingleThreadedFlatBitSetFrame`: Optimized for single-threaded use
+  - `ConcurrentFlatBitSetFrame`: Thread-safe implementation with atomic operations
+- **ReusableBitSet**: Adapter for reusing BitSet instances with different underlying storage
+- All operations throw IndexOutOfBoundsException for out-of-bounds access
+
+#### 4. Locks (`algo.locks`)
+- Off-heap locking strategies for concurrent access control
+- **LockingStrategy**: Base interface for lock/unlock/reset operations via Access pattern
+- **Lock state interfaces**: Separate state from strategy
+  - `ReadWriteLockState` / `ReadWriteLockingStrategy`
+  - `ReadWriteUpdateLockState` / `ReadWriteUpdateLockingStrategy` (adds update locks)
+  - `ReadWriteUpdateWithWaitsLockState` / corresponding strategy (tracks waiting threads)
+- **AcquisitionStrategy**: Defines try/lock behaviors (`TryAcquireOperation`, `TryAcquireOperations`)
+- Vanilla implementations: `VanillaReadWriteUpdateWithWaitsLockingStrategy`, `VanillaReadWriteWithWaitsLockingStrategy`
+- All locking is managed through the Access abstraction, enabling off-heap lock storage
+
+### Key Design Patterns
+
+1. **Access/Accessor Abstraction**: Unified interface for byte-level operations on diverse data sources. Access defines operations on a handle type T, while Accessor converts sources to Access handles with offset calculations.
+
+2. **Zero-Allocation**: Algorithms are designed to avoid object allocation in hot paths. Prefer primitive types, reuse objects (e.g., ReusableBitSet), and operate directly on raw memory.
+
+3. **Off-Heap Support**: All core algorithms work via the Access pattern, allowing operations on off-heap memory without GC pressure.
+
+4. **Strategy Pattern**: Locking and hashing use strategy interfaces to allow algorithm selection and customization.
+
+## Dependencies
+
+Core Chronicle dependencies:
+- `chronicle-core`: Foundation utilities
+- `chronicle-bytes`: Byte buffer abstractions
+
+Test framework uses both JUnit 4 and JUnit 5 (Jupiter), plus Mockito for mocking.
+
+## License
+
+Apache 2.0 (SPDX-License-Identifier: Apache-2.0)
+Copyright 2013-2025 chronicle.software