The desktop podcast player's Stop sat alone at the right of the action row. It was a carry-over from the bar ADR 0045 replaced, and nothing recorded a reason to keep it. Android never had one, and neither did Music, on the grounds that pausing is all anyone wants. That is just as true of an episode, whose position is remembered, and none of the major podcast apps has a Stop. What it did was end the session: release the app-wide transport and empty the sidebar's Media row. That is a dismiss, so it now lives where dismissing does. The Media row shows a ✕ while its media is paused, which asks the owning player to end its session (MediaSessionEvent::EndRequested, the sibling of ToggleRequested). Music gets this too; it had no way to end a session. The ✕ sits left of play/pause, so it appearing on pause doesn't move the button just pressed. SecondaryAction is the rate pill alone, copy::player::STOP goes, and the speed pill keeps its height under a name of its own. ADR 0046 records it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Architecture Decision Records
This directory records significant architectural/design decisions for this project, in the style popularized by Michael Nygard's "Documenting Architecture Decisions" (2011) — one short, dated, immutable file per decision: what problem existed, what we chose, and what it costs. A later change of mind gets a new ADR that supersedes the old one rather than editing history in place.
These are retrospective for this project: rather than writing an ADR before
building something, most of these were extracted from completed TODO.md
entries, or from the "done"/"implementation note" callouts inside a living
design doc (e.g. docs/sync-management.md), once the work landed and the
outcome was known. TODO.md and the design docs remain the place for
open/in-progress work and current-state descriptions; once a decision both
finishes and represents a real architectural choice (not just a bugfix or
small feature), it moves here, and the source document is trimmed to a short
pointer at this file instead of re-narrating the decision. Purely tactical
bugfixes and small features are just deleted from TODO.md once done — not
every finished task merits a permanent record, and jj/git history already
covers those.
The one exception so far is Status: Proposed (currently 0022):
used when a decision is worth version-controlling ahead of the implementation
landing, because the design itself — not just the outcome — needs review.
Flip it to Accepted once built, in place, no new ADR needed for that
transition alone.
Index
| # | Title | Status |
|---|---|---|
| 0001 | Hermetic Android builds via the Nix flake devShell | Accepted |
| 0002 | No detekt baseline — every finding fails the build | Accepted |
| 0003 | Single shared helper for the "no display name" placeholder | Accepted |
| 0004 | CLI/TUI are daemon-first clients of the store | Accepted |
| 0005 | Daemon/client protocol versioning via build commit hash | Accepted |
| 0006 | NativeLib FFI calls return Result<T> |
Accepted |
| 0007 | Android media playback lives in a MediaSessionService |
Accepted |
| 0008 | Android navigation: NavHost + ViewModel, type-safe routes |
Accepted |
| 0009 | Two-plane sync — catalog always replicates, content is policy-gated | Accepted |
| 0010 | Three-variant SyncPolicy, plus per-document Pin/Exclude overrides |
Accepted |
| 0011 | Jobs as a first-class model, deduplicated by (kind, subject) | Accepted |
| 0012 | Continuous sync scheduler — three passes, pull-only | Accepted |
| 0013 | Blob possession evidence, and the last-copy deletion guard built on it | Accepted |
| 0014 | Remote node administration, never triggers eviction | Accepted |
| 0015 | One blob-streaming protocol for every type, not three | Accepted |
| 0016 | PDF and comics streaming adapters — download-then-open, closure-based fallback | Accepted |
| 0017 | Browser extension pairing — bounded port-range discovery, revocable bearer tokens, capability-bounded | Accepted |
| 0018 | Per-agent synced settings via a derived AgentSettings document |
Accepted |
| 0019 | Store methods take &Transaction; batch() is the only way to get one |
Accepted |
| 0020 | Sync schema versioning, plus per-record tolerance, for enum variants a peer doesn't know | Accepted |
| 0021 | Android error surfacing — four tiers, Snackbar for one-shot failures | Accepted |
| 0022 | A @ThrowsSyncException marker + custom detekt rule, Rust-#[must_use]-style |
Proposed |
| 0023 | SyncError as a deliberate FFI vocabulary, plus a Recourse projection |
Proposed |
| 0024 | Typography — Inter, UDEV Gothic, Source Serif 4, and a typeface token module |
Accepted |
| 0025 | One MediaLibrary browser component per modality, not a tree per agent |
Accepted |
| 0026 | Identity display — name plus truncated id, full value on demand | Accepted |
| 0027 | Evaluated iroh-blobs/iroh-docs against hand-rolled sync — keep doc-sync and blob-stream, revisit blob-sync's transfer layer only |
Accepted |
| 0028 | Chunked blob AEAD — the client always decrypts, never the server | Accepted |
| 0029 | Per-node content possession evidence for every artifact, with first-hand absence and promulgated eviction releases | Accepted |
| 0030 | Note bodies merge with Loro — one CRDT document per NoteBody, plaintext kept beside it |
Accepted |
| 0031 | SyncGuarded<T> — one generic type for "alert, don't apply", not one ad hoc trio per view |
Accepted |
| 0032 | Visual direction — charcoal ground, cobalt for state, color never for categories; Charcoal/Slate grounds defaulting to Charcoal | Proposed |
| 0033 | Marking availability — a rule, a word, and a tooltip, chosen by the room each surface has; the full enum until the point of use | Accepted |
| 0034 | Filtering a document tree — matches in place, ancestors as context, emphasis on the match | Accepted |
| 0035 | A PDF's own metadata is read in lib, by hayro-syntax |
Accepted |
| 0036 | The daemon handshake compares build inputs, not the commit hash | Accepted |
| 0037 | Every growable list is virtualized, in each modality's own idiom | Accepted |
| 0038 | One Provenance per document, replacing DocumentType::is_derived |
Accepted |
| 0039 | Clippings — captured text as documents under an anchored root, with a plain TextBody |
Accepted |
| 0040 | The daemon protocol stays JSON; the response body gets types instead | Accepted |
| 0041 | One change ledger for the store, one long-poll for a client — DaemonCommand::AwaitChange over per-store channels |
Accepted |
| 0042 | Persistence stays in the Rust core; Android carries no local store | Accepted |
| 0043 | Removal in the property model — a (document_id, kind) tombstone, and per-element add/remove state for SetUnion |
Accepted |
| 0044 | A node's human-readable name is ensemble-private: off /version and the DHT registry, sealed in gossip |
Accepted |
| 0045 | One transport bar per modality; agents differ only in how audio is resolved | Accepted |
| 0046 | The audio player is four fixed regions configured by capabilities, not two modes | Accepted |
| 0047 | Constituent documents — a Part provenance, not agent ownership or a parent-type test |
Proposed |
| 0048 | Content shared by several documents — liveness by reference count, and sharing disclosed wherever it changes a number | Proposed |
| 0049 | Parentage stays a field on the document; edges are for facts | Accepted |
| 0050 | Captured posts — a Post document beside Snippet, under one capture agent renamed Clippings |
Proposed |
| 0051 | Service credentials are documents on the catalog plane, sealed with the vault key | Accepted |
| 0052 | Two local listeners, and what each one is allowed to trust | Accepted |
| 0053 | One keymap for every modality | Accepted |
| 0054 | Re-importing a comic updates it in place — matched by source name, then by page set | Accepted |
| 0055 | Android screens are assembled from roles, not from Material components | Accepted |
| 0056 | Keep synchronicity-lib one crate; give hot loops their own optimized crate |
Accepted |
| 0057 | Writes take a WriteTx, which only an IMMEDIATE transaction hands out |
Accepted |
| 0058 | Writes that must survive power loss take a DurableTx |
Accepted |