adr

Architecture Decision Records

ADRs record durable decisions. The code cannot explain these decisions alone. Each record is a short markdown file. The file has a date. The file has a number in creation order (NNNN-kebab-title.md).

When to add an ADR

Add a record when a decision is:

• load-bearing — changing it breaks correctness, portability, or a frozen contract.
• non-obvious — a reader cannot reconstruct the reasoning from the code alone. For example: why a specific ort feature flag is pinned, why a cursor is monotonic, why two resampler caches must not be shared.

Do not add an ADR for clear code. Do not add an ADR for release history. Release history lives in CHANGELOG.md. Do not add an ADR for frozen IPC interfaces. Frozen IPC interfaces live in docs/references/contracts/.

Format

# ADR NNNN — <imperative title>

Date: YYYY-MM-DD
Status: accepted | superseded by NNNN | deprecated

## Context

<one paragraph: the problem and the forces that make it non-obvious>

## Decision

<one paragraph: what we chose>

## Consequences

<bullet list: what this forces on future code, and what it rules out>

Writing rules

Write new ADRs in ASD-STE100 Simplified English. See docs/agents/engineering.md for the rules. Use short sentences. Use active voice. Use one topic per sentence. Use one word for one meaning.

Do not rewrite accepted ADRs. To supersede one: write a new ADR, then change only the old ADR’s Status line (for example to superseded by NNNN). Leave every other line of the old ADR untouched. Do not delete accepted records.

Index

• 0001 — ADR format and scope
• 0002 — PlaybackCoordinator serializes the control plane
• 0003 — IPC types are snake_case end-to-end
• 0004 — transport_generation is the monotonic transport identity
• 0005 — Realtime audio callback is lock-free
• 0006 — Multi-stem streaming uses all-or-nothing buffering
• 0007 — Opaque generation newtypes prevent cross-space comparison
• 0008 — Waveform cache is per (song_id, bucket_count), single-flight
• 0009 — Demucs stem order is vocals, drums, bass, other
• 0010 — Library sort is mixed-script, locale-aware, case-insensitive
• 0011 — Remote library mirror is database-first, files-lazy
• 0012 — CDG seek resets both timelines, transport_generation preserves renderer
• 0013 — Use standards as product quality baselines
• 0014 — Route product standards by changed surface
• 0015 — Lyrics acquisition uses a multi-source fallback chain (superseded by 0026)
• 0016 — Source separation runs locally with ONNX Runtime
• 0017 — Release evidence binds publication to tested bytes
• 0018 — Remote Repository modules own complete lifecycles
• 0019 — Execution provider selection uses host capability
• 0020 — Validate execution provider compatibility before separation
• 0021 — App language is sticky after choice
• 0022 — Windows runtime load uses the install directory
• 0023 — Windows runtime falls back to CPU on load timeout
• 0024 — Windows runtime load strategy
• 0025 — Windows runtimes link the MSVC CRT statically
• 0026 — Put AMLL first among online lyrics sources
• 0027 — Upgrade online Line-timed Lyrics only on a confident AMLL match
• 0028 — Do not depend on AGPL AMLL player packages
• 0029 — Centered lyrics use an in-house focus stage
• 0030 — Focus stage owns line slots, word roman, and emphasis