ADR candidates
As of 2026-10-09, main @ 67b846e3. This document lists the surfaces,
structures, seams and contracts in this repo that deserve an Architecture
Decision Record. It builds on architecture-overview.md
and is the second step of the "Project Management 101" plan.
How it was produced. Five read-only Sonnet agents worked in parallel: recorded-decision inventory, shell and library contract, auth and security, agent/client/wire contract, and git/PR history (1,648 commits, about 300 PRs and issues). The load-bearing claims were spot-checked against code before writing. Items marked (unverified) were reported but not confirmed.
How to read this
Each candidate has a kind:
| Kind | Meaning | Work needed |
|---|---|---|
| Retro | The decision is made and shipped; its reasoning lives only in code comments, commit bodies or one person's head. | Write it down: context, decision, alternatives, consequences. Cheap. |
| Open | The code embodies a choice nobody has explicitly made, or there is a live tension (open issue, known gap, contradiction). | A decision meeting first, then the ADR. |
| Amend | An existing ADR or doc covers part of it and is stale or too broad. | Edit or split the existing record. |
Priority.
- P1: a wrong or unrecorded call here constrains forks, deployers, IdP operators or the backend team, or has security impact.
- P2: a contributor convention that is costly to reverse.
- P3: useful to pin down, but low reversal cost.
"Who is bound" names whoever has to know about the decision outside this repo's maintainers.
Ranked summary
| # | Candidate | Kind | Pri | Who is bound |
|---|---|---|---|---|
| C01 | Library public API and compatibility policy | Open | P1 | Forks |
| C02 | Module composition contract — done: ADR-004 (#620) | Retro | P1 | Forks |
| C03 | Module layering and inter-module contracts — proposed: ADR-005 (#620) | Open | P1 | Forks, contributors |
| C04 | Server identity, alias and URL scheme | Open | P1 | Users (links), forks |
| C05 | Web sign-in via backend BFF and token custody on web | Open | P1 | Backend, deployers |
| C06 | Sign-out and IdP session end | Retro + Open | P1 | Backend, IdP operators |
| C07 | User identity and in-memory isolation | Open | P1 | IdP operators |
| C08 | Rendering untrusted model output | Open | P1 | Users, deployers |
| C09 | Logging privacy and diagnostics exposure | Amend + Open | P1 | Contributors, forks |
| C10 | Backend compatibility contract | Open | P1 | Backend team |
| C11 | Run lifecycle and failure reporting | Amend + Open | P1 | Backend team |
| C12 | Timeline, runs and bands model — done: ADR-006 (#620) | Retro | P1 | Contributors |
| C13 | Signals convention and the 7.x migration | Open | P1 | Contributors, forks |
| C14 | HTTP client stack and token refresh | Retro | P2 | Forks |
| C15 | Stream resume, history replay and failures-as-data | Retro | P2 | Backend team |
| C16 | Error taxonomy as a UI contract | Retro | P2 | Forks |
| C17 | Client-side tools, approval and host APIs | Open | P2 | Forks |
| C18 | Device-local persistence scheme | Retro | P2 | Contributors |
| C19 | Platform split conventions | Retro | P2 | Contributors |
| C20 | OIDC deployment requirements | Retro | P2 | IdP operators |
| C21 | Multi-database thread semantics | Retro | P2 | Backend team |
| C22 | Inactivity logout policy | Open | P3 | Deployers |
| C23 | Time handling | Retro | P3 | Contributors |
| C24 | Product constraints that bind engineering | Retro | P3 | Contributors |
| C25 | Design package boundary and token governance | Amend | P3 | Forks |
| C26 | Boot validation and theme requirements — partly covered by ADR-004 §3.7 | Amend | P3 | Forks |
Dependencies between candidates
Deciding some of these first makes others easier or changes their answer.
flowchart LR
C01["C01 Public API policy"] --> C02["C02 Module contract"]
C01 --> C14["C14 HTTP stack"]
C01 --> C16["C16 Error taxonomy"]
C02 --> C03["C03 Layering"]
C03 --> C18["C18 Persistence"]
C04["C04 Server identity"] --> C18
C04 --> C07["C07 User isolation"]
C05["C05 Web BFF + tokens"] --> C06["C06 Sign-out"]
C05 --> C07
C10["C10 Backend compat"] --> C15["C15 Resume and replay"]
C10 --> C21["C21 Multi-db"]
C11["C11 Run lifecycle"] --> C12["C12 Timeline model"]
C15 --> C12
C13["C13 Signals convention"] --> C12
C09["C09 Logging privacy"] --> C08["C08 Untrusted rendering"]
Housekeeping on existing records
Done in #608, except splitting ADR-001, which was deferred: its axes are numbered, so it can be split when one of them changes.
Do these before writing new ADRs. They are small and they set the template.
- ADR-003 is
Proposedbut shipped.FlavorandFlavorThemeare inlib/src/core/flavor.dart. Mark itAccepted. Its §2 blockquote aboutrunSoliplexShelltaking a builder was patched in place, so record it as an amendment instead. - ADR-001 bundles six decisions. These include the
ThreadKeyrecord, ownership-based discovery and runtime-owned disposal. The repo-wide rule "Riverpod is DI only, signals for state" sits in §5.3 as a rejected alternative. Lift that rule into its own record, or into C13. docs/plans/0001-app-shell/proposal.mdis stale. It says modules use "no base class or registry", butAppModulereplacedModuleContributioninda882974. Add a superseded note.docs/developer-setup.mdis stale. It still describesag_uias a git dependency with Git LFS.pubspec.lockshows the hosted pub.dev0.3.0.docs/adr/has no index. Add aREADME.mdwith the template, the status vocabulary (Proposed,Accepted,Superseded,Deprecated) and a table of ADRs.AGENTS.md's "Key Documentation" lists neither ADRs nordiagnostics-known-risks.md.- Template. Keep the existing numbered shape:
- header bullets: Status, Date, Authors, Supersedes, Superseded by, Amends;
- §1 Context;
- §2 Decision;
- §3 Decisions by axis;
- Consequences;
- Alternatives (as a table).
Retro ADRs can drop Migration.
A. Shell and library contract
C01 Library public API and compatibility policy (Open, P1)
- Today.
lib/soliplex_frontend.dartexports a curated surface:AppModule,ModuleRoutes,Flavor,ShellConfig,buildRouter,standard,standardFlavor,ServerManager,AuthState, and ashow-listed subset of go_router, design and logging.- Two tests guard it:
test/barrel_module_authoring_test.dartandtest/barrel_reexport_test.dart. - All packages are
publish_to: none. The app is0.107.0+93, andsoliplex_clientis1.0.0-dev. soliplex_agentre-exports most ofsoliplex_client, and the client re-exportsag_ui(pre-1.0) wholesale. Forks therefore inherit a third-party wire type as public API.- Why. Forks build on this surface (CLAUDE.md: "runnable app and importable library"). There is no statement of what is stable, how breaking changes are versioned, or whether forks may import the packages directly. The CHANGELOG already carries "Library consumers (breaking)" bullets for agent types the barrel does not export.
- Decide.
- Is the barrel the only stable surface?
- Is the library version separate from the app's build number?
- Should the internal DI providers that leak out today
(
serverManagerProvider,inactivityLogoutFlagsProvider) be exported? - Should
ag_uisit behind an anti-corruption layer? - Which packages do forks consume?
C02 Module composition contract (Retro, P1)
- Today.
ShellConfig.fromModules(lib/src/core/shell_config.dart) validates namespaces, routes and public paths. It builds modules in registration order and disposes them in reverse. On abort it tears down every module.ShellConfig.redirectadmits declared public paths first. Module redirects then run in order, and the first non-null result wins.publicPathsmust belong to the declaring module's own routes (router.dart,validateModulePublicPaths).- The embedder owns
dispose. - Why. This is the extension contract for every fork module. Two things
are security-relevant behaviour: the redirect order, which is implied by
the order modules are registered, and the rule that public paths belong to
their module. A hand-built router silently drops an in-flight sign-in
(comment in
auth_module.dart). Origin:da882974, ADR-003.
C03 Module layering and inter-module contracts (Open, P1)
- Today.
core/imports auth, lobby and room storage (removed_server_cleanup.dart,inactivity/*).lobbyandroomimport each other.lib/src/interfaces/holds only the sealedAuthState. Everything else crosses modules by concrete import or constructor injection.- Why. CLAUDE.md says modules are "included/excluded by presence".
Today a fork cannot drop
lobbyorroom. Root cause:d6085becmoved cleanup into core. - Decide.
- The layering rule.
- Whether
interfaces/becomes the real contract layer. - How per-server cleanup is registered.
- How the rule is enforced in CI.
- Tracked in #607;
related to #23 (split
ServerManager).
C04 Server identity, alias and URL scheme (Open, P1)
- Today.
serverIdFromUrl(url) => url.origin(lib/src/modules/auth/server_entry.dart:10) is the storage and session key.aliasFromUrlreplaces dots in the host with dashes, appends-port, and adds-2,-3and so on when an alias collides. It is persisted and used in paths (/room/:serverAlias/:roomId/...).- Lobby uses
?server=<serverId>, so one server has two identifiers. - Why.
- Web URLs and bookmarks are user-facing.
- The alias is lossy:
httpandhttpson one host collide, and collision suffixes depend on the order servers were added. A shared link can therefore open a different server on another device. - Same-origin backends on different paths cannot coexist.
- The direction toward shared databases builds on this model.
- Decide.
- A stable identifier in the path, versus the alias.
- Whether one origin can hold several servers or accounts.
- What happens to bookmarks when a server is renamed.
C18 Device-local persistence scheme (Retro, P2)
- Today.
core/keyed_storage.dartbuilds percent-encoded composite keys withserverIdfirst, and uses anunauthenticatedbucket.core/storage_migration.dartkeeps a single monotonic schema version (1) and runs best-effort.- Tokens are in
flutter_secure_storage; everything else is inSharedPreferences. - Read markers are swept by key prefix.
- Why. The keys are on-disk user data, so changing them needs a migration. Every new store must follow the convention and register for cleanup on server removal. Today that registration is a hard-coded list in core (C03).
C19 Platform split conventions (Retro, P2)
- Today. Three mechanisms coexist:
- conditional imports, mostly on
dart.library.js_interop, with a few ondart.library.io; kIsWebbranches;- the injected
PlatformConstraints. - Why. Contributors need a rule for which mechanism to use. Some failures
only show at runtime on web:
Isolate.runcompiles but throws, andPlatform.*throws.
B. Identity, auth and security
C05 Web sign-in via backend BFF and token custody on web (Open, P1)
- Today. Web signs in through the backend (
/api/login/{provider}, a full-page redirect); native usesflutter_appauth. Sessions persist throughSecureServerStorageon every platform. - Why. It binds the backend to the login contract, and the web and native flows rest on two different trust models.
- Decide. The token-custody posture on web. Security specifics are tracked privately until fixed; ask the maintainers.
C06 Sign-out and IdP session end (Retro + Open, P1)
- Today.
- Signing out of or removing any server with a session triggers
RP-initiated logout at the IdP (
server_logout.dart;ed513e41,50112f68). - Native.
end_sessionruns first, and local state is cleared only if it succeeds. A user therefore cannot remove a server while the IdP is unreachable. - Web. Local state is cleared first, then the app navigates to the IdP, which may be abandoned.
- Why. The asymmetry is deliberate but easy to re-litigate. The
server_logout.dartdocstring proposes a BFF logout endpoint, which would be a backend commitment.
C07 User identity and in-memory isolation (Open, P1)
- Today.
AuthSession.currentUserIdderives the user from the access token;room/user_switch_teardown.dartevicts in-memory stores when it changes, and persisted state is partitioned by identity. - Why. The identity source is an assumption IdP operators are not told about, the partition scheme is baked into storage keys, and every new cache must opt in to eviction by hand.
- Decide. The identity source, and an enforced registry of caches that must be evicted. Security specifics are tracked privately until fixed; ask the maintainers.
C08 Rendering untrusted model output (Open, P1)
- Today. Model output renders as markdown with images, SVG code blocks,
LaTeX and tappable links (
room/ui/markdown/,shared/markdown/). - Why. Model output is attacker-influenced (prompt injection through documents), and forks inherit whatever policy the renderer has.
- Decide. A rendering policy for images, links and embedded formats, and whether a flavor can tighten it. Security specifics are tracked privately until fixed; ask the maintainers.
C09 Logging privacy and diagnostics exposure (Amend + Open, P1)
- Today. The
CLAUDE.mdrule "never log a user/backend-supplied value; usedescribeFailure" is enforced by review only.HttpRedactorredacts captured HTTP traffic by name.soliplex_logging'sLogManagerreplaceddart:developer(9d66cea7,660a29e6). - Why. A security boundary held up by convention; it binds every
contributor and fork.
docs/diagnostics-known-risks.mdlists the open questions. - Decide. Redaction of log records, a lint or CI check, and the
diagnostics screen's exposure. Promote the
CLAUDE.mdsection and the risk register into one ADR.
C20 OIDC deployment requirements (Retro, P2)
- Today.
- Every discovery endpoint must share the discovery URL's origin
(
soliplex_client/lib/src/auth/oidc_discovery.dart), or sign-in fails. - Native needs a public client and the
ai.soliplex.client://callbackredirect. - Sign-out needs
end_session_endpointand post-logout redirect URIs. - Why. These are requirements for IdP operators (split-host Keycloak and custom domains fail) that are currently discoverable only by failing. Write an operator-facing section alongside the ADR.
C22 Inactivity logout policy (Open, P3)
- Today.
- A warning after 10 minutes idle, then a local logout after a 5-minute
grace period (
core/inactivity/). - Configurable per flavor at compile time; it can be disabled.
- Decide.
- Whether the logout should also end the IdP session.
- Whether the policy should come from the backend.
- Whether a sleeping tab counts as idle (#409).
C. Backend contract and runs
C10 Backend compatibility contract (Open, P1)
- Today.
ragStateKey = 'rag'andragSourcesKey = 'sources'(soliplex_client/lib/src/application/rag_snapshot.dart) must match haiku.rag'sSTATE_NAMESPACE.- One schema snapshot (
haiku-rag-0.89.0.json) and a drift test guard the mirror. - Support for haiku.rag 0.40 was dropped in favour of a single version
(
73d44744, #414). - Code that no supported backend reaches is pruned (
fd4328b6,c9f8165e). - Capability is detected by skill, not by config flag (#452 and #455).
Activities are rendered from the AG-UI envelope, not from backend
schemas (
b39e190a). getBackendVersionInfoexists but gates no behaviour (not exhaustively checked).- Why. This is the tightest coupling to another team. A key rename silently breaks citations and filters. There is no stated window of supported backend versions and no feature-detection rule.
- Decide.
- The supported range: N backend versions, a minimum version, and how the app behaves outside it.
- Detection by skill versus by version.
- Who owns the snapshot refresh.
- Whether the backend should publish a versioned state schema.
C11 Run lifecycle and failure reporting (Amend + Open, P1)
- Today.
docs/send-cancel-lifecycle.mdstates the rule: only the cancel button cancels, and navigation only stops observing.RunRegistrykeeps runs alive across navigation. For a failed run that has arunId,run_registry.dartposts an automaticthumbsDownfeedback. The comment explains that the backend keeps no queryable run status. - Why. The lifecycle doc is the strongest de-facto ADR in the repo. Auto-feedback uses the user-feedback table as a failure log, which skews feedback analytics and is a workaround for a missing backend API.
- Decide. Whether to keep auto-feedback or ask the backend for a run-status or telemetry endpoint. Then promote the lifecycle doc to an ADR.
C12 Timeline, runs and bands model (Retro, P1)
- Today.
layOutTimelineis a single pure function. Its invariant is that every ended run has a hosting tile and every band attaches exactly once.- The parked outcome is the only record of how a run ended.
- Runs, bands and the registry form the central concept (#566, #578;
cc1fb454,7e84ce07). - Why. This is the most-churned area:
room_screen.darthas 206 touches,thread_view_state.dart73 andrun_orchestrator.dart63. It has been rewritten several times:NoResponseTilewas added and later deleted, and the band vocabulary was renamed. Pin the reasoning before #601 splits_RoomScreenState.
C13 Signals convention and the 7.x migration (Open, P1)
- Today.
- CLAUDE.md mandates
signal.watch(context)andWatch(...), and says Riverpod is DI only. A grep found noFutureProvider,AsyncNotifierorStateNotifier. - signals 7.x deprecates both mandated APIs. Adopting it fails the zero-warning gate (#314, about 30 sites).
- Open issues #52 and #54 argue for replacing one-shot or error signals
with returned values or
FutureBuilder. - Why. The mandated convention is deprecated upstream, so a decision is forced.
- Decide.
- The new subscription idiom.
- When to use a signal and when to use a
Future. - Whether to amend ADR-001 or write a new ADR.
C14 HTTP client stack and token refresh (Retro, P2)
- Today.
- The chain, outermost first: Concurrency (max 6), Refreshing,
Authenticated, Observable, Platform. Built by
createAgentHttpClient. - Refresh uses a separate unauthenticated
plainClient: the probe and refresh clients were split and then reverted to one (6078f08b). invalid_grantputs the session inExpiredSession, which a later refresh can revive. Network errors and unexpected errors do not expire the session.- Platform clients:
cupertino_httpon Apple, XHR on web,dart:ioelsewhere. - Why. The order matters:
- the redactor sees the injected headers;
- retries re-run token injection;
- the expire-or-retry choice decides whether a user gets locked out.
C15 Stream resume, history replay and failures-as-data (Retro, P2)
- Today.
- Resume. On a dropped stream,
Last-Event-IDresume is tried up to 5 times with 500 ms to 8 s backoff and ±20% jitter (soliplex_client/lib/src/http/resume_policy.dart). - History. It is rebuilt by replaying stored run events through the
same reducer as the live stream (
SoliplexApi._replayEventsToHistory). - Bad events. An undecodable event becomes a
DroppedEventMessagetile. A per-tile try/catch was tried and reverted (0fabfb60). Citations fail soft, raisingThreadStateWarnings. - Why. This assumes the backend keeps a resumable event log and per-run event retrieval. Keeping replay identical to live behaviour is subtle. "A failure is data, not an exception" is a principle worth stating once.
C16 Error taxonomy as a UI contract (Retro, P2)
- Today.
- The
SoliplexExceptionfamily is: Auth, PermissionDenied, Network, Api, NotFound, Cancelled, MalformedResponse, Unexpected. HttpTransportmaps 401 to Auth, 403 to PermissionDenied, 404 to NotFound, and everything else to Api.- 429 and 5xx have no dedicated types, but
FailureReasonhasrateLimited(mapping not traced). - Why. The UI and forks branch on these types, so adding or splitting one is a breaking change (C01).
C17 Client-side tools, approval and host APIs (Open, P2)
- Today.
- A flavor supplies
ToolRegistryper room. The standard flavor's is empty. - Approval is a
SessionExtensionand denies by default when none is registered. HumanApprovalExtensionauto-denies on cancel.- The host APIs (
AgentApi,HostApi,BlackboardApi,FormApi) and the interpreter-shapedPlatformConstraintsflags have no consumer in the standard flavor. - Why. This decides who may run code on a user's device on the model's say-so. If the host APIs are aspirational, they are public surface with no owner.
- Decide.
- The intent of this surface: keep, document, or delete.
- Which tools must require approval.
C21 Multi-database thread semantics (Retro, P2)
- Today.
- A thread's database set is frozen by its first message, so that "evidence stays comparable" (#563).
- The
sourceswire shape and MISSING marker follow backend issue #1322. - Why. It is a cross-repo contract and a product rule. Both are recorded only in commits and personal notes.
D. Conventions and product constraints
C23 Time handling (Retro, P3)
createdAt is nullable. No client clock is used on the display path, and
UTC is stamped at the marker-store boundary (94061061, a7a05fa7,
3c46382c).
C24 Product constraints that bind engineering (Retro, P3)
Some product calls currently live only in commit bodies:
- "No new snackbars" (
84b62fc4; the commit citesdocs/plans/home-server-list/known-issues.md, which is not onmain). - Classification markings are theme-only, with no wire field and no per-room value (#319–#322).
Record them in one place so they stop being rediscovered.
C25 Design package boundary and token governance (Amend ADR-002, P3)
soliplex_designwas extracted as a package (b127f3bc, #274), and its boundary keeps renderer dependencies out of it.- Adding a token requires approval and changes to
design_system/in the same commit. - The CLAUDE.md hard rules are enforced only by a hygiene test and a review checklist.
C26 Boot validation and theme requirements (Amend ADR-003, P3)
ShellConfigurationErrorreaches the screen verbatim.- Any theme, including the full-token-control tier, must carry the
SoliplexThemeextension or it is rejected at boot.
Suggested first batch
Start with the items that are cheap or that block other work:
- Housekeeping (above). This is a single small PR.
- Decision meetings for the Open P1s that bind other parties:
- C05, C07 and C08 (security posture);
- C10 and C11 (with the backend team);
- C01 (with fork consumers);
- C13 (forced by #314).
- Retro ADRs that de-risk the next refactors:
- C02 and C03, before #607;
- C12, before #601.
- P2 retro ADRs. These can be written by one person per area from the evidence cited here.