xtdb-object-boundaries

# Object roles and boundaries Interpret MUST, MUST NOT, SHOULD, SHOULD NOT, MAY per RFC 2119. **You MUST identify an object's role before you change it, and what state it owns**, and **one object holds one role**: an object that owns a `select` and also holds state others wait on is two objects that have not been separated yet. A role is decided by the control flow an object owns, and confirmed by the state it holds. **XTDB is a functional core with an imperative shell** (Bernhardt, 2012), with autonomy substituted for purity: the shell decides what happens next, the core only does what it was asked. Classify by autonomy, not by side effects — `Log.appendMessage` does I/O and belongs to the core. **Every object is an Active Object, a Passive Object or a Monitor Object** (POSA2, 2000). ## Active Object — it offers a choice among simultaneously-ready events In Kotlin, it owns a `select`. **Test: does it decide *what happens next*, or only *how to do what it was asked*?** - **A subordinate exposes a select clause rather than running a loop of its own**, so the choice stays with the owner. - **The choice makes it active, not the coroutine.** CSP's external choice (`□`) is resolved by the environment, internal choice (`⊓`) by the process; a `select` with several clauses is external choice, occam's `ALT` (Hoare, 1978). - **A long-running loop is not automatically active.** `Log.tailAll` suspends for as long as the tail runs, is driven by one source and offers no choice — passive. ## Passive object — everything it does completes on the caller's coroutine **Test: could it finish if nobody else ever ran?** - **Suspension is allowed.** `Log.appendMessage` is `suspend` and does I/O; the caller asked for the write and gets it back on its own coroutine. - **`coroutineScope { }` stays passive**: it joins its children before returning, so nothing escapes (`runST` — Launchbury & Peyton Jones, 1994). - **The discriminator is mechanical.** `coroutineScope` and `withContext` join, so passive; a stored `CoroutineScope` plus `launch` escapes, so not. A method handing back a `Deferred` that runs on its own object's scope is the shape to spot. ## Monitor Object — passive state that callers wait on State outliving a call, callers suspending on a condition over it, and a signal that wakes them. A refinement within passive, not a third role. **Test: does anyone wait on it?** - **The mutual exclusion is often a single-writer discipline rather than a lock**, so there is no `synchronized` block to spot. `TermFence` is passive state written by one coroutine and read by another with nobody waiting — not a monitor. - **A monitor's condition MUST be re-evaluable: a waiter arriving later MUST be able to reach a different verdict** (Hoare, 1974; Brinch Hansen, 1973). A latching condition is a monitor defect, and swapping the concurrency primitive does not fix it. - **`Watchers` is the monitor to know, and the defect to recognise.** A `MutableStateFlow` over a sealed `Active`/`Failed` pair, one write path, several condition waits over it, and no lock in sight — which is why it read as ordinary passive state for as long as it did. Its `Failed` variant latches: once failed, every later waiter throws, so ingestion failing once left a queryable database unqueryable until the node restarted. A monitor defect rather than a coroutine subtlety, and it would latch identically behind a `ReentrantLock`. ## One value — fixed identity, immutable state, one swap Clojure's epochal model (Hickey, *Are We There Yet?*, 2009): an **identity** is a stable handle, its **state** is the immutable value it holds at one moment, and time is the succession of those states. The same boundary is Evans' **aggregate** (2003) — the unit of consistency, whose invariants are never observably violated — with an atomic swap standing in for the transaction. **Test: name a value the identity holds in between.** Two fields are one value exactly when you cannot. - **The shape is a sealed hierarchy behind one reference, armed with a single `set`** — "Related state SHOULD be updated atomically" in `dev/CODING.adoc` has it. A reader holding a generation cannot observe a mixture of two, which is what makes it safe with no lock to point at. - **A swap function MUST be pure**: a CAS loop may run it more than once. - **Keep the value small** (Vernon, *Effective Aggregate Design*, 2011) — inside goes what must be consistent and nothing else. The placement question is *who must see this change immediately, and who can wait?* - **Needing to swap two identities together means the boundary is in the wrong place.** That is `dosync` over refs: a signal, not a tool. ## Accumulating state is a transient, not an atom A **transient** is mutable, owned by exactly one writer, and MUST NOT be published mid-flight — Clojure's transients, with `runST` (Launchbury & Peyton Jones, 1994) as the formal account. **Test: does anyone read it while it is being built?** - **Nobody** — mutate in place under its owner and hand it over complete. `PendingBlock` accumulates buffered records under the follower that owns it, and is passed on whole. - **Somebody** — it is an atom, and every observable step MUST be a swap. `Watchers`' watermarks move together on each applied record precisely because callers are waiting on them. ## Region and owner - **A region groups by lifetime; a value groups by atomicity.** A region is a node in the lifetime tree (structured concurrency — Sústrik, 2016; Smith, 2018) and may hold values with nothing else in common. A value has one write point. Conflating them buys either a torn read or a region-wide lock. - **A reference MUST NOT outlive its owner** — ownership and RAII, which Rust makes mechanical and we do by hand. State read after its owner is torn down, or read before the join that made it safe, is a dangling borrow. - **Where there is no lock, ownership is a discipline plus safe publication** (Goetz, *Java Concurrency in Practice*): one writer, and the volatile that makes its writes visible to the coroutine reading them.