adr

Architecture Decision Records

This directory captures the architectural decisions made on pbr-cpp-memory-pool as lightweight, immutable Markdown records — one decision per file.

Format

Each ADR follows the Michael Nygard format and is created from template.md. File naming: NNNN-short-kebab-title.md, where NNNN is a zero-padded sequential number.

Lifecycle

Proposed ─► Accepted ─┬─► Superseded by ADR-XXXX
                     └─► Deprecated

• Proposed — decision drafted, under discussion. Allowed to evolve.
• Accepted — decision is in force. The record is now immutable; only the Status line may change.
• Superseded — a newer ADR replaces this one. Both records remain in the repo; the older one points to the newer one in its Status line, the newer one references the older in Context.
• Deprecated — the decision no longer applies but is preserved for historical context.

When to write an ADR

Write one when a decision:

• affects the public C or C++ API of the pool;
• affects ABI, alignment, or thread-safety guarantees;
• has two or more reasonable alternatives and the rationale is not obvious from the code;
• supersedes or amends a prior ADR.

Do not write one for purely local implementation details, formatting, or trivially reversible choices — those belong in the commit body.

Index

Number	Title	Status
0001	Record architecture decisions	Accepted
0002	Adopt a Maven-style cross-language source layout	Accepted
0003	Design Patterns Policy	Accepted
0004	Versioning and Release Policy	Accepted
0005	Toolchain Matrix and Supported Platforms	Accepted
0006	Code style and static-analysis baseline	Accepted
0007	Test framework — doctest	Accepted
0008	Delegate tag creation and push to the agent	Accepted
0009	Free-list layout, block_size constraints, and alignment guarantee	Accepted
0010	RAII for the Pool wrapper and Pimpl across the C/C++ boundary	Accepted
0011	Factory Method and Builder for Pool construction	Accepted
0012	Foreign-pointer and out-of-range pointer policy	Accepted
0013	Doxygen for the API contract, Markdown for the narrative	Accepted
0014	Microbenchmark methodology — pool vs. malloc	Accepted
0015	Metadata-overhead budget and introspection contract	Accepted
0016	Exception policy at the C/C++ boundary	Accepted
0017	TypedPool design — block-size derivation and typed surface	Accepted
0018	STL-compatible allocator Adapter — routing and propagation traits	Accepted
0019	Read-only free-list diagnostic Iterator — gating and traversal	Accepted
0020	Thread-safety Strategy and compile-time configuration knob	Accepted
0021	Template Method allocation skeleton with thread-safety hook points	Accepted
0022	Dynamic-growth policy and chunk-linking strategy	Accepted
0023	Composite chunk-list representation	Accepted
0024	Dynamic-growth synchronization, creation surface, and the lock-free deferral	Accepted
0025	Decorator for an instrumented pool variant	Accepted
0026	Observer for pool-lifecycle events	Accepted
0027	Doxygen HTML API site published to GitHub Pages	Accepted
0028	Install and packaging layout — Phase 1 distribution	Accepted
0029	Specification-compliance acceptance audit (v1.0.0 gate)	Accepted
0030	vcpkg port — Phase 2 distribution (overlay, pinned to v1.0.0)	Accepted
0031	Conan recipe — Phase 2 distribution (in-repo, pinned to v1.0.0)	Accepted
0032	Documentation i18n architecture	Accepted
0033	English as the specification's normative language	Accepted
0034	Post-release maintenance protocol	Accepted
0035	Agent-runnable consistency lint	Accepted
0036	Extract the session journal from ROADMAP.md into dated per-session files	Accepted
0037	A new feature is planned on the roadmap — new milestone or appended item	Accepted
0038	Split the changelog into one immutable Markdown file per release	Accepted
0039	In-repo bug ledger and agent triage protocol	Accepted
0040	Pull-request metadata policy (assignee, labels, milestone)	Accepted

When adding a new ADR, append a row to this table in the same PR.