Architecture Decision Records

Every decision that shapes the library, or changes an earlier decision, is recorded here as an ADR: NNNN-short-title.md with the sections Status, Context, Decision and Consequences. ADRs are written when their decision is first exercised. An ADR is never rewritten after it is accepted; a later ADR marks it “Superseded by NNNN”.

ADR	Title	Status
0001	Name: dynG	Accepted
0002	License and credit	Accepted
0003	Language and toolkit floors (C++17, CUDA >= 12.4, sm_75, CCCL 3.x memory-resource shape)	Accepted
0004	Naming conventions	Accepted
0006	Algorithm contract	Accepted under delegation with the 0.1 API freeze (2026-09-29, ADR 0023)
0009	Default index types (edge_t = int32 with checked construction)	Accepted (M1b)
0010	Batch and graph semantics	Proposed (M1a draft; amended in M2a: set semantics and the unweighted graph)
0011	The Python package (nanobind bindings, the typed layer, dtype dispatch, array lifetimes, locking)	Accepted under delegation (2026-09-30)
0013	Parity and goldens	Proposed (M1a draft)
0014	Approval checkpoints	Accepted
0015	Workspace sharing (scratch memory owned by resources)	Proposed (M1b)
0016	CUDA execution resources (streams, memory, errors, warm-up)	Proposed (M1b)
0017	The CUDA sssp engine, engine selection, placement and the resident device graph	Proposed (M1b); item 2 superseded by 0026
0018	The GPU clock state in the CUDA performance gate	Accepted (2026-09-28: option B, the gate is read at locked clocks; default-clock readings are reported, not gated)
0019	Merge policy (merge commits for milestone and integration work, squash for contributions, no rebase)	Accepted (INT1); amended 2026-10-14 (merge commits only)
0020	The resident device graph under set semantics (device set apply, lazily downloaded host copy), and Step 0 once per update	Accepted (2026-09-29, by the author; written in M2b, amended by the M2b review)
0021	The power cap and the base clock lock in the cycle_count CUDA gate (a case whose GPU cannot hold the boost lock is read at the base lock)	Accepted (2026-09-29, by the author)
0022	The conformance kit, the algorithm registry and the scaffold (registry-driven kit, C8’s reservations and container work, the scope of new_algorithm.py)	Accepted under delegation (2026-09-29)
0023	The 0.1 API review and freeze (the review’s findings and fixes, @guarantee, the committed public-API listing and its check)	Accepted under delegation (2026-09-29)
0024	Reading a refactor against an earlier dynG build (rounds over heap layouts, bimodal regions read mode by mode)	Accepted under delegation (2026-09-30)
0025	The command line as a Python console script (generated flags, dyng prep with mospPrep’s syntax, the originals’ output formats), and the build of the distributions (cibuildwheel in CI, the local manylinux_2_28 build, release.yml for v0.1.0+)	Accepted under delegation (2026-09-30)
0026	The sssp operators engine on CUDA (the multi-kernel, non-cooperative engine, byte-identical to the fused one) and the engine choice of 0.2	Accepted under delegation (2026-09-30)
0027	The mosp API (0.2) and mosp as a composition of K sssp problems	Accepted under delegation (2026-09-30)
0028	mosp in Python and on the command line (0.2)	Accepted under delegation (2026-10-01)
0029	The packing window, where the host and CUDA backends follow different originals (non-canonical input trees)	Accepted (2026-10-06, by the author: option A)
0030	The CUDA plugin wheels dyng-cu12 / dyng-cu13 built from the same sources (a rendered pyproject.toml, DYNG_PYTHON_PLUGIN, the static CUDA runtime, the plugin package, the pinned extras, the licence files)	Accepted under delegation (2026-10-06)
0031	Choosing a CUDA plugin (the driver’s major, the version pin), the CPU fallback with dyng.BackendWarning, and arrays in device memory from Python (__cuda_array_interface__, DLPack stream ordering, device inputs)	Accepted under delegation (2026-10-06)
0032	The CUDA plugin wheels in CI and in the release workflow (cibuildwheel with the CUDA toolkits pinned file by file, the GPU-less fallback smoke test, one publishing environment pair per distribution, the wheel-vs-parity row)	Accepted under delegation (2026-10-06)
0033	The tutorial algorithms: registered with maturity tutorial, one source for every backend (executors), undirected graphs in the kit	Accepted under delegation (2026-10-06)
0034	Reader fuzzers (cpp/fuzz), the golden mutation suites of parity/mutate.py (sssp, mosp, cycle_count) and the long property runs	Accepted under delegation (2026-10-06)
0035	The mosp API review and freeze (0.2): the review’s findings and amendments, the frozen headers following the manifests’ maturity, both API checks failing on a mosp change	Accepted under delegation (2026-10-07; the maturity stable: the author, 2026-10-07)
0036	The CBST trace format 1 and the link-time recorders of ESCHER-GPU@abcf9b2 and MOSP_ESCHER@4b86159 (the originals’ unchanged objects relinked with -Xlinker --wrap, the nm census, the twin output check, the readers, the trace goldens)	Accepted under delegation (2026-10-07)
0037	The CBST host model (dyng::testing::cbst_host_model: the flat payload, policy presets, predicted growth and compaction, isolation from the store) and the rules of the trace replay (the field sets, why per-key length is compared, hash-only rows and inputs, events, first divergence)	Accepted under delegation (2026-10-07)
0038	The port of ESCHER-GPU@abcf9b2’s CBST store (dyng::detail::escher::cbst_store: the reproducible transplant, one class of mechanical change per commit, the read points and the tie rule, the dynG additions, store_policy::escher_gpu(), the documented divergence, the replays of both originals’ traces)	Accepted under delegation (2026-10-07)
0039	The staged merge of MOSP_ESCHER@4b86159’s CBST behaviours, part 1 (the staging preset mosp_escher_staged() and its judgement against the host model; construct validation, the fill clamps, caller row counts, the bounded chain walk chain.cuh bounded by the used payload instead of 1,024 hops, the device error word, the integrity checks, rows(), scratch growth, an explicit compact(), the storage counters, the rule for dead or absent keys, the disposition of every other differing file)	Accepted under delegation (2026-10-07)
0040	The CBST presets and automatic compaction, part 2 of the staged merge (mosp_escher() with B’s compaction at its fill and insert trigger points; dynG’s default dyng_default(): compact first, then grow, capacity_error only beyond max_payload; the documented divergence construct_without_row_counts; the field set policy for the default preset; the partial-failure guarantees; B’s 9 scenarios, the lockstep with the host model, the graph-on-CBST test; the 7 CBST mutations)	Accepted under delegation (2026-10-08)
0041	The hypergraph container on the ESCHER store (PLAN 5.2 and the sketch reconciled; dead rows empty; inserted_ids on the host and an internal device copy; id-indexed weights; placement per backend; the host best-fit id allocator; capacity_policy and its presets; the order of a batch per id_reuse, skipped ops and the guarantees; the applied record; container-level id parity)	Accepted under delegation (2026-10-13)
0042	The sorted_merge line graph, the row views and the line-graph oracle (the policies; ESCHER-GPU’s delta merge ported in stages, its host form on the CPU backends, A’s layout entry by entry; the key count of the largest bound; the internal row views per commit and the public views per version; rebuild_line_graph; H2H parity by layout hashes and digests)	Accepted under delegation (2026-10-14)
0043	The hypergraph’s update path and the conformance kit’s container axis (the two-phase transaction; dyng::update() over hypergraphs through participant_of<hypergraph>; the framework’s composition for both containers; container_traits and the hypergraph presets, model and mixes; the test-only aggregate-delta fakes and the planted bug; the gaps the kit exposed)	Accepted under delegation (2026-10-14)
0044	The hypergraph scaffold and the requirements of a hypergraph manifest (_template_hypergraph; the placeholders; graph_requirements keys of a hypergraph manifest; the scaffold check’s hypergraph probes)	Accepted under delegation (2026-10-14)
0045	Hypergraph files, hypergraph batch files, the binary batch format .dgb and the hypergraph generators (.hg with the originals’ option sets; +h / -h in .dgt, one container kind per file; .dgb version 1 and the streaming batch_reader; the ESCHER dump decoder, by-content resolver and converter; library-owned generators; generators::legacy for ESCHER-GPU)	Accepted under delegation (2026-10-14)
0046	The hypergraph in Python (dyng.Hypergraph, HyperedgeBatch, HypergraphProperties, CapacityPolicy, HyperApplySummary with int64 inserted_ids; the native holders HypergraphI32U / HypergraphI32I32; id_reuse= keywords and string enumerations; int64 members refused without vertex_dtype="int32"; host copies of the views; .hg, .dgt, .dgb and BatchReader; the generators with EscherEngine; the strategies and the model; the dump replays from Python)	Accepted under delegation (2026-10-14)
0047	The hypergraph API review and freeze (0.3): the review of dyng/hypergraph/* and its tracked io, generators and testing parts by ADR 0023’s method; the additions (the batch’s incidence accessors, a noexcept constructor); the freeze’s Doxygen rules; compile-only fitness skeletons for M9 and M11; the headers frozen, both API checks failing on a deliberate change; O16 and the stability awaiting the author at 0.3.0	Accepted under delegation (2026-10-14; stable from 0.3.0: awaits the author)

Planned (PLAN Section 12.3): 0005 layout, 0007 framework, 0008 backends, 0012 versioning and stability.