SBK documentation

This directory contains the authoritative engineering documentation for Storage Benchmark Kit. The root README is the product and quick-start entry point; this page routes readers to the right level of detail.

Reading paths

New user

1. Project README: requirements, build, first benchmark, and module overview.
2. WebLogger guide: the dependency-free SBK Local Web Console for SBK, SBM, and SBK-GEM.
3. The README under the selected drivers/<name>/ directory: backend prerequisites and examples.
4. Architecture and code flow: what happens after the command starts.

New contributor

1. Contributing guide: workflow, standards, and verification.
2. Repository map: where code and configuration live.
3. Driver guide: the most common extension workflow.
4. Engineering recipes: task-oriented implementation procedures.

Maintainer or reviewer

1. Architecture and code flow: ownership boundaries and lifecycle.
2. Internal design: detailed PerL measurement flow, ElasticWait, timestamp queues, SBM, and SBP design.
3. TimeStampMpscQueue research guide: intrusive MPSC queue architecture, correctness evidence, JDK comparison, and reproducible performance methodology.
4. Exact latency recorders research guide: dense-array, boxed-map, and primitive-map algorithms, memory models, correctness, and JDK 25 JMH results.
5. Documentation maintenance: how to keep examples and links current.
6. Agent-documentation distribution: how documentation enters release artifacts.

Coding agent

1. AGENTS.md: repository constraints and required verification.
2. INSTRUCTIONS.md: compact compatibility entry point.
3. Engineering recipes: deterministic task playbooks.
4. Driver specification template: spec-driven driver work.

Document ownership

Document	Authoritative for
README.md	Product overview, installation, first run, top-level commands
ARCHITECTURE.md	Module boundaries, code flow, lifecycle, concurrency, extension points
REPOSITORY_MAP.md	Directory and important-file navigation
DRIVER_GUIDE.md	Driver inventory, contract, structure, and verification
CONTRIBUTING.md	Human contribution workflow and definition of done
AGENTS.md	Agent rules and repository-specific constraints
AGENT_RECIPES.md	Exact task procedures
DRIVER_SPECIFICATION.md	Fillable design template for new drivers
WEB_LOGGER.md	SBK Local Web Console usage, lifecycle, options, security, and troubleshooting
sbk-internals.md	Detailed design rationale and research-oriented treatment
TIMESTAMP_MPSC_QUEUE.md	Intrusive timestamp queue architecture, JDK comparison, correctness evidence, and research methodology
LATENCY_RECORDERS.md	Exact array and sparse-map latency storage, complexity, memory accounting, correctness, and reproducible JMH results
PerlBench driver	End-to-end timestamp-queue comparison using exact-count, timed, and rate-controlled SBK workloads
Component READMEs	Component operation and component-specific examples
Driver READMEs	Backend prerequisites, properties, limitations, and example commands

When documents disagree, source code and generated -help output are authoritative. Correct the nearest authoritative document instead of copying a workaround into several READMEs.

Generated and historical material

• */javadoc/ contains generated API documentation. Do not hand-edit generated HTML or its bundled legal notices.
• PDFs in docs/ are design publications and historical references, not operational instructions.
• Long console transcripts in some driver READMEs are examples from particular environments, not performance guarantees.
• Dashboards, Docker definitions, and Kubernetes examples are operational assets; their nearby README explains their use.

Documentation standards

• Use repository-relative links for files in this repository.
• Name the source class or Gradle task that supports an architectural claim.
• Mark defaults as defaults, not requirements, unless validation enforces them.
• Never present benchmark numbers as generally reproducible results.
• Keep commands runnable from the repository root unless a different directory is explicitly stated.
• Use ./gradlew, not an assumed system Gradle installation.
• Update both the detailed guide and its entry-point link when introducing a new subsystem.

See DOCUMENTATION_GUIDE.md for the review checklist.