Skip to content

README.md

Latest commit

 

History

History
167 lines (149 loc) · 23.8 KB

README.md

File metadata and controls

167 lines (149 loc) · 23.8 KB
Raw

Architecture Decision Records

Every non-trivial architectural, product, or process decision in Relavium is recorded here as an ADR (Architecture Decision Record) using a lightweight MADR (Markdown Architectural Decision Records) style.

Why ADRs

  • They preserve the why, not just the what. The reasoning behind a choice is the information that decays fastest and is most expensive to re-derive later.
  • They make the evolution of the project readable: you can follow the numbered history and see how the design language developed, including the options that were rejected.
  • They give future contributors (human or AI) a way to disagree with a decision by writing a new ADR that supersedes an old one, rather than silently changing code or docs.

Concrete specifications (workflow/agent YAML, the SSE event schema, the IPC contract, store shapes, DB DDL) live in their canonical reference/ files. ADRs cite those by relative link and never restate them; they capture the decision and its drivers, not the spec.

Format

Every ADR is a single file named NNNN-short-kebab-slug.md, where NNNN is a zero-padded four-digit sequence number. Each one opens with an H1 title and bold metadata lines, then three sections:

  • Context — the situation, the problem, the constraints that applied.
  • Decision — the option chosen, the alternatives considered, and the drivers that connected them.
  • Consequences — split into Positive and Negative effects, with mitigations where relevant.

Pinned tool and library versions are not restated in ADRs; they live in tech-stack.md and are referenced from there.

Two ADR spaces

Relavium will ship as more than one git repository. To avoid renumbering pain across repos, there are two independent ADR number spaces — one for this meta repo, one reserved for the Phase-2 cloud repo.

Space Location Scope Numbering
Product / cross-cutting ADR this repo docs/decisions/ (this folder) Decisions that touch more than one surface (desktop, CLI, VS Code, portal), the shared engine, or product scope / phasing Independent ADR-0001..
Cloud backend ADR (Phase 2) reserved relavium-cloud/docs/decisions/ Decisions internal to the Phase-2 cloud execution backend only (worker orchestration, queue tuning, secrets injection, VPC peering) Independent ADR-0001..

The two spaces are deliberately separate; a collision (e.g. two ADR-0005s) is expected and is not a problem — the files live in different repos. Renumbering would touch every cross-reference (high risk, no value), so it is never done. Citation convention: "Product ADR-00NN" (this folder) vs "Cloud ADR-00NN" (relavium-cloud/docs/decisions/).

The cloud repo and its ADR space do not exist yet — they are a Phase-2 carry-forward. See ADR-0008 for the phasing decision that creates this split, and the (Phase 2) cloud architecture doc.

flowchart TD
    Q{What does the decision affect?}
    Q -->|More than one surface, the shared<br/>engine, or product scope / phasing| META[Product ADR<br/>this folder]
    Q -->|Phase-2 cloud backend internals only| CLOUD[Cloud ADR<br/>relavium-cloud/docs/decisions/<br/>reserved, does not exist yet]
Loading

Index

# Title Status Date
0001 Tauri v2 over Electron for the desktop app Accepted 2026-06-03
0002 Vite + React 19 + TanStack Router, not Next.js Accepted 2026-06-03
0003 Pure TypeScript workflow engine, not LangGraph-Python Accepted 2026-06-03
0004 Vercel AI SDK for multi-LLM Superseded by 0011 2026-06-03
0005 SQLite + Drizzle local, PostgreSQL cloud Accepted 2026-06-03
0006 OS keychain for API keys Accepted 2026-06-03
0007 The desktop app is not an IDE Accepted 2026-06-03
0008 Local-first Phase 1, cloud Phase 2 Accepted 2026-06-03
0009 Git-native workflow and agent YAML Accepted 2026-06-03
0010 Zustand direct subscriptions for ReactFlow Accepted 2026-06-03
0011 Internal multi-LLM abstraction (@relavium/llm) Accepted 2026-06-03
0012 Dual-mode inference — managed inference as an opt-in third execution mode Accepted 2026-06-03
0013 Managed-mode provider-key vault and key pools Accepted 2026-06-03
0014 Managed-mode metering, quota, and billing Accepted 2026-06-03
0015 Managed-mode data handling and compliance posture Accepted 2026-06-03
0016 Hono as the apps/api framework Accepted 2026-06-04
0017 Bun as the apps/api runtime Accepted 2026-06-04
0018 Desktop execution model — engine in WebView, Rust-delegated LLM egress Accepted 2026-06-04
0019 Node-side OS-keychain access for the CLI — a maintained library, not the archived keytar Accepted 2026-06-04
0020 Zod as the runtime schema and validation library Accepted 2026-06-04
0021 better-sqlite3 as the Node-side SQLite driver for @relavium/db Superseded by 0067 2026-06-04
0022 Run records reference the workflow by surrogate UUID, not the authored slug Accepted 2026-06-04
0023 Authored workflow/agent YAML is strictly validated — unknown keys rejected Accepted 2026-06-04
0024 Agent-first entry point — AgentSession alongside WorkflowEngine Accepted 2026-06-05
0025 The conversational agent surface — a refinement of ADR-0007's desktop scope Accepted 2026-06-05
0026 Session export to workflow YAML — the chat-to-workflow continuum Accepted 2026-06-05
0027 Expression sandbox for condition / transform / merge_fn Accepted 2026-06-05
0028 Workflow resource governance — pre-egress budget, run timeout, concurrency cap Accepted 2026-06-05
0029 Tool-policy hardening — command match, tool narrowing, secret interpolation, SSRF Accepted 2026-06-05
0030 @relavium/llm seam-shape amendment — reasoning channel, responseFormat, providerExecuted Accepted 2026-06-07
0031 @relavium/llm seam-shape amendment — first-class multimodal I/O Accepted 2026-06-08
0032 Desktop Rust-side media de-inlining on the egress path (amends 0018) Accepted 2026-06-08
0033 Local config files are strictly validated too (amends 0023) Accepted 2026-06-09
0034 MCP client implementation — the official TypeScript SDK, scheduled in build phase 2 Accepted 2026-06-10
0035 YAML parser for the engine — the yaml package, confined to @relavium/core Accepted 2026-06-11
0036 Run-loop substrate — in-house RunEventBus, the ExecutionHost seam, and the exactly-one-terminal-event invariant Accepted 2026-06-13
0037 Engine-side tool-execution boundary — the ToolHost capability seam, policy/mechanism split, bounded results Accepted 2026-06-13
0038 AgentRunner LLM-call boundary — host-injected provider resolution, the per-node-execution FallbackChain, and the credential discipline Accepted 2026-06-14
0039 Same-provider signed-reasoning replay — a behavioral amendment to ADR-0030 Accepted 2026-06-14
0040 Node-level retry budget above the provider fallback chain (1.S) — amends ADR-0038 Accepted 2026-06-15
0041 External action-governance seam — the optional, host-injected ActionGuard over side-effecting tool actions Accepted 2026-06-18
0042 Engine media storage substrate — the MediaStore host port, the deInlineMedia choke-point ordering, and the media_objects retention/GC store (amends 0036) Accepted 2026-06-18
0043 Media egress — the binary media-egress capability, the FallbackChain↔MediaStore re-materialization contract, and the SSRF mechanism half (amends 0031) Accepted 2026-06-18
0044 Media access & spend governance — read_media scope-set authz, the byte-delivery gate, the save_to write port, and the per-modality media cost (amends 0028 and 0029) Accepted 2026-06-18
0045 Engine-owned async media-job loop (1.AG/A5) — the generateMedia/pollMediaJob poll/checkpoint/resume/cancel LRO, the media_job:submitted derived state, inline-vs-generative routing, and media-cost realization (amends 0031, 0036, 0040) Accepted 2026-06-20
0046 Inline media-out routes through generate(); the streaming media triad is host-deferred (amends 0031, 0038) Accepted 2026-06-20
0047 CLI framework — commander + ink + @clack/prompts, confined to apps/cli Accepted (single-output constraint partially replaced by ADR-0111) 2026-06-22
0048 TOML parser for config files — smol-toml, confined to the apps/cli config loader Accepted 2026-06-22
0049 CLI machine-output contract (--json NDJSON stream + stderr diagnostics) Accepted (§5 infrastructure/storage and §6 explicit JSON help partially replaced by ADR-0110) 2026-06-22
0050 CLI run-history history.db is unencrypted at rest, guarded by OS file permissions (refines 0005/0008 for the Node/CLI surface) Accepted 2026-06-23
0051 CLI distribution — an engine-inlined ESM bundle that externalizes every third-party dependency (finalizes 0047's bundle boundary) Accepted (single-output constraint partially replaced by ADR-0111) 2026-06-24
0052 Inbound MCP client — the @relavium/mcp package boundary, host-injected connection lifecycle, host-side tool registration, a dependency-free schema→validator compiler, and the agent↔config reference linkage (implements 0034) Accepted 2026-06-26
0053 MCP network-transport (sse/websocket) egress security — SSRF enforcement on the one shared primitive, and the explicit per-server local-endpoint opt-in Accepted 2026-06-26
0054 Bare relavium invocation opens an interactive Home (TTY only), preserving the meta-op contract Accepted 2026-06-29
0055 Shared CLI tool-environment factory — ToolHost, ToolPolicy, and dispatch context as separate channels Accepted 2026-06-28
0056 In-app slash command system driven by a single command manifest Accepted 2026-06-29
0057 Reseat-less chat modes and per-tool approval (with mid-turn abort) Accepted 2026-06-28
0058 @relavium/authoring package and the conversational-authoring pre-flight contract Proposed 2026-06-28
0059 Mid-session model switching via host-side reseat (refines ADR-0024) Accepted 2026-07-06
0060 Session {{ctx.*}} prompt interpolation Proposed 2026-06-28
0061 CLI chat input-layer file-injection (@-mention) and shell-escape (!-shell) security model Accepted 2026-07-03
0062 Context compaction — append-only conversation summarization and the CLI history commands (/clear · /trim · /compact) Accepted 2026-07-04
0063 CLI config-write contract — the first on-disk config writer, the global [preferences].default_model target, and the resolveChat global fallback Accepted 2026-07-05
0064 Live model catalog — the listModels? seam capability, the kind protocol abstraction, the model_catalog live cache, the refresh lifecycle, and the static/live merge Accepted 2026-07-05
0065 Provider economics and extensibility — user-supplied pricing, the cost-path pricing-injection seam, pricing-reference capture, and custom OpenAI-compatible endpoints Accepted 2026-07-05
0066 Normalized reasoning-effort control — a provider-agnostic tier, per-adapter native mapping, and a per-model capability Accepted 2026-07-06
0067 Node supported-floor >=22 and re-affirmed better-sqlite3 (supersedes ADR-0021) Accepted 2026-07-09
0068 Full-screen TUI renderer, ink 7, and the CLI component test harness (refines ADR-0047) Accepted 2026-07-09
0069 string-width for the CLI renderer's display-width measurement Accepted 2026-07-10
0070 Durable per-model session cost attribution — the session_costs aggregate, single-owner cost writes, and the reconciliation invariant Accepted 2026-07-12
0071 models.dev as the model-metadata source; the hand-maintained registry is retired (supersedes two ADR-0064 clauses, corrects an ADR-0066 premise) Accepted 2026-07-13
0072 Model metadata in the DB behind the offline snapshot floor (partially supersedes ADR-0064 §4's seed-prohibition; amends ADR-0071 §3/§4/§9) Accepted 2026-07-14
0073 runMigrations is serialized across processes by an OS lock file, not by a transaction Accepted 2026-07-29
0074 Durable conservative budget commitments across run and session resume (amends ADR-0028, ADR-0036, ADR-0045, ADR-0070) Accepted 2026-07-30
0075 A resume fails closed on an unreadable event log (amends ADR-0074 §5) Accepted 2026-08-09
0076 A durable per-attempt realized-cost ledger (amends ADR-0070, extends ADR-0074) Accepted 2026-08-09
0077 The realized-cost ledger uses ADR-0074 §2's barrier mechanism (amends ADR-0076 §1) Accepted 2026-08-10
0078 The durable event log is an ordered append, and a terminal that cannot be made durable says so (amends ADR-0036 and ADR-0042 §4) Accepted 2026-08-11
0079 Cross-process run ownership — a durable run lease with a monotonic fencing token (amends ADR-0036) Accepted 2026-08-12
0080 A durable effect journal, and a tiered effect contract that says what it can keep (amends ADR-0027, ADR-0037, ADR-0040, ADR-0041) Accepted 2026-08-17
0081 The compaction summary is untrusted content, and the system prompt becomes a branded type (supersedes ADR-0062 §1) Accepted 2026-08-18
0082 The stream grammar is a seam obligation the chain verifies, and every chain attempt has a hard deadline Accepted 2026-08-18
0083 One input-admission gate in the engine, and a resume that verifies its own identity Accepted 2026-08-19
0084 Consent before a local MCP spawn Accepted 2026-08-20
0085 The node executor owes liveness, the engine enforces it, and a late dispatch is fenced Accepted 2026-08-25
0086 Authored values get absolute admission ceilings, and an omitted concurrency cap is finite Accepted 2026-08-28
0087 A stream is bounded by whether anyone reads it; outputs and events are bounded by size; finished runs are bounded by count Accepted 2026-09-04
0088 The MCP boundary is hostile — a remote server is pinned and bounded, an unbounded one must be local and opted into Accepted 2026-08-30
0089 Media correctness — the four boundaries W5 had to choose (amends 0031, 0039, 0042, 0043, 0044, 0070, 0071) Accepted (§3 superseded by 0090) 2026-09-02
0090 A continuation token rides the part it belongs to (supersedes 0089 §3; refines 0030, 0039, 0043) Accepted 2026-09-02
0091 merge_strategy: first means first DECLARED, not first to finish Accepted 2026-09-02
0092 output_schema is deep-validated by the JSON-Schema compiler we already own Accepted 2026-09-02
0093 An expression sees only what it is ordered after Accepted 2026-09-02
0094 A tool grant is checked when the plan is built Accepted 2026-09-02
0095 What an agent session remembers across turns Accepted 2026-09-14
0096 A request is measured before it is sent, and a context overflow is a classified failure Accepted 2026-09-14
0097 A budget approval is an allowance, not an exemption Accepted 2026-09-14
0098 A session's effect row holds no result, never replays, and discloses what did not complete Accepted 2026-09-14
0099 Compaction has an idle budget outcome and an unknown-window policy Accepted 2026-10-02
0100 Budget authorization is durable state with a replay barrier Accepted 2026-10-02
0101 Configured output estimates apply only when the wire is uncapped Accepted 2026-10-02
0102 A measured request owns its inert data through egress Accepted 2026-10-04
0103 A paused run hands off its local producers before its host closes Accepted 2026-10-07
0104 Unknown provider usage is durable cost uncertainty Accepted 2026-10-10
0105 Filesystem roots are invocation grants, not project authority Accepted 2026-10-12
0106 Media publication requires bounded verified bytes Accepted 2026-10-12
0107 First-run secret inputs use bounded stdin Accepted 2026-10-12
0108 Provider headers stay gated until keychain custody Accepted 2026-10-12
0109 Native media close ownership is explicit iterator provenance Accepted 2026-10-13
0110 CLI diagnostics and discovery have explicit compatibility Accepted 2026-10-15
0111 CLI meta-operations use a lazy packaged runtime Accepted 2026-10-15
0112 Chat network grants and onboarding state are operator-owned Accepted 2026-10-15
0113 Secret-derived context keeps provenance at public sinks Accepted 2026-10-15

Creating a new ADR

  1. Copy the structure of an existing ADR to the next available number: NNNN-your-slug.md.
  2. Fill in the H1, bold Status / Date / Related lines, then ## Context, ## Decision, ## Consequences (### Positive / ### Negative with mitigations / optionally ### Neutral for scope notes, non-reversals, and forward pointers).
  3. Start at status Accepted once the decision is settled; cross-link sibling ADRs and reference tech-stack.md for versions.
  4. If a later ADR overrides this one, mark the old one Superseded by NNNN and link forward. Do not delete or rewrite the old ADR — the historical reasoning is the point.
  5. To refine, clarify, or reconcile an Accepted ADR without reversing it (e.g. a later ADR refines its mechanism), amend it in place with a dated > Amended YYYY-MM-DD: … note that points to the driving ADR — never a silent rewrite. Reversing a decision is a supersession (step 4), not an amendment. The rule is in documentation-style.md §7.