reaktor-graph Refinement Plan

Sharpening the graph framework toward an expressive, layered, React/Actor-grade runtime.

✜ 1. Principles

Every refinement in this document is judged against these four constraints. When they conflict, the order is the tiebreaker: an expressive primitive beats a simple one; a simple primitive beats a clever one; a clever one-shot API beats nothing only when it is also expressive.

✓ 2. Snapshot — What Already Works

Before proposing changes, lock in what we keep. The runtime has earned the following load-bearing decisions:

The skeleton holds. Everything below adds tissue; nothing replaces a bone.

✗ 3. Diagnosis — Where Expressiveness Leaks

Findings from a sweep of bestbuds/modules/app and bestbuds/modules/engine, cross-referenced with the framework source.

• D1 — RouteBinding subclasses are pure plumbingChatScreen.kt:77, BestBuds.kt:139
  Every navigable screen declares a RouteBinding subtype solely to hold cross-route NavigationEdge references in constructor parameters. The class never carries logic.
• D2 — exposePort chains repeat 3–10× per graphBestBuds.kt:389–411, WorkbenchGraph.kt:163–167
  Every node that should be reachable from sibling graphs needs .apply { exposePort(myPort) }. The intent ("I am exposed as T") is declarative; the call is imperative.
• D3 — by consumes<T>() bloat on actorsChatActor.kt:32–55
  Heavy actors declare 6–10 individual consumes delegates plus getters. autoWire() would handle most of these, but the developer still has to spell them out because the actor needs typed references.
• D4 — MutableStateFlow sprawl in controllers/interactorsChatSessionStateInteractor.kt:27–46
  A single interactor declares six independent StateFlows with manual field = MutableStateFlow(...). There is no reducer composition, no useState-equivalent, no derived selectors.
• D5 — Lifecycle ↔ effect adhesion at the UIChatScreen.kt:44–54
  Every screen pairs LaunchedEffect(payloadKey) with DisposableEffect(Unit){ onDispose { ... } } to track route enter/exit. The framework already runs lifecycle phases; the UI duplicates them by hand.
• D6 — Container selection state hand-mirroredBestBudsContainers.kt:66–135
  BottomNavigationContainer overrides activateGraphForRoute just to keep a MutableStateFlow<String> selected in sync. Every container variant repeats this glue.
• D7 — Generic type information lost at the port boundaryportgraph/port/Type.kt, registerProvider
  Type<Map<String,Int>>() collapses to Type("Map"). Two semantically different ports become indistinguishable to autoWire.
• D8 — Reply<R> ask ceremonyActorNode.kt:109–125
  Every actor message that supports request/response must thread a Reply<R> through the sealed message class. The call site is clean (ask { reply -> Msg.Query(reply) }); the schema isn't.
• D9 — Routes pushed imperatively, no route table or guardsRouteNode.kt, Graph.addRoot
  There is no declarative inventory of "what routes does this graph have, and what protects them?" Deeplinks and auth gates have to be re-derived per call site.
• D10 — Property delegation as a substitute for module compositionWorkbenchGraph.kt:127–145
  Engine code re-exposes child-graph services via thirty hand-written get() = shell.xyz lines. There is no notion of a sub-graph contract or module re-export.
• D11 — Edge constructor mutates port state in initportgraph/edge/Edge.kt
  No transactional rewiring. A listener that throws leaves the graph half-connected. Connect failures cannot be batched/rolled back.
• D12 — No stream-shaped port; everything is a method callport/ProviderPort.kt
  Reaktor uses StateFlow and SharedFlow everywhere but the port layer has no notion of an observable port. Consumers re-derive Flow plumbing per use site.

⧉ 4. Mental Model — Five Layers

The refinements organize into five concentric layers. Each one is small and orthogonal; each can be adopted independently. Lower layers know nothing about higher ones.

⦿ 5. Layer 0 — Atomic Primitives

These are the cells the higher layers are built from. Each one is independently testable and ~50–200 LOC.

inline fun<reified T> Type() = create(T::class)
// Type<List<String>>() ≡ Type<List<Int>>()

inline fun<reified T> Type() = Type(typeOf<T>())

data class Type(val kType: KType) {
    val raw: KClass<*> get() = kType.classifier as KClass<*>
}
// Type<List<String>>() ≠ Type<List<Int>>() ✓

class Wiring(private val graph: Graph) {
    private val pending = mutableListOf<Pair<ConsumerPort<*>, ProviderPort<*>>>()
    fun<T> add(c: ConsumerPort<T>, p: ProviderPort<T>): Wiring = apply { pending += c to p }
    fun commit(): Result<List<Edge>> { /* validate all, then apply */ }
}

// usage
graph.wire {
    chatActor.operations to operationsInteractor
    chatActor.timeline   to timelineInteractor
}.commit().getOrThrow()

interface LifecycleAware {
    fun onTransition(prev: Lifecycle, next: Lifecycle) {}        // sync, optional
    suspend fun onTransitionAsync(prev: Lifecycle, next: Lifecycle) {} // async, optional
}

sealed interface Behavior<M : Any> {
    object Same : Behavior<Nothing>
    object Stopped : Behavior<Nothing>
    class Receive<M : Any>(val fn: suspend ActorContext<M>.(M) -> Behavior<M>) : Behavior<M>
    class Setup<M : Any>(val fn: suspend ActorContext<M>.() -> Behavior<M>) : Behavior<M>
}

val chatActor = behavior<ChatMsg> {
    receive { msg -> when(msg) {
        is ChatMsg.Open  -> { ops.load(msg.id); become(open(msg.id)) }
        is ChatMsg.Close -> Behavior.Stopped
        else             -> Behavior.Same
    }}
}

◇ 6. Layer 1 — Port Shapes

Today every port is a value provider. Consumers call into the value directly. This works for repositories and interactors, but everywhere else the team rebuilds Flow/Channel/Deferred plumbing on the call site. Five port shapes cover >95% of real usage.

Port-shape declaration DSL

The by provides<T>()/by consumes<T>() delegates stay for the ValuePort case; new delegates layer in next to them.

class ChatSessionInteractor(graph: Graph) : BasicNode(graph) {

    // L1 — declarative state, single line
    val chatState   by state<Data<Chat>>(Data.Loading)
    val messages    by state<List<ChatMessage>>(emptyList())
    val presence    by state<Map<String, ChatPresence>>(emptyMap())

    // L1 — declarative downstream event channel
    val typingEvents by stream<TypingEvent>()

    // L1 — declarative request endpoint
    val sendMessage  by request<DraftMessage, SentMessage>(retry = backoff(3))

    // L1 — declarative inbound mailbox; auto-wired by actor key
    val chatActor   by mailbox(chatActorKey)
}

⚛ 7. Layer 2 — Reactive Nodes (Hooks & Behaviors)

With Layer-1 port shapes in place we can express two of the most useful organism patterns: React-style hook nodes and Akka-style behavior actors. Both compile down to existing concrete Node subclasses; both are entirely optional.

7.1 Hook nodes — React-flavored controllers

React's reducer pattern (useReducer + useEffect + useEvent) cleanly separates what state we have from what events change it and what side effects happen. Today every interactor reimplements this poorly. Wrap it once:

val chatController = graph.controller<ChatState, ChatEvent>(
    initial = ChatState.Loading,
    label = "chat",
) {

    // reducer: events ➜ next state
    reduce { state, event -> when(event) {
        is ChatEvent.Loaded   -> ChatState.Ready(event.chat, event.messages)
        is ChatEvent.Typed    -> (state as? ChatState.Ready)?.addMessage(event.msg) ?: state
        is ChatEvent.Disposed -> ChatState.Loading
    }}

    // effect: state transitions trigger IO
    effect(on = { it.chatId }) { state ->
        if (state is ChatState.Loading)
            sendMessage(DraftMessage(...))   // RequestPort call
    }

    // derived selector: re-derive only on dependency change
    val unreadCount = derived { state -> state.messages.count { !it.read } }

    // lifecycle: bound to node Attaching/Saving
    onEnter { chatActor.send(ChatMsg.Open(payload.chatId)) }
    onLeave { chatActor.send(ChatMsg.Close) }
}

What we get:

• One reducer instead of six independent MutableStateFlows. Fixes D4.
• Effects scoped to dependency keys — React's useEffect deps, but built on StateFlow. Fixes D5.
• onEnter/onLeave bound to the node's lifecycle, not the screen's DisposableEffect. The UI layer becomes a thin renderer of state.collectAsState().

The result is a ControllerNode<State> with a StatePort<State> already exposed — readable from Compose, from sibling nodes, and from tests, without any new glue.

7.2 Behavior actors — Akka Typed-flavored mailboxes

Inspired by L0.4, this is the high-level surface for the same primitive:

val chatActor = graph.actor<ChatMsg>(key = chatActorKey) {

    setup {
        // preStart equivalent — runs before first message
        operations.connect()
    }

    receive<ChatMsg.Open> { msg ->
        chatState.update { ChatState.Loading }
        val chat = sendMessage(DraftMessage(...))
        chatState.update { ChatState.Ready(chat) }
    }

    receive<ChatMsg.Close> {
        Behavior.Stopped
    }

    supervise {
        on<NetworkError> { ActorDirective.Restart }
        default            { ActorDirective.Escalate }
    }

    teardown { operations.disconnect() }
}

Three wins:

• Per-message handlers instead of one when-statement receive — better IDE jump, smaller diffs.
• Supervise block declares directives by exception type instead of overriding onFailure. Fixes the lack of structured error handling.
• The ask pattern stays the same at the call site (ask<Out>(timeout) { reply -> Msg.Query(reply) }), but request-shaped messages can be expressed as RequestPort instead. Sidesteps D8 for the common case.

7.3 exposed { } — one place declares the node's public surface

The current exposePort() chain (D2) is the worst offender for ceremony. Replace with a node-local exposed { } block, evaluated once at attach time, that registers ports into the parent graph's DI scope:

Node(::ConfigRepository).apply { exposePort(configRepository) }
Node(::StickerRepository).apply { exposePort(stickerRepository) }
Node(::SessionHydrationInteractor).apply {
    exposePort(sessionHydrationInteractor)
}

class ConfigRepository(g: Graph) : BasicNode(g) {
    val repo by state<Config>(Config.Default)
    exposed { +repo }   // one line, declarative
}

// parent graph:
Node(::ConfigRepository)
Node(::StickerRepository)
Node(::SessionHydrationInteractor)

↪ 8. Layer 3 — Routing & Container Idioms

8.1 Declarative route tables (D1, D9)

A route table co-locates pattern, payload type, screen, and guards. RouteBinding subclasses disappear — their only job was to carry edge references, which the table holds globally.

val routes = routes {

    route<ChatPayload>("/chats/{id}") {
        screen = ::ChatScreen
        controller = ::ChatController
        guard { auth.user.value != null }
        onEnter { actor.send(ChatMsg.Open(payload.chatId)) }
        onLeave { actor.send(ChatMsg.Close) }

        navigatesTo("/profile/{userId}")
        navigatesTo("/groups/{groupId}")
    }

    route<FriendProfilePayload>("/profile/{userId}") {
        screen = ::FriendProfileScreen
    }

    deeplink("bestbuds://chat/{id}") to "/chats/{id}"
}

graph.install(routes)

The routes DSL is just data — it compiles down to RouteNode instances plus a registry. The runtime can answer questions previously impossible:

• "What deeplinks does this app support?" → iterate registry.
• "What routes are protected by auth?" → filter on guard.
• "From /chats/{id}, where can the user go?" → navigatesTo edges.
• "Generate a debug nav graph picture" → render registry as graphviz.

8.2 Typed result returns (refines D8 for navigation)

Current back(result: R) erases R to Any. Make the return type part of the route declaration:

route<PickStickerPayload, PickedSticker>("/picker/sticker") {
    screen = ::StickerPickerScreen
}

// caller:
val picked: PickedSticker = routeBinding.pushForResult(stickerPickerEdge, ...)

// callee:
routeBinding.back(PickedSticker(id))   // type-checked at compile time

8.3 Container with reactive selection (D6)

Today every ContainerNode subclass mirrors the active child into its own MutableStateFlow. Push that into the base class:

abstract class ContainerNode(graph: Graph, ...) : Node(graph) {
    val selectedKey: StateFlow<String>     // driven by activateGraphForRoute
    val activeGraph: StateFlow<Graph?>     // derived
    fun select(key: String): Boolean       // reverse: programmatic switch
}

BottomNavigationContainer drops its 70-line glue and becomes:

class BottomNavigationContainer(g: Graph, p: String, c: Map<String, ChildGraph>)
    : ContainerNode(g, p, c.values.map { it.graph }) {
    val controller by provides<Controller>(Controller(selectedKey))
}

8.4 Modules — reusable subgraph contracts (D10)

The engine module's WorkbenchGraph re-exports thirty properties from a child shell graph. The framework should know about this pattern. A module is a subgraph plus a public contract:

val messagingModule = module {
    provides<MessagingApi>()
    provides<PresenceTracker>()
    consumes<AuthSession>()
    build { graph ->
        ServiceNode(graph, MessagingServiceClient(Servers.MessagingServer))
        Node(::PresenceTrackerNode)
    }
}

// inside a parent graph:
use(messagingModule)   // one line — wires consumes/provides automatically

Two things to note: (1) the contract is checked at commit time using the L0.2 wiring machinery — missing AuthSession → compile-time-quality error; (2) modules nest: a module can use(otherModule).

⚘ 9. Layer 4 — Module Composition & Supervision

9.1 Supervision trees rooted in the graph hierarchy

actorSupervisorStrategy is currently a flat per-graph function. Promote it to a tree:

Concretely: every ActorNode can declare its own supervise { } block (already in Layer 2.2). When a directive is Escalate, the failure walks up the graph parent chain until handled. This mirrors Erlang's supervisor hierarchies and gives operators a single tunable.

9.2 Cross-graph mesh — explicit named edges

The current cross-graph forward works but is invisible: NavigationEdge.isCrossGraph is a derived boolean and the bubble-up is unwritten. Make cross-graph edges a first-class concept:

val crossEdge: CrossGraphEdge<ChatPayload> = chatGraph.routes.chatRoute crosses rootGraph.routes.chatRoute

This gives us a registry the workbench/devtools can render and the runtime can validate at startup. Today, a typo in a target graph silently fails at runtime with a Logger.w.

9.3 Visitor with mutation — framework-level transforms

The visitor pattern is read-only. Add a MutatingVisitor that returns a GraphPatch instead of side-effecting. A devtools "rewire" command, a hot-reload swap, or a feature-flag-driven node swap all become structured operations that the wiring machinery (L0.2) can apply atomically.

✍ 10. End-to-end Walkthrough — ChatGraph Re-imagined

What does a real screen look like once all five layers exist? Here is BestBuds' ChatGraph (which today spans ~80 lines plus three separate RouteBinding classes plus a manually wired actor).

// BestBuds.kt:128-179
class ChatGraph(parent: Graph?) : Graph(parent, label = "Chat") {
    val chatRoute: RouteNode<ChatPayload, ChatBinding>
    val friendProfileRoute: RouteNode<FriendProfilePayload, FriendProfileBinding>
    val groupProfileRoute: RouteNode<GroupProfilePayload, GroupProfileBinding>

    init {
        Node(::MessageRepository)
        Node(::ChatSessionOperationsInteractor)
        Node(::ChatSessionStateInteractor)
        Node(::ChatTimelineInteractor)
        Node(::ChatAnalyticsInteractor)
        Node(::ChatSocketInteractor)
        Node(::ChatTypingInteractor)
        Node(::ChatActor)

        friendProfileRoute = Route("/profile/{userId}") { FriendProfileBinding() }
        groupProfileRoute  = Route("/groups/{groupId}") { GroupProfileBinding() }
        chatRoute = Route("/chats/{id}") {
            ChatBinding(
                friendProfileEdge = it.edge(friendProfileRoute),
                groupProfileEdge  = it.edge(groupProfileRoute),
            )
        }
        Node(::ChatScreen)
        Node(::FriendProfileScreen)
        Node(::GroupProfileScreen)

        autoWire()
        addRoot(chatRoute, Payload())
    }
}

// + ChatBinding (5 lines), FriendProfileBinding (3), GroupProfileBinding (3)
// + ChatActor with 6 manual `by consumes<T>()` declarations
// + ChatSessionStateInteractor with 6 manual MutableStateFlow fields

val chatModule = module(label = "Chat") {

    // 1. Sub-nodes are normal — Layer 2 conventions remove boilerplate inside each.
    +MessageRepository()
    +ChatSessionOperationsInteractor()
    +ChatSessionStateInteractor()      // uses `by state` from L1
    +ChatTimelineInteractor()
    +ChatAnalyticsInteractor()
    +ChatSocketInteractor()
    +ChatTypingInteractor()

    // 2. The actor is a behavior block — no subclass, no consumes ceremony.
    actor<ChatMsg>(chatActorKey) {
        setup { operations.connect() }
        receive<ChatMsg.Open>  { msg -> state.update { Loading }; ops.load(msg.id) }
        receive<ChatMsg.Close> { Behavior.Stopped }
        supervise { on<NetworkError> { Restart } }
    }

    // 3. Routes are declarative; navigation targets are listed inline.
    routes {
        route<ChatPayload>("/chats/{id}") {
            screen = ::ChatScreen
            controller = ::ChatController
            onEnter { actor.send(ChatMsg.Open(payload.chatId)) }
            onLeave { actor.send(ChatMsg.Close) }
            navigatesTo("/profile/{userId}")
            navigatesTo("/groups/{groupId}")
        }
        route<FriendProfilePayload>("/profile/{userId}") { screen = ::FriendProfileScreen }
        route<GroupProfilePayload>("/groups/{groupId}")   { screen = ::GroupProfileScreen }
    }
}

// somewhere up in App.kt
use(chatModule)

↻ 11. Migration — Additive Path

Every layer is additive: nothing in this plan deletes or replaces an existing API. The migration story is one of opt-in, screen by screen.

⊘ 12. Non-Goals

? 13. Open Questions

1. How far does structural KType matching go? Exact equality is safe but rigid; subtype matching (List<String> accepts ArrayList<String>) is intuitive but requires careful variance handling. Start with exact, add covariance behind an opt-in.
2. Does RequestPort subsume ServiceNode? The handlers in service/* already are request/response. We could deprecate the GetHandler/PostHandler hierarchy in favor of a single RequestPort with HTTP-method metadata. Worth a prototype.
3. How do hook controllers interact with JsExport? Reified-generic property delegates don't always round-trip through @JsExport. May need a parallel controllerJs(...) factory that avoids reified types at the JS boundary.
4. Persistence model for StatePort. ActorNode already has ObjectStore-backed state. Should by state<S>() support an persisted = true flag that automatically rehydrates from the store on Restoring?
5. Cross-graph mesh: validation timing. Layer-4 cross-graph edges are validated at startup. But subgraphs can be added/removed at runtime (tab creation). The wiring needs to support incremental validation without re-walking the whole world.
6. Where does reaktor-react fit? The plan is largely Compose-centric, but a sibling module exists for React. Hook controllers in particular need to translate cleanly to React hooks. Should the controller DSL emit both a Compose and a React adapter?