Beamtalk Language Features

Language features for Beamtalk. See Design Principles for design philosophy and Syntax Rationale for syntax design decisions.

Status: v0.4.0 — implemented features are stable, including generics, protocols, union types, control flow narrowing, the typed class modifier, FFI type inference, package management with qualified pkg@Class names, native Erlang sources in packages, named actor registration, and Result-shaped supervisor lifecycles. See ADR 0068 for the type system design.

Syntax note: Beamtalk uses a modernised Smalltalk syntax: // comments (not "..."), standard math precedence (not left-to-right), and optional statement terminators (newlines work).

Table of Contents

• String Encoding and UTF-8
• Core Syntax
  • Class-Side Methods (ADR 0048)
  • Doc Comments (///)
  • Erlang FFI
  • Loading Code into the Workspace
• Gradual Typing (ADR 0025)
• Parametric Types — Generics (ADR 0068)
• Structural Protocols (ADR 0068)
  • Printable Protocol and Display Methods
• Traits (ADR 0127)
  • Which mechanism to use
  • Reflection
• Union Types and Narrowing (ADR 0068)
  • Named Type Aliases (type Declarations) (ADR 0108)
• Actor Message Passing
• Server — OTP Interop (ADR 0065)
• Supervision Trees (ADR 0059)
• Named Actor Registration (ADR 0079)
• Pattern Matching
• Live Patching
  • Keyword Method Patching — compile:source: and tryCompile:source: (ADR 0082)
  • Removing methods — removeSelector: and removeSelector:ifAbsent: (ADR 0112)
  • ChangeLog — Tracking In-Memory Changes (ADR 0082)
  • Live Re-Checking on Reload (ADR 0105)
• Actor Observability and Tracing (ADR 0069)
• Announcements — Typed Events (ADR 0093)
• Distribution — Location-Transparent Actors (ADR 0126)
• Namespace and Class Visibility
  • Visibility and Access Control (ADR 0071)
• Smalltalk + BEAM Mapping
• Tooling
• Inspiration Sources
• References

String Encoding and UTF-8

Beamtalk strings are UTF-8 by default. This follows modern BEAM conventions and matches Elixir's approach. String is a subclass of Binary (Collection > Binary > String) — see Binary — Byte-Level Data for byte-level operations inherited by String.

String Types

// Double-quoted strings - UTF-8 binaries
name := "Alice"
greeting := "Hello, 世界! 🌍"

// String interpolation (ADR 0023)
message := "Welcome, {name}!"
emoji := "Status: {status} ✓"

// Escape sequences inside strings:
//   ""   doubled delimiter → literal double-quote character
//   \{   backslash preserved → literal \{  (prevents interpolation)
//   \}   backslash preserved → literal \}
quote := """"                    // 1-char string containing "
dialog := "She said ""hello"""  // → She said "hello"
// Note: \{ and \} keep the backslash in the string value (current lexer behavior)

// All strings are <<"UTF-8 binary">> in Erlang

Character Encoding

Character Methods

Character-typed receivers dispatch through the Character method table, so methods like asString, printString, uppercase, lowercase, and class return Character-appropriate values. This applies to character literals ($A), the Character value: class factory, and chained uppercase/lowercase sends — all statically Character-typed forms:

$A asInteger              // => 65
$A asString               // => "A"
$A printString            // => "$A"
$A uppercase              // => 65
$A lowercase              // => 97
$A class                  // => Character
$A respondsTo: #uppercase // => true
Character value: 65       // => $A
(Character value: 10) asString   // => "\n" (LF, not "10")
$a uppercase asString            // => "A"

String Operations (Grapheme-Aware)

String operations respect Unicode grapheme clusters (user-perceived characters):

// Length in graphemes, not bytes
"Hello" length        // => 5
"世界" length          // => 2 (not 6 bytes)
"👨‍👩‍👧‍👦" length        // => 1 (family emoji is 1 grapheme, 7 codepoints)

// Slicing by grapheme
"Hello" at: 1         // => "H"
"世界" at: 1           // => "世"

// First / last grapheme
"Hello" first         // => "H"
"Hello" last          // => "o"
"über" first          // => "ü" (one grapheme, two UTF-8 bytes)

// Iteration over graphemes
"Hello" each: [:char | Transcript show: char]

// Case conversion (locale-aware)
"HELLO" lowercase     // => "hello"
"straße" uppercase    // => "STRASSE" (German ß → SS)

Inherited Byte-Level Methods

String inherits byte-level methods from Binary. These provide unambiguous byte access regardless of grapheme semantics:

// Byte access (inherited from Binary)
"hello" byteAt: 0      // => 104 (byte value, 0-based)
"hello" byteSize       // => 5 (byte count)
"café" byteSize        // => 5 (bytes — more than 4 graphemes due to UTF-8)

// Byte-level slicing returns Binary, not String
"hello" part: 0 size: 3  // => Binary (raw bytes, not String)

// Byte-level concatenation returns Binary
"hello" concat: " world"  // => Binary (use ++ for String concatenation)

// Byte list conversion
"hello" toBytes        // => #(104, 101, 108, 108, 111)

See Binary — Byte-Level Data for the full Binary API.

BEAM Mapping

Why UTF-8 by Default?

1. Modern web/API standard - JSON, HTTP, REST APIs all use UTF-8
2. Compact for ASCII - 1 byte per ASCII character (most code/English text)
3. Elixir compatibility - Seamless interop with Elixir libraries
4. BEAM convention - Erlang's :string module is Unicode-aware
5. Agent/LLM-friendly - AI models output UTF-8; easy integration

Legacy Charlist Support

Charlists are Erlang lists of integer codepoints. Beamtalk uses binaries for strings, but you can convert when needed for Erlang interop via binary_to_list / list_to_binary.

Core Syntax

Actor Definition

Actor subclass: Counter
  state: value = 0

  increment => self.value := self.value + 1
  decrement => self.value := self.value - 1
  getValue => self.value
  incrementBy: delta => self.value := self.value + delta

Actor Lifecycle Hooks

Actors support two optional lifecycle hooks:

• initialize — called automatically after spawn, before the actor is returned to the caller. Use it to set up resources or compute derived state.
• terminate: reason — called automatically during graceful shutdown (stop) and supervisor-initiated shutdown (cascade or direct aSupervisor terminate: aClass). Use it to clean up resources. The reason parameter indicates why the actor is stopping (e.g., #normal, #shutdown).

Actor subclass: ResourceActor
  state: handle = nil

  initialize =>
    self.handle := Resource open

  terminate: reason =>
    self.handle isNil ifFalse: [self.handle close]

  doWork => self.handle process

Key behaviour:

Both hooks are optional — actors without them work normally.

Initialization chaining — initialize methods defined on ancestors run automatically, parent-first, before the child's own initialize. State threads through each call so the child sees the parent's mutations. Do not write super initialize yourself — the compiler warns on redundant super initialize sends inside an Actor's initialize. After the full chain runs, any typed state: field without a default (on the child or any ancestor, including cross-file parents) must have been assigned, or the actor crashes with UninitializedStateError naming the owning class. See ADR 0078.

Three Class Kinds (ADR 0067)

Beamtalk has three class kinds with distinct data keywords and construction protocols:

// Value — immutable data, no process (ADR 0042)
Value subclass: Point
  field: x = 0
  field: y = 0

  // Methods return new instances (immutable)
  plus: other => Point new: #{x => (self.x + other x), y => (self.y + other y)}
  printString => "Point({self.x}, {self.y})"

// Actor — process with mailbox
Actor subclass: Counter
  state: count = 0

  // Methods mutate state via message passing
  increment => self.count := self.count + 1
  getCount => self.count

// Object — no Beamtalk-managed data; commonly class-methods-only
Object subclass: MathHelper
  class factorial: n =>
    n <= 1
      ifTrue: [1]
      ifFalse: [n * (self factorial: n - 1)]

Key differences:

Class hierarchy:

ProtoObject (minimal — identity, DNU)
  └─ Object (protocol provider — reflection, equality, error handling)
       ├─ Integer, String (primitives)
       ├─ Value (immutable value objects — field:)
       │    ├─ Point, Color (value types)
       │    ├─ Collection(E) (abstract)
       │    │    └─ Set(E), Bag(E), Interval
       │    └─ TestCase (BUnit test base)
       └─ Actor (process-based — state: + spawn)
            └─ Counter, Server (actors)

Why this matters:

• Clarity: The data keyword tells you the mutability contract — field: = fixed, state: = changeable — without looking up the class hierarchy
• Safety: Using the wrong keyword is a compile error, not a silent runtime footgun
• Performance: Value types avoid process overhead for simple data
• BEAM alignment: field: maps to Erlang maps, state: maps to gen_server state

Object's Three Roles

Object subclass: cannot have instance data (field: or state: is a compile error). Object serves three purposes:

1. Protocol provider — common methods inherited by all Value and Actor subclasses: isNil, respondsTo:, printString, hash, error:, yourself, show:, showCr: (debug output to Transcript; replaces the former trace:/traceCr: which are deprecated aliases)
2. FFI namespace — zero-overhead class-method wrappers around Erlang modules and OTP primitives (e.g., Json, System, File, Ets, Random). No instances, no process
3. Abstract extension point — framework contracts designed for subclassing, where subclasses define methods but hold no data (e.g., Supervisor, DynamicSupervisor)

// FFI namespace — wraps Erlang modules as class methods
Object subclass: Json
  class parse: str => // ... Erlang FFI
  class stringify: obj => // ... Erlang FFI

// Abstract extension point — designed for subclassing
abstract Object subclass: Supervisor
  class children => self subclassResponsibility

Sendability Tiers (ADR 0103)

Because a BEAM send copies the term, whether a value survives crossing a process boundary depends on its class kind. The type checker derives a sendability tier for every inferred type and warns (advisory only, per ADR 0100) when a value's tier is too weak for the boundary it crosses. No new annotations are required for the common case — the class kind is the annotation.

A Value composes structurally, inheriting the weakest tier of its fields, and generic collections inherit their element tier (List(Port) is HandleScoped). The builtin table classifies the canonical hazards directly: Pid → SendableRef, Port/FileHandle → HandleScoped(#process), Reference → Sendable, Subscription → HandleScoped(#node).

Checked boundaries (a HandleScoped(#process) value warns): actor message arguments, spawnWith: initial-state maps, blocks sent to actors (including Timer every:do: and postfix ! casts), and Announcement payloads. Local blocks (do:, collect:, ifTrue:) and self-sends do not warn.

Declaring handle scope

A user Object subclass: that wraps runtime state may declare its scope with a class-side handleScope: clause. The value is symbol-valued and the set is open (#process and #node ship first); undeclared Object kinds stay Unknown (silent).

// node-global handle: fine to send within the node, not across nodes
sealed typed Object subclass: MetricsTable
  handleScope: #node

handleScope: is only meaningful on Object-kind classes (a Value/Actor declaration is an advisory no-op). A companion lint nudges FFI-wrapping (native:) Object classes that carry instance behaviour but declare no scope. Suppress a sendability finding with @expect sendability.

Header clauses are parsed in a fixed order — write them as: modifiers → Superclass subclass: Name(TypeParams) → native: module → handleScope: #scope. In particular native: must precede handleScope:; reversing them (handleScope: #process native: pb) silently drops the native: clause (it falls into the class body).

Wrong Keyword Errors

The compiler enforces keyword/class-kind rules with clear error messages:

// state: on a Value — compile error
Value subclass: BadValue
  state: x = 0
// error: use 'field:' for Value subclass data declarations, not 'state:'

// field: on an Actor — compile error
Actor subclass: BadActor
  field: x = 0
// error: use 'state:' for Actor subclass data declarations, not 'field:'

// Any data declaration on an Object — compile error
Object subclass: BadObject
  state: x = 0
// error: Object subclass cannot have instance data declarations;
//   use 'Value subclass:' for immutable data or 'Actor subclass:' for mutable state

Class Modifiers

Class definitions support optional modifier keywords before the superclass:

Modifiers can be combined: sealed typed Collection subclass: Array.

Most stdlib classes are sealed — this prevents user code from subclassing built-in types like Integer, String, Array, Result, and Stream. If you need custom behaviour, compose with these types rather than subclassing them.

Performance: Sealed actor classes benefit from a direct-call optimization — self-sends within the class emit direct function calls instead of dynamic dispatch, since the compiler knows no subclass can override the method. This is automatic and requires no user intervention.

Self-Sends and Overrides (BT-3666)

A self send is late-bound on the receiver, as in every Smalltalk: an inherited (or trait-flattened, ADR 0127) method that does self foo runs the foo of the receiver's class, so a subclass override is reached. This is what makes the template-method pattern work.

Actor subclass: Report
  title -> String => "Report"
  render -> String => "== " ++ self title ++ " =="

Report subclass: SalesReport
  title -> String => "Sales"

// SalesReport spawn render  => "== Sales =="

This holds for instance-side sends on actors and value classes, for class-side sends (class foo / self foo inside a class method), and for a protocol's provided methods flattened into a class whose subclass overrides a required selector.

super is the exception by design — it is always bound to the superclass of the class that contains the method. A sealed class cannot be subclassed, so its self-sends are compiled as direct calls (no lookup).

Implementation notes: an actor self-send dispatches through the module named by the instance's own '__class_mod__' state key (a per-send map lookup); a class-side self-send in a non-sealed class calls the compiled method directly when the receiver is the defining class and nothing shadows it (beamtalk_class_dispatch:class_self_direct_ok/4), and otherwise walks the class hierarchy from the receiving class (beamtalk_class_dispatch:class_self_send/4). Only self foo late-binds: naming the class explicitly (Base foo) calls Base's own method directly, but the running receiver (ClassSelf and its class variables) is still the subclass's, so self sends nested inside Base foo still late-bind to overrides and class-variable writes go to the subclass's class variables. Class variables live in the class process and are read and written in place (ADR 0130), so a write is visible to every later read wherever it happens: at a class method's top level, inside bare blocks, loops, conditionals, ensure:/on:do: bodies, and in a stored closure invoked by a later statement. Nothing is threaded through class-side self-sends. A write made inside a catch boundary (on:do:, Result tryDo:) whose block then raises is discarded with the rest of that protected region (ADR 0130 §4); writes made before entering the boundary are kept. A selector declared class sealed cannot be overridden and stays a direct call.

Cost: every non-sealed actor self-send does a maps:get('__class_mod__', State, Module) lookup (tens of nanoseconds). An open-class class-side self foo is a guarded direct call: when the receiver is the defining class itself and no class-side extension or runtime-installed method shadows foo, it calls the compiled class_foo directly (a few persistent_term reads more than a sealed class, about 215 ns on a 4-core VM); when the receiver is a subclass it walks the class hierarchy (microseconds). Seal the class (or the selector, class-side) to keep plain direct calls.

Value subclass: in Depth

Value subclass: defines an immutable value object. All slots are set at construction time; there is no mutation.

Construction forms

Three forms create instances — all produce equivalent results:

// 1. new — all slots get their declared defaults
p := Point new                       // => Point(0, 0)

// 2. new: — provide a map of slot values; missing keys keep defaults
p := Point new: #{#x => 3, #y => 4}  // => Point(3, 4)

// 3. Keyword constructor — auto-generated from slot names
p := Point x: 3 y: 4                 // => Point(3, 4)

The keyword constructor form (Point x: 3 y: 4) is preferred for readability. The argument order follows the order the slots were declared.

with*: functional setters

Each slot automatically gets a with<SlotName>: method that returns a new instance with that slot changed. The original object is unchanged.

p  := Point x: 1 y: 2
p2 := p withX: 10       // new object: x=10, y=2
p  x                     // => 1   (original unchanged)
p2 x                     // => 10
p2 y                     // => 2

// Chaining
p3 := (Point new withX: 5) withY: 7   // x=5, y=7

The with<SlotName>: selector is built by uppercasing only the first letter of the slot name. Two slots whose names differ only by the case of their first letter (e.g. x and X) would generate the same setter selector — this is a compile error:

// Compile error — rejected before the code runs:
// Value subclass: Weird
//   field: x = 0
//   field: X = 0   ← error: both `x` and `X` produce the setter `withX:`

Immutability enforcement

Direct slot mutation is illegal in value types:

• Compile-time: self.x := newX inside a Value subclass: method is a compile error (Cannot assign to slot).
• Runtime: fieldAt:put: raises immutable_value (use with*: instead).

// Compile error — rejected before the code runs:
// Value subclass: BadPoint
//   field: x = 0
//   badSetX: v => self.x := v   ← error: Cannot assign to slot

// Runtime error:
p := Point x: 1 y: 2
p fieldAt: #x put: 99   // raises: immutable_value

Value equality

Value objects compare by structural equality: two objects with the same class and the same slot values are equal (==).

p1 := Point x: 3 y: 4
p2 := Point x: 3 y: 4
p1 == p2    // => true

p3 := Point x: 9 y: 9
p1 == p3    // => false

// with*: result equals a freshly constructed object
(p1 withX: 10) == (Point x: 10 y: 4)   // => true

This compares the representation, and cannot be changed: the equality operators are not overridable (see Equality operators cannot be overridden). A value type whose logical value differs from its stored form — one that is not canonicalised, or that carries a field outside its identity — should override equals: and say so in its class documentation.

Value objects in collections

Value objects work seamlessly with all collection methods:

points := #((Point x: 1 y: 1), (Point x: 2 y: 2), (Point x: 3 y: 3))

// collect: transforms elements
points collect: [:p | p x]           // => #(1, 2, 3)

// select: filters elements
points select: [:p | p x > 1]        // => #(Point(2,2), Point(3,3))

// inject:into: folds
points inject: 0 into: [:sum :p | sum + p x]   // => 6

Reflection

p := Point x: 3 y: 4
p fieldAt: #x          // => 3
p fieldAt: #y          // => 4
p fieldNames size      // => 2  (contains #x and #y; order is not guaranteed)
p class                // => Point
Point superclass       // => Value

// Full chain from self up to (and including) Object (or Object class for metaclass receivers)
Counter superclassChain        // => [Counter, Actor, Object]
Object superclassChain         // => [Object]
Counter class superclassChain  // => [Counter class, Actor class, Object class]

Message Sends

// Unary message
counter increment

// Binary message (standard math precedence: 2 + 3 * 4 = 14)
2 + 3 * 4

// Keyword message
dict at: #name put: "hello"

// Cascade - multiple messages to same receiver
Transcript show: "Hello"; cr; show: "World"

Message Precedence (high to low)

1. Unary messages: 3 factorial
2. Binary messages: 3 + 4 (with standard math precedence within binary)
3. Keyword messages: dict at: #name

Splitting a Message Send Across Lines

A newline acts as a statement separator (see "Core Syntax" above), so whether a message send can be split across lines — receiver on one line, message on the next — depends on whether the following line could validly begin a new statement on its own:

// Keyword messages split fine: a bare keyword part (`copyFrom:`) can never
// start a statement on its own, so it unambiguously continues the receiver
// above, no matter how it's indented.
result := "abc"
  copyFrom: 1
  to: 2

// A unary selector chained after something else on the same line also
// splits fine, because only the *continuation* keyword moves to its own line:
result := "abc" asList
  collect: [:ch | ch uppercase]

// A unary selector alone on its own line, immediately after its intended
// receiver, does NOT continue it — it parses as a new statement instead:
result := "abc"
  asList        // parsed as its own statement, not `"abc" asList`

This is intentional, not a bug: a bare identifier like asList is itself a valid statement (e.g. a variable reference), so the parser cannot safely rejoin it with the line above without risking silently swallowing a genuinely separate statement that happens to start with a unary-looking name. Keyword parts don't have this ambiguity — bar: alone can never be a complete statement — which is why only keyword-message continuation is safe to infer automatically.

Keep a unary selector on the same line as its receiver. If the identifier that follows fails to resolve, the diagnostic hints at this — join the two lines instead of chasing a phantom spelling mistake.

Binary Operators

Binary operators follow standard math precedence (highest to lowest):

Exponentiation (highest precedence)

• ** - Power: 2 ** 10 → 1024 (right-associative)

Multiplicative

• * - Multiplication: 3 * 4 → 12
• / - Division: 10 / 2 → 5
• % - Modulo/Remainder: 17 % 5 → 2

Additive

• + - Addition: 3 + 4 → 7
• - - Subtraction: 10 - 3 → 7
• ++ - String concatenation: "Hello" ++ " World" → "Hello World"

Number-on-the-left coercion (plusFromNumber: etc.)

+ - * / are receiver-dispatched messages, so a value type can overload them as the receiver — aVector + 5 works because Vector defines +. That says nothing about 5 + aVector: a numeric literal (or other statically-numeric receiver) on the left, with a non-numeric value type on the right. For that shape, Beamtalk dispatches to a reflected method on the right operand instead of crashing, named by a <verb>FromNumber: convention:

A value type opts in per operator by declaring the method it wants to support, alongside its ordinary receiver-dispatch operators:

Value subclass: Vector
  field: components :: Array = #()

  + other :: Number -> Vector => self collect: [:c | c + other]
  - other :: Number -> Vector => self collect: [:c | c - other]

  plusFromNumber:  n :: Number -> Vector => self collect: [:c | n + c]
  timesFromNumber: n :: Number -> Vector => self collect: [:c | n * c]
  minusFromNumber: n :: Number -> Vector => self collect: [:c | n - c]

aVector + 5   // => Vector(6, 7, 8)   receiver-dispatch `+`, unchanged
5 + aVector   // => Vector(6, 7, 8)   dispatches to `aVector plusFromNumber: 5`

Operand order matters — easy to get backwards for a non-commutative operator. The reflected method's receiver (self) is the value that was on the right of the original expression; its parameter is the value that was on the left. 5 - aVector sends aVector minusFromNumber: 5, computing n - self (5 minus each component) — not self - n. aVector - 5 (ordinary receiver-dispatch -, unchanged) computes the opposite: each component minus 5. These are genuinely different computations, not the same subtraction read backwards:

aVector := Vector withAll: #(1 2 3)
aVector - 5   // => Vector(-4, -3, -2)   each component minus 5 (self - n)
5 - aVector   // => Vector(4, 3, 2)      5 minus each component (n - self)

When an operator doesn't apply, implement it anyway — to reject with intent. Not every reflected operator makes sense for every type: 5 / aVector ("a number divided by a vector") rarely has an obvious meaning the way 5 * aVector (scale) does, and a point-like type (e.g. Temperature) may sensibly support + but not *. Omitting the method leaves does_not_understand to fire on a selector — divFromNumber: — that the caller never typed, which is harder to connect back to their own 5 / aVector than an ordinary DNU is. Implementing the method anyway, with a body that rejects explicitly, is better:

divFromNumber: n :: Number -> Vector =>
  self error: "Cannot divide a number by a Vector — did you mean (aVector / n)?"

A type author who commits to number-on-the-left arithmetic at all typically implements all four reflected methods — some as real arithmetic, the rest as deliberate rejections — not a variable subset.

Missing hook: does_not_understand, with a hint. A type that implements no reflected method at all still fails safely — 5 + aThing raises an ordinary does_not_understand rather than crashing with a raw BEAM badarith. Because plusFromNumber: is a selector synthesized by this mechanism rather than one the caller ever typed, the error carries an added hint naming the original operator:

5 + "not a vector"
// => ERROR: String does not understand 'plusFromNumber:'
// => ERROR: String has no 'plusFromNumber:' — implement it to support 'number + String' arithmetic

This is receiver-dispatch's mirror image, not a new arithmetic mechanism: no generality/coercion tower, no perform:-based reflective retry — each reflected method is an ordinary, fully-typed method, so static typing (covariant-return refinement) and compile-time DNU checking work on it exactly as they do on +/-/*// themselves. A type that never implements number-on-the-left arithmetic pays no cost for it: a statically-typed call site (total + delta, both operands' types known at compile time) compiles to the identical bare arithmetic instruction whether or not this mechanism exists. Comparison operators (< > <= >=) are not covered by this convention — 5 < aVector is unaffected. See ADR 0116 for the full double-dispatch design, the rejected alternatives (a Smalltalk-style generality tower, perform:-based retry), and the zero-cost measurement for the statically-typed case.

Comparison

• < - Less than: 3 < 5 → true
• > - Greater than: 5 > 3 → true
• <= - Less than or equal: 3 <= 3 → true
• >= - Greater than or equal: 5 >= 3 → true

Equality (lowest precedence)

• =:= - Strict equality (Erlang =:=): 5 =:= 5 → true
• == - Loose equality (Erlang ==): 5 == 5.0 → true
• /= - Loose inequality (Erlang /=): 5 /= 6 → true
• =/= - Strict inequality (Erlang =/=): 5 =/= 6 → true

Note: bare = is not a valid Beamtalk operator — it has no entry in the parser's precedence table, so x = y fails to parse. Use =:= for value equality or == for reference equality.

Equality operators cannot be overridden

Unlike the arithmetic (+ - * /) and ordering (< > <= >=) operators, which are dispatched as messages so a value type can overload them, all four equality operators are lowered directly to the corresponding Erlang BIF at codegen time (ADR 0002). There is no method lookup, so a class-level =:= / =/= / == / /= method could never be called. Declaring one is a compile error (BT-2997):

Value subclass: Money
  field: cents :: Integer = 0
  =:= other :: Money -> Boolean => self.cents =:= other cents
  // error: `=:=` cannot be overridden — this method can never be called

Use equals: instead. It is declared on Object, defaults to =:=, and is an ordinary message send, so overriding it works:

// Fractions stored unnormalised: 1/2 and 2/4 are different terms…
half := Fraction numer: 1 denom: 2
twoQuarters := Fraction numer: 2 denom: 4

half =:= twoQuarters      // => false  (structural — compares representation)
half equals: twoQuarters  // => true   (dispatches to Fraction>>equals:)

This is a deliberate limit, not a gap to be closed. The keyed containers decide identity inside the VM, below anything the language can dispatch — Dictionary by Erlang map keys, Set by a term-order-sorted list — as do lists:member/2, ets, and receive-pattern matching. An override the compiler honoured would still be invisible to all of them, so a =:= b could report true while a Set holding both still reported size 2. A class that needs content-based membership must normalise its representation rather than redefine the operator.

Both containers use =:= for identity, so they agree with each other and with List>>includes: — Set new add: 1; add: 1.0 holds two elements, matching a Dictionary keyed on 1 and 1.0. What they cannot do is consult a user-defined equals:.

What honours equals:

The line is searching versus keying: a linear search can afford to ask each element, while membership in a keyed container — or deduplication — needs an order or a hash that a user-defined equals: cannot supply. This is the same constraint Java's equals/hashCode contract expresses.

An equals: override must agree with =:= wherever =:= holds: it may only make more values equal, never fewer. The searches rely on that to try raw equality first and dispatch only on a miss.

Where the two notions of equality are genuinely different questions, prefer a domain-specific name to overriding equals: — DateTime keeps equals: structural and offers sameInstant: for instant-based comparison.

Short-circuit boolean operators (and:/or:)

and and or are not binary operators. They are keyword messages that take blocks for short-circuit evaluation:

// Short-circuit AND - second block only evaluated if first is true
result := condition and: [self expensiveCheck]

// Short-circuit OR - second block only evaluated if first is false  
result := condition or: [self fallbackValue]

Field Access and Assignment

Direct field access within actors using dot notation:

// Read field
current := self.value

// Write field
self.value := 10

// Explicit assignment
self.value := self.value + 1
self.count := self.count - delta
self.total := self.total * factor

Note: self.field compiles to direct map access, not a message send. For external access to another actor's state, use message sends.

Parenthesized assignment: Field assignments can be used as expressions when wrapped in parentheses — (self.x := 5) returns the assigned value:

// Assignment as expression (returns 6)
(self.x := 5) + 1

// Field assignments as sequential statements
self.x := 5
self.y := self.x + 1
self.y

Limitation: Field assignments (self.x :=) in stored closures are a compile error — they require control-flow context for state threading. Local variable mutations in stored closures work in actor instance methods (ADR 0041 Tier 2); elsewhere a stored closure that writes an outer local has no way to return the write and is a compile error (ADR 0131 §6, see Control Flow and Mutations).

// ❌ ERROR: field assignment inside stored closure
nestedBlock := [:m | self.x := m]

// ✅ Field mutation in control flow blocks
true ifTrue: [self.x := 5]

// ✅ Local variable mutation in a control-flow block
count := 0
10 timesRepeat: [count := count + 1]   // count => 10

Blocks (Closures)

// Block with no arguments
[self doSomething]

// Block with arguments
[:x :y | x + y]

// Block with local variables
[:x | temp := x * 2. temp + 1]

Non-local returns: ^ inside a block returns from the enclosing method, not just from the block. This is the standard Smalltalk non-local return semantics and enables clean early-exit patterns:

Object subclass: Finder
  firstPositive: items =>
    items do: [:x | x > 0 ifTrue: [^x]]
    nil   // returned only if no positive element found

Object subclass: Validator
  validate: x =>
    x isNil ifTrue: [^"missing"]
    x isEmpty ifTrue: [^"empty"]
    "ok"

^ at the top level of a method body is an early return (the method exits immediately). ^ inside a block argument causes the method to exit with that value.

Abstract and Stub Methods

Empty method bodies are a compile-time error. Use one of these two explicit forms instead:

// Abstract interface contract — must be overridden by subclasses
area => self subclassResponsibility

// Work-in-progress stub — not yet implemented
processPayment => self notImplemented

Both methods raise a runtime error with a clear message. The distinction is intent: subclassResponsibility signals an interface contract, while notImplemented marks incomplete work.

Class-Side Methods (ADR 0048)

Methods prefixed with class belong to the class itself, not to instances. They are called on the class name directly.

Object subclass: MathUtils
  class factorial: n =>
    n <= 1
      ifTrue: [1]
      ifFalse: [n * (self factorial: n - 1)]

  class fibonacci: n =>
    n <= 1
      ifTrue: [n]
      ifFalse: [(self fibonacci: n - 1) + (self fibonacci: n - 2)]

MathUtils factorial: 10    // => 3628800
MathUtils fibonacci: 10    // => 55

Common uses:

• Factory methods: Counter spawn, Point x: 3 y: 4 (auto-generated from field: declarations)
• FFI namespaces: File readAll: path, Json parse: str — class methods wrapping Erlang modules
• Supervisor configuration: class children, class strategy — pure metadata for OTP init
• Singleton access: class current — return the singleton instance (see classState: below)

classState: declares mutable class-level state — shared across all instances and accessible from class methods. Used for singletons:

sealed Object subclass: MyRegistry
  classState: current = nil

  class current => self.current
  class current: instance => self.current := instance

classState: is distinct from state: (per-instance actor state) and field: (per-instance immutable data). It stores values at the class level, analogous to Smalltalk class variables.

A class variable is read and written in place in the class's own process; see Class variables and blocks for what a block, a caught error and a call from another process see.

Programmatic Class Creation (ClassBuilder) (ADR 0038 / ADR 0084)

Object subclass: Counter … is the grammar form, but a class can also be built programmatically by cascading messages to a ClassBuilder and ending with register. This is a first-class user API (the same protocol the compiler emits for the grammar form): register returns the new, dispatchable class object.

// Build a class in one cascade. register returns the canonical class object.
account := Object classBuilder
  name: #Account;
  superclass: Object;
  classVars: #{ #opened => 0 };
  fields: #{ #balance => 0 };
  methods: #{ #balance => [:inst | inst fieldAt: #balance] };
  classMethods: #{ #open => [:self | self.opened := self.opened + 1. self.opened] };
  register

account new balance        // => 0
Account open               // => 1  (also reachable by name — the name IS the class)
Account open               // => 2  (class-variable state threads correctly)

Each block value is compiler-lowered into the same dispatchable fun a file-defined method produces, so class-variable mutations thread, and super / self resolve — it is not a naive runtime closure. Class methods built this way are callable and reflectable (ADR 0084).

Incremental piece API. A class can be assembled one piece at a time before register — the "browser" use case. The add* setters write the same maps the bulk setters do, and removeMethod: / removeClassMethod: drop a piece:

Object classBuilder
  name: #Tally;
  superclass: Object;
  addClassState: #total default: 10;
  addField: #count default: 0;
  addMethod: #answer body: [:inst | 42];
  addClassMethod: #tally body: [:self | self.total := self.total + 5. self.total];
  register

Tally new answer           // => 42
Tally tally                // => 15

Instantiation. A purely programmatic (module-less) builder class instantiates with new / new:, exactly like a compiled value type:

point := Object classBuilder name: #P; superclass: Object; fields: #{ #x => 0, #y => 0 }; register
point new: #{ #x => 3, #y => 4 }     // => a P  (fields seeded from the map)

Metadata parity. Optional setters bring a builder-defined class to :help parity with a file-defined one — methodSignatures: / classMethodSignatures:, methodDocs: / classMethodDocs:, methodReturnTypes: / classMethodReturnTypes:, classDoc:, meta:, and isConstructible:. The class-side method bodies are also auto-indexed for SystemNavigation source-text queries.

Class-side live edit. A registered class's class method can be live-edited with the same >> patcher used for instance methods (see Live Patching and Extension Methods below), e.g. Counter class >> reset => self.opened := 0. The class-side dispatch path picks up the new class method immediately (ADR 0084).

The grammar form (Object subclass: …) remains the idiomatic way to define a class in source. The programmatic builder is for tooling, REPL exploration, and metaprogramming where the class shape is computed rather than written out.

Doc Comments (///)

Triple-slash comments (///) are structured documentation parsed into the AST and queryable at runtime via Beamtalk help:. They support Markdown formatting and a ## Examples convention with fenced code blocks.

/// Counter — A simple incrementing actor.
///
/// Demonstrates actor state and message passing.
///
/// ## Examples
/// ```beamtalk
/// c := Counter spawn
/// c increment   // => 1
/// ```
Actor subclass: Counter
  state: value = 0

  /// Increment the counter by 1 and return the new value.
  ///
  /// ## Examples
  /// ```beamtalk
  /// Counter spawn increment   // => 1
  /// ```
  increment => self.value := self.value + 1

Query documentation at runtime:

Beamtalk help: Counter
// => "== Counter < Actor ==\n  increment\n  ..."

Beamtalk help: Counter selector: #increment
// => "Counter >> increment\n  Increment the counter by 1..."

Doc comments flow from source → AST → compiled BEAM module → runtime. They are not stripped at compilation. The ## Examples blocks are the source for Beamtalk help: output and can be verified by the test framework.

Method Category Dividers (// === Name ===)

A // === Name === comment placed between methods introduces a method category — a named group used across all surfaces: the LSP outline (documentSymbol), VS Code breadcrumbs/sticky-scroll, LSP folding ranges (textDocument/foldingRange), REPL :help grouped method listing, and MCP docs structured output.

Value subclass: Point
  field: x :: Integer
  field: y :: Integer

  // === Accessing ===

  /// The X coordinate.
  x -> Integer => self.x

  /// The Y coordinate.
  y -> Integer => self.y

  // === Arithmetic ===

  /// Add two points.
  + other :: Point -> Point =>
    Point x: self.x + other x y: self.y + other y

Format: a leading // line comment whose trimmed text is =+ <name> =+, where the leading and trailing = runs are the same length (3 or more) and <name> is non-empty. Triple-slash (///) and block (/* */) comments are not recognized as dividers. A =-bordered comment that looks like a divider but doesn't parse as one (mismatched = run lengths, too-short runs, /////* */ instead of //) is flagged by beamtalk lint as a near-miss (BT-3240). A class with no dividers keeps the existing flat outline — no behavior change.

Methods following a divider belong to that category until the next divider or end of class. Instance-side and class-side methods are merged in true source order (not grouped by side). The REPL falls back to the flat alphabetical listing when grouping can't be trusted (no on-disk .bt file, no dividers, or unflushed >> patches). The stdlib uses this convention throughout (BT-2601, BT-2626, BT-3237, BT-3239, BT-3240).

Erlang FFI

Beamtalk provides direct access to all Erlang modules via the Erlang gateway object (ADR 0028). Send a unary message with the module name to get a proxy, then send messages as normal:

// Call any Erlang module function
Erlang lists reverse: #(3, 2, 1)      // => [1, 2, 3]
Erlang erlang node                     // => current node atom
Erlang maps merge: #{#a => 1} with: #{#b => 2}

// Store a module proxy for repeated use
proxy := Erlang crypto
proxy strong_rand_bytes: 16            // => random binary

The (Erlang module) pattern is used throughout the stdlib to wrap Erlang functions as Beamtalk class methods:

// How File.readAll: is implemented — a thin wrapper.
// The `{ok, _} | {error, _}` tuples beamtalk_file returns become a Result
// at the FFI boundary (see "Result conversion" below), so the return type
// is Result(String, Error), not a bare String.
Object subclass: File
  class readAll: path :: String -> Result(String, Error) =>
    (Erlang beamtalk_file) readAll: path

A class that delegates wholesale to one Erlang module can declare the module on subclass: and replace each body with => self delegate instead of hand-writing the FFI call — see native: for stateless Objects. Stream (native: beamtalk_stream) is the worked example.

Keyword mapping: The Erlang function name is taken from the first keyword (with its colon removed); the remaining keyword values follow as positional arguments. Erlang maps merge: a with: b calls maps:merge(A, B) (not maps:merge_with — only the first keyword names the function). Unary selectors map directly: Erlang erlang node calls erlang:node().

Result conversion (ADR 0076): Erlang functions that return {ok, Value} or {error, Reason} tuples are automatically converted to Result objects at the FFI boundary. This means FFI calls use the same error-handling idiom as native Beamtalk code:

// FFI calls returning ok/error tuples become Result objects
result := Erlang file read_file: "/tmp/hello.txt"
result              // => Result ok: "Hello, world!\n"
result value        // => "Hello, world!\n"

// Use Result combinators directly on FFI returns
result map: [:content | content size]
// => Result ok: 14

// Error path
result := Erlang file read_file: "/nonexistent"
result              // => Result error: enoent
result isError      // => true

// Chain FFI calls with andThen:
(Erlang file read_file: "/tmp/config.json")
  andThen: [:content | Erlang json decode: content]
  mapError: [:e | "Config load failed: " ++ e message]

// Bare ok atoms (e.g. file:write_file/2) become Result ok: nil
Erlang file write_file: "/tmp/out.txt" with: "data"
// => Result ok: nil

Conversion rules:

• {ok, Value} becomes Result ok: Value
• {error, Reason} becomes Result error: Reason
• Bare ok atom becomes Result ok: nil
• Bare error atom becomes Result error: nil
• Tuples with 3+ elements, non-ok/error tuples, and non-tuple values pass through unchanged

Lone ok/error return specs (ADR 0121, type inference): A non-union Erlang return spec of -> ok. or -> error. — including annotated forms like -> Result :: ok. — is now recognized as Result(Nil) or Result(Dynamic, Nil) respectively, matching the runtime coercion that coerce_result/1 already applies. Previously these lone atoms fell through to Symbol in the type inference, creating a static/dynamic type mismatch.

Atom-enum precedence (type inference): When the spec reader maps a pure-atom union type containing atoms beyond ok/error, it infers a singleton union rather than applying ADR-0076 Result recognition. Unions whose atoms are a subset of {ok, error} and lone ok/error atoms infer as Result. For example, a spec of text | json | xml infers #text | #json | #xml, while ok | error or a bare ok infers Result.

⚠️ Type/runtime mismatch for enums containing ok/error. Type inference and runtime coercion use different rules. A spec like ok | error | pending infers the singleton union #ok | #error | #pending at the type level, but runtime ok/error coercion (coerce_result/1) is unconditional and spec-unaware: at runtime a bare ok still arrives as Result ok: nil and a bare error as Result error: nil. So code that matches the inferred #ok/#error singletons passes the type checker but never matches at runtime for those branches. When a spec uses ok or error as semantic enum members, handle those call-site branches as Result, not as the inferred singleton (only the non-ok/error members — here #pending — arrive as singletons).

undefined stays #undefined: Erlang undefined in an FFI return type spec maps to the singleton #undefined (a Symbol), not Nil. The FFI boundary does not coerce undefined → nil — callsites that want nil semantics must convert explicitly.

Scope: Conversion applies only to FFI calls via Erlang module method: args. Messages received from Erlang processes via receive or actor mailboxes remain raw Tuples. Use Result fromTuple: to explicitly convert those:

// Converting a Tuple received from a message
tuple := receiveMessage  // raw {ok, data} Tuple from Erlang process
result := Result fromTuple: tuple
result value  // => data

Migration from Tuple-based FFI code:

// Before (Tuple-based, pre-ADR-0076 — FFI returned raw Tuples):
result := Erlang file read_file: path
result isOk ifTrue: [result unwrap] ifFalse: ["error"]  // Tuple methods

// After (Result-based):
result := Erlang file read_file: path
result ifOk: [:content | content] ifError: [:e | "error"]
// Or simply:
result value  // raises on error

Error handling — wrap by default (ADR 0101): every FFI call is safe by default. The boundary treats the two channels a BEAM function can use independently, and they are mutually exclusive per call (a function either returns or raises):

The guarantee: a user never sees a raw Erlang error tuple. A badarg becomes a structured #beamtalk_error{} (kind type_error) with a hint, not a bare {badarg, [...]} — most visible at the REPL, where the abstraction is most exposed. exit:/throw: are deliberately not wrapped, so (Erlang erlang) exit: #killed still terminates the process with reason killed.

Same function, both channels. Because the channels are orthogonal, one function can use both: File readAll: returns a Result error: for the modeled missing-file case, but raises a #beamtalk_error{} if called with a non-String path. The rule is Result for expected/recoverable outcomes the API models, exceptions for misuse/faults. Wrapping changes no return type — a raised #beamtalk_error{} is invisible to the type system, so Result stays the only type-visible error channel.

A raised FFI error is catchable as BEAMError, ExitError, or ThrowError. The handler block parameter is typed from the exception class argument, so e in on: BEAMError do: [:e | ...] is inferred as BEAMError (not Dynamic):

[Erlang erlang error: #badarg] on: BEAMError do: [:e | e message]
// => "badarg"
// e is typed as BEAMError — `e message` type-checks without warnings

A native: method's wrapped error carries the Beamtalk Class/selector (e.g. Type error in 'take:' on Stream), whereas inline (Erlang …) FFI carries the Erlang-facing ErlangModule context (e.g. Type error in 'atom_to_list' on ErlangModule) — a documented limitation, since the proxy knows the MFA but not the calling class.

Type Specs for Native Modules

When writing native Erlang modules that implement Beamtalk class methods, prefer the exported Dialyzer-facing types for Result and wrapped error values instead of bare map(). These types are primarily useful for Erlang -spec annotations and Dialyzer; Beamtalk's spec importer may resolve them to Dictionary in generated Beamtalk signatures rather than Result(...) / Exception.

Example specs:

-module(beamtalk_mylib).
-include_lib("beamtalk_runtime/include/beamtalk.hrl").

%% Unparameterized — any Result
-spec 'readConfig:'(binary()) -> beamtalk_result:t().
'readConfig:'(Path) ->
    case file:read_file(Path) of
        {ok, Bin} ->
            beamtalk_result:from_tagged_tuple({ok, Bin});
        {error, Reason} ->
            Err0 = beamtalk_error:new(io_error, 'MyLib', 'readConfig:'),
            Err1 = beamtalk_error:with_details(Err0, #{path => Path, reason => Reason}),
            beamtalk_result:from_tagged_tuple({error, Err1})
    end.

%% Parameterized — precise ok/error types for Dialyzer
-spec 'parse:'(binary()) -> beamtalk_result:t(map(), beamtalk_error:t()).
'parse:'(Data) -> ...

These types are defined in:

• runtime/apps/beamtalk_stdlib/src/beamtalk_result.erl — t/0 and t/2
• runtime/apps/beamtalk_runtime/src/beamtalk_error.erl — t/0 and error/0

FFI Collection Element Types

The spec importer carries collection element types from Erlang -spec attributes (ADR 0075 amendment), so iterating an FFI-typed list binds block parameters to the element type instead of Dynamic:

// allSendsIn/1 is specced [{atom(), pos_integer(), atom()}]:
sends := (Erlang beamtalk_interface) allSendsIn: source
sends do: [:s |
  // s is Tuple(Symbol, Integer, Symbol) — no annotation needed
  selector := s at: 1   // inferred Symbol
  arity := s at: 2       // inferred Integer
]

Literal-index tuple access: Sending at: with a literal integer index to a value of a known Tuple(T1, …, Tn) type infers the element type at that 1-based index:

pair := someTupleTyped     // Tuple(Symbol, Integer)
pair at: 1                  // inferred Symbol
pair at: 2                  // inferred Integer

A non-literal index (pair at: i) or an out-of-range literal falls back to Dynamic — no false-positive warning. An untyped tuple() spec (unknown arity) stays bare Tuple, so at: on it remains Dynamic as before.

FFI Type Stub Files (ADR 0075 Phase 2)

When the auto-extracted Erlang -spec types are missing or imprecise for a module, you can provide hand-written type stubs in a project's stubs/ directory. Each .bt file there uses declare native: to declare type signatures for Erlang module functions:

/// Type declarations for Erlang module `lists`.
declare native: lists
  reverse: list :: List(T) -> List(T)
  seq: from :: Integer to: to :: Integer -> List(Integer)
  member: elem :: T in: list :: List(T) -> Boolean

Stub signatures use the same syntax as Protocol method signatures — parameter names with optional :: Type annotations and an optional -> ReturnType — but never have a => body. Unary functions use a bare name:

declare native: erlang
  node -> Symbol
  self -> Pid

declare is a contextual keyword — it remains a legal identifier everywhere else.

Build integration: beamtalk build and beamtalk lint automatically scan the project's stubs/ directory (no beamtalk.toml config needed). Stub declarations merge into the FFI type registry at function/arity granularity: a stub for lists:reverse/1 overrides only that entry; lists:nth/2, not declared in the stub, still uses the auto-extracted type from the .beam file.

Version-drift detection: A stub function/arity that doesn't exist in the corresponding .beam module's real exports produces a warning anchored to the stub file, so stubs stay in sync with the Erlang modules they describe.

Restrictions:

• declare native: is only valid in stubs/ — using it in src/ is a hard compile error.
• Project-local stubs/ only (resolution chain layer 1). Package-bundled and compiler-distribution stubs are a planned follow-up.

Generating stubs: Use beamtalk generate stubs to bootstrap stub files from .beam abstract code:

beamtalk generate stubs lists maps string
# Output: stubs/lists.bt, stubs/maps.bt, stubs/string.bt

Loading Code into the Workspace

Beamtalk source files are loaded into the live workspace via :load or the Workspace class-side facade. Loaded classes are immediately available — existing actors pick up new code on next dispatch.

// Via REPL shortcut
:load examples/counter.bt
// => Loaded: Counter

// Via native message send (works from compiled code and MCP)
Workspace load: "examples/counter.bt"

// Load an entire directory (compiles all .bt files in dependency order)
Workspace load: "src/"

// Reload a specific class from its source file
Counter reload
// => Counter  (recompiled and hot-swapped)

// Or via REPL shortcut
:reload Counter

See Workspace and Reflection API for the full Workspace facade interface.

Gradual Typing (ADR 0025)

Beamtalk supports optional type annotations and typed classes. Type checks are compile-time warnings (not hard errors), so interactive workflows remain fast.

Typed Class Syntax

typed Actor subclass: TypedAccount
  state: balance :: Integer = 0
  state: owner :: String = ""

  deposit: amount :: Integer -> Integer =>
    self.balance := self.balance + amount
    self.balance

  balance -> Integer => self.balance

late Slots (ADR 0124)

A nilable slot is not automatically a late candidate. The question late answers is narrow: is this slot acquired exactly once, by an explicit lifecycle call, and correct for as long as it stays assigned — never whether its type merely permits nil. Most nilable slots in real Beamtalk code use nil to mean something else, and converting them to late would be wrong. Exdura's timer manager resolves its dependencies by name on every read, deliberately, so that a supervisor restart of either dependency is picked up automatically instead of leaving a stale reference behind:

typed Actor subclass: TimerManager
  // (ADR 0079) instead of passing live refs, since neither exists yet
  // when the child spec is built. `engine`/`eventStore` resolve fresh by
  // name in that case, so a `rest_for_one` restart of either is picked up
  // automatically instead of leaving a nil/stale field.
  state: engine :: WorkflowEngine | Nil = nil
  state: eventStore :: EventStore | Nil = nil

An ordinary method (currentEngine/currentEventStore, on the sibling ExduraClient) does the by-name lookup on every call. If engine were converted to late state: engine :: WorkflowEngine and assigned once from a resolved reference, a later restart of WorkflowEngine would leave the stale pid behind, unnoticed — exactly the failure this slot exists to avoid, and exactly what late cannot express: a late slot is absent-or-assigned, never "assigned, but now to the wrong thing." So the distinguishing question is never "can this hold nil?" — it is "would a stale, already-assigned value here be wrong?" If yes, the slot stays nilable and keeps resolving fresh in an ordinary method, the way currentEngine does — that method stays a method, not a slot kind; late has no "recompute on every read" mode and does not try to. Convert only a slot in the other shape: acquired exactly once by an explicit lifecycle call (open a subprocess, start a listener, attach a resource) and correct for the rest of that resource's life — Symphony's CodexClient proc below.

late is a declaration-level modifier on state:/classState: for a slot in that second shape — legitimately unassigned after initialize, acquired later by an explicit lifecycle call — instead of being declared nilable and nil-checked at every read:

typed Actor subclass: CodexClient
  late state: proc :: Subprocess   // not `proc :: Subprocess | Nil = nil`
  state: workspacePath :: String

  launch -> Nil =>
    self.proc := Subprocess open: "/bin/bash" args: #() dir: self.workspacePath

The modifier precedes the declaration keyword, matching the class-header modifier position (sealed typed Actor subclass: …). It requires a type annotation, and that type must not admit Nil and must have no default value — a late slot has exactly two states, absent and assigned, and its declared type is always non-nilable. Five compile-time Errors govern where late may appear:

1. late field: on a Value — a Value is fully constructed and never reassigned (below).
2. late state:/classState: with no type annotation — the point of late is a non-nilable declared type, and an untyped slot already defaults to nil with no check.
3. late state:/classState: on a nilable type (T | Nil) — a slot whose type already admits nil is never in the state late describes.
4. late state:/classState: with a default value — a slot with a default is never unset.
5. late state: on a native: Actor, or late state:/field: on Object — already errors before late is even considered (ADR 0056 forbids state: on a native: Actor; ADR 0067 gives Object no instance data at all), and late does not change that.

late state: x            // error (2): requires a type annotation
late state: x :: T | Nil // error (3): drop `late` or make the type non-nilable
late state: x :: T = v   // error (4): a slot with a default is never unset

late is rejected on a Value's field: (error 1) — a Value is fully constructed by new/new:/its keyword constructor and never reassigned, so "assigned later" has no meaning; make the field optional (| Nil = nil) or hold the resource in an Actor instead. Outside declaration position late stays an ordinary identifier (late := 1) or method name.

Slot kinds and fieldKinds/allFieldKinds. Every declared slot has a kind — #eager (the default, no modifier) or #late — reflectable via Behaviour>>fieldKinds (this class's own slots only) and allFieldKinds (this class's plus every inherited slot, the flattened chain, mirroring fieldNames/allFieldNames):

CodexClient fieldKinds
// => #{#proc => #late, #workspacePath => #eager}

This draws the identical instance-vs-declared line fieldNames/ allFieldNames already draw (ADR 0035): Cls fieldKinds/ Cls allFieldKinds answer the declared schema — a late slot is always listed there, assigned or not — while an instance's fieldNames answers the keys actually present in its state map, so an unassigned late slot is not listed there. That is why c fieldNames silently omitting #proc and c hasField: #proc answering false read as the same fact seen from two angles, not a contradiction: one reports declared shape, the other reports assignment.

A late slot is excluded from the post-initialize definite-assignment check. Reading it before assignment raises UninitializedStateError whichever way it is still unassigned — its key is simply absent, or an open-world writer (spawnWith: with a non-literal map, fieldAt:put:, perform:) has planted an observed nil there without going through ordinary self.slot := assignment; late does not make a non-nilable declared type sound against those writers, it only makes the violation raise at the read, naming the slot, instead of surfacing as a does-not-understand on nil somewhere downstream. self.slot (or fieldAt: #slot) is the raising direct read; hasField: #slot is the non-raising presence test to ask first — Object's hasField:/ clearField: (ADR 0035's field-prefixed reflection family) make a late slot usable, not just declarable: hasField: answers whether it is currently assigned, and clearField: returns it to unassigned so it can be acquired again (maps:remove, not a sentinel value):

typed Actor subclass: CodexClient
  late state: proc :: Subprocess
  state: workspacePath :: String

  launch -> Nil =>
    self.proc := Subprocess open: "/bin/bash" args: #() dir: self.workspacePath

  stopProcess -> Nil =>
    (self hasField: #proc)
      ifTrue: [self clearField: #proc]
    nil

hasField: and clearField: are declared on Object, so they answer for every receiver, not only late-slot actors: hasField: on a Value answers whether the named field is declared, and on a primitive (Integer, String, …) always answers false — never raises. clearField: on a Value is the same "Cannot modify slot on value type" error fieldAt:put: already raises, since a Value is fully constructed and never reassigned. The class-side counterpart (classState:) works the same way, both from inside a class method (self hasField:/self clearField:) and from outside (SomeClass hasField: #x/SomeClass clearField: #x).

Supplying a late slot via spawnWith: counts as assigned — this is legitimate dependency injection (substituting a value for a slot normally acquired by a lifecycle call), not a violation of "absent until assigned": see the spawnWith:-injection clause beside the spawnWith: key-checking rule in Actor Message Passing below. Converting a slot between eager and late (or back) is a shape change and bumps shapeVersion: — see Chain and reconcile semantics for the reconcile-table row and the reload-time tooling finding that flags a flip landing without a version bump.

Unguarded late-slot reads in lifecycle hooks. A direct self.slot read of a late slot inside terminate: or handleInfo: (or one level of self-send from either) that isn't guarded by (self hasField: #slot) ifTrue: [...] produces a compile-time warning (unguarded-late-read diagnostic category). Both lifecycle hooks swallow raised errors — terminate/2's dispatch is try-wrapped, and handleInfo: logs and continues — so an UninitializedStateError from an unguarded read there never surfaces as a crash; the operation is silently skipped instead. The fix is the hasField: guard shown above, not a suppression — like definite-assignment, there is no site-level @expect category for this diagnostic. Per-project severity is configurable via the [diagnostics] table (unguarded-late-read key — see the Package Management guide).

Definite Assignment (ADR 0124)

The compiler checks, at a class's construction site, that every declared, typed, non-nilable, no-default, non-late slot is guaranteed a real value — the same predicate ADR 0078's runtime backstop already used for Actors, now also checked statically, and now for Values too.

The predicate. A state:/field: slot requires definite assignment when it carries a type annotation, has no default value, its declared type does not admit Nil (resolving aliases and intersection/negation operators), and it is not declared late:

state: count :: Integer            // requires assignment
state: label :: String | Nil       // no — Nil is a valid value
state: count :: Integer = 0        // no — has a default
state: count                       // no — untyped, defaults to nil
late state: proc :: Subprocess     // no — declared assigned later (see above)

Where it reports: the construction site, not the declaration. A declaration alone is not enough evidence — the slot might be supplied at every real call site — so the diagnostic fires on Cls spawn / Cls new, or a literal-map Cls spawnWith: #{...} / Cls new: #{...} that omits the slot; only a literal map is inspected, the same boundary the spawnWith: key-checking rule above uses:

typed Actor subclass: Connection
  state: socket :: Socket
  state: retries :: Integer = 0

Connection spawn
//         ^ warning: `Connection` declares `socket :: Socket` with no
//           default, and no `initialize` in its chain assigns it.
//           `Connection spawn` supplies no `socket`, so it may raise
//           `UninitializedStateError`

The four fixes, named in the diagnostic's hint: supply the slot at the construction site, give it a default value, widen its type to admit Nil, or declare it late (Actors only, since late field: is rejected on a Value — see above).

The Actor/Value asymmetry. For an Actor subclass:, this diagnostic is an early warning in front of ADR 0078's existing runtime check — a spawn it flags was already going to raise UninitializedStateError, just later, at spawn time instead of at compile time. For a Value subclass:, it is the only check there is — Values have no initialize and no post-construction runtime validation, so StoredSnapshot new on a typed-no-default field silently yields an instance holding nil behind a declared non-nilable type, with nothing to catch it at runtime. That makes the default Warning severity a real gap, not merely an advisory one, for a Value-heavy codebase — see escalation below.

The deserialization limit. A Value built by deserialization has no construction site at all:

typed Value subclass: StoredSnapshot
  field: state :: ReplaySnapshot   // typed, no default

  class fromBinary: content :: Binary -> StoredSnapshot =>
    result :: StoredSnapshot := Binary deserialize: content
    result

Binary deserialize: is not new/new:, so the check never inspects this site — the local type annotation on result is an assertion at a type-erasure boundary, not something the checker can verify, and nothing is reported here (consistent with the open-world silence of ADR 0100 where knowledge is absent). A class in this position should default the field or widen it to | Nil.

Severity and @expect. The diagnostic is Warning when the checker's knowledge is complete — the ancestor chain is fully known, no ancestor is native:, and (for Actors) no fieldAt:put:/perform: write anywhere in the class is invisible to the must-analysis — and Hint otherwise. There is no dedicated @expect category for this diagnostic, by design: late is the language construct that opts a slot out, not an annotation that silences a warning about it. A test that deliberately constructs an instance with the slot left unassigned suppresses the diagnostic with @expect all.

Escalating to Error. Per-project severity is ADR 0100 Rule 3's [diagnostics] table (definite-assignment = "error" in beamtalk.toml — see the Package Management guide). Because a Value's Warning has no runtime backstop, a Value-heavy codebase has more reason to make that escalation than an Actor-heavy one — provided the bare-new-override check is in place: a class that defines its own class new/new: already exempts that construction site, the same as any other override of the auto-generated constructor.

Annotation Forms

// Unary return annotation
getBalance -> Integer => self.balance

// Keyword parameter annotation
deposit: amount :: Integer => self.balance := self.balance + amount

// Binary parameter + return annotation
+ other :: Number -> Number => other

// Multiple keyword parameters with annotations
sum: left :: Integer with: right :: Integer -> Integer => left + right

// Union type annotations parse (full checking is phased in)
maybeName: flag :: Boolean -> Integer | String =>
  ^flag ifTrue: [1] ifFalse: ["none"]

// Self return type — resolves to the static receiver class at call sites
// (only valid in return position, not parameters)
collect: block :: Block(E, R) -> Self =>
  self species withAll: (self inject: #() into: [:acc :each |
    acc addFirst: (block value: each)
  ]) reversed

// At call sites, Self resolves to the static receiver type:
// (List new collect: [:each | each])  — inferred return type: List
// (Set new collect: [:each | each])   — inferred return type: Set

// Self also substitutes inside nested generic return types
class named: name :: Symbol -> Result(Self, Error) => ...
// (Counter named: #c) — inferred return type: Result(Counter, Error)

// On parameterised receivers, Self preserves type arguments:
// (Box(Integer) new) someMethod — where someMethod -> Result(Self, Error)
//   inferred return type: Result(Box(Integer), Error)

// Self class — the receiver's metatype, i.e. the class object (ADR 0083).
class -> Self class => @primitive "class"
// (Counter new) class — inferred type: the metatype-of-Counter (rendered
// `Counter class`). Sends are routed class-side: `(Counter new) class new`
// infers a Counter instance, and `(Counter new) class instanceCount`
// type-checks against Counter's class-side methods.

// <ClassName> class — a named class metatype annotation.
// Valid in any type position (fields, parameters, return types, locals).
// Resolves to the metatype-of-<ClassName> (a tracked type, ADR 0083), so
// class-side methods on that class resolve without false DNU warnings, and a
// class value flows with type through variables, collections, and FFI returns.
// The metatype is name-only — the class object is unparameterized (ADR 0068),
// so there is no `List(E) class`, only `List class`. Type-erased at runtime.
field: actorClass :: Actor class | nil = nil
// After `actorClass isNil ifTrue: [^nil]`, actorClass is narrowed to
// `Actor class` — class-side methods like `isSupervisor` type-check.

// Class literal inference: a bare class literal (`Counter`) infers as the
// metatype `Counter class`, so class values stored in variables, collections,
// or returned from FFI calls route class-side sends correctly without annotation.
klass := Counter            // inferred Counter class (the metatype)
klass new                   // inferred Counter (an instance)
klass instanceCount         // resolves class-side method

// Metatype subtyping: `C class <: Class <: Behaviour <: Object`, so a class
// value satisfies `:: Class` / `:: Behaviour` parameters and `List(Behaviour)`
// FFI returns. `new` / `basicNew` on a *concrete* class metatype infers an
// instance of that class; on an *abstract* class (e.g. `Collection`,
// `Behaviour`) it stays Dynamic — instantiating an abstract class is an error.

Current Semantics

• Type mismatch diagnostics are warnings, never compile-stopping errors.
• Invalid annotation forms (e.g., Self in parameter position) are errors.
• typed classes require parameter/return annotations on non-primitive methods.
• Data annotations (field: x :: Integer = 0 on Value, state: x :: Integer = 0 on Actor) are checked for defaults and assignments. When a type annotation is present, the default value is optional (field: x :: Integer / state: x :: Integer) — the type annotation is the contract, and nil is used internally.
• Local variable annotations (name :: Type := expr) declare the binding's type at type-erasure boundaries. See Local Variable Type Annotations below.
• Complex annotations (e.g., unions/generics) are parsed and accepted; deeper checking is phased in.
• Self in return position resolves to the static receiver class. Using Self as a parameter type is an error (unsound with subclassing).

Local Variable Type Annotations

Local variables can carry a type annotation using name :: Type := expr. The declared type overrides the inferred type of the right-hand side, which is useful at type-erasure boundaries (FFI returns, deserialization, untyped APIs). The annotation is erased at codegen — there is no runtime effect.

x :: Integer := 42
dict :: Dictionary := Binary deserialize: content
name :: String | nil := dictionary at: "name"
r :: Result(Integer, Error) := computeSomething

Supported type forms: simple (Integer), parametric (Result(T, E)), and union (String | nil).

Type checking: The compiler warns when the RHS type is unrelated to the declared type (e.g., x :: Integer := "hello"). Narrowing assertions — where the declared type is more specific than the inferred type — are accepted silently, since the annotation communicates that the runtime type is known to be more specific (BT-2015). Dynamic and Never RHS types are always accepted.

Dynamic Type Visibility (ADR 0077)

When the compiler cannot determine an expression's type, it infers Dynamic. Beamtalk makes Dynamic visible so you can see exactly where the compiler lacks type information and why.

Dynamic with Reasons

Each Dynamic type carries a reason explaining why the type could not be determined:

LSP Hover

When hovering over an expression in the editor, the LSP shows the inferred type including Dynamic with its reason:

Identifier: `handler` — Type: Dynamic (unannotated return)
Identifier: `result` — Type: Dynamic (dynamic receiver)
Identifier: `data` — Type: Dynamic (unannotated parameter)
Identifier: `count` — Type: Integer

When the reason is Unknown, the hover shows just Type: Dynamic. Previously, Dynamic expressions showed no type information at all — the type line was omitted entirely.

Typed Class Diagnostics

typed classes opt into thorough type checking. In addition to requiring parameter and return annotations on methods, typed classes produce warnings for:

Missing State Field Annotations

State fields without type annotations produce a warning:

typed Actor subclass: BankAccount
  state: balance = 0          // warning: Missing type annotation for state field
                               //          `balance` in typed class `BankAccount`
  state: owner :: String = ""  // OK — annotated

Dynamic Inference Warnings

When an expression in a typed class infers as Dynamic (for a root-cause reason like unannotated parameter or unannotated return), the compiler warns. Propagated reasons like dynamic receiver are not warned on separately since the root cause already has its own warning.

typed Actor subclass: BankAccount
  process: handler =>
    handler doWork    // warning: expression inferred as Dynamic in typed class
                      //          `BankAccount` (unannotated parameter)

Suppressing Type Warnings with @expect type

When Dynamic dispatch is intentional (e.g., a method that deliberately accepts any object), suppress the warning with @expect type on the preceding line:

typed Actor subclass: BankAccount
  process: handler =>
    @expect type
    handler doWork    // no warning — suppressed

@expect type suppresses all type-related warnings on the next expression, including type mismatches, does-not-understand hints, and Dynamic inference warnings. @expect all also works as a broader suppression.

Parametric Types — Generics (ADR 0068)

Beamtalk supports declaration-site parametric types (generics) with compile-time substitution. Type parameters use parenthesis syntax — Result(T, E) — keeping < reserved exclusively as a binary message (comparison operator). All generic type information is erased at runtime (zero cost).

Declaring a Generic Class

Classes declare type parameters in parentheses after the class name:

sealed Value subclass: Result(T, E)
  field: okValue :: T = nil
  field: errReason :: E = nil

  sealed unwrap -> T =>
    self.isOk ifTrue: [
      self.okValue
    ] ifFalse: [(Erlang beamtalk_result) unwrapError: self.errReason]

  sealed map: block :: Block(T, R) -> Result(R, E) =>
    self.isOk ifTrue: [Result ok: (block value: self.okValue)] ifFalse: [self]

  sealed andThen: block :: Block(T, Result(R, E)) -> Result(R, E) =>
    self.isOk ifTrue: [block value: self.okValue] ifFalse: [self]

Type parameters are bare uppercase identifiers (by convention single letters: T, E, K, V, R). They appear in:

• Field type annotations: field: okValue :: T
• Method parameter types: block :: Block(T, R)
• Method return types: -> T, -> Result(R, E)
• Nested generic types: Block(T, Result(R, E))

Using Generic Types

When using a generic class as a type annotation, concrete types replace the parameters:

// Annotating a variable
result :: Result(String, IOError) := File read: "config.json"
result unwrap    // Type checker knows: -> String

// Annotating a method parameter
processResult: r :: Result(Integer, Error) -> Integer =>
  r unwrap + 1   // r unwrap is Integer, Integer has '+'

// Annotating state
Actor subclass: Cache(K, V)
  state: store :: Dictionary(K, V) = Dictionary new

Type Inference Through Generics

The type checker performs positional substitution: when it encounters Result(String, IOError), it maps T -> String, E -> IOError, and substitutes through all method signatures:

r :: Result(Integer, Error) := computeSomething
r unwrap          // Return type T -> Integer
r map: [:v | v asString]   // Block param T -> Integer, return Result(String, Error)
r error           // Return type E -> Error

When concrete type parameters are unknown, they fall back to Dynamic:

r := someMethod        // someMethod returns bare Result (no type params)
r unwrap               // -> Dynamic (T is unknown)
r unwrap + 1           // No warning — Dynamic bypasses checking

Constructor Type Inference

For named constructors (ok:, error:, new), the compiler infers type parameters from the argument types:

r := Result ok: 42                  // Inferred: Result(Integer, Dynamic)
r unwrap                            // -> Integer

r2 := Result error: #file_not_found // Inferred: Result(Dynamic, Symbol)
r2 error                            // -> Symbol

Generic Inheritance

When a generic class extends another, the type parameter mapping must be explicit:

// Array passes its E to Collection's E
Collection(E) subclass: Array(E)

// IntArray fixes E to Integer
Collection(Integer) subclass: IntArray

// SortedArray passes E through
Array(E) subclass: SortedArray(E)

Block Type Parameters

Block(...) is special-cased — the last type parameter is always the return type:

• Block(R) — zero-argument block returning R
• Block(A, R) — one-argument block with arg type A, returning R
• Block(A, B, R) — two-argument block, returning R

Design Constraints

• Type erasure: All type information is compile-time only. Zero runtime cost.
• Warnings, not errors: Type mismatches produce warnings, never block compilation.
• Invariant type parameters: No covariance/contravariance in Stage 1 (added with protocols in Stage 2).
• Parenthesis syntax: Result(T, E) not Result<T, E> — keeps < as a pure binary message.

Dialyzer Spec Generation

Generic annotations generate expanded Dialyzer specs with concrete types at the BEAM interop boundary:

processResult: r :: Result(Integer, Error) -> Integer => r unwrap + 1

Generates:

-spec processResult(#{
  '__class__' := 'Elixir.Result',
  'okValue' := integer(),
  'errReason' := any()
}) -> integer().

Unresolved type parameters map to any() in Dialyzer specs.

Named type alias emission. When a module declares type aliases (ADR 0108), codegen emits matching named Erlang -type attributes into the compiled module. Method annotations referencing an alias name emit user_type references in their -spec attributes instead of any():

type Timeout = Integer | #infinity

Actor subclass: Worker
  run: t :: Timeout => // ...

Generates:

-type 'Timeout'() :: integer() | 'infinity'.
-spec run('Timeout'()) -> any().

(The bare ('Timeout'()) form omits the parameter name — both it and the named form (T :: 'Timeout'()) are valid Erlang specs; codegen emits the bare form, matching typical erlc output.)

Cross-package alias references (an annotation referencing an alias exported by a dependency) are not yet resolved in codegen — they still fall through to any().

REPL Type Display

The REPL displays generic type information when available:

> :help Result >> unwrap
unwrap -> T

When the workspace knows the concrete type parameters, :help substitutes them:

> r := Result ok: 42
> r unwrap
=> 42
// Type info: Integer (inferred from Result(Integer, Dynamic))

Structural Protocols (ADR 0068)

Protocols define named message sets. A class conforms to a protocol if it responds to all required messages — no implements: declaration needed. This is Smalltalk's duck-typing philosophy made explicit.

Defining a Protocol

Protocol define: Printable
  /// Return a human-readable string representation.
  asString -> String
  /// Return a developer-oriented representation (for debugging/REPL).
  printString -> String

Protocol define: Collection(E)
  /// The number of elements in this collection.
  size -> Integer

  /// Iterate over each element.
  do: block :: Block(E, Object)

  /// Transform each element, returning a new collection of the same kind.
  collect: block :: Block(E, Object) -> Self

  /// Return elements matching the predicate.
  select: block :: Block(E, Boolean) -> Self

Protocol bodies use class-body style — method signatures without => implementations. Doc comments are supported on each required method.

A protocol body may also carry provided methods — a signature with => and a body, flattened into every class that names the protocol in a uses: line. That is a trait, covered in full in § Traits below. The stdlib's own Comparable (stdlib/src/comparable.bt) is one: it requires only <, and provides >, <=, >=, between:and:, min:, max:.

Using Protocols as Types

Protocol names are used in type annotations the same way as class names — the compiler resolves the name and determines whether to perform nominal (class) or structural (protocol) checking:

// Structural/protocol type — Printable guarantees asString
display: thing :: Printable =>
  Transcript show: thing asString

// Generic protocol type
printAll: items :: Collection(Object) =>
  items do: [:each | Transcript show: each asString]

Automatic Conformance

Conformance is structural and automatic — no implements: declaration needed:

// String has asString -> conforms to Printable
// Integer has asString -> conforms to Printable
display: "hello"           // String conforms to Printable
display: 42                // Integer conforms to Printable
display: Counter spawn     // Counter conforms to Printable (inherited from Object)

Classes that override doesNotUnderstand: conform to every protocol (they can respond to any message).

Protocol Composition

// Require multiple protocols
sort: items :: Collection(Object) & Comparable => ...

// Protocol extending another
Protocol define: Sortable
  extending: Comparable
  /// The key used for sort ordering.
  sortKey -> Object

Class Method Requirements (BT-1611)

Protocols can require class-side methods using the class prefix, the same syntax as class definitions:

Protocol define: Serializable
  asString -> String
  class fromString: aString :: String -> Self

A class conforms to Serializable only if it has both the instance method asString and the class method fromString:. This is useful for factory methods, singleton patterns, and other class-level contracts.

Type Parameter Bounds

Type parameters can be bounded by protocols:

// T must conform to Printable
Actor subclass: Logger(T :: Printable)
  log: item :: T =>
    Transcript show: item asString    // Guaranteed by Printable bound

Runtime Protocol Queries

> Integer conformsTo: #Printable
=> true

> Integer conformsTo: #NonExistentProtocol
=> false

> Integer protocols
=> [#Printable, #Comparable]

> Protocol requiredMethods: #Printable
=> [#asString, #printString]

> Protocol conformingClasses: #Printable
=> [Integer, Float, String, Boolean, Symbol, Array, ...]

conformsTo: returns false for unknown or non-protocol names — a class cannot conform to something that is not a registered protocol.

Diagnostic Philosophy

Protocol conformance issues are warnings, never errors:

Traits (ADR 0127)

A trait is a Protocol define: body that carries at least one provided method — a signature with => and a body, alongside the protocol's ordinary required signatures (no =>). There is no separate Trait define: keyword; a trait is just a protocol with provisions, and it is used exactly like any other protocol.

// stdlib/src/comparable.bt
Protocol define: Comparable
  /// Required — the using class must implement this.
  < other :: Self -> Boolean

  // Provided — derived from `<`, flattened into every user.
  > other :: Self -> Boolean => other < self
  <= other :: Self -> Boolean => (other < self) not
  >= other :: Self -> Boolean => (self < other) not
  between: min :: Self and: max :: Self -> Boolean =>
    (self >= min) and: [self <= max]
  min: other :: Self -> Self => (self < other) ifTrue: [self] ifFalse: [other]
  max: other :: Self -> Self => (self < other) ifTrue: [other] ifFalse: [self]

A class receives a trait's provisions by naming it in a uses: line at the top of its body, immediately after the header and before any state:/ field:/classState: declaration or method:

sealed typed Value subclass: DateTime native: beamtalk_datetime
  uses: Comparable

  < other :: DateTime -> Boolean => self delegate
  // `>`, `<=`, `>=` stay hand-written (each its own FFI call) — DateTime's
  // own methods win over Comparable's provisions (see Precedence below).
  // Gained from Comparable: `between:and:`, `min:`, `max:`.

Self in a trait's signature is substituted with the using class at flattening time, so Comparable>>max: other :: Self -> Self becomes DateTime>>max: other :: DateTime -> DateTime on DateTime — exactly the signature a hand-written method would declare.

Composing more than one trait, and excluding:/overriding:

The full grammar of a uses: line:

uses: [package@]ProtocolName[(TypeArgs)] [excluding: #(#sel, …)] [overriding: #(#sel, …)]

A bare uses: ProtocolName resolves by first-definition-wins across all dependencies. A qualified uses: pkg@ProtocolName resolves only against that package's protocols, so two dependencies that each export a same-named protocol can be composed without ambiguity.

One trait per uses: line — several traits are several lines:

typed Actor subclass: WorkerPool
  uses: Enumerable(Worker)
  state: workers :: List(Worker) = #()

  elements -> List(Worker) => self.workers

excluding: drops one or more of a trait's provisions (Pharo's -), keeping the class's own or inherited version instead:

typed Value subclass: SupervisionTree
  // This class's own `do:` answers `self` (chainable), not `Nil` —
  // `Enumerable`'s provision is dropped before it can conflict.
  uses: Enumerable(SupervisionNode) excluding: #(#do:)

overriding: acknowledges that a trait's provision replaces a method the class would otherwise inherit from its superclass — required because a trait provision never silently overrides an inherited method:

Record subclass: AuditRecord
  uses: Describable overriding: #(#printString)

Leaving out overriding: there is a compile error naming both sides and both fixes:

error: Describable provides `printString`, which AuditRecord would otherwise
       inherit from Record.
  hint: to use Describable's version, write
          uses: Describable overriding: #(#printString)
        to keep Record's version, write
          uses: Describable excluding: #(#printString)

printString and displayString inherited from Object/Value are exempt (they're cosmetic defaults every class is expected to replace); every other inherited selector — including equals:/hash — needs overriding:.

Two traits providing the same selector to one class is a compile error unless the class defines that selector itself or one uses: line excludes it:

Value subclass: Report
  uses: Labelled
  uses: Describable
  // error: `printString` is provided by both Labelled and Describable in Report.
  //   Define `printString` in Report, or exclude one:
  //     uses: Describable excluding: #(#printString)

Precedence

Flattening applies, highest precedence first: class body → trait provision → inherited. A class's own method always wins over a trait's provision, and a trait's provision — once acknowledged where needed (overriding: above) — wins over what the class would otherwise inherit. This is exactly what a hand-written method in the class body would mean; after flattening, there is nothing trait-shaped left for the type checker, dispatch, super, or hot reload to know about.

Requirements

Every required selector of a used trait must resolve on the class — from the class body, another used trait's provisions, or the superclass chain — or it's a compile error naming the missing selector:

Value subclass: Version
  uses: Comparable
  field: major = 0
// error: Version uses Comparable but does not implement required `<`
//   hint: Comparable requires `< other :: Self -> Boolean`

uses: on a protocol with no provisions is a hint, not an error or warning — it only checks the protocol's requirements at the class definition ("assert conformance here"); conformance itself stays structural (ADR 0068).

Which mechanism to use

Beamtalk has three ways to share behaviour, and each answers a different question:

A superclass spends the class's one superclass slot and claims a kinship ("DateTime is-a Magnitude") that may not be true — DateTime, a Duration, and a Uuid share only that they can be ordered, not what they are. A protocol with provisions gives capabilities their own home and works across the class-kind wall (an Actor can use a trait a Value also uses, Enumerable above being one). Reach for an extension method only for a single class, typically one you don't own — it isn't reusable the way a trait is (two extensions repeating the same body on two classes is exactly the duplication traits remove).

Traits across the class kinds

An Actor wanting enumeration over what it holds needs its trait's provisions to work by snapshot, not an internal iterator — a block passed through a self-send to an actor loses ^ and captured-local writes (BT-3580). Enumerable(E) (stdlib/src/enumerable.bt) is written this way: its one requirement is elements -> List(E), and every provision (size, isEmpty, isNotEmpty, do:, inject:into:, select:, collect:, detect:ifNone:, anySatisfy:, count:) forwards to the matching List primitive over that snapshot — no block ever crosses a self-send, so every provision runs in the caller's process regardless of whether the receiver is a Value or an Actor.

Collection does not uses: Enumerable itself (its own select:/ collect: already answer Self via the species pattern, richer than Enumerable's plain List(E)), but gains elements -> List(E) => self asList so every List, Set, Array, … conforms to Enumerable structurally, with no uses: needed.

Provisions are instance-side only in v1 (class sel … => in a protocol is rejected). An Object subclass: (no instances) that composes a trait is not an error, but gets nothing useful from it: the provisions flatten onto a class that will never be instantiated. Class-side provisions are a post-v1 item, tracked in BT-3595.

Reflection

DateTime usedProtocols                        // => [#Comparable]
DateTime usesProtocol: #Comparable             // => true
DateTime usesProtocol: #Printable              // => false
Protocol providedMethods: #Comparable          // => [#between:and:, #min:, #max:, #>, #<=, #>=]
Protocol usersOf: #Comparable                  // => [DateTime, Duration, Uuid, String]
(DateTime >> #between:and:) origin             // => Comparable
(DateTime >> #<) origin                        // => nil  (class's own method)

usedProtocols is distinct from protocols (ADR 0068's structural conformance query, § Runtime Protocol Queries above): a class can structurally conform to a protocol it never uses:, and usedProtocols answers only what it actually composes via uses:. allUsedProtocols walks the superclass chain too. CompiledMethod >> origin names the protocol a method was flattened from, or nil for a method the class wrote itself.

Editing a loaded protocol file's provisions and reloading it (ProtocolName reload / :reload ProtocolName) atomically recompiles and hot-swaps every loaded, source-backed user together — all-or-nothing: if any user's recompile fails against the edited protocol, nothing installs and the error names the failing user (ADR 0127 §11).

At the REPL, Describable >> summary => … adds or replaces a provision in the protocol's own source, and Describable removeSelector: #summary removes one. Both run through the same all-or-nothing re-expansion of every user, are recorded in the ChangeLog against the protocol (so Workspace flush writes the protocol file), and are refused for stdlib protocols. This is a live-image edit only: put a provision in a .bt file by writing it inside the Protocol define: body.

Two-Protocol String Model (Debug / Display)

Beamtalk follows a two-string-protocol model (ADR 0094), mirroring Rust's Debug / Display split:

• printString = Debug. The self-describing, structural representation used by the REPL, logs, and any other printString that nests this object. It is the REPL default — evaluating an expression shows its printString. It is derived by default, so you rarely override it.
• displayString = Display. The human-facing representation. It is the hook the language pulls during string interpolation — every {...} segment renders its value via displayString. It defaults to printString; you override it when a value has a natural human form (e.g. Money → $10.50).
• inspect is the navigable-inspector verb (ADR 0095): anObject inspect opens an Inspector cursor (Inspector on: self), not a string. The cursor drills into fields (at:/fields/path), refreshes a snapshot, renders a printString text tree, and serialises to the MCP/browser wire form (asDictionaries/asDictionary). For the structural Debug string — formerly the inspect result — use printString. (Repurposed in ADR 0095 Phase 3, BT-2504; the redesign ADR 0094 deferred.)

String demonstrates the Debug/Display split directly: "hi" printString → "\"hi\"" (quoted, Debug) while "hi" displayString → hi (plain, Display).

Default printString forms by class kind

The a/an article prefix (the old a Point / ungrammatical a Integer default) is removed entirely. The default printString now takes one of four visually distinct forms, one per kind of thing:

Value forms carry field: labels while process forms are positional; the process heads (Actor / Supervisor / DynamicSupervisor) are reserved kind words no user Value class may shadow, so the two shapes are unambiguous. Raw platform primitives (Pid, Port, Reference, Tuple) keep their Erlang-native #Pid<…> / #Port<…> rendering — they are Erlang terms.

Nested Value fields expand recursively (so Line(from: Point(x: 0, y: 0), to: Point(x: 3, y: 4)) shows in full), each rendered via its own printString (Debug form — strings stay quoted), bounded by depth (default 5), width, and total-length caps with a cycle guard; truncated positions render as ....

Printable Protocol and Display Methods

The Printable protocol is the standard contract for objects that can represent themselves as strings. It requires two methods:

• asString — a human-readable representation (for end-user display)
• printString — a developer-oriented (Debug) representation (for debugging, logging, and REPL display)

Most stdlib classes conform automatically because Object provides a default printString (the bare class name, or the structural ClassName(field: value, ...) form for Value subclasses) and most subclasses implement asString. Custom classes only need to implement these two methods to conform:

Value subclass: Point
  field: x = 0
  field: y = 0

  // Human-readable
  asString -> String => "({self.x}, {self.y})"

  // Developer-readable (REPL display)
  printString -> String => "Point({self.x}, {self.y})"

displayString is not part of Printable (deferred per ADR 0094 §5), and inspect is not part of any protocol — so the two-protocol changes leave protocol conformance unaffected.

The related display methods on Object are:

show: and showCr: are convenience methods on Object that delegate to the Transcript class-side facade (ADR 0129). Inside an interactive workspace the output goes to the REPL's transcript; everywhere else (beamtalk run, beamtalk test, releases) it is one plain Logger notice per call in the [beamtalk, user, transcript] domain, so they are always safe to call and return self. Programs should prefer Logger or Console; Transcript recent and Transcript clear are workspace-only and raise no_workspace elsewhere:

// Cascaded output
Transcript show: "Hello"; cr; show: "World"

// show:/showCr: on any object — nil-safe
42 show: "value: "
42 showCr: "hello world"

Transcript show: accepts any Printable value, so custom classes that conform to Printable work directly with Transcript show: without manual asString conversion.

Navigable Inspector (ADR 0095)

printString renders an object to one string. The Inspector lets you navigate into it — drill through fields, render across surfaces (REPL text tree, MCP/browser wire form), and re-snapshot live actor state. anObject inspect is the shorthand for Inspector on: anObject; it returns a cursor, not a string.

i := (Point x: 3 y: 4) inspect      // an Inspector cursor (#value kind)
i fields                            // the drillable InspectorField records (x, y)
i at: #x                            // Result(Inspector) — a child cursor on the value 3
(i at: #x) unwrap subject           // => 3
i printString                       // an indented text tree (Inspector(Point) + fields)

One polymorphic class, four kinds. A single Inspector carries a kind tag rather than a subclass per kind — classification lives in the runtime shim:

A wedged, dead, or non-sys actor degrades to a single #status: #unavailable field — it never crashes.

Navigation is immutable. Every navigation message returns a new cursor, so a UI can hold several at once:

Each InspectorField is an immutable Value record with name (the navigation key), label, value, kind, and drillable (isLeaf is its negation).

evaluate: is values-only. On a #value cursor, i evaluate: "self x + self y" compiles and runs the expression with self bound to the inspected value, returning a Result — failures are Result error:, never a raise. The one exception is a ^ (non-local return) from a block captured elsewhere and run by the expression: it is control flow, not a failure, so evaluate: re-raises it to its home method (BT-3735). Class-variable writes made before the ^ are kept, as for any ^ that crosses a protected region (ADR 0130 §4); an error exit still discards them. If the home method has already returned (a stale ^), nothing catches it and the enclosing eval/dispatch boundary reports it as a structured error. On an #actor cursor it returns Result error: with kind #actor_eval_unsupported (actor evaluate-in-context is a deferred §7 follow-up). Live updates are poll-only: re-issue refresh.

i := (Point x: 3 y: 4) inspect
(i evaluate: "self x * 10") unwrap        // => 30
(i evaluate: "self nonesuch") isError     // => true  (a Result error:, not a crash)

Deferred §7 seams (not in v1): actor evaluate-in-context (live routing), per-class inspectorFields custom views, sealedFromInspection, and push live updates (poll-only for now).

Union Types and Narrowing (ADR 0068)

Union Types

Union types express that a value may be one of several types:

// All members must respond to the message
x :: Integer | String := getValue
x asString             // Both Integer and String have asString
x size                 // Warning: Integer does not respond to 'size'
x + 1                  // Warning: String does not respond to '+'

The nullable pattern (String | nil) is the most common union — Beamtalk's Option/Maybe type:

name :: String | nil := dictionary at: "name"
name size              // Warning: Nil does not respond to 'size'

Similarly, false in type position resolves to False — used for Erlang FFI patterns:

entry :: Tuple | false := ErlangLists keyfind: key

Singleton members. Singleton symbol types (#foo, a subtype of Symbol) may appear in any type position — including unions — to express a closed set of atom values:

// a parameter that is an Integer or the sentinel #infinity
withTimeout: ms :: Integer | #infinity => ...

// a closed enum of singletons
restart: policy :: #temporary | #transient | #permanent => ...

A singleton receiver resolves methods against Symbol's protocol — #infinity asString infers String, and an unknown selector produces a DNU hint naming the singleton (e.g. #infinity does not understand 'frobnicate'). Equality comparisons (=:=, ==, /=, =/=) are excluded from this redirect so statically-decidable comparison hints still fire.

Discriminate a singleton union with =:= (identity) and the branches narrow — see Control Flow Narrowing.

Difference and Intersection Types (\ / &)

Beyond | (union), type annotations support two more set-theoretic operators (ADR 0102):

• \ (difference) — "T without U". Written Base \ Excluded, it expresses a co-finite set: every value of Base except the named ones. Today this is only meaningful for symbol singletons subtracted from Symbol (or from a smaller \-chain) — nominal-class difference (e.g. Object \ Number) is not yet defined.
• & (intersection) — the general form of the class/protocol composition ADR 0068 already specified (Collection(Object) & Comparable). Class ∩ class reduces via the hierarchy (the narrower class, or Never for unrelated sealed classes); class ∩ protocol is the interesting, irreducible case.

// "any Symbol except #north" — a co-finite atom set
tag :: Symbol \ #north := #south

// chained difference — left-associative, same as subtracting a union:
// equivalent to "any Symbol except {#north, #south}"
heading :: Symbol \ #north \ #south := #east

// union binds looser than difference: `Integer | Symbol \ #foo` is
// `Integer | (Symbol \ #foo)`, not `(Integer | Symbol) \ #foo`
withSentinel: ms :: Integer | Symbol \ #infinity => ...

// intersection: class ∩ protocol (ADR 0068's operator, now general)
describe: value :: Integer & Printable -> String => value asString

// chained intersection — left-associative, same tier as `\`
requires: value :: A & B & C => ...

Precedence (lowest-binding to highest), all only inside a type annotation — & and \ remain ordinary binary message selectors in value position, unaffected:

So Integer | Symbol \ #foo parses as Integer | (Symbol \ #foo) — \ binds tighter than |. Within one operator, chains are left-associative: Symbol \ #a \ #b parses as (Symbol \ #a) \ #b, and A & B & C parses as (A & B) & C.

Grouping parentheses. (...) is a grouping operator inside a type annotation, just as in value expressions (in addition to its generic-argument use, Result(T, E)). A group wraps any annotation — unions, &/\ chains, generics — and groups nest. Grouping is purely syntactic: the parenthesised annotation is the same annotation, so (Integer) means Integer, and (A | B) | C is the same flat three-member union as A | B | C.

// subtract a whole union in one step — equivalent to the chain
// `Symbol \ #a \ #b`, which the algebra normalises to the same result
tag :: Symbol \ (#a | #b) := #c

// a grouped difference as a union member (parens redundant here — `\`
// already binds tighter than `|` — but allowed)
withSentinel: ms :: Integer | (Symbol \ #infinity) => ...

Grouping is also how you mix & and \ in one annotation: mixing them in the same chain without parentheses is a deliberate parse error, not a left-associative fallback — A & B \ #c is rejected with "Cannot mix & and \ in a type annotation without parentheses; parenthesise to disambiguate", because (A & B) \ #c and A & (B \ #c) differ and neither reading is obviously the intended one. Parenthesise the reading you mean:

// intersect first, then subtract
narrow -> (A & B) \ #c => ...

// subtract first, then intersect
narrow -> A & (B \ #c) => ...

The lexer also greedily merges \\ (two backslashes) into the Smalltalk modulo selector, so a doubled backslash in type position — the natural typo for \ — gets a targeted diagnostic ("did you mean \?") instead of a confusing generic parse error.

Difference types show up in Control Flow Narrowing too: the false branch of a singleton equality test (x =:= #foo) narrows x to Symbol \ #foo, and hover displays that co-finite type directly.

Named Type Aliases (type Declarations) (ADR 0108)

A type declaration names an existing type annotation for reuse across signatures:

/// How a supervised child restarts after exit.
type RestartStrategy = #temporary | #transient | #permanent

type OptionalString = String | Nil
type JsonKey = String | Symbol
type Timeout = Integer | #infinity
type PublicTag = Symbol \ (#reserved | #internal)
type PrintableInt = Integer & Printable

Transparent, not nominal. RestartStrategy and #temporary | #transient | #permanent are the same type — a reference to the alias expands to its right-hand-side annotation everywhere type annotations are resolved: parameter types, return types, typed locals, both sides of |/\/&, narrowing, and match:/matchExhaustive: exhaustiveness. Two aliases with the same expansion are interchangeable, and there is no runtime tag distinguishing them — a RestartStrategy value is the atom temporary, exactly the value a hand-written union annotation would carry. A type declaration is erased entirely at compile time: no BEAM module, no runtime object, no live process.

type Direction = #north | #south | #east | #west

Object subclass: Compass
  heading: h :: Direction =>
    h matchExhaustive: [
      #north -> 0;
      #south -> 180;
      #east  -> 90;
      #west  -> 270
    ]

  defaultHeading -> Direction => #north

type is a contextual keyword. It is recognized only at top-level declaration position via a three-token lookahead (type + uppercase identifier + =). It remains a legal identifier everywhere else — type := 5, foo type, type printString are all unaffected.

Exhaustiveness is inherited, not new. Because an alias reference expands to its structural annotation before any checker runs, the advisory match: warning and asserted matchExhaustive: error apply exactly as they would to the spelled-out union — no new exhaustiveness machinery. Adding a member to the alias declaration makes every matchExhaustive: over it non-exhaustive in one edit:

heading match: [
  #north -> 0;
  #south -> 180;
  #east  -> 90
]
// ⚠ Warning: non-exhaustive match: `#west` is not handled (residual type: `#west`)

heading matchExhaustive: [
  #north -> 0;
  #south -> 180;
  #east  -> 90
]
// ⛔ Error: non-exhaustive matchExhaustive: `#west` is not handled (residual type: `#west`)

A value outside the named union is flagged the same way an inline union would be:

p :: RestartStrategy := #premanent
// ⚠ Warning: Type mismatch: declared as RestartStrategy
//    (#temporary | #transient | #permanent), got #premanent

Exported by default, like classes and protocols. A type declaration is visible to any package that depends on the declaring one, unless marked internal:

internal type ParserState = Integer | String

An internal alias is package-private, following the same model as class- and method-level internal (ADR 0071): usable within the declaring package, a compile error to reference from outside it. Because aliases are transparent, referencing an internal alias from a public signature is also a compile error even within the same package (the same "leaked visibility" rule 0071 already applies to internal classes) — and so is reaching one through the expansion of a public alias, since a public alias has no "internal signature" escape hatch of its own:

internal type Priv = Integer
type Pub = Priv | String
// ⛔ Error: Internal type alias 'Priv' appears in the expansion of
//    public type alias 'Pub'

Constraints:

• Single-letter names are rejected at parse time — reserved for ADR 0068's implicit method-local type parameters: type T = Integer | Nil is a declaration error.
• Alias names share the class/protocol namespace: declaring an alias with the same name as an existing class or protocol (or vice versa) is a compile error.
• The RHS accepts any type annotation: unions (|), singletons (#foo), generics (List(Integer)), difference (\), intersection (&), and combinations of these.
• Aliases may reference other aliases; a reference cycle — including self-reference and cycles that span multiple files — is a compile error at declaration time (type Ab = Bc | Integer / type Bc = Ab | Symbol → type alias cycle: 'Ab' → 'Bc' → 'Ab'). Cross-file cycles (where each half of the cycle is declared in a separate file) are detected when pre-loaded aliases are merged with module-local aliases.
• Parametric aliases (type Option(T) = T | Nil) and recursive aliases (type JsonValue = ... | List(JsonValue)) are not yet supported — both need deferred (lazy) resolution in place of the eager expansion aliases use today. type Name(...) = ... is reserved syntax for the future parametric form.
• Doc comments (///) above a type declaration are preserved and shown by :help <Alias> and LSP hover.

Erlang interop. Codegen emits a named Erlang -type attribute for each alias declared in a module, and method -spec attributes reference it via user_type instead of expanding to any(). Erlang/Elixir consumers of a compiled Beamtalk module see idiomatic Dialyzer types (e.g. -type 'Timeout'() :: integer() | 'infinity'.). See Dialyzer Spec Generation for details.

Tooling. The LSP offers completions, go-to-definition, find-references, and hover for alias names in .bt files. In the REPL, type declarations are accepted as input and persist for the rest of the session; declaring type Direction = ... at the prompt echoes the declared name (=> Direction), the same convention a class declaration echoes (Actor subclass: Counter → Counter); :help <Alias> renders the declaration, its expansion, and any doc comment. Stdlib-declared type aliases (e.g. RestartStrategy, Timeout) are available automatically in a fresh REPL session — :: typed locals referencing them resolve without a prior declaration, and :help RestartStrategy shows Declared in: stdlib. A session-declared type with the same name shadows the stdlib alias. The System Browser and the VS Code Workspace Explorer sidebar list declared aliases in a "Type Aliases" section alongside Classes and Protocols. See docs/development/surface-parity.md for the full cross-surface matrix.

Control Flow Narrowing

When the type checker recognises a type-testing pattern followed by ifTrue: / ifFalse:, it narrows the variable's type inside the block scope:

// class identity check — narrows to exact class
process: x :: Object =>
  x class =:= Integer ifTrue: [
    x + 1          // x is Integer here — has '+'
  ]
  x + 1            // x is Object here — no narrowing outside the block

// kind check — narrows to class including subclasses
process: x :: Object =>
  x isKindOf: Number ifTrue: [
    x abs           // x is Number here
  ]

// early return narrows the rest of the method
validate: x :: Object =>
  x isNil ifTrue: [^nil]
  x doSomething    // x is non-nil for the remainder

// isKindOf: guard-and-return also narrows the rest of the method (BT-2825)
render: coll :: Printable | Nil -> String =>
  coll isNil ifTrue: [^""]
  (coll isKindOf: List) ifFalse: [^""]
  items :: List := coll   // no `@expect type` needed — coll is List here
  items inject: "" into: [:acc :item | acc ++ item asString]

Supported narrowing patterns:

The diverging-guard pattern (isNil ifTrue: [self error: "..."]) recognises any block whose body infers as Never — including calls to error:, notImplemented, or any -> Never method — not just non-local returns (^). Narrowing also works on self.field reads: inside self.field isNil ifFalse: [...], the field narrows to non-nil within the block.

notNil and: (BT-2872): x notNil and: [...] narrows x to non-nil for the whole block argument — not just where x is a further send's receiver, but in any nested position, including as an argument to a binary send inside a further-nested block (local notNil and: [local > 0 and: [5 >= local]] narrows local inside 5 >= local too). The narrowing does not survive past the block — a later unguarded use of x after the and: send is unaffected.

isKindOf: guard-and-return (BT-2825): the same diverging-guard treatment isNil gets also applies to isKindOf: — (x isKindOf: Foo) ifFalse: [^default] proves x is Foo for the rest of the method, and (x isKindOf: Foo) ifTrue: [^default] proves x is T \ Foo. This also closes a related gap: when x's declared type is a Protocol (e.g. Printable) and Foo is a concrete class, the narrowed type collapses to the bare Foo — a runtime isKindOf: Foo check is a stronger proof than the protocol annotation, so the narrowed value is assignable to a Foo-typed local without an @expect type escape hatch.

Singleton-equality guard-and-return (BT-3369): the same diverging-guard treatment extends to singleton-equality checks — x == #undefined ifTrue: [^false] proves x is not #undefined for the rest of the method, narrowing to T \ #undefined. Both == and =:= are accepted (they are provably equivalent for atom/symbol comparisons). respondsTo: guards also carry forward: (x respondsTo: #foo) ifFalse: [^default] narrows x post-guard.

Conditional Return Type Inference

ifTrue:ifFalse: on Boolean (and True/False) is declared as Block(R), Block(R) -> R — the type checker unifies both arms to a common return type. The result of a conditional expression is now statically typed rather than Dynamic:

x := condition ifTrue: [42] ifFalse: [0]
// x is inferred as Integer (not Dynamic)

result isOk ifTrue: [result unwrap] ifFalse: [default]
// inferred as the common type of both arms

The solo forms — ifTrue: [...] and ifFalse: [...] — can't unify to a bare R the way the two-armed form does: Boolean>>ifTrue:/ifFalse: are deliberately declared with no return type, because on an unnarrowed Boolean receiver the checker can't statically prove whether True or False handles the send, and the sibling override (e.g. False>>ifTrue:) never invokes the block — it returns self instead. Rather than collapsing all the way to Dynamic, a solo send infers the union of that Boolean self-branch and the block's own return type (BT-2868):

flag :: Boolean := x > y
flag ifTrue: [1]
// inferred as Boolean | Integer, not Dynamic

flag ifFalse: ["no"]
// inferred as Boolean | String

A receiver already narrowed to exactly True or False (e.g. inside an x isKindOf:-style guard, or after control-flow narrowing) is unaffected — True>>ifTrue:/False>>ifFalse: declare concrete -> R return types and resolve normally, without the extra Boolean union member.

ifNil:ifNotNil: (and ifNotNil:ifNil:) on nullable receivers also infers a branch-union return type — typeof(nilBranch) | typeof(notNilBranch). A branch containing a non-local return (^) contributes Never, leaving only the surviving branch's type:

name :: String | nil := dictionary at: "name"
result := name ifNil: ["unknown"] ifNotNil: [:n | n size]
// result is inferred as String | Integer

value := name ifNil: [^nil] ifNotNil: [:n | n]
// value is inferred as String (nil branch contributes Never, skipped)

The solo forms — ifNil: [...] and ifNotNil: [:v | ...] — infer the same way, unioning the block's return type with the "self" branch (executed when the nil-check doesn't match):

name :: String | nil := dictionary at: "name"
name ifNil: ["unknown"]
// inferred as String (T | R, where T = String and R = String both dedup)

count :: Integer | nil := dictionary at: "count"
count ifNil: ["none"]
// inferred as Integer | String (T | R)

name ifNotNil: [:n | n size]
// inferred as Integer | Nil (R | Nil)

Union + Narrowing Compose

name :: String | nil := dictionary at: "name"
name isNil ifTrue: [^"unknown"]
name size              // name is narrowed to String — nil eliminated by early return

Control Flow and Mutations

Beamtalk supports Smalltalk-style control flow via messages to booleans and blocks, with full mutation support via a universal state-threading protocol (ADR 0041).

How It Works

The compiler uses a two-tier optimization for block mutations:

• Tier 1 (stdlib control flow): whileTrue:, do:, collect:, timesRepeat:, etc. — inlined tail-recursive loops with versioned state variables. Zero overhead.
• Tier 2 (user-defined methods): All other methods accepting blocks — universal {Result, StateAcc} protocol. Pure blocks have no overhead; stateful blocks pay ~65ns per invocation.

Local variable mutations work in the blocks of control-flow messages (the table below, conditionals, on:do:/ensure:), and, in a few top-level shapes of an actor instance method, in stored closures and blocks passed to the actor's own methods. Anywhere else there is no way for the callee to hand the write back, and the compiler rejects it (see What Works and What Doesn't). Field mutations (self.x :=) require control-flow context and are a compile error in stored closures.

Control Flow Constructs

These message sends are Tier 1 optimized — the compiler generates inlined tail-recursive loops with zero overhead:

Local Variable Mutations

// Simple counter
count := 0
[count < 10] whileTrue: [count := count + 1]
// count is now 10

// Multiple variables
sum := 0
product := 1
i := 1
[i <= 5] whileTrue: [
    sum := sum + i
    product := product * i
    i := i + 1
]
// sum = 15, product = 120, i = 6

// Collection iteration
numbers := #(1, 2, 3, 4, 5)
total := 0
numbers do: [:n | total := total + n]
// total = 15

// With index
result := 0
1 to: 10 do: [:n | result := result + n]
// result = 55 (sum of 1..10)

Field Mutations

Mutations to actor state (self.field) work the same way:

Actor subclass: Counter
  state: value = 0
  state: count = 0

  // Field mutation in control flow
  increment =>
    [self.value < 10] whileTrue: [
      self.value := self.value + 1
    ]
    self.value

  // Multiple fields
  incrementBoth =>
    [self.value < 10] whileTrue: [
      self.value := self.value + 1
      self.count := self.count + 1
    ]

Mixed Mutations

Local variables and fields can be mutated together:

processItems =>
    total := 0
    self.processed := 0
    
    self.items do: [:item |
        total := total + item
        self.processed := self.processed + 1
    ]
    
    ^total

What Works and What Doesn't

A block that writes an outer local needs a way back (ADR 0131 §6). A block literal that assigns a local of the enclosing method (a Tier 2 block value, ADR 0041), or a local bound to such a block and never reassigned, may only be used where its write can be threaded back: as the block of a control-flow message (whileTrue:, do:, inject:into:, the conditionals, on:do:/ensure:, Result tryDo:, [...] value), or, in an actor instance method at the top level of the method body, as a bare [...] argument of a plain self send (not super, not a cascade) whose block reads every outer local it writes, or as a stored block (bound by a method-body statement) sent value in method-body statements only. Passing it to any other send (a user-defined higher-order method, at:ifAbsent:, a class-side self send) or sending a stored one value in a class or value-type method is a compile error, because no callee can return the write. An Erlang FFI argument is exempt: it is lossy by design and codegen warns (ADR 0041 §Erlang Interop Boundary).

error: block writes outer local `count`, but `ap:` cannot return the write
  = help: return the new value from the block and assign it: `count := ... ap: [... count + 1]`,
          or use a control-flow message (`do:`, `inject:into:`, `on:do:`) that threads locals

// ❌ ERROR (class or value-type method): `ap:` cannot return the write
count := 0
CvA ap: [count := count + 1]

// ✅ Return the value instead
count := CvA ap: [count + 1]

// ✅ Or use a control-flow message that threads locals
10 timesRepeat: [count := count + 1]

Until ADR 0131's later phases make every local-threading construct thread its writes in every position, a construct whose blocks write an outer local is also rejected outside the positions that work today, with an error naming the construct, the position and BT-3743 (for example (items collect: [:x | count := count + x]) size in a class method). As a statement it is accepted unless it is one of the statement shapes that lose the write today (BT-3753): most constructs nested in a conditional arm, a protected body or a loop body of a class or value-type method (for example flag ifTrue: [items do: [:x | count := count + x]]), eachWithIndex:, do:separatedBy:, keysAndValuesDo:, ifNil:, and:/or: and anySatisfy: statements in class and value-type methods (and [...] value in a class method), a detect:ifNone: statement whose ifNone: block writes, and a construct nested two blocks deep in an actor method. r := <construct> is accepted wherever it threads correctly.

Field mutations (self.x :=) require control-flow context and are a compile error in stored closures:

// ❌ ERROR: Field assignment in stored closure
badBlock =>
    myBlock := [self.value := self.value + 1]
    // ERROR: Cannot assign to field 'value' inside a stored closure.

// ✅ CORRECT: Field mutation in control flow
increment =>
    10 timesRepeat: [self.value := self.value + 1]  // ✅ Works!

Why This Design?

Error Messages

When you accidentally assign to a field inside a stored closure, the compiler provides guidance:

// This won't compile — stored closure can't mutate fields
myBlock := [:item | self.sum := self.sum + item]
items do: myBlock

Error: Cannot assign to field 'sum' inside a stored closure.

Field assignments require immediate execution context for state threading.

Fix: Extract the mutation into a method:
  // Instead of:
  myBlock := [:item | self.sum := self.sum + item].
  items do: myBlock.

  // Use a method:
  addToSum: item => self.sum := self.sum + item.
  items do: [:item | self addToSum: item].

The addTo{Field}: method fix is offered because it's the only rewrite that's valid everywhere this diagnostic fires — writing the block inline (items do: [:item | self.sum := self.sum + item]) only threads correctly for an Actor subclass: method. The identical inline rewrite is itself rejected in a Value subclass: or class method, so it isn't offered as a fix here.

Actor Message Passing

Beamtalk uses sync-by-default actor message passing (ADR 0043). The . message send operator uses gen_server:call, which blocks the caller until the actor processes the message and returns a value. This is the same natural synchronous feel as Smalltalk, while preserving full process isolation and fault tolerance.

Default: Sync with Direct Return

// Load the Counter actor
:load examples/counter.bt

// Spawn an actor — returns a reference
c := Counter spawn

// Messages to actors return values directly
c increment             // => 1
c increment             // => 2
c getValue              // => 2

REPL and Compiled Code

Actor sends behave identically in REPL and compiled code — both return values directly:

> c := Counter spawn
Actor(Counter, _)

> c increment
1

> c increment
2

> c getValue
2

Explicit Async Cast (!)

For fire-and-forget scenarios, use the ! (bang) operator, which uses gen_server:cast and returns nil immediately:

// Fire-and-forget — does not block, returns nil
c increment!

The ! is postfix — it terminates the send it applies to. A cast is only legal as a bare statement: using its (always-nil) value in an assignment, return, or argument is a parse error (cast_in_expression_error).

Use ! when you intentionally don't need the result and don't want to block.

Deadlock Prevention

Because . sends block the caller (gen_server:call), two actors calling each other creates a deadlock. The default timeout is 5000ms, after which a #timeout error is raised:

// DeadlockA calls DeadlockB, which calls DeadlockA — timeout after 5s
self should: [a callPeer] raise: #timeout

Design actor interactions to avoid circular synchronous calls. Use ! (cast) when an actor needs to notify another without expecting a response.

Custom Timeouts

The default . send timeout is 5000ms. For actors that may take longer (database queries, HTTP calls), use withTimeout: to create a timeout proxy:

// Wrap an actor with a custom timeout (milliseconds)
slowDb := db withTimeout: 30000
slowDb query: sql              // forwarded with 30s timeout
slowDb stop                    // stop the proxy when done

// Infinite timeout (use with care — blocks indefinitely)
infDb := db withTimeout: #infinity
infDb query: sql
infDb stop

withTimeout: returns a TimeoutProxy — a lightweight actor that forwards ordinary messages to the target via doesNotUnderstand:args: using the specified timeout. Lifecycle messages such as stop apply to the proxy itself, not the target. This is pure message passing with no special syntax or reserved keywords.

Lifecycle: The proxy is a separate actor process. Capture the reference and call stop when finished to avoid leaking processes.

Static Typing of Actor Protocols (ADR 0104)

An Actor subclass:'s public method set is its message protocol — the checker types actor sends exactly as ordinary method sends, with no parallel channel type and no new syntax. Four typing rules apply (all advisory per ADR 0100, and static-only — no runtime, codegen, or wire change):

1. A sync send types as the method's return. c increment on a Counter whose increment declares (or infers) -> Integer types as Integer, and forwards its declared/inferred return to callers:

   c := Counter spawn
   c increment          // :: Integer — the method's declared/inferred return
   

2. A bare cast (!) types as Nil. The fire-and-forget gen_server:cast has no synchronous reply, so a cast statement evaluates to Nil regardless of the target method's return type. (Using a cast's value in an assignment, return, or argument is already a parse error — see Explicit Async Cast above). One consequence: a method declaring a non-Nil return whose body ends in a bare cast now warns "body returns Nil" — usually a genuine bug where a mutator returns nothing:

   c increment!         // :: Nil — no reply is awaited
   
   // ⚠️ Method 'bump' declares return type Integer, but body returns Nil
   bump -> Integer => c increment!
   

3. spawnWith: keys are checked against state: slots. The keys of a literal init-state map are validated against the actor's declared state: slots; an unknown key is a Warning (a provably-failing construction, not merely an unresolved selector) with a typo suggestion naming the nearest slot. When a slot is typed, the literal value's type is checked against it too:

   Counter spawnWith: #{#count => 0}     // :: Counter — key `count` is a declared slot
   Counter spawnWith: #{#cuont => 0}     // ⚠️ unknown state key `cuont` — did you mean `count`?
   

   Only a literal map is inspected; a spawnWith: argument flowing in through a variable is not key-checked. The rule fires only for Actor subclass: receivers.

   Supplying a late slot by key counts as assigned. spawn's init/1 merges the declared defaults with the caller's map, caller winning, so CodexClient spawnWith: #{#proc => aFakeSubprocess} puts proc in the state map even though it is declared late — this is legitimate dependency injection (substituting a value for a slot normally acquired by a lifecycle call), not a violation of late's "absent until assigned" contract, and it also satisfies the Definite Assignment construction-site check the same way supplying any other unassigned slot does. See late Slots above.

4. withTimeout: is transparent; cross-process DNU grades like a local send. withTimeout: returns a value typed as the wrapped actor (not the opaque TimeoutProxy), so forwarded calls resolve the wrapped class's real return types. A timeout raises rather than returning, so method return types are unchanged. An unknown selector on a statically-known actor gets the same knowledge-graded ADR 0100 diagnostic as a local send — the process boundary is invisible to the checker:

   (db withTimeout: 30000) query: sql    // resolves query:'s real return, not Dynamic
   
   logger := Logger spawn
   logger logg: "hi"                     // ⚠️ Logger does not understand 'logg:' — did you mean 'log:'?
   

See ADR 0104 for the full rationale, prior art, and the metaclass-aware constructor inference (ADR 0083) that types spawn / spawnWith:.

BEAM Mapping

Caller-Process Class Method Dispatch

Class methods normally execute inside the class object's gen_server process. For long-running class methods (batch processing, report generation) that would block all other messages to the class, use performLocally:withArguments: to execute in the caller's process instead:

// Normal dispatch — runs in MyClass gen_server process
MyClass computeReport

// Local dispatch — runs in caller's process, doesn't block the class
MyClass performLocally: #computeReport withArguments: #()

// With arguments
MyClass performLocally: #add:to: withArguments: #(3, 7)

Limitations: Local dispatch calls the method directly on the target class module — it does not walk the superclass chain. Class variables follow the read-only snapshot rule (ADR 0130 §5): the method reads the class variables as of the last completed class-method invocation, and a write raises class_state_read_only. When performLocally:withArguments: is reached from inside the class's own method mid-invocation, it reads and writes the live class variables instead. Use this only for stateless or read-only class methods.

Passing Blocks Through Class Methods

Unless the method is direct-called (see below), a class method runs in the class object's gen_server process, so a block passed into one runs there too, not where it was written (BT-3022):

Value subclass: Driver
  class run: aBlock over: aList -> Nil =>
    aList do: [:x | aBlock value: x]      // aBlock runs in Driver's class process
    nil

Arguments and return values cross that boundary as copies, so blocks that compute answers work normally. Two things do not survive the hop:

• Process-local side effects. A block that writes to the process dictionary (Erlang erlang put:value:), reads self(), or otherwise depends on running in a particular process affects the class process. The caller sees none of it.
• Re-entrant class sends. If the block messages the same class whose method is driving it, the class process would have to gen_server:call itself. That raises a structured dispatch_error naming the selector rather than deadlocking. Read what you need before the call, or hold the resource yourself instead of using the block form.

When there is no hop (ADR 0129 Phase 0b). The process hop applies only to classes with class state (classState:), or to methods that are not class sealed. A class sealed method of a sealed class with no classState: is called directly, in the caller's process, however it is reached: statically, through a variable, perform:, Beamtalk classNamed:, or a class passed as an argument. For those methods a block runs where it was written, self() and the process dictionary are the caller's, there is no class_send timeout, and messaging the same class from inside does not raise dispatch_error. Eligibility is computed once by the compiler and emitted as direct_class_methods in __beamtalk_meta/0; new/new: and the supervisor startLink family are never direct.

Non-local return (^) does cross the boundary: the signal is relayed back and unwinds the enclosing method as it would without the hop. A ^ is not an error, so a class variable written before the block escaped keeps its write (ADR 0130 §4).

Class variables and blocks (ADR 0130)

Class variables follow three rules (ADR 0130).

1. One home. During a class-method invocation a class's variables live in exactly one place, the class's own process. Class methods neither take nor return them, and a write is made in place wherever it happens, so every later read sees it: at a method's top level, in loops and conditionals, inside do:/collect: and the other collection methods, inside ensure:/on:do:/Result tryDo:, in a stored closure invoked by a later statement, and in a block handed to a class-side higher-order method of the same class. Sealing a class or a selector changes how a send is dispatched and nothing about class variables. There is no workaround to learn: a loop body that only writes a class variable, or only sends a class-side message that writes one, compiles and works.
2. A boundary discards what happened inside it. An error that crosses a boundary discards every write made inside that boundary; a write made before entering it is kept. There are two boundaries. The invocation boundary: an error that escapes a class method discards all of that invocation's writes. The catch boundary: on:do:, Result tryDo: and the other runtime catchers that run Beamtalk blocks restore the variables to their value on entry before the handler runs. A non-local return (^) is not an error and discards nothing; ensure: is not a boundary (it does not catch), so its cleanup block's writes go with whichever boundary the error reaches.
3. A block writes its home class's variables only at home, and reads what it captured elsewhere. A block runs at home when it runs inside an invocation of the class it was written in: the same process, or a later invocation of the same class. At home it reads and writes the live variables. Anywhere else (a block carried to another process by a class method of another class that has class state or is not class sealed, handed to an actor, or stored or returned and run after its invocation ended) it reads the values the variables had when the block was created, as a closure reads a captured variable, and a write raises class_state_unreachable. A class sealed method of a sealed, stateless class is direct-called in the caller, so a block handed to it stays at home.

Object subclass: Counter
  classState: n = 0
  class bump -> Integer => self.n := self.n + 1
  class hook => nil
  class run =>
    b := [self hook]
    #(1, 2, 3) do: [:i | i > 1 ifTrue: [self bump]]
    b value
    self.n

Counter subclass: LoudCounter
  classState: n = 0          // class variables are per class, not inherited (ADR 0013)
  class hook => self bump

Counter run        // => 2
LoudCounter run    // => 3

The loop's conditional arm writes through self bump, and the stored closure b reads and writes the live variables when b value runs at home, so LoudCounter run answers 3 (the template-method override hook bumps once more).

Rule 3, a block abroad:

Object subclass: Tally
  classState: total = 0
  class add: x => self.total := self.total + x
  class addAll: items =>
    Batch each: items do: [:x | self add: x]
    self.total

Object subclass: Batch
  classState: runs = 0
  class each: items do: aBlock =>
    self.runs := self.runs + 1
    items do: aBlock
    nil

Tally addAll: #(1, 2)
// => ERROR: class_state_unreachable: a block that reads or writes Tally's class variables ran in another process

Batch each:do: runs in Batch's process, so the block (and the Tally add: it sends) runs away from Tally's home. The write raises instead of being silently lost, and the class-state-abroad lint warns at the block. A block that only reads self.total there would answer the value it captured. The fix is to return the value and assign it in the home class's own method, or to read into a local before passing the block.

Rule 2, a catch boundary:

Object subclass: Ids
  classState: next = 0
  class take =>
    self.next := self.next + 1
    self error: "boom"
  class tryTake =>
    [self take] on: Error do: [:e | nil]
    self.next

Ids tryTake        // => 0

The write made inside the protected block is discarded when the error crosses the catch. Had tryTake assigned self.next before entering the block, that write would be kept. Outside the class process each class-method call is its own transaction (in [X bump. X failingBump] on: Error do: [:e | nil] from the REPL, bump's write is committed when its call returns), whereas inside one of X's own class methods the protected region is the transaction.

Errors.

Runtime-owned out-of-process calls read a snapshot. Supervisor definition (class children and the other static_init/dynamic_init selectors, the withClassMethod: factory), a class's initialize: hook, and performLocally:withArguments: run a class method outside the class process. They read the class variables as of the last completed invocation (a snapshot), and a write there raises class_state_read_only. When the caller is the class process itself, mid-invocation, they read and write the live variables. A supervisor factory or performLocally: method that used to assign a class variable (the assignment was dropped, or for class children crashed supervisor startup) now raises; assign the variable from a normal class-side message instead.

Class-module ABI. Every compiled class module records its class-variable calling convention as class_var_abi in __beamtalk_meta/0. The loader (class registration, hot reload, and the release upgrade preflight) refuses a module whose class_var_abi is missing or differs from the running runtime's, including every module compiled before ADR 0130, with a structured abi_mismatch error that names the module and says to recompile. Hot upgrades across the release that changed the convention are not supported: restart the node and recompile every package.

The class-state-abroad lint. Where the compiler can see the case, it says what a block means abroad instead of leaving it to run time: a block literal that reads class variables and is passed to an asynchronous send, handed to an actor, stored or returned, or a block literal that writes class variables and is passed to another class's class-side method that runs in that class's process, gets a class-state-abroad warning at the block. Suppress it with @expect class_state_abroad, or package-wide with class-state-abroad = "off" under [diagnostics]. It is a lint, not a guarantee: a block passed through a variable or an instance method is only caught at run time, and only for writes. Cascade messages after the first are inspected (e.g. self log; bump), and an inherited method (sealed or not) of an open class that makes a late-bound self send to a non-sealed selector is flagged when a subclass override could write a class variable.

This matters most when building a Collection subclass: implementing do: by delegating to a class-side helper works, and so does a helper that reaches back into its own class.

Collection subclass: Batch
  field: items :: List = #()
  size -> Integer => self.items size

  do: block :: Block -> Nil =>
    Driver run: block over: self.items
    nil

Actor-to-Actor Coordination

Because . sends are synchronous, when an actor method calls another actor internally, the caller waits for the nested call to complete before continuing. The sync barrier pattern (explicit round-trip queries) is generally no longer needed:

// With sync-by-default: bus notify: calls receive: on each subscriber
// synchronously. When notify: returns, all subscribers have processed it.
bus notify: "hello".
col eventCount          // => 1 (already processed)

The sync barrier pattern is only needed when using ! (cast) sends internally:

// If bus uses `!` internally to forward to subscriber:
bus notify: "hello".    // bus sends subscriber ! receive: "hello" internally
col events.             // barrier: ensures col processed the cast message
col eventCount          // => 1 (now correctly reflects the event)

Server — OTP Interop (ADR 0065)

Server is an abstract subclass of Actor for BEAM-level OTP interop. The class hierarchy expresses the abstraction boundary:

Object
  └── Actor           # Beamtalk objects — messages, state, Timer
        └── Server    # BEAM processes — handleInfo:, raw OTP interop (abstract)

• Actor — Beamtalk-level: message-passing, state, Timer API, lifecycle (initialize, terminate:). Most users, most of the time.
• Server — BEAM-level: raw message handling (handleInfo:), and the natural home for future OTP features (named registration, trapExit, codeChange:from:).

Defining a Server

Use Server subclass: when you need to receive raw Erlang messages (timer events, monitor DOWN tuples, system messages). All existing Actor methods continue to work — Server inherits everything from Actor.

Server subclass: PeriodicWorker
  state: count = 0

  initialize =>
    Erlang erlang send_after: 1000 dest: (self pid) msg: #tick

  handleInfo: msg =>
    msg match: [
      #tick -> [
        self.count := self.count + 1.
        Erlang erlang send_after: 1000 dest: (self pid) msg: #tick
      ];
      _ -> nil
    ]

  getValue => self.count

handleInfo: Semantics

• Defined on Server with a default no-op implementation — messages are ignored unless you override it.
• Error handling: errors in handleInfo: are logged and the server continues (log-and-continue). A bad message does not crash the server.
• Sending handleInfo: to a plain Actor raises doesNotUnderstand — only Server subclasses have this method.

Migration: Actor to Server

Promoting an Actor to a Server is a one-word change. All existing methods continue to work:

// Before
Actor subclass: MyThing
  // ...

// After — all existing methods still work, handleInfo: now available
Server subclass: MyThing
  handleInfo: msg => ...

Timer Lifecycle

Timer processes (Timer every:do: and Timer after:do:) are linked to the calling process via spawn_link. This means:

• When the actor dies, linked Timer processes die automatically — no orphaned ticks
• cancel still works for explicit lifecycle control
• User code errors in Timer blocks are wrapped in catch — they do not crash the Timer process

Actor subclass: Ticker
  state: count = 0

  initialize =>
    Timer every: 1000 do: [self tick!]   // async cast — MUST use ! not .

  tick => self.count := self.count + 1
  getValue => self.count

No state: for the timer reference, no terminate: cleanup needed — the link handles it.

BEAM Mapping

Supervision Trees (ADR 0059)

Beamtalk provides declarative OTP supervision trees via Supervisor subclass: and DynamicSupervisor subclass:. This is the Beamtalk idiom for "let it crash" fault tolerance — define which actors should be restarted automatically, and how.

Static Supervisor

Subclass Supervisor and override class children to return a list of actor classes (or SupervisionSpec values for per-child configuration). The supervisor starts all children at startup using OTP one_for_one strategy by default.

Important: class children, class strategy, class maxRestarts, and class restartWindow are called during supervisor startup from the OTP init/1 callback — before the class gen_server is available. These methods must be pure (return literal values only). Do not send messages to self, call other class methods via dispatch, or read class variables from within these methods.

Supervisor subclass: WebApp
  class children => #(DatabasePool HTTPRouter MetricsCollector)

Start the supervisor with supervise. It registers under its class name so it can be found from anywhere. supervise and terminate: both return Result values (ADR 0080) — use unwrap at boot / in the REPL, or ifOk:ifError: / andThen: for recoverable flows:

// Boot-style: crash on failure (application boot, test setup, REPL exploration)
app := (WebApp supervise) unwrap
// => Supervisor(WebApp, _)

// Idempotent — second call also returns a successful Result wrapping the
// already-running supervisor, without restarting
(WebApp supervise) isOk
// => true

// Recoverable form — branch on the Result explicitly
(WebApp supervise)
  ifOk:    [:sup | sup count]
  ifError: [:e | Logger error: e message]

// Find the running instance by class name (no reference needed — returns the
// bare supervisor or nil, unchanged from pre-ADR-0080 semantics)
WebApp current
// => Supervisor(WebApp, _)

Inspect and manage children:

app count                                 // => 3  (number of running children)
app children                              // => ["DatabasePool","HTTPRouter","MetricsCollector"]  (child ids)
(app which: DatabasePool) unwrap           // => Actor(DatabasePool, _)  (running child instance)
(app terminate: HTTPRouter) unwrap        // gracefully stop a single child; Result(Nil, Error)
app stop                                  // stop the supervisor and all children (unchanged — Nil)

// After stop:
WebApp current                            // => nil

terminate: is idempotent — terminating a child that is already gone returns Result ok: nil, not an error (see idempotent-startup convention below).

Class-Side Configuration Defaults

Override these class methods in your subclass to customise restart behaviour:

Supervisor subclass: CriticalApp
  class children => #(Database Cache)
  class strategy => #oneForAll       // restart all if any child crashes
  class maxRestarts => 3             // give up after 3 crashes in 60 seconds

Actor Supervision Policy

Each actor class declares its OTP restart policy via class supervisionPolicy:

Actor subclass: DatabasePool
  class supervisionPolicy => #permanent   // always restart on crash

Actor subclass: RequestHandler
  class supervisionPolicy => #transient   // restart only on abnormal exit

Actor subclass: BackgroundJob
  class supervisionPolicy => #temporary   // never restart (default)

SupervisionSpec — Per-Child Overrides

Use SupervisionSpec when you need to override a child's restart policy, provide startup arguments, or set a custom shutdown timeout:

Supervisor subclass: WebApp
  class children =>
    #(DatabasePool
      HTTPRouter supervisionSpec withRestart: #transient
      (MetricsCollector supervisionSpec withId: #metrics withArgs: #{#port => 9090}))

Use withShutdown: to set a graceful shutdown timeout (in milliseconds) for children that need time to drain connections or flush state. The default is 5000ms for workers and infinity for nested supervisors.

HttpServer supervisionSpec withShutdown: 30000   // 30s graceful shutdown

Use withName: (and the withName:withRestart: / withName:withArgs: / withName:withRestart:withArgs: combinators) to have the supervisor register the child atomically under a Symbol name on each restart. Named specs emit a #spawnAs: / #spawnWith:as: startFn so re-registration happens in the same OTP call that starts the process — held Actor named: references survive restarts (see ADR 0079 and the Actor Named Registration section below). name and classMethod cannot be combined on the same spec.

Supervisor subclass: WebApp
  class children =>
    #((Counter supervisionSpec withName: #counter withRestart: #permanent))

Dynamic Supervisor

Subclass DynamicSupervisor to manage pools of actors started at runtime. Override class childClass to declare which actor class the pool manages.

DynamicSupervisor(Worker) subclass: WorkerPool
  class childClass => Worker

pool := (WorkerPool supervise) unwrap
// => DynamicSupervisor(WorkerPool, _)

// Start children dynamically — startChild returns Result(C, Error) where C is
// the DynamicSupervisor's child class parameter (Worker here)
w1 := pool startChild unwrap        // => Actor(Worker, _)
w2 := pool startChild unwrap        // => Actor(Worker, _)
pool count                          // => 2

// Start a child with custom init args — args is passed to the child's init/1
// the same way ActorClass spawnWith: args would
w3 := (pool startChild: #{#label => "y"}) unwrap   // => Actor(Worker, _)

// Recoverable variant — useful when a failing init should not abort the caller
pool startChild
  ifOk:    [:w | w process: 21]
  ifError: [:e | Logger warn: e message]
pool count                          // => 4

// Terminate a specific child — idempotent (Ok(nil) even if already gone)
(pool terminateChild: w1) unwrap    // => nil
pool count                          // => 3

// Stop the whole pool (unchanged — Nil, let-it-crash teardown)
pool stop
WorkerPool current                  // => nil

Automatic restart replays per-child args. OTP tracks the exact args each dynamically-started child was started with. A child started via startChild: args that later crashes under a #permanent or #transient restart policy comes back with those same args, not blank defaults. A child started via the no-arg startChild restarts the same way. Restart re-runs init/1 from scratch — it does not resume the child's prior runtime state.

Named dynamic children — identity that survives restart. startChild: alone gives you a pid, and a simple_one_for_one-restarted child comes back as a different, unlabelled pid — there is no which:/children method on DynamicSupervisor to rediscover it (see below). startChild: args name: aSymbol closes that gap by combining args-replay with named actor registration: the child starts under {local, aSymbol} registration, and because OTP replays each dynamic child's own start args (including the name) on automatic restart, a crashed named child re-registers under the same name every time.

DynamicSupervisor(Monitor) subclass: CheckRegistry
  class childClass => Monitor

pool := (CheckRegistry supervise) unwrap
m := (pool startChild: #{#check => "db"} name: #dbCheck) unwrap
// => Actor(Monitor, _)

// ... time passes; #dbCheck's process crashes and OTP restarts it ...

current := (Monitor named: #dbCheck) unwrap   // re-resolves to the NEW pid
current isAlive                                // => true

aSymbol should come from a bounded, statically-known namespace (e.g. a fixed set of configured checks/workers) — the same atom-exhaustion guidance that applies to Actor>>spawnAs: applies here, since names are Erlang atoms.

Why no which: id / children method on DynamicSupervisor. Static Supervisor>>which: and >>children (below) work because OTP's plain one_for_one gives every statically-declared child a stable childspec id. DynamicSupervisor's simple_one_for_one children are anonymous — matched only by pid — and supervisor:which_children/1 is a documented performance cliff at scale (it copies the whole child list out of the supervisor process in one message). startChild:name: + Actor named: gives "find this dynamic child again by a stable identity, surviving restart" without either limitation: a whereis/1-backed point lookup, not a full-list scan. This differs from DynamicSupervisor>>count, which only reports an aggregate number with no per-child identity at all.

Nested Supervisors

Supervisors can be nested — include another supervisor class in children:

Supervisor subclass: AppRoot
  class children => #(DatabaseSupervisor WebTierSupervisor MetricsSupervisor)

Nested supervisor children are identified by isSupervisor => true and started via OTP start_link/0, ensuring they are correctly linked into the supervision tree. The outer supervisor shuts down inner supervisors (and all their children) gracefully on stop.

root := (AppRoot supervise) unwrap
root count                          // => 3
(root which: DatabaseSupervisor) unwrap  // => Supervisor(DatabaseSupervisor, _)

Lifecycle API returns Result (ADR 0080)

Supervisor lifecycle methods that can fail at a startup / registry boundary return a Result:

stop, current, children, and count are unchanged — they are teardown / lookup / inspection operations over an already-valid handle and follow let-it-crash semantics (teardown) or nil-on-miss (lookup), matching the rules established in ADR 0079 for the parallel Actor surface.

This mirrors Actor spawnAs: / Class named: from the Actor Named Registration section — both APIs speak Result at registry / lifecycle boundaries so call sites that chain actor spawns and supervisor operations stay on a single error idiom.

Errors carry structured beamtalk_error values (ADR 0015) with a Symbol kind and a human-readable message. REPL display shows them as Result error: (beamtalk_error <kind>) so they are greppable in logs and aggregatable in metrics.

Idempotent-startup convention

Across every supervisor lifecycle method, an operation returns a successful Result when the caller's target end state is already in effect, regardless of whether this call or a prior one established it. The rule is "does the target state hold now?" — not "did this call change the input?"

This matters in practice: you can call WebApp supervise at every entry point of your application without branching on "is this the first call?" — the second caller gets the already-running supervisor back in the ok branch. Similarly, a cleanup path that calls app terminate: StaleChild succeeds whether the child was still alive or already gone, so you never have to swallow a raise to express "stop it if it's running."

Error is reserved for outcomes the caller cannot trivially ignore:

• #supervisor_start_failed — start_link returned a non-already_started reason (init crash, config error, resource exhaustion).
• #child_start_failed — child's init/1 raised, or the supervisor rejected the spec.
• #terminate_failed — supervisor:terminate_child/2 returned a reason other than not_found (supervisor crash, timeout).
• #stale_handle — the supervisor process itself is dead.

Call-site patterns

Boot-style: crash on failure. Use unwrap at application boot, test setup, and in the REPL — the resulting exception carries the structured error payload.

app  := (WebApp supervise) unwrap
pool := (WorkerPool supervise) unwrap
w    := pool startChild unwrap

Recoverable: branch on the Result. Use ifOk:ifError: (or andThen: / mapError:) when a failure should be logged or retried rather than crashing the caller.

(WebApp supervise)
  ifOk:    [:sup | Logger info: "app started with " , sup count asString , " children"]
  ifError: [:e   | Logger error: e message]

pool startChild
  ifOk:    [:worker | worker process: job]
  ifError: [:e      | Logger warn: "worker start failed: " , e message]

Idempotent terminate. terminate: / terminateChild: naturally express "make sure this child is gone" — no special-casing required.

// Before ADR 0080 — had to swallow Error because not_found raised
[app terminate: Counter] on: Error do: [:_e | nil]

// After — idempotent: returns Result ok: nil whether fresh terminate or already gone
(app terminate: Counter) unwrap
// real failures still surface as Result error: (beamtalk_error terminate_failed)
(app terminate: Counter) ifError: [:e | Logger warn: e message]

See ADR 0080 §Migration Path for the full mechanical rewrite guide and common gotchas (chained sends on the return value, type-narrowing in tests, REPL display changes).

BEAM Mapping

Actor Named Registration (ADR 0079)

Actors can be registered under a Symbol name so they can be looked up without passing a reference around, and so supervised restarts stay addressable. Named lookups are class-checked — Counter named: #counter only returns the registered process if it is a Counter (or subclass).

// Atomic spawn + register — prefer this when the name is known up front
c := (Counter spawnAs: #counter) unwrap
c := (Counter spawnWith: #{#count => 10} as: #counter) unwrap

// Register an already-spawned actor (not atomic w.r.t. spawn)
(c registerAs: #counter) onSuccess: [:c | c increment]

// Typed lookup — Result(Self, Error), so `Counter named:` narrows to Counter
engine := (WorkflowEngine named: #engine) unwrap
(Logger named: #counter)   // => Result error: (beamtalk_error wrong_class)

// Instance queries
c registeredName    // => #counter  (or nil if unnamed)
c isRegistered      // => true

// Idempotent release
c unregister        // => #ok

// Discover all currently-registered Beamtalk actors
Actor allRegistered       // => #(an Actor(Counter), an Actor(Logger))

Restart survival. When a named actor is started under a supervisor (via SupervisionSpec withName:), the runtime dispatches sends through the registered name, not the snapshot pid. Held Counter named: #counter references continue to work after a supervisor restart because the name is re-registered atomically in the restarted process's gen_server:start_link({local, Name}, ...) call.

Errors are surfaced as Result values (or raised as #beamtalk_error{} on direct send):

See ADR 0079 for the full design and exposure table.

Introspecting the Live Supervision Tree (ADR 0092)

Where supervision syntax declares a tree, Node current processes lets you walk the live one — the dynamic counterpart to Node current actors, and the process-structure twin of SystemNavigation. It returns a navigable SupervisionTree snapshot of the running OTP supervision tree, built as a thin wrapper over supervisor:which_children (no new bookkeeping process).

tree := Node current processes unwrap   // == ProcessNavigation default tree
tree root                          // => the snapshot root SupervisionNode
tree size                          // => total node count
tree do: [:node | Transcript showCr: node printString]
tree select: [:node | node isSupervisor]
tree findClass: Counter            // => every running Counter as SupervisionNodes
tree nodesOfKind: #beamtalkActor   // => List(SupervisionNode)

Each SupervisionNode is an immutable record:

node pid               // => a Pid | nil   (nil for a child mid-restart)
node registeredName    // => Symbol | nil
node kind              // => #beamtalkSupervisor | #beamtalkActor
                       //    | #otpSupervisor | #otpProcess | #restarting
node behaviourClass    // => Class | nil   (nil for foreign OTP processes)
node childCount        // => Integer       (live children; supervisors only)
node strategy          // => Symbol | nil  (#oneForOne … ; supervisors only)
node restartIntensity  // => Dictionary | nil  (configured #{#maxRestarts, #window})
node children          // => List(SupervisionNode)
node parent            // => SupervisionNode | nil
node isSupervisor      // => Boolean
node isBeamtalk        // => Boolean
node status            // => Dictionary | nil   (LAZY — see below)

The kind field drives rendering: a Beamtalk class badge for #beamtalkActor / #beamtalkSupervisor (with behaviourClass populated), a foreign-process badge for #otpSupervisor / #otpProcess. A child OTP is currently restarting carries kind => #restarting and pid => nil — the snapshot never crashes on a process caught mid-restart.

Snapshot semantics. Construction freezes the tree once; iterating it never re-enters OTP, so a walk is internally consistent and can never deadlock or block on a busy process. Construction itself is not atomic, so the snapshot is a best-effort point-in-time view — re-call Node current processes to refresh. A node whose pid has since died is detected lazily: node status returns nil rather than raising.

Lazy state. node status is not captured at snapshot time. Calling it issues a timeout-guarded sys:get_status against the node's pid then — returning a Dictionary for an alive, sys-compliant process, or nil for one that is dead, timed out, or not sys-compliant.

Scopes and scale. ProcessNavigation default (what Node current processes wraps) filters runtime plumbing; ProcessNavigation system shows everything, including runtime internals — a privileged view (ADR 0091). A from: constructor roots a walk at a Supervisor handle or a Pid, returning a Result (the root may be dead). A simple_one_for_one DynamicSupervisor with more children than the cap is reported truncated with its childCount instead of materialising every child; opt into full expansion with ProcessNavigation from: aSup limit: n.

ProcessNavigation system tree size                 // everything, incl. infra
(ProcessNavigation from: aSup) unwrap tree         // a rooted subtree
(ProcessNavigation from: aStoppedSup)              // => Result error: (beamtalk_error stale_handle)

See ADR 0092 for the full design.

Named Actor Registration (ADR 0079)

Named actor registration gives a process a stable identity (a Symbol) that survives supervised restarts. A name-resolving proxy re-resolves the name on every message send, so a held reference keeps working even when the underlying actor is restarted with a fresh pid.

Under the hood this maps directly to OTP's process registry (erlang:register/2, gen_server:start_link({local, Name}, ...)), so registered Beamtalk actors show up in observer, recon, and erlang:registered/0 with the names you chose.

API Surface

Supervised children gain naming through SupervisionSpec withName:, which tells the runtime to start the child with {local, Name} registration so the name is re-established every time the supervisor restarts the child:

EventStore supervisionSpec withName: #eventStore withRestart: #permanent

Errors

Registration returns Result(Self, Error) rather than raising — callers branch explicitly on outcome:

The asymmetry is deliberate: named: returns a Result because name-absence is an expected outcome the caller must branch on; sending to a vanished proxy raises because the caller has already committed to a send.

Worked Example — Migrating from Supervisor which:

Before named registration

The pre-ADR pattern uses a supervisor-local lookup (which:) and an initialize: hook to re-wire dependencies after each restart:

typed Supervisor subclass: ExduraSupervisor
  class strategy -> SupervisionStrategy => #restForOne
  class children -> List(SupervisionSpec) =>
    storeSpec := EventStore supervisionSpec withRestart: #permanent
    poolSpec := ActivityWorkerPool supervisionSpec withRestart: #permanent
    engineSpec := WorkflowEngine supervisionSpec withRestart: #permanent
    #(storeSpec, poolSpec, engineSpec)

  // Re-runs after every restart to rebuild cached pids.
  class initialize: sup :: Supervisor -> Nil =>
    store := (sup which: EventStore) unwrap
    pool := (sup which: ActivityWorkerPool) unwrap
    engine := (sup which: WorkflowEngine) unwrap
    engine initWithStore: store pool: pool
    nil

After named registration

Naming each child eliminates the initialize: hook, and the supervisor strategy is freed from the rewire-on-restart constraint:

typed Supervisor subclass: ExduraSupervisor
  class strategy -> SupervisionStrategy => #oneForOne
  class children -> List(SupervisionSpec) => #(
    EventStore supervisionSpec withName: #eventStore withRestart: #permanent,
    ActivityWorkerPool supervisionSpec withName: #workerPool withRestart: #permanent,
    WorkflowEngine supervisionSpec withName: #workflowEngine withRestart: #permanent
  )
  // No initialize: hook — WorkflowEngine looks up its dependencies by name.

WorkflowEngine now calls (Actor named: #eventStore) unwrap at use-time — automatically picking up the current pid across restarts — and cross-tree consumers (HTTP handlers, REPL workspaces, tests) can reach supervised actors directly without routing through the supervisor.

Proxy Semantics

Class named: returns a lightweight name-resolving proxy. The proxy does not cache a pid; each message send re-resolves the name via the Erlang runtime. This is the key restart-survival property:

engine := (WorkflowEngine named: #workflowEngine) unwrap
engine runWorkflow: w1    // resolves #workflowEngine, sends to that pid
// (#workflowEngine crashes; the supervisor restarts it under the same name)
engine runWorkflow: w2    // re-resolves #workflowEngine, sends to the NEW pid

A few caveats the proxy intentionally does not paper over:

• monitor: and onExit: are pid-level — they watch the current pid, not the name. A monitor does not re-arm when the supervisor restarts the process under the same name. A future "watch a name" API can be added separately; for now, prefer isAlive polling via the proxy when you need restart-aware liveness.
• Equality is identity-shape-based. Two proxies with the same name are equal. A proxy and a direct-pid reference are not equal, even if they currently resolve to the same pid — the whole point of a name proxy is to be a different kind of reference.
• unregister makes the proxy dead. After unregistering, further sends through a proxy raise #no_such_process even if the underlying actor is still running. Re-register under a new name if you want to keep routing messages through a name-resolving proxy.

Reserved Names

A static blocklist of OTP-kernel atoms is rejected at registration time, regardless of whether the corresponding process is currently running. Attempting spawnAs: #logger or spawnAs: #kernel_sup returns Result error: (beamtalk_error reserved_name).

The reserved set covers:

• OTP kernel and stdlib processes: application_controller, code_server, erl_prim_loader, erl_signal_server, error_logger, erts_code_purger, file_server_2, global_group, global_name_server, inet_db, init, kernel_refc, kernel_safe_sup, kernel_sup, logger, logger_handler_watcher, logger_proxy, logger_std_h_default, logger_sup, net_kernel, net_sup, rex, socket_registry, standard_error, standard_error_sup, standard_error_writer, user, user_drv, user_drv_reader, user_drv_writer.
• Any atom prefixed with beamtalk_ (reserves the namespace for runtime infrastructure).

See beamtalk_actor:reserved_name/1 in the runtime for the authoritative list and the policy rationale (ADR 0079 §Errors).

Scope

This release covers local (per-node) registration. Cluster-wide (#global) and pluggable ({via, Module, Term}) scopes are deferred to a future ADR — the API is designed to admit them additively via a scope: keyword. Users who need cluster registration today can call the Erlang global module via FFI.

BEAM Mapping

Pattern Matching

Smalltalk lacks pattern matching - this is a major ergonomic addition.

Match Expression

The match: keyword message takes a block of pattern arms separated by ;:

// Basic match with literals
x match: [1 -> "one"; 2 -> "two"; _ -> "other"]

// Variable binding in patterns
42 match: [n -> n + 1]
// => 43

// Symbol matching
status match: [#ok -> "success"; #error -> "failure"; _ -> "unknown"]

// String matching
greeting match: ["hello" -> "hi"; _ -> "huh?"]

// Guard clauses with when:
x match: [
  n when: [n > 100] -> "big";
  n when: [n > 10] -> "medium";
  _ -> "small"
]

// Negative number patterns
temp match: [-1 -> "minus one"; 0 -> "zero"; _ -> "other"]

// Match on computed expression
(3 + 4) match: [7 -> "correct"; _ -> "wrong"]

// Array destructuring in match arms (BT-1296)
#[10, 20] match: [
  #[h, t] -> h + t;
  _ -> 0
]
// => 30

// Dict/map destructuring in match arms (BT-1296)
#{#event => "click", #x => 5} match: [
  #{#event => evName} -> evName;
  _ -> "unknown"
]
// => "click"

// Nested array patterns
#[#[1, 2], 3] match: [
  #[#[a, b], c] -> a + b + c;
  _ -> 0
]
// => 6

// Constructor patterns (Result ok:/error: only in this release)
(Result ok: 42) match: [
  Result ok: v    -> v;
  Result error: _ -> 0
]
// => 42

// Nil pattern — matches nil exactly (BT-2854, ADR 0107)
value := nil
value match: [
  nil -> "was nil";
  s :: String -> s;
  _ -> "other"
]
// => "was nil"

// Type patterns — bind and test runtime class (BT-2855, ADR 0107)
x := "hello"
x match: [
  nil -> "nil";
  s :: String -> s size;
  n :: Integer -> n + 1;
  _ -> "other"
]
// => 5

// Guard scoped over the type-pattern binding
x := 42
x match: [
  n :: Integer when: [n > 100] -> "big";
  n :: Integer -> "small";
  _ -> "other"
]
// => "small"

// Mixing type patterns with literal and wildcard patterns
x := "hi"
x match: [
  nil -> 0;
  s :: String -> s size;
  _ -> -1
]
// => 2

Type patterns test the runtime class of the scrutinee and bind the value to the named variable, narrowed to that class. Subsequent arms see the scrutinee type narrowed by difference (e.g. after a s :: String arm, the remaining arms see the type minus String).

Phase A scope (ADR 0107): type patterns are restricted to concrete/leaf classes only — binding :: SomeClass where SomeClass has subclasses is a compile error ("SomeClass has subclasses; type patterns are not yet supported for non-leaf classes"), never silently-wrong matching. Subclass-polymorphic matching (binding :: Shape where Shape has subclasses Circle/Square) is deferred to a future ADR 0107 Phase B. Supported classes today: String, Integer, Float, List, Dictionary, Boolean (uses the is_boolean/1 BIF; True/False use exact atom guards — all three are stdlib primitives that bypass the leaf-restriction via a BIF/atom-guard check, not the user-class hierarchy check a Shape/Circle-style class would go through), True, False, Symbol, Nil, UndefinedObject, Block, Pid, Reference, Port, user-defined Value subclasses, Actor subclasses, and Supervisor/DynamicSupervisor subclasses (BT-2870).

Four runtime-representation nuances (see ADR 0107 Implementation for the full codegen rationale):

• Supervisor/DynamicSupervisor subclasses use a distinct runtime shape. A live supervisor reference is a 4-tuple tagged 'beamtalk_supervisor' (not 'beamtalk_object' like Actor subclasses, and not a tagged map like Value subclasses). x :: MySupervisorSubclass compiles to a tuple-tag check accepting 'beamtalk_supervisor' at element(1) before comparing element(2) against the class name (BT-2870).
• Character is not a supported type pattern. It compiles to a plain Erlang integer with no runtime tag distinguishing it from Integer, so x :: Character could never be told apart from x :: Integer at runtime — use x :: Integer instead.
• Dictionary has no '$beamtalk_class' tag — it's a bare Erlang map, unlike tagged Value/sealed-class instances (which are also maps, but with a class tag). x :: Dictionary is fully supported, but compiles to a different check shape under the hood (a nested map-key test) so it doesn't false-positive on every other map-backed value.
• A Symbol type pattern excludes nil and booleans. nil, true/false, and symbols are all plain Erlang atoms with no distinguishing runtime tag, so nil match: [s :: Symbol -> ...] does not match, and a Symbol arm can never accidentally shadow a nil -> or b :: Boolean arm regardless of arm order.
• Bare true/false are not valid patterns. Unlike nil, true/false are not reserved pattern keywords — a bare true -> arm would otherwise silently parse as a variable binding (Pattern::Variable) that matches any value, not a boolean-literal test, and — tried first in arm order — would always win. This is rejected with a compile-time diagnostic (BT-2883); use x :: True / x :: False (exact literal) or x :: Boolean (either) instead.
• Constructor pattern keyword bindings (Result ok: v) apply the same nil/true/false rules, but the true/false fix-it differs. Result ok: nil tests the wrapped value is nil (Pattern::Nil), same as top-level nil. Result ok: true/Result ok: false are rejected with a compile-time diagnostic (BT-2884), same as top-level bare true/false — but since x :: True/x :: False type patterns aren't supported nested inside a constructor pattern, the diagnostic instead points at binding a variable and testing it in a guard clause: Result ok: v when: [v =:= true] / Result ok: v when: [v =:= false].

Supported pattern types:

Exhaustiveness checking (BT-1299): match: on a sealed type with constructor patterns must cover all known variants or include a wildcard _ arm, or the compiler emits an error:

// Compile error: missing error: arm
r match: [Result ok: v -> v + 1]

// Fine: all variants covered
r match: [Result ok: v -> v + 1; Result error: _ -> 0]

// Fine: wildcard suppresses the check
r match: [Result ok: v -> v + 1; _ -> 0]

Advisory singleton-union exhaustiveness (BT-2745, ADR 0102): when the type checker knows a match: scrutinee is a closed union of #symbol singletons, it emits a warning (never an error) for any uncovered members:

// direction :: #north | #south | #east | #west
direction match: [
  #north -> 0;
  #south -> 180;
  #east  -> 90
]
// ⚠ Warning: non-exhaustive match: `#west` is not handled (residual type: `#west`)

This check is advisory — it fires only when the scrutinee type is a union of pure #symbol singletons (not Dynamic, open Symbol, or mixed unions). An unguarded _ -> wildcard silences the warning; guarded arms do not count as coverage.

Asserted exhaustiveness — matchExhaustive: (BT-2763, ADR 0106): matchExhaustive: is an opt-in, stricter variant of match: that asserts exhaustiveness. It parses identically to match: (same patterns, guards, and destructuring), but the check runs at error severity instead of warning:

// direction :: #north | #south | #east | #west

// Compile error: matchExhaustive: proves this is NOT exhaustive
direction matchExhaustive: [
  #north -> 0;
  #south -> 180;
  #east  -> 90
]
// ⛔ Error: non-exhaustive matchExhaustive: `#west` is not handled (residual type: `#west`)

// Fine: all four members covered — silent, no diagnostic
direction matchExhaustive: [
  #north -> 0;
  #south -> 180;
  #east  -> 90;
  #west  -> 270
]

// Fine: an unguarded wildcard is still full coverage
direction matchExhaustive: [
  #north -> 0;
  _      -> -1
]

If the scrutinee's type is not a closed union of #symbol singletons (Dynamic, a bare/open Symbol, or a mixed union), nor a closed Known | Nil union (or small closed union of concrete leaf classes) covered by nil/Type patterns (ADR 0107), matchExhaustive: cannot verify the assertion and fails loudly rather than staying silent:

x matchExhaustive: [#ok -> 1; _ -> 0]
// ⛔ Error: cannot verify `matchExhaustive:` is exhaustive — scrutinee type
//    `Dynamic` is not a closed union of symbol singletons, `nil`, or
//    concrete leaf classes

Plain match:'s advisory warning behaviour is unchanged by matchExhaustive: — the two checks are independent, and only the keyword you write selects between them.

Guard expressions support: >, <, >=, <=, =:=, =/=, /=, +, -, *, /

Destructuring in Match Arms

Pattern matching can bind variables in match arms:

// Variable captures the matched value
42 match: [x -> x + 1]
// => 43

// Variable binding with guard
10 match: [x when: [x > 100] -> "big"; x when: [x > 5] -> "medium"; _ -> "small"]
// => "medium"

// Tuple destructuring in match arms
t := Erlang erlang list_to_tuple: #(#ok, 42)
t match: [{#ok, v} -> v; {#error, _} -> 0]
// => 42

Rest Patterns in Destructuring (BT-1251)

The ...identifier syntax in array destructuring captures remaining elements:

#[first, ...rest] := #[1, 2, 3, 4, 5]
// first = 1, rest = #[2, 3, 4, 5]

#[a, b, ...tail] := #[10, 20, 30, 40]
// a = 10, b = 20, tail = #[30, 40]

#[...all] := #[1, 2, 3]
// all = #[1, 2, 3]

#[head, ..._] := #[1, 2, 3]
// head = 1 (rest discarded)

The rest element must be the last in the pattern. Rest patterns are supported in destructuring assignment only — they are not yet supported in match: arms.

Note: Tuple destructuring works in both assignment ({x, y} := expr) and match: arms. collect: with pattern blocks is not yet supported.

Live Patching

Hot code reload via message sends — no dedicated patch syntax needed.

// Canonical Counter (already running in the workspace)
Actor subclass: Counter
  state: value = 0
  increment => self.value := self.value + 1
  getValue => self.value

// Replace a single method — existing instances pick it up immediately
Counter >> increment =>
  Telemetry log: "incrementing"
  self.value := self.value + 1

// Redefine the class to add state — new instances get the updated shape
Actor subclass: Counter
  state: value = 0
  state: lastModified = nil
  increment =>
    self.value := self.value + 1
    self.lastModified := DateTime now
  getValue => self.value

Live patching works on the class side too (ADR 0084): ClassName class >> sel => body installs or replaces a class method on a registered class, and class-side dispatch resolves the new method immediately.

Object subclass: Registry
  class current => nil

// Live-edit the class method — subsequent class-side sends pick it up
Registry class >> current => "live"
Registry current        // => "live"

// Add a brand-new class-side selector
Registry class >> reset => 0
Registry reset          // => 0

The >> live-edit path recompiles the class's recorded source, so it applies to classes defined in source (inline Object subclass: or :loaded files). Purely-programmatic ClassBuilder classes have no recorded source; supply their class methods up front via classMethods: / addClassMethod:body: instead.

Saving live edits back to disk — compile:source:, ChangeLog, and flush (ADR 0082)

Live patches go into memory; they reach the .bt source file only when you flush. Between the patch and the flush, every in-memory mutation is recorded in the workspace ChangeLog — the pending-changes view, dirty-state tracker, and undo store rolled into one (ADR 0082).

The model has three layers: in-memory class state (hot-reloaded BEAM), the ChangeLog (per-workspace append-only log; persists across workspace restart), and the .bt files on disk. Every successful live patch updates memory and appends a ChangeEntry. Workspace flush walks pending entries and splices each patched body back into its source file via byte-span replacement — no AST re-print, no whole-file reformat — atomically (<file>.tmp + rename) with external-edit conflict detection.

The patcher primitives

>> and compile:source: are equivalent in effect — both install the new method and append a durable ChangeEntry. The keyword form takes the body as a String value so tools (MCP, LSP, browser editors) don't have to escape quotes or multi-line bodies back into source. tryCompile:source: installs in memory like compile:source: but tags the entry as ephemeral — successful spikes are promoted by re-calling compile:source: with the same body. Every successful in-memory mutation logs unconditionally, including spikes and patches against stdlib / dependency classes (which are not flushable). The audit trail is exhaustive on purpose.

Canonical patch → changes → flush round trip

> Counter >> increment => self.value := self.value + 1
=> Counter                          // memory patched
> Workspace changes notEmpty
=> true
> Workspace changes dirtyMethods
=> #{#Counter => #{#increment}}     // per-class set of dirty selectors
> Workspace flush
=> _                                // FlushResult; quiet on success
> Workspace changes isEmpty
=> true                             // flushed entries drop out of the active view

Workspace changes returns a ChangeLog object (see below). Workspace flush returns a FlushResult summary with #flushed, #files, #newClasses, #removedClasses, #skipped, and #conflicts. A non-empty #conflicts list means the listed entries remain pending and require manual reconciliation; a non-empty #skipped list means a pending destructive (Tier 2) entry was withheld — see Destructive flush below.

Targeted flush

Workspace flush                                   // every durable + flushable entry
Workspace flush: Counter                          // entries targeting one class
Workspace flush: #'new-class'                     // entries of one kind
Workspace flush: #{ #file => "src/counter.bt" }   // entries against one file
Workspace changes flushKinds: #{#agent}           // only agent-authored entries
Workspace changes flushKinds: #{#agent, #'new-class'}  // both filters AND together

External-edit conflict — patch, edit on disk, flush

> Counter >> increment => self.value := self.value + 2   // memory patched
=> Counter
// ... another editor (or `git pull`) modifies examples/counter.bt on disk ...
> Workspace flush
=> _   // FlushResult with #conflicts: [#{#file => "examples/counter.bt",
       //                                  #reason => #external_edit, ...}]
       // The patch stays pending; memory is still ahead of disk.

When flush detects an external edit, the offending entries stay in the log and the user picks the recovery path:

Workspace changes clear                           // drop the pending ChangeLog entries
                                                  //   (already-installed patches stay in memory
                                                  //    until workspace restart — use `revert:` to
                                                  //    actually re-install the prior method body)
Workspace changes revert: anEntry                 // undo one patch (re-install prior body)
// or open the file, reconcile by hand, then:
Workspace flush                                   // retry once disk matches expectations

Ephemeral spike → promote → flush

> Counter tryCompile: #doubled source: "doubled => self.value * 2"
=> Counter                          // memory patched, ChangeEntry logged as ephemeral
> (Counter spawn) doubled
=> 0                                // works — agent decides to keep it
> Counter compile: #doubled source: "doubled => self.value * 2"
=> Counter                          // promoted: durable ChangeEntry layered on top
> Workspace flush
=> _                                // disk gains the new method

The earlier ephemeral entry remains in the log for audit and is auto-pruned on the next workspace restart.

Creating a brand-new class file

> Workspace newClass: "Object subclass: Greeter\n  greet => 'hello'" at: "src/greeter.bt"
=> [Greeter]                        // compiled and installed in memory
> Workspace flush
=> _                                // writes src/greeter.bt

newClass:at: raises a loud, specific error (no silent fallback) if path already exists, lies outside the project tree, the declared class name does not match the path basename (ADR 0040 one-class-per-file convention), or a class of that name is already loaded.

Removing methods — removeSelector: and removeSelector:ifAbsent: (ADR 0112)

removeSelector: completes Behaviour's patch/create/remove trio alongside compile:source: and newClass:at:: it drops a method from the receiver's own method table (instance-side) or the receiver's metaclass's method table (class-side), then logs a durable kind: #'remove-method' ChangeEntry — exactly the ChangeLog participation a patch gets, just deleting text instead of replacing it.

sealed removeSelector: aSelector :: Symbol -> Behaviour
sealed removeSelector: aSelector :: Symbol ifAbsent: absentBlock :: Block(T) -> Behaviour | T

Counter removeSelector: #increment          // instance-side: touches instance_methods
Counter class removeSelector: #ofSize:      // class-side: touches class_methods

Receiver side follows the existing Counter vs Counter class convention already used to pick a side for >> extension definitions — there is no boolean parameter. Both forms return the receiver (Behaviour) on success, so removals chain the same way patches do: Counter removeSelector: #a; removeSelector: #b.

Because dispatch always walks the class chain live (ADR 0032 — no flattened method-table cache), removing an overriding method instantly re-exposes whatever the superclass defines, with no restart and no cache to invalidate:

Actor >> initialize => Transcript show: 'base init'
Actor subclass: Counter
  state: value = 0

  initialize => Transcript show: 'counter init'

Counter new                    // prints 'counter init'
Counter removeSelector: #initialize
Counter new                    // prints 'base init' — no restart needed

removeSelector: also reaches extension methods (ADR 0066 open classes) — sent to the target class, the same way an extension is installed via >>:

String >> shout => self uppercase ++ "!"
"hi" shout                     // => "HI!"
String removeSelector: #shout
"hi" respondsTo: #shout        // => false

The bare form raises; removeSelector:ifAbsent: is the paired escape hatch — mirroring Dictionary>>at:ifAbsent: and Pharo's own removeSelector:/removeSelector:ifAbsent: pairing. A selector that is absent locally — never defined, already removed, or only inherited — raises a structured error with kind selector_not_found, deliberately distinct from does_not_understand (the message removeSelector: itself was understood and executed; only its argument had nothing to act on):

[Counter removeSelector: #bogus] on: Error do: [:e | e kind]
// => selector_not_found

Counter removeSelector: #bogus ifAbsent: ["not found"]
// => "not found"

// #printString is inherited from Object, not local to Counter, so it still
// raises — includesSelector: distinguishes "responds to" from "defines locally".
Counter includesSelector: #printString    // => false
Counter removeSelector: #printString      // raises selector_not_found

removeSelector:ifAbsent:'s block runs only on absence and its value is returned instead of the receiver.

Process semantics note. Like every Behaviour tower primitive, removeSelector:ifAbsent: runs in the caller's process (the Class → Behaviour chain-walk fallthrough), not the receiver class's gen_server. The absentBlock messaging the receiver class back is an ordinary cross-process send — no dispatch_error restriction applies here (unlike a block argument received by a locally-defined class method; see Passing Blocks Through Class Methods).

removeSelector: never refuses based on where a class lives — it always installs the removal in memory. What varies is whether the resulting ChangeEntry is flushable, exactly mirroring compile:source:'s rule (see Flushability below) rather than removeFromSystem's outright block (see removeFromSystem):

Integer removeSelector: #printString      // installs in memory, no error
Workspace changes dirtyMethods             // => #{#Integer => #{#printString}}
Workspace flush                            // skips it: not flushable (stdlib)

See ADR 0112 for the full design, including extension-removal edge cases, dangling-sender risk, and the side field's role in the ChangeLog schema.

autoflush

For users who want write-through editor semantics, flip a single workspace setting:

Workspace autoflush       // => false  (default)
Workspace autoflush: true // => true   (every successful durable patch flushes immediately)

Autoflush persists across workspace restarts. It is best-effort, not transactional — a flush failure under autoflush (external-edit conflict, write error) leaves memory ahead of disk and the entry pending in the log. The BEAM module install is not rolled back because live actors may hold references to the new closures. The error surfaces with a "memory ahead of disk" warning.

Ephemeral patches via tryCompile:source: are never autoflushed.

Flushability — what flush writes

A class is flushable iff its sourceFile is non-nil and lies inside the current project's source tree. Workspace flush writes only entries where intent = durable AND flushable = true. Other entries are reported under #conflicts (for external-edit / target-exists errors) or simply skipped:

• Stdlib classes (Integer, String, ...) — sourceFile = nil. Patches install in memory and log with flushable: false; flush skips them. Smalltalk muscle memory (Integer compile: #double source: "...") is supported as live, audited, non-flushable drift.
• Dependency classes — sourceFile outside the project tree. Same shape. Flush never writes into the dependency cache (reproducible-build guarantee).
• Dynamic classes (ADR 0038 ClassBuilder) — sourceFile = nil. Same shape.

ChangeLog

Workspace changes returns a ChangeLog object (analogous to Pharo's Smalltalk changes). All pending-state queries live on this object, not on the Workspace facade itself.

Each ChangeEntry carries the patch's body, prior body, byte span, class, selector, intent (durable / ephemeral), flushable flag, authorKind (#human / #agent), and source-file reference. Bodies are stored as plain .bt files under <workspace>/changes/sources/; metadata lives in <workspace>/changes/changes.jsonl. cat, less, diff, and bt fmt all work on the source files directly.

Repeated patches to one method — or a patch followed by a revert:, which is itself a patch (ADR 0082 "Undo") — append multiple entries for the same (class, selector). The default view keeps only the latest (the one Workspace flush would apply) and marks the rest shadowed; e isShadowed identifies them, and select: still reaches them for audit.

The latest entry is also compared against the current on-disk body: if it matches (the method was reverted back to its on-disk state) the entry is clean (e isClean) and drops out of the default view — there is no net change to flush. Each entry that does differ carries e diff, the net on-disk→in-memory unified diff (lines prefixed / - / + ). So Workspace changes answers "what differs from disk", not "everything I touched this session"; the audit trail of every entry stays in allEntries / select:.

The ChangeLog persists across workspace restart. On restart, the workspace assigns a fresh epoch and excludes prior-epoch entries from the active view (their memory state is gone). The underlying audit log keeps them; reach them via Workspace changes select: [:e | e isOrphan].

REPL and tooling shortcuts

Every operation above is reachable via the REPL meta-commands, MCP tools, LSP executeCommand handlers, and browser actions. These are all thin front-ends over the Beamtalk language — see REPL shortcuts below and the Tooling guide for the surface tables.

Live Re-Checking on Reload (ADR 0105)

A live edit doesn't just change the class being patched — it can invalidate every existing caller in the image. Every save above (>>, class-body redefinition, :load) triggers an incremental re-check of known dependents: the compiler re-checks the callers beamtalk_xref (ADR 0087) already knows about, using the same type checker that runs at compile time, and publishes what it finds as live diagnostics — no rebuild, no manual "find senders" required.

:load counter.bt
counter := Counter spawn
counter getCount + 1          // => 1

// ... change `getCount -> Integer` to `getCount -> String`, save
// (a plain `Counter >> getCount -> String => ...` live patch) ...

⚠ reload check: Counter>>getCount signature changed;
   2 callers re-checked, 1 stale
   Dashboard>>refresh (dashboard.bt:14): `+` expects a number, `getCount` now returns String

Only genuinely-affected callers surface. If StatsView>>render also calls getCount but only stringifies the result, it re-checks clean against the new signature and stays silent — the header's "2 re-checked, 1 stale" is its only trace.

A removed selector is a does_not_understand waiting to happen, reported at Hint severity (ADR 0100 Rule 1 — a single closed-complete receiver):

ℹ reload check: Counter>>reset was removed; 1 caller remains
   AdminPanel>>onClick (admin.bt:9): `counter reset` will raise
   does_not_understand at runtime
   (Hint severity per ADR 0100 Rule 1 — single closed receiver)

A state:/field: slot added, removed, or retyped re-checks spawnWith: call sites and the changed slots' generated accessors the same way, under a shape_change classification.

Advisory, never blocking. The reload already happened — a finding informs, it never vetoes. Findings are workspace-session state (LSP diagnostics, REPL/workspace-UI notices), never persisted, and never fail a build; they disappear on workspace restart. Clearing is by replacement: every re-check of a caller replaces all of its findings attributed to that changed class with the fresh result — clean or different — so back-to-back reloads of the same method never leave a stale finding sitting alongside a current one (supersession), and a later reload that fixes the callee clears the caller's finding with no edit to the caller at all.

Two related, on-demand operations round out the surface:

• Pre-save advisory — aClass precheckCompile: #selector source: "..." compiles a pending edit and reports would-be-stale dependents without installing it, so an editor can warn before you save. Never touches the live image, the ChangeLog, or the findings store.
• Workspace recheckImage (also :recheck image) — the "complete but unbounded" whole-image sweep kept out of the automatic per-reload trigger: re-checks every live class the workspace has a recorded source for and returns a checked/stale/findings report, on demand.

(Counter precheckCompile: #getCount source: "getCount -> String => self.value printString")
// => a Dictionary shaped like the reload_check report — findings without installing

Workspace recheckImage
// => _  (checked/stale summary across the whole live image)

The dependent lookup is keyed by selector and the receiver's inferred type (ADR 0115): a candidate sender is dropped before it is ever re-checked when its recorded receiver type could not dispatch to the changed class — an unrelated class hierarchy, a protocol the changed class does not conform to, or the wrong side (a Counter class receiver is a dependent of a change to Counter's class-side methods, never its instance-side ones).

Narrowing is permissive by construction: a send the compiler could not type (dynamic), a send indexed by the runtime live-patch path (which has no type-checker access and records dynamic unconditionally), a row compiled before ADR 0115, and a receiver type that resolves to no loaded class or protocol are all kept as candidates. Those still re-check and let the checker's own type inference decide relevance — a size sender on an unrelated class simply re-checks clean. Fan-out is capped per reload (with a "N more not checked" note), now as a backstop over the narrowed pool rather than over every syntactic sender of the selector; one level of fan-out only, not transitive; and proxy-routed calls (ADR 0104 §4 forwarding) are invisible to xref, so a proxy-wrapped caller can go unflagged — see ADR 0105 and ADR 0115 for the full mechanism, severity rules, and accepted gaps.

Shape Versioning (ADR 0123)

Reload's structural fallback (add a defaulted field, drop a removed one, matching by name) handles additive changes for free — it always has. What it cannot express is a rename, a retype, or a field derived from others: dropping one field and adding another loses data instead of transforming it. shapeVersion: and migrateFromVN: are the two additions that let a class author say, in ordinary Beamtalk, how a live instance's state gets from one shape to the next — the same problem hot reload, persistence, and cross-node distribution all share, solved once.

shapeVersion: — declaring a version

A class declares its shape version with a class-header clause, on its own line before any state:/field: lines — the same position handleScope: occupies:

Actor subclass: Cart
  shapeVersion: 2
  state: items :: List = #()
  state: total :: Integer = 0

• The argument is a positive integer literal — the compiler must read it without evaluating code.
• Absent means shapeVersion: 1. Every class that predates this feature is implicitly at version 1; nothing in an existing corpus needs to change.
• At most one shapeVersion: per class, and it is not inherited: versions and migration chains are per concrete class, over the flattened (inherited-fields-included) field set — because that is what an instance's actual state map holds. A subclass's chain is only the migrateFromVN: methods it defines; to reuse an ancestor's step, call it explicitly (Base migrateFromV1: old).
• Cart shapeVersion reads it back (Behaviour >> shapeVersion, sealed, defaults to 1 when undeclared):

Cart shapeVersion
// => 2

Counter shapeVersion    // no shapeVersion: clause declared
// => 1

• native: classes cannot declare shapeVersion: (or migrateFromVN:) at all — they compile to a facade with no generated init/1/code_change/3 to carry a version (ADR 0056); the compiler rejects it.

class migrateFromVN: — one method per step

A migration from shape N to shape N+1 is a class-side method, migrateFromVN:, taking the old fields as a Dictionary and returning the new fields as a Dictionary:

Actor subclass: Cart
  shapeVersion: 2
  state: items :: List = #()
  state: total :: Integer = 0

  /// v1 had only `items`; v2 caches their sum.
  class migrateFromV1: old :: Dictionary -> Dictionary =>
    old at: #total put: (old at: #items) sum

A rename the structural fallback cannot express (it would drop owner and default ownerName instead of carrying the value across):

Actor subclass: Account
  shapeVersion: 3
  state: balance :: Integer = 0
  state: ownerName :: String = ""

  class migrateFromV2: old :: Dictionary -> Dictionary =>
    (old at: #ownerName put: (old at: #owner)) removeKey: #owner

A Value, retyping a field (integer cents → float amount) and adding one:

Value subclass: Money
  shapeVersion: 2
  field: amount :: Float = 0.0
  field: currency :: Symbol = #USD

  class migrateFromV1: old :: Dictionary -> Dictionary =>
    (old at: #amount put: (old at: #cents) / 100.0) removeKey: #cents

Rules, all checked statically:

• Recognised only on the class side, with exactly one parameter; N must be a positive integer.

• A method with N ≥ shapeVersion is a warning — unreachable, since the chain never runs a step at or past the current version:

  Actor subclass: Cart
    shapeVersion: 2
    class migrateFromV7: old => old
  // ⚠️ warning: `migrateFromV7:` is unreachable — Cart's shapeVersion is 2
  

• Gaps are fine. A missing step is a no-op on the dictionary — the structural fallback runs once, after the whole chain, against the final declared shape. Consequently a hook sees the raw dictionary left by the hooks before it, and a key introduced at an earlier un-hooked step may be absent: guard with at:ifAbsent: / includesKey: when reading such a key.

• No class-variable access — a compile error, not a style rule. A migration runs outside the class process (see below), where self.x would silently read nil and a write would be silently dropped; the validator refuses both before that contract is ever reached:

  Actor subclass: Cart
    shapeVersion: 2
    classState: taxRate = 0.2
    class migrateFromV1: old => old at: #tax put: (old at: #total) * self.taxRate
  // ⛔ error: `migrateFromV1:` may not access class variables (`self.taxRate`);
  //    migration methods run outside the class process, where class
  //    variables are not available
  

• The return type, when annotated, must be Dictionary.

• A declaration error is likewise static:

  Actor subclass: Cart
    shapeVersion: "two"
  // ⛔ error: 'shapeVersion:' expects a positive integer literal (got a non-positive value)
  
  Actor subclass: Cart
    shapeVersion: 2
    shapeVersion: 3
  // ⛔ error: duplicate shapeVersion: declaration (already 2)
  

Ordinary sends are allowed inside a hook, so a migration is not pure — it just needs no process context (no live instance, no class process), which is what makes it callable standalone at the REPL, before any instance depends on it:

Cart migrateFromV1: #{#items => #(3, 4)}
// => #{#items => #(3, 4), #total => 7}

Cart migrateShape: #{#items => #(3, 4)} from: 1     // whole chain + reconcile
// => #{#items => #(3, 4), #total => 7}

migrateShape:from: (sealed, Behaviour >> migrateShape:from:) runs the full chain from a given version to the class's current shapeVersion, then reconciles against the declared fields — the identical operation a reload performs, exposed for standalone testing. It is idempotent at the current version (migrateShape:from: with aVersion = shapeVersion runs reconcile only, unchanged):

Cart migrateShape: #{#items => #(3, 4), #total => 7} from: 2
// => #{#items => #(3, 4), #total => 7}     // already current — unchanged

Chain and reconcile semantics

For a reload (or any migrateShape:from: call) from version V to the class's current T:

1. For each K in V, V+1, …, T-1: if a migrateFromVK: exists, apply it to the running dictionary; otherwise that step is a no-op.
2. Reconcile against the declared field list (the flattened one, inherited fields included). A declared field present in the dictionary is kept, whether or not it is late (see late Slots); absent gets its declared default; absent with no default is nil on an untyped class and a failure on a typed one (a migration may not leave a typed slot unset, same rule ADR 0078 enforces after initialize) — except a declared-but-absent late field (ADR 0124 §8), which is never defaulted or failed: it simply stays absent from the reconciled dictionary, on both a typed and an untyped class (late slots declare no default in the first place, so this check runs before the has-default/typed-no-default rules above, not as a fallback from them). An undeclared key is dropped with a warning.
3. Downgrading (T < V) runs reconcile only — migrateToVN: downgrade hooks are reserved, not defined.

Changing a slot between eager and late (or back) is a shape change — it changes what an absent key means to the reconcile step above — and bumps shapeVersion: the same way adding, removing, or retyping a slot does; the reload-time tooling findings (ADR 0123 §4) flag a flip that lands without a version bump the same way they flag a dropped or retyped field.

Every live actor's state map carries one internal key, '__shape_version__', written by init/1 (absent means 1) and updated to the class's current version on a successful migration — never visible through fieldNames, printString, the Inspector, or any other reflection surface, exactly like every other internal key.

Suspend on failure, not resume-on-old-state or kill

If a migrateFromVN: hook raises, the actor is left suspended — not resumed with its old-shaped state under the new code (which is what the structural-only fallback used to do), and not killed:

Cart reload
// => Cart
⛔ reload: 1 instance of Cart left suspended — migrateFromV1: raised
   does_not_understand: List>>summ (Cart class >> migrateFromV1:, cart.bt:9)
   state intact at v1; fix the hook and `Cart reload` again, or stop the instances via `Node current actors`

The suspended instance's state is intact and inspectable — but not through an ordinary message send: anActor inspect (see Navigable Inspector) is itself a send, so it lands in the actor's mailbox like any other and cannot be answered while suspended. sys:get_state/sys:get_status are OTP debug messages, not gen_server calls — they bypass the mailbox entirely, which is what makes a suspended actor's state genuinely readable (via the Erlang FFI gateway, or external tools — observer, recon). Fixing the hook and reloading again re-suspends idempotently and, on success, resumes the actor at the new shape:

Cart reload            // migrateFromV1: still raises
// => Cart
Erlang maps get: #items from: (Erlang sys get_state: cart pid)
// => #(3, 4)     // state survives, still v1-shaped — an ordinary send to
                   // `cart` would time out instead; `sys:get_state` bypasses
                   // the mailbox

// ... fix the hook, save ...

Cart reload             // migrateFromV1: now succeeds
// => Cart
cart getTotal            // now answers on the new shape
// => 7

A synchronous caller blocked on the suspended actor simply times out with the usual structured timeout error until the author fixes the hook (or kills the instance) — the actor never silently continues on a wrong-shaped map, and nothing is lost in the meantime. See ADR 0123 for the full design, including the runtime-only versioned envelope (pack/1/unpack/1) that the persistence and distribution ADRs will consume — not yet exposed as a Beamtalk-callable method — and the reload-time tooling findings (§4).

Extension Methods (Open Classes)

The >> syntax adds methods to existing classes without redefining them (ADR 0066). Extensions work on any class including built-in value types.

// Instance method
String >> shout => self uppercase ++ "!"

// Class-side method
String class >> fromJson: s => // ...parse JSON string

// Keyword method with typed parameter
Array >> chunksOf: n :: Integer => // ...split into n-sized chunks

// Binary method
Point >> + other :: Point => Point x: self x + other x y: self y + other y

Type annotations on extensions

Extensions support the same -> ReturnType annotation as regular methods. Additionally, extensions accept :: -> ReturnType as a visual separator between the selector and return type — especially useful on unary methods where there are no parameters to carry :: annotations.

// Standard return type syntax (same as inside a class)
String >> reversed -> String => self reverse

// Extension-style: `:: ->` separates selector from return type
Integer >> factorial :: -> Integer =>
  self <= 1
    ifTrue: [1]
    ifFalse: [self * (self - 1) factorial]

String >> words :: -> Array => self split: " "

// Typed parameters with :: -> return type
Map >> at: key :: String put: value :: Integer :: -> Map => // ...

Both forms are equivalent — the return type flows to the type checker identically. The :: -> form is preferred for unary extensions; the -> form is preferred when parameters already have :: annotations (to avoid consecutive :: tokens).

Cross-file extensions

Extensions can target classes defined in other files or in stdlib. The compiler registers each foreign extension at module load, so it dispatches at runtime just like a same-file extension. Class-side extensions register under the metaclass tag (String class).

// In helpers.bt — String is defined in stdlib, not this file
String >> shoutIt => super printString uppercase ++ "!"

// Class-side foreign extension
String class >> banner => "=== String ==="

Workspace and Reflection API

Beamtalk exposes system reflection and workspace operations as typed message sends to class-side facades (ADR 0040, ADR 0129). Beamtalk, Workspace, Transcript and SystemNavigation are ordinary sealed, stateless classes: every operation is a class sealed method sent to the class itself, there is no instance to construct, and Beamtalk new (etc.) is a compile error. They are not injected names, so they resolve exactly like Integer does and mean the same thing in the REPL, beamtalk run, beamtalk test and releases. There is no current, default or singleton accessor to call first.

Facts about the BEAM node or the running program are on Node and Program, and logging control is on Logger; none of these are on Beamtalk.

Beamtalk — System reflection

Provides access to the class registry, documentation and release provenance. Analogous to Smalltalk's Smalltalk global. Works everywhere, with no workspace.