Nested graphs

A nested graph is a reusable, identified region inside a larger system. Its boundary exports named contracts; its contents retain their own IDs, relationships and source ownership. Expanding or collapsing a frame changes presentation without replacing the definition.

Definition, ownership and activation

A RegionDefinition.parent forms an acyclic containment hierarchy. The runtime Graph(parentGraph=...) separately inherits declared DI/coroutine scopes and owns lifecycle. H19 can state ownership, H20 instantiation, H21 placement and H30 exported aliases. A parent region does not imply one process, global scheduler, tenant grant or shared mutable instance.

Composition law

For an exported boundary contract b, preserve the internal endpoint alias b → (nodeId,portId) and all crossing relation roles. Composition connects compatible exported contracts, namespaces new identities and checks state/authority/resource obligations. It must not silently drop a multi-party incidence or flatten away ownership.

Choosing a deployment cut

A graph partition is a constrained cut, not a visual rectangle. Report every crossing port/relation, required adapter, resource lifetime, state owner, policy scope, target profile, artifact dependency and clock assumption. Optimize only among legal cuts. The code-push visitor in Subgraph views computes eligibility findings; the release controller performs separately admitted changes.

A feature graph inside an app

How does ChatGraph expose a route while retaining its internal service and Surface identities?

Domains and use cases: mobile, web, navigation.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: The runtime Graph has parentGraph, lifecycle, DI and coroutine scopes. A definition region records a semantic boundary; ChatGraph activation realizes it. Exports preserve contracts and original port identities. The parent does not inherit arbitrary visibility into private data.

Concrete module/design guide · Definition JSON · revision f19d203e3ae8

Laws and limits:

• This is a schematic mapping of existing nested graph/runtime concepts; named region exports need the qualified host adapter.
• A visual frame does not alone establish lifetime ownership, scheduling, authority or physical co-location.

A legal boundary across systems

What changes when the service moves to a remote host?

Domains and use cases: distributed systems, RPC, FFI.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: Keep the ConversationRoute local to Compose. Rebind only the MessagingApi exported port through a ServiceEndpoint HTTP adapter; preserve service identity, auth scope, schema, timeout and error outcomes. The target FFI adapter similarly crosses a language boundary only after ABI and ownership qualification.

Concrete module/design guide · Definition JSON · revision e0435a91df19

Laws and limits:

• Do not export a local borrowed buffer or Compose object across a network boundary.
• Placement is a plan; an observation with activation/revision/host is needed to establish what actually runs.

Shared definition, separate activations

Can two conversation sessions share a blueprint without sharing mutable actor state?

Domains and use cases: actors, games, tenancy.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: A session factory references one Chat feature definition and creates two activation identities, each owning its own state and lifetime. The definition is reusable; runtime mailbox, grants and resources remain scoped to the activation.

Concrete module/design guide · Definition JSON · revision 4c53109051da

Laws and limits:

• Region nesting is not a durability or tenant-isolation mechanism by itself.
• Use stable definition IDs with separate activation IDs and epochs, rather than copying live object identities.

A replaceable RGL feature region

What makes one feature region independently replaceable?

Domains and use cases: RGL, code push, mobile.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: RGL combines its GraphDefinition with ordinary common Kotlin implementation, a Kotlin/JS artifact and qualified FFI host bindings. A release boundary exports stable contracts, pins dependencies, drains old calls and accepts only supported checkpoint schemas.

Concrete module/design guide · Definition JSON · revision 1a0261576dc2

Laws and limits:

• The graph model can describe this release protocol; current prototype FFI does not make every region universally deployable.
• Hard constraints such as active borrows, native ABI mismatch or unqualified state migration make a cut ineligible.

A graph across Kotlin JS and C++

Which graph identities survive a language boundary, and who owns the returned bytes?

Domains and use cases: FFI, Kotlin common, Kotlin JS, native media.

Diagram legend. Frames are named graph regions. Left/right pins show required/offered participation, not a universal schedule. Filled pins are connected; hollow pins are unbound. A junction card preserves one relation's role slots.

Reaktor mapping: The target RGL implementation is ordinary Kotlin/common compiled to Kotlin/JS. A qualified host exposes a typed FFI adapter to a C++ codec. The graph retains caller, host and codec identities; contracts separately describe invocation outcomes and owned frame transfer. Normal KMP code implements the host integration without changing the graph into a second language. Current native hello paths are evidence of integration scaffolding, not this complete production transport.

Concrete module/design guide · Definition JSON · revision ebe45be1d641

Laws and limits:

• Kotlin JS/JVM bridge actuals and the versioned typed frame/stream transport are not generally implemented. Treat this as the target design, not a deployed capability.
• Pin ABI, target/module epoch, schema, ownership, release, cancellation and thread affinity; an asynchronous borrow cannot escape without a qualified lease or copy.