Architecture Decision Records (ADRs)

August 2, 2026 · View on GitHub

This directory contains Architecture Decision Records (ADRs) for Beamtalk.

ADRs document significant architectural and design decisions, including:

  • Language design choices
  • Implementation strategies
  • Trade-offs and their rationale

Format

Each ADR follows the structure in TEMPLATE.md. Key sections:

  • Status: Proposed, Accepted, Implemented, Deferred, Deprecated, Superseded, Rejected
  • Context: Background, problem statement, constraints
  • Decision: What was decided, with code and REPL examples
  • Prior Art: How reference languages handle this
  • User Impact: How this affects each user persona
  • Steelman Analysis: Best argument for rejected alternatives from each user cohort
  • Alternatives Considered: What else was evaluated and why it was rejected
  • Consequences: Positive, negative, and neutral impacts
  • Implementation: Affected components and rough phases
  • Migration Path: How to migrate existing code (if applicable)
  • References: Related issues, ADRs, documentation

ADR List

NumberTitleStatusDate
0001No Compound Assignment in BeamtalkImplemented2026-02-08
0002Use Erlang Comparison Operators DirectlyImplemented2026-02-08
0003Keep Core Erlang as Primary Code Generation TargetImplemented2026-02-08
0004Persistent Workspace ManagementImplemented2026-02-15
0005BEAM Object Model - Pragmatic Hybrid ApproachImplemented2026-02-08
0006Unified Method Dispatch with Hierarchy WalkingImplemented2026-02-08
0007Compilable Standard Library with Primitive InjectionImplemented2026-02-07
0008Doc Comments and API DocumentationImplemented2026-02-15
0009OTP Application Structure — Split Workspace from RuntimeImplemented2026-02-07
0010Global Objects and Singleton DispatchImplemented2026-02-15
0011Robustness Testing — Layered Fuzzing and Error QualityImplemented2026-02-15
0012Collection Literal Syntax and the # Data Literal SystemImplemented2026-02-15
0013Class Variables, Class-Side Methods, and Instantiation ProtocolImplemented2026-02-15
0014Beamtalk Test Framework — Native Unit Tests and CLI Integration TestsImplemented2026-02-15
0015Signal-Time Exception Objects and Error Class HierarchyImplemented2026-02-15
0016Unified Stdlib Packaging and Module NamingImplemented2026-02-10
0017Browser Connectivity to Running WorkspacesImplemented (Phases 0–2)2026-02-17
0018Document Tree Code Generation (Wadler-Lindig Pretty Printer)Implemented2026-02-15
0019Singleton Access via Class VariablesImplemented2026-02-15
0020Connection Security — mTLS, Proxies, and Network OverlaysImplemented2026-02-17
0021Stream — Lazy Pipeline for Value-Side DataImplemented (Revised)2026-02-15
0022Embedded Compiler via OTP Port (with NIF option)Implemented2026-02-15
0023String Interpolation Syntax and CompilationImplemented2026-02-17
0024Static-First, Live-Augmented IDE ToolingImplemented (Phase 1)2026-02-17
0025Gradual Typing and ProtocolsImplemented (Phases 1–2)2026-02-15
0026Package Definition and Project ManifestImplemented2026-02-17
0027Cross-Platform SupportImplemented2026-02-17
0028BEAM Interop StrategyImplemented2026-02-17
0029Streaming Eval OutputImplemented2026-02-18
0030cargo-dist Evaluation for Release PackagingRejected2026-02-18
0031Flat Namespace for v0.1Superseded by 00702026-02-18
0032Early Class Protocol — Behaviour and Class in Beamtalk StdlibImplemented2026-02-24
0033Runtime-Embedded Documentation on Class and CompiledMethodImplemented2026-02-24
0034Stdlib Self-Hosting — Moving Logic from Erlang to BeamtalkImplemented2026-02-24
0035Rename Instance Variable Reflection API from instVar to fieldImplemented2026-02-24
0036Full Metaclass TowerImplemented2026-02-24
0037Collection Class Hierarchy — Shallow Abstract Layer with Minimal Primitive SurfaceImplemented2026-02-24
0038subclass: Grammar Desugaring to ClassBuilder ProtocolImplemented2026-02-24
0039Syntax Pragmatism vs SmalltalkImplemented2026-02-24
0040Workspace-Native REPL Commands, Facade/Dictionary Split, and Class-Based ReloadImplemented2026-02-24
0041Universal State-Threading Block ProtocolImplemented2026-02-24
0042Immutable Value Objects and Actor-Only Mutable StateImplemented2026-02-26
0043Sync-by-Default Actor MessagingImplemented2026-02-26
0044Comments as First-Class AST NodesImplemented2026-02-28
0045REPL Expression-Level Completion via Gradual Type InferenceImplemented2026-03-01
0046VSCode Live Workspace SidebarImplemented2026-03-02
0047Return Type Arrow Token DisambiguationImplemented2026-03-02
0048Class-Side Method Syntax RedesignDeferred2026-03-02
0049Remove Method-Level sealed — Infer Protection from @primitive/@intrinsicDeferred2026-03-02
0050Incremental Compiler ClassHierarchy via BEAM Metadata StreamingImplemented2026-03-04
0051Subprocess Execution — System Commands and Interactive Subprocess ActorAccepted | Implemented2026-03-05
0052Recursive Descent Parser with Pratt Parsing for Binary OperatorsAccepted | Implemented2026-03-05
0053Double-Colon Type Annotation SyntaxImplemented2026-03-05
0054Communication ProtocolsAccepted | Implemented2026-03-05
0055Erlang-Backed Class Authoring ProtocolImplemented2026-03-06
0056@native — Erlang-Backed ActorsAccepted (partial)2026-03-07
0057Authoritative Superclass Source for Abstract Stdlib ClassesImplemented2026-03-07
0058Platform Security ModelAccepted (policy)2026-03-07
0059Supervision Tree SyntaxImplemented2026-03-07
0060Result Type — Hybrid Error Handling for Expected FailuresImplemented2026-03-08
0061Program Entry Points and Run LifecycleImplemented2026-03-10
0062Bundled Example Corpus and Search Tool for MCP ServerImplemented2026-03-15
0063Remove File Path SandboxImplemented2026-03-16
0064Runtime Logging Control and Observability APIImplemented2026-03-17
0065Complete OTP Primitives for Actor Lifecycle and SupervisionImplemented2026-03-17
0066Open Class Extension Methods (>> Syntax)Implemented2026-03-18
0067Separate state:/field: Keywords by Class KindImplemented2026-03-18
0068Parametric Types and ProtocolsAccepted | Implemented2026-03-20
0069Actor Observability and TracingAccepted | Implemented2026-03-21
0070Package Namespaces and DependenciesImplemented2026-03-24
0071Class Visibility — internal Modifier for Package-Scoped Access ControlImplemented2026-03-28
0072User Erlang Sources in Beamtalk PackagesImplemented2026-03-29
0073Package Distribution and DiscoveryImplemented (Phase 1; Phase 2 implemented in simplified form, amended 2026-07-26)2026-03-31
0074Deferred MetaprogrammingAccepted (deferral)2026-04-01
0075Erlang FFI Type DefinitionsImplemented (Phase 1; Phase 2 deferred)2026-04-02
0076Convert Erlang ok/error Tuples to Result at FFI BoundaryImplemented2026-04-03
0077Type Coverage VisibilityImplemented2026-04-05
0078Actor Initialize InheritanceImplemented2026-04-12
0079Named Actor RegistrationImplemented2026-04-15
0080Migrate Supervisor Lifecycle to ResultImplemented2026-04-16
0081First-Class Session Object — Walkable Binding LayersProposed2026-05-09
0082Method-Level Edit and Save in the Live WorkspaceImplemented2026-05-17
0083Metaclass-Aware Type InferenceImplemented2026-05-23
0084Class-Side Runtime Method Installation and Fun DispatchAccepted (in progress)2026-05-24
0085Editor Live-Image RepresentationProposed2026-05-24
0086Make String a Subclass of BinaryImplemented2026-03-21
0087Maintained Selector→Sites Cross-Reference Index for SystemNavigationAccepted2026-05-26
0088Direct Core Erlang AST Emission via ETFPhases 1–4 Rejected; Wire Deferred2026-05-26
0089Typed Document Leaves for Core Erlang CodegenAccepted2026-05-28
0090Canonical Array Representation for O(log n) at:put:Accepted2026-06-02
0091Connection Security for Remote Workspace Access — Phoenix as Authenticated FrontAccepted2026-06-06
0092Supervision Tree Introspection API (Runtime Query Surface)Implemented2026-06-07
0093Announcements — Typed Event Substrate (Runtime Bus + stdlib Veneer)Accepted2026-06-07
0094Object String Representation Protocols (printString / displayString / inspect)Proposed2026-06-07
0095Rich Navigable Inspector — Drillable, Live-Refreshing Object ViewsAccepted2026-06-11
0096System Browser Data Source — Class/Method Browse API for the LiveView IDEProposed2026-06-10
0097Desktop Attach Client — One Front Node per WorkspaceProposed2026-06-13
0098Build Artifact Provenance and Version-Based Staleness InvalidationAccepted2026-06-23
0099CLI Application Story — Console, Arguments, Exit, and PackagingAccepted2026-06-26
0100Open-World Diagnostic Policy for Unresolved Selectors and ClassesProposed2026-06-27
0101Unified Erlang Interop — native: for Stateless Objects, Wrap-by-Default FFI, Clean @primitive/@intrinsic/native: SplitAccepted2026-06-28
0102Set-Theoretic Type Operators (Intersection and Negation) for Narrowing and Atom ExhaustivenessImplemented (Phases 1, 2, 4, 5; Phase 1b deferred)2026-07-06
0103Sendability Typing from Class KindsProposed2026-07-05
0104Typed Actor Protocols — the Class Interface Is the ProtocolAccepted2026-07-07
0105Live Image Re-Checking on Hot ReloadAccepted2026-07-11
0106Opt-In Asserted match: Exhaustiveness (matchExhaustive:)Implemented2026-07-07
0107Nil and Type Patterns in match:Accepted2026-07-12
0108Named Union Type Aliases (type Declarations)Accepted2026-07-15
0109Block-Scoped Class Methods Run Their Block in the Caller's ProcessAccepted2026-07-28
0110Class-Variable Shadow Write-Through for Foreign NLR RelayAccepted2026-08-02

ADR 0086 was originally numbered 0069 (a collision with Actor Observability and Tracing) and was renumbered on 2026-05-25.

Creating New ADRs

  1. Number sequentially: Use the next available number (0003, 0004, etc.)
  2. Use descriptive titles: Make it clear what decision is being made
  3. Document thoroughly: Include context, rationale, and consequences
  4. Link to issues: Reference Linear issues (e.g., BT-XXX) where relevant
  5. Update this index: Add your ADR to the table above

References