Skip to content

decision-log.adoc

Latest commit

 

History

History
116 lines (89 loc) · 4.53 KB

decision-log.adoc

File metadata and controls

116 lines (89 loc) · 4.53 KB

Decision Log - OpenHFT Posix

Table of Contents
ID Title (scope) Date Tags

ALL-DOC-001

Language and Character-Set Policy

2025-05-26

DOC, UX

POSIX-FN-002

Provider Fallback Order

2025-05-26

FN, NF-P

ALL-DOC-002

Real-Time Documentation Loop

2025-05-26

DOC, OPS

POSIX-NF-O-003

No-Op Provider Contract

2025-05-26

NF-O, TEST

ALL-OPS-004

Nine-Box Tag Taxonomy Adoption

2025-05-26

OPS

This log records Posix-specific decisions and a small set of global ALL-* decisions that are particularly relevant to the module. Identifiers follow the <Scope>-<Tag>-NNN pattern, where Scope is POSIX for module decisions and ALL for company-wide items.

1. ALL-DOC-001 Language & Character-Set Policy

Context

Chronicle teams span multiple regions. Mixed US/UK spelling and occasional UTF-8 artefacts caused build failures in binary wire-format tests and confused spell-checkers.

Decision

  • Use British English spelling for prose/code except fixed US technical spellings (synchronized, Serializable).

  • Restrict all source and documentation files to ISO-8859-1 (Latin-1) code-points (0-255).

Alternatives considered

Allow UTF-8 universally - rejected: breaks zero-copy buffers that rely on MSB=0. Allow US spellings - rejected: inconsistent with London HQ style guide.

Consequences

  • Tooling: CI linter added (scripts/check-ascii.sh).

  • On-boarding: documented in AGENTS.md; IDE templates updated.

Links

2. POSIX-FN-002 Provider Fallback Order

Context

The Posix facade must run on Linux, macOS and Windows. Performance varies between native libraries (JNR, JNA) and reflection. Deterministic bootstrap order avoids surprises.

Decision

At first successful class-load we try providers in this strict order:

  1. JNRPosixAPI

  2. WinJNRPosixAPI

  3. JNAPosixAPI

  4. RawPosixAPI

  5. NoOpPosixAPI

Override with -Dchronicle.posix.provider.

Alternatives

ServiceLoader scan - too slow; non-deterministic. OS-hard-coded providers - would fork the code-base per platform.

Consequences

  • Single-point selection in PosixAPIHolder.

  • Unit tests must set POSIX_TEST_ALLOW_NATIVE=false to force No-Op in CI.

Links

3. ALL-DOC-002 Real-Time Documentation Loop

Context

Documentation drift led to mis-generated code from AI agents. The team adopted a "doc-first or doc-alongside" workflow but lacked formal guidance.

Decision

  • Update AsciiDoc in the same commit as code/tests.

  • CI fails if a PR touches src/main/java without touching any .adoc and scripts/doc-drift-check.sh flags potential drift.

Consequences

Quicker feedback, cleaner PR reviews, slightly longer dev cycle per change.

Links

4. POSIX-NF-O-003 No-Op Provider Contract

Context

Some environments (Graal native-image, security-restricted CI) cannot load native libs.

Decision

NoOpPosixAPI compiles everywhere, returns 0 for safe no-ops, -1 (or throws PosixRuntimeException(errno=ENOSYS)) where silent failure may lose data. lastError() fixed at 0.

Consequences

Baseline behaviour predictable; integration tests must stub filesystem side-effects.

Links

5. ALL-OPS-004 Nine-Box Tag Taxonomy Adoption

Context

Requirement and decision identifiers historically varied across Chronicle projects, which made cross-repository traceability and compliance checks harder to automate.

Decision

Adopt the Nine-Box taxonomy for requirement and decision identifiers, using <Scope>-<Tag>-NNN with tags such as FN, NF-P, NF-S, NF-O, DOC, OPS, TEST, UX, and RISK.

Alternatives considered

Per-project schemes - simpler locally but do not scale across shared tooling or audits. Free-form tags - easy to start with but impossible to validate consistently.

Consequences

  • Build and documentation tooling must recognise the Nine-Box tags.

  • New requirements and decisions in Posix and other modules must allocate unique identifiers within their scope.

Links