Reaktor Visual Language (Blueprints)

Reaktor Blueprints let developers compose real application behavior and whole systems through the same definitions they edit in code. Select a feature, create an operation from a typed port, extract reusable behavior, choose a native or cloud implementation, run a concrete scenario and navigate a failure back to source. The visual language is an expert tool inside the Reaktor super-IDE, alongside ordinary Kotlin and other source editors.

The foundation is one Living Graph: a heterogeneous, nested, multilayer logical port graph spanning source, build and runtime. Blueprint behavior is a region with a declared computation profile in that graph. Structure, control, data, authority, deployment and observation are typed relations and facets, not competing graph stores.

1. Vision

The target is the composition and instrumentation power of an engine such as Unreal, applied to general software development. Module authors expose useful operations, types, actors, state, services, UI, target bindings, tests and instruments through ordinary APIs. Developers and Claude/Codex compose those contributions into applications without rebuilding their glue for every project.

Four connected activities matter:

1. Create and extend applications. Compose UI behavior, data, auth, offline intent, native computation and cloud services; retain arbitrary source where a library cannot express the product's needs.
2. Make reusable abstractions. Extract functions and full-stack compositions with explicit interfaces, source ownership and instance state. A feature can expose a visual API while its implementation remains hand-written Kotlin, native code or an imported service.
3. Inspect a concrete execution. Follow data, actor turns, requests, native calls and effect outcomes for a selected revision and activation. Step only where the target supports stepping.
4. Change the whole feature coherently. A capability choice can update bindings, placement, source, UI fallbacks and tests together. Preview the affected closure, validate the supported claims and follow the resulting artifact through deployment and observation.

The graph language does not replace Kotlin with a closed catalog of nodes. Ordinary Kotlin is a full-power authoring path. Explicitly reified behavior regions offer an additional visual syntax, instrumentation and stronger checks under named semantics.

2. What exists and what needs integration

The work is broader than attaching an evaluator to a viewer: source ownership, identity, executable semantics, editor commands, target adapters and observed evidence have to agree.

3. Design constraints

1. One logical graph; extensible modules. Blueprint definitions, calls, execution relations and observations refer to the canonical identity fabric. Keep the semantic nucleus small; introduce a core mechanism only when several domains require it, rather than declaring the current API permanently sufficient.
2. Source ownership is explicit. Ordinary source remains owned source. A reified Blueprint region has one declared textual or structured source owner and generated artifacts. The canvas never silently chooses between two editable truths.
3. One command contract. Human gestures, keyboard actions and agents use the same applicability checks, preconditions, authority, validation and receipts. Layout changes, source commits and runtime operations remain distinct kinds of command.
4. Pure analysis, explicit execution. Visitors inspect snapshots and produce findings, derived facts or plans. An interpreter, actor adapter or operation executor performs effects under its runtime profile. Calling execution a pass does not remove its scheduling or failure semantics.
5. Ports carry protocols. Contract identity is necessary context, not sufficient compatibility. Type/schema, direction, ownership, multiplicity, cancellation, buffering, authority and effects matter at the boundary.
6. Deterministic tools, qualified runtime claims. Stable queries, serialization and layout help reproducibility. Runtime determinism additionally requires declared inputs, ordering, state and effect assumptions.
7. State has an owner. Function locals, controller state, actor-owned state and external resources have different lifetimes and concurrency rules. Actors are valuable state/concurrency boundaries, not a requirement that every local variable become an actor.
8. Projection layers compose. Scope, semantic layers, detail, revision/time and authoring/debug mode are independent. A graph can show structure, state/effects, runtime evidence and an agent proposal together.
9. Authority follows grants. Agents and humans may perform the same operations when granted the required scope. Routine granted edits and checks need no extra approval ceremony; sensitive operations depend on effective policy and the exact proposed effects.
10. Physical packaging remains modular. App runtimes need not import cloud/IDE implementations. Their definitions and observations still participate in the same logical system graph.

4. Visual grammar: what the canvas means

4.1 Composable layers over one graph

These are composable selections of typed facts. Their ordered query stack may filter, expand, group and analyze; changing order can change the result and must be explicit. A hidden layer does not erase an edge or its effects. Source detail and trace detail can remain open in other editor groups with independently pinned context. See hierarchical UI.

4.2 Cards, pins and wires

A node card shows a concise title, semantic family, source owner and applicable state. Its inspector exposes stable identity, definition revision, selected activation, contracts, findings and commands. Color supports meaning; labels, icons and line styles provide the same distinctions without color.

Data, control, containment, binding and observation wires are different relations. A wire identifies exact endpoint ports, direction and mapping; a folded bundle retains all member IDs and a way to inspect them. A dependency arrow consumer-to-provider and a value arrow provider-to-consumer must have an explicit legend.

An exec connection selects an ordered control continuation. A request is a protocol interaction with completion and error semantics. A stream is not a repeated synchronous call, and a mailbox is not a remote object pointer. The pin inspector states what happens when no input is available, a queue fills, an invocation fails, cancellation arrives or an observer disconnects.

Road grammar and family grammar

The system map draws every relation as a road whose class is carried by its line pattern, endpoint shape and label, so the grammar survives high contrast and colour-blind viewing. Colour follows the edge palette but is secondary. One visual language connects the classes without erasing their failure, ordering, lifetime or completion differences: a dependency arrow is not an invocation, and a short road is not an execution route.

A route is drawn in one of four modes: declared (accent underlay), candidate (Δ44, dashed outline), simulated (amber) and correlated (green, up to the observation cursor; unknown beyond it, never traffic). A bundle between two scopes is presentation only: it keeps the member relation IDs, endpoint roles and multiplicity and opens into its members on selection. Ports remain visible where a route enters or exits a scope; a wire never terminates on a container edge.

Family grammar. Node kinds use the MachineSignal entity palette (MachineSignal.Entity in reaktor-ui/machinesignal, transcribed from the design file): service, interactor, repository, route, screen, actor, container, cloud, topic, auth, agent, infra and native. The kind badge and icon carry the family; the card stroke is the line token unless the card is selected (accent) or carries a status (stale, danger, live). Before the 7 September 2026 map iteration a service was orange on one BestBuds board and cyan on another, and interactors changed from purple to orange between boards because relation colours had been reused for families; the shared Graph / Typed node component now applies the palette, and a verification pass normalised every instance (111 kind badges and 47 strokes across 13 boards). The Map / Road Legend component in the design file reproduces this table.

4.3 Gestures are commands

Preview, validation, commit and reconciliation share the command API. A local model commit can have atomic undo; an external cloud call or already-sent message cannot be undone by reversing its canvas wire. Compensations and reconciliation are explicit operations with possible failure.

Typed holes are saved and inspectable incomplete inputs. A partial program can have meaningful types and diagnostics while remaining ineligible for a runnable artifact.

4.4 A connected BestBuds example

The whole-system atlas uses a media-message feature. The source-backed path uploads media through MediaUploader and MediaWorker to R2, obtains a URL, then submits the message through SessionInteractor, ChatActor and the messaging Worker to Postgres. A returned stored-message result is relayed through the chat Durable Object path. Relay is not a recipient receipt, and current blob upload plus message publication is not one atomic transaction.

A proposed offline strategy can add durable intent/outbox state, native processing, explicit retry/idempotency handling, staged publication and analytics projection. The composition command must connect those changes to the same UI journey, auth boundaries, source, FFI contracts, providers and tests. The graph's value is being able to design and validate that change as one feature, while retaining the actual boundaries.

5. The execution gap

Current graph wiring establishes object dependencies and some domain-specific transfers such as navigation and actor messages. It does not establish a universal rule for executing arbitrary connected nodes. A static provider/consumer edge cannot simply be reinterpreted as pull-data, a stream, a transaction or a durable workflow.

The missing execution work is therefore profile-specific:

• A pure/value region evaluates data dependencies under a purity and cycle rule.
• A structured behavior region sequences control, local state, calls, loops and recursion.
• An actor region defines mailbox admission, turns, state ownership, failure and activation.
• A stream region defines firing, readiness, buffering, ordering and completion.
• A durable protocol/workflow defines persisted progress, effect identity, recovery and reconciliation.
• Ordinary Kotlin and native regions execute through their existing host semantics and explicit boundary contracts.

An optional interpreter can accelerate live authoring for supported regions. Compiled execution should remain available where performance, platform or deployment requires it. Neither backend alone establishes source equivalence or distributed reliability.

6. Blueprint regions and reusable definitions

BehaviorBlueprintProgram denotes a region/profile over the canonical definition IR. It is not an independently maintained List<BlueprintGraph> store that competes with the application graph. Its view can collect canonical references, entry points, exported interfaces and diagnostics. Runtime frames and queues belong to activations of that definition revision.

// Proposed view contract; references canonical definitions rather than owning copies.
data class BehaviorRegionView(
    val region: DefinitionRef,
    val revision: RevisionRef,
    val profile: ExecutionProfileRef,
    val entries: List<PortRef>,
    val exports: List<BoundaryMappingRef>,
    val findings: List<FindingRef>
)

Useful module vocabulary includes events, pure operations, actions, branch/sequence/loop, variable reads/writes, function calls/returns, actor messages, streams and external operations. These are open semantic interfaces and library contributions, not a closed list of kernel node subclasses.

A function definition has typed parameters/results and call-site instances with separate invocation frames. A reusable composition exports selected internal ports through explicit mappings. A macro expands a template and retains definition/call-site source maps. A visual group has no such executable meaning. An actor or service boundary adds ownership and protocol semantics that grouping alone cannot create.

7. The language and its semantic contracts

This section specifies a proposed executable subset. It does not claim a completed language proof or define all Kotlin by translating it into boxes.

7.1 Two authoring paths, one identity fabric

Ordinary Kotlin and Kotlin DSLs can use arbitrary host-language control flow, abstractions and libraries. Build tooling extracts what is statically known; declared interfaces and runtime instrumentation expose dynamic structure. Unsupported or opaque internals remain source-addressable. They are not rejected merely because a finite pass cannot decide their behavior.

Explicitly reified behavior regions record operations and control constructs as typed canonical definitions. This gives the visual editor a supported edit grammar and the interpreter/compiler a precise input. Deep embedding is one implementation technique for that region, not a rule that all Reaktor Kotlin must be deep-embedded.

Each editable region names one source owner. Text-owned regions use constrained source edits; structured-owned regions generate source artifacts. Migration between owners is explicit. Generated Kotlin is not a second hand-maintained source of truth. Lossless round-trip is tested only for the adapter's supported grammar; arbitrary Kotlin has no promised unique graph-to-source inverse.

7.2 Relations and well-formedness

A structured behavior region has control and value-dependency relations in the same graph. Its pure instantaneous dependency subset is acyclic unless another profile supplies an explicit fixed-point/delay semantics. Its control profile allows well-formed branches, joins, loops and recursion. Other profiles may accept actor feedback or cyclic streams; there is no global DAG restriction.

Static checks establish precise properties: pin direction and interaction compatibility, required inputs or typed holes, selected branches/joins, owned variable access, valid call/result mappings and known execution profile. They do not establish termination, race freedom or successful external effects for arbitrary source.

7.3 Typed Kotlin sketch

The following is illustrative DSL design, not a current API. Declaration and definition are separate so recursion has a valid reference before its body is built. Int is a bounded machine integer; an unbounded-integer type would need its own implementation and target contract.

val factorial = declareBehavior<Int, Int>("factorial")
factorial.define { n ->
    branch(n lessOrEqual literal(1)) {
        whenTrue { ret(literal(1)) }
        whenFalse { ret(n times call(factorial, n minus literal(1))) }
    }
}

val count = declareBehavior<Int, Int>("countTo")
count.define { limit ->
    val i = local(0) // invocation-local state, with declared integer semantics
    whileLoop(i.read() lessThan limit) {
        i.write(i.read() plus literal(1))
    }
    ret(i.read())
}

The visual syntax can create the same supported definitions and call sites. Hand-written functions outside the region remain ordinary callable source with an explicit contract. Their body need not be regenerated by the visual editor.

7.4 Types, effects and holes

A ContractId names a versioned contract; payload types, schema compatibility and interaction profiles supply the actual connection rules. Nominal equality, declared schema evolution, generic constraints and explicitly implemented conversion are distinct. A registered conversion is a callable adapter, not a subtype proof. A top type such as Any must not silently bypass a remote schema or capability boundary.

Pure operations consume immutable values and have a qualified no-effect contract. Reading mutable state has a state/version dependency even if it performs no write. Time, randomness, host queries, I/O and callbacks must be explicit inputs/effects for a reproducibility claim. A library annotation alone is a declaration to validate or trust, not a proof.

A missing required pin carries a typed-hole finding. The editor supports incomplete artifacts; the selected build/run profile determines whether that hole prevents execution or has an explicit fixture/default semantics.

7.5 Evaluation, state versions and invocation frames

For a single sequential behavior region, an evaluator state can be described as (definition revision, activation, invocation frame, control position, local store, continuation stack, pending effects). Function calls allocate fresh parameter/local environments and return into the caller's result bindings. Recursion does not share one unqualified global variable map.

Demanding a data input evaluates its dependencies for the current input and state versions. A pure operation can cache by its operation revision and immutable input values/versions. A state read supplies both value and owner/version dependency. Invocation/frame identity is part of a cache key wherever values are frame-dependent. Untracked state or opaque effects disable the relevant cache optimization.

This matters for a basic counterexample: i = 0; while (i < 3) i++. Memoizing the comparison once for the entire activation retains the first true forever. Updating i must invalidate the dependency or produce a new explicit value/state token before the next condition evaluation. “Once per activation” is not a sound general evaluation rule.

Control transitions consume the selected continuation. A suspending action records a pending invocation; success, failure, deadline and cancellation follow declared continuations. Completion from an obsolete activation cannot mutate its replacement. Effects are associated with an operation identity and observable outcome, rather than assumed complete when a token advances visually.

7.6 Turing completeness and decidable profiles

The proposed general Kotlin/behavior profile must be Turing-complete in the usual unbounded-memory language model. It supports structured control, general loops, recursion and dynamic data structures through reified graph control/data/state or source-backed computation. This is an explicit expressiveness requirement for the language and its conforming backend, not a claim proved by the bounded-Int example above. Actual Kotlin targets have finite memory, bounded numeric types and host limits, with execution budgets appropriate to the target. Finite DAG/protocol subsets provide stronger decidable checks without limiting the general graph language.

Checks remain stratified. Finite workflow/protocol models can support bounded model checking. Pure acyclic regions can support precise dependency evaluation. Selected stream profiles can support stronger scheduling analysis. Arbitrary Kotlin can still be tested, profiled, reviewed and partially analyzed without promising a complete decision procedure for termination or correctness.

A general loop or recursive function cannot be lowered to a finite workflow DAG while preserving unrestricted behavior. The compiler either selects an appropriate general-code backend, uses an explicit bounded unrolling with that bound recorded, or reports that the selected workflow target cannot represent the region.

7.7 Concurrency, streams and durability

Actor-owned state can serialize declared turns. Invocation-local state stays local; controller state follows its UI/thread owner. Structured forks define child ownership, join behavior, cancellation and failure propagation. They do not prove race freedom if an arbitrary callback, foreign pointer, shared cell or external resource bypasses those rules.

A stream profile states trigger/non-trigger inputs, readiness, correlation, buffering, backpressure, end-of-stream and failure. A join inspector must explain which input is missing and what can resolve the wait. Synchronous dataflow scheduling results require its declared rate assumptions; Kahn-style determinacy requires its process/channel assumptions. Neither applies automatically to a bounded actor mailbox or nondeterministic cloud response.

A local actor with an ObjectStore does not by itself implement a durable workflow. Durable progress requires defined persistence/transaction boundaries, effect intent and identity, duplicate handling, retry policy, recovery and reconciliation. A Pub/Sub ordering key does not supply atomic publication or exactly-once external effects. See actors, distributed actors and Living Graph boundaries.

7.8 Reference semantics and backend conformance

The profile specification is the contract. An interpreter can provide a reference implementation for its supported subset; generated Kotlin, actor execution or a workflow adapter must pass conformance and differential tests over that subset. The reference implementation can itself be wrong, so counterexamples and independent checks remain valuable.

An interpreter is a real execution engine, with frame/state management, scheduling, cancellation, errors and resource limits. Reuse coroutines, actors and established host mechanisms where appropriate; do not hide that implementation work behind the phrase “just a visitor.”

8. The editor: coordinated source, graph and execution

The editor extends the existing local document/session machinery through explicit adapters. A render scene is a read model; it retains canonical IDs, source maps and supported operation descriptors. The same source command can originate in the canvas, command search, an editor refactor or an agent request.

The persistent workspace includes project/symbol explorer, editor groups, breadcrumbs, layer stack, selected-port details, input/output inspector and tool windows for problems, run output, tests, debug and Conductor. It supports drag-from-port creation, keyboard equivalents, precise mappings, reusable extraction, semantic diff and source navigation. A graph is one expert editor among peers.

Each editor may follow the working copy or pin a definition/artifact revision, activation and time cursor. Switching the active deployment target must not relabel an old trace as a current execution. A watch distinguishes not executed, value observed, stale, redacted and observer unavailable. A breakpoint names the paused process/activation; it does not stop every island. Recorded traces offer event navigation, not fake live stepping.

“Run selection” produces a plan showing prerequisite work, chosen inputs, fixture substitutions, state origin, allowed effects and target. Promoting recorded output to a fixture creates a separate versioned artifact with provenance/redaction; it does not mutate production data. Re-running a local pure transform should not accidentally repeat an unrelated upload or message publication.

Layout is non-semantic and can be manual or computed. Incremental updates preserve unaffected positions, selection and expanded scopes; full auto-layout is explicit. Large regions use scope, layer filters, summaries and bounded expansion rather than rendering the whole system. See hierarchical UI.

From visible product to the full graph

Inspecting a rendered DOM or Compose element reveals its exact component instance, source/binding and handler mappings, then highlights the operations, state/effects, dependencies and resources implementing that behavior. Choose an event when the element has multiple or delegated handlers. A reused component keeps definition and rendered-instance identities separate; a partial/generated/opaque mapping is labeled instead of guessed.

That selection becomes a named graph route. Follow Capture intent, Send/upload, Completion/return, Notification or Analytics branches while zooming continuously from application/fleet to island, feature, node and port. The same route and source selection persist across scale; folded boundaries retain exact entry/exit mappings. UI navigation, a service call, an FFI exchange and actor feedback remain different typed relationships in that route.

The continuous navigation contract defines scale bands, stable layout and source/preview synchronization. Scope restricts query and work budget independently of camera zoom; viewing a whole system does not require loading every runtime event. A recorded route follows actual invocation/correlation evidence. An animated static topology is not execution evidence.

9. Compilation, interpretation and change plans

A compilation pipeline queries a fixed definition revision and produces checked artifacts. Proposed stages include boundary/schema validation, profile validation, ownership/effect checks, control/data analysis, instrumentation/source maps and target lowering. Each stage reports its inputs, coverage, assumptions and stable findings through the pass contract.

The pipeline separates:

1. Source normalization and semantic changes owned by source adapters.
2. Pure analysis and planning over immutable graph snapshots.
3. Build/code generation for a named target/profile and exact source closure.
4. Activation preparation including compatibility, state migration and effect scope.
5. Runtime execution and reconciliation producing observed evidence.

A model commit is not an application activation. Reversible local changes need no universal deployment ceremony. Tests, simulations, shadow replay, bounded proofs and production observations are selected where they establish relevant claims; shadow replay is not a prerequisite for every edit or possible for every opaque external effect.

Generated artifacts carry source maps and provenance. Whether checked into the repository or produced by the build is a project policy. They are not independently edited while their declared source owner remains authoritative.

10. Composing the complete ecosystem

One feature can span several profiles and authority domains. UI behavior can call a service, enqueue actor intent, invoke a native transform, publish through a Worker, store authoritative state in Postgres and feed an analytics projection. The graph records the selected bindings and the contracts at every cut. It does not impose one universal scheduler across those systems.

The module contribution surface should combine ordinary API + graph exposure + reusable composition + target/provider adapter + checks + instruments + commands where relevant. A native media module can contribute buffer/lifetime contracts and profile tools; an auth module contributes capability mediation; a cloud adapter contributes resource bindings and deployment operations; an analytics module contributes event schemas and lineage. Their visual tools combine around the selected feature rather than becoming isolated dashboards.

Runtime applications depend on portable interfaces and required runtime code. IDE/cloud tools may own provider inventory, deployment plans and operations. This is a physical dependency boundary inside one logical graph. Provider configuration, selected deployment binding and live observed resource state retain distinct provenance and timestamps.

UI composition likewise joins the same identity fabric. Host/render trees are activation-specific projections with their own rendering semantics; source/design definitions and supported edits have explicit owners. Selecting a screen can open UI composition, behavior, source and preview without inventing unrelated product truths. The react-compose design supplies the host-specific rendering seam.

Compose and execute end-to-end flows

Blueprint orchestration is trigger-independent: headless services, streams, jobs and native computation are first-class, with no UI wrapper required. Entries include HTTP/service/webhooks, queues/Pub/Sub/state changes, schedules/timers, device streams, CLI/operators, agents through MCP/A2A adapters and lifecycle/protocol continuations, as well as UI events. A typed entry/admission contract defines schema mapping, event/correlation identity, auth/grants, acknowledgement, ordering/backpressure and retry/cancellation.

A Blueprint can orchestrate a named route across supported profiles: gather device inputs, select native or remote processing, advance actor-owned intent, call a service, wait for a qualified outcome and trigger downstream notification or analytics. The route remains one composition while each participant retains its actual scheduling, authority, state and failure semantics.

A versioned flow/runbook asset binds reusable entry mappings, typed parameters, profiles, targets, checks and recovery. A flow can join an existing actor/protocol/stream and produce several outcomes or continue indefinitely; it is not necessarily a finite DAG invocation. The run plan exposes exact inputs, selected bindings/targets, prerequisite work, fixture substitutions, state origin, effect identities, grants, budgets and branch/completion conditions. Simulate or run a selected segment without accidentally re-executing unrelated predecessors. Pause/step, drain, cancellation, checkpoint resume and reconciliation are supplied by the relevant adapters; source-defined arbitrary behavior remains available even when it lacks those specialized controls.

Headless ETL, settlement, incident-response runbooks, fleet coordination, deployment/migration and scientific/native pipelines use these same composition and execution interfaces. One important interactive workflow begins at a UI element: explain its offline failure, propose a capability fallback and owned intent protocol, preview source/graph/UI changes, exercise denied permission and lost response, compare latency/privacy/cost, then build and deploy the affected closure. A reusable recipe or agent can perform these same composition operations. The Living Graph route contract defines execution and evidence boundaries.

11. Agentic access

Claude/Codex use the same query and command contracts as the developer. A query names scope, relations, revision/time vector and budget; it returns typed references, findings, witnesses and coverage. A change names preconditions, source owners, added/removed relationships and effect scope. Tool schemas derive from public contracts where supported rather than exposing arbitrary in-process objects.

Useful agent operations include creating a feature from module contributions, finding compatible providers, extracting a composition, explaining a denied path, proposing a placement strategy, repairing a schema migration and narrowing a failed trace to a source change. An impact report includes unsupported regions and alternative derivations. “No affected nodes found” cannot imply no impact after incomplete extraction.

Authority is evaluated for the actual principal, target and operation. Granted source edits, tests and local runs proceed routinely. Deployment and administrative operations are available only under their explicit policy and current grants; there is no blanket rule that agents can never perform them or that only one agent product may apply changes.

Concurrent edits use expected revisions and semantic preconditions. Rebase preserves unaffected identities and recomputes findings; competing provider choices or port deletions surface as conflicts. Layout collaboration can use different merge rules from program semantics. A critic can contribute evidence or a scoped policy decision, but an LLM judgment is not a substitute for type, authority or runtime enforcement.

12. Module ownership

reaktor-blueprint is a proposed packaging boundary for profile definitions, reusable behavior vocabulary, analysis/lowering and optional interpreter support. It should not duplicate every concern in the engine:

The precise dependency split must follow implementation needs. “No kernel change ever” is not a design law; duplicating identity, ports or revisions to avoid a justified shared primitive would be worse.

13. Delivery plan

The roadmap owns dates. December 2026 should prove a useful bounded chain rather than claim the complete language is shipped.

Existing local editing does not wait for a universal mutation engine. Source-backed semantic editing and runtime activation do require their particular adapters and contracts. The long-term design remains general; the first release has a bounded supported surface.

14. Decisions and counterexamples to resolve

• Freeze the first source-owned reified grammar and demonstrate no-op/source-edit round-trip laws without rewriting arbitrary Kotlin.
• Specify numeric, exception, frame, suspension, cancellation and effect-outcome semantics for the first executable profile.
• Test changing loop-state dependencies, recursion frames, cancellation races and duplicate completions before describing backend equivalence.
• Decide when a supported interpreter may ship to a target; OTA/reconfiguration requires target/platform policy and activation compatibility, not a generic canvas switch.
• Test actor feedback, stream waits and opaque native callbacks so profile validation does not become a global DAG or false race-freedom claim.
• Demonstrate that folding/layout preserve the semantic program, while extraction and provider replacement produce inspectable source deltas and obligations.
• Measure incremental evaluation, query coverage, source/graph mapping and canvas budgets on actual feature graphs before adopting a specialized engine.
• Keep source, editor, compiler, runtime and agent contracts coherent as modules evolve; do not mistake design completeness for implementation maturity.

15. Study guide and references

This is the reading and study plan for turning the design into an implementation. It is intentionally opinionated: Unreal Engine Blueprints is the closest analogy, not Scratch, Blockly, Node-RED, or generic low-code tooling. Those systems are useful, but the Reaktor target is closer to Unreal: expert-grade engine primitives, programmer-authored substrate, designer/agent-authored composition, strong type information, live debugging, and code remaining the durable truth.

15.1 Unreal Engine Blueprints: primary analogy

Study Unreal first. The goal is not to copy game-specific concepts, but to copy the durable architecture: C++/engine code exposes a curated surface, Blueprints compose that surface, the editor gives immediate feedback, and production execution is validated/compiled by the engine.

When Unreal source is available, also inspect these source areas:

• Engine/Source/Editor/Kismet - main Blueprint/Kismet editor layer.
• Engine/Source/Editor/BlueprintGraph - editor graph nodes and schema behavior.
• Engine/Source/Editor/KismetCompiler - compilation, validation, skeleton/generated class flow.
• Engine/Source/Runtime/Engine/Classes/Engine/Blueprint.h - UBlueprint asset shape.
• Engine/Source/Runtime/CoreUObject - reflection/object model that makes Blueprint exposure possible.

15.2 Books and chapters

The implementation crosses language design, game-engine tooling, live debugging, and graph algorithms. These are the highest-value books, with the specific chapters/concepts to mine.

Recommended chapter order for implementation:

1. Unreal docs: API exposure, basic editing, debugging, compiler results.
2. Game Programming Patterns: Bytecode, Command, Event Queue, Component.
3. Crafting Interpreters: interpreter semantics, then bytecode/jumps/calls.
4. Engineering a Compiler: IR, semantic analysis, data-flow, code shape.
5. Papers below: typed holes, dataflow, structured editing, visual language surveys.

15.3 Papers, essays, and core concepts

15.4 Systems and open-source projects to study

Unreal is the main model, but these systems each solve one concrete problem Reaktor will face.

15.5 Concrete Unreal-to-Reaktor mappings

15.6 Concepts to define before implementation starts

• Node exposure policy - what makes a Kotlin service, actor, repository, UI action, infra operation, or external API show up in the Blueprint palette?
• Purity contract - how does a module prove or declare PureNode behavior, and how does the interpreter prevent hidden effects?
• Pin contract schema - how does ContractId map to serializer schema, display label, default value editor, validation, and agent tool schema?
• Exec semantics - ordering, reentrancy, async/latent nodes, cancellation, failure, retries, loops, gates, and branch exhaustiveness.
• Typed holes - how unconnected required pins, missing providers, and invalid coercions remain saved editor states with findings.
• Generated source shape - whether the compiler emits Kotlin functions, actor receive handlers, workflow DAG manifests, Pulumi/Dagger operations, or a shared IR first.
• Source maps - how a generated Kotlin line, operation, trace span, or runtime error jumps back to a node/pin/wire.
• Search index - what fields are indexed, how stale indexes are refreshed, and how member IDs survive renames.
• Undo/redo and collaboration - patch identity, region leases, three-way structural merge, and agent/human conflict UX.
• Security and safety - operation safety classes, forbidden scopes, secret redaction, deploy gates, data-access gates, and audit spans.
• Diff and review - textual review for visual source, generated code diffs, layout-only changes, semantic changes, and operation plans.

See also

• Graph Kernel Analysis — the fixed kernel ontology + 10 laws the VPL must respect.
• Reaktor Graph Visitors — passes as the compiler; GraphPatch, Findings, determinism.
• The Reaktor Control Plane — Observe/Call/Change, the mutation spine, permission scopes.
• Reaktor Unified System Graph — whole-product orchestration, desired/observed, SafetyClass.
• Reaktor Actor Model — the execution substrate for stateful behavior.
• Flow Analysis — react-flow / compose-flow / reaktor-flow; the editor's starting point.
• React × Compose Blueprint — the distinct UI-render-tree Blueprint surface.

Related docs

• Graph Kernel - Use to keep the core language small while modules add vocabulary.
• Flow Analysis - Use when shaping flow UI behavior and graph editor affordances.
• Control Plane - Use when exposing Reaktor safely to humans and agents.
• Unified Graph - Use before building Reaktor Engine graph importers, cloud/resource nodes, operation providers, or MCP graph tools.
• UI & Design System - Use before touching reaktor-ui tokens/components/theming, designing the tactile runtime (interaction/physics/field/skins/host-tree/reconciler), or planning adaptive layouts and AI/server-driven UI.
• Reaktor Arena - Use when designing the Unreal-based Arena lab, AI/algorithm playgrounds, scenario replay, debug inspectors, and the future Reaktor-to-Unreal bridge.