# Reaktor Documentation URL: https://reaktor.build/docs/home Status: unverified Content revision: f18329900ca278b9339b6963a06c9765ea8e8d4838afc3b3a7ddf4d9d98d5f3b Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/home","polarity":"Neutral"},{"id":"section-map","anchor":"map","label":"map","profile":"section","contract":"https://reaktor.build/docs/home#map","polarity":"Neutral"},{"id":"section-background","anchor":"background","label":"background","profile":"section","contract":"https://reaktor.build/docs/home#background","polarity":"Neutral"}],"relations":[{"id":"home:references-documentation-library","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"documentation-library","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-framework-overview","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-framework-overview","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-atlas-revamp-5.6-ultra","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-atlas-revamp-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"home:references-astra-reaktor-plan-and-roadmap","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"astra-reaktor-plan-and-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-desktop-master-plan","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-desktop-master-plan","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-service","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"home:references-auth-analysis","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"auth-analysis","port":"page","role":"target","ordinal":0}]},{"id":"home:references-flexbuffer-implementation","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"flexbuffer-implementation","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-cloud-pane","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-cloud-pane","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-unified-system-graph","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-formal-methods","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-formal-methods","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-conductor","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-conductor","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-essays","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-essays","port":"page","role":"target","ordinal":0}]},{"id":"home:references-contributing","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"contributing","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-core","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-core","port":"page","role":"target","ordinal":0}]},{"id":"home:references-graph-kernel-analysis","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"graph-kernel-analysis","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-stable-foundations-5.6-ultra","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-stable-foundations-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"home:references-reaktor-build-tools","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"reaktor-build-tools","port":"page","role":"target","ordinal":0}]},{"id":"home:references-documentation-audit","kind":"references","owner":"home","incidences":[{"node":"home","port":"page","role":"source","ordinal":0},{"node":"documentation-audit","port":"page","role":"target","ordinal":0}]}]} ## Reaktor Documentation Section ID: preamble Reaktor documentation Reading pathsFrameworkAsk in Manna ↗ Documentation map Reading paths, featured documents and areas Featured now11 The docs most closely tied to the current implementation and architecture cleanup. design · AstraReaktor Product AtlasOne engine across the software lifecycle: persistent source and Blueprint editors, full-stack modules, actors, capabilities, FFI, cloud placement, AI harnesses, devices, releases, telemetry and analytics. Every Pencil board, with implementation handoffs and explicit design status. start here · AstraAstra Reaktor Plan and RoadmapIdea to design to working app, powered by Claude/Codex and a composable runtime. The refined core—live graphs, actors, capabilities, FFI and formal methods—plus December 2026 v1 and the two-developer roadmap. master planDesktop Master PlanThe combined constitution and build score for Reaktor Desktop: product laws, Graph Studio and System Fabric architecture, the verified state of every surface, a decision log, trust and delivery gates, and six shippable phases — two independent plans merged into one readable document. overviewFramework OverviewThe single holistic overview for beginners and experts: the full-stack-modules + Turing-complete-wiring model, the Unreal Engine analogy, the graph and its visitors, a real BestBuds worked example, and every subsystem — with an honest shipped-vs-designed map. moduleService LayerGraph-neutral service contracts: typed Request/Response DTOs, handlers, endpoint identity, staged OkHttp-style interceptors, HTTP adapters, connection setup hooks, Cloudflare service bindings, ServiceNode projection, and the boundary to bus, queue, pubsub, and workflow delivery. securityAuth ArchitectureSource of truth for Reaktor auth: graph runtime, AuthContext, anonymous guest sessions, Supabase email/password, magic links, OTP, provider exchange, sessions, PATs, service accounts, Worker verification, schema, and E2E gates. performanceHigh-Performance FlexBufferThe complete runtime guide: generated and raw kotlinx tiers, every retained optimization, JVM/ART/Native/JS/C++ evidence, BestBuds and Manna adoption, and versioned low-copy FFI design. opsCloud Control PlaneGCP-first cloud control plane for regional k3s cells: Reaktor-managed capacity billed through Reaktor, customer-owned GCP cells managed through reaktor-agent, typed fleet operations, Dagger/Pulumi execution, and no scattered provider auth or Node sidecar. control-planeUnified GraphThe canonical heterogeneous, nested, multilayer port graph: source, build and runtime identities; composition, execution profiles, visitors, graph changes and AI. architectureFormal MethodsHow an application built inside Reaktor's semantic boundary inherits machine-checked guarantees, and how verification results flow back to coding agents as structured counterexamples instead of failing tests. control-planeConductorDrive Claude Code and Codex from inside Reaktor: your own agents, your own collaboration topologies, and one canonical conversation that outlives either tool. Choose a reading path6 Six routes through the catalog, each written for a different reason to be here. Every path is three to five documents, in order. I want to understand ReaktorEssays -> Framework Overview -> Vision and roadmap. I want to contributeContributing -> Framework Overview -> Graph Kernel -> the module you are changing. Build an appCore -> Service -> Auth -> Data -> UI -> FlexBuffer and FFI. I want the graph modelKernel -> lifecycle -> visitors -> actors -> unified graph. I care whether it is correctStable Foundations -> Verified Foundations -> Formal Methods -> the critic reviews. Ship and operateBuild tools -> CLI -> DevOps -> Cloud control plane -> telemetry. Start here7 Find your reading path, understand Reaktor's purpose and direction, then use the contributor guide to start work. Begin with the documentation library or Framework Overview. Documentation library and improvement programmeguide · Reaktor documentationReading paths for people, retrieval systems and agents; source coverage, audit criteria, website improvements and remaining editorial work.7 min read Reaktor Framework Overviewoverview · ClaudeThe single holistic overview for beginners and experts: the full-stack-modules + Turing-complete-wiring model, the Unreal Engine analogy, the graph and its visitors, a real BestBuds worked example, and every subsystem — with an honest shipped-vs-designed map.35 min read Reaktor Essays — Two Readingsoverview · Claude + CodexTwo independent technical essays written to the same brief without either author seeing the other's work: Claude (Fable 5) argues from what a live runtime graph makes possible, Codex argues from what a small trusted semantic kernel makes provable. Both are reproduced verbatim.14 min read Astra Reaktor Plan and Roadmapstrategy · Astra / CodexReaktor's software-forge north star: create and evolve apps with a live graph, actors, capabilities, polyglot FFI, formal methods and Claude/Codex; current system status and a two-developer roadmap to December 2026 public v1 and September 2027.1.6 hr read Contributing to Reaktorguide · MergedThe practical entry point for a new contributor: what lives in which repository, the module map, how to set up and build, the two rules every module must obey, where to put a change, and how to add or edit a doc on this site.8 min read Documentation audit — 7 October 2026analysis · Reaktor documentationCriterion-by-criterion findings across the public and private corpus, source integration, structural repairs, canonical roles and editorial priorities.10 min read Markdown graph markersguide · Reaktor documentationAuthor document metadata, navigation regions, named ports and relationships in Markdown; generate every graph and reading view from the same declarations.5 min read Theory and worked designs18 Start with the graph model and Kotlin language, then inspect thirty designs with named ports, hyperedge roles and explicit runtime qualifications. Explore 18 documents in Theory and worked designs Architecture atlas8 The October design synthesis: invariants, vocabulary, semantics, lowering, releases, precedents and concrete scenarios. Read as design, with current implementation evidence in module chapters. Explore 8 documents in Architecture atlas Engine reference10 The September technical preprint as an ordered web book. Scope and source lineage remain explicit; current guides own implementation status. Explore 10 documents in Engine reference Data layer12 One ordered home for data architecture, storage, tenancy, transactions, durable delivery, live channels, execution, inspection and qualification. Explore 12 documents in Data layer Using the framework23 The modules you build an application out of: what each one gives you, the API it exposes, and how far it is actually built. Explore 23 documents in Using the framework FlexBuffers and FFI19 Binary wire formats, measured codec performance and stability, mutable-memory design, and ownership across language boundaries. Explore 19 documents in FlexBuffers and FFI The graph model14 Reaktor's central idea: an application is a typed graph. These docs define the kernel, what walks it, how it runs, and what can be proved about it. Explore 14 documents in The graph model Build and ship8 The toolchain, deployment and fleet resources that take a working change into production. Operations & Reliability owns diagnostics and verification. Explore 8 documents in Build and ship Operations & Reliability23 Shared observability, instance health, profiling, realistic load and the Shadow textbook: evidence from graph and source to a repeatable experiment. Explore 23 documents in Operations & Reliability Workbench9 The surfaces people use to see and change a running system: the desktop workbench, its panes and the visual language. Agent tooling has its own group. Explore 9 documents in Workbench Agents8 Everything about AI agents and Reaktor: how agents build Reaktor code cheaply, the control plane agents call, how Reaktor drives Claude Code and Codex, and the agents that run inside Reaktor products and tools. Explore 8 documents in Agents Products built on Reaktor6 Real applications on the framework. They are the honesty check: anything the framework claims has to survive one of these. Explore 6 documents in Products built on Reaktor Background and archive16 Kept for the record: market positioning, adversarial reviews, superseded plans, and long research dumps. Nothing here is current — read it for how a decision was reached, not for what is true now. Explore 16 documents in Background and archive # Shadow, evidence and region releases URL: https://reaktor.build/docs/architecture-atlas-evolution Status: design Content revision: 5634e817df860fa72b4918fcf69ffec6e2e6948f4858c9502de9b5084b716b6d Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-shadow","panel-evidence","panel-update-cut","panel-release","panel-host-matrix"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-evolution","polarity":"Neutral"},{"id":"section-11-shadow-claims-and-evidence","anchor":"11-shadow-claims-and-evidence","label":"11. Shadow, claims and evidence","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#11-shadow-claims-and-evidence","polarity":"Neutral"},{"id":"section-12-region-releases-and-subgraph-level-code-push","anchor":"12-region-releases-and-subgraph-level-code-push","label":"12. Region releases and subgraph-level code push","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#12-region-releases-and-subgraph-level-code-push","polarity":"Neutral"},{"id":"section-panel-shadow","anchor":"panel-shadow","label":"Shadow should answer a named counterfactual question","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#panel-shadow","polarity":"Neutral"},{"id":"section-panel-evidence","anchor":"panel-evidence","label":"A claim chooses its evidence—not the other way around","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#panel-evidence","polarity":"Neutral"},{"id":"section-panel-update-cut","anchor":"panel-update-cut","label":"Compatibility-closed region updates","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#panel-update-cut","polarity":"Neutral"},{"id":"section-panel-release","anchor":"panel-release","label":"Region release and activation","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#panel-release","polarity":"Neutral"},{"id":"section-cross-document-contract-obligations","anchor":"cross-document-contract-obligations","label":"Cross-document contract obligations","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#cross-document-contract-obligations","polarity":"Neutral"},{"id":"section-boundary--caveat","anchor":"boundary--caveat","label":"Boundary / caveat","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-evolution#boundary--caveat","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-evolution:references-architecture-atlas-foundations","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-architecture-atlas-vocabulary","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-vocabulary","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-architecture-atlas-semantics","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-semantics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-architecture-atlas-language","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-architecture-atlas-workbench","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-architecture-atlas-scenarios","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-scenarios","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-architecture-atlas-qualification","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-qualification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-shadow-foundations","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-11-shadow-claims-and-evidence","role":"source","ordinal":0},{"node":"shadow-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-shadow-capture-replay","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-11-shadow-claims-and-evidence","role":"source","ordinal":0},{"node":"shadow-capture-replay","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-shadow-verification","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-11-shadow-claims-and-evidence","role":"source","ordinal":0},{"node":"shadow-verification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-operations-graph-evidence","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-11-shadow-claims-and-evidence","role":"source","ordinal":0},{"node":"operations-graph-evidence","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-shadow-workspaces","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-11-shadow-claims-and-evidence","role":"source","ordinal":0},{"node":"shadow-workspaces","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-capability","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"reaktor-capability","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-astra-reaktor-plan-and-roadmap","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"astra-reaktor-plan-and-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-formal-methods","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"reaktor-formal-methods","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-surface-contracts-and-interaction","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"reaktor-surface-contracts-and-interaction","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-graph-protocol","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"reaktor-graph-protocol","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-work","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-ffi","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-conductor","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-cross-document-contract-obligations","role":"source","ordinal":0},{"node":"reaktor-conductor","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-evolution:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-evolution","incidences":[{"node":"architecture-atlas-evolution","port":"section-boundary--caveat","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]}]} ## Shadow, evidence and region releases Section ID: shadow-evidence-and-region-releases Shadow, evidence and region releases Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification ## 11. Shadow, claims and evidence Section ID: 11-shadow-claims-and-evidence 11. Shadow, claims and evidence Reaktor’s strongest potential is a closed change loop: propose a typed edit, calculate obligations, run a pinned candidate against qualified state and faults, promote the exact approved artifact vector, realize it, and join the observed outcomes back to the same identities. FoundationDB’s simulation architecture is an important precedent because the paper’s authors report that simulation made risky subsystem changes more feasible, not merely faster to test. That supports the qualitative hypothesis that better experimentation can expand what a team is willing and able to build. It is not evidence for a particular Reaktor productivity factor. [FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021)] Shadow must distinguish contract assertions, baseline comparisons and live observations. Sampling is not replay completeness. Duplicate observers must not produce duplicate substitutions. A recorded AI output can validate orchestration but cannot measure a new model’s quality. Changed artifacts or policies invalidate approval according to a sound dependency model. [Shadow foundations] [Capture and replay] [Shadow verification and capsules] [Operational graph evidence] Immutability also does not mean retaining sensitive payloads forever. Keep controlled artifact references, scope disclosure, retention and revocation policies, and suppression information so a rebuilt workspace does not resurrect erased records. Captured text is untrusted input to agents and must not rewrite the policy used to approve those agents’ changes. [Shadow workspaces] [Shadow verification and capsules] ## Cross-document contract obligations Section ID: cross-document-contract-obligations Cross-document contract obligations Capabilities: the current capability API presents a tier enum and additional attributes; the roadmap asks for multidimensional offers and constraints. Preserve the latter as the semantic model. A “higher tier” remote model does not dominate a local model when privacy prohibits transmission. Resolve hard compatibility, authority and placement constraints first; only then optimize preferences. Pin running sessions or define migration and hysteresis so adaptation does not create oscillation or resource churn. [Capability selection] [Reaktor plan and roadmap] Evidence: Formal Methods defines an ordinal EvidenceLevel sequence ending in operational attestation. Replace that total order with claim-indexed evidence. A proof about a finite model, a replay of a recorded workload, a schema guarantee and a latency observation are complementary, not substitutable rungs. A release gate names the claim, artifacts, assumptions, bounds, checker and required evidence portfolio. [Formal methods and evidence] [Shadow verification and capsules] Protocols: payload compatibility is weaker than behavioral compatibility. Admission, persistence, processing, cancellation and reconciliation need explicit meaning. The Surface documents already include behavioral versioning, while Graph Protocol and Work describe different completion and lifetime guarantees. These should be one shared vocabulary with qualified protocol-specific laws. [Surface contracts and interaction] [Graph protocol] [Durable work] Execution truth: the Work document reports a 5 October conformance gate for scoped SQLite-backed claims and recovery, while still listing missing provider/device and durable-journal qualification. The FFI document reports working bridge experiments but says the general typed frame/Flow transport is unimplemented. The graph engine should reuse proven primitives, not equate these different statuses or create competing implementations of ownership and recovery. These are document-reported states; implementation qualification requires direct testing. [Durable work] [FFI / Switchboard] Agent authority: Conductor supports inherited harness configuration and passthrough arguments. Those external tools may possess capabilities outside the graph command catalog. Governance claims must therefore bind effective harness and operating-system authority, or explicitly mark the run as partially ungoverned. A graph permission check is not an OS sandbox. [Conductor harness boundaries] [Formal methods and evidence] ## 12. Region releases and subgraph-level code push Section ID: 12-region-releases-and-subgraph-level-code-push 12. Region releases and subgraph-level code push The user-selected subgraph S is an editing unit. Compute a conservative compatibility closure C containing S under the selected module/target rules: include entities that must change together because a crossing contract changes, shared state needs coordinated migration, a continuation cannot cross versions, or compilation has erased an independently replaceable boundary. Refine toward a minimal unit only where the declared rules support it. Do not include all transitive dependencies indiscriminately; stable compatible dependencies can remain pinned imports. The boundary of C includes every crossing incidence, not only ordinary directed edges. Each exported/imported port has a schema, protocol, role, ownership and effect contract. A multiparty hyperedge can cross the cut only with a qualified boundary mapping; slicing a session in half without its relation identity is invalid. Semantic update granularity is not physical download granularity. Inlining, shared libraries or a JS bundle may require a larger artifact even for a one-node semantic change. Chunking/content addressing can avoid retransmitting unchanged artifacts; that optimization must not imply independent activation of coupled regions. Package an immutable RegionRelease: selected and closed regions, base revision, canonical definition digest, per-target artifact digests, boundary descriptor, dependency vector, host requirements, state schema/migrator, activation policy, rollout policy and evidence references. A signature authenticates bytes and publisher. It does not establish correctness, grant additional capabilities or make an update compliant with distribution rules. The server commits desired release intent and receipts. Hosts download and verify separately, stage the complete candidate, check runtime/policy compatibility, prepare state and then activate at a safe point. Distribution, eligibility, local activation and cross-host rollout are separate operations. A release only becomes observed-active after the target reports it. ## Admission and activation Section ID: admission-and-activation Admission and activation Admit a release only if its signature/provenance is trusted, host descriptor satisfies required capabilities and ABI profiles, pinned dependencies are present/compatible, exported contracts remain valid, required grants are currently available, state migration is acceptable, evidence is fresh and the channel/distribution policy allows the change. Fail closed for unknown required semantics. Start with exact qualified compatibility fingerprints where possible, then add explicit equivalence profiles. Do not identify a native host merely as Android or iOS. It has installed service/FFI descriptors, renderer vocabulary, bytecode/VM version, memory rules and a set of updateable regions. Manifest requirements are not capabilities minted by the downloaded release. Use signed manifests, trusted publisher scope, key-rotation strategy, bounded decompression/decoding and verification before execution. Keep a known-good embedded or cached release and durable activation receipts. An anti-rollback policy may forbid an older vulnerable artifact: intentional rollback must be an explicitly authorized newer release record, not arbitrary generation reversal. Pin new invocation trees to one activation image. Existing calls and sessions retain their previous compatible generation. Shared writers require ownership fencing or quiescence; migrating state while the old owner continues writing is not a valid cutover. Never free native code or buffers while callbacks/resources still reference their generation. Across devices and services, use a release vector with compatible mixed versions. Additive protocol evolution and expand/contract data migration are common strategies; some changes require draining old sessions or a coordinated maintenance window. Graph commit atomicity cannot force disconnected phones to activate simultaneously. ## Runtime update classes Section ID: runtime-update-classes Runtime update classes Expo provides the useful separation between the native binary and compatible update content. Runtime versions/fingerprints gate compatibility, signing verifies published updates, and staged rollout limits exposure. These mechanisms are precedents or reusable delivery components for suitable RN deployments—not evidence that Expo supplies Reaktor region-level activation. Expo runtime versions and updates Expo end-to-end update signing Expo update rollouts For an installed RN host, update JS/assets or a graph program only when supported by its loader and existing native capabilities. New native modules, entitlements or incompatible native ABI requirements need a new app binary. Hot module replacement in development is a separate feature from production-safe update delivery. For a compiled Kotlin/Native or Compose host, arbitrary new Kotlin machine code is not an assumed OTA feature. Options are data/configuration, a deliberately installed and qualified graph interpreter, supported JS/Wasm execution where available, or a conventional signed binary release. JVM and desktop hosts may use qualified loaders or processes, but class/state/resource compatibility still requires explicit handling. For browser and server/Worker targets, publish immutable modules or artifacts and switch references according to host rules. A web refresh, a fresh Worker deployment and a live replacement inside one process have different continuity guarantees. Database schema changes and external work remain migration/reconciliation steps, not code swapping. Technical executability and store permission are separate. Apple 2.5.2 restricts downloaded code changing functionality; 4.7 permits particular software categories under additional conditions. Google Play restricts externally downloaded dex/JAR/native executable code and specifies a qualified VM/interpreter exception. Neither an interpreted graph nor FlexBuffers is a compliance loophole. Obtain platform review for the concrete distribution model; platform compliance requires separate review. Apple App Review Guidelines, 2.5.2 and 4.7 Google Play Device and Network Abuse policy ## Shadow should answer a named counterfactual question Section ID: panel-shadow Shadow should answer a named counterfactual question What changes when this exact candidate runs under this exact approved workload? Shadow should answer a named counterfactual question Law / model / proof obligation: Evidence = f(base, candidate, artifacts, state cut, workload, policy, runner, fault schedule, coverage). Diagram: Shadow should answer a named counterfactual question COUNTERFACTUAL EXECUTION • PIN WHAT CHANGES AND WHAT DOES NOT Approved base + workload + environment Same defined capture cut and nondeterminism schedule Baseline world Graph r10 + artifact A Shadow-owned state authority Explicit real/recorded/simulated effects Candidate world Graph r11 + artifact B Isolated copy of the same approved base No accidental production side effects Contract assertions + controlled comparison Changed requirements are judged against acceptance—not blind byte equality. A trace is not automatically a replay journal. Suppression, capture loss and substitution ownership stay explicit. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision Use isolated state, qualified nondeterminism control and explicit execution cuts. Compare expected behavior and invariants; record why evidence is applicable to this candidate rather than to a nearby commit. ## What this does not establish Section ID: what-this-does-not-establish What this does not establish Opaque effects and live dependencies limit determinism. Recorded model outputs test orchestration, not the quality of today’s model. CDC plus recorded events must not apply the same mutation twice. Falsifiable acceptance test. Change one artifact after the run. Evidence becomes stale; changing the acceptance policy needs independently authorized review. Theory, precedent and Reaktor context: Shadow foundations Capture and replay Shadow verification and capsules Shadow workspaces FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) ## A claim chooses its evidence—not the other way around Section ID: panel-evidence A claim chooses its evidence—not the other way around The docs’ EvidenceLevel scale should become a typed requirement over evidence kinds and scope. A claim chooses its evidence—not the other way around Law / model / proof obligation: Claim = subject + proposition + profile + assumptions + bounds; evidence binds artifacts, method, coverage and verifier. Diagram: A claim chooses its evidence—not the other way around VERIFICATION THEORY • EVIDENCE IS A MATRIX, NOT AN ORDINAL LADDER Types BMC Replay Production No illegal schema value Relevant* Not inferred Not inferred Not inferred No deadlock within bounds Not inferred Relevant* Not inferred Not inferred This workload preserves outcomes Not inferred Not inferred Relevant* Not inferred Observed latency under load Not inferred Not inferred Not inferred Relevant* *Illustrative matches, not exclusions. Richer models and combined evidence can support additional claims. ## Reaktor design decision Section ID: reaktor-design-decision-1 Reaktor design decision A promotion policy can require several complementary kinds of evidence. Operational observation informs risk but cannot replace a universal theorem; a theorem over an abstraction cannot establish actual runtime latency. ## What this does not establish Section ID: what-this-does-not-establish-1 What this does not establish There can be a partial order for comparable claims, but no universal total order placing production attestation above mechanical proof. Avoid percentages that combine incomparable claims. Falsifiable acceptance test. Ask whether a production trace proves that all future unauthorized writes are impossible. Reject that inference while retaining the trace’s actual observational value. Theory, precedent and Reaktor context: Formal methods and evidence Shadow verification and capsules Lamport — A high-level view of TLA+ FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) ## Compatibility-closed region updates Section ID: panel-update-cut Compatibility-closed region updates Do not confuse a selection rectangle with a safe unit of runtime replacement. Vector diagram · click a marked item to inspect A selected subgraph expands only when compatibility requires it Diagram: A selected subgraph expands only when compatibility requires it Stable client boundary request : RankInput result : RankedItems consumer stays at v1 EDITED REGION: matching.rank Rank function v2 Changed pure scoring logic Selected subgraph S Shared feature schema Include if format changes Coupled definition Session state / continuation Include only if migration couples it Old writers require fencing Installed native host Native ABI remains outside Compatible exports only New native API → host build Boundary = every crossing incidence, including multiparty relations. Closure: C₀ = S; Cₙ₊₁ = Cₙ ∪ RequiredTogether(Cₙ) Keep stable external contracts as pinned imports. Widen for shared state, protocol evolution or indivisible compiled artifacts. A runtime cut may be larger than the selected canvas region. Semantic granularity is not necessarily download granularity. The closure algorithm is driven by declared coupling/compatibility rules; ordinary dependency reachability alone is too broad. ## Reaktor design decision Section ID: reaktor-design-decision-2 Reaktor design decision Compute a compatibility closure under declared rules, preserve boundary roles and pin compatible dependencies. Keep physical artifact packaging separate from semantic edit scope. ## Boundary / caveat Section ID: boundary--caveat Boundary / caveat Inlining, native ABI changes, shared writers and persisted continuations may force a wider artifact, host rebuild, drain or explicit migration. Qualification test. Change only a pure ranker, then change its shared schema. The second candidate must widen its update obligations and invalidate relevant prior evidence. Official context and precedents: Expo runtime versions and updates Reaktor Visual Language / Blueprints ## Region release and activation Section ID: panel-release Region release and activation A signed bundle identifies a proposed update. Only a compatible, authorized host may activate it. Vector diagram · click a marked item to inspect Signed region release: publish intent, then admit and activate per host Diagram: Signed region release: publish intent, then admit and activate per host Package Immutable region bundle Verify Shadow + independent gate Promote Durable desired revision Stage Download + host admission Activate Safe local root switch Signed RegionRelease definition + artifact digests boundary + dependency vector installed-host requirements state schema + migrator policy + evidence + rollout base revision + publisher scope Admission is conjunctive—not “the signature passed” Trusted bytes ∧ compatible host ∧ valid boundary ∧ current grants ∧ safe state plan ∧ pinned dependencies ∧ fresh evidence ∧ allowed distribution policy Old activation: epoch 42 Existing sessions stay pinned Leases / callbacks drain No new writes after fencing New activation: epoch 43 Prepared before publication New calls use one image State migration is explicit one root Across hosts: compatible release vector + recoverable reconciliation A phone can remain on the old version while a server is new. Bind sessions to compatible protocol versions. Lost activation reply → retry operation identity and retrieve the receipt, not blindly perform the mutation again. Rollback selects an older compatible artifact under a NEW authorized epoch; it cannot undo arbitrary external effects. Illustrative state machine only. Staging/activation require a qualified loader and do not bypass store or operating-system rules. ## Reaktor design decision Section ID: reaktor-design-decision-3 Reaktor design decision Reuse the graph commit/receipt mechanism for desired release intent. Prepare immutable host images, pin old calls, stage state and publish one activation root per owned domain. ## Boundary / caveat Section ID: boundary--caveat-1 Boundary / caveat A signature proves integrity/publisher under its trust chain, not correctness, permission or state compatibility. No global instantaneous mobile/server cutover is promised. Qualification test. Inject a stale-evidence condition before promotion, a lost activation reply, and an in-flight old callback. Reject, recover by receipt, and preserve old resource lifetimes respectively. Official context and precedents: Expo runtime versions and updates Expo end-to-end update signing Expo update rollouts Reaktor FFI / Switchboard ## Runtime-specific update classes Section ID: panel-host-matrix Runtime-specific update classes Avoid a universal promise of live code replacement across every Reaktor runtime. Vector diagram · click a marked item to inspect Update classes depend on the installed host and distribution policy Diagram: Update classes depend on the installed host and distribution policy Runtime host Data / graph / script update New native capability Activation contract Browser Versioned modules/assets or a supported interpreter Host/browser capability limits still apply Refresh, worker replacement or qualified live region React Native host Compatible JS/assets; graph loader if installed New native module → new app binary Usually host-defined restart/reload; region swap is extra work K/N / Compose host Config/assets; installed graph VM where qualified No assumed arbitrary native Kotlin OTA New binary, or safe point in an installed interpreter JVM / desktop host Qualified loaders/processes or graph programs Native library / ABI upgrades need host handling Resource/class compatibility; drain or process restart Worker / server New immutable artifact, versioned release or loader Rebuild/deploy to the host runtime profile Provider deployment plus compatible session rollout Unity / Unreal host Supported data/script/plugin path only Native engine/plugin change follows platform build rules New matches/instances first; engine state is separately owned Technical loadability ≠ authorization ≠ distribution-policy permission Downloaded graph data or bytecode is not an App Store / Play policy loophole. Native capability sets do not expand by manifest request. This matrix is a proposed qualification model, not a claim that all host loaders or live-update paths already exist. ## Reaktor design decision Section ID: reaktor-design-decision-4 Reaktor design decision Describe the installed host precisely and compile each change to an eligible delivery class. Keep metadata updates, interpreted/script updates and native binary changes distinct. ## Boundary / caveat Section ID: boundary--caveat-2 Boundary / caveat Store rules and host limitations remain independent gates. Expo runtime compatibility is a useful precedent, not automatic region hot-swap support. Qualification test. A downloaded program requiring an absent native camera export must be rejected before execution, even if its signature and graph types are valid. Official context and precedents: Expo runtime versions and updates How EAS Update works Apple App Review Guidelines, 2.5.2 and 4.7 Google Play Device and Network Abuse policy # Architecture thesis and invariants URL: https://reaktor.build/docs/architecture-atlas-foundations Status: design Content revision: 3f0a34a1c224d361628a02f5682929e295091a528a194b6ae98c804910a5d80b Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-system","panel-ideas","panel-contracts","panel-incidence","panel-layers"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-foundations","polarity":"Neutral"},{"id":"section-1-architectural-thesis","anchor":"1-architectural-thesis","label":"1. Architectural thesis","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#1-architectural-thesis","polarity":"Neutral"},{"id":"section-2-core-ideas-and-invariants","anchor":"2-core-ideas-and-invariants","label":"2. Core ideas and invariants","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#2-core-ideas-and-invariants","polarity":"Neutral"},{"id":"section-3-semantic-kernel-and-graph-substrate","anchor":"3-semantic-kernel-and-graph-substrate","label":"3. Semantic kernel and graph substrate","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#3-semantic-kernel-and-graph-substrate","polarity":"Neutral"},{"id":"section-panel-system","anchor":"panel-system","label":"The graph is the system language","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#panel-system","polarity":"Neutral"},{"id":"section-panel-ideas","anchor":"panel-ideas","label":"Core ideas and invariants","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#panel-ideas","polarity":"Neutral"},{"id":"section-panel-contracts","anchor":"panel-contracts","label":"Reusable feature contracts","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#panel-contracts","polarity":"Neutral"},{"id":"section-1-one-semantic-identity-system","anchor":"1-one-semantic-identity-system","label":"1. One semantic identity system","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#1-one-semantic-identity-system","polarity":"Neutral"},{"id":"section-2-typed-role-labelled-port-hypergraph","anchor":"2-typed-role-labelled-port-hypergraph","label":"2. Typed, role-labelled port hypergraph","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#2-typed-role-labelled-port-hypergraph","polarity":"Neutral"},{"id":"section-4-orthogonal-facets-and-semantic-layers","anchor":"4-orthogonal-facets-and-semantic-layers","label":"4. Orthogonal facets and semantic layers","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#4-orthogonal-facets-and-semantic-layers","polarity":"Neutral"},{"id":"section-5-definitions-are-not-activations-or-observations","anchor":"5-definitions-are-not-activations-or-observations","label":"5. Definitions are not activations or observations","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#5-definitions-are-not-activations-or-observations","polarity":"Neutral"},{"id":"section-6-source-and-visual-projections-share-edit-authority","anchor":"6-source-and-visual-projections-share-edit-authority","label":"6. Source and visual projections share edit authority","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#6-source-and-visual-projections-share-edit-authority","polarity":"Neutral"},{"id":"section-7-general-computation-with-qualified-execution-profiles","anchor":"7-general-computation-with-qualified-execution-profiles","label":"7. General computation with qualified execution profiles","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#7-general-computation-with-qualified-execution-profiles","polarity":"Neutral"},{"id":"section-8-protocols-not-only-payload-types","anchor":"8-protocols-not-only-payload-types","label":"8. Protocols, not only payload types","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#8-protocols-not-only-payload-types","polarity":"Neutral"},{"id":"section-9-explicit-state-lifetime-and-resource-ownership","anchor":"9-explicit-state-lifetime-and-resource-ownership","label":"9. Explicit state, lifetime and resource ownership","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#9-explicit-state-lifetime-and-resource-ownership","polarity":"Neutral"},{"id":"section-10-effects-and-authority-are-different-contracts","anchor":"10-effects-and-authority-are-different-contracts","label":"10. Effects and authority are different contracts","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#10-effects-and-authority-are-different-contracts","polarity":"Neutral"},{"id":"section-11-adaptive-capability-selection","anchor":"11-adaptive-capability-selection","label":"11. Adaptive capability selection","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#11-adaptive-capability-selection","polarity":"Neutral"},{"id":"section-13-one-interop-contract-several-physical-paths","anchor":"13-one-interop-contract-several-physical-paths","label":"13. One interop contract, several physical paths","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#13-one-interop-contract-several-physical-paths","polarity":"Neutral"},{"id":"section-14-transactional-system-definitions","anchor":"14-transactional-system-definitions","label":"14. Transactional system definitions","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#14-transactional-system-definitions","polarity":"Neutral"},{"id":"section-17-deployment-is-recoverable-realization","anchor":"17-deployment-is-recoverable-realization","label":"17. Deployment is recoverable realization","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#17-deployment-is-recoverable-realization","polarity":"Neutral"},{"id":"section-18-incremental-queries-and-transformations","anchor":"18-incremental-queries-and-transformations","label":"18. Incremental queries and transformations","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#18-incremental-queries-and-transformations","polarity":"Neutral"},{"id":"section-19-shadow-executes-controlled-counterfactuals","anchor":"19-shadow-executes-controlled-counterfactuals","label":"19. Shadow executes controlled counterfactuals","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#19-shadow-executes-controlled-counterfactuals","polarity":"Neutral"},{"id":"section-21-maps-make-one-model-legible","anchor":"21-maps-make-one-model-legible","label":"21. Maps make one model legible","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#21-maps-make-one-model-legible","polarity":"Neutral"},{"id":"section-22-human-and-agent-actions-share-commands","anchor":"22-human-and-agent-actions-share-commands","label":"22. Human and agent actions share commands","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#22-human-and-agent-actions-share-commands","polarity":"Neutral"},{"id":"section-23-interaction-semantics-are-portable-rendering-remains-specialized","anchor":"23-interaction-semantics-are-portable-rendering-remains-specialized","label":"23. Interaction semantics are portable, rendering remains specialized","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#23-interaction-semantics-are-portable-rendering-remains-specialized","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-1","anchor":"what-this-does-not-establish-1","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-foundations#what-this-does-not-establish-1","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-foundations:references-architecture-atlas-vocabulary","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-vocabulary","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-architecture-atlas-semantics","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-semantics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-architecture-atlas-language","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-architecture-atlas-evolution","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-evolution","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-architecture-atlas-workbench","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-architecture-atlas-scenarios","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-scenarios","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-architecture-atlas-qualification","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-qualification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-unified-system-graph","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-1-architectural-thesis","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-astra-reaktor-plan-and-roadmap","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-1-architectural-thesis","role":"source","ordinal":0},{"node":"astra-reaktor-plan-and-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-ffi","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-1-architectural-thesis","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-shadow-workspaces","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-1-architectural-thesis","role":"source","ordinal":0},{"node":"shadow-workspaces","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-graph-sources","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-1-one-semantic-identity-system","role":"source","ordinal":0},{"node":"reaktor-graph-sources","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-graph-substrate-redesign","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-2-typed-role-labelled-port-hypergraph","role":"source","ordinal":0},{"node":"reaktor-graph-substrate-redesign","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-data-graph","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-2-typed-role-labelled-port-hypergraph","role":"source","ordinal":0},{"node":"reaktor-data-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-module-execution-plan","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-4-orthogonal-facets-and-semantic-layers","role":"source","ordinal":0},{"node":"reaktor-module-execution-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-operations-graph-evidence","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-5-definitions-are-not-activations-or-observations","role":"source","ordinal":0},{"node":"operations-graph-evidence","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-6-source-and-visual-projections-share-edit-authority","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-actor-model","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-7-general-computation-with-qualified-execution-profiles","role":"source","ordinal":0},{"node":"reaktor-actor-model","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-service","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-8-protocols-not-only-payload-types","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-graph-protocol","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-8-protocols-not-only-payload-types","role":"source","ordinal":0},{"node":"reaktor-graph-protocol","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-component-lifecycle","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-9-explicit-state-lifetime-and-resource-ownership","role":"source","ordinal":0},{"node":"reaktor-component-lifecycle","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-formal-methods","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-10-effects-and-authority-are-different-contracts","role":"source","ordinal":0},{"node":"reaktor-formal-methods","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-auth-analysis","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-10-effects-and-authority-are-different-contracts","role":"source","ordinal":0},{"node":"auth-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-capability","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-11-adaptive-capability-selection","role":"source","ordinal":0},{"node":"reaktor-capability","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-flatbuffers-flexbuffers-mutable-memory-05-mutable-memory","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-13-one-interop-contract-several-physical-paths","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-05-mutable-memory","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-stable-foundations-5.6-ultra","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-14-transactional-system-definitions","role":"source","ordinal":0},{"node":"reaktor-stable-foundations-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-data-transactions","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-14-transactional-system-definitions","role":"source","ordinal":0},{"node":"reaktor-data-transactions","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-devops","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-17-deployment-is-recoverable-realization","role":"source","ordinal":0},{"node":"reaktor-devops","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor_graph_visitors_design","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-18-incremental-queries-and-transformations","role":"source","ordinal":0},{"node":"reaktor_graph_visitors_design","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-shadow-foundations","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-19-shadow-executes-controlled-counterfactuals","role":"source","ordinal":0},{"node":"shadow-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-shadow-capture-replay","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-19-shadow-executes-controlled-counterfactuals","role":"source","ordinal":0},{"node":"shadow-capture-replay","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-shadow-verification","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-19-shadow-executes-controlled-counterfactuals","role":"source","ordinal":0},{"node":"shadow-verification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-workbench-layers","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-21-maps-make-one-model-legible","role":"source","ordinal":0},{"node":"reaktor-workbench-layers","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-conductor","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-22-human-and-agent-actions-share-commands","role":"source","ordinal":0},{"node":"reaktor-conductor","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-surface-contracts-and-interaction","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-23-interaction-semantics-are-portable-rendering-remains-specialized","role":"source","ordinal":0},{"node":"reaktor-surface-contracts-and-interaction","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-surface-dynamic-ui-and-verification","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-23-interaction-semantics-are-portable-rendering-remains-specialized","role":"source","ordinal":0},{"node":"reaktor-surface-dynamic-ui-and-verification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-surface-renderers","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-23-interaction-semantics-are-portable-rendering-remains-specialized","role":"source","ordinal":0},{"node":"reaktor-surface-renderers","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-core","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-3-semantic-kernel-and-graph-substrate","role":"source","ordinal":0},{"node":"reaktor-core","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-build-tools","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-3-semantic-kernel-and-graph-substrate","role":"source","ordinal":0},{"node":"reaktor-build-tools","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-foundations:references-reaktor-multitenancy","kind":"references","owner":"architecture-atlas-foundations","incidences":[{"node":"architecture-atlas-foundations","port":"section-what-this-does-not-establish-1","role":"source","ordinal":0},{"node":"reaktor-multitenancy","port":"page","role":"target","ordinal":0}]}]} ## Architecture thesis and invariants Section ID: architecture-thesis-and-invariants Architecture thesis and invariants Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification Reaktor is a typed, transactional language for describing, realizing, inspecting and safely changing multi-runtime systems. The graph is the semantic authority; specialized runtimes remain responsible for specialized execution. ## 1. Architectural thesis Section ID: 1-architectural-thesis 1. Architectural thesis Documentation scope: 140 routes exposed by the public documentation navigation were inventoried, including archive entries and a redirect/alias. Substantive sections of 51 documents were compared across graph, data, execution, FFI, UI, build, agents and operations. Additional legacy material was checked separately. The coverage ledger distinguishes retrieval, substantive review and inaccessible material. The architecture depends on exact contracts connecting Reaktor’s mechanisms: capabilities, completion protocols, lifecycle ownership, source publication, evidence validity, specialized UI execution and actual harness authority. Compact definition: Reaktor is a typed, transactional language for describing, realizing, inspecting and safely changing multi-runtime systems, with specialized execution behind qualified boundaries. This expresses the Living Graph’s intended scope without claiming that all of it currently ships. [The Living Graph] [Reaktor plan and roadmap] [FFI / Switchboard] [Shadow workspaces] ## 2. Core ideas and invariants Section ID: 2-core-ideas-and-invariants 2. Core ideas and invariants ## 1. One semantic identity system Section ID: 1-one-semantic-identity-system 1. One semantic identity system Problem: Duplicated models drift across build, runtime and tools. Mechanism: Stable definition, operation and resource identities; versioned joins to artifacts and activations. Theory: Denotational meaning; content-addressed identity. Precedent: Unison; MLIR symbol/operation models. Qualification: Stable identity is not the same as a mutable name, hash or runtime address. Sources: The Living Graph, Source ownership, Unison — Code as content-addressed definitions, MLIR — Interfaces ## 2. Typed, role-labelled port hypergraph Section ID: 2-typed-role-labelled-port-hypergraph 2. Typed, role-labelled port hypergraph Problem: Binary links lose the meaning of multi-party relations. Mechanism: Nodes own ports; incidences carry relation, role and optional position. Theory: Typed hypergraphs; relational incidence models. Precedent: Ptolemy II port-connected actors. Qualification: Topology does not define ordering, coordination or protocol progress. Sources: Graph substrate redesign, Data graph, Ptolemy II: hierarchy, ports and models of computation ## 3. Open hierarchical regions Section ID: 3-open-hierarchical-regions 3. Open hierarchical regions Problem: Reuse must preserve boundaries while changing internals. Mechanism: Exported ports and explicit replacement boundary mappings. Theory: Cospans; symmetric monoidal composition; typed substitution. Precedent: Ptolemy hierarchical composition; FMI boundaries. Qualification: Ownership-constrained composition must not introduce arbitrary resource copying. Sources: The Living Graph, Fong — Decorated Cospans (2015), Functional Mock-up Interface — Model exchange and co-simulation ## 4. Orthogonal facets and semantic layers Section ID: 4-orthogonal-facets-and-semantic-layers 4. Orthogonal facets and semantic layers Problem: Class inheritance and duplicate graphs couple unrelated concerns. Mechanism: One identity space, typed facts and relation families; versioned dialects. Theory: Multilayer graphs; extensible algebraic signatures. Precedent: MLIR dialects and interfaces. Qualification: Unknown required semantics block execution; optional display metadata may round-trip. Sources: Module execution plan, MLIR — Interfaces, Cozzo et al. — Structure of Triadic Relations in Multiplex Networks ## 5. Definitions are not activations or observations Section ID: 5-definitions-are-not-activations-or-observations 5. Definitions are not activations or observations Problem: A deployment plan is mistaken for current reality. Mechanism: Separate revision streams for definitions, activations, observations and evidence. Theory: Temporal databases; partial orders and causal cuts. Precedent: Kubernetes desired/observed state. Qualification: A federated snapshot is not automatically a globally consistent cut. Sources: The Living Graph, Operational graph evidence, Lamport — Distributed clocks, snapshots and temporal specifications, Kubernetes — Controllers ## 6. Source and visual projections share edit authority Section ID: 6-source-and-visual-projections-share-edit-authority 6. Source and visual projections share edit authority Problem: Source and canvas become independent editable truths. Mechanism: One owner per region; source-backed transformations or graph-owned programs. Theory: Bidirectional lenses and round-trip laws. Precedent: MPS projectional editing. Qualification: Round-trip laws apply only to a declared supported language subset. Sources: Source ownership, Visual language, Foster et al. — Combinators for Bidirectional Tree Transformations, JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental) ## 7. General computation with qualified execution profiles Section ID: 7-general-computation-with-qualified-execution-profiles 7. General computation with qualified execution profiles Problem: A DAG-only tool cannot express the intended systems. Mechanism: Executable regions with control, state and effects; specialized actor/stream/native profiles. Theory: Operational semantics; abstract machines; models of computation. Precedent: Ptolemy directors; ordinary compilers. Qualification: Turing completeness provides expressiveness, not decidable verification or bounded execution. Sources: The Living Graph, Actor execution model, Ptolemy II: hierarchy, ports and models of computation, Lee & Parks — Dataflow Process Networks (1995) ## 8. Protocols, not only payload types Section ID: 8-protocols-not-only-payload-types 8. Protocols, not only payload types Problem: A well-typed message can arrive in an illegal phase. Mechanism: Versioned interaction protocols, local state machines, cancellation and completion semantics. Theory: Session types; labelled transition systems; Petri nets. Precedent: Session-type research; Temporal execution contracts. Qualification: Progress guarantees require specified failures, fairness and transport assumptions. Sources: Service contracts, Graph protocol, Honda, Yoshida & Carbone — Multiparty Asynchronous Session Types, A Mechanised Theory of Multiparty Asynchronous Session Types (ECOOP 2025), Temporal — Workflow execution ## 9. Explicit state, lifetime and resource ownership Section ID: 9-explicit-state-lifetime-and-resource-ownership 9. Explicit state, lifetime and resource ownership Problem: GC, native buffers, actors and host teardown disagree. Mechanism: Owners, leases, affinity, borrow scopes and activation epochs. Theory: Linear/affine resource reasoning; structured lifetimes. Precedent: WIT resources; Arrow release callbacks; Erlang ownership. Qualification: A generation handle prevents reuse confusion, not arbitrary native memory corruption. Sources: Component lifecycle, Actor execution model, FFI / Switchboard, WebAssembly Component Model — WIT, Apache Arrow — C data interface ## 10. Effects and authority are different contracts Section ID: 10-effects-and-authority-are-different-contracts 10. Effects and authority are different contracts Problem: Knowing an API exists is mistaken for permission to use it. Mechanism: Effect declarations, scoped grants, policy decisions and actual effect receipts. Theory: Effect systems; non-amplification and access-control invariants. Precedent: Koka effect typing; reference-monitor architecture. Qualification: A graph annotation does not sandbox trusted in-process code. Sources: Formal methods and evidence, Authentication module, Koka — Types and effect handlers ## 11. Adaptive capability selection Section ID: 11-adaptive-capability-selection 11. Adaptive capability selection Problem: Platform conditionals and fallback logic scatter throughout apps. Mechanism: Filter offers by hard constraints and authority, then rank qualified preferences. Theory: Constraint satisfaction; partial orders; control hysteresis. Precedent: Ptolemy/FMI qualified heterogeneous implementations are partial precedents. Qualification: No single cited precedent supplies the whole Reaktor adaptation contract. Sources: Capability selection, Reaktor plan and roadmap, Functional Mock-up Interface — Model exchange and co-simulation ## 12. Multiple backends preserve one contract Section ID: 12-multiple-backends-preserve-one-contract 12. Multiple backends preserve one contract Problem: Cross-platform code paths silently change semantics. Mechanism: Semantic profiles, lowering legality, source maps and translation qualification. Theory: Compiler refinement and simulation relations. Precedent: MLIR conversion targets and dialect interfaces. Qualification: A successful conversion is not itself a proof of behavioral equivalence. Sources: The Living Graph, MLIR — Dialect conversion, MLIR — Interfaces ## 13. One interop contract, several physical paths Section ID: 13-one-interop-contract-several-physical-paths 13. One interop contract, several physical paths Problem: Each language pair becomes a bespoke bridge. Mechanism: Switchboard + Service contracts; direct typed calls or framed FlexBuffers and leased attachments. Theory: Representation independence; ABI lowering; resource semantics. Precedent: WIT/Canonical ABI; Arrow C data interface. Qualification: Zero-copy is qualified per address space and lifetime, not promised universally. Sources: FFI / Switchboard, Mutable memory and publication, WebAssembly Component Model — WIT, Apache Arrow — C data interface ## 14. Transactional system definitions Section ID: 14-transactional-system-definitions 14. Transactional system definitions Problem: Partial edits produce invalid intermediate published systems. Mechanism: Immutable snapshots, typed patches, per-authority serialized commit and durable receipts. Theory: MVCC; serializability; atomic state transition. Precedent: SQLite; PostgreSQL; FoundationDB. Qualification: Graph ACID does not atomically include remote APIs or unrelated application databases. Sources: Stable foundations, Data transactions, SQLite — Isolation, PostgreSQL — Transaction isolation, FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) ## 15. Legal rewrites carry obligations Section ID: 15-legal-rewrites-carry-obligations 15. Legal rewrites carry obligations Problem: A valid syntax edit breaks references, authority or invariants. Mechanism: Preconditions, boundary mappings, affected invariants and explicit authority changes. Theory: DPO rewriting; Hoare-style preservation; assume/guarantee reasoning. Precedent: Graph transformation research; compiler rewrite systems. Qualification: Structural preservation is weaker than behavior preservation. Sources: Formal methods and evidence, Stable foundations, Patch Graph Rewriting: comparison with DPO rewriting, MLIR — Dialect conversion ## 16. Coordination follows invariants Section ID: 16-coordination-follows-invariants 16. Coordination follows invariants Problem: Optimistic collaboration violates exclusive bindings or ownership. Mechanism: Start conservative; coordinate where merges are not invariant-confluent. Theory: Invariant confluence; predicate conflicts. Precedent: Serializable databases. Qualification: Commuting writes do not necessarily preserve invariants after merge. Sources: Data transactions, PostgreSQL — Transaction isolation, Bailis et al. — Coordination Avoidance in Database Systems ## 17. Deployment is recoverable realization Section ID: 17-deployment-is-recoverable-realization 17. Deployment is recoverable realization Problem: Restoring a graph pointer is mistaken for undoing external effects. Mechanism: Desired release manifest; prepared activation root; fences, drain and compensations. Theory: State-machine replication; reconciliation; sagas. Precedent: Kubernetes controllers; Erlang release handling; Temporal. Qualification: Rollback after an incompatible data migration may require forward repair. Sources: Component lifecycle, DevOps integration, Kubernetes — Controllers, Erlang/OTP — Release handling, Temporal — Workflow execution ## 18. Incremental queries and transformations Section ID: 18-incremental-queries-and-transformations 18. Incremental queries and transformations Problem: Every tool rescans the full graph after every change. Mechanism: Indexed relations and dependency-tracked derivations across queries, plans and evidence. Theory: Fixed-point computation; incremental view maintenance; build calculus. Precedent: Differential Dataflow; Build Systems à la Carte. Qualification: Absence predicates and opaque dependencies must invalidate conservatively. Sources: Graph visitors, Module execution plan, McSherry et al. — Differential Dataflow, Mokhov, Mitchell & Peyton Jones — Build Systems à la Carte ## 19. Shadow executes controlled counterfactuals Section ID: 19-shadow-executes-controlled-counterfactuals 19. Shadow executes controlled counterfactuals Problem: Production defects are expensive to reproduce or compare. Mechanism: Pinned input/state/artifact closures with explicit substitution boundaries and fault schedules. Theory: Transition systems; deterministic simulation; controlled comparison. Precedent: FoundationDB simulation; durable workflow replay. Qualification: Replay fidelity and model coverage constrain the claims it supports. Sources: Shadow foundations, Capture and replay, Shadow verification and capsules, FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021), Temporal — Workflow execution ## 20. Claim-indexed evidence, not a global green check Section ID: 20-claim-indexed-evidence-not-a-global-green-check 20. Claim-indexed evidence, not a global green check Problem: Tests and proofs get oversold as universal correctness. Mechanism: Claim → assumptions → evidence → verifier → artifact and coverage. Theory: Proof obligations; epistemic scope; partial orders. Precedent: TLA+ models; translation validation; simulation test portfolios. Qualification: This revises the docs’ ordinal EvidenceLevel model; evidence kinds are not totally ordered. Sources: Formal methods and evidence, Shadow verification and capsules, Lamport — A high-level view of TLA+, MLIR — Dialect conversion, FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) ## 21. Maps make one model legible Section ID: 21-maps-make-one-model-legible 21. Maps make one model legible Problem: A universal canvas becomes an unreadable hairball. Mechanism: Task-scoped maps, semantic zoom, projections and provenance-aware unknowns. Theory: Graph queries; abstraction; information hiding. Precedent: Ptolemy hierarchy; compiler IR views; structured editors. Qualification: A diagram is a presentation, not the authority for inferred missing facts. Sources: Graph visitors, Workbench layers, Ptolemy II: hierarchy, ports and models of computation ## 22. Human and agent actions share commands Section ID: 22-human-and-agent-actions-share-commands 22. Human and agent actions share commands Problem: Agents act through brittle text edits and privileged shortcuts. Mechanism: Typed commands, scoped reads, patch validation, receipts and the same policy gates. Theory: Capability discipline; transition-system semantics; projectional editing. Precedent: MPS Projectional Agent Toolkit (experimental, 2026.1). Qualification: MPS already supplies structured agent editing. External harness tools may bypass graph commands unless their effective authority is qualified. Sources: Workbench layers, Formal methods and evidence, JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental), Conductor harness boundaries ## 23. Interaction semantics are portable, rendering remains specialized Section ID: 23-interaction-semantics-are-portable-rendering-remains-specialized 23. Interaction semantics are portable, rendering remains specialized Problem: Generic cross-platform trees destroy performance or accessibility. Mechanism: State/events/behavior contracts with specialized renderer and island implementations. Theory: State machines; refinement; unidirectional dataflow. Precedent: Compose architecture; Unreal native visual scripting. Qualification: Preserve focus, IME, drafts and assistive semantics; not merely visual similarity. Sources: Surface contracts and interaction, Dynamic UI and verification, Surface renderers, Jetpack Compose — Architecture and state, Unreal Engine — Introduction to Blueprints ## 24. Reusable features include operational obligations Section ID: 24-reusable-features-include-operational-obligations 24. Reusable features include operational obligations Problem: Reusing a library does not transfer its deployment or safety assumptions. Mechanism: Feature regions package contracts, effects, placement, migrations and acceptance scenarios. Theory: Assume/guarantee composition; refinement types. Precedent: FMI component exchange; reusable workflow/component systems. Qualification: Reuse reduces obligations only when environment assumptions are discharged. Sources: Reaktor plan and roadmap, Module execution plan, Functional Mock-up Interface — Model exchange and co-simulation, Honda, Yoshida & Carbone — Multiparty Asynchronous Session Types ## 25. Privacy and trust survive inspection and replay Section ID: 25-privacy-and-trust-survive-inspection-and-replay 25. Privacy and trust survive inspection and replay Problem: Immutable histories retain secrets or resurrect deleted data. Mechanism: Artifact references, scoped disclosure, retention/revocation and suppression records. Theory: Information-flow reasoning; provenance; lifecycle policies. Precedent: Existing storage/identity systems remain the enforcement providers. Qualification: Reference retention is not a legal compliance proof or automatic secure erasure. Sources: Shadow workspaces, Shadow verification and capsules, Authentication module ## 26. Adoption and qualification are part of the architecture Section ID: 26-adoption-and-qualification-are-part-of-the-architecture 26. Adoption and qualification are part of the architecture Problem: The platform only works after a complete rewrite. Mechanism: Library-first boundaries, honest opaque regions, native escape hatches and measured guarantees. Theory: Refinement boundaries; experimental ablation; modularity. Precedent: MLIR incremental adoption; MPS host integration; specialist runtimes. Qualification: The benefit must exceed modeling, runtime and operational overhead for external teams. Sources: The Living Graph, Reaktor plan and roadmap, MLIR — Dialect conversion, JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental) ## 3. Semantic kernel and graph substrate Section ID: 3-semantic-kernel-and-graph-substrate 3. Semantic kernel and graph substrate The semantic kernel should own stable identity, typed incidence structure, region boundaries, schemas, protocols, effect/ownership declarations, immutable snapshots and a closed change algebra. It should expose indexed query and transformation facilities. Modules contribute domain vocabulary, validators, lowerings, providers and inspection support. It should not own every product record, event sample, media frame or game transform. It also should not force every operation through a mailbox or a serialized value tree. The same declared service may use a direct typed call, a framed FFI call, a live session or a durable request profile where the chosen contract supports that interpretation. [The Living Graph] [Data graph] [Service contracts] [FFI / Switchboard] Integration is not an import dependency. Low-level core, storage and authorization libraries can remain graph-free. Their graph-facing modules register facts, resources and effects at the composition boundary. Otherwise “everything uses the graph” creates cyclic dependencies and prevents headless or incremental adoption. The existing Core and Build Tools documents already establish the relevant separation. [Core dependency boundary] [Build control-plane responsibilities] Likewise, one common semantic identity system need not imply one centralized database or transaction domain. A device, server and authority can have local publication rules and a declared distributed revision vector. The federation must explain what it knows and what it cannot yet join; it must not invent global simultaneity. ## Open-world node, port and relation grammar Section ID: open-world-node-port-and-relation-grammar Open-world node, port and relation grammar An extensible system cannot enumerate all future domain types. This catalog instead gives a generative specification and 100 concrete starter entries: 40 node families, 24 port profiles and 36 hyperedge schemas. Families overlap through facets. They are not 100 mandatory kernel classes or proof that every combination is meaningful. Node descriptor = semantic family + facets + owned ports + execution profile + source/instance/lifetime metadata. A node may describe a pure function, actor, store, UI component, native adapter, schema, deployment or evidence record. Represent a value as its own node only when identity, relationships, ownership or provenance justify doing so. Port contract = payload/schema × protocol × incidence role × multiplicity × ownership/lifetime × effects/required authority × clock/ordering × target requirements. This is a constraint product: many combinations are invalid. A borrowed GPU buffer cannot simply be sent to a remote host as an ordinary value. Hyperedge descriptor = typed roles with per-role cardinalities + relation laws + layer + optional execution interpretation. Binary bindings are two-incidence specializations. A transaction hyperedge records participation under a named authority; it does not create a distributed transaction. A quorum relation does not implement consensus. An authorization relation does not itself grant access. Adding a module means registering versioned schemas, compatible port descriptors, relation invariants, optional validators/lowerings, tooling metadata, migration and qualification support. Unknown optional inspection metadata can round-trip. Unknown required execution semantics block execution. Nothing requires adding every domain type to a central enum. For FFI, use the existing Switchboard contract and graph identities. FlexBuffers carries checked structured values, manifests and patch metadata; leased attachments carry large buffers/resources where allowed. The typed contract lives above the wire encoding. Local direct calls and serialized calls are two lowerings, not separate semantic APIs. Reaktor FFI / Switchboard ## The graph is the system language Section ID: panel-system The graph is the system language The revised center is a small semantic kernel plus qualified interpretations and changes. A common system language, not a universal runtime Law / model / proof obligation: meaning → legal plan → qualified realization → attributable observation Diagram: A common system language, not a universal runtime AUTHORED MEANING • ONE OWNER PER REGION Source / Blueprint Module contributions Build facts REVISIONED SEMANTIC AUTHORITY Typed port hypergraph Identity + schemas + protocols Regions + effects + ownership Queries and legal changes Maps + analyses + patches Scoped authority + obligations CLAIMS AND EVIDENCE Shadow + qualification Pinned candidate and assumptions No universal “verified” state SPECIALIZED EXECUTION • NO GRAPH DATABASE LOOKUP REQUIRED ON EVERY CALL Compiled images Direct bindings; typed value paths Qualified runtime profiles Actors · streams · Work · native Realization and observation Release vector; receipts; provenance Integration is semantic accountability—not one global store, process, scheduler or universal representation. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision Keep graph semantics authoritative while letting Gradle, platform renderers, databases and native kernels do their specialized jobs. Low-level libraries can remain graph-free; higher-layer contributions register the operational boundary. ## What this does not establish Section ID: what-this-does-not-establish What this does not establish A universal graph-shaped intermediate object on every hot call would defeat the performance and adoption goals. A diagram cannot certify unmodeled native or external harness behavior. Falsifiable acceptance test. Replace a service region across two runtimes; trace its source, policy, artifacts and outcomes without inventing a second identity graph. Theory, precedent and Reaktor context: The Living Graph Core dependency boundary Module execution plan FFI / Switchboard Build control-plane responsibilities ## Core ideas and invariants Section ID: panel-ideas Core ideas and invariants Twenty-six ideas covering meaning, execution, controlled change and leverage. Precedents support individual mechanisms; the complete integration is a design hypothesis to qualify. 01One semantic identity system Problem Duplicated models drift across build, runtime and tools. Reaktor mechanism Stable definition, operation and resource identities; versioned joins to artifacts and activations. Theory Denotational meaning; content-addressed identity. Precedent Unison; MLIR symbol/operation models. Qualification Stable identity is not the same as a mutable name, hash or runtime address. The Living Graph Source ownership Unison — Code as content-addressed definitions MLIR — Interfaces 02Typed, role-labelled port hypergraph Problem Binary links lose the meaning of multi-party relations. Reaktor mechanism Nodes own ports; incidences carry relation, role and optional position. Theory Typed hypergraphs; relational incidence models. Precedent Ptolemy II port-connected actors. Qualification Topology does not define ordering, coordination or protocol progress. Graph substrate redesign Data graph Ptolemy II: hierarchy, ports and models of computation 03Open hierarchical regions Problem Reuse must preserve boundaries while changing internals. Reaktor mechanism Exported ports and explicit replacement boundary mappings. Theory Cospans; symmetric monoidal composition; typed substitution. Precedent Ptolemy hierarchical composition; FMI boundaries. Qualification Ownership-constrained composition must not introduce arbitrary resource copying. The Living Graph Fong — Decorated Cospans (2015) Functional Mock-up Interface — Model exchange and co-simulation 04Orthogonal facets and semantic layers Problem Class inheritance and duplicate graphs couple unrelated concerns. Reaktor mechanism One identity space, typed facts and relation families; versioned dialects. Theory Multilayer graphs; extensible algebraic signatures. Precedent MLIR dialects and interfaces. Qualification Unknown required semantics block execution; optional display metadata may round-trip. Module execution plan MLIR — Interfaces Cozzo et al. — Structure of Triadic Relations in Multiplex Networks 05Definitions are not activations or observations Problem A deployment plan is mistaken for current reality. Reaktor mechanism Separate revision streams for definitions, activations, observations and evidence. Theory Temporal databases; partial orders and causal cuts. Precedent Kubernetes desired/observed state. Qualification A federated snapshot is not automatically a globally consistent cut. The Living Graph Operational graph evidence Lamport — Distributed clocks, snapshots and temporal specifications Kubernetes — Controllers 06Source and visual projections share edit authority Problem Source and canvas become independent editable truths. Reaktor mechanism One owner per region; source-backed transformations or graph-owned programs. Theory Bidirectional lenses and round-trip laws. Precedent MPS projectional editing. Qualification Round-trip laws apply only to a declared supported language subset. Source ownership Visual language Foster et al. — Combinators for Bidirectional Tree Transformations JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental) 07General computation with qualified execution profiles Problem A DAG-only tool cannot express the intended systems. Reaktor mechanism Executable regions with control, state and effects; specialized actor/stream/native profiles. Theory Operational semantics; abstract machines; models of computation. Precedent Ptolemy directors; ordinary compilers. Qualification Turing completeness provides expressiveness, not decidable verification or bounded execution. The Living Graph Actor execution model Ptolemy II: hierarchy, ports and models of computation Lee & Parks — Dataflow Process Networks (1995) 08Protocols, not only payload types Problem A well-typed message can arrive in an illegal phase. Reaktor mechanism Versioned interaction protocols, local state machines, cancellation and completion semantics. Theory Session types; labelled transition systems; Petri nets. Precedent Session-type research; Temporal execution contracts. Qualification Progress guarantees require specified failures, fairness and transport assumptions. Service contracts Graph protocol Honda, Yoshida & Carbone — Multiparty Asynchronous Session Types A Mechanised Theory of Multiparty Asynchronous Session Types (ECOOP 2025) Temporal — Workflow execution 09Explicit state, lifetime and resource ownership Problem GC, native buffers, actors and host teardown disagree. Reaktor mechanism Owners, leases, affinity, borrow scopes and activation epochs. Theory Linear/affine resource reasoning; structured lifetimes. Precedent WIT resources; Arrow release callbacks; Erlang ownership. Qualification A generation handle prevents reuse confusion, not arbitrary native memory corruption. Component lifecycle Actor execution model FFI / Switchboard WebAssembly Component Model — WIT Apache Arrow — C data interface 10Effects and authority are different contracts Problem Knowing an API exists is mistaken for permission to use it. Reaktor mechanism Effect declarations, scoped grants, policy decisions and actual effect receipts. Theory Effect systems; non-amplification and access-control invariants. Precedent Koka effect typing; reference-monitor architecture. Qualification A graph annotation does not sandbox trusted in-process code. Formal methods and evidence Authentication module Koka — Types and effect handlers 11Adaptive capability selection Problem Platform conditionals and fallback logic scatter throughout apps. Reaktor mechanism Filter offers by hard constraints and authority, then rank qualified preferences. Theory Constraint satisfaction; partial orders; control hysteresis. Precedent Ptolemy/FMI qualified heterogeneous implementations are partial precedents. Qualification No single cited precedent supplies the whole Reaktor adaptation contract. Capability selection Reaktor plan and roadmap Functional Mock-up Interface — Model exchange and co-simulation 12Multiple backends preserve one contract Problem Cross-platform code paths silently change semantics. Reaktor mechanism Semantic profiles, lowering legality, source maps and translation qualification. Theory Compiler refinement and simulation relations. Precedent MLIR conversion targets and dialect interfaces. Qualification A successful conversion is not itself a proof of behavioral equivalence. The Living Graph MLIR — Dialect conversion MLIR — Interfaces 13One interop contract, several physical paths Problem Each language pair becomes a bespoke bridge. Reaktor mechanism Switchboard + Service contracts; direct typed calls or framed FlexBuffers and leased attachments. Theory Representation independence; ABI lowering; resource semantics. Precedent WIT/Canonical ABI; Arrow C data interface. Qualification Zero-copy is qualified per address space and lifetime, not promised universally. FFI / Switchboard Mutable memory and publication WebAssembly Component Model — WIT Apache Arrow — C data interface 14Transactional system definitions Problem Partial edits produce invalid intermediate published systems. Reaktor mechanism Immutable snapshots, typed patches, per-authority serialized commit and durable receipts. Theory MVCC; serializability; atomic state transition. Precedent SQLite; PostgreSQL; FoundationDB. Qualification Graph ACID does not atomically include remote APIs or unrelated application databases. Stable foundations Data transactions SQLite — Isolation PostgreSQL — Transaction isolation FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) 15Legal rewrites carry obligations Problem A valid syntax edit breaks references, authority or invariants. Reaktor mechanism Preconditions, boundary mappings, affected invariants and explicit authority changes. Theory DPO rewriting; Hoare-style preservation; assume/guarantee reasoning. Precedent Graph transformation research; compiler rewrite systems. Qualification Structural preservation is weaker than behavior preservation. Formal methods and evidence Stable foundations Patch Graph Rewriting: comparison with DPO rewriting MLIR — Dialect conversion 16Coordination follows invariants Problem Optimistic collaboration violates exclusive bindings or ownership. Reaktor mechanism Start conservative; coordinate where merges are not invariant-confluent. Theory Invariant confluence; predicate conflicts. Precedent Serializable databases. Qualification Commuting writes do not necessarily preserve invariants after merge. Data transactions PostgreSQL — Transaction isolation Bailis et al. — Coordination Avoidance in Database Systems 17Deployment is recoverable realization Problem Restoring a graph pointer is mistaken for undoing external effects. Reaktor mechanism Desired release manifest; prepared activation root; fences, drain and compensations. Theory State-machine replication; reconciliation; sagas. Precedent Kubernetes controllers; Erlang release handling; Temporal. Qualification Rollback after an incompatible data migration may require forward repair. Component lifecycle DevOps integration Kubernetes — Controllers Erlang/OTP — Release handling Temporal — Workflow execution 18Incremental queries and transformations Problem Every tool rescans the full graph after every change. Reaktor mechanism Indexed relations and dependency-tracked derivations across queries, plans and evidence. Theory Fixed-point computation; incremental view maintenance; build calculus. Precedent Differential Dataflow; Build Systems à la Carte. Qualification Absence predicates and opaque dependencies must invalidate conservatively. Graph visitors Module execution plan McSherry et al. — Differential Dataflow Mokhov, Mitchell & Peyton Jones — Build Systems à la Carte 19Shadow executes controlled counterfactuals Problem Production defects are expensive to reproduce or compare. Reaktor mechanism Pinned input/state/artifact closures with explicit substitution boundaries and fault schedules. Theory Transition systems; deterministic simulation; controlled comparison. Precedent FoundationDB simulation; durable workflow replay. Qualification Replay fidelity and model coverage constrain the claims it supports. Shadow foundations Capture and replay Shadow verification and capsules FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) Temporal — Workflow execution 20Claim-indexed evidence, not a global green check Problem Tests and proofs get oversold as universal correctness. Reaktor mechanism Claim → assumptions → evidence → verifier → artifact and coverage. Theory Proof obligations; epistemic scope; partial orders. Precedent TLA+ models; translation validation; simulation test portfolios. Qualification This revises the docs’ ordinal EvidenceLevel model; evidence kinds are not totally ordered. Formal methods and evidence Shadow verification and capsules Lamport — A high-level view of TLA+ MLIR — Dialect conversion FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) 21Maps make one model legible Problem A universal canvas becomes an unreadable hairball. Reaktor mechanism Task-scoped maps, semantic zoom, projections and provenance-aware unknowns. Theory Graph queries; abstraction; information hiding. Precedent Ptolemy hierarchy; compiler IR views; structured editors. Qualification A diagram is a presentation, not the authority for inferred missing facts. Graph visitors Workbench layers Ptolemy II: hierarchy, ports and models of computation 22Human and agent actions share commands Problem Agents act through brittle text edits and privileged shortcuts. Reaktor mechanism Typed commands, scoped reads, patch validation, receipts and the same policy gates. Theory Capability discipline; transition-system semantics; projectional editing. Precedent MPS Projectional Agent Toolkit (experimental, 2026.1). Qualification MPS already supplies structured agent editing. External harness tools may bypass graph commands unless their effective authority is qualified. Workbench layers Formal methods and evidence JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental) Conductor harness boundaries 23Interaction semantics are portable, rendering remains specialized Problem Generic cross-platform trees destroy performance or accessibility. Reaktor mechanism State/events/behavior contracts with specialized renderer and island implementations. Theory State machines; refinement; unidirectional dataflow. Precedent Compose architecture; Unreal native visual scripting. Qualification Preserve focus, IME, drafts and assistive semantics; not merely visual similarity. Surface contracts and interaction Dynamic UI and verification Surface renderers Jetpack Compose — Architecture and state Unreal Engine — Introduction to Blueprints 24Reusable features include operational obligations Problem Reusing a library does not transfer its deployment or safety assumptions. Reaktor mechanism Feature regions package contracts, effects, placement, migrations and acceptance scenarios. Theory Assume/guarantee composition; refinement types. Precedent FMI component exchange; reusable workflow/component systems. Qualification Reuse reduces obligations only when environment assumptions are discharged. Reaktor plan and roadmap Module execution plan Functional Mock-up Interface — Model exchange and co-simulation Honda, Yoshida & Carbone — Multiparty Asynchronous Session Types 25Privacy and trust survive inspection and replay Problem Immutable histories retain secrets or resurrect deleted data. Reaktor mechanism Artifact references, scoped disclosure, retention/revocation and suppression records. Theory Information-flow reasoning; provenance; lifecycle policies. Precedent Existing storage/identity systems remain the enforcement providers. Qualification Reference retention is not a legal compliance proof or automatic secure erasure. Shadow workspaces Shadow verification and capsules Authentication module 26Adoption and qualification are part of the architecture Problem The platform only works after a complete rewrite. Reaktor mechanism Library-first boundaries, honest opaque regions, native escape hatches and measured guarantees. Theory Refinement boundaries; experimental ablation; modularity. Precedent MLIR incremental adoption; MPS host integration; specialist runtimes. Qualification The benefit must exceed modeling, runtime and operational overhead for external teams. The Living Graph Reaktor plan and roadmap MLIR — Dialect conversion JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental) ## Reusable feature contracts Section ID: panel-contracts Reusable feature contracts Assume/guarantee reasoning is the practical bridge between libraries and system-level confidence. A reusable feature should expose what makes it safe Law / model / proof obligation: Environment ⊨ A(C), and (implementation C under A(C)) ⊨ G(C), under the declared model. Diagram: A reusable feature should expose what makes it safe COMPOSITIONAL REASONING • REUSE TRANSFERS CONDITIONS, NOT MAGIC Environment assumptions A: authenticated principal B: serial state owner C: durable conditional commit Component contract Under A ∧ B ∧ C, guarantee one logical result. Name the observation boundary. System obligation Prove/bind assumptions or weaken the guarantee. Attach qualifying evidence. An adapter must preserve the assumptions it relies on A local mutex is not a distributed compare-and-swap. A signed tenant label is not permission to every resource. Compositional verification works only when contracts, environment assumptions and refinement boundaries align. ## Reaktor design decision Section ID: reaktor-design-decision-1 Reaktor design decision Package the conditions of a reusable region alongside its code: owner, protocol, replay-safe effects, migration requirements, acceptance and evidence. Composition creates obligations where those assumptions meet the host. ## What this does not establish Section ID: what-this-does-not-establish-1 What this does not establish Assumptions can be wrong, incomplete or circular. Opaque providers need explicit trust/qualification; annotations alone do not discharge their obligations. Falsifiable acceptance test. Bind a component requiring distributed conditional writes to a process-local keyed mutex. Reject the claimed guarantee rather than silently degrading it. Theory, precedent and Reaktor context: Formal methods and evidence Stable foundations Data transactions Multitenancy Functional Mock-up Interface — Model exchange and co-simulation Honda, Yoshida & Carbone — Multiparty Asynchronous Session Types ## Store the relation once; preserve each participant’s role Section ID: panel-incidence Store the relation once; preserve each participant’s role A multi-party relation should not dissolve into unrelated pairwise edges. Store the relation once; preserve each participant’s role Law / model / proof obligation: I ⊆ H × P × Role × Position Diagram: Store the relation once; preserve each participant’s role GRAPH THEORY • ROLE-LABELLED INCIDENCES Client A session port Client B session port Authority session port Observer session port H₁ participant participant authority observer RELATIONAL STORAGE • SAME MEANING Incidence(h, port, role, ordinal) edge port role H₁ A.session participant H₁ B.session participant H₁ S.session authority H₁ O.session observer One authority; many participants. Binary connect() is a specialization. A hyperedge records a relationship. Delivery, scheduling and coordination are separate protocol laws. ## Reaktor design decision Section ID: reaktor-design-decision-2 Reaktor design decision The incidence model supports joins, pub/sub relationships, sessions and replicated groups without manufacturing fake coordinator objects. Fast binary indexes remain possible. ## What this does not establish Section ID: what-this-does-not-establish-2 What this does not establish The “one provider per consumer” invariant belongs to the corresponding binding schema, not every port in every relation. A hyperedge is not automatically an executable join. Falsifiable acceptance test. Add two participants and one authority. Reject a second authority without accidentally rejecting the valid multi-party relationship. Theory, precedent and Reaktor context: Graph substrate redesign Data graph Formal methods and evidence Ptolemy II: hierarchy, ports and models of computation ## An edge’s meaning survives the map Section ID: panel-layers An edge’s meaning survives the map Layer-aware reachability prevents false security, placement and dependency conclusions. An edge’s meaning survives the map Law / model / proof obligation: A(ℓ) is indexed by relation layer; aggregation can destroy relevant distinctions. Diagram: An edge’s meaning survives the map MULTILAYER NETWORKS • DO NOT FLATTEN RELATION MEANING Invocation UI Service Store call write Placement UI Service Store same device / runtime? Authority UI Service Store principal grant tenant grant Shared identity across layers does not imply identical edges, reachability, timestamps or visibility. ## Reaktor design decision Section ID: reaktor-design-decision-3 Reaktor design decision An authorization map can join invocation and policy facts without pretending they are the same relation. Semantic layers are not copied objects or separate sources of truth. ## What this does not establish Section ID: what-this-does-not-establish-3 What this does not establish A path in an aggregated graph may not correspond to a legal path in any execution or authority model. Degree and centrality are diagnostics, not automatic measures of risk. Falsifiable acceptance test. An invocation route reaches a store, but the required grant is missing. The map must flag the mismatch rather than infer permission from connectivity. Theory, precedent and Reaktor context: The Living Graph Graph visitors Cozzo et al. — Structure of Triadic Relations in Multiplex Networks # Compiler, source publication and consistency URL: https://reaktor.build/docs/architecture-atlas-language Status: design Content revision: 7a372d3bd6f1c196e61466c544c224b4c485f4bba39efa16da1f3ab1e0bfc279 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-language","panel-compiler","panel-incremental","panel-capabilities","panel-placement","panel-source","panel-mvcc","panel-causal"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-language","polarity":"Neutral"},{"id":"section-9-compiler-incremental-analysis-and-runtime-lowering","anchor":"9-compiler-incremental-analysis-and-runtime-lowering","label":"9. Compiler, incremental analysis and runtime lowering","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#9-compiler-incremental-analysis-and-runtime-lowering","polarity":"Neutral"},{"id":"section-10-transactions-and-distributed-consistency","anchor":"10-transactions-and-distributed-consistency","label":"10. Transactions and distributed consistency","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#10-transactions-and-distributed-consistency","polarity":"Neutral"},{"id":"section-panel-language","anchor":"panel-language","label":"Blueprint as a distributed-system language","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#panel-language","polarity":"Neutral"},{"id":"section-panel-compiler","anchor":"panel-compiler","label":"Lowering is an obligation to preserve meaning","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#panel-compiler","polarity":"Neutral"},{"id":"section-panel-incremental","anchor":"panel-incremental","label":"One dependency system can serve many tools","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#panel-incremental","polarity":"Neutral"},{"id":"section-panel-capabilities","anchor":"panel-capabilities","label":"Portability should adapt without hiding degradation","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#panel-capabilities","polarity":"Neutral"},{"id":"section-boundary--caveat","anchor":"boundary--caveat","label":"Boundary / caveat","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#boundary--caveat","polarity":"Neutral"},{"id":"section-what-this-does-not-establish","anchor":"what-this-does-not-establish","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#what-this-does-not-establish","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-1","anchor":"what-this-does-not-establish-1","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#what-this-does-not-establish-1","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-2","anchor":"what-this-does-not-establish-2","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#what-this-does-not-establish-2","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-3","anchor":"what-this-does-not-establish-3","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#what-this-does-not-establish-3","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-4","anchor":"what-this-does-not-establish-4","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#what-this-does-not-establish-4","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-6","anchor":"what-this-does-not-establish-6","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-language#what-this-does-not-establish-6","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-language:references-architecture-atlas-foundations","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-architecture-atlas-vocabulary","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-vocabulary","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-architecture-atlas-semantics","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-semantics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-architecture-atlas-evolution","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-evolution","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-architecture-atlas-workbench","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-architecture-atlas-scenarios","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-scenarios","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-architecture-atlas-qualification","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-qualification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-ffi","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-9-compiler-incremental-analysis-and-runtime-lowering","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-work","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-10-transactions-and-distributed-consistency","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-stable-foundations-5.6-ultra","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-10-transactions-and-distributed-consistency","role":"source","ordinal":0},{"node":"reaktor-stable-foundations-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-flatbuffers-flexbuffers-mutable-memory-05-mutable-memory","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-10-transactions-and-distributed-consistency","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-05-mutable-memory","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-data-transactions","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-10-transactions-and-distributed-consistency","role":"source","ordinal":0},{"node":"reaktor-data-transactions","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-boundary--caveat","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-unified-system-graph","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-boundary--caveat","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-formal-methods","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish","role":"source","ordinal":0},{"node":"reaktor-formal-methods","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-module-execution-plan","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-1","role":"source","ordinal":0},{"node":"reaktor-module-execution-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor_graph_visitors_design","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-1","role":"source","ordinal":0},{"node":"reaktor_graph_visitors_design","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-capability","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-2","role":"source","ordinal":0},{"node":"reaktor-capability","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-astra-reaktor-plan-and-roadmap","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-2","role":"source","ordinal":0},{"node":"astra-reaktor-plan-and-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-db","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-3","role":"source","ordinal":0},{"node":"reaktor-db","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-mesh","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-3","role":"source","ordinal":0},{"node":"reaktor-mesh","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-graph-sources","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-4","role":"source","ordinal":0},{"node":"reaktor-graph-sources","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-reaktor-devops","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-4","role":"source","ordinal":0},{"node":"reaktor-devops","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-shadow-workspaces","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-6","role":"source","ordinal":0},{"node":"shadow-workspaces","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-language:references-operations-graph-evidence","kind":"references","owner":"architecture-atlas-language","incidences":[{"node":"architecture-atlas-language","port":"section-what-this-does-not-establish-6","role":"source","ordinal":0},{"node":"operations-graph-evidence","port":"page","role":"target","ordinal":0}]}]} ## Compiler, source publication and consistency Section ID: compiler-source-publication-and-consistency Compiler, source publication and consistency Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification ## 9. Compiler, incremental analysis and runtime lowering Section ID: 9-compiler-incremental-analysis-and-runtime-lowering 9. Compiler, incremental analysis and runtime lowering The compiler should turn semantic regions into execution images with explicit legality and type/effect interfaces. Local pure calls can become direct calls; static regions can be fused; reactive renderers can keep host-native fast paths. The graph remains their identity and contract authority rather than their per-call interpreter. MLIR is a precedent for extensible operations, dialect interfaces and legality-driven lowering. It is neither a graph database nor an automatic proof of semantic equivalence. For each Reaktor profile, define observations and require the compiled result to refine the reference behavior under the relevant environment assumptions. A reference interpreter and differential corpus are a practical first semantic oracle. [MLIR — Interfaces] [MLIR — Dialect conversion] Effects, protocol phases and ownership must survive lowering—not only primitive type layouts. A JVM exception, canceled coroutine, rejected remote request and dropped native callback have different possible outcomes. Unsupported target/lifetime combinations should fail generation or admission instead of becoming latent runtime failures. One dependency-tracked analysis service can support queries, build invalidation, deployment planning and evidence freshness. Differential Dataflow and build-system calculus supply relevant precedents. Negative facts and opaque dependencies must remain conservative; an optimized cache is not correct merely because it computes quickly. [FFI / Switchboard] [Koka — Types and effect handlers] [McSherry et al. — Differential Dataflow] [Mokhov, Mitchell & Peyton Jones — Build Systems à la Carte] ## 10. Transactions and distributed consistency Section ID: 10-transactions-and-distributed-consistency 10. Transactions and distributed consistency Start with immutable snapshot readers and one commit serialization point per authority domain. A candidate records its exact base; commit checks the base and current authorization, validates transition obligations, durably records the revision and intent, then publishes the new root. Receipts handle a lost reply without duplicating the logical mutation. Whole-head comparison is deliberately conservative. Two candidates can write different edge records and still violate an exclusive-port invariant. Finer concurrency requires read and predicate conflict tracking, not merely intersecting write sets. Invariant-confluence theory explains why some merge operations can avoid coordination while others cannot. [SQLite — Isolation] [PostgreSQL — Transaction isolation] [Bailis et al. — Coordination Avoidance in Database Systems] Use an existing qualified storage authority before inventing a bespoke transactional database. The hot graph can still have compact columns, incidence indexes and copy-on-write directories. Work and storage primitives deserve reuse and conformance tests, but a local keyed mutex, a retained inspection window or a process-local Flow must not be mistaken for distributed conditional writes or a complete durable journal. [Durable work] [Stable foundations] [Mutable memory and publication] Separate graph commit, application-data commit, activation and external realization. An outbox for a domain mutation belongs in the same authority transaction as that mutation. Source artifacts may need staged publication rather than shared ACID. Deployment needs recoverable intents, fencing and state migration; returning to an older program creates a new activation epoch. Abort, semantic revert, application restore, simulation rewind and external compensation are different commands. Keeping that distinction in the type system prevents a rollback button from promising an impossible undo. [Data transactions] [Kubernetes — Controllers] [Erlang/OTP — Release handling] ## Blueprint as a distributed-system language Section ID: panel-language Blueprint as a distributed-system language Compile one feature into a linked set of runtime artifacts and operational obligations—not unrelated source files. Vector diagram · click a marked item to inspect Compile a feature into a Reaktor distributed program bundle Diagram: Compile a feature into a Reaktor distributed program bundle Blueprint source / typed region feature Checkout { surface : CheckoutView behavior : CheckoutStatechart command : PlaceOrder work : CheckoutSaga authority : OrderStore ports : Payment, Inventory effect : Charge, Reserve target : Client + Core update : CompatibleRegion } Illustrative syntax, not a shipped API. Elaborate one semantic graph Types • roles • effects • ownership Statecharts, functions, resources Validate + partition + lower Legal profiles and host requirements Runtime cuts / durable boundaries Stable IDs ↔ source maps ProgramBundle Graph revision + region definitions Per-runtime code / interpreted plans Service + Switchboard descriptors Schemas + artifact/dependency vector Placement + grants + durable intent Verification and migration obligations Client region Surface plan + compatible logic Native capabilities already installed Service region JVM / Worker artifact Command + effect boundary State / Work region Store schema + workflow definition Durability and ownership profiles A distributed-system target, not a distributed interpreter Definitions describe composition; execution runs on qualified local hosts and communicates through explicit protocols. Graph transactions publish desired meaning. Realization performs recoverable deployment effects. FlexBuffers handles structured interchange; direct calls and leased buffers retain specialized fast paths. A graph-owned program can generate Kotlin/JS/C++ adapters without making generated source a second edit authority. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision Make the complete distributed program bundle the compilation target. Existing host languages implement algorithms and opaque regions; graph-owned behavior supports higher-level composition. ## Boundary / caveat Section ID: boundary--caveat Boundary / caveat No single physical VM spans the network. Target-specific failures, schedulers, persistence and memory limits remain observable semantics. Qualification test. Compile the same declared feature for a supported local fixture and a remote service profile; check protocol/effect observations, not just matching payload schemas. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Lowering is an obligation to preserve meaning Section ID: panel-compiler Lowering is an obligation to preserve meaning A backend is valid because of what it preserves, not because it accepts the syntax. Lowering is an obligation to preserve meaning Law / model / proof obligation: Obs(run(compile(P), E)) refines Obs(semantics(P, E)) for the supported profile and assumptions. Diagram: Lowering is an obligation to preserve meaning COMPILER THEORY • A COMMUTING SEMANTIC SQUARE Graph behavior region Typed control + values + effects Reference semantics Target execution image JVM / JS / native / Wasm Qualified lowering Specified observable behavior Chosen profile and environment Includes allowed failures Observed target behavior Compare the same observations Retain source / graph identity compile interpret execute required refinement relation The two routes must agree under the declared observation model. Timing and failures may require refinement, not equality. ## Reaktor design decision Section ID: reaktor-design-decision-1 Reaktor design decision Define one semantic oracle for portable behavior; qualify generated target paths with differential tests, bounded models and stronger proofs where useful. MLIR-style interfaces let generic passes ask about effects and regions. ## What this does not establish Section ID: what-this-does-not-establish What this does not establish Whole-program equivalence is not decidable in general. Unknown operations remain opaque; successful type conversion does not establish every runtime property. Falsifiable acceptance test. Compile a behavior with cancellation and borrowed buffers to two targets; compare terminal outcomes and lifetime violations, not merely return values. Theory, precedent and Reaktor context: MLIR — Dialect conversion MLIR — Interfaces Formal methods and evidence The Living Graph ## One dependency system can serve many tools Section ID: panel-incremental One dependency system can serve many tools Queries, compiler plans and evidence should not each invent incomplete invalidation rules. One dependency system can serve many tools Law / model / proof obligation: Δinputs → affected derivations; unknown dependency coverage widens invalidation conservatively. Diagram: One dependency system can serve many tools INCREMENTAL COMPUTATION • INVALIDATE BY DEPENDENCY, INCLUDING ABSENCE Port contract changes New field or protocol rule Generated bindings Depends on this contract Compatibility query Depends on this contract Verification claim Depends on this contract Unrelated theme Retain cached result A cached “no provider exists” query depends on a predicate over membership—not just the rows it previously returned. ## Reaktor design decision Section ID: reaktor-design-decision-2 Reaktor design decision Use indexed relational facts, tracked queries and fixed-point analyses as shared infrastructure. Visitors remain useful for custom passes, but not every analysis should be a full DFS. ## What this does not establish Section ID: what-this-does-not-establish-1 What this does not establish Cache invalidation over negative predicates and recursive queries requires care. A hash of an output is not proof that all its inputs were declared. Incrementality is optional until its cost wins. Falsifiable acceptance test. Invalidate bindings, a compatibility result and its evidence when the contract changes; retain the unrelated theme derivation. Theory, precedent and Reaktor context: Module execution plan Graph visitors McSherry et al. — Differential Dataflow Mokhov, Mitchell & Peyton Jones — Build Systems à la Carte ## Portability should adapt without hiding degradation Section ID: panel-capabilities Portability should adapt without hiding degradation Capability selection was already in the docs; it must survive the graph redesign. Portability should adapt without hiding degradation Law / model / proof obligation: Eligible = {o | satisfies(o, requirements, context) ∧ authorized(o)}; preferences apply only within Eligible. Diagram: Portability should adapt without hiding degradation ADAPTATION • FILTER ELIGIBLE OFFERS BEFORE RANKING On-device model Data stays local Lower capability; available offline Cloud model Potentially higher quality Requires network + data permission Unavailable accelerator Fast when hardware exists Not available on this host Decision: choose local Private-input constraint rules out the cloud offer. Prefer among eligible choices; keep the active session stable. Feature availability, provider offer, permission grant, policy verdict and actual effect are different typed facts. ## Reaktor design decision Section ID: reaktor-design-decision-3 Reaktor design decision Use multidimensional offers for privacy, accuracy, cost, latency, affinity and availability. Record the selected offer and fallback reason. Re-selection needs hysteresis, qualification and a state-transfer or session-pinning rule. ## What this does not establish Section ID: what-this-does-not-establish-2 What this does not establish “Full” does not dominate “Basic” across every dimension. Scalar tier labels may remain in a UI, but not as the complete compatibility or authority contract. Falsifiable acceptance test. Remove private-input and network constraints in the toy: the cloud offer becomes eligible. Add either back and it cannot be chosen by a quality score alone. Theory, precedent and Reaktor context: Capability selection Reaktor plan and roadmap Formal methods and evidence ## Placement is constrained graph partitioning Section ID: panel-placement Placement is constrained graph partitioning The graph can expose the cost of a boundary before a feature becomes operationally expensive. Placement is constrained graph partitioning Law / model / proof obligation: Minimize boundary cost subject to residency, authority, capacity, affinity and protocol feasibility. Diagram: Placement is constrained graph partitioning PARTITIONING • HARD CONSTRAINTS BEFORE CUT COST DEVICE EDGE CORE Camera frames Private input; native lease Session router Allowed compact events Model / storage Eligible only for permitted data Local inference Qualified fallback metadata events REJECT: raw private frames cross the boundary Optimize weighted traffic/latency only over feasible placements. Min-cut alone cannot satisfy every system constraint. ## Reaktor design decision Section ID: reaktor-design-decision-4 Reaktor design decision Use graph cuts and measured interaction weights to propose placements, co-location and batching. Produce explanations for rejected placements and retain the accepted profile in the release manifest. ## What this does not establish Section ID: what-this-does-not-establish-3 What this does not establish Hypergraph partitioning with multiple resource and policy constraints is not generally a trivial min-cut. Use heuristics or bounded optimization and report the objective, not an unproved global optimum. Falsifiable acceptance test. A cheaper remote inference offer must lose to a valid local offer when raw data is prohibited from leaving the device. Theory, precedent and Reaktor context: Capability selection Reaktor plan and roadmap Tidemark data layer Live session topology Fong & Spivak — Seven Sketches in Compositionality ## A lens explains round trips; it does not create cross-store ACID Section ID: panel-source A lens explains round trips; it does not create cross-store ACID Source authority and graph authority must not drift during edits or crashes. A lens explains round trips; it does not create cross-store ACID Law / model / proof obligation: PutGet and GetPut are laws for a chosen source/view model; unsupported edits are explicit errors or proposals. Diagram: A lens explains round trips; it does not create cross-store ACID BIDIRECTIONAL TRANSFORMATION • A DECLARED SUPPORTED SUBSET Source-owned region Human source is authoritative. Extraction preserves identity/provenance. Graph projection Structured view and legal proposals. No second independent authoring truth. get / extract put / supported edit PUBLICATION ACROSS AUTHORITIES • STAGE AND RECOVER Stage source Pin source revision Build candidate Pin artifact digest Promote graph Compare expected base Reconcile Recover partial steps get(put(s,v)) = v and put(s,get(s)) ≈ s apply only where supported; do not promise lossless editing of arbitrary foreign code. ## Reaktor design decision Section ID: reaktor-design-decision-5 Reaktor design decision Use projections and source-aware edits where the source owns a region; directly transact graph-owned programs. Publish immutable source/artifact candidates using recoverable phases when the authorities differ. ## What this does not establish Section ID: what-this-does-not-establish-4 What this does not establish A filesystem, Git repository and graph database do not become one atomic store because their IDs are linked. Formatting, generated code and opaque bodies require a declared equivalence or preservation policy. Falsifiable acceptance test. Crash after source materialization and before graph promotion. Recovery must not activate mismatched code while claiming one tested candidate. Theory, precedent and Reaktor context: Source ownership Visual language Foster et al. — Combinators for Bidirectional Tree Transformations DevOps integration ## A graph transaction protects invariants, not just records Section ID: panel-mvcc A graph transaction protects invariants, not just records Start with a serialized commit authority rather than premature optimistic multi-writer complexity. A graph transaction protects invariants, not just records Law / model / proof obligation: Commit(candidate) requires candidate.base = currentHead, current authority, and valid transition obligations. Diagram: A graph transaction protects invariants, not just records DATABASE THEORY • DISJOINT WRITES CAN STILL VIOLATE ONE INVARIANT Base r10: exclusive consumer P has no provider Invariant: count(bindings(P)) ≤ 1. Both candidates read the same absence predicate. Candidate A Read: no binding for P Write: edge(P, provider A) Candidate B Read: no binding for P Write: edge(P, provider B) Commit A: r10 → r11 Succeeds at one serialization point Commit B: expected r10 REJECT: current head is r11 Checking only common written records would miss the exclusive-binding violation. Whole-head CAS is conservative and safe. ## Reaktor design decision Section ID: reaktor-design-decision-6 Reaktor design decision Readers pin immutable snapshots. Writers prepare candidates privately. A short commit validates and durably publishes one revision plus intent and receipt; recovery returns the same result for a repeated operation ID. ## What this does not establish Section ID: what-this-does-not-establish-5 What this does not establish Whole-domain conflict detection sacrifices concurrency. Finer validation requires predicate/read dependencies and a defined serializability contract. Remote effects are outside this atomic boundary. Falsifiable acceptance test. Two candidates add different provider records to the same exclusive port. The second stale commit is rejected even though write sets differ. Theory, precedent and Reaktor context: Stable foundations Data transactions SQLite — Isolation PostgreSQL — Transaction isolation Bailis et al. — Coordination Avoidance in Database Systems ## One global graph does not imply one global instant Section ID: panel-causal One global graph does not imply one global instant Definition snapshots, workload checkpoints and runtime observations have different consistency scopes. One global graph does not imply one global instant Law / model / proof obligation: If receive ∈ cut, then its causally preceding send must also be in a consistent cut. Diagram: One global graph does not imply one global instant DISTRIBUTED SYSTEMS • A SNAPSHOT CUT MUST RESPECT CAUSALITY Runtime A Runtime B a₁ send a₃ b₁ receive b₃ message BAD CUT: includes receive but excludes its send Choose an admissible causal cut or report a revision vector with incomplete consistency guarantees—not fictional global now. ## Reaktor design decision Section ID: reaktor-design-decision-7 Reaktor design decision Carry revision vectors, checkpoints, authority domains and capture coverage into maps and Shadow fixtures. A global operation can coordinate a consistent snapshot when its actual providers support the needed protocol. ## What this does not establish Section ID: what-this-does-not-establish-6 What this does not establish Physical timestamps do not by themselves establish causal order or atomic multi-store snapshots. A partially observed system needs explicit unknowns. Falsifiable acceptance test. Reject a fixture that contains a reply or durable effect without the causally required input/state boundary. Theory, precedent and Reaktor context: Lamport — Distributed clocks, snapshots and temporal specifications Shadow workspaces Operational graph evidence # Impact, design obligations and qualification URL: https://reaktor.build/docs/architecture-atlas-qualification Status: design Content revision: c232430c10799d2ddf1e6a7e4e3ed45d0cba6bc1898275cbfe802df49a14a5c6 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-impact","panel-audit","panel-coverage","panel-bibliography"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-qualification","polarity":"Neutral"},{"id":"section-15-ecosystem-impact-and-complexity-frontier","anchor":"15-ecosystem-impact-and-complexity-frontier","label":"15. Ecosystem impact and complexity frontier","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#15-ecosystem-impact-and-complexity-frontier","polarity":"Neutral"},{"id":"section-16-design-obligations-and-open-findings","anchor":"16-design-obligations-and-open-findings","label":"16. Design obligations and open findings","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#16-design-obligations-and-open-findings","polarity":"Neutral"},{"id":"section-17-implementation-and-validation-sequence","anchor":"17-implementation-and-validation-sequence","label":"17. Implementation and validation sequence","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#17-implementation-and-validation-sequence","polarity":"Neutral"},{"id":"section-18-documentation-coverage","anchor":"18-documentation-coverage","label":"18. Documentation coverage","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#18-documentation-coverage","polarity":"Neutral"},{"id":"section-panel-impact","anchor":"panel-impact","label":"Complexity frontier and ecosystem impact","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#panel-impact","polarity":"Neutral"},{"id":"section-panel-audit","anchor":"panel-audit","label":"Design obligations and open findings","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#panel-audit","polarity":"Neutral"},{"id":"section-1-capability-tier-versus-constrained-offer","anchor":"1-capability-tier-versus-constrained-offer","label":"1. Capability tier versus constrained offer","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#1-capability-tier-versus-constrained-offer","polarity":"Neutral"},{"id":"section-2-evidence-kinds-versus-an-ordinal-ladder","anchor":"2-evidence-kinds-versus-an-ordinal-ladder","label":"2. Evidence kinds versus an ordinal ladder","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#2-evidence-kinds-versus-an-ordinal-ladder","polarity":"Neutral"},{"id":"section-3-binary-kernel-examples-versus-n-ary-relationships","anchor":"3-binary-kernel-examples-versus-n-ary-relationships","label":"3. Binary kernel examples versus n-ary relationships","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#3-binary-kernel-examples-versus-n-ary-relationships","polarity":"Neutral"},{"id":"section-4-protocol-and-completion-semantics","anchor":"4-protocol-and-completion-semantics","label":"4. Protocol and completion semantics","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#4-protocol-and-completion-semantics","polarity":"Neutral"},{"id":"section-5-lifecycle-ownership-and-handover","anchor":"5-lifecycle-ownership-and-handover","label":"5. Lifecycle, ownership and handover","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#5-lifecycle-ownership-and-handover","polarity":"Neutral"},{"id":"section-6-source-backed-transaction-publication","anchor":"6-source-backed-transaction-publication","label":"6. Source-backed transaction publication","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#6-source-backed-transaction-publication","polarity":"Neutral"},{"id":"section-7-incremental-analysis-is-more-than-visitors","anchor":"7-incremental-analysis-is-more-than-visitors","label":"7. Incremental analysis is more than visitors","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#7-incremental-analysis-is-more-than-visitors","polarity":"Neutral"},{"id":"section-8-time-scales-and-specialized-execution","anchor":"8-time-scales-and-specialized-execution","label":"8. Time scales and specialized execution","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#8-time-scales-and-specialized-execution","polarity":"Neutral"},{"id":"section-9-coordination-and-collaboration-boundaries","anchor":"9-coordination-and-collaboration-boundaries","label":"9. Coordination and collaboration boundaries","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#9-coordination-and-collaboration-boundaries","polarity":"Neutral"},{"id":"section-10-evidence-capture-and-privacy","anchor":"10-evidence-capture-and-privacy","label":"10. Evidence capture and privacy","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#10-evidence-capture-and-privacy","polarity":"Neutral"},{"id":"section-12-storage-engine-ambition","anchor":"12-storage-engine-ambition","label":"12. Storage engine ambition","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#12-storage-engine-ambition","polarity":"Neutral"},{"id":"section-14-design-truth-versus-implementation-truth","anchor":"14-design-truth-versus-implementation-truth","label":"14. Design truth versus implementation truth","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#14-design-truth-versus-implementation-truth","polarity":"Neutral"},{"id":"section-15-graph-integration-without-dependency-cycles","anchor":"15-graph-integration-without-dependency-cycles","label":"15. Graph integration without dependency cycles","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#15-graph-integration-without-dependency-cycles","polarity":"Neutral"},{"id":"section-16-external-harness-authority-is-not-graph-authority","anchor":"16-external-harness-authority-is-not-graph-authority","label":"16. External harness authority is not graph authority","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#16-external-harness-authority-is-not-graph-authority","polarity":"Neutral"},{"id":"section-panel-coverage","anchor":"panel-coverage","label":"Documentation coverage","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-qualification#panel-coverage","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-qualification:references-architecture-atlas-foundations","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-architecture-atlas-vocabulary","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-vocabulary","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-architecture-atlas-semantics","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-semantics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-architecture-atlas-language","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-architecture-atlas-evolution","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-evolution","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-architecture-atlas-workbench","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-architecture-atlas-scenarios","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-scenarios","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-astra-reaktor-plan-and-roadmap","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-15-ecosystem-impact-and-complexity-frontier","role":"source","ordinal":0},{"node":"astra-reaktor-plan-and-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-capability","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-1-capability-tier-versus-constrained-offer","role":"source","ordinal":0},{"node":"reaktor-capability","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-formal-methods","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-2-evidence-kinds-versus-an-ordinal-ladder","role":"source","ordinal":0},{"node":"reaktor-formal-methods","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-verification","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-2-evidence-kinds-versus-an-ordinal-ladder","role":"source","ordinal":0},{"node":"shadow-verification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-graph-substrate-redesign","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-3-binary-kernel-examples-versus-n-ary-relationships","role":"source","ordinal":0},{"node":"reaktor-graph-substrate-redesign","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-data-graph","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-3-binary-kernel-examples-versus-n-ary-relationships","role":"source","ordinal":0},{"node":"reaktor-data-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-service","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-4-protocol-and-completion-semantics","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-graph-protocol","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-4-protocol-and-completion-semantics","role":"source","ordinal":0},{"node":"reaktor-graph-protocol","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-data-workflows","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-4-protocol-and-completion-semantics","role":"source","ordinal":0},{"node":"reaktor-data-workflows","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-contracts-and-interaction","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-4-protocol-and-completion-semantics","role":"source","ordinal":0},{"node":"reaktor-surface-contracts-and-interaction","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-component-lifecycle","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-5-lifecycle-ownership-and-handover","role":"source","ordinal":0},{"node":"reaktor-component-lifecycle","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-actor-model","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-5-lifecycle-ownership-and-handover","role":"source","ordinal":0},{"node":"reaktor-actor-model","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-work","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-5-lifecycle-ownership-and-handover","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-ffi","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-5-lifecycle-ownership-and-handover","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-graph-sources","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-6-source-backed-transaction-publication","role":"source","ordinal":0},{"node":"reaktor-graph-sources","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-6-source-backed-transaction-publication","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-devops","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-6-source-backed-transaction-publication","role":"source","ordinal":0},{"node":"reaktor-devops","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-module-execution-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-7-incremental-analysis-is-more-than-visitors","role":"source","ordinal":0},{"node":"reaktor-module-execution-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor_graph_visitors_design","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-7-incremental-analysis-is-more-than-visitors","role":"source","ordinal":0},{"node":"reaktor_graph_visitors_design","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-dynamic-ui-and-verification","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-8-time-scales-and-specialized-execution","role":"source","ordinal":0},{"node":"reaktor-surface-dynamic-ui-and-verification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-performance-and-assets","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-8-time-scales-and-specialized-execution","role":"source","ordinal":0},{"node":"reaktor-surface-performance-and-assets","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations-graph-evidence","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-8-time-scales-and-specialized-execution","role":"source","ordinal":0},{"node":"operations-graph-evidence","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-stable-foundations-5.6-ultra","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-9-coordination-and-collaboration-boundaries","role":"source","ordinal":0},{"node":"reaktor-stable-foundations-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-data-transactions","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-9-coordination-and-collaboration-boundaries","role":"source","ordinal":0},{"node":"reaktor-data-transactions","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-capture-fabric","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-10-evidence-capture-and-privacy","role":"source","ordinal":0},{"node":"shadow-capture-fabric","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-capture-replay","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-10-evidence-capture-and-privacy","role":"source","ordinal":0},{"node":"shadow-capture-replay","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-workspaces","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-10-evidence-capture-and-privacy","role":"source","ordinal":0},{"node":"shadow-workspaces","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-05-mutable-memory","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-12-storage-engine-ambition","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-05-mutable-memory","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-workbench-layers","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-14-design-truth-versus-implementation-truth","role":"source","ordinal":0},{"node":"reaktor-workbench-layers","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-core","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-15-graph-integration-without-dependency-cycles","role":"source","ordinal":0},{"node":"reaktor-core","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-build-tools","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-15-graph-integration-without-dependency-cycles","role":"source","ordinal":0},{"node":"reaktor-build-tools","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-conductor","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-16-external-harness-authority-is-not-graph-authority","role":"source","ordinal":0},{"node":"reaktor-conductor","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-unified-system-graph","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-graph-hierarchical-ui","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-graph-hierarchical-ui","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-graph-kernel-analysis","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"graph-kernel-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-distributed-actors","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-distributed-actors","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-contributing","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"contributing","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-essays","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-essays","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-framework-overview","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-framework-overview","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-db","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-db","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-data-storage","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-data-storage","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-multitenancy","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-multitenancy","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-bus-mesh","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-bus-mesh","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-mesh","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-mesh","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-data-inspection","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-data-inspection","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-data-implementation","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-data-implementation","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-bestbuds-schema-hardening","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"bestbuds-schema-hardening","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-module-review","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-module-review","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-server","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-server","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-auth-analysis","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"auth-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-notifications-design","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-notifications-design","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-deep-link-integration","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"deep-link-integration","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-koog-agents","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-koog-agents","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-desktop","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-desktop","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-webview","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-webview","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-application-extensions","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-application-extensions","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-application-patterns","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-application-patterns","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-design-and-ownership","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-design-and-ownership","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-foundations","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-implementation-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-implementation-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-motion-and-materials","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-motion-and-materials","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-references","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-references","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-surface-renderers","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-surface-renderers","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-01-bytes-and-ownership","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-01-bytes-and-ownership","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-02-flatbuffers","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-02-flatbuffers","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-03-flexbuffers","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-03-flexbuffers","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-04-quality-and-performance","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-04-quality-and-performance","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-06-appendix-a","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-06-appendix-a","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-07-appendix-b","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-07-appendix-b","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-08-appendix-c","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-08-appendix-c","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-09-appendix-d","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-09-appendix-d","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-10-appendix-e","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-10-appendix-e","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-11-appendix-f","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-11-appendix-f","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flatbuffers-flexbuffers-mutable-memory-12-appendix-g","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory-12-appendix-g","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flexbuffer-implementation","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flexbuffer-implementation","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flexbuffer-improvement-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flexbuffer-improvement-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flexbuffer-performance-review","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flexbuffer-performance-review","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-kotlin-clr","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"kotlin-clr","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-ffi-design","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-ffi-design","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-verified-foundations-fable-5","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-verified-foundations-fable-5","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-graph-refinement-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-graph-refinement-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-cli","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-cli","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-dependeasy","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-dependeasy","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-cloud-pane","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-cloud-pane","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-megascale-strategy","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-megascale-strategy","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-secrets-management","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"secrets-management","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-security-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"security-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"operations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations-references","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"operations-references","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-performance-observability","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"performance-observability","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations-observability","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"operations-observability","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-analytics-telemetry","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-analytics-telemetry","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations-profiling","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"operations-profiling","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations-instance-diagnostics","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"operations-instance-diagnostics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations-load-resilience","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"operations-load-resilience","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-devtools","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-devtools","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-tooling-layer","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-tooling-layer","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-backends","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"shadow-backends","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-dev-environment","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"shadow-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-clients-agents","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"shadow-clients-agents","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-foundations","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"shadow-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-operations-delivery","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"operations-delivery","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-instrumentation-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-instrumentation-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-workbench-links","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-workbench-links","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-hangar","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"hangar","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-agent-workspace","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-agent-workspace","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-cloud","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-cloud","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-graph-pane","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-graph-pane","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-agentic-tooling","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-agentic-tooling","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-browser-local-ai","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-browser-local-ai","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-atlas-revamp-5.6-ultra","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-atlas-revamp-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-ui-ux-audit-2026-09-08","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-ui-ux-audit-2026-09-08","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-desktop-master-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-desktop-master-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-koog-workbench","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-koog-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-arena","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-arena","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-companyos-migration-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"companyos-migration-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-manna-functional-designs","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"manna-functional-designs","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-manna-hld","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"manna-hld","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-claude-nexergy-appweb-analysis","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"claude-nexergy-appweb-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-codex-nexergy-appweb-analysis","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"codex-nexergy-appweb-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-manna-kotlin-surface-migration-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"manna-kotlin-surface-migration-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-claude-critic-review","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"claude-critic-review","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-codex-critic-review","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"codex-critic-review","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-competitive-analysis","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-competitive-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-codex-roadmap","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"codex-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-implementation-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-implementation-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-workbench-roadmap","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-workbench-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-claude-dev-environment","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"claude-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-codex-dev-environment","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"codex-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-performance-observability-history","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"performance-observability-history","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-shadow-design-history","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"shadow-design-history","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-engine-website-implementation-report","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"engine-website-implementation-report","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-flow-analysis","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"flow-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-architecture-analysis","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-architecture-analysis","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-graph-migration-plan","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-graph-migration-plan","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-atlas-review-fable-5","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-atlas-review-fable-5","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-desktop-v3","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-desktop-v3","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-qualification:references-reaktor-gemini-devops-agent","kind":"references","owner":"architecture-atlas-qualification","incidences":[{"node":"architecture-atlas-qualification","port":"section-panel-coverage","role":"source","ordinal":0},{"node":"reaktor-gemini-devops-agent","port":"page","role":"target","ordinal":0}]}]} ## Impact, design obligations and qualification Section ID: impact-design-obligations-and-qualification Impact, design obligations and qualification Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification ## 15. Ecosystem impact and complexity frontier Section ID: 15-ecosystem-impact-and-complexity-frontier 15. Ecosystem impact and complexity frontier Reaktor can potentially solve families of boundary problems: cross-runtime feature composition; native-resource access; durable command execution; offline state and synchronization contracts; live sessions; safe deployment; environment reproduction; cross-tool context drift; agent mutation safety; inspection and authorization; adaptive model placement; and multi-surface behavior reuse. A single feature may benefit from several, which is where the composition can be more valuable than isolated wrappers. The nearest precedents should sharpen—not weaken—the differentiation. Ptolemy supplies heterogeneous execution semantics; MLIR supplies extensible compiler structure; databases supply atomic change; Kubernetes and Erlang supply realization and upgrades; FoundationDB supplies disciplined simulation. MPS’s experimental Projectional Agent Toolkit now gives agents structured model-editing and validation facilities. “Agents can edit a typed graph” alone is therefore not a defensible uniqueness claim. [Ptolemy II: hierarchy, ports and models of computation] [MLIR — Dialect conversion] [JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental)] [Kubernetes — Controllers] [Erlang/OTP — Release handling] [FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021)] The stronger hypothesis is that Reaktor lowers the total cost of accepted, cross-layer changes across mobile, browser, server, data, native and operational boundaries. That should be tested against the best ordinary stack, not a deliberately weak baseline. Do not equate this with increasing computational power beyond a general programming language. The target is the feasible frontier at a fixed team, time, reliability, cost and performance budget. Domain understanding, algorithm design, product judgment and external failures remain essential difficulty. A broad framework can also impose modeling, dependency, adoption and lock-in costs. An Amdahl-style fixed-work sensitivity model illustrates the fixed-work case. If 60% of work improves fourfold with no overhead, the overall factor is about 1.82, not four. That is an illustration, not a forecast. The model also misses a second benefit: teams may attempt larger or riskier designs because the cost of safe experimentation falls. [Amdahl — Validity of the single processor approach (1967)] [Reaktor plan and roadmap] [FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021)] ## 16. Design obligations and open findings Section ID: 16-design-obligations-and-open-findings 16. Design obligations and open findings ## 1. Capability tier versus constrained offer Section ID: 1-capability-tier-versus-constrained-offer 1. Capability tier versus constrained offer Classification: Documentation conflict Keep tier as presentation. Eligibility must satisfy schema, protocol, placement, privacy, lifetime and authority before preference ranking. Re-selection needs stability and session migration rules. Acceptance test: A higher-quality remote model is rejected when private inputs cannot leave the device; fallback is observed and testable. Sources: Capability selection, Reaktor plan and roadmap ## 2. Evidence kinds versus an ordinal ladder Section ID: 2-evidence-kinds-versus-an-ordinal-ladder 2. Evidence kinds versus an ordinal ladder Classification: Design correction Replace minimum EvidenceLevel with a claim-indexed evidence requirement. Bounds, assumptions, checker trust and exact artifacts are part of the claim. Acceptance test: A successful production trace cannot discharge a universal no-unauthorized-write claim; a proof of a model cannot discharge a measured latency SLO. Sources: Formal methods and evidence, Shadow verification and capsules ## 3. Binary kernel examples versus n-ary relationships Section ID: 3-binary-kernel-examples-versus-n-ary-relationships 3. Binary kernel examples versus n-ary relationships Classification: Documentation reconciliation Choose typed incidence records as the structural substrate. Binary invocation, ownership and hyperedge protocols are qualified relation schemas. Acceptance test: A session has exactly one authority and many participants; this must not conflict with a unary consumer’s exclusive-binding rule. Sources: Graph substrate redesign, Data graph, Formal methods and evidence ## 4. Protocol and completion semantics Section ID: 4-protocol-and-completion-semantics 4. Protocol and completion semantics Classification: Omission from design Make admitted, persisted, processed, canceled and reconciled outcomes explicit per protocol. Require versioned behavioral compatibility, not only matching record layouts. Acceptance test: Inject reply loss after commit. The caller reconciles the same command receipt instead of duplicating the logical effect. Sources: Service contracts, Graph protocol, Data workflows, Surface contracts and interaction ## 5. Lifecycle, ownership and handover Section ID: 5-lifecycle-ownership-and-handover 5. Lifecycle, ownership and handover Classification: Omission from design Model host lifetime, component ownership, task scope and resource leases separately. Persist required work before acknowledging host-local completion. Acceptance test: Destroy a browser/Worker host without cleanup callbacks; prove durable intent survives or declare a weaker profile. Sources: Component lifecycle, Actor execution model, Durable work, FFI / Switchboard ## 6. Source-backed transaction publication Section ID: 6-source-backed-transaction-publication 6. Source-backed transaction publication Classification: New boundary to make explicit Source edits, graph revisions and built artifacts may have different authorities. Stage and pin a candidate; compare source revision; record recoverable publication phases. Acceptance test: Crash after materializing source but before promoting the graph. Recovery must not publish a mixed source/artifact revision. Sources: Source ownership, Visual language, DevOps integration ## 7. Incremental analysis is more than visitors Section ID: 7-incremental-analysis-is-more-than-visitors 7. Incremental analysis is more than visitors Classification: Sharper mechanism Use a dependency-tracked query/analysis service for positive and negative facts. Run generic visitors as one client, not the only execution model. Acceptance test: Insert a new provider that invalidates a previous absence result; its query, binding and verification evidence all become stale. Sources: Module execution plan, Graph visitors, McSherry et al. — Differential Dataflow, Mokhov, Mitchell & Peyton Jones — Build Systems à la Carte ## 8. Time scales and specialized execution Section ID: 8-time-scales-and-specialized-execution 8. Time scales and specialized execution Classification: Omission from design Separate definition revisions, activation roots, reactive values, durable workflow events and native frame/tick state. Bind observations back by identity. Acceptance test: Animate at the host frame rate without committing architecture revisions; replace a UI region without discarding an active IME draft. Sources: Surface contracts and interaction, Dynamic UI and verification, Surface performance and assets, Operational graph evidence ## 9. Coordination and collaboration boundaries Section ID: 9-coordination-and-collaboration-boundaries 9. Coordination and collaboration boundaries Classification: Sharper invariant policy Use serialized authority commits first. Permit coordination-free merges only for operations proven safe under the required merge/invariant model. Acceptance test: Two private branches add different providers to one exclusive port. Individually valid does not mean jointly valid. Sources: Stable foundations, Data transactions, PostgreSQL — Transaction isolation, Bailis et al. — Coordination Avoidance in Database Systems ## 10. Evidence capture and privacy Section ID: 10-evidence-capture-and-privacy 10. Evidence capture and privacy Classification: Omission from design Keep trace sampling separate from replay completeness. Exactly one substitution owner per effect; mark loss and unavailable joins. Retention and suppression apply to every derived workspace. Acceptance test: Deleted source data does not reappear after Shadow base reconstruction; duplicated collectors do not replay one effect twice. Sources: Operational graph evidence, Capture fabric, Capture and replay, Shadow workspaces, Shadow verification and capsules ## 11. Meta-schema and qualification evolution Section ID: 11-meta-schema-and-qualification-evolution 11. Meta-schema and qualification evolution Classification: New explicit obligation Version module semantics, contracts and checker implementations. Unknown required semantics block activation; evidence binds the interpreter/checker versions. Acceptance test: An upgraded dialect changes cancellation semantics without changing payloads. Old compatibility and evidence must not silently survive. Sources: Formal methods and evidence, Module execution plan, MLIR — Dialect conversion, Surface contracts and interaction ## 12. Storage engine ambition Section ID: 12-storage-engine-ambition 12. Storage engine ambition Classification: Implementation simplification Define graph storage semantics independently of physical layout. Start with a qualified existing transactional authority plus immutable graph indexes; custom WAL/GC only when measured needs justify it. Acceptance test: Crash-recovery and snapshot-lifetime tests pass before any performance claim; old snapshots retain their own resolution directory. Sources: Stable foundations, Mutable memory and publication, SQLite — Isolation ## 13. Product intent and reusable feature boundaries Section ID: 13-product-intent-and-reusable-feature-boundaries 13. Product intent and reusable feature boundaries Classification: Omission from design Connect changes to acceptance contracts and user journeys, not only types. Reusable regions carry assumptions, effects, migrations and operational tests. Acceptance test: The feature compiles and deploys, but loses a user draft or breaks accessibility; its acceptance gate still rejects it. Sources: Reaktor plan and roadmap, Surface contracts and interaction, Dynamic UI and verification ## 14. Design truth versus implementation truth Section ID: 14-design-truth-versus-implementation-truth 14. Design truth versus implementation truth Classification: Documentation hygiene Every normative claim gets status, owner, source revision, implementation pointers and qualifying tests. Separate historical criticism from active contract. Acceptance test: No generated compliance view may show a design-only streaming guarantee as implemented merely because a document describes it. Sources: FFI / Switchboard, Formal methods and evidence, Workbench layers, Shadow workspaces ## 15. Graph integration without dependency cycles Section ID: 15-graph-integration-without-dependency-cycles 15. Graph integration without dependency cycles Classification: Sharper architectural rule Low-level reaktor-core and graph-free policy/storage primitives need not import the graph. Higher-level module contributions expose their identities, capabilities and effects to the graph. Acceptance test: The foundational libraries remain usable headlessly while every admitted operational boundary is registered and inspectable. Sources: Core dependency boundary, Module execution plan, Build control-plane responsibilities ## 16. External harness authority is not graph authority Section ID: 16-external-harness-authority-is-not-graph-authority 16. External harness authority is not graph authority Classification: New trust-boundary finding Model provider configuration, raw harness arguments, subprocess/network access and inherited tools as effective execution authority. Isolate untrusted runs or mark the governance claim incomplete. Acceptance test: A denied graph mutation must not become authorized merely by asking an inherited harness tool to perform the same external action. Sources: Conductor harness boundaries, Workbench layers, Formal methods and evidence, Shadow verification and capsules ## 17. Implementation and validation sequence Section ID: 17-implementation-and-validation-sequence 17. Implementation and validation sequence Start with descriptor-driven palette/source mapping and one qualified behavior profile. Add release manifests and activation images before promising arbitrary node hot-swap. Then prove a single end-to-end update through Service, FFI, Work, Data and Shadow, reusing existing graph/storage authorities rather than creating another IR or ownership universe. Acceptance tests: preserve the semantic digest after layout-only edits; reject a missing native descriptor; detect a stale-evidence candidate; widen an update when a shared state schema changes; preserve old calls under the old image; survive a lost activation reply; reject stale callbacks after resource disposal; refuse an unauthorized capability escalation; and recover from a partially rolled-out fleet. Benchmark node-by-node interpreter overhead against compiled region execution, physical bytes transmitted versus semantic change size, time to compile/invalidate, retained-generation memory, and hot-path FFI copies. More granular updates can reduce change scope, but they can also prevent inlining and increase dispatch cost; make the tradeoff selectable per region. Product thesis: Stately-like precision for behavior, Unreal-like engine composition, Cursor-like expert editing, FlutterFlow-like product iteration and Expo-like runtime-aware delivery—all expressed through Reaktor’s governed distributed-system model. The value must be demonstrated by a difficult full-stack change that remains typed, authorized, testable and recoverable. First: settle the common contract vocabulary—identity, typed incidences, region/source ownership, protocols, effect/authority separation, lifetime and claim-indexed evidence. Preserve compatibility façades while this becomes the source of truth. Second: qualify one complete change loop on existing storage and runtime primitives. A stateful service/Work path should admit a command, commit an exact receipt, survive acknowledgement loss, run under current tenant authority, and remain inspectable across restart. Third: add graph-aware incremental compilation and evidence invalidation. Begin conservatively; validate optimization against the reference semantics and failure corpus. Avoid implementing custom storage, distributed scheduling and a new compiler backend simultaneously. Fourth: prove the cross-runtime composition on a difficult feature, such as a multiplayer or live-media workflow with native buffers, browser/mobile interaction, a model provider, durable results and mixed-version rollout. Inject disconnects, stale policies, failed migrations, duplicate delivery and host disappearance. Finally: run external-team ablations: ordinary tooling; Reaktor libraries without global graph automation; graph-aware plans and typed agent operations; and the full Shadow/governance loop. Hold feature requirements and model/harness versions constant. Measure accepted-change lead time, regression escape rate, recovery, unauthorized-action prevention, onboarding, memory/call overhead and ability to leave the platform. The essential deliverable is not a larger picture. It is a small compositional core whose promises remain true while the surrounding system changes. ## 18. Documentation coverage Section ID: 18-documentation-coverage 18. Documentation coverage 140 current navigation routes retrieved/inventoried; 51 targeted substantive section comparisons. The remaining routes were not fully substantively audited. Counts include the canonical FFI alias. Additional legacy and private-access failures are in the ledger. This is not an immutable snapshot of the site or a repository audit. ## Complexity frontier and ecosystem impact Section ID: panel-impact Complexity frontier and ecosystem impact Measure the whole accepted change, including modeling, tests, adapters and operational recovery. Raise the feasible complexity frontier—not a magic multiplier Law / model / proof obligation: S = 1 / [(1−f) + f/s + h], a hypothetical fixed-work sensitivity model. Diagram: Raise the feasible complexity frontier—not a magic multiplier IMPACT • A SENSITIVITY MODEL, NOT AN EMPIRICAL PRODUCTIVITY CLAIM Fixed-work cost model Normalized new cost = (1 − f) + f / s + h f = addressable fraction; s = speedup of that fraction; h = added overhead Effective speedup 1.82× Default illustration 60% improved 4×, zero added overhead. Even an infinite improvement of that 60% caps at 2.5×. A safer change process may expand feasible scope, which this fixed-work formula does not measure. Amdahl-style reasoning disciplines speed claims; it is not a forecast of Reaktor’s adoption or economic value. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision Reaktor could reduce cross-tool translation, duplicated configuration, agent context assembly and incident reproduction. More importantly, verified experimentation may make previously too-risky refactors affordable. ## What this does not establish Section ID: what-this-does-not-establish What this does not establish Essential algorithms, product discovery and cross-system failure remain difficult. A new semantic platform can add lock-in, training, bottlenecks and maintenance cost. No market-size or productivity multiplier is measured here. Falsifiable acceptance test. Use external-team ablations and count escaped defects, unsafe action attempts, onboarding, recovery, runtime overhead and accepted-change lead time—not generated lines of code. Theory, precedent and Reaktor context: Amdahl — Validity of the single processor approach (1967) Reaktor plan and roadmap FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) ## Design obligations and open findings Section ID: panel-audit Design obligations and open findings Sixteen findings: existing concepts omitted from our synthesis, documentation inconsistencies, and proposed corrections. These are not a repository security or correctness audit. Documentation conflict ## 01. Capability tier versus constrained offer Section ID: 01-capability-tier-versus-constrained-offer 01. Capability tier versus constrained offer Keep tier as presentation. Eligibility must satisfy schema, protocol, placement, privacy, lifetime and authority before preference ranking. Re-selection needs stability and session migration rules. Acceptance: A higher-quality remote model is rejected when private inputs cannot leave the device; fallback is observed and testable. Capability selection Reaktor plan and roadmap Design correction ## 02. Evidence kinds versus an ordinal ladder Section ID: 02-evidence-kinds-versus-an-ordinal-ladder 02. Evidence kinds versus an ordinal ladder Replace minimum EvidenceLevel with a claim-indexed evidence requirement. Bounds, assumptions, checker trust and exact artifacts are part of the claim. Acceptance: A successful production trace cannot discharge a universal no-unauthorized-write claim; a proof of a model cannot discharge a measured latency SLO. Formal methods and evidence Shadow verification and capsules Documentation reconciliation ## 03. Binary kernel examples versus n-ary relationships Section ID: 03-binary-kernel-examples-versus-n-ary-relationships 03. Binary kernel examples versus n-ary relationships Choose typed incidence records as the structural substrate. Binary invocation, ownership and hyperedge protocols are qualified relation schemas. Acceptance: A session has exactly one authority and many participants; this must not conflict with a unary consumer’s exclusive-binding rule. Graph substrate redesign Data graph Formal methods and evidence Design gap ## 04. Protocol and completion semantics Section ID: 04-protocol-and-completion-semantics 04. Protocol and completion semantics Make admitted, persisted, processed, canceled and reconciled outcomes explicit per protocol. Require versioned behavioral compatibility, not only matching record layouts. Acceptance: Inject reply loss after commit. The caller reconciles the same command receipt instead of duplicating the logical effect. Service contracts Graph protocol Data workflows Surface contracts and interaction Design gap ## 05. Lifecycle, ownership and handover Section ID: 05-lifecycle-ownership-and-handover 05. Lifecycle, ownership and handover Model host lifetime, component ownership, task scope and resource leases separately. Persist required work before acknowledging host-local completion. Acceptance: Destroy a browser/Worker host without cleanup callbacks; prove durable intent survives or declare a weaker profile. Component lifecycle Actor execution model Durable work FFI / Switchboard Required boundary ## 06. Source-backed transaction publication Section ID: 06-source-backed-transaction-publication 06. Source-backed transaction publication Source edits, graph revisions and built artifacts may have different authorities. Stage and pin a candidate; compare source revision; record recoverable publication phases. Acceptance: Crash after materializing source but before promoting the graph. Recovery must not publish a mixed source/artifact revision. Source ownership Visual language DevOps integration Sharper mechanism ## 07. Incremental analysis is more than visitors Section ID: 07-incremental-analysis-is-more-than-visitors 07. Incremental analysis is more than visitors Use a dependency-tracked query/analysis service for positive and negative facts. Run generic visitors as one client, not the only execution model. Acceptance: Insert a new provider that invalidates a previous absence result; its query, binding and verification evidence all become stale. Module execution plan Graph visitors McSherry et al. — Differential Dataflow Mokhov, Mitchell & Peyton Jones — Build Systems à la Carte Design gap ## 08. Time scales and specialized execution Section ID: 08-time-scales-and-specialized-execution 08. Time scales and specialized execution Separate definition revisions, activation roots, reactive values, durable workflow events and native frame/tick state. Bind observations back by identity. Acceptance: Animate at the host frame rate without committing architecture revisions; replace a UI region without discarding an active IME draft. Surface contracts and interaction Dynamic UI and verification Surface performance and assets Operational graph evidence Sharper invariant policy ## 09. Coordination and collaboration boundaries Section ID: 09-coordination-and-collaboration-boundaries 09. Coordination and collaboration boundaries Use serialized authority commits first. Permit coordination-free merges only for operations proven safe under the required merge/invariant model. Acceptance: Two private branches add different providers to one exclusive port. Individually valid does not mean jointly valid. Stable foundations Data transactions PostgreSQL — Transaction isolation Bailis et al. — Coordination Avoidance in Database Systems Design gap ## 10. Evidence capture and privacy Section ID: 10-evidence-capture-and-privacy-1 10. Evidence capture and privacy Keep trace sampling separate from replay completeness. Exactly one substitution owner per effect; mark loss and unavailable joins. Retention and suppression apply to every derived workspace. Acceptance: Deleted source data does not reappear after Shadow base reconstruction; duplicated collectors do not replay one effect twice. Operational graph evidence Capture fabric Capture and replay Shadow workspaces Shadow verification and capsules Required obligation ## 11. Meta-schema and qualification evolution Section ID: 11-meta-schema-and-qualification-evolution-1 11. Meta-schema and qualification evolution Version module semantics, contracts and checker implementations. Unknown required semantics block activation; evidence binds the interpreter/checker versions. Acceptance: An upgraded dialect changes cancellation semantics without changing payloads. Old compatibility and evidence must not silently survive. Formal methods and evidence Module execution plan MLIR — Dialect conversion Surface contracts and interaction Implementation simplification ## 12. Storage engine ambition Section ID: 12-storage-engine-ambition-1 12. Storage engine ambition Define graph storage semantics independently of physical layout. Start with a qualified existing transactional authority plus immutable graph indexes; custom WAL/GC only when measured needs justify it. Acceptance: Crash-recovery and snapshot-lifetime tests pass before any performance claim; old snapshots retain their own resolution directory. Stable foundations Mutable memory and publication SQLite — Isolation Design gap ## 13. Product intent and reusable feature boundaries Section ID: 13-product-intent-and-reusable-feature-boundaries-1 13. Product intent and reusable feature boundaries Connect changes to acceptance contracts and user journeys, not only types. Reusable regions carry assumptions, effects, migrations and operational tests. Acceptance: The feature compiles and deploys, but loses a user draft or breaks accessibility; its acceptance gate still rejects it. Reaktor plan and roadmap Surface contracts and interaction Dynamic UI and verification Documentation hygiene ## 14. Design truth versus implementation truth Section ID: 14-design-truth-versus-implementation-truth-1 14. Design truth versus implementation truth Every normative claim gets status, owner, source revision, implementation pointers and qualifying tests. Separate historical criticism from active contract. Acceptance: No generated compliance view may show a design-only streaming guarantee as implemented merely because a document describes it. FFI / Switchboard Formal methods and evidence Workbench layers Shadow workspaces Sharper architectural rule ## 15. Graph integration without dependency cycles Section ID: 15-graph-integration-without-dependency-cycles-1 15. Graph integration without dependency cycles Low-level reaktor-core and graph-free policy/storage primitives need not import the graph. Higher-level module contributions expose their identities, capabilities and effects to the graph. Acceptance: The foundational libraries remain usable headlessly while every admitted operational boundary is registered and inspectable. Core dependency boundary Module execution plan Build control-plane responsibilities Trust boundary ## 16. External harness authority is not graph authority Section ID: 16-external-harness-authority-is-not-graph-authority-1 16. External harness authority is not graph authority Model provider configuration, raw harness arguments, subprocess/network access and inherited tools as effective execution authority. Isolate untrusted runs or mark the governance claim incomplete. Acceptance: A denied graph mutation must not become authorized merely by asking an inherited harness tool to perform the same external action. Conductor harness boundaries Workbench layers Formal methods and evidence Shadow verification and capsules ## Documentation coverage Section ID: panel-coverage Documentation coverage 140 navigation routes retrieved; 51 received targeted substantive section comparisons. The remainder were inventoried, not fully substantively audited. The count includes archives and the FFI design alias; it is not a count of unique implementations or 140 fully read documents. This is not an atomic snapshot of a changing site and is not a source-code audit. Additional legacy routes and a private authentication boundary are listed below. No completeness claim is made about unlinked, private or unavailable material. 140 routes Document / family Access Review depth Connected findings reaktor-graph-substrate-redesign Graph kernel and semantics public route retrieved targeted substantive sections compared Binary kernel examples versus n-ary relationships; Binary kernel examples versus n-ary relationships reaktor-unified-system-graph Graph kernel and semantics public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor_graph_visitors_design Graph kernel and semantics public route retrieved retrieved and inventoried; not fully substantively audited Incremental analysis is more than visitors; Incremental analysis is more than visitors reaktor-component-lifecycle Graph kernel and semantics public route retrieved targeted substantive sections compared Lifecycle, ownership and handover; Lifecycle, ownership and handover reaktor-graph-hierarchical-ui Graph kernel and semantics public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. graph-kernel-analysis Graph kernel and semantics public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-actor-model Graph kernel and semantics public route retrieved targeted substantive sections compared Lifecycle, ownership and handover; Lifecycle, ownership and handover reaktor-distributed-actors Graph kernel and semantics public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-graph-protocol Graph kernel and semantics public route retrieved targeted substantive sections compared Protocol and completion semantics; Protocol and completion semantics reaktor-graph-sources Graph kernel and semantics public route retrieved targeted substantive sections compared Source-backed transaction publication; Source-backed transaction publication reaktor-service Graph kernel and semantics public route retrieved targeted substantive sections compared Protocol and completion semantics; Protocol and completion semantics astra-reaktor-plan-and-roadmap Vision, data and delivery public route retrieved targeted substantive sections compared Capability tier versus constrained offer; Product intent and reusable feature boundaries; Capability tier versus constrained offer; Product intent and reusable feature boundaries contributing Vision, data and delivery public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-essays Vision, data and delivery public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-framework-overview Vision, data and delivery public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-db Vision, data and delivery public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-data-graph Vision, data and delivery public route retrieved targeted substantive sections compared Binary kernel examples versus n-ary relationships; Binary kernel examples versus n-ary relationships reaktor-data-storage Vision, data and delivery public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-multitenancy Vision, data and delivery public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-data-transactions Vision, data and delivery public route retrieved targeted substantive sections compared Coordination and collaboration boundaries; Coordination and collaboration boundaries reaktor-bus-mesh Vision, data and delivery public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-mesh Vision, data and delivery public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-data-workflows Vision, data and delivery public route retrieved targeted substantive sections compared Protocol and completion semantics; Protocol and completion semantics reaktor-work Vision, data and delivery public route retrieved targeted substantive sections compared Lifecycle, ownership and handover; Lifecycle, ownership and handover reaktor-data-inspection Vision, data and delivery public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-data-implementation Vision, data and delivery public route retrieved targeted substantive sections compared No per-document finding asserted. bestbuds-schema-hardening Vision, data and delivery public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-module-execution-plan Modules, capabilities and Surface public route retrieved targeted substantive sections compared Incremental analysis is more than visitors; Meta-schema and qualification evolution; Incremental analysis is more than visitors; Meta-schema and qualification evolution; Graph integration without dependency cycles reaktor-module-review Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-capability Modules, capabilities and Surface public route retrieved targeted substantive sections compared Capability tier versus constrained offer; Capability tier versus constrained offer reaktor-core Modules, capabilities and Surface public route retrieved targeted substantive sections compared Graph integration without dependency cycles reaktor-server Modules, capabilities and Surface public route retrieved targeted substantive sections compared No per-document finding asserted. auth-analysis Modules, capabilities and Surface public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-notifications-design Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. deep-link-integration Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-koog-agents Modules, capabilities and Surface public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-surface-desktop Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-webview Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface-application-extensions Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface-application-patterns Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface-contracts-and-interaction Modules, capabilities and Surface public route retrieved targeted substantive sections compared Protocol and completion semantics; Time scales and specialized execution; Meta-schema and qualification evolution; Product intent and reusable feature boundaries; Protocol and completion semantics; Time scales and specialized execution; Meta-schema and qualification evolution; Product intent and reusable feature boundaries reaktor-surface-design-and-ownership Modules, capabilities and Surface public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-surface-dynamic-ui-and-verification Modules, capabilities and Surface public route retrieved targeted substantive sections compared Time scales and specialized execution; Product intent and reusable feature boundaries; Time scales and specialized execution; Product intent and reusable feature boundaries reaktor-surface-foundations Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface-implementation-plan Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface-motion-and-materials Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface-performance-and-assets Modules, capabilities and Surface public route retrieved targeted substantive sections compared Time scales and specialized execution; Time scales and specialized execution reaktor-surface-references Modules, capabilities and Surface public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-surface-renderers Modules, capabilities and Surface public route retrieved targeted substantive sections compared No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory Binary memory, FFI and verification public route retrieved targeted substantive sections compared No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-01-bytes-and-ownership Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-02-flatbuffers Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-03-flexbuffers Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-04-quality-and-performance Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-05-mutable-memory Binary memory, FFI and verification public route retrieved targeted substantive sections compared Storage engine ambition; Storage engine ambition flatbuffers-flexbuffers-mutable-memory-06-appendix-a Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-07-appendix-b Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-08-appendix-c Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-09-appendix-d Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-10-appendix-e Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-11-appendix-f Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flatbuffers-flexbuffers-mutable-memory-12-appendix-g Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flexbuffer-implementation Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flexbuffer-improvement-plan Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flexbuffer-performance-review Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. kotlin-clr Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-ffi Binary memory, FFI and verification public route retrieved targeted substantive sections compared Lifecycle, ownership and handover; Design truth versus implementation truth; Lifecycle, ownership and handover; Design truth versus implementation truth reaktor-ffi-design Binary memory, FFI and verification alias of canonical reaktor-ffi redirect/duplicate; not a distinct document No per-document finding asserted. reaktor-formal-methods Binary memory, FFI and verification public route retrieved targeted substantive sections compared Evidence kinds versus an ordinal ladder; Binary kernel examples versus n-ary relationships; Meta-schema and qualification evolution; Design truth versus implementation truth; Evidence kinds versus an ordinal ladder; Binary kernel examples versus n-ary relationships; Meta-schema and qualification evolution; Design truth versus implementation truth; External harness authority is not graph authority reaktor-verified-foundations-fable-5 Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-stable-foundations-5.6-ultra Binary memory, FFI and verification public route retrieved targeted substantive sections compared Coordination and collaboration boundaries; Storage engine ambition; Coordination and collaboration boundaries; Storage engine ambition reaktor-graph-refinement-plan Binary memory, FFI and verification public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-devops Operations, build and Shadow public route retrieved targeted substantive sections compared Source-backed transaction publication; Source-backed transaction publication reaktor-build-tools Operations, build and Shadow public route retrieved targeted substantive sections compared Graph integration without dependency cycles reaktor-cli Operations, build and Shadow public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-dependeasy Operations, build and Shadow public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-cloud-pane Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-megascale-strategy Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. secrets-management Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. security-plan Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. operations Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. operations-references Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. operations-graph-evidence Operations, build and Shadow public route retrieved targeted substantive sections compared Time scales and specialized execution; Evidence capture and privacy; Time scales and specialized execution; Evidence capture and privacy performance-observability Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. operations-observability Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-analytics-telemetry Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. operations-profiling Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. operations-instance-diagnostics Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. operations-load-resilience Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-devtools Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-tooling-layer Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. shadow-backends Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. shadow-capture-fabric Operations, build and Shadow public route retrieved targeted substantive sections compared Evidence capture and privacy; Evidence capture and privacy shadow-capture-replay Operations, build and Shadow public route retrieved targeted substantive sections compared Evidence capture and privacy; Evidence capture and privacy shadow-dev-environment Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. shadow-clients-agents Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. shadow-foundations Operations, build and Shadow public route retrieved targeted substantive sections compared No per-document finding asserted. shadow-verification Operations, build and Shadow public route retrieved targeted substantive sections compared Evidence kinds versus an ordinal ladder; Evidence capture and privacy; Evidence kinds versus an ordinal ladder; Evidence capture and privacy; External harness authority is not graph authority shadow-workspaces Operations, build and Shadow public route retrieved targeted substantive sections compared Evidence capture and privacy; Design truth versus implementation truth; Evidence capture and privacy; Design truth versus implementation truth operations-delivery Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-instrumentation-plan Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-workbench-links Operations, build and Shadow public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. hangar Workbench, agents and products public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-workbench-layers Workbench, agents and products public route retrieved targeted substantive sections compared Design truth versus implementation truth; Design truth versus implementation truth; External harness authority is not graph authority reaktor-agent-workspace Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-cloud Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-graph-pane Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-agentic-tooling Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-conductor Workbench, agents and products public route retrieved targeted substantive sections compared External harness authority is not graph authority reaktor-browser-local-ai Workbench, agents and products public route retrieved targeted substantive sections compared No per-document finding asserted. reaktor-visual-language Workbench, agents and products public route retrieved targeted substantive sections compared Source-backed transaction publication; Source-backed transaction publication reaktor-atlas-revamp-5.6-ultra Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-ui-ux-audit-2026-09-08 Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-desktop-master-plan Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-koog-workbench Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-arena Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. companyos-migration-plan Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. manna-functional-designs Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. manna-hld Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. claude-nexergy-appweb-analysis Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. codex-nexergy-appweb-analysis Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. manna-kotlin-surface-migration-plan Workbench, agents and products public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. claude-critic-review Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. codex-critic-review Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-competitive-analysis Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. codex-roadmap Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-implementation-plan Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-workbench-roadmap Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. claude-dev-environment Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. codex-dev-environment Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. performance-observability-history Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. shadow-design-history Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. engine-website-implementation-report Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. flow-analysis Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-architecture-analysis Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-graph-migration-plan Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-atlas-review-fable-5 Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-desktop-v3 Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. reaktor-gemini-devops-agent Critique and historical designs public route retrieved retrieved and inventoried; not fully substantively audited No per-document finding asserted. ## Additional and inaccessible material Section ID: additional-and-inaccessible-material Additional and inaccessible material codex-reaktor-notifications-design/ — additional legacy page retrieved. legacy design; not counted among 140 current navigation routes. multiplatform-analysis/ — search-index material only; direct retrieval failed. not fully reviewed. react-compose/ — search-index material only; direct retrieval failed. not fully reviewed. architecture-analysis/ — search-index material only; direct retrieval failed. not fully reviewed. https://reaktor.build/private/astra-analysis — authentication redirect. not accessible; not reviewed. Route discovery used the current site navigation plus indexed legacy material. Proposed behavior, source presence, passing tests, deployed behavior and current operational qualification remain distinct statuses throughout this report. ## Primary sources Section ID: panel-bibliography Primary sources A mechanism-by-mechanism reading map, not a novelty claim. Papers and official documentation establish their own guarantees, not those of an unqualified Reaktor implementation. The Living GraphReaktor document · living Graph substrate redesignReaktor document · substrate Reaktor plan and roadmapReaktor document · roadmap Formal methods and evidenceReaktor document · formal Stable foundationsReaktor document · stable Capability selectionReaktor document · cap Module execution planReaktor document · module Graph visitorsReaktor document · visitors Component lifecycleReaktor document · life Actor execution modelReaktor document · actors Distributed actorsReaktor document · dactors Graph protocolReaktor document · protocol Source ownershipReaktor document · sources Service contractsReaktor document · service Data graphReaktor document · data Data transactionsReaktor document · txn Durable workReaktor document · work Data workflowsReaktor document · workflows MultitenancyReaktor document · tenant Surface contracts and interactionReaktor document · surface Dynamic UI and verificationReaktor document · dynamic Surface performance and assetsReaktor document · surfaceperf Surface renderersReaktor document · renderer FFI / SwitchboardReaktor document · ffi Mutable memory and publicationReaktor document · liveflex Shadow foundationsReaktor document · shadow Shadow workspacesReaktor document · workspace Shadow verification and capsulesReaktor document · verify Capture and replayReaktor document · replay Capture fabricReaktor document · capture Operational graph evidenceReaktor document · ops DevOps integrationReaktor document · devops Workbench layersReaktor document · layers Visual languageReaktor document · visual HangarReaktor document · hangar Authentication moduleReaktor document · auth Ptolemy II: hierarchy, ports and models of computationPrimary precedent · ptolemy Lee & Parks — Dataflow Process Networks (1995)Primary precedent · processnets Compositionality of dataflow modelsPrimary precedent · compositiondataflow Fong — Decorated Cospans (2015)Primary precedent · cospan Fong & Spivak — Seven Sketches in CompositionalityPrimary precedent · sketches Patch Graph Rewriting: comparison with DPO rewritingPrimary precedent · rewrite Foster et al. — Combinators for Bidirectional Tree TransformationsPrimary precedent · lenses Honda, Yoshida & Carbone — Multiparty Asynchronous Session TypesPrimary precedent · mpst A Mechanised Theory of Multiparty Asynchronous Session Types (ECOOP 2025)Primary precedent · mpstproof van der Aalst et al. — Soundness of workflow netsPrimary precedent · petri Cozzo et al. — Structure of Triadic Relations in Multiplex NetworksPrimary precedent · multilayer MIT OpenCourseWare — Queueing theory and Little’s lawPrimary precedent · queues MLIR — Dialect conversionPrimary precedent · mlir MLIR — InterfacesPrimary precedent · interfaces Koka — Types and effect handlersPrimary precedent · effects WebAssembly Component Model — WITPrimary precedent · wit Apache Arrow — C data interfacePrimary precedent · arrow SQLite — IsolationPrimary precedent · sqlite PostgreSQL — Transaction isolationPrimary precedent · postgres Bailis et al. — Coordination Avoidance in Database SystemsPrimary precedent · iconfluence FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021)Primary precedent · fdb Lamport — Distributed clocks, snapshots and temporal specificationsPrimary precedent · lamport Lamport — A high-level view of TLA+Primary precedent · tla Kubernetes — ControllersPrimary precedent · k8s Temporal — Workflow executionPrimary precedent · temporal Erlang/OTP — Release handlingPrimary precedent · otp Mokhov, Mitchell & Peyton Jones — Build Systems à la CartePrimary precedent · build McSherry et al. — Differential DataflowPrimary precedent · differential Unison — Code as content-addressed definitionsPrimary precedent · unison JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental)Primary precedent · mps Functional Mock-up Interface — Model exchange and co-simulationPrimary precedent · fmi Unreal Engine — Introduction to BlueprintsPrimary precedent · blueprint Jetpack Compose — Architecture and statePrimary precedent · compose Amdahl — Validity of the single processor approach (1967)Primary precedent · amdahl Core dependency boundaryReaktor document · core Conductor harness boundariesReaktor document · conductor Build control-plane responsibilitiesReaktor document · buildtools Dependeasy build factsReaktor document · dependeasy Bus versus live MeshReaktor document · bus Live session topologyReaktor document · mesh Tidemark data layerReaktor document · db # Cross-runtime systems and worked scenarios URL: https://reaktor.build/docs/architecture-atlas-scenarios Status: design Content revision: 1a16c06765f0f7d97dfff4d23d4a05f3c6d9fadb83a419e1c70266c6fa1bbf88 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-example","panel-scenario-dispatch","panel-scenario-checkout","panel-scenario-game","panel-scenario-voice","panel-scenario-iot","panel-scenario-ml","panel-scenario-collab","panel-scenario-media","panel-scenario-logistics","panel-scenario-selfhost"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-scenarios","polarity":"Neutral"},{"id":"section-14-concrete-system-graphs","anchor":"14-concrete-system-graphs","label":"14. Concrete system graphs","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#14-concrete-system-graphs","polarity":"Neutral"},{"id":"section-panel-example","anchor":"panel-example","label":"Cross-runtime reference architecture","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#panel-example","polarity":"Neutral"},{"id":"section-panel-scenario-dispatch","anchor":"panel-scenario-dispatch","label":"A ride-dispatch feature, from maps to durable assignment","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#panel-scenario-dispatch","polarity":"Neutral"},{"id":"section-panel-scenario-checkout","anchor":"panel-scenario-checkout","label":"Checkout: a local transaction plus an external saga","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#panel-scenario-checkout","polarity":"Neutral"},{"id":"section-panel-scenario-game","anchor":"panel-scenario-game","label":"Multiplayer across Unreal, Unity and a shared backend","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#panel-scenario-game","polarity":"Neutral"},{"id":"section-panel-scenario-voice","anchor":"panel-scenario-voice","label":"Private voice coaching with adaptive inference","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#panel-scenario-voice","polarity":"Neutral"},{"id":"section-what-this-does-not-establish","anchor":"what-this-does-not-establish","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#what-this-does-not-establish","polarity":"Neutral"},{"id":"section-boundary--caveat","anchor":"boundary--caveat","label":"Boundary / caveat","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-scenarios#boundary--caveat","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-scenarios:references-architecture-atlas-foundations","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-architecture-atlas-vocabulary","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-vocabulary","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-architecture-atlas-semantics","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-semantics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-architecture-atlas-language","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-architecture-atlas-evolution","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-evolution","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-architecture-atlas-workbench","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-architecture-atlas-qualification","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-qualification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-reaktor-unified-system-graph","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"section-what-this-does-not-establish","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-reaktor-mesh","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"section-what-this-does-not-establish","role":"source","ordinal":0},{"node":"reaktor-mesh","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-reaktor-work","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"section-what-this-does-not-establish","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-reaktor-ffi","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"section-what-this-does-not-establish","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-reaktor-surface-contracts-and-interaction","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"section-what-this-does-not-establish","role":"source","ordinal":0},{"node":"reaktor-surface-contracts-and-interaction","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-scenarios:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-scenarios","incidences":[{"node":"architecture-atlas-scenarios","port":"section-boundary--caveat","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]}]} ## Cross-runtime systems and worked scenarios Section ID: cross-runtime-systems-and-worked-scenarios Cross-runtime systems and worked scenarios Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification ## 14. Concrete system graphs Section ID: 14-concrete-system-graphs 14. Concrete system graphs Rounded rectangles are components/regions; small circles on their boundary are named ports. Oval H markers are relation identities, not secret coordinator services. Their role-labelled spokes are incidences. Solid directed links are specialized binary relationships; dashed links show planning, evidence or authority. The colored runtime columns show placement, not separate copies of the semantic graph. Each scenario identifies a candidate update boundary, actual state authority and at least one hard failure obligation. Every diagram is an illustrative design, not a claim that a backend is connected or that the depicted system is implemented. The JSON in the bundle preserves node IDs, ports, hyperedges and incidences for machine inspection. The broad reuse unit is a feature region with boundary contracts, implementation choices, state owners, deployment requirements and evidence. A graph subregion is not automatically a movable network service; locality, clock and resource requirements can forbid relocation. ## A ride-dispatch feature, from maps to durable assignment Section ID: a-ride-dispatch-feature-from-maps-to-durable-assignment A ride-dispatch feature, from maps to durable assignment Compose a mobile native capability, low-latency stream and durable command without inventing three unrelated APIs. State authority: Trip database owns durable assignment; Match actor owns one active control scope. Update: Ranker inside Match region; preserve actor state Push a ranking-policy change only after its boundary, model requirements and session assumptions remain compatible. A new native map SDK still requires a host build. Failure qualification: Lose the commit reply, then retry the same command. No second driver may be assigned; old trip sessions must remain valid. Nodes: rider [N11], driver [N15], edge [N07], match [N05], db [N21], ops [N11] Relation H1 (H06): participant=rider.session, participant=driver.session, authority=match.session ## Checkout: a local transaction plus an external saga Section ID: checkout-a-local-transaction-plus-an-external-saga Checkout: a local transaction plus an external saga Keep local ACID and distributed recovery in one visible feature without pretending they are the same guarantee. State authority: Order/outbox storage is one atomic domain; payment and inventory are independent authorities. Update: Version workflow; pin in-flight continuation Change retry or routing logic for new checkout instances. Existing persisted workflows retain their old definition unless an explicit continuation migration is qualified. Failure qualification: A payment commits and the reply is lost. Reconcile by payment key before retrying; failure compensation is itself durable work. Nodes: ui [N14], auth [N33], work [N06], order [N23], stock [N21], payment [N19], notify [N24] Relation H1 (H17): forward=work.state, compensator=payment.refund, compensator=stock.release ## Multiplayer across Unreal, Unity and a shared backend Section ID: multiplayer-across-unreal-unity-and-a-shared-backend Multiplayer across Unreal, Unity and a shared backend A single feature definition spans game-native execution, companion UI, a live protocol and durable back-end work. State authority: Match activation owns simulation; result database owns durable outcomes. Update: New match definition; old matches pin old version A matchmaking change can affect new matches immediately after qualification. Replacing a native engine binary or hot-swapping live physics is a different release class. Failure qualification: Disconnect/rejoin and upgrade the match definition. Existing matches must not receive code with incompatible state or tick semantics. Nodes: engine [N16], lobby [N11], gateway [N05], sim [N29], model [N18], data [N21] Relation H1 (H06): participant=engine.session, observer=lobby.session, authority=sim.session ## Private voice coaching with adaptive inference Section ID: private-voice-coaching-with-adaptive-inference Private voice coaching with adaptive inference Compose local-first behavior and cloud capability without silently treating cloud as a universally superior fallback. State authority: Device owns live audio; each provider owns qualified execution; policy limits export. Update: Update routing policy, not native microphone ABI Update a policy region or model artifact only when the installed host can execute it and its quality/privacy evidence applies. A recorded transcript is not evidence for a new model’s quality. Failure qualification: Revoke network permission or consent mid-session. No new audio may be exported; in-flight outcomes and cleanup remain explicit. Nodes: mic [N15], local [N18], route [N32], cloud [N18], policy [N33], eval [N36] Relation H1 (H24): requirement=route.policy, offer=local.offer, offer=cloud.offer, decision=route.decision ## Industrial telemetry around a qualified control boundary Section ID: industrial-telemetry-around-a-qualified-control-boundary Industrial telemetry around a qualified control boundary Model telemetry and deployment around an external system without claiming ownership of its certified internals. State authority: PLC controls physical actuation; broker/store own persisted telemetry; operators authorize commands. Update: Analytics update; safety/control region excluded A new anomaly detector can be delivered to a qualified edge runtime. Safety-critical firmware changes remain a separate controlled process, not an automatic extension of graph updateability. Failure qualification: Lose the cloud and deploy an analytics update. Local safety control must remain unaffected; buffer exhaustion must be bounded. Nodes: sensor [N15], plc [N30], filter [N07], broker [N24], store [N21], ops [N20] Relation H1 (H22): member=plc.request, member=filter.config, constraint=ops.config ## A reproducible model experiment and deployment pipeline Section ID: a-reproducible-model-experiment-and-deployment-pipeline A reproducible model experiment and deployment pipeline Connect experiment reproducibility and runtime deployment without conflating a model tensor graph with the architecture graph. State authority: Artifact stores own datasets and weights; the experiment authority pins the full input/run vector. Update: Feature/model change widens evaluation closure Deploy the resulting model region only where its operators, shapes and memory requirements are supported. Model quality evidence and orchestrator replay validate different claims. Failure qualification: Change preprocessing but keep the model name. Invalidate dependent evaluation and refuse stale approval. Nodes: dataset [N26], pre [N01], train [N06], base [N18], eval [N36], registry [N35] Relation H1 (H27): input=dataset.dataset, input=pre.features, input=train.candidate, transform=eval.run, output=eval.evidence ## Local-first collaborative editing with controlled publication Section ID: local-first-collaborative-editing-with-controlled-publication Local-first collaborative editing with controlled publication Put merge-friendly editing beside coordinated publication rather than making every invariant use the same consistency model. State authority: Replicas own local drafts; publication authority owns the published revision. Update: Protocol update requires mixed-version sync support A server sync change must remain compatible with offline clients until the allowed upgrade window ends. A graph snapshot is not permission to resurrect deleted document payloads. Failure qualification: Two disconnected users publish divergent drafts. The exclusive publication invariant must be checked at its authority. Nodes: a [N25], b [N25], sync [N25], authority [N23], store [N21], render [N06] Relation H1 (H14): replica=a.edit, replica=b.edit, authority=sync.merged ## A low-copy camera and GPU processing pipeline Section ID: a-low-copy-camera-and-gpu-processing-pipeline A low-copy camera and GPU processing pipeline Show how graph contracts preserve meaning without forcing large buffers through generic serialized values. State authority: Native buffer owner controls lifetime; activation generations pin callbacks and consumers. Update: Swap compatible operator after outstanding leases drain FlexBuffers can carry width/height/format/timestamp and attachment indices. The actual memory path is qualified per backend and may need a copy, fence or process restart. Failure qualification: Replace the processing region while GPU work is in flight. Old callbacks and leases must never target freed code or reused handle slots. Nodes: camera [N16], pool [N26], gpu [N17], ui [N11], encoder [N17], store [N26] Relation H1 (H22): constraint=pool.lease, member=gpu.frame lease, member=ui.preview lease ## A multi-party allocation problem, not a web of pairwise links Section ID: a-multi-party-allocation-problem-not-a-web-of-pairwise-links A multi-party allocation problem, not a web of pairwise links Represent one joint constraint over orders, warehouses, vehicles and time without losing its identity in pairwise edges. State authority: Input stores own availability; reservation authority owns accepted assignments. Update: Optimize-policy region; approvals invalidate on changed inputs A better optimizer is a substitutable implementation if it preserves required feasibility and effect contracts. Its objective/quality claims need fresh comparative evidence. Failure qualification: Capacity changes after optimization. Reject or recompute a stale plan rather than committing an over-allocation. Nodes: demand [N22], supply [N22], join [N07], solve [N01], approve [N20], dispatch [N23] Relation H1 (H09): input=demand.orders, input=supply.capacity, input=solve.proposal, result=dispatch.assignment ## Reaktor improves a Reaktor system without approving itself Section ID: reaktor-improves-a-reaktor-system-without-approving-itself Reaktor improves a Reaktor system without approving itself The same system language can describe its own tooling without granting self-modifying code control over the root of trust. State authority: Graph authority owns candidate/promotion; independent policy owns approval; runtime hosts own activation. Update: Candidate product region only; trust roots remain outside Human and agent changes use the same patch/receipt model. External harnesses need OS/tool isolation or an explicit incomplete-governance declaration. Failure qualification: Change a candidate after Shadow or weaken its gate in the patch. Release admission must refuse stale or self-authorized approval. Nodes: agent [N39], draft [N23], build [N34], shadow [N36], approve [N33], rollout [N40] Relation H1 (H28): claim=draft.claim, evidence=shadow.evidence, verifier=approve.verifier ## Cross-runtime reference architecture Section ID: panel-example Cross-runtime reference architecture Combine interactive clients, native execution, live sessions, durable outcomes and model-backed behavior. A demanding use case for the whole design Law / model / proof obligation: Each boundary carries protocol, authority, state owner, placement, recovery and observation contracts. Diagram: A demanding use case for the whole design END-TO-END EXAMPLE • ONE MULTIPLAYER CAPABILITY Unity / Unreal client Native input + simulation FFI resource and session contract Authoritative match Actor / native tick owner Pinned protocol + state epoch Results authority Command + durable receipt Outbox follows that commit session result Web / mobile companion Lobby + accessible interaction Same public operation identities Model / matchmaking Capability constraints Measured placement and budgets Shadow release scenario Disconnect + duplicate input Upgrade + recover + inspect Game-state rewind, graph revert and deployment rollback are different operations. Integration does not replace engine internals. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision A reusable multiplayer region can own lobby/session logic, model selection and release qualification while leaving engine rendering, physics and the tick loop native. State and effects cross only declared boundaries. ## What this does not establish Section ID: what-this-does-not-establish What this does not establish This is a proposed application design, not an implemented Reaktor game stack. Native integration, device parity, rollout behavior and performance need their own qualification. Falsifiable acceptance test. Upgrade the match implementation under mixed client versions while injecting disconnect, duplicate delivery and acknowledgement loss. Preserve authority and recover outcomes. Theory, precedent and Reaktor context: The Living Graph Live session topology Durable work FFI / Switchboard Surface contracts and interaction Unreal Engine — Introduction to Blueprints ## A ride-dispatch feature, from maps to durable assignment Section ID: panel-scenario-dispatch A ride-dispatch feature, from maps to durable assignment Compose a mobile native capability, low-latency stream and durable command without inventing three unrelated APIs. Vector diagram · click a marked item to inspect A ride-dispatch feature, from maps to durable assignment Diagram: A ride-dispatch feature, from maps to durable assignment A ride-dispatch feature, from maps to durable assignment Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary MOBILE / NATIVE HOSTS EDGE + MATCH AUTHORITY DATA + OPERATIONS E1 E2 E3 E4 E5 E6 H1 H1 · Trip session [H06] rider: rider.session | driver: driver.session | authority: match.session Rider map UI N11 / rider state request session Driver location N15 / driver offer positions session Ingress + geo filter N07 / edge positions request candidate update Match actor + ranker N05 / match candidate session assign Trip authority N21 / db assign receipt record Operations dashboard N11 / ops record update decision PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-1 Reaktor design decision Push a ranking-policy change only after its boundary, model requirements and session assumptions remain compatible. A new native map SDK still requires a host build. ## Boundary / caveat Section ID: boundary--caveat Boundary / caveat Trip database owns durable assignment; Match actor owns one active control scope. Qualification test. Lose the commit reply, then retry the same command. No second driver may be assigned; old trip sessions must remain valid. Actual authority: Trip database owns durable assignment; Match actor owns one active control scope. Candidate update: Ranker inside Match region; preserve actor state Push a ranking-policy change only after its boundary, model requirements and session assumptions remain compatible. A new native map SDK still requires a host build. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H02 driver.positions → edge.positions sampled stream E2 H05 rider.request → edge.request request + identity E3 H02 edge.candidate → match.candidate bounded candidates E4 H05 match.assign → db.assign conditional write E5 H04 db.record → ops.record trip events E6 H04 edge.update → rider.state live map state H1 / H06 — Trip session: participant (rider) = rider.session; participant (driver) = driver.session; authority (authority) = match.session Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes Diagram inspection notes E1: driver.positions → edge.positions | H02 | sampled stream E2: rider.request → edge.request | H05 | request + identity E3: edge.candidate → match.candidate | H02 | bounded candidates E4: match.assign → db.assign | H05 | conditional write E5: db.record → ops.record | H04 | trip events E6: edge.update → rider.state | H04 | live map state Trip session | H06 | rider=rider.session; driver=driver.session; authority=match.session rider · Rider map UI [N11]: A map SDK is exposed through a Surface/native adapter; map internals remain external. driver · Driver location [N15]: Sampling and OS permissions belong to the installed host; location payloads do not become persistent graph entities. edge · Ingress + geo filter [N07]: Bound noisy location streams, authenticate callers and preserve trip/session correlation. match · Match actor + ranker [N05]: Owns assignment transitions. The replaceable ranking function is not the owner of active trip state. db · Trip authority [N21]: Conditional assignment writes and outbox share the real store transaction. ops · Operations dashboard [N11]: Observes approved trip state and issues separately authorized intervention commands. ## Checkout: a local transaction plus an external saga Section ID: panel-scenario-checkout Checkout: a local transaction plus an external saga Keep local ACID and distributed recovery in one visible feature without pretending they are the same guarantee. Vector diagram · click a marked item to inspect Checkout: a local transaction plus an external saga Diagram: Checkout: a local transaction plus an external saga Checkout: a local transaction plus an external saga Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary CLIENT + IDENTITY DURABLE WORK AUTHORITY INDEPENDENT PROVIDERS E1 E2 E3 E4 E5 E6 E7 E8 H1 H1 · Saga compensation [H17] checkout: work.state | refund: payment.refund | release: stock.release Checkout Surface N14 / ui status submit Tenant / identity gate N33 / auth context grant Checkout workflow N06 / work submit grant reserve charge state Order + outbox DB N23 / order state stock receipt events Inventory service N21 / stock reserve release stock Payment provider N19 / payment charge refund reconcile Notification worker N24 / notify events delivery PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-2 Reaktor design decision Change retry or routing logic for new checkout instances. Existing persisted workflows retain their old definition unless an explicit continuation migration is qualified. ## Boundary / caveat Section ID: boundary--caveat-1 Boundary / caveat Order/outbox storage is one atomic domain; payment and inventory are independent authorities. Qualification test. A payment commits and the reply is lost. Reconcile by payment key before retrying; failure compensation is itself durable work. Actual authority: Order/outbox storage is one atomic domain; payment and inventory are independent authorities. Candidate update: Version workflow; pin in-flight continuation Change retry or routing logic for new checkout instances. Existing persisted workflows retain their old definition unless an explicit continuation migration is qualified. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H05 ui.submit → work.submit durable command E2 H23 auth.grant → work.grant scoped grant E3 H05 work.reserve → stock.reserve reserve E4 H05 work.charge → payment.charge charge id E5 H02 stock.stock → order.stock reserved stock E6 H02 work.state → order.state workflow state E7 H04 order.events → notify.events outbox delivery E8 H04 order.receipt → ui.status receipt / status H1 / H17 — Saga compensation: forward (checkout) = work.state; compensator (refund) = payment.refund; compensator (release) = stock.release Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-1 Diagram inspection notes E1: ui.submit → work.submit | H05 | durable command E2: auth.grant → work.grant | H23 | scoped grant E3: work.reserve → stock.reserve | H05 | reserve E4: work.charge → payment.charge | H05 | charge id E5: stock.stock → order.stock | H02 | reserved stock E6: work.state → order.state | H02 | workflow state E7: order.events → notify.events | H04 | outbox delivery E8: order.receipt → ui.status | H04 | receipt / status Saga compensation | H17 | checkout=work.state; refund=payment.refund; release=stock.release ui · Checkout Surface [N14]: Draft validation stays separate from submitting durable work. auth · Tenant / identity gate [N33]: The client cannot mint a payment or inventory grant. work · Checkout workflow [N06]: Stable command identity, persisted continuation and explicit unknown-outcome handling. order · Order + outbox DB [N23]: Order mutation and its notification intent commit together under this authority only. stock · Inventory service [N21]: Reservation uses a key and expiry; remote participation is not silently part of the order DB transaction. payment · Payment provider [N19]: Charge idempotency and status lookup are provider-qualified requirements. notify · Notification worker [N24]: At-least-once delivery needs application-level deduplication or acceptable duplicate policy. ## Multiplayer across Unreal, Unity and a shared backend Section ID: panel-scenario-game Multiplayer across Unreal, Unity and a shared backend A single feature definition spans game-native execution, companion UI, a live protocol and durable back-end work. Vector diagram · click a marked item to inspect Multiplayer across Unreal, Unity and a shared backend Diagram: Multiplayer across Unreal, Unity and a shared backend Multiplayer across Unreal, Unity and a shared backend Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary GAME + COMPANION CLIENTS SESSION + GAME SERVER PERSISTENCE + MODELS E1 E2 E3 E4 E5 E6 E7 H1 H1 · Match session [H06] player: engine.session | observer: lobby.session | authority: sim.session Unreal / Unity client N16 / engine snapshot input session Web / mobile lobby N11 / lobby status join session Session ingress N05 / gateway input join session commands Authoritative match N29 / sim commands policy snapshot result session Bot / ranking model N18 / model state policy Results authority N21 / data result receipt PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-3 Reaktor design decision A matchmaking change can affect new matches immediately after qualification. Replacing a native engine binary or hot-swapping live physics is a different release class. ## Boundary / caveat Section ID: boundary--caveat-2 Boundary / caveat Match activation owns simulation; result database owns durable outcomes. Qualification test. Disconnect/rejoin and upgrade the match definition. Existing matches must not receive code with incompatible state or tick semantics. Actual authority: Match activation owns simulation; result database owns durable outcomes. Candidate update: New match definition; old matches pin old version A matchmaking change can affect new matches immediately after qualification. Replacing a native engine binary or hot-swapping live physics is a different release class. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H07 engine.input → gateway.input input protocol E2 H05 lobby.join → gateway.join join match E3 H02 gateway.commands → sim.commands ordered input E4 H07 sim.snapshot → engine.snapshot state snapshots E5 H02 model.policy → sim.policy bot policy E6 H05 sim.result → data.result durable result E7 H04 gateway.session → lobby.status session state H1 / H06 — Match session: participant (player) = engine.session; observer (observer) = lobby.session; authority (authority) = sim.session Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-2 Diagram inspection notes E1: engine.input → gateway.input | H07 | input protocol E2: lobby.join → gateway.join | H05 | join match E3: gateway.commands → sim.commands | H02 | ordered input E4: sim.snapshot → engine.snapshot | H07 | state snapshots E5: model.policy → sim.policy | H02 | bot policy E6: sim.result → data.result | H05 | durable result E7: gateway.session → lobby.status | H04 | session state Match session | H06 | player=engine.session; observer=lobby.session; authority=sim.session engine · Unreal / Unity client [N16]: Generated Blueprint/C++ or C# boundary bindings; renderer, physics and prediction remain engine-owned. lobby · Web / mobile lobby [N11]: Same match identity and session contract across companion clients. gateway · Session ingress [N05]: Sequence validation, authentication, session pinning and admission budgets. sim · Authoritative match [N29]: Each match activation owns a tick loop; simulation transforms are not graph-definition commits. model · Bot / ranking model [N18]: Model and preprocessing artifacts have explicit device/quality requirements. data · Results authority [N21]: Durable result submission has match/round identity; deduplicate retried outcomes. ## Private voice coaching with adaptive inference Section ID: panel-scenario-voice Private voice coaching with adaptive inference Compose local-first behavior and cloud capability without silently treating cloud as a universally superior fallback. Vector diagram · click a marked item to inspect Private voice coaching with adaptive inference Diagram: Private voice coaching with adaptive inference Private voice coaching with adaptive inference Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary DEVICE / BROWSER OPTIONAL NETWORK PATH QUALIFICATION + CONTENT E1 E2 E3 E4 E5 E6 E7 E8 H1 H1 · Provider choice [H24] privacy/quality: route.policy | local: local.offer | remote: cloud.offer | selection: route.decision Microphone + UI N15 / mic feedback pcm Local VAD + model N18 / local pcm policy segments feedback offer Capability resolver N32 / route segments policy evidence request decision Remote speech model N18 / cloud request feedback offer Privacy / lesson policy N33 / policy consent policy Evaluation corpus N36 / eval candidate evidence PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-4 Reaktor design decision Update a policy region or model artifact only when the installed host can execute it and its quality/privacy evidence applies. A recorded transcript is not evidence for a new model’s quality. ## Boundary / caveat Section ID: boundary--caveat-3 Boundary / caveat Device owns live audio; each provider owns qualified execution; policy limits export. Qualification test. Revoke network permission or consent mid-session. No new audio may be exported; in-flight outcomes and cleanup remain explicit. Actual authority: Device owns live audio; each provider owns qualified execution; policy limits export. Candidate update: Update routing policy, not native microphone ABI Update a policy region or model artifact only when the installed host can execute it and its quality/privacy evidence applies. A recorded transcript is not evidence for a new model’s quality. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H02 mic.pcm → local.pcm leased audio E2 H02 local.segments → route.segments segments / metadata E3 H05 route.request → cloud.request only if eligible E4 H04 local.feedback → mic.feedback local result E5 H04 cloud.feedback → mic.feedback remote result E6 H23 policy.policy → route.policy privacy constraint E7 H23 policy.policy → local.policy local requirement E8 H02 eval.evidence → route.evidence qualification H1 / H24 — Provider choice: requirement (privacy/quality) = route.policy; offer (local) = local.offer; offer (remote) = cloud.offer; decision (selection) = route.decision Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-3 Diagram inspection notes E1: mic.pcm → local.pcm | H02 | leased audio E2: local.segments → route.segments | H02 | segments / metadata E3: route.request → cloud.request | H05 | only if eligible E4: local.feedback → mic.feedback | H04 | local result E5: cloud.feedback → mic.feedback | H04 | remote result E6: policy.policy → route.policy | H23 | privacy constraint E7: policy.policy → local.policy | H23 | local requirement E8: eval.evidence → route.evidence | H02 | qualification Provider choice | H24 | privacy/quality=route.policy; local=local.offer; remote=cloud.offer; selection=route.decision mic · Microphone + UI [N15]: Installed microphone adapter; permissions and audio thread remain host-specific. local · Local VAD + model [N18]: Owned audio buffers; local inference remains available when network or consent prohibits remote work. route · Capability resolver [N32]: Evaluate hard privacy, connectivity and quality requirements before preferences. cloud · Remote speech model [N18]: Remote speech receives only permitted payloads under a scoped data policy. policy · Privacy / lesson policy [N33]: Content, user consent and residency constrain eligible providers. eval · Evaluation corpus [N36]: Assess model output quality separately from replay of orchestration. ## Industrial telemetry around a qualified control boundary Section ID: panel-scenario-iot Industrial telemetry around a qualified control boundary Model telemetry and deployment around an external system without claiming ownership of its certified internals. Vector diagram · click a marked item to inspect Industrial telemetry around a qualified control boundary Diagram: Industrial telemetry around a qualified control boundary Industrial telemetry around a qualified control boundary Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary EDGE / PHYSICAL SYSTEM MESSAGE + ANALYTICS CLOUD + OPERATIONS E1 E2 E3 E4 E5 E6 E7 H1 H1 · Safety separation [H22] control: plc.request | analytics: filter.config | separation: ops.config Sensor gateway N15 / sensor sampling readings PLC / control boundary N30 / plc request status Edge filter + detector N07 / filter readings config alerts telemetry Durable broker N24 / broker telemetry status events Historian / analytics N21 / store events trend Operator dashboard N20 / ops alerts trend approved request config PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-5 Reaktor design decision A new anomaly detector can be delivered to a qualified edge runtime. Safety-critical firmware changes remain a separate controlled process, not an automatic extension of graph updateability. ## Boundary / caveat Section ID: boundary--caveat-4 Boundary / caveat PLC controls physical actuation; broker/store own persisted telemetry; operators authorize commands. Qualification test. Lose the cloud and deploy an analytics update. Local safety control must remain unaffected; buffer exhaustion must be bounded. Actual authority: PLC controls physical actuation; broker/store own persisted telemetry; operators authorize commands. Candidate update: Analytics update; safety/control region excluded A new anomaly detector can be delivered to a qualified edge runtime. Safety-critical firmware changes remain a separate controlled process, not an automatic extension of graph updateability. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H02 sensor.readings → filter.readings sampled telemetry E2 H04 filter.telemetry → broker.telemetry bounded delivery E3 H04 plc.status → broker.status control status E4 H04 broker.events → store.events historian stream E5 H04 filter.alerts → ops.alerts alerts E6 H02 store.trend → ops.trend trend E7 H23 ops.approved request → plc.request approved command H1 / H22 — Safety separation: member (control) = plc.request; member (analytics) = filter.config; constraint (separation) = ops.config Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-4 Diagram inspection notes E1: sensor.readings → filter.readings | H02 | sampled telemetry E2: filter.telemetry → broker.telemetry | H04 | bounded delivery E3: plc.status → broker.status | H04 | control status E4: broker.events → store.events | H04 | historian stream E5: filter.alerts → ops.alerts | H04 | alerts E6: store.trend → ops.trend | H02 | trend E7: ops.approved request → plc.request | H23 | approved command Safety separation | H22 | control=plc.request; analytics=filter.config; separation=ops.config sensor · Sensor gateway [N15]: Calibration, timestamps and sequence are part of the ingress contract. plc · PLC / control boundary [N30]: Existing qualified safety/control implementation stays opaque and independent; no generic hot code push. filter · Edge filter + detector [N07]: Bounded buffers and event-time semantics; telemetry update must not alter safety control. broker · Durable broker [N24]: Explicit retention, QoS and redelivery contract supplied by the broker. store · Historian / analytics [N21]: Time-series data remains in a specialized store. ops · Operator dashboard [N20]: Operator command has an independent authority path to the control boundary. ## A reproducible model experiment and deployment pipeline Section ID: panel-scenario-ml A reproducible model experiment and deployment pipeline Connect experiment reproducibility and runtime deployment without conflating a model tensor graph with the architecture graph. Vector diagram · click a marked item to inspect A reproducible model experiment and deployment pipeline Diagram: A reproducible model experiment and deployment pipeline A reproducible model experiment and deployment pipeline Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary INPUT ARTIFACTS COMPUTE / EXPERIMENT EVIDENCE + RELEASE E1 E2 E3 E4 E5 E6 E7 E8 H1 H1 · Experiment provenance [H27] data: dataset.dataset | features: pre.features | candidate: train.candidate | evaluation: eval.run | evidence: eval.evidence Dataset manifest N26 / dataset access dataset Preprocessing region N01 / pre dataset features GPU training job N06 / train features config candidate metrics Baseline evaluator N18 / base features baseline Comparison + gates N36 / eval candidate baseline metrics evidence run Model release authority N35 / registry evidence candidate release PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-6 Reaktor design decision Deploy the resulting model region only where its operators, shapes and memory requirements are supported. Model quality evidence and orchestrator replay validate different claims. ## Boundary / caveat Section ID: boundary--caveat-5 Boundary / caveat Artifact stores own datasets and weights; the experiment authority pins the full input/run vector. Qualification test. Change preprocessing but keep the model name. Invalidate dependent evaluation and refuse stale approval. Actual authority: Artifact stores own datasets and weights; the experiment authority pins the full input/run vector. Candidate update: Feature/model change widens evaluation closure Deploy the resulting model region only where its operators, shapes and memory requirements are supported. Model quality evidence and orchestrator replay validate different claims. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H02 dataset.dataset → pre.dataset pinned dataset E2 H02 pre.features → train.features feature schema E3 H02 pre.features → base.features same evaluation inputs E4 H02 train.candidate → eval.candidate candidate digest E5 H02 base.baseline → eval.baseline baseline outputs E6 H02 train.metrics → eval.metrics run measures E7 H28 eval.evidence → registry.evidence claim-indexed evidence E8 H26 train.candidate → registry.candidate immutable artifact H1 / H27 — Experiment provenance: input (data) = dataset.dataset; input (features) = pre.features; input (candidate) = train.candidate; transform (evaluation) = eval.run; output (evidence) = eval.evidence Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-5 Diagram inspection notes E1: dataset.dataset → pre.dataset | H02 | pinned dataset E2: pre.features → train.features | H02 | feature schema E3: pre.features → base.features | H02 | same evaluation inputs E4: train.candidate → eval.candidate | H02 | candidate digest E5: base.baseline → eval.baseline | H02 | baseline outputs E6: train.metrics → eval.metrics | H02 | run measures E7: eval.evidence → registry.evidence | H28 | claim-indexed evidence E8: train.candidate → registry.candidate | H26 | immutable artifact Experiment provenance | H27 | data=dataset.dataset; features=pre.features; candidate=train.candidate; evaluation=eval.run; evidence=eval.evidence dataset · Dataset manifest [N26]: Versioned, access-controlled references; the graph is not a duplicate of every sample. pre · Preprocessing region [N01]: Pin transforms, feature schema and random sources where relevant. train · GPU training job [N06]: Durable job lifecycle with checkpoint ownership; model internals may remain opaque source. base · Baseline evaluator [N18]: Same evaluation contract, not necessarily identical hardware execution. eval · Comparison + gates [N36]: Task-specific claims, confidence and slice coverage; no universal verified scalar. registry · Model release authority [N35]: Signed, immutable artifacts and approved target/runtime requirement vector. ## Local-first collaborative editing with controlled publication Section ID: panel-scenario-collab Local-first collaborative editing with controlled publication Put merge-friendly editing beside coordinated publication rather than making every invariant use the same consistency model. Vector diagram · click a marked item to inspect Local-first collaborative editing with controlled publication Diagram: Local-first collaborative editing with controlled publication Local-first collaborative editing with controlled publication Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary CLIENT REPLICAS SYNC + PUBLICATION PERSISTENT OUTPUTS E1 E2 E3 E4 E5 E6 E7 E8 H1 H1 · Draft replica group [H14] replica A: a.edit | replica B: b.edit | merge service: sync.merged Editor A / local store N25 / a merged edit publish Editor B / local store N25 / b merged edit publish Merge / sync service N25 / sync a b merged Publication authority N23 / authority publish document version events Versioned documents N21 / store version snapshot Export / search workers N06 / render events artifact PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-7 Reaktor design decision A server sync change must remain compatible with offline clients until the allowed upgrade window ends. A graph snapshot is not permission to resurrect deleted document payloads. ## Boundary / caveat Section ID: boundary--caveat-6 Boundary / caveat Replicas own local drafts; publication authority owns the published revision. Qualification test. Two disconnected users publish divergent drafts. The exclusive publication invariant must be checked at its authority. Actual authority: Replicas own local drafts; publication authority owns the published revision. Candidate update: Protocol update requires mixed-version sync support A server sync change must remain compatible with offline clients until the allowed upgrade window ends. A graph snapshot is not permission to resurrect deleted document payloads. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H14 a.edit → sync.a replica edits E2 H14 b.edit → sync.b replica edits E3 H07 sync.merged → a.merged merged draft E4 H07 sync.merged → b.merged merged draft E5 H02 sync.merged → authority.document draft revision E6 H05 a.publish → authority.publish publish command E7 H05 authority.version → store.version conditional commit E8 H04 authority.events → render.events durable export H1 / H14 — Draft replica group: replica (replica A) = a.edit; replica (replica B) = b.edit; authority (merge service) = sync.merged Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-6 Diagram inspection notes E1: a.edit → sync.a | H14 | replica edits E2: b.edit → sync.b | H14 | replica edits E3: sync.merged → a.merged | H07 | merged draft E4: sync.merged → b.merged | H07 | merged draft E5: sync.merged → authority.document | H02 | draft revision E6: a.publish → authority.publish | H05 | publish command E7: authority.version → store.version | H05 | conditional commit E8: authority.events → render.events | H04 | durable export Draft replica group | H14 | replica A=a.edit; replica B=b.edit; merge service=sync.merged a · Editor A / local store [N25]: Local text/draft edits can use a qualified merge scheme while offline. b · Editor B / local store [N25]: Replica state and tombstones are application data, not architecture definitions. sync · Merge / sync service [N25]: CRDT or operational transformation where the chosen invariant permits it. authority · Publication authority [N23]: Exclusive release/publication invariants use a serializable decision, not unconstrained merging. store · Versioned documents [N21]: Versioned content and access policy support later retrieval and deletion constraints. render · Export / search workers [N06]: Durable downstream processing with source-version identity. ## A low-copy camera and GPU processing pipeline Section ID: panel-scenario-media A low-copy camera and GPU processing pipeline Show how graph contracts preserve meaning without forcing large buffers through generic serialized values. Vector diagram · click a marked item to inspect A low-copy camera and GPU processing pipeline Diagram: A low-copy camera and GPU processing pipeline A low-copy camera and GPU processing pipeline Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary NATIVE ACQUISITION LOCAL COMPUTE + UI OPTIONAL REMOTE OUTPUT E1 E2 E3 E4 E5 E6 H1 H1 · Lifetime constraint [H22] owner lease: pool.lease | GPU borrower: gpu.frame lease | UI borrower: ui.preview lease Native camera resource N16 / camera configuration frame lease Buffer / resource owner N26 / pool release lease GPU crop + inference N17 / gpu frame lease model result preview lease Preview Surface N11 / ui preview lease result released Encoder / upload region N17 / encoder frame lease chunks Media object store N26 / store chunks artifact PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-8 Reaktor design decision FlexBuffers can carry width/height/format/timestamp and attachment indices. The actual memory path is qualified per backend and may need a copy, fence or process restart. ## Boundary / caveat Section ID: boundary--caveat-7 Boundary / caveat Native buffer owner controls lifetime; activation generations pin callbacks and consumers. Qualification test. Replace the processing region while GPU work is in flight. Old callbacks and leases must never target freed code or reused handle slots. Actual authority: Native buffer owner controls lifetime; activation generations pin callbacks and consumers. Candidate update: Swap compatible operator after outstanding leases drain FlexBuffers can carry width/height/format/timestamp and attachment indices. The actual memory path is qualified per backend and may need a copy, fence or process restart. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H02 camera.frame lease → gpu.frame lease borrow / lease E2 H02 gpu.preview lease → ui.preview lease GPU fence + view E3 H04 gpu.result → ui.result structured metadata E4 H02 camera.frame lease → encoder.frame lease qualified sharing E5 H02 encoder.chunks → store.chunks encoded stream E6 H02 ui.released → pool.release release token H1 / H22 — Lifetime constraint: constraint (owner lease) = pool.lease; member (GPU borrower) = gpu.frame lease; member (UI borrower) = ui.preview lease Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-7 Diagram inspection notes E1: camera.frame lease → gpu.frame lease | H02 | borrow / lease E2: gpu.preview lease → ui.preview lease | H02 | GPU fence + view E3: gpu.result → ui.result | H04 | structured metadata E4: camera.frame lease → encoder.frame lease | H02 | qualified sharing E5: encoder.chunks → store.chunks | H02 | encoded stream E6: ui.released → pool.release | H02 | release token Lifetime constraint | H22 | owner lease=pool.lease; GPU borrower=gpu.frame lease; UI borrower=ui.preview lease camera · Native camera resource [N16]: Frame metadata and backing resource have separate lifetime/representation contracts. pool · Buffer / resource owner [N26]: Generational handles; release belongs to the allocator/owner that created the buffer. gpu · GPU crop + inference [N17]: Explicit synchronization and memory-domain transitions; no unconditional zero-copy promise. ui · Preview Surface [N11]: Native rendering continues on its qualified host thread. encoder · Encoder / upload region [N17]: Remote boundaries require bytes or qualified shared-memory transport, not local pointers. store · Media object store [N26]: Controlled artifact references and retention; raw frame traffic is not graph metadata. ## A multi-party allocation problem, not a web of pairwise links Section ID: panel-scenario-logistics A multi-party allocation problem, not a web of pairwise links Represent one joint constraint over orders, warehouses, vehicles and time without losing its identity in pairwise edges. Vector diagram · click a marked item to inspect A multi-party allocation problem, not a web of pairwise links Diagram: A multi-party allocation problem, not a web of pairwise links A multi-party allocation problem, not a web of pairwise links Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary DEMAND + SUPPLY INPUTS OPTIMIZATION AUTHORITY APPROVAL + EXECUTION E1 E2 E3 E4 E5 H1 H1 · Allocation relation [H09] demand: demand.orders | capacity: supply.capacity | proposal: solve.proposal | assignment: dispatch.assignment Orders / time windows N22 / demand refresh orders Warehouses / vehicles N22 / supply refresh capacity Temporal input join N07 / join orders capacity snapshot Allocation optimizer N01 / solve snapshot policy proposal Human approval N20 / approve proposal decision Reservation + dispatch N23 / dispatch decision assignment receipt PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-9 Reaktor design decision A better optimizer is a substitutable implementation if it preserves required feasibility and effect contracts. Its objective/quality claims need fresh comparative evidence. ## Boundary / caveat Section ID: boundary--caveat-8 Boundary / caveat Input stores own availability; reservation authority owns accepted assignments. Qualification test. Capacity changes after optimization. Reject or recompute a stale plan rather than committing an over-allocation. Actual authority: Input stores own availability; reservation authority owns accepted assignments. Candidate update: Optimize-policy region; approvals invalidate on changed inputs A better optimizer is a substitutable implementation if it preserves required feasibility and effect contracts. Its objective/quality claims need fresh comparative evidence. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H11 demand.orders → join.orders versioned demand E2 H11 supply.capacity → join.capacity versioned supply E3 H02 join.snapshot → solve.snapshot aligned input cut E4 H02 solve.proposal → approve.proposal proposal + assumptions E5 H23 approve.decision → dispatch.decision scoped approval H1 / H09 — Allocation relation: input (demand) = demand.orders; input (capacity) = supply.capacity; input (proposal) = solve.proposal; result (assignment) = dispatch.assignment Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-8 Diagram inspection notes E1: demand.orders → join.orders | H11 | versioned demand E2: supply.capacity → join.capacity | H11 | versioned supply E3: join.snapshot → solve.snapshot | H02 | aligned input cut E4: solve.proposal → approve.proposal | H02 | proposal + assumptions E5: approve.decision → dispatch.decision | H23 | scoped approval Allocation relation | H09 | demand=demand.orders; capacity=supply.capacity; proposal=solve.proposal; assignment=dispatch.assignment demand · Orders / time windows [N22]: Authoritative availability and requested delivery windows are versioned inputs. supply · Warehouses / vehicles [N22]: Capacity, stock and location constraints come from separate qualified sources. join · Temporal input join [N07]: Align by a declared cut/window and mark missing or stale observations. solve · Allocation optimizer [N01]: Solver profile, objective and limits are explicit; infeasible is a legitimate outcome. approve · Human approval [N20]: Approval is revision-scoped and does not waive current availability checks. dispatch · Reservation + dispatch [N23]: Revalidate and reserve at the actual inventory/dispatch authority before emitting work. ## Reaktor improves a Reaktor system without approving itself Section ID: panel-scenario-selfhost Reaktor improves a Reaktor system without approving itself The same system language can describe its own tooling without granting self-modifying code control over the root of trust. Vector diagram · click a marked item to inspect Reaktor improves a Reaktor system without approving itself Diagram: Reaktor improves a Reaktor system without approving itself Reaktor improves a Reaktor system without approving itself Named ports • explicit relation roles • specialized runtime lanes • candidate update boundary HUMAN + AGENT WORKSPACE BUILD + SHADOW TRUSTED RELEASE AUTHORITY E1 E2 E3 E4 E5 E6 E7 E8 H1 H1 · Acceptance claim [H28] release claim: draft.claim | evidence: shadow.evidence | independent verifier: approve.verifier Agent + source editor N39 / agent findings patch Candidate graph branch N23 / draft patch candidate claim Compiler / packager N34 / build candidate artifacts findings Shadow scenario runner N36 / shadow candidate artifacts evidence Independent policy gate N33 / approve candidate evidence decision verifier Region rollout controller N40 / rollout decision receipt observed PURPLE DASH = update candidate / semantic relation overlay; this is not an implicit network protocol. ## Reaktor design decision Section ID: reaktor-design-decision-10 Reaktor design decision Human and agent changes use the same patch/receipt model. External harnesses need OS/tool isolation or an explicit incomplete-governance declaration. ## Boundary / caveat Section ID: boundary--caveat-9 Boundary / caveat Graph authority owns candidate/promotion; independent policy owns approval; runtime hosts own activation. Qualification test. Change a candidate after Shadow or weaken its gate in the patch. Release admission must refuse stale or self-authorized approval. Actual authority: Graph authority owns candidate/promotion; independent policy owns approval; runtime hosts own activation. Candidate update: Candidate product region only; trust roots remain outside Human and agent changes use the same patch/receipt model. External harnesses need OS/tool isolation or an explicit incomplete-governance declaration. Inspect every drawn relationship ID Schema pattern Owned port endpoints Meaning E1 H25 agent.patch → draft.patch typed edit E2 H26 draft.candidate → build.candidate pinned revision E3 H26 draft.candidate → shadow.candidate exact candidate E4 H26 build.artifacts → shadow.artifacts artifact vector E5 H28 shadow.evidence → approve.evidence claims / coverage E6 H26 draft.candidate → approve.candidate candidate digest E7 H23 approve.decision → rollout.decision release authority E8 H04 build.findings → agent.findings source-linked findings H1 / H28 — Acceptance claim: claim (release claim) = draft.claim; evidence (evidence) = shadow.evidence; verifier (independent verifier) = approve.verifier Some binary arrows are projections of relations that also use policy or descriptor metadata; the H oval shows the explicit n-ary relation. These are proposed descriptors, not compiled source. Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph Reaktor FFI / Switchboard ## Diagram inspection notes Section ID: diagram-inspection-notes-9 Diagram inspection notes E1: agent.patch → draft.patch | H25 | typed edit E2: draft.candidate → build.candidate | H26 | pinned revision E3: draft.candidate → shadow.candidate | H26 | exact candidate E4: build.artifacts → shadow.artifacts | H26 | artifact vector E5: shadow.evidence → approve.evidence | H28 | claims / coverage E6: draft.candidate → approve.candidate | H26 | candidate digest E7: approve.decision → rollout.decision | H23 | release authority E8: build.findings → agent.findings | H04 | source-linked findings Acceptance claim | H28 | release claim=draft.claim; evidence=shadow.evidence; independent verifier=approve.verifier agent · Agent + source editor [N39]: A bounded task context identifies region, code, grants and unresolved obligations. draft · Candidate graph branch [N23]: Save typed holes during drafting; base revision and mutation authority remain explicit. build · Compiler / packager [N34]: Generate region images, source maps and semantic dependency closure. shadow · Shadow scenario runner [N36]: Isolated pre-state, prescribed workload and failure injection. Capture is not unrestricted execution authority. approve · Independent policy gate [N33]: Agent cannot weaken required tests and approve the same release; trusted verifier boundary is outside the patch. rollout · Region rollout controller [N40]: Signed bundle distribution, host admission, atomic local publication and cross-host reconciliation. # Composition and execution semantics URL: https://reaktor.build/docs/architecture-atlas-semantics Status: design Content revision: fd44e21b8d7f1654050f790abbb0e0b6efab5f2e99c1ff305f736696c9622a64 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-cospan","panel-rewrite","panel-statecharts-v2","panel-scc","panel-protocol","panel-petri","panel-queues","panel-resources","panel-timescales"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-semantics","polarity":"Neutral"},{"id":"section-7-composition-rewriting-and-graph-theory","anchor":"7-composition-rewriting-and-graph-theory","label":"7. Composition, rewriting and graph theory","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#7-composition-rewriting-and-graph-theory","polarity":"Neutral"},{"id":"section-8-programming-and-execution-semantics","anchor":"8-programming-and-execution-semantics","label":"8. Programming and execution semantics","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#8-programming-and-execution-semantics","polarity":"Neutral"},{"id":"section-panel-cospan","anchor":"panel-cospan","label":"Composition is gluing a boundary, not drawing an arrow","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#panel-cospan","polarity":"Neutral"},{"id":"section-panel-rewrite","anchor":"panel-rewrite","label":"A safe rewrite explains what must remain","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#panel-rewrite","polarity":"Neutral"},{"id":"section-panel-statecharts-v2","anchor":"panel-statecharts-v2","label":"Statecharts as an execution profile","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#panel-statecharts-v2","polarity":"Neutral"},{"id":"section-panel-scc","anchor":"panel-scc","label":"Allow cycles where their semantics are defined","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#panel-scc","polarity":"Neutral"},{"id":"section-what-this-does-not-establish","anchor":"what-this-does-not-establish","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#what-this-does-not-establish","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-1","anchor":"what-this-does-not-establish-1","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#what-this-does-not-establish-1","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-3","anchor":"what-this-does-not-establish-3","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#what-this-does-not-establish-3","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-4","anchor":"what-this-does-not-establish-4","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#what-this-does-not-establish-4","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-5","anchor":"what-this-does-not-establish-5","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#what-this-does-not-establish-5","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-6","anchor":"what-this-does-not-establish-6","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#what-this-does-not-establish-6","polarity":"Neutral"},{"id":"section-what-this-does-not-establish-7","anchor":"what-this-does-not-establish-7","label":"What this does not establish","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-semantics#what-this-does-not-establish-7","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-semantics:references-architecture-atlas-foundations","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-architecture-atlas-vocabulary","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-vocabulary","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-architecture-atlas-language","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-architecture-atlas-evolution","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-evolution","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-architecture-atlas-workbench","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-architecture-atlas-scenarios","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-scenarios","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-architecture-atlas-qualification","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-qualification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-graph-sources","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-7-composition-rewriting-and-graph-theory","role":"source","ordinal":0},{"node":"reaktor-graph-sources","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-8-programming-and-execution-semantics","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-unified-system-graph","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-formal-methods","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-1","role":"source","ordinal":0},{"node":"reaktor-formal-methods","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-stable-foundations-5.6-ultra","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-1","role":"source","ordinal":0},{"node":"reaktor-stable-foundations-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-graph-protocol","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-3","role":"source","ordinal":0},{"node":"reaktor-graph-protocol","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-service","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-3","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-work","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-3","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-data-workflows","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-4","role":"source","ordinal":0},{"node":"reaktor-data-workflows","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-ffi","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-5","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-mesh","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-5","role":"source","ordinal":0},{"node":"reaktor-mesh","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-bus-mesh","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-5","role":"source","ordinal":0},{"node":"reaktor-bus-mesh","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-component-lifecycle","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-6","role":"source","ordinal":0},{"node":"reaktor-component-lifecycle","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-surface-contracts-and-interaction","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-7","role":"source","ordinal":0},{"node":"reaktor-surface-contracts-and-interaction","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-surface-dynamic-ui-and-verification","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-7","role":"source","ordinal":0},{"node":"reaktor-surface-dynamic-ui-and-verification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-reaktor-surface-performance-and-assets","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-7","role":"source","ordinal":0},{"node":"reaktor-surface-performance-and-assets","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-semantics:references-operations-graph-evidence","kind":"references","owner":"architecture-atlas-semantics","incidences":[{"node":"architecture-atlas-semantics","port":"section-what-this-does-not-establish-7","role":"source","ordinal":0},{"node":"operations-graph-evidence","port":"page","role":"target","ordinal":0}]}]} ## Composition and execution semantics Section ID: composition-and-execution-semantics Composition and execution semantics Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification ## 7. Composition, rewriting and graph theory Section ID: 7-composition-rewriting-and-graph-theory 7. Composition, rewriting and graph theory A role-labelled incidence model makes n-ary relationships first class without turning every relation into a fake service. Let an incidence identify a hyperedge, node-owned port, role and optional position. A binary exclusive binding, a many-party session and a fanout relation share storage, but their role and cardinality laws remain different. Open regions admit a useful category-theoretic model: boundaries are objects and implementations with exposed boundaries are morphisms. Sequential composition glues a shared interface; independent composition places regions side by side. Decorated cospans provide a formal construction under stated assumptions. Associativity and identity laws can become property tests for extraction, substitution and deployment partitioning. Reaktor still needs to choose an exact typed model and prove that its representation satisfies those laws. [Fong — Decorated Cospans (2015)] [Fong & Spivak — Seven Sketches in Compositionality] Do not import copying or discarding laws for unique native resources merely because a diagram contains junctions. Ports with linear or affine ownership need restrictions. Likewise, DPO-style rewriting supplies structural matching/gluing conditions; it does not prove that replacing a payment or actor implementation preserves business behavior. [Patch Graph Rewriting: comparison with DPO rewriting] [WebAssembly Component Model — WIT] [Apache Arrow — C data interface] Source-to-graph projections resemble lenses. Within a supported syntax subset, extracting after an accepted edit should recover the intended view, and writing an unchanged view should preserve the source modulo declared equivalence. Arbitrary foreign code cannot be promised a lossless round trip. Source ownership and staged publication are more important than claiming universal bidirectionality. [Foster et al. — Combinators for Bidirectional Tree Transformations] [Source ownership] These theories should mostly produce compact specifications and acceptance tests. They are not a reason to implement a general category-theory engine inside the hot runtime. ## 8. Programming and execution semantics Section ID: 8-programming-and-execution-semantics 8. Programming and execution semantics Blueprint should denote a system, not just generate isolated Kotlin or JavaScript functions. The compiler output is a program bundle: graph revision, per-runtime region artifacts, service/FFI descriptors, schemas, placement and capability requirements, durable-work definitions, source maps, deployment intent and verification obligations. Build and realization are distinct phases. The distributed abstract machine is semantic: named runtime islands with local execution, messages and sessions, resource owners, durable authorities and activation generations. It is not one physical interpreter spanning the network. A local pure call can lower to a direct function; a remote command lowers to a qualified service/work boundary. Failed or unavailable network execution is part of the language semantics, not an invisible implementation detail. Keep three domain perspectives: topology/composition describes what exists and connects; behavior specifies state, control, values and effects; realization describes how approved definitions become running components. They share identity and schemas, but not one universal wire law. Each module dialect contributes legality and lowering rules. Code owns efficient algorithms; graph-owned regions make system composition inspectable and editable. A source-owned region uses supported source edits. A structured-owned region has deterministic, versioned graph source and generates adapters or code. Layout, comments and editor coordinates stay separate from executable meaning. Cosmetic dragging must not change the semantic digest or invalidate Shadow. Transferring source ownership is an explicit migration, never a silent bidirectional overwrite. Reaktor Visual Language / Blueprints General computation belongs inside behavior profiles with branches, calls, recursion/growable memory and explicit effects. Statecharts and workflow DAGs are useful restricted profiles, not the ceiling of the language. No generic static analysis can establish every behavioral property of arbitrary source; unsupported semantic knowledge is marked opaque while the boundary remains typed. Ptolemy II is one of the closest architectural precedents: port-connected hierarchical actors whose directors specify models of computation. This strongly supports Reaktor’s use of qualified profiles rather than treating every connection as an ordinary function call and every cycle as an error. [Ptolemy II: hierarchy, ports and models of computation] [Lee & Parks — Dataflow Process Networks (1995)] Use strongly connected components for recursive analysis or grouped activation, but let the semantic profile distinguish call recursion, delayed stream feedback, fixed-point queries and invalid ownership cycles. A condensed dependency graph being acyclic does not establish termination or a useful runtime schedule. Session types and state machines make protocol phases checkable. A restricted workflow-net profile can visualize enabled work, outstanding branches and completion. Neither theory automatically handles every timeout, process crash, cancellation or unbounded program; their assumptions must survive projection and execution. [Honda, Yoshida & Carbone — Multiparty Asynchronous Session Types] [A Mechanised Theory of Multiparty Asynchronous Session Types (ECOOP 2025)] [van der Aalst et al. — Soundness of workflow nets] Queueing theory connects the graph to operational behavior. Little’s law relates stable mean occupancy, arrival rate and response time. The M/M/1 model additionally assumes Poisson arrivals and exponential single-server service; its divergence near capacity explains why credits, admission and retry budgets matter. It is not a production latency model or a p99 predictor. [MIT OpenCourseWare — Queueing theory and Little’s law] Placement is a constrained partitioning problem, not simply minimizing drawn network edges. Privacy, state ownership, memory domain, affinity and runtime availability are hard constraints. Optimize measured traffic or latency over feasible choices, using bounded methods or heuristics and exposing the chosen objective. ## Composition is gluing a boundary, not drawing an arrow Section ID: panel-cospan Composition is gluing a boundary, not drawing an arrow The practical benefit is a reusable law for extraction, replacement and deployment partitioning. Composition is gluing a boundary, not drawing an arrow Law / model / proof obligation: X → F ← Y, Y → G ← Z ⇒ X → (F +ᵧ G) ← Z Diagram: Composition is gluing a boundary, not drawing an arrow CATEGORY THEORY • COMPONENTS AS OPEN SYSTEMS X F: normalize Input and output boundary Internal implementation Y G: persist Input and output boundary Internal implementation Z COMPOSITION • GLUE THE SHARED, TYPE-CHECKED BOUNDARY X G ∘ F: one reusable feature Glue along Y; do not duplicate Y’s semantic identity. Hide internal wiring behind exported ports. Z Formal model: typed/decorated cospans under suitable colimits. Reaktor’s ownership restrictions need explicit laws. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision Use open regions whose exported contracts stay fixed while their internals change. Composition should be associative up to the declared identity/isomorphism convention; identity regions should do nothing semantically. ## What this does not establish Section ID: what-this-does-not-establish What this does not establish This is a proposed semantic model, not a proved theorem about current Reaktor. Do not infer arbitrary copying/deleting of linear resources from an unrestricted hypergraph/Frobenius construction. Falsifiable acceptance test. Compose three pure regions with either parenthesization and compare observables and boundary ownership. Reject an attempt to duplicate a unique camera handle. Theory, precedent and Reaktor context: Fong — Decorated Cospans (2015) Fong & Spivak — Seven Sketches in Compositionality The Living Graph ## A safe rewrite explains what must remain Section ID: panel-rewrite A safe rewrite explains what must remain Treat a rewrite as a transaction proposal with a preserved interface and explicit preconditions. A safe rewrite explains what must remain Law / model / proof obligation: L ← K → R; require a legal match and gluing conditions, then discharge semantic obligations. Diagram: A safe rewrite explains what must remain GRAPH REWRITING • MATCH, PRESERVE, REPLACE L: old implementation Boundary + obsolete internals K: preserved interface Stable ports and owned identity R: new implementation Boundary + replacement internals preserve preserve ADMISSION EXAMPLE • A REFERENCED RESOURCE CANNOT SIMPLY DISAPPEAR Outside region A still-live external reference Deleted resource No replacement mapping Rewrite result REJECT: dangling reference The dangling condition is structural. Types, authority, state migration and behavior add separate obligations. ## Reaktor design decision Section ID: reaktor-design-decision-1 Reaktor design decision DPO-style reasoning makes deletion and replacement conditions precise. Reaktor can use a simpler typed patch representation while testing equivalent preservation rules for the supported fragment. ## What this does not establish Section ID: what-this-does-not-establish-1 What this does not establish General graph matching can be expensive. Use stable identities and bounded matches for normal edits. Structural legality does not prove behavior equivalence or authorize an effect. Falsifiable acceptance test. Toggle the external reference. A destructive rewrite is rejected while that unremapped reference remains. Theory, precedent and Reaktor context: Patch Graph Rewriting: comparison with DPO rewriting Formal methods and evidence Stable foundations ## Statecharts as an execution profile Section ID: panel-statecharts-v2 Statecharts as an execution profile Hierarchical states, parallel regions, guards and actors make protocol and interaction behavior explicit. Vector diagram · click a marked item to inspect Statecharts are one execution dialect inside a larger system Diagram: Statecharts are one execution dialect inside a larger system SESSION ACTOR / statechart profile / owned event queue Idle No session resources Joining Invoke handshake actor Closed No new input admitted Active: parallel child regions Transport Connected / reconnecting Synchronization Catching up / current JOIN ACCEPT LEAVE CANCEL / FAIL Guards are pure. Actions declare effects. A guarded transition updates actor state; external commands remain explicit operations with their own outcomes. Invocation-lifetime child actors stop when their owning scope exits under the declared profile. Statechart inspection Observe event, state, child lifecycle and microsteps. Distinguish a definition from a running activation. Persist only when a durable profile actually does so. Other legal regions remain first class Pure functions, recursion, streams and native code. No universal finite-state or workflow-DAG restriction. A remote effect may outlive a local cancel transition. This miniature viewer only demonstrates a local state progression; it is not an XState runtime or distributed-model checker. ## Reaktor design decision Section ID: reaktor-design-decision-2 Reaktor design decision Define a qualified statechart dialect with explicit actor lifetime, event ordering, transition and effect semantics. Expose snapshots/microsteps through existing graph inspection. ## Boundary / caveat Section ID: boundary--caveat Boundary / caveat A statechart is not automatically durable or distributed. Pure guards do not undo commands already accepted by another authority. Qualification test. Leave the Joining state while a request has committed remotely. Stop the child scope, but retrieve/reconcile the external result rather than claiming the effect vanished. Official context and precedents: State machines and statecharts XState actor semantics Stately inspection API ## Allow cycles where their semantics are defined Section ID: panel-scc Allow cycles where their semantics are defined Do not impose DAG restrictions globally merely because they simplify one workflow executor. Allow cycles where their semantics are defined Law / model / proof obligation: Condense(G) is a DAG; each SCC is a maximal mutually reachable set. Diagram: Allow cycles where their semantics are defined GRAPH ALGORITHMS • STRONGLY CONNECTED COMPONENTS A B C D E Cycle A–D; downstream E is outside the SCC. CONDENSATION GRAPH • A DAG OF COMPONENTS SCC {A, B, C, D} Treat as one analysis/scheduling unit. Its execution profile supplies the law. Downstream E Separate component Acyclic condensation is structural. Convergence, deadlock freedom and scheduling still require profile-specific reasoning. ## Reaktor design decision Section ID: reaktor-design-decision-3 Reaktor design decision Use SCCs for recursive dependency analysis, mutually dependent activation groups and fixed-point queries. Enforce acyclicity only on relations such as exclusive ownership containment that require it. ## What this does not establish Section ID: what-this-does-not-establish-2 What this does not establish A cycle can denote recursion, feedback with delay, a fixed point or deadlock. These are not interchangeable. Every accepted cycle needs the corresponding semantics and budget. Falsifiable acceptance test. Accept a stream feedback loop with explicit delay/state; reject a cyclic ownership chain under the containment profile. Theory, precedent and Reaktor context: The Living Graph Ptolemy II: hierarchy, ports and models of computation Compositionality of dataflow models ## A well-typed message can still be an illegal action Section ID: panel-protocol A well-typed message can still be an illegal action Unary calls, streams, jobs and sessions need different interaction contracts. A well-typed message can still be an illegal action Law / model / proof obligation: State × Event → State × Outcome; local projections must preserve the chosen global protocol. Diagram: A well-typed message can still be an illegal action SESSION / PROTOCOL THEORY • THE PHASE MATTERS Created Admitted Committed Acknowledged GLOBAL CHOREOGRAPHY → QUALIFIED LOCAL AUTOMATA Client role Submit → await receipt → reconcile Timeout is not proof of failure. Authority role Check → commit → return receipt Acknowledge may be lost. Delivery role Publish retained intent → retry Deduplicate at the effect owner. A payload schema can match while completion semantics, cancellation or durable ownership are incompatible. ## Reaktor design decision Section ID: reaktor-design-decision-4 Reaktor design decision Use protocol automata to check request admission, cancellation, durable completion and recovery. Project a global choreography only where the chosen multiparty type theory supports projection and composition. ## What this does not establish Section ID: what-this-does-not-establish-3 What this does not establish Session-type progress results have assumptions. Crashes, timeouts, cancellation and transport reordering must be modeled or honestly excluded. Falsifiable acceptance test. Advance the call phases. A lost acknowledgement must trigger receipt reconciliation, not a second commit. Theory, precedent and Reaktor context: Graph protocol Service contracts Honda, Yoshida & Carbone — Multiparty Asynchronous Session Types A Mechanised Theory of Multiparty Asynchronous Session Types (ECOOP 2025) Durable work ## Visualize what a workflow is waiting for Section ID: panel-petri Visualize what a workflow is waiting for A finite Petri-net profile can make deadlock and completion obligations concrete. Visualize what a workflow is waiting for Law / model / proof obligation: A transition fires only when enabled; m′ = m + C·u is necessary bookkeeping, not a reachability proof. Diagram: Visualize what a workflow is waiting for PETRI NET • PARALLEL WORK AND A JOIN split Branch A complete Branch B complete join Tokens describe a marking. The join is enabled only when both required input places contain tokens. ## Reaktor design decision Section ID: reaktor-design-decision-5 Reaktor design decision Represent supported bounded workflow control as places, transitions and tokens. Test proper completion, missing branches and outstanding work instead of inferring completion from a drawn DAG. ## What this does not establish Section ID: what-this-does-not-establish-4 What this does not establish General extensions can make soundness difficult or undecidable. Bounded model checks apply to a pinned finite abstraction, not arbitrary Turing-complete behavior. Falsifiable acceptance test. Step through split and join. The final token appears only after consuming both branch tokens. Theory, precedent and Reaktor context: van der Aalst et al. — Soundness of workflow nets Durable work Data workflows ## Backpressure is a first-class network contract Section ID: panel-queues Backpressure is a first-class network contract Capacity, buffering, retry and arrival behavior belong in the binding plan and evidence. Backpressure is a first-class network contract Law / model / proof obligation: Little: L = λW in a stable system. M/M/1: W = 1/(μ−λ), under the stated assumptions. Diagram: Backpressure is a first-class network contract QUEUEING THEORY • UTILIZATION IS NOT LINEAR LATENCY Arrival process λ requests / second Poisson in this toy model One modeled server μ = 100 requests / second Exponential service; infinite queue Steady-state mean W = 1 / (μ − λ) Only when λ < μ INTERACTIVE ILLUSTRATION • NOT REAKTOR BENCHMARK DATA Load ρ = 0.50 Mean W = 20 ms Mean L = 1.0 Backpressure bounds admission or buffering. It does not create service capacity, and a mean does not determine p99. ## Reaktor design decision Section ID: reaktor-design-decision-6 Reaktor design decision Expose credits, queue depth, drop/coalesce policy, service capacity and deadline budget. Avoid retry policies that amplify overload and unchecked stream buffering that converts latency into memory exhaustion. ## What this does not establish Section ID: what-this-does-not-establish-5 What this does not establish This toy assumes Poisson arrivals, exponential service, one server and steady state. Real workloads need measurements and different models; no percentile or throughput claim follows. Falsifiable acceptance test. Drive the toy arrival rate to capacity. The mean diverges rather than displaying a misleading finite prediction. Theory, precedent and Reaktor context: MIT OpenCourseWare — Queueing theory and Little’s law FFI / Switchboard Live session topology Bus versus live Mesh ## Make resource misuse unrepresentable where possible Section ID: panel-resources Make resource misuse unrepresentable where possible The same lifetime contract must survive native, managed and asynchronous boundaries. Make resource misuse unrepresentable where possible Law / model / proof obligation: Borrow lifetime ⊆ owner lifetime; one owned token cannot be duplicated without an explicit sharing operation. Diagram: Make resource misuse unrepresentable where possible RESOURCE THEORY • BORROWING IS NOT COPYING OWNERSHIP Owner activation Unique camera buffer lease Borrowed view Valid within the call scope Async consumer Needs owned transfer or retain borrow not automatic Lifetime acquire borrow starts borrow ends release owner retained borrowed call scope Owned transfer, shared retain and borrowed access are distinct. Raw pointers are not portable remote resource identities. ## Reaktor design decision Section ID: reaktor-design-decision-7 Reaktor design decision Use generated wrappers, static checks and runtime generation/lease validation. The graph catalogs the contract; the hot runtime enforces its qualified representation without serializing every resource. ## What this does not establish Section ID: what-this-does-not-establish-6 What this does not establish Static ownership laws cannot prevent every defect in opaque native code. A zero-copy path remains unsafe if a callback outlives the buffer, even when its bytes are correctly encoded. Falsifiable acceptance test. Suspend an async consumer past the original borrowed call. Require a legal transfer/retain or reject the binding at generation/admission. Theory, precedent and Reaktor context: FFI / Switchboard Component lifecycle WebAssembly Component Model — WIT Apache Arrow — C data interface ## Do not transact an architecture edit for every state update Section ID: panel-timescales Do not transact an architecture edit for every state update Surface and game-native workloads expose why one store or scheduler would be the wrong unification. Do not transact an architecture edit for every state update Law / model / proof obligation: Definition revision ≠ activation epoch ≠ durable event sequence ≠ reactive/frame state. Diagram: Do not transact an architecture edit for every state update MULTIPLE TIMESCALES • ONE SEMANTIC IDENTITY, DIFFERENT STATE OWNERS Definition revisions Schemas, composition, policy Draft → validate → promote Activation epochs Executable image and owned resources Prepare → safe cutover → drain Durable work Commands, receipts, checkpoints Recover according to its authority Frame / tick / reactive values Pixels, transforms, local interaction Host-native fast path; no definition commit Timescales are illustrative categories, not performance promises. Identity joins the planes without equating their transactions. ## Reaktor design decision Section ID: reaktor-design-decision-8 Reaktor design decision Keep source maps and operation IDs across planes. A performance tracer joins an observed invocation to its activation and definition; it does not make every animation sample a semantic graph record. ## What this does not establish Section ID: what-this-does-not-establish-7 What this does not establish Reactive state can be persisted when the application requires it, but that is a separate state authority. Different streams have different retention and privacy policies. Falsifiable acceptance test. Update a theme value or game transform without rebuilding topology. Hot-replace a stateful region only under its explicit migration and lifetime protocol. Theory, precedent and Reaktor context: Surface contracts and interaction Dynamic UI and verification Surface performance and assets Operational graph evidence Component lifecycle # Nodes, ports and hyperedge vocabulary URL: https://reaktor.build/docs/architecture-atlas-vocabulary Status: design Content revision: 3bf155bcdb8060dac01fa91d6acd12831898dabb8297176b945f6cf9a3bd9711 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-nodes-1","panel-nodes-2","panel-nodes-3","panel-nodes-4","panel-ports-1","panel-ports-2","panel-relations-1","panel-relations-2","panel-relations-3","panel-vocabulary"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary","polarity":"Neutral"},{"id":"section-4-node-families","anchor":"4-node-families","label":"4. Node families","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#4-node-families","polarity":"Neutral"},{"id":"section-5-port-profiles","anchor":"5-port-profiles","label":"5. Port profiles","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#5-port-profiles","polarity":"Neutral"},{"id":"section-6-hyperedge-patterns","anchor":"6-hyperedge-patterns","label":"6. Hyperedge patterns","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#6-hyperedge-patterns","polarity":"Neutral"},{"id":"section-panel-nodes-1","anchor":"panel-nodes-1","label":"Node families · behavior","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#panel-nodes-1","polarity":"Neutral"},{"id":"section-panel-nodes-2","anchor":"panel-nodes-2","label":"Node families · experience","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#panel-nodes-2","polarity":"Neutral"},{"id":"section-panel-nodes-3","anchor":"panel-nodes-3","label":"Node families · resources","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#panel-nodes-3","polarity":"Neutral"},{"id":"section-boundary--caveat","anchor":"boundary--caveat","label":"Boundary / caveat","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#boundary--caveat","polarity":"Neutral"},{"id":"section-boundary--caveat-4","anchor":"boundary--caveat-4","label":"Boundary / caveat","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-vocabulary#boundary--caveat-4","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-vocabulary:references-architecture-atlas-foundations","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-architecture-atlas-semantics","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-semantics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-architecture-atlas-language","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-architecture-atlas-evolution","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-evolution","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-architecture-atlas-workbench","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-workbench","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-architecture-atlas-scenarios","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-scenarios","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-architecture-atlas-qualification","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-qualification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"section-boundary--caveat","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-reaktor-unified-system-graph","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"section-boundary--caveat","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-vocabulary:references-reaktor-ffi","kind":"references","owner":"architecture-atlas-vocabulary","incidences":[{"node":"architecture-atlas-vocabulary","port":"section-boundary--caveat-4","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]}]} ## Nodes, ports and hyperedge vocabulary Section ID: nodes-ports-and-hyperedge-vocabulary Nodes, ports and hyperedge vocabulary Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification ## 4. Node families Section ID: 4-node-families 4. Node families ## N01 · Pure computation Section ID: n01--pure-computation N01 · Pure computation Map, hash, score, validate Contract: No hidden effects; cache only against declared inputs and semantic version. ## N02 · Effectful operation Section ID: n02--effectful-operation N02 · Effectful operation Send, reserve, write, invoke Contract: Effects and required grants are explicit; timeout does not imply no effect. ## N03 · Decision / pattern match Section ID: n03--decision--pattern-match N03 · Decision / pattern match Guard, switch, eligibility Contract: Define exhaustive cases and defaults; guards are pure in the selected profile. ## N04 · Loop / recursive region Section ID: n04--loop--recursive-region N04 · Loop / recursive region Fold, iterate, call itself Contract: Specify continuation/state semantics and resource budgets; a cycle is not a schedule. ## N05 · Actor / statechart Section ID: n05--actor--statechart N05 · Actor / statechart Session, cart, connection Contract: Owns state and event ordering; hierarchy does not itself provide durability. ## N06 · Workflow / saga Section ID: n06--workflow--saga N06 · Workflow / saga Checkout, onboarding, import Contract: Version durable continuations; make retries, unknown results and compensation explicit. ## N07 · Stream operator Section ID: n07--stream-operator N07 · Stream operator Filter, window, resample Contract: Specify demand, buffering, event-time policy, loss and cancellation. ## N08 · Fork / join / scheduler Section ID: n08--fork--join--scheduler N08 · Fork / join / scheduler Parallel tasks, join, race Contract: Choose all/any/quorum semantics, including failure and abandoned branches. ## N09 · Timer / clock source Section ID: n09--timer--clock-source N09 · Timer / clock source Deadline, interval, logical tick Contract: Distinguish logical, event and wall clocks; inject clocks for replay. ## N10 · Function / blueprint region Section ID: n10--function--blueprint-region N10 · Function / blueprint region Reusable feature, generic subgraph Contract: Stable exported interface; instantiate fresh owned state, not copied global identity. ## N11 · Surface / view component Section ID: n11--surface--view-component N11 · Surface / view component Screen, card, scene overlay Contract: Interaction semantics are shared; native renderer behavior is qualified separately. ## N12 · Route / navigation Section ID: n12--route--navigation N12 · Route / navigation Deep link, page, modal Contract: Make route state, permissions and unsupported destinations explicit. ## N13 · Input / interaction source Section ID: n13--input--interaction-source N13 · Input / interaction source Gesture, keyboard, controller Contract: Declare focus, sampling, ordering and host lifecycle behavior. ## N14 · Form / validation region Section ID: n14--form--validation-region N14 · Form / validation region Address form, editor inspector Contract: Keep draft/invalid state saveable; effects require separately accepted values. ## N15 · Device / platform adapter Section ID: n15--device--platform-adapter N15 · Device / platform adapter Camera, GPS, clipboard Contract: Native implementation is bounded by OS permissions, affinity and installed capabilities. ## N16 · Native resource / engine Section ID: n16--native-resource--engine N16 · Native resource / engine Map SDK, Unity, Unreal, codec Contract: Resource owner and release callback survive async calls; opaque internals stay declared. ## N17 · Media transform Section ID: n17--media-transform N17 · Media transform Crop, encode, render, mix Contract: Specify memory domain, mutability, format and synchronization; zero-copy is conditional. ## N18 · Model inference Section ID: n18--model-inference N18 · Model inference Ranker, speech, embedding Contract: Pin model artifact and preprocessing; quality requires task-specific evidence. ## N19 · Tool / external API adapter Section ID: n19--tool--external-api-adapter N19 · Tool / external API adapter Geocoder, payments, search Contract: Treat credentials and external outcomes separately from local graph transactions. ## N20 · Human decision / approval Section ID: n20--human-decision--approval N20 · Human decision / approval Review, moderation, release signoff Contract: Human identity, scope, policy version and expiry are part of the decision. ## N21 · Database / state authority Section ID: n21--database--state-authority N21 · Database / state authority Postgres, SQLite, KV authority Contract: Actual store profile determines isolation and durability; rows are not architecture nodes. ## N22 · Query / materialized view Section ID: n22--query--materialized-view N22 · Query / materialized view Projection, lookup, aggregate Contract: Declare source cut, freshness and dependency coverage; no unsound negative inference. ## N23 · Transaction / unit of work Section ID: n23--transaction--unit-of-work N23 · Transaction / unit of work Graph commit, local outbox Contract: Atomicity applies only to the named authority and enlisted qualified resources. ## N24 · Queue / log / pubsub resource Section ID: n24--queue--log--pubsub-resource N24 · Queue / log / pubsub resource Topic, task queue, event journal Contract: Delivery, retention, offset, deduplication and redelivery laws belong to the provider. ## N25 · Cache / replica / sync agent Section ID: n25--cache--replica--sync-agent N25 · Cache / replica / sync agent Local-first replica, CDN cache Contract: Specify merge/conflict policy and deletion semantics; not every invariant permits CRDT merge. ## N26 · Blob / buffer / asset store Section ID: n26--blob--buffer--asset-store N26 · Blob / buffer / asset store Images, model weights, snapshots Contract: Graph stores descriptors and controlled references; large payloads remain in their owner. ## N27 · Runtime host / executor Section ID: n27--runtime-host--executor N27 · Runtime host / executor JVM, Hermes, browser, native Contract: Expose an installed capability descriptor and lifetime; target name alone is insufficient. ## N28 · Placement / resource pool Section ID: n28--placement--resource-pool N28 · Placement / resource pool Worker fleet, GPU pool, region Contract: Hard constraints precede optimization; placement is not proof of current availability. ## N29 · Factory / dynamic instance Section ID: n29--factory--dynamic-instance N29 · Factory / dynamic instance Match factory, tenant worker Contract: Separate reusable definition from dynamic instance identity and bounded registry visibility. ## N30 · External system boundary Section ID: n30--external-system-boundary N30 · External system boundary Legacy service, PLC, SaaS Contract: Expose integration coverage honestly; graph visibility does not sandbox external code. ## N31 · Schema / contract definition Section ID: n31--schema--contract-definition N31 · Schema / contract definition Record, protocol, resource ABI Contract: Represent as a node when independently referenced; otherwise keep it a typed value/facet. ## N32 · Capability offer / requirement Section ID: n32--capability-offer--requirement N32 · Capability offer / requirement Offline ranker, GPU offer Contract: Availability and suitability do not confer authority; selection is context-scoped. ## N33 · Policy / principal boundary Section ID: n33--policy--principal-boundary N33 · Policy / principal boundary Grant evaluator, tenant scope Contract: Secrets stay out of graph payloads; current effect-time authority is rechecked. ## N34 · Build / compiler pass Section ID: n34--build--compiler-pass N34 · Build / compiler pass Typecheck, lower, package Contract: Key caches by semantic inputs and toolchain; preserve source maps and qualification profile. ## N35 · Artifact / release manifest Section ID: n35--artifact--release-manifest N35 · Artifact / release manifest Signed region bundle, runtime image Contract: Stable identity differs from content digest; exclude cosmetic layout from semantic identity. ## N36 · Test / Shadow scenario Section ID: n36--test--shadow-scenario N36 · Test / Shadow scenario Fault replay, baseline/candidate Contract: Record assumptions, capture gaps and runner; no generic green-check guarantee. ## N37 · Claim / evidence record Section ID: n37--claim--evidence-record N37 · Claim / evidence record Protocol claim, performance run Contract: Evidence is claim-indexed, not a universal ordered strength score. ## N38 · Observer / query / visitor Section ID: n38--observer--query--visitor N38 · Observer / query / visitor Inspector, trace lens, analysis Contract: Inspection cannot mutate implicitly; coverage and authority limit conclusions. ## N39 · Agent / change proposer Section ID: n39--agent--change-proposer N39 · Agent / change proposer Planner, coding harness, reviewer Contract: Drafts are not deployment; effective tool/OS authority must be controlled or disclosed. ## N40 · Deployment / migration controller Section ID: n40--deployment--migration-controller N40 · Deployment / migration controller Rollout, drain, state transfer Contract: Durable reconciliation; monotonic fencing epochs and explicit mixed-version policy. ## 5. Port profiles Section ID: 5-port-profiles 5. Port profiles ## P01 · Value / immutable snapshot Section ID: p01--value--immutable-snapshot P01 · Value / immutable snapshot Out → In Contract: Schema, nullability, units and representation matter; value flow alone imposes no effect order. ## P02 · Request / response Section ID: p02--request--response P02 · Request / response Require ↔ Provide Contract: Direction is a role; sync/async, error and timeout outcomes are part of compatibility. ## P03 · Durable command / receipt Section ID: p03--durable-command--receipt P03 · Durable command / receipt Submit → Receipt Contract: Receipt names the qualified completion stage, not simply receipt of bytes. ## P04 · Push event Section ID: p04--push-event P04 · Push event EventOut → EventIn Contract: Declare ordering, overflow, replay and delivery guarantee; not implicitly durable. ## P05 · Pull iterator / cursor Section ID: p05--pull-iterator--cursor P05 · Pull iterator / cursor Next → Item|End Contract: Cursor lifetime, backpressure, consistency cut and resume behavior are explicit. ## P06 · Credit-controlled stream Section ID: p06--credit-controlled-stream P06 · Credit-controlled stream Stream + Request(n) Contract: Demand, buffer bounds, terminal events and cancellation must agree across the boundary. ## P07 · Duplex session Section ID: p07--duplex-session P07 · Duplex session Session Contract: Both endpoints follow the protocol; pin session version and handoff semantics. ## P08 · Signal / reactive state Section ID: p08--signal--reactive-state P08 · Signal / reactive state Signal Contract: Distinguish latest-value conflation from delivery of every historical change. ## P09 · Mutation / conditional update Section ID: p09--mutation--conditional-update P09 · Mutation / conditional update Update Contract: The authority checks predicates and authorization; local write locks are not distributed CAS. ## P10 · Transaction participant Section ID: p10--transaction-participant P10 · Transaction participant Participant Contract: Only qualified participants enlist; a transaction token is not universal ACID. ## P11 · Execution / continuation Section ID: p11--execution--continuation P11 · Execution / continuation ExecIn → ExecOut Contract: Defines effect order within one execution profile; not a generic network message. ## P12 · Branch / guarded transition Section ID: p12--branch--guarded-transition P12 · Branch / guarded transition Case / Event[Guard] Contract: Exhaustiveness and guard purity are checked; branch choice is separate from data encoding. ## P13 · Completion / join token Section ID: p13--completion--join-token P13 · Completion / join token Done Contract: Join rule defines required contributors and treatment of failure/cancellation. ## P14 · Cancellation / deadline Section ID: p14--cancellation--deadline P14 · Cancellation / deadline Cancel Contract: Cancellation is cooperative unless stated otherwise; reconcile already-committed effects. ## P15 · Clock / tick / timer Section ID: p15--clock--tick--timer P15 · Clock / tick / timer Tick Contract: Specify event-time versus processing-time semantics; clocks are dependencies for replay. ## P16 · Owned resource transfer Section ID: p16--owned-resource-transfer P16 · Owned resource transfer Owned Contract: Exactly one accepted owner after transfer; reject duplication and invalid module epoch. ## P17 · Borrowed buffer / view Section ID: p17--borrowed-buffer--view P17 · Borrowed buffer / view Borrow Contract: Cannot escape its declared scope; async and cross-address-space use require a qualified lease/copy. ## P18 · Shared read lease Section ID: p18--shared-read-lease P18 · Shared read lease SharedRead Contract: Reference counting alone does not make concurrent mutation safe; memory rules stay explicit. ## P19 · Capability descriptor Section ID: p19--capability-descriptor P19 · Capability descriptor Offer / Require Contract: Metadata for selection, not an authorization bearer; no implied access to the capability. ## P20 · Authorization request / grant Section ID: p20--authorization-request--grant P20 · Authorization request / grant Authorize Contract: Bind principal, scope, expiry and issuer; recheck at use and never serialize raw credentials. ## P21 · Lifecycle management Section ID: p21--lifecycle-management P21 · Lifecycle management Prepare / Activate / Drain / Release Contract: Calls may fail or be skipped on host death; required persistence cannot rely on cleanup. ## P22 · Checkpoint / migration Section ID: p22--checkpoint--migration P22 · Checkpoint / migration Snapshot → Restore Contract: Migration is versioned and staged; rollback depends on state compatibility, not old code availability. ## P23 · Artifact / schema reference Section ID: p23--artifact--schema-reference P23 · Artifact / schema reference Ref Contract: A reference is not a raw pointer; loading verifies integrity, provenance and access. ## P24 · Inspection / evidence Section ID: p24--inspection--evidence P24 · Inspection / evidence Observe → Finding Contract: Carries coverage and provenance; observational access does not confer mutation authority. ## 6. Hyperedge patterns Section ID: 6-hyperedge-patterns 6. Hyperedge patterns ## H01 · Exclusive binding Section ID: h01--exclusive-binding H01 · Exclusive binding consumer:1, provider:1 Contract: Reject a second provider where exclusivity is required; dispatch can compile to a direct call. ## H02 · Value flow Section ID: h02--value-flow H02 · Value flow source:1, sink:1..N Contract: Copy/fanout is legal only for the value ownership profile; units and schemas must match. ## H03 · Control precedence Section ID: h03--control-precedence H03 · Control precedence before:1..N, after:1..N Contract: Defines ordering under a named profile; does not serialize unrelated graph layers. ## H04 · Event subscription Section ID: h04--event-subscription H04 · Event subscription publisher:1..N, subscriber:1..N Contract: Subscriptions name filters, replay and delivery rules; broker resources remain separate nodes. ## H05 · Request / reply binding Section ID: h05--request--reply-binding H05 · Request / reply binding caller:1, callee:1, reply:0..1 Contract: Protocol includes correlation, failure and unknown outcomes; transport is chosen independently. ## H06 · Multiparty session Section ID: h06--multiparty-session H06 · Multiparty session authority:1, participant:1..N, observer:0..N Contract: Single relation identity with role/cardinality checks; delivery comes from an explicit protocol. ## H07 · Broadcast / fanout Section ID: h07--broadcast--fanout H07 · Broadcast / fanout producer:1, consumer:1..N Contract: State whether delivery waits for all, any or no receivers; slow receivers need a policy. ## H08 · Merge-any Section ID: h08--merge-any H08 · Merge-any producer:1..N, consumer:1 Contract: Specify interleaving, fairness and order; merging is not a join of corresponding values. ## H09 · Join-all Section ID: h09--join-all H09 · Join-all input:2..N, result:1 Contract: Align values by invocation/key; define failure, timeout and missing-input treatment. ## H10 · Race / select Section ID: h10--race--select H10 · Race / select contender:2..N, winner:1 Contract: Define first-completion versus first-success and cleanup/reconciliation of losing effects. ## H11 · Keyed temporal join Section ID: h11--keyed-temporal-join H11 · Keyed temporal join left:1, right:1..N, result:1 Contract: State key, clock, lateness/watermark and window policy; topology alone cannot pair records. ## H12 · Barrier / synchronization Section ID: h12--barrier--synchronization H12 · Barrier / synchronization member:2..N, continuation:1 Contract: Specify membership epoch, arrival condition and failure handling; no hidden global clock. ## H13 · Quorum requirement Section ID: h13--quorum-requirement H13 · Quorum requirement proposer:1, voter:1..N, result:1 Contract: Names a qualified protocol and membership; counting votes alone does not implement consensus. ## H14 · Replica group Section ID: h14--replica-group H14 · Replica group authority:0..1, replica:1..N Contract: Replication/merge and fencing rules are explicit; schema does not create consistency. ## H15 · Partition / route Section ID: h15--partition--route H15 · Partition / route router:1, shard:1..N Contract: Specify key function, assignment epoch and resharding; preserve owner and replay semantics. ## H16 · Atomic authority scope Section ID: h16--atomic-authority-scope H16 · Atomic authority scope authority:1, participant:1..N Contract: ACID applies only where that authority/profile implements it; not across arbitrary stores. ## H17 · Compensation relation Section ID: h17--compensation-relation H17 · Compensation relation forward:1, compensator:1..N Contract: Compensation is a new effect with its own failure modes, not automatic historical erasure. ## H18 · Supervision Section ID: h18--supervision H18 · Supervision supervisor:1, child:1..N Contract: Specify restart budget, state/ownership effects and host-death behavior. ## H19 · Ownership / containment Section ID: h19--ownership--containment H19 · Ownership / containment owner:1, owned:1..N Contract: Selected ownership relation is acyclic; visual grouping is not ownership. ## H20 · Instantiation Section ID: h20--instantiation H20 · Instantiation definition:1, instance:1..N Contract: Fresh activation identities and scopes; shared definitions are not shared mutable instance state. ## H21 · Placement Section ID: h21--placement H21 · Placement component:1..N, host:1..N Contract: A plan expresses intended placement; observations separately establish what actually runs. ## H22 · Affinity / separation Section ID: h22--affinity--separation H22 · Affinity / separation member:2..N, constraint:1 Contract: Co-location, anti-affinity or memory-domain rule is a constraint, not an executable wire. ## H23 · Scoped authorization Section ID: h23--scoped-authorization H23 · Scoped authorization principal:1, resource:1..N, policy:1 Contract: Decision is tied to action/context; visual reachability neither proves nor grants access. ## H24 · Capability resolution Section ID: h24--capability-resolution H24 · Capability resolution requirement:1, offer:1..N, decision:1 Contract: Filter hard constraints and grants before preferences; pin or safely migrate running sessions. ## H25 · Implements / source ownership Section ID: h25--implements--source-ownership H25 · Implements / source ownership source:1, contract:1..N, region:1 Contract: Exactly one edit authority per region; generated projections are not independently editable truth. ## H26 · Artifact dependency Section ID: h26--artifact-dependency H26 · Artifact dependency consumer:1, dependency:1..N Contract: Pin semantic/artifact revisions; cosmetic layout changes need not invalidate code. ## H27 · Derivation / provenance Section ID: h27--derivation--provenance H27 · Derivation / provenance input:1..N, transform:1, output:1..N Contract: Results carry input cut and transform version; unknown dependencies widen invalidation. ## H28 · Evidence supports claim Section ID: h28--evidence-supports-claim H28 · Evidence supports claim claim:1, evidence:1..N, verifier:1..N Contract: Scope assumptions and coverage; evidence does not promote or authorize itself. ## H29 · Activation cohort Section ID: h29--activation-cohort H29 · Activation cohort release:1, image:1..N, localRoot:1 Contract: Local root publication can be atomic; cross-host realization is recoverable coordination. ## H30 · Boundary export / alias Section ID: h30--boundary-export--alias H30 · Boundary export / alias internal:1..N, external:1..N Contract: Preserve role, ownership and protocol when hiding/expanding a reusable region. ## H31 · Clock / time alignment Section ID: h31--clock--time-alignment H31 · Clock / time alignment clock:1..N, stream:1..N Contract: Alignment needs a defined transform/uncertainty; timestamps do not establish causal order. ## H32 · Tensor / algebraic operation Section ID: h32--tensor--algebraic-operation H32 · Tensor / algebraic operation operand:1..N, operator:1, result:1..N Contract: Validate axes, units and device layout; computation belongs to the qualified implementation. ## H33 · Fallback / preference set Section ID: h33--fallback--preference-set H33 · Fallback / preference set requirement:1, alternative:1..N Contract: Fallbacks must remain eligible and authorized; never silently relax mandatory privacy or safety. ## H34 · Data access / lineage Section ID: h34--data-access--lineage H34 · Data access / lineage operation:1, store:1..N, schema:1..N Contract: Records the modeled access scope; enforce at actual storage boundary and disclose opaque access. ## H35 · State migration Section ID: h35--state-migration H35 · State migration oldState:1, migrator:1, newState:1 Contract: Version checkpoints, fence writers and validate postconditions; inverse may not exist. ## H36 · Navigation / interaction route Section ID: h36--navigation--interaction-route H36 · Navigation / interaction route origin:1, intent:1, destination:1..N Contract: Choose destination with guards and grants; back-stack and cancellation semantics are explicit. ## Node families · behavior Section ID: panel-nodes-1 Node families · behavior Ten representative module families: N01–N10. Full contracts are below the diagram. Vector diagram · click a marked item to inspect Node families: Behavior Diagram: Node families: Behavior NODE = family + facets + owned ports + profile + source / activation identity A family is a descriptor contribution, not a new kernel subclass. Select a card for its full contract. N01 Pure computation Map, hash, score, validate in: value:T out: result:U No hidden effects; cache only against declared inputs and semantic version. N02 Effectful operation Send, reserve, write, invoke in: request:I, context out: result:O|E Effects and required grants are explicit; timeout does not imply no effect. N03 Decision / pattern match Guard, switch, eligibility in: value:T out: branch:Case Define exhaustive cases and defaults; guards are pure in the selected profile. N04 Loop / recursive region Fold, iterate, call itself in: seed:T out: result:U Specify continuation/state semantics and resource budgets; a cycle is not a schedule. N05 Actor / statechart Session, cart, connection in: event:E out: state:S, effects Owns state and event ordering; hierarchy does not itself provide durability. N06 Workflow / saga Checkout, onboarding, import in: command:I out: receipt, outcome Version durable continuations; make retries, unknown results and compensation… N07 Stream operator Filter, window, resample in: stream:T out: stream:U Specify demand, buffering, event-time policy, loss and cancellation. N08 Fork / join / scheduler Parallel tasks, join, race in: activation out: completion Choose all/any/quorum semantics, including failure and abandoned branches. N09 Timer / clock source Deadline, interval, logical tick in: schedule out: tick, timeout Distinguish logical, event and wall clocks; inject clocks for replay. N10 Function / blueprint region Reusable feature, generic subgraph in: boundary:In out: boundary:Out Stable exported interface; instantiate fresh owned state, not copied global identity. Orthogonal facets include effects, lifecycle, tenancy, placement, observability, mutability and update policy. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision Keep stable entity identity and owned ports in the kernel; register domain families through versioned descriptors. Use typed facets for orthogonal concerns instead of a class hierarchy explosion. ## Boundary / caveat Section ID: boundary--caveat Boundary / caveat These categories overlap. A native inference service can combine resource, operation and model facets; a property is not automatically a separate node. Qualification test. Register a new domain family without changing the graph kernel, while unsupported required behavior still blocks activation. N01 · Pure computation Example / shape: Map, hash, score, validate Contract: No hidden effects; cache only against declared inputs and semantic version. proposed family; module-extensible N02 · Effectful operation Example / shape: Send, reserve, write, invoke Contract: Effects and required grants are explicit; timeout does not imply no effect. proposed family; module-extensible N03 · Decision / pattern match Example / shape: Guard, switch, eligibility Contract: Define exhaustive cases and defaults; guards are pure in the selected profile. proposed family; module-extensible N04 · Loop / recursive region Example / shape: Fold, iterate, call itself Contract: Specify continuation/state semantics and resource budgets; a cycle is not a schedule. proposed family; module-extensible N05 · Actor / statechart Example / shape: Session, cart, connection Contract: Owns state and event ordering; hierarchy does not itself provide durability. proposed family; module-extensible N06 · Workflow / saga Example / shape: Checkout, onboarding, import Contract: Version durable continuations; make retries, unknown results and compensation explicit. proposed family; module-extensible N07 · Stream operator Example / shape: Filter, window, resample Contract: Specify demand, buffering, event-time policy, loss and cancellation. proposed family; module-extensible N08 · Fork / join / scheduler Example / shape: Parallel tasks, join, race Contract: Choose all/any/quorum semantics, including failure and abandoned branches. proposed family; module-extensible N09 · Timer / clock source Example / shape: Deadline, interval, logical tick Contract: Distinguish logical, event and wall clocks; inject clocks for replay. proposed family; module-extensible N10 · Function / blueprint region Example / shape: Reusable feature, generic subgraph Contract: Stable exported interface; instantiate fresh owned state, not copied global identity. proposed family; module-extensible Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph ## Diagram inspection notes Section ID: diagram-inspection-notes Diagram inspection notes N01 · Pure computation: No hidden effects; cache only against declared inputs and semantic version. N02 · Effectful operation: Effects and required grants are explicit; timeout does not imply no effect. N03 · Decision / pattern match: Define exhaustive cases and defaults; guards are pure in the selected profile. N04 · Loop / recursive region: Specify continuation/state semantics and resource budgets; a cycle is not a schedule. N05 · Actor / statechart: Owns state and event ordering; hierarchy does not itself provide durability. N06 · Workflow / saga: Version durable continuations; make retries, unknown results and compensation explicit. N07 · Stream operator: Specify demand, buffering, event-time policy, loss and cancellation. N08 · Fork / join / scheduler: Choose all/any/quorum semantics, including failure and abandoned branches. N09 · Timer / clock source: Distinguish logical, event and wall clocks; inject clocks for replay. N10 · Function / blueprint region: Stable exported interface; instantiate fresh owned state, not copied global identity. ## Node families · experience Section ID: panel-nodes-2 Node families · experience Ten representative module families: N11–N20. Full contracts are below the diagram. Vector diagram · click a marked item to inspect Node families: Experience Diagram: Node families: Experience NODE = family + facets + owned ports + profile + source / activation identity A family is a descriptor contribution, not a new kernel subclass. Select a card for its full contract. N11 Surface / view component Screen, card, scene overlay in: state, commands out: interaction Interaction semantics are shared; native renderer behavior is qualified separately. N12 Route / navigation Deep link, page, modal in: intent out: result, location Make route state, permissions and unsupported destinations explicit. N13 Input / interaction source Gesture, keyboard, controller in: host event out: typed event Declare focus, sampling, ordering and host lifecycle behavior. N14 Form / validation region Address form, editor inspector in: model, edit out: valid value, issues Keep draft/invalid state saveable; effects require separately accepted values. N15 Device / platform adapter Camera, GPS, clipboard in: operation out: result, events Native implementation is bounded by OS permissions, affinity and installed… N16 Native resource / engine Map SDK, Unity, Unreal, codec in: command, lease out: event, lease Resource owner and release callback survive async calls; opaque internals stay… N17 Media transform Crop, encode, render, mix in: buffer lease out: buffer lease Specify memory domain, mutability, format and synchronization; zero-copy is… N18 Model inference Ranker, speech, embedding in: tensor, options out: prediction Pin model artifact and preprocessing; quality requires task-specific evidence. N19 Tool / external API adapter Geocoder, payments, search in: request out: result, receipt Treat credentials and external outcomes separately from local graph transactions. N20 Human decision / approval Review, moderation, release signoff in: proposal out: decision Human identity, scope, policy version and expiry are part of the decision. Orthogonal facets include effects, lifecycle, tenancy, placement, observability, mutability and update policy. ## Reaktor design decision Section ID: reaktor-design-decision-1 Reaktor design decision Keep stable entity identity and owned ports in the kernel; register domain families through versioned descriptors. Use typed facets for orthogonal concerns instead of a class hierarchy explosion. ## Boundary / caveat Section ID: boundary--caveat-1 Boundary / caveat These categories overlap. A native inference service can combine resource, operation and model facets; a property is not automatically a separate node. Qualification test. Register a new domain family without changing the graph kernel, while unsupported required behavior still blocks activation. N11 · Surface / view component Example / shape: Screen, card, scene overlay Contract: Interaction semantics are shared; native renderer behavior is qualified separately. proposed family; module-extensible N12 · Route / navigation Example / shape: Deep link, page, modal Contract: Make route state, permissions and unsupported destinations explicit. proposed family; module-extensible N13 · Input / interaction source Example / shape: Gesture, keyboard, controller Contract: Declare focus, sampling, ordering and host lifecycle behavior. proposed family; module-extensible N14 · Form / validation region Example / shape: Address form, editor inspector Contract: Keep draft/invalid state saveable; effects require separately accepted values. proposed family; module-extensible N15 · Device / platform adapter Example / shape: Camera, GPS, clipboard Contract: Native implementation is bounded by OS permissions, affinity and installed capabilities. proposed family; module-extensible N16 · Native resource / engine Example / shape: Map SDK, Unity, Unreal, codec Contract: Resource owner and release callback survive async calls; opaque internals stay declared. proposed family; module-extensible N17 · Media transform Example / shape: Crop, encode, render, mix Contract: Specify memory domain, mutability, format and synchronization; zero-copy is conditional. proposed family; module-extensible N18 · Model inference Example / shape: Ranker, speech, embedding Contract: Pin model artifact and preprocessing; quality requires task-specific evidence. proposed family; module-extensible N19 · Tool / external API adapter Example / shape: Geocoder, payments, search Contract: Treat credentials and external outcomes separately from local graph transactions. proposed family; module-extensible N20 · Human decision / approval Example / shape: Review, moderation, release signoff Contract: Human identity, scope, policy version and expiry are part of the decision. proposed family; module-extensible Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph ## Diagram inspection notes Section ID: diagram-inspection-notes-1 Diagram inspection notes N11 · Surface / view component: Interaction semantics are shared; native renderer behavior is qualified separately. N12 · Route / navigation: Make route state, permissions and unsupported destinations explicit. N13 · Input / interaction source: Declare focus, sampling, ordering and host lifecycle behavior. N14 · Form / validation region: Keep draft/invalid state saveable; effects require separately accepted values. N15 · Device / platform adapter: Native implementation is bounded by OS permissions, affinity and installed capabilities. N16 · Native resource / engine: Resource owner and release callback survive async calls; opaque internals stay declared. N17 · Media transform: Specify memory domain, mutability, format and synchronization; zero-copy is conditional. N18 · Model inference: Pin model artifact and preprocessing; quality requires task-specific evidence. N19 · Tool / external API adapter: Treat credentials and external outcomes separately from local graph transactions. N20 · Human decision / approval: Human identity, scope, policy version and expiry are part of the decision. ## Node families · resources Section ID: panel-nodes-3 Node families · resources Ten representative module families: N21–N30. Full contracts are below the diagram. Vector diagram · click a marked item to inspect Node families: Resources Diagram: Node families: Resources NODE = family + facets + owned ports + profile + source / activation identity A family is a descriptor contribution, not a new kernel subclass. Select a card for its full contract. N21 Database / state authority Postgres, SQLite, KV authority in: query, mutation out: rows, receipt Actual store profile determines isolation and durability; rows are not architecture… N22 Query / materialized view Projection, lookup, aggregate in: query, changes out: snapshot, delta Declare source cut, freshness and dependency coverage; no unsound negative inference. N23 Transaction / unit of work Graph commit, local outbox in: candidate, expected revision out: commit receipt Atomicity applies only to the named authority and enlisted qualified resources. N24 Queue / log / pubsub resource Topic, task queue, event journal in: publish out: delivery, ack Delivery, retention, offset, deduplication and redelivery laws belong to the provider. N25 Cache / replica / sync agent Local-first replica, CDN cache in: changes, sync out: view, checkpoint Specify merge/conflict policy and deletion semantics; not every invariant permits CRDT… N26 Blob / buffer / asset store Images, model weights, snapshots in: put, lease out: artifact ref, bytes Graph stores descriptors and controlled references; large payloads remain in their… N27 Runtime host / executor JVM, Hermes, browser, native in: activation image out: health, receipt Expose an installed capability descriptor and lifetime; target name alone is… N28 Placement / resource pool Worker fleet, GPU pool, region in: requirements out: reservation Hard constraints precede optimization; placement is not proof of current availability. N29 Factory / dynamic instance Match factory, tenant worker in: create, dispose out: activation handle Separate reusable definition from dynamic instance identity and bounded registry… N30 External system boundary Legacy service, PLC, SaaS in: declared interface out: observations Expose integration coverage honestly; graph visibility does not sandbox external code. Orthogonal facets include effects, lifecycle, tenancy, placement, observability, mutability and update policy. ## Reaktor design decision Section ID: reaktor-design-decision-2 Reaktor design decision Keep stable entity identity and owned ports in the kernel; register domain families through versioned descriptors. Use typed facets for orthogonal concerns instead of a class hierarchy explosion. ## Boundary / caveat Section ID: boundary--caveat-2 Boundary / caveat These categories overlap. A native inference service can combine resource, operation and model facets; a property is not automatically a separate node. Qualification test. Register a new domain family without changing the graph kernel, while unsupported required behavior still blocks activation. N21 · Database / state authority Example / shape: Postgres, SQLite, KV authority Contract: Actual store profile determines isolation and durability; rows are not architecture nodes. proposed family; module-extensible N22 · Query / materialized view Example / shape: Projection, lookup, aggregate Contract: Declare source cut, freshness and dependency coverage; no unsound negative inference. proposed family; module-extensible N23 · Transaction / unit of work Example / shape: Graph commit, local outbox Contract: Atomicity applies only to the named authority and enlisted qualified resources. proposed family; module-extensible N24 · Queue / log / pubsub resource Example / shape: Topic, task queue, event journal Contract: Delivery, retention, offset, deduplication and redelivery laws belong to the provider. proposed family; module-extensible N25 · Cache / replica / sync agent Example / shape: Local-first replica, CDN cache Contract: Specify merge/conflict policy and deletion semantics; not every invariant permits CRDT merge. proposed family; module-extensible N26 · Blob / buffer / asset store Example / shape: Images, model weights, snapshots Contract: Graph stores descriptors and controlled references; large payloads remain in their owner. proposed family; module-extensible N27 · Runtime host / executor Example / shape: JVM, Hermes, browser, native Contract: Expose an installed capability descriptor and lifetime; target name alone is insufficient. proposed family; module-extensible N28 · Placement / resource pool Example / shape: Worker fleet, GPU pool, region Contract: Hard constraints precede optimization; placement is not proof of current availability. proposed family; module-extensible N29 · Factory / dynamic instance Example / shape: Match factory, tenant worker Contract: Separate reusable definition from dynamic instance identity and bounded registry visibility. proposed family; module-extensible N30 · External system boundary Example / shape: Legacy service, PLC, SaaS Contract: Expose integration coverage honestly; graph visibility does not sandbox external code. proposed family; module-extensible Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph ## Diagram inspection notes Section ID: diagram-inspection-notes-2 Diagram inspection notes N21 · Database / state authority: Actual store profile determines isolation and durability; rows are not architecture nodes. N22 · Query / materialized view: Declare source cut, freshness and dependency coverage; no unsound negative inference. N23 · Transaction / unit of work: Atomicity applies only to the named authority and enlisted qualified resources. N24 · Queue / log / pubsub resource: Delivery, retention, offset, deduplication and redelivery laws belong to the provider. N25 · Cache / replica / sync agent: Specify merge/conflict policy and deletion semantics; not every invariant permits CRDT merge. N26 · Blob / buffer / asset store: Graph stores descriptors and controlled references; large payloads remain in their owner. N27 · Runtime host / executor: Expose an installed capability descriptor and lifetime; target name alone is insufficient. N28 · Placement / resource pool: Hard constraints precede optimization; placement is not proof of current availability. N29 · Factory / dynamic instance: Separate reusable definition from dynamic instance identity and bounded registry visibility. N30 · External system boundary: Expose integration coverage honestly; graph visibility does not sandbox external code. ## Node families · governance Section ID: panel-nodes-4 Node families · governance Ten representative module families: N31–N40. Full contracts are below the diagram. Vector diagram · click a marked item to inspect Node families: Governance Diagram: Node families: Governance NODE = family + facets + owned ports + profile + source / activation identity A family is a descriptor contribution, not a new kernel subclass. Select a card for its full contract. N31 Schema / contract definition Record, protocol, resource ABI in: versioned definition out: descriptor Represent as a node when independently referenced; otherwise keep it a typed… N32 Capability offer / requirement Offline ranker, GPU offer in: constraints out: eligible offers Availability and suitability do not confer authority; selection is context-scoped. N33 Policy / principal boundary Grant evaluator, tenant scope in: subject, action out: decision Secrets stay out of graph payloads; current effect-time authority is rechecked. N34 Build / compiler pass Typecheck, lower, package in: source, dependencies out: artifact, findings Key caches by semantic inputs and toolchain; preserve source maps and qualification… N35 Artifact / release manifest Signed region bundle, runtime image in: content refs out: digest, manifest Stable identity differs from content digest; exclude cosmetic layout from semantic… N36 Test / Shadow scenario Fault replay, baseline/candidate in: pinned candidate, fixture out: evidence Record assumptions, capture gaps and runner; no generic green-check guarantee. N37 Claim / evidence record Protocol claim, performance run in: subject, results out: attestation Evidence is claim-indexed, not a universal ordered strength score. N38 Observer / query / visitor Inspector, trace lens, analysis in: selector, snapshot out: finding, view Inspection cannot mutate implicitly; coverage and authority limit conclusions. N39 Agent / change proposer Planner, coding harness, reviewer in: task, scoped context out: typed patch Drafts are not deployment; effective tool/OS authority must be controlled or… N40 Deployment / migration controller Rollout, drain, state transfer in: release intent out: receipt, observed state Durable reconciliation; monotonic fencing epochs and explicit mixed-version policy. Orthogonal facets include effects, lifecycle, tenancy, placement, observability, mutability and update policy. ## Reaktor design decision Section ID: reaktor-design-decision-3 Reaktor design decision Keep stable entity identity and owned ports in the kernel; register domain families through versioned descriptors. Use typed facets for orthogonal concerns instead of a class hierarchy explosion. ## Boundary / caveat Section ID: boundary--caveat-3 Boundary / caveat These categories overlap. A native inference service can combine resource, operation and model facets; a property is not automatically a separate node. Qualification test. Register a new domain family without changing the graph kernel, while unsupported required behavior still blocks activation. N31 · Schema / contract definition Example / shape: Record, protocol, resource ABI Contract: Represent as a node when independently referenced; otherwise keep it a typed value/facet. proposed family; module-extensible N32 · Capability offer / requirement Example / shape: Offline ranker, GPU offer Contract: Availability and suitability do not confer authority; selection is context-scoped. proposed family; module-extensible N33 · Policy / principal boundary Example / shape: Grant evaluator, tenant scope Contract: Secrets stay out of graph payloads; current effect-time authority is rechecked. proposed family; module-extensible N34 · Build / compiler pass Example / shape: Typecheck, lower, package Contract: Key caches by semantic inputs and toolchain; preserve source maps and qualification profile. proposed family; module-extensible N35 · Artifact / release manifest Example / shape: Signed region bundle, runtime image Contract: Stable identity differs from content digest; exclude cosmetic layout from semantic identity. proposed family; module-extensible N36 · Test / Shadow scenario Example / shape: Fault replay, baseline/candidate Contract: Record assumptions, capture gaps and runner; no generic green-check guarantee. proposed family; module-extensible N37 · Claim / evidence record Example / shape: Protocol claim, performance run Contract: Evidence is claim-indexed, not a universal ordered strength score. proposed family; module-extensible N38 · Observer / query / visitor Example / shape: Inspector, trace lens, analysis Contract: Inspection cannot mutate implicitly; coverage and authority limit conclusions. proposed family; module-extensible N39 · Agent / change proposer Example / shape: Planner, coding harness, reviewer Contract: Drafts are not deployment; effective tool/OS authority must be controlled or disclosed. proposed family; module-extensible N40 · Deployment / migration controller Example / shape: Rollout, drain, state transfer Contract: Durable reconciliation; monotonic fencing epochs and explicit mixed-version policy. proposed family; module-extensible Official context and precedents: Reaktor Visual Language / Blueprints Reaktor Living Graph ## Diagram inspection notes Section ID: diagram-inspection-notes-3 Diagram inspection notes N31 · Schema / contract definition: Represent as a node when independently referenced; otherwise keep it a typed value/facet. N32 · Capability offer / requirement: Availability and suitability do not confer authority; selection is context-scoped. N33 · Policy / principal boundary: Secrets stay out of graph payloads; current effect-time authority is rechecked. N34 · Build / compiler pass: Key caches by semantic inputs and toolchain; preserve source maps and qualification profile. N35 · Artifact / release manifest: Stable identity differs from content digest; exclude cosmetic layout from semantic identity. N36 · Test / Shadow scenario: Record assumptions, capture gaps and runner; no generic green-check guarantee. N37 · Claim / evidence record: Evidence is claim-indexed, not a universal ordered strength score. N38 · Observer / query / visitor: Inspection cannot mutate implicitly; coverage and authority limit conclusions. N39 · Agent / change proposer: Drafts are not deployment; effective tool/OS authority must be controlled or disclosed. N40 · Deployment / migration controller: Durable reconciliation; monotonic fencing epochs and explicit mixed-version policy. ## Port profiles · values & interaction Section ID: panel-ports-1 Port profiles · values & interaction Payload typing is necessary but insufficient: the interaction, ownership and outcome contracts travel with it. Vector diagram · click a marked item to inspect Port profiles: Values & interaction Diagram: Port profiles: Values & interaction PORT = schema × protocol × role × cardinality × lifetime × effects × authority × target These are composable profiles. The product is constrained: many trait combinations are deliberately illegal. P01 Value / immutable snapshot Out → In Schema, nullability, units and representation matter;… P02 Request / response Require ↔ Provide Direction is a role; sync/async, error and timeout… P03 Durable command / receipt Submit → Receipt Receipt names the qualified completion stage, not simply… P04 Push event EventOut → EventIn Declare ordering, overflow, replay and delivery… P05 Pull iterator / cursor Next → Item|End Cursor lifetime, backpressure, consistency cut and… P06 Credit-controlled stream Stream + Request(n) Demand, buffer bounds, terminal events and cancellation… P07 Duplex session Session Both endpoints follow the protocol; pin session version… P08 Signal / reactive state Signal Distinguish latest-value conflation from delivery of… P09 Mutation / conditional update Update The authority checks predicates and authorization; local… P10 Transaction participant Participant Only qualified participants enlist; a transaction token… P11 Execution / continuation ExecIn → ExecOut Defines effect order within one execution profile; not a… P12 Branch / guarded transition Case / Event[Guard] Exhaustiveness and guard purity are checked; branch… A port is an owned semantic boundary. In/out drawing positions are not a substitute for protocol-role compatibility. ## Reaktor design decision Section ID: reaktor-design-decision-4 Reaktor design decision Generate codecs, façades, palette constraints and runtime validation from one port descriptor. Keep required capabilities distinct from authorization grants. ## Boundary / caveat Section ID: boundary--caveat-4 Boundary / caveat Schema-compatible values can still violate lifetime, delivery, affinity, timing or authority. Do not flatten all ports to function signatures or untyped event messages. Qualification test. Reject a borrowed native buffer sent beyond its lease or address space; offer a qualified copy/transfer adapter rather than silently accepting it. P01 · Value / immutable snapshot Example / shape: Out → In Contract: Schema, nullability, units and representation matter; value flow alone imposes no effect order. proposed profile; composable traits P02 · Request / response Example / shape: Require ↔ Provide Contract: Direction is a role; sync/async, error and timeout outcomes are part of compatibility. proposed profile; composable traits P03 · Durable command / receipt Example / shape: Submit → Receipt Contract: Receipt names the qualified completion stage, not simply receipt of bytes. proposed profile; composable traits P04 · Push event Example / shape: EventOut → EventIn Contract: Declare ordering, overflow, replay and delivery guarantee; not implicitly durable. proposed profile; composable traits P05 · Pull iterator / cursor Example / shape: Next → Item|End Contract: Cursor lifetime, backpressure, consistency cut and resume behavior are explicit. proposed profile; composable traits P06 · Credit-controlled stream Example / shape: Stream + Request(n) Contract: Demand, buffer bounds, terminal events and cancellation must agree across the boundary. proposed profile; composable traits P07 · Duplex session Example / shape: Session Contract: Both endpoints follow the protocol; pin session version and handoff semantics. proposed profile; composable traits P08 · Signal / reactive state Example / shape: Signal Contract: Distinguish latest-value conflation from delivery of every historical change. proposed profile; composable traits P09 · Mutation / conditional update Example / shape: Update Contract: The authority checks predicates and authorization; local write locks are not distributed CAS. proposed profile; composable traits P10 · Transaction participant Example / shape: Participant Contract: Only qualified participants enlist; a transaction token is not universal ACID. proposed profile; composable traits P11 · Execution / continuation Example / shape: ExecIn → ExecOut Contract: Defines effect order within one execution profile; not a generic network message. proposed profile; composable traits P12 · Branch / guarded transition Example / shape: Case / Event[Guard] Contract: Exhaustiveness and guard purity are checked; branch choice is separate from data encoding. proposed profile; composable traits Official context and precedents: Reaktor FFI / Switchboard XState actor semantics Expo runtime versions and updates ## Diagram inspection notes Section ID: diagram-inspection-notes-4 Diagram inspection notes P01 · Value / immutable snapshot: Schema, nullability, units and representation matter; value flow alone imposes no effect order. P02 · Request / response: Direction is a role; sync/async, error and timeout outcomes are part of compatibility. P03 · Durable command / receipt: Receipt names the qualified completion stage, not simply receipt of bytes. P04 · Push event: Declare ordering, overflow, replay and delivery guarantee; not implicitly durable. P05 · Pull iterator / cursor: Cursor lifetime, backpressure, consistency cut and resume behavior are explicit. P06 · Credit-controlled stream: Demand, buffer bounds, terminal events and cancellation must agree across the boundary. P07 · Duplex session: Both endpoints follow the protocol; pin session version and handoff semantics. P08 · Signal / reactive state: Distinguish latest-value conflation from delivery of every historical change. P09 · Mutation / conditional update: The authority checks predicates and authorization; local write locks are not distributed CAS. P10 · Transaction participant: Only qualified participants enlist; a transaction token is not universal ACID. P11 · Execution / continuation: Defines effect order within one execution profile; not a generic network message. P12 · Branch / guarded transition: Exhaustiveness and guard purity are checked; branch choice is separate from data encoding. ## Port profiles · lifetime & control Section ID: panel-ports-2 Port profiles · lifetime & control Payload typing is necessary but insufficient: the interaction, ownership and outcome contracts travel with it. Vector diagram · click a marked item to inspect Port profiles: Lifetime & control Diagram: Port profiles: Lifetime & control PORT = schema × protocol × role × cardinality × lifetime × effects × authority × target These are composable profiles. The product is constrained: many trait combinations are deliberately illegal. P13 Completion / join token Done Join rule defines required contributors and treatment of… P14 Cancellation / deadline Cancel Cancellation is cooperative unless stated otherwise;… P15 Clock / tick / timer Tick Specify event-time versus processing-time semantics;… P16 Owned resource transfer Owned Exactly one accepted owner after transfer; reject… P17 Borrowed buffer / view Borrow Cannot escape its declared scope; async and… P18 Shared read lease SharedRead Reference counting alone does not make concurrent… P19 Capability descriptor Offer / Require Metadata for selection, not an authorization bearer; no… P20 Authorization request / grant Authorize Bind principal, scope, expiry and issuer; recheck at use… P21 Lifecycle management Prepare / Activate / Drain / Release Calls may fail or be skipped on host death; required… P22 Checkpoint / migration Snapshot → Restore Migration is versioned and staged; rollback depends on… P23 Artifact / schema reference Ref A reference is not a raw pointer; loading verifies… P24 Inspection / evidence Observe → Finding Carries coverage and provenance; observational access… A port is an owned semantic boundary. In/out drawing positions are not a substitute for protocol-role compatibility. ## Reaktor design decision Section ID: reaktor-design-decision-5 Reaktor design decision Generate codecs, façades, palette constraints and runtime validation from one port descriptor. Keep required capabilities distinct from authorization grants. ## Boundary / caveat Section ID: boundary--caveat-5 Boundary / caveat Schema-compatible values can still violate lifetime, delivery, affinity, timing or authority. Do not flatten all ports to function signatures or untyped event messages. Qualification test. Reject a borrowed native buffer sent beyond its lease or address space; offer a qualified copy/transfer adapter rather than silently accepting it. P13 · Completion / join token Example / shape: Done Contract: Join rule defines required contributors and treatment of failure/cancellation. proposed profile; composable traits P14 · Cancellation / deadline Example / shape: Cancel Contract: Cancellation is cooperative unless stated otherwise; reconcile already-committed effects. proposed profile; composable traits P15 · Clock / tick / timer Example / shape: Tick Contract: Specify event-time versus processing-time semantics; clocks are dependencies for replay. proposed profile; composable traits P16 · Owned resource transfer Example / shape: Owned Contract: Exactly one accepted owner after transfer; reject duplication and invalid module epoch. proposed profile; composable traits P17 · Borrowed buffer / view Example / shape: Borrow Contract: Cannot escape its declared scope; async and cross-address-space use require a qualified lease/copy. proposed profile; composable traits P18 · Shared read lease Example / shape: SharedRead Contract: Reference counting alone does not make concurrent mutation safe; memory rules stay explicit. proposed profile; composable traits P19 · Capability descriptor Example / shape: Offer / Require Contract: Metadata for selection, not an authorization bearer; no implied access to the capability. proposed profile; composable traits P20 · Authorization request / grant Example / shape: Authorize Contract: Bind principal, scope, expiry and issuer; recheck at use and never serialize raw credentials. proposed profile; composable traits P21 · Lifecycle management Example / shape: Prepare / Activate / Drain / Release Contract: Calls may fail or be skipped on host death; required persistence cannot rely on cleanup. proposed profile; composable traits P22 · Checkpoint / migration Example / shape: Snapshot → Restore Contract: Migration is versioned and staged; rollback depends on state compatibility, not old code availability. proposed profile; composable traits P23 · Artifact / schema reference Example / shape: Ref Contract: A reference is not a raw pointer; loading verifies integrity, provenance and access. proposed profile; composable traits P24 · Inspection / evidence Example / shape: Observe → Finding Contract: Carries coverage and provenance; observational access does not confer mutation authority. proposed profile; composable traits Official context and precedents: Reaktor FFI / Switchboard XState actor semantics Expo runtime versions and updates ## Diagram inspection notes Section ID: diagram-inspection-notes-5 Diagram inspection notes P13 · Completion / join token: Join rule defines required contributors and treatment of failure/cancellation. P14 · Cancellation / deadline: Cancellation is cooperative unless stated otherwise; reconcile already-committed effects. P15 · Clock / tick / timer: Specify event-time versus processing-time semantics; clocks are dependencies for replay. P16 · Owned resource transfer: Exactly one accepted owner after transfer; reject duplication and invalid module epoch. P17 · Borrowed buffer / view: Cannot escape its declared scope; async and cross-address-space use require a qualified lease/copy. P18 · Shared read lease: Reference counting alone does not make concurrent mutation safe; memory rules stay explicit. P19 · Capability descriptor: Metadata for selection, not an authorization bearer; no implied access to the capability. P20 · Authorization request / grant: Bind principal, scope, expiry and issuer; recheck at use and never serialize raw credentials. P21 · Lifecycle management: Calls may fail or be skipped on host death; required persistence cannot rely on cleanup. P22 · Checkpoint / migration: Migration is versioned and staged; rollback depends on state compatibility, not old code availability. P23 · Artifact / schema reference: A reference is not a raw pointer; loading verifies integrity, provenance and access. P24 · Inspection / evidence: Carries coverage and provenance; observational access does not confer mutation authority. ## Hyperedge patterns · flow & coordination Section ID: panel-relations-1 Hyperedge patterns · flow & coordination Role-labelled relations retain the identity and meaning of n-ary interactions. Vector diagram · click a marked item to inspect Hyperedge patterns: Flow & coordination Diagram: Hyperedge patterns: Flow & coordination HYPEREDGE = roles + per-role cardinality + laws + layer + optional execution interpretation The oval is a relation identity. It does not secretly create a coordinator, queue, transaction manager or consensus engine. H01 Exclusive binding consumer:1 provider:1 H01 Reject a second provider where exclusivity is… H02 Value flow source:1 sink:1..N H02 Copy/fanout is legal only for the value ownership… H03 Control precedence before:1..N after:1..N H03 Defines ordering under a named profile; does not… H04 Event subscription publisher:1..N subscriber:1..N H04 Subscriptions name filters, replay and delivery rules;… H05 Request / reply binding caller:1 callee:1 reply:0..1 H05 Protocol includes correlation, failure and unknown… H06 Multiparty session authority:1 participant:1..N observer:0..N H06 Single relation identity with role/cardinality checks;… H07 Broadcast / fanout producer:1 consumer:1..N H07 State whether delivery waits for all, any or no… H08 Merge-any producer:1..N consumer:1 H08 Specify interleaving, fairness and order; merging is… H09 Join-all input:2..N result:1 H09 Align values by invocation/key; define failure,… H10 Race / select contender:2..N winner:1 H10 Define first-completion versus first-success and… H11 Keyed temporal join left:1 right:1..N result:1 H11 State key, clock, lateness/watermark and window… H12 Barrier / synchronization member:2..N continuation:1 H12 Specify membership epoch, arrival condition and… Binary edges are specializations; metadata constraints can add participants. Cardinality and laws are checked on the complete relation. ## Reaktor design decision Section ID: reaktor-design-decision-6 Reaktor design decision Store each relationship once with typed incidences. Keep pure structural, constraint, evidence and executable layers distinguishable in queries and views. ## Boundary / caveat Section ID: boundary--caveat-6 Boundary / caveat A hyperedge records a contract and relation. Atomicity, quorum agreement, stream alignment or access enforcement must come from an actual qualified implementation. Qualification test. Inspect an n-party relationship without replacing it with an arbitrary clique of unrelated binary links; reject invalid role cardinalities. H01 · Exclusive binding Example / shape: consumer:1 • provider:1 Contract: Reject a second provider where exclusivity is required; dispatch can compile to a direct call. proposed relation schema; not an execution primitive by default H02 · Value flow Example / shape: source:1 • sink:1..N Contract: Copy/fanout is legal only for the value ownership profile; units and schemas must match. proposed relation schema; not an execution primitive by default H03 · Control precedence Example / shape: before:1..N • after:1..N Contract: Defines ordering under a named profile; does not serialize unrelated graph layers. proposed relation schema; not an execution primitive by default H04 · Event subscription Example / shape: publisher:1..N • subscriber:1..N Contract: Subscriptions name filters, replay and delivery rules; broker resources remain separate nodes. proposed relation schema; not an execution primitive by default H05 · Request / reply binding Example / shape: caller:1 • callee:1 • reply:0..1 Contract: Protocol includes correlation, failure and unknown outcomes; transport is chosen independently. proposed relation schema; not an execution primitive by default H06 · Multiparty session Example / shape: authority:1 • participant:1..N • observer:0..N Contract: Single relation identity with role/cardinality checks; delivery comes from an explicit protocol. proposed relation schema; not an execution primitive by default H07 · Broadcast / fanout Example / shape: producer:1 • consumer:1..N Contract: State whether delivery waits for all, any or no receivers; slow receivers need a policy. proposed relation schema; not an execution primitive by default H08 · Merge-any Example / shape: producer:1..N • consumer:1 Contract: Specify interleaving, fairness and order; merging is not a join of corresponding values. proposed relation schema; not an execution primitive by default H09 · Join-all Example / shape: input:2..N • result:1 Contract: Align values by invocation/key; define failure, timeout and missing-input treatment. proposed relation schema; not an execution primitive by default H10 · Race / select Example / shape: contender:2..N • winner:1 Contract: Define first-completion versus first-success and cleanup/reconciliation of losing effects. proposed relation schema; not an execution primitive by default H11 · Keyed temporal join Example / shape: left:1 • right:1..N • result:1 Contract: State key, clock, lateness/watermark and window policy; topology alone cannot pair records. proposed relation schema; not an execution primitive by default H12 · Barrier / synchronization Example / shape: member:2..N • continuation:1 Contract: Specify membership epoch, arrival condition and failure handling; no hidden global clock. proposed relation schema; not an execution primitive by default Official context and precedents: Reaktor Living Graph Reaktor Visual Language / Blueprints ## Diagram inspection notes Section ID: diagram-inspection-notes-6 Diagram inspection notes H01 · Exclusive binding | consumer:1, provider:1 | Reject a second provider where exclusivity is required; dispatch can compile to a direct call. H02 · Value flow | source:1, sink:1..N | Copy/fanout is legal only for the value ownership profile; units and schemas must match. H03 · Control precedence | before:1..N, after:1..N | Defines ordering under a named profile; does not serialize unrelated graph layers. H04 · Event subscription | publisher:1..N, subscriber:1..N | Subscriptions name filters, replay and delivery rules; broker resources remain separate nodes. H05 · Request / reply binding | caller:1, callee:1, reply:0..1 | Protocol includes correlation, failure and unknown outcomes; transport is chosen independently. H06 · Multiparty session | authority:1, participant:1..N, observer:0..N | Single relation identity with role/cardinality checks; delivery comes from an explicit protocol. H07 · Broadcast / fanout | producer:1, consumer:1..N | State whether delivery waits for all, any or no receivers; slow receivers need a policy. H08 · Merge-any | producer:1..N, consumer:1 | Specify interleaving, fairness and order; merging is not a join of corresponding values. H09 · Join-all | input:2..N, result:1 | Align values by invocation/key; define failure, timeout and missing-input treatment. H10 · Race / select | contender:2..N, winner:1 | Define first-completion versus first-success and cleanup/reconciliation of losing effects. H11 · Keyed temporal join | left:1, right:1..N, result:1 | State key, clock, lateness/watermark and window policy; topology alone cannot pair records. H12 · Barrier / synchronization | member:2..N, continuation:1 | Specify membership epoch, arrival condition and failure handling; no hidden global clock. ## Hyperedge patterns · state & structure Section ID: panel-relations-2 Hyperedge patterns · state & structure Role-labelled relations retain the identity and meaning of n-ary interactions. Vector diagram · click a marked item to inspect Hyperedge patterns: State & structure Diagram: Hyperedge patterns: State & structure HYPEREDGE = roles + per-role cardinality + laws + layer + optional execution interpretation The oval is a relation identity. It does not secretly create a coordinator, queue, transaction manager or consensus engine. H13 Quorum requirement proposer:1 voter:1..N result:1 H13 Names a qualified protocol and membership; counting… H14 Replica group authority:0..1 replica:1..N H14 Replication/merge and fencing rules are explicit;… H15 Partition / route router:1 shard:1..N H15 Specify key function, assignment epoch and resharding;… H16 Atomic authority scope authority:1 participant:1..N H16 ACID applies only where that authority/profile… H17 Compensation relation forward:1 compensator:1..N H17 Compensation is a new effect with its own failure… H18 Supervision supervisor:1 child:1..N H18 Specify restart budget, state/ownership effects and… H19 Ownership / containment owner:1 owned:1..N H19 Selected ownership relation is acyclic; visual… H20 Instantiation definition:1 instance:1..N H20 Fresh activation identities and scopes; shared… H21 Placement component:1..N host:1..N H21 A plan expresses intended placement; observations… H22 Affinity / separation member:2..N constraint:1 H22 Co-location, anti-affinity or memory-domain rule is a… H23 Scoped authorization principal:1 resource:1..N policy:1 H23 Decision is tied to action/context; visual… H24 Capability resolution requirement:1 offer:1..N decision:1 H24 Filter hard constraints and grants before preferences;… Binary edges are specializations; metadata constraints can add participants. Cardinality and laws are checked on the complete relation. ## Reaktor design decision Section ID: reaktor-design-decision-7 Reaktor design decision Store each relationship once with typed incidences. Keep pure structural, constraint, evidence and executable layers distinguishable in queries and views. ## Boundary / caveat Section ID: boundary--caveat-7 Boundary / caveat A hyperedge records a contract and relation. Atomicity, quorum agreement, stream alignment or access enforcement must come from an actual qualified implementation. Qualification test. Inspect an n-party relationship without replacing it with an arbitrary clique of unrelated binary links; reject invalid role cardinalities. H13 · Quorum requirement Example / shape: proposer:1 • voter:1..N • result:1 Contract: Names a qualified protocol and membership; counting votes alone does not implement consensus. proposed relation schema; not an execution primitive by default H14 · Replica group Example / shape: authority:0..1 • replica:1..N Contract: Replication/merge and fencing rules are explicit; schema does not create consistency. proposed relation schema; not an execution primitive by default H15 · Partition / route Example / shape: router:1 • shard:1..N Contract: Specify key function, assignment epoch and resharding; preserve owner and replay semantics. proposed relation schema; not an execution primitive by default H16 · Atomic authority scope Example / shape: authority:1 • participant:1..N Contract: ACID applies only where that authority/profile implements it; not across arbitrary stores. proposed relation schema; not an execution primitive by default H17 · Compensation relation Example / shape: forward:1 • compensator:1..N Contract: Compensation is a new effect with its own failure modes, not automatic historical erasure. proposed relation schema; not an execution primitive by default H18 · Supervision Example / shape: supervisor:1 • child:1..N Contract: Specify restart budget, state/ownership effects and host-death behavior. proposed relation schema; not an execution primitive by default H19 · Ownership / containment Example / shape: owner:1 • owned:1..N Contract: Selected ownership relation is acyclic; visual grouping is not ownership. proposed relation schema; not an execution primitive by default H20 · Instantiation Example / shape: definition:1 • instance:1..N Contract: Fresh activation identities and scopes; shared definitions are not shared mutable instance state. proposed relation schema; not an execution primitive by default H21 · Placement Example / shape: component:1..N • host:1..N Contract: A plan expresses intended placement; observations separately establish what actually runs. proposed relation schema; not an execution primitive by default H22 · Affinity / separation Example / shape: member:2..N • constraint:1 Contract: Co-location, anti-affinity or memory-domain rule is a constraint, not an executable wire. proposed relation schema; not an execution primitive by default H23 · Scoped authorization Example / shape: principal:1 • resource:1..N • policy:1 Contract: Decision is tied to action/context; visual reachability neither proves nor grants access. proposed relation schema; not an execution primitive by default H24 · Capability resolution Example / shape: requirement:1 • offer:1..N • decision:1 Contract: Filter hard constraints and grants before preferences; pin or safely migrate running sessions. proposed relation schema; not an execution primitive by default Official context and precedents: Reaktor Living Graph Reaktor Visual Language / Blueprints ## Diagram inspection notes Section ID: diagram-inspection-notes-7 Diagram inspection notes H13 · Quorum requirement | proposer:1, voter:1..N, result:1 | Names a qualified protocol and membership; counting votes alone does not implement consensus. H14 · Replica group | authority:0..1, replica:1..N | Replication/merge and fencing rules are explicit; schema does not create consistency. H15 · Partition / route | router:1, shard:1..N | Specify key function, assignment epoch and resharding; preserve owner and replay semantics. H16 · Atomic authority scope | authority:1, participant:1..N | ACID applies only where that authority/profile implements it; not across arbitrary stores. H17 · Compensation relation | forward:1, compensator:1..N | Compensation is a new effect with its own failure modes, not automatic historical erasure. H18 · Supervision | supervisor:1, child:1..N | Specify restart budget, state/ownership effects and host-death behavior. H19 · Ownership / containment | owner:1, owned:1..N | Selected ownership relation is acyclic; visual grouping is not ownership. H20 · Instantiation | definition:1, instance:1..N | Fresh activation identities and scopes; shared definitions are not shared mutable instance state. H21 · Placement | component:1..N, host:1..N | A plan expresses intended placement; observations separately establish what actually runs. H22 · Affinity / separation | member:2..N, constraint:1 | Co-location, anti-affinity or memory-domain rule is a constraint, not an executable wire. H23 · Scoped authorization | principal:1, resource:1..N, policy:1 | Decision is tied to action/context; visual reachability neither proves nor grants access. H24 · Capability resolution | requirement:1, offer:1..N, decision:1 | Filter hard constraints and grants before preferences; pin or safely migrate running sessions. ## Hyperedge patterns · meaning & change Section ID: panel-relations-3 Hyperedge patterns · meaning & change Role-labelled relations retain the identity and meaning of n-ary interactions. Vector diagram · click a marked item to inspect Hyperedge patterns: Meaning & change Diagram: Hyperedge patterns: Meaning & change HYPEREDGE = roles + per-role cardinality + laws + layer + optional execution interpretation The oval is a relation identity. It does not secretly create a coordinator, queue, transaction manager or consensus engine. H25 Implements / source ownership source:1 contract:1..N region:1 H25 Exactly one edit authority per region; generated… H26 Artifact dependency consumer:1 dependency:1..N H26 Pin semantic/artifact revisions; cosmetic layout… H27 Derivation / provenance input:1..N transform:1 output:1..N H27 Results carry input cut and transform version; unknown… H28 Evidence supports claim claim:1 evidence:1..N verifier:1..N H28 Scope assumptions and coverage; evidence does not… H29 Activation cohort release:1 image:1..N localRoot:1 H29 Local root publication can be atomic; cross-host… H30 Boundary export / alias internal:1..N external:1..N H30 Preserve role, ownership and protocol when… H31 Clock / time alignment clock:1..N stream:1..N H31 Alignment needs a defined transform/uncertainty;… H32 Tensor / algebraic operation operand:1..N operator:1 result:1..N H32 Validate axes, units and device layout; computation… H33 Fallback / preference set requirement:1 alternative:1..N H33 Fallbacks must remain eligible and authorized; never… H34 Data access / lineage operation:1 store:1..N schema:1..N H34 Records the modeled access scope; enforce at actual… H35 State migration oldState:1 migrator:1 newState:1 H35 Version checkpoints, fence writers and validate… H36 Navigation / interaction route origin:1 intent:1 destination:1..N H36 Choose destination with guards and grants; back-stack… Binary edges are specializations; metadata constraints can add participants. Cardinality and laws are checked on the complete relation. ## Reaktor design decision Section ID: reaktor-design-decision-8 Reaktor design decision Store each relationship once with typed incidences. Keep pure structural, constraint, evidence and executable layers distinguishable in queries and views. ## Boundary / caveat Section ID: boundary--caveat-8 Boundary / caveat A hyperedge records a contract and relation. Atomicity, quorum agreement, stream alignment or access enforcement must come from an actual qualified implementation. Qualification test. Inspect an n-party relationship without replacing it with an arbitrary clique of unrelated binary links; reject invalid role cardinalities. H25 · Implements / source ownership Example / shape: source:1 • contract:1..N • region:1 Contract: Exactly one edit authority per region; generated projections are not independently editable truth. proposed relation schema; not an execution primitive by default H26 · Artifact dependency Example / shape: consumer:1 • dependency:1..N Contract: Pin semantic/artifact revisions; cosmetic layout changes need not invalidate code. proposed relation schema; not an execution primitive by default H27 · Derivation / provenance Example / shape: input:1..N • transform:1 • output:1..N Contract: Results carry input cut and transform version; unknown dependencies widen invalidation. proposed relation schema; not an execution primitive by default H28 · Evidence supports claim Example / shape: claim:1 • evidence:1..N • verifier:1..N Contract: Scope assumptions and coverage; evidence does not promote or authorize itself. proposed relation schema; not an execution primitive by default H29 · Activation cohort Example / shape: release:1 • image:1..N • localRoot:1 Contract: Local root publication can be atomic; cross-host realization is recoverable coordination. proposed relation schema; not an execution primitive by default H30 · Boundary export / alias Example / shape: internal:1..N • external:1..N Contract: Preserve role, ownership and protocol when hiding/expanding a reusable region. proposed relation schema; not an execution primitive by default H31 · Clock / time alignment Example / shape: clock:1..N • stream:1..N Contract: Alignment needs a defined transform/uncertainty; timestamps do not establish causal order. proposed relation schema; not an execution primitive by default H32 · Tensor / algebraic operation Example / shape: operand:1..N • operator:1 • result:1..N Contract: Validate axes, units and device layout; computation belongs to the qualified implementation. proposed relation schema; not an execution primitive by default H33 · Fallback / preference set Example / shape: requirement:1 • alternative:1..N Contract: Fallbacks must remain eligible and authorized; never silently relax mandatory privacy or safety. proposed relation schema; not an execution primitive by default H34 · Data access / lineage Example / shape: operation:1 • store:1..N • schema:1..N Contract: Records the modeled access scope; enforce at actual storage boundary and disclose opaque access. proposed relation schema; not an execution primitive by default H35 · State migration Example / shape: oldState:1 • migrator:1 • newState:1 Contract: Version checkpoints, fence writers and validate postconditions; inverse may not exist. proposed relation schema; not an execution primitive by default H36 · Navigation / interaction route Example / shape: origin:1 • intent:1 • destination:1..N Contract: Choose destination with guards and grants; back-stack and cancellation semantics are explicit. proposed relation schema; not an execution primitive by default Official context and precedents: Reaktor Living Graph Reaktor Visual Language / Blueprints ## Diagram inspection notes Section ID: diagram-inspection-notes-8 Diagram inspection notes H25 · Implements / source ownership | source:1, contract:1..N, region:1 | Exactly one edit authority per region; generated projections are not independently editable truth. H26 · Artifact dependency | consumer:1, dependency:1..N | Pin semantic/artifact revisions; cosmetic layout changes need not invalidate code. H27 · Derivation / provenance | input:1..N, transform:1, output:1..N | Results carry input cut and transform version; unknown dependencies widen invalidation. H28 · Evidence supports claim | claim:1, evidence:1..N, verifier:1..N | Scope assumptions and coverage; evidence does not promote or authorize itself. H29 · Activation cohort | release:1, image:1..N, localRoot:1 | Local root publication can be atomic; cross-host realization is recoverable coordination. H30 · Boundary export / alias | internal:1..N, external:1..N | Preserve role, ownership and protocol when hiding/expanding a reusable region. H31 · Clock / time alignment | clock:1..N, stream:1..N | Alignment needs a defined transform/uncertainty; timestamps do not establish causal order. H32 · Tensor / algebraic operation | operand:1..N, operator:1, result:1..N | Validate axes, units and device layout; computation belongs to the qualified implementation. H33 · Fallback / preference set | requirement:1, alternative:1..N | Fallbacks must remain eligible and authorized; never silently relax mandatory privacy or safety. H34 · Data access / lineage | operation:1, store:1..N, schema:1..N | Records the modeled access scope; enforce at actual storage boundary and disclose opaque access. H35 · State migration | oldState:1, migrator:1, newState:1 | Version checkpoints, fence writers and validate postconditions; inverse may not exist. H36 · Navigation / interaction route | origin:1, intent:1, destination:1..N | Choose destination with guards and grants; back-stack and cancellation semantics are explicit. ## Node, port and hyperedge catalog Section ID: panel-vocabulary Node, port and hyperedge catalog 40 node families, 24 port profiles and 36 hyperedge patterns. This is a starter catalog, not a finite claim to exhaust all possible domain types. node N01 · Pure computation Shape: Map, hash, score, validate Law / obligation: No hidden effects; cache only against declared inputs and semantic version. proposed family; module-extensible node N02 · Effectful operation Shape: Send, reserve, write, invoke Law / obligation: Effects and required grants are explicit; timeout does not imply no effect. proposed family; module-extensible node N03 · Decision / pattern match Shape: Guard, switch, eligibility Law / obligation: Define exhaustive cases and defaults; guards are pure in the selected profile. proposed family; module-extensible node N04 · Loop / recursive region Shape: Fold, iterate, call itself Law / obligation: Specify continuation/state semantics and resource budgets; a cycle is not a schedule. proposed family; module-extensible node N05 · Actor / statechart Shape: Session, cart, connection Law / obligation: Owns state and event ordering; hierarchy does not itself provide durability. proposed family; module-extensible node N06 · Workflow / saga Shape: Checkout, onboarding, import Law / obligation: Version durable continuations; make retries, unknown results and compensation explicit. proposed family; module-extensible node N07 · Stream operator Shape: Filter, window, resample Law / obligation: Specify demand, buffering, event-time policy, loss and cancellation. proposed family; module-extensible node N08 · Fork / join / scheduler Shape: Parallel tasks, join, race Law / obligation: Choose all/any/quorum semantics, including failure and abandoned branches. proposed family; module-extensible node N09 · Timer / clock source Shape: Deadline, interval, logical tick Law / obligation: Distinguish logical, event and wall clocks; inject clocks for replay. proposed family; module-extensible node N10 · Function / blueprint region Shape: Reusable feature, generic subgraph Law / obligation: Stable exported interface; instantiate fresh owned state, not copied global identity. proposed family; module-extensible node N11 · Surface / view component Shape: Screen, card, scene overlay Law / obligation: Interaction semantics are shared; native renderer behavior is qualified separately. proposed family; module-extensible node N12 · Route / navigation Shape: Deep link, page, modal Law / obligation: Make route state, permissions and unsupported destinations explicit. proposed family; module-extensible node N13 · Input / interaction source Shape: Gesture, keyboard, controller Law / obligation: Declare focus, sampling, ordering and host lifecycle behavior. proposed family; module-extensible node N14 · Form / validation region Shape: Address form, editor inspector Law / obligation: Keep draft/invalid state saveable; effects require separately accepted values. proposed family; module-extensible node N15 · Device / platform adapter Shape: Camera, GPS, clipboard Law / obligation: Native implementation is bounded by OS permissions, affinity and installed capabilities. proposed family; module-extensible node N16 · Native resource / engine Shape: Map SDK, Unity, Unreal, codec Law / obligation: Resource owner and release callback survive async calls; opaque internals stay declared. proposed family; module-extensible node N17 · Media transform Shape: Crop, encode, render, mix Law / obligation: Specify memory domain, mutability, format and synchronization; zero-copy is conditional. proposed family; module-extensible node N18 · Model inference Shape: Ranker, speech, embedding Law / obligation: Pin model artifact and preprocessing; quality requires task-specific evidence. proposed family; module-extensible node N19 · Tool / external API adapter Shape: Geocoder, payments, search Law / obligation: Treat credentials and external outcomes separately from local graph transactions. proposed family; module-extensible node N20 · Human decision / approval Shape: Review, moderation, release signoff Law / obligation: Human identity, scope, policy version and expiry are part of the decision. proposed family; module-extensible node N21 · Database / state authority Shape: Postgres, SQLite, KV authority Law / obligation: Actual store profile determines isolation and durability; rows are not architecture nodes. proposed family; module-extensible node N22 · Query / materialized view Shape: Projection, lookup, aggregate Law / obligation: Declare source cut, freshness and dependency coverage; no unsound negative inference. proposed family; module-extensible node N23 · Transaction / unit of work Shape: Graph commit, local outbox Law / obligation: Atomicity applies only to the named authority and enlisted qualified resources. proposed family; module-extensible node N24 · Queue / log / pubsub resource Shape: Topic, task queue, event journal Law / obligation: Delivery, retention, offset, deduplication and redelivery laws belong to the provider. proposed family; module-extensible node N25 · Cache / replica / sync agent Shape: Local-first replica, CDN cache Law / obligation: Specify merge/conflict policy and deletion semantics; not every invariant permits CRDT merge. proposed family; module-extensible node N26 · Blob / buffer / asset store Shape: Images, model weights, snapshots Law / obligation: Graph stores descriptors and controlled references; large payloads remain in their owner. proposed family; module-extensible node N27 · Runtime host / executor Shape: JVM, Hermes, browser, native Law / obligation: Expose an installed capability descriptor and lifetime; target name alone is insufficient. proposed family; module-extensible node N28 · Placement / resource pool Shape: Worker fleet, GPU pool, region Law / obligation: Hard constraints precede optimization; placement is not proof of current availability. proposed family; module-extensible node N29 · Factory / dynamic instance Shape: Match factory, tenant worker Law / obligation: Separate reusable definition from dynamic instance identity and bounded registry visibility. proposed family; module-extensible node N30 · External system boundary Shape: Legacy service, PLC, SaaS Law / obligation: Expose integration coverage honestly; graph visibility does not sandbox external code. proposed family; module-extensible node N31 · Schema / contract definition Shape: Record, protocol, resource ABI Law / obligation: Represent as a node when independently referenced; otherwise keep it a typed value/facet. proposed family; module-extensible node N32 · Capability offer / requirement Shape: Offline ranker, GPU offer Law / obligation: Availability and suitability do not confer authority; selection is context-scoped. proposed family; module-extensible node N33 · Policy / principal boundary Shape: Grant evaluator, tenant scope Law / obligation: Secrets stay out of graph payloads; current effect-time authority is rechecked. proposed family; module-extensible node N34 · Build / compiler pass Shape: Typecheck, lower, package Law / obligation: Key caches by semantic inputs and toolchain; preserve source maps and qualification profile. proposed family; module-extensible node N35 · Artifact / release manifest Shape: Signed region bundle, runtime image Law / obligation: Stable identity differs from content digest; exclude cosmetic layout from semantic identity. proposed family; module-extensible node N36 · Test / Shadow scenario Shape: Fault replay, baseline/candidate Law / obligation: Record assumptions, capture gaps and runner; no generic green-check guarantee. proposed family; module-extensible node N37 · Claim / evidence record Shape: Protocol claim, performance run Law / obligation: Evidence is claim-indexed, not a universal ordered strength score. proposed family; module-extensible node N38 · Observer / query / visitor Shape: Inspector, trace lens, analysis Law / obligation: Inspection cannot mutate implicitly; coverage and authority limit conclusions. proposed family; module-extensible node N39 · Agent / change proposer Shape: Planner, coding harness, reviewer Law / obligation: Drafts are not deployment; effective tool/OS authority must be controlled or disclosed. proposed family; module-extensible node N40 · Deployment / migration controller Shape: Rollout, drain, state transfer Law / obligation: Durable reconciliation; monotonic fencing epochs and explicit mixed-version policy. proposed family; module-extensible port P01 · Value / immutable snapshot Shape: Out → In Law / obligation: Schema, nullability, units and representation matter; value flow alone imposes no effect order. proposed profile; composable traits port P02 · Request / response Shape: Require ↔ Provide Law / obligation: Direction is a role; sync/async, error and timeout outcomes are part of compatibility. proposed profile; composable traits port P03 · Durable command / receipt Shape: Submit → Receipt Law / obligation: Receipt names the qualified completion stage, not simply receipt of bytes. proposed profile; composable traits port P04 · Push event Shape: EventOut → EventIn Law / obligation: Declare ordering, overflow, replay and delivery guarantee; not implicitly durable. proposed profile; composable traits port P05 · Pull iterator / cursor Shape: Next → Item|End Law / obligation: Cursor lifetime, backpressure, consistency cut and resume behavior are explicit. proposed profile; composable traits port P06 · Credit-controlled stream Shape: Stream + Request(n) Law / obligation: Demand, buffer bounds, terminal events and cancellation must agree across the boundary. proposed profile; composable traits port P07 · Duplex session Shape: Session Law / obligation: Both endpoints follow the protocol; pin session version and handoff semantics. proposed profile; composable traits port P08 · Signal / reactive state Shape: Signal Law / obligation: Distinguish latest-value conflation from delivery of every historical change. proposed profile; composable traits port P09 · Mutation / conditional update Shape: Update Law / obligation: The authority checks predicates and authorization; local write locks are not distributed CAS. proposed profile; composable traits port P10 · Transaction participant Shape: Participant Law / obligation: Only qualified participants enlist; a transaction token is not universal ACID. proposed profile; composable traits port P11 · Execution / continuation Shape: ExecIn → ExecOut Law / obligation: Defines effect order within one execution profile; not a generic network message. proposed profile; composable traits port P12 · Branch / guarded transition Shape: Case / Event[Guard] Law / obligation: Exhaustiveness and guard purity are checked; branch choice is separate from data encoding. proposed profile; composable traits port P13 · Completion / join token Shape: Done Law / obligation: Join rule defines required contributors and treatment of failure/cancellation. proposed profile; composable traits port P14 · Cancellation / deadline Shape: Cancel Law / obligation: Cancellation is cooperative unless stated otherwise; reconcile already-committed effects. proposed profile; composable traits port P15 · Clock / tick / timer Shape: Tick Law / obligation: Specify event-time versus processing-time semantics; clocks are dependencies for replay. proposed profile; composable traits port P16 · Owned resource transfer Shape: Owned Law / obligation: Exactly one accepted owner after transfer; reject duplication and invalid module epoch. proposed profile; composable traits port P17 · Borrowed buffer / view Shape: Borrow Law / obligation: Cannot escape its declared scope; async and cross-address-space use require a qualified lease/copy. proposed profile; composable traits port P18 · Shared read lease Shape: SharedRead Law / obligation: Reference counting alone does not make concurrent mutation safe; memory rules stay explicit. proposed profile; composable traits port P19 · Capability descriptor Shape: Offer / Require Law / obligation: Metadata for selection, not an authorization bearer; no implied access to the capability. proposed profile; composable traits port P20 · Authorization request / grant Shape: Authorize Law / obligation: Bind principal, scope, expiry and issuer; recheck at use and never serialize raw credentials. proposed profile; composable traits port P21 · Lifecycle management Shape: Prepare / Activate / Drain / Release Law / obligation: Calls may fail or be skipped on host death; required persistence cannot rely on cleanup. proposed profile; composable traits port P22 · Checkpoint / migration Shape: Snapshot → Restore Law / obligation: Migration is versioned and staged; rollback depends on state compatibility, not old code availability. proposed profile; composable traits port P23 · Artifact / schema reference Shape: Ref Law / obligation: A reference is not a raw pointer; loading verifies integrity, provenance and access. proposed profile; composable traits port P24 · Inspection / evidence Shape: Observe → Finding Law / obligation: Carries coverage and provenance; observational access does not confer mutation authority. proposed profile; composable traits hyperedge H01 · Exclusive binding Shape: consumer:1, provider:1 Law / obligation: Reject a second provider where exclusivity is required; dispatch can compile to a direct call. proposed relation schema; not an execution primitive by default hyperedge H02 · Value flow Shape: source:1, sink:1..N Law / obligation: Copy/fanout is legal only for the value ownership profile; units and schemas must match. proposed relation schema; not an execution primitive by default hyperedge H03 · Control precedence Shape: before:1..N, after:1..N Law / obligation: Defines ordering under a named profile; does not serialize unrelated graph layers. proposed relation schema; not an execution primitive by default hyperedge H04 · Event subscription Shape: publisher:1..N, subscriber:1..N Law / obligation: Subscriptions name filters, replay and delivery rules; broker resources remain separate nodes. proposed relation schema; not an execution primitive by default hyperedge H05 · Request / reply binding Shape: caller:1, callee:1, reply:0..1 Law / obligation: Protocol includes correlation, failure and unknown outcomes; transport is chosen independently. proposed relation schema; not an execution primitive by default hyperedge H06 · Multiparty session Shape: authority:1, participant:1..N, observer:0..N Law / obligation: Single relation identity with role/cardinality checks; delivery comes from an explicit protocol. proposed relation schema; not an execution primitive by default hyperedge H07 · Broadcast / fanout Shape: producer:1, consumer:1..N Law / obligation: State whether delivery waits for all, any or no receivers; slow receivers need a policy. proposed relation schema; not an execution primitive by default hyperedge H08 · Merge-any Shape: producer:1..N, consumer:1 Law / obligation: Specify interleaving, fairness and order; merging is not a join of corresponding values. proposed relation schema; not an execution primitive by default hyperedge H09 · Join-all Shape: input:2..N, result:1 Law / obligation: Align values by invocation/key; define failure, timeout and missing-input treatment. proposed relation schema; not an execution primitive by default hyperedge H10 · Race / select Shape: contender:2..N, winner:1 Law / obligation: Define first-completion versus first-success and cleanup/reconciliation of losing effects. proposed relation schema; not an execution primitive by default hyperedge H11 · Keyed temporal join Shape: left:1, right:1..N, result:1 Law / obligation: State key, clock, lateness/watermark and window policy; topology alone cannot pair records. proposed relation schema; not an execution primitive by default hyperedge H12 · Barrier / synchronization Shape: member:2..N, continuation:1 Law / obligation: Specify membership epoch, arrival condition and failure handling; no hidden global clock. proposed relation schema; not an execution primitive by default hyperedge H13 · Quorum requirement Shape: proposer:1, voter:1..N, result:1 Law / obligation: Names a qualified protocol and membership; counting votes alone does not implement consensus. proposed relation schema; not an execution primitive by default hyperedge H14 · Replica group Shape: authority:0..1, replica:1..N Law / obligation: Replication/merge and fencing rules are explicit; schema does not create consistency. proposed relation schema; not an execution primitive by default hyperedge H15 · Partition / route Shape: router:1, shard:1..N Law / obligation: Specify key function, assignment epoch and resharding; preserve owner and replay semantics. proposed relation schema; not an execution primitive by default hyperedge H16 · Atomic authority scope Shape: authority:1, participant:1..N Law / obligation: ACID applies only where that authority/profile implements it; not across arbitrary stores. proposed relation schema; not an execution primitive by default hyperedge H17 · Compensation relation Shape: forward:1, compensator:1..N Law / obligation: Compensation is a new effect with its own failure modes, not automatic historical erasure. proposed relation schema; not an execution primitive by default hyperedge H18 · Supervision Shape: supervisor:1, child:1..N Law / obligation: Specify restart budget, state/ownership effects and host-death behavior. proposed relation schema; not an execution primitive by default hyperedge H19 · Ownership / containment Shape: owner:1, owned:1..N Law / obligation: Selected ownership relation is acyclic; visual grouping is not ownership. proposed relation schema; not an execution primitive by default hyperedge H20 · Instantiation Shape: definition:1, instance:1..N Law / obligation: Fresh activation identities and scopes; shared definitions are not shared mutable instance state. proposed relation schema; not an execution primitive by default hyperedge H21 · Placement Shape: component:1..N, host:1..N Law / obligation: A plan expresses intended placement; observations separately establish what actually runs. proposed relation schema; not an execution primitive by default hyperedge H22 · Affinity / separation Shape: member:2..N, constraint:1 Law / obligation: Co-location, anti-affinity or memory-domain rule is a constraint, not an executable wire. proposed relation schema; not an execution primitive by default hyperedge H23 · Scoped authorization Shape: principal:1, resource:1..N, policy:1 Law / obligation: Decision is tied to action/context; visual reachability neither proves nor grants access. proposed relation schema; not an execution primitive by default hyperedge H24 · Capability resolution Shape: requirement:1, offer:1..N, decision:1 Law / obligation: Filter hard constraints and grants before preferences; pin or safely migrate running sessions. proposed relation schema; not an execution primitive by default hyperedge H25 · Implements / source ownership Shape: source:1, contract:1..N, region:1 Law / obligation: Exactly one edit authority per region; generated projections are not independently editable truth. proposed relation schema; not an execution primitive by default hyperedge H26 · Artifact dependency Shape: consumer:1, dependency:1..N Law / obligation: Pin semantic/artifact revisions; cosmetic layout changes need not invalidate code. proposed relation schema; not an execution primitive by default hyperedge H27 · Derivation / provenance Shape: input:1..N, transform:1, output:1..N Law / obligation: Results carry input cut and transform version; unknown dependencies widen invalidation. proposed relation schema; not an execution primitive by default hyperedge H28 · Evidence supports claim Shape: claim:1, evidence:1..N, verifier:1..N Law / obligation: Scope assumptions and coverage; evidence does not promote or authorize itself. proposed relation schema; not an execution primitive by default hyperedge H29 · Activation cohort Shape: release:1, image:1..N, localRoot:1 Law / obligation: Local root publication can be atomic; cross-host realization is recoverable coordination. proposed relation schema; not an execution primitive by default hyperedge H30 · Boundary export / alias Shape: internal:1..N, external:1..N Law / obligation: Preserve role, ownership and protocol when hiding/expanding a reusable region. proposed relation schema; not an execution primitive by default hyperedge H31 · Clock / time alignment Shape: clock:1..N, stream:1..N Law / obligation: Alignment needs a defined transform/uncertainty; timestamps do not establish causal order. proposed relation schema; not an execution primitive by default hyperedge H32 · Tensor / algebraic operation Shape: operand:1..N, operator:1, result:1..N Law / obligation: Validate axes, units and device layout; computation belongs to the qualified implementation. proposed relation schema; not an execution primitive by default hyperedge H33 · Fallback / preference set Shape: requirement:1, alternative:1..N Law / obligation: Fallbacks must remain eligible and authorized; never silently relax mandatory privacy or safety. proposed relation schema; not an execution primitive by default hyperedge H34 · Data access / lineage Shape: operation:1, store:1..N, schema:1..N Law / obligation: Records the modeled access scope; enforce at actual storage boundary and disclose opaque access. proposed relation schema; not an execution primitive by default hyperedge H35 · State migration Shape: oldState:1, migrator:1, newState:1 Law / obligation: Version checkpoints, fence writers and validate postconditions; inverse may not exist. proposed relation schema; not an execution primitive by default hyperedge H36 · Navigation / interaction route Shape: origin:1, intent:1, destination:1..N Law / obligation: Choose destination with guards and grants; back-stack and cancellation semantics are explicit. proposed relation schema; not an execution primitive by default # Authoring and industry precedents URL: https://reaktor.build/docs/architecture-atlas-workbench Status: design Content revision: 44cfae3ea4d1afc24846b9f1ad0b12050a6cf82a8e46fde68158d6f2f060410d Verification: {"at":null,"revision":null,"evidence":[]} Sources: [{"id":"astra-architecture-atlas-2026-10-07","title":"Reaktor architecture, language and graph atlas","date":"2026-10-07","revision":"71c9cdc97b480ad08a50d5bb8d1c14c8fb49edb0d4d97f9c0f65f0d6468a324a","coverage":["panel-synthesis","panel-studio","panel-precedents"]}] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/architecture-atlas-workbench","polarity":"Neutral"},{"id":"section-13-authoring-workbench-and-product-precedents","anchor":"13-authoring-workbench-and-product-precedents","label":"13. Authoring workbench and product precedents","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-workbench#13-authoring-workbench-and-product-precedents","polarity":"Neutral"},{"id":"section-panel-synthesis","anchor":"panel-synthesis","label":"Stately, Unreal, Cursor, FlutterFlow and Expo","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-workbench#panel-synthesis","polarity":"Neutral"},{"id":"section-panel-studio","anchor":"panel-studio","label":"Synchronized authoring and inspection views","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-workbench#panel-studio","polarity":"Neutral"},{"id":"section-panel-precedents","anchor":"panel-precedents","label":"Do not base differentiation on a familiar primitive","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-workbench#panel-precedents","polarity":"Neutral"},{"id":"section-boundary--caveat-1","anchor":"boundary--caveat-1","label":"Boundary / caveat","profile":"section","contract":"https://reaktor.build/docs/architecture-atlas-workbench#boundary--caveat-1","polarity":"Neutral"}],"relations":[{"id":"architecture-atlas-workbench:references-architecture-atlas-foundations","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-foundations","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-workbench:references-architecture-atlas-vocabulary","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-vocabulary","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-workbench:references-architecture-atlas-semantics","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-semantics","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-workbench:references-architecture-atlas-language","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-language","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-workbench:references-architecture-atlas-evolution","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-evolution","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-workbench:references-architecture-atlas-scenarios","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-scenarios","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-workbench:references-architecture-atlas-qualification","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"page","role":"source","ordinal":0},{"node":"architecture-atlas-qualification","port":"page","role":"target","ordinal":0}]},{"id":"architecture-atlas-workbench:references-reaktor-visual-language","kind":"references","owner":"architecture-atlas-workbench","incidences":[{"node":"architecture-atlas-workbench","port":"section-boundary--caveat-1","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]}]} ## Authoring and industry precedents Section ID: authoring-and-industry-precedents Authoring and industry precedents Design synthesis, 7 October 2026. This chapter incorporates the supplied Astra report. Its models and acceptance tests describe intended architecture; they do not certify current implementation. The report inventoried 140 public routes and compared substantive sections of 51 documents. Repository source and current qualification receipts determine what ships. Architecture thesis and invariants · Nodes, ports and hyperedge vocabulary · Composition and execution semantics · Compiler, source publication and consistency · Shadow, evidence and region releases · Authoring and industry precedents · Cross-runtime systems and worked scenarios · Impact, design obligations and qualification ## 13. Authoring workbench and product precedents Section ID: 13-authoring-workbench-and-product-precedents 13. Authoring workbench and product precedents Use a context-sensitive palette derived from module descriptors, not a hard-coded menu of every possible node. Dragging from a port filters by schema, protocol role, required authority, lifetime and target availability. Pure conversions may be suggested; a conversion that adds effects, permissions, lossy semantics or a network boundary must remain explicit. A selected entity should synchronize the product preview, region canvas, source editor, statechart, contract inspector and trace view. Each view carries the same region/revision/activation selection. The UI must clearly distinguish authored desired state from what is running on a particular device. Take state and microstep inspection from Stately, instance-aware pin watches and play/debug from Unreal, code-and-agent collaboration from Cursor, and component/interaction authoring from FlutterFlow. Play-in-Shadow launches a scoped test environment; it is not permission to pause a shared production runtime. Stately inspection API Unreal Blueprint debugger Cursor Agent overview FlutterFlow Action Flow Editor Keep named reusable regions, typed holes, undoable draft patches, semantic zoom, bounded graph queries and direct source escape hatches. Save incomplete drafts with findings; only activation requires a closed, executable contract. Automated edits land in a candidate workspace, not an auto-reloaded production authority. ## Stately / XState Section ID: stately--xstate Stately / XState Behavior is executable, inspectable state—not a flowchart approximation. Take: Hierarchical and parallel states, typed events, guards, actor ownership, snapshots and microstep inspection. Extend: A qualified statechart dialect for UI, protocols, services and durable processes, with explicit persistence and cancellation profiles. Avoid: Do not make all Reaktor computation finite-state or silently add durability to XState-style actor execution. Stately and XState documentation State machines and statecharts XState actor semantics Stately inspection API ## Unreal Engine / Blueprints Section ID: unreal-engine--blueprints Unreal Engine / Blueprints A powerful engine exposes curated primitives to a visual language. Take: Reflected module palette, typed pins, pure/effectful split, reusable assets, compiler findings, instance-aware watches, content cooking and Play-In-Editor. Extend: A system studio over apps, servers, data and infrastructure; Play-in-Shadow; target-specific region packaging and native C++/C# boundaries. Avoid: Do not reproduce engine-specific object assumptions, treat every drawn wire as an exec pin, or require giant graphs instead of source. Unreal Blueprint visual scripting Blueprint technical guide Unreal Blueprint debugger Unreal content cooking ## Cursor Section ID: cursor Cursor Source editing, agent context and review belong in the main workbench. Take: Code-and-agent workflow, context/rules, checkpoints, tool integration and review UX. Extend: One selected region drives graph, source, contract and trace views. Agents propose typed region patches with visible blast radius and independently enforced publication. Avoid: Prompts/rules are not an authority boundary; a source checkpoint does not roll back databases or external effects. Cursor Agent overview Cursor Agent security Cursor rules ## FlutterFlow Section ID: flutterflow FlutterFlow Start from the product the user is building, then expose its behavior. Take: Reusable UI components, forms, trigger-bound action flows, preview and custom code escape hatches. Extend: A product-first Surface lens linked to statecharts, service/data interfaces, authorization, deployment and evidence. Runtime renderer choice stays explicit. Avoid: Do not equate a widget tree with the entire system, or promise arbitrary generated-code round trips. FlutterFlow Action Flow Editor FlutterFlow custom code FlutterFlow reusable components ## Expo Section ID: expo Expo Separate the installed native runtime from compatible updateable content. Take: Development builds, runtime compatibility, signed updates, staged rollouts and artifact distribution. Extend: A signed region release and dependency vector, with per-host admission and state-safe activation; use existing Expo mechanisms for suitable RN targets. Avoid: EAS Update is not assumed to be arbitrary subgraph hot-swap. Native additions need new builds; policy compliance is independent of technical loadability. Expo development builds Expo runtime versions and updates Expo end-to-end update signing Expo update rollouts ## Stately, Unreal, Cursor, FlutterFlow and Expo Section ID: panel-synthesis Stately, Unreal, Cursor, FlutterFlow and Expo Each precedent contributes a distinct mode of building software; none should become the universal semantics. Vector diagram · click a marked item to inspect Five product lessons, one distributed-system language Diagram: Five product lessons, one distributed-system language Stately Behavior is executable, inspectable state—not a flowchart approximation. Statecharts + actors Unreal / Blueprints A powerful engine exposes curated primitives to a visual language. Engine + visual language Cursor Source editing, agent context and review belong in the main workbench. Code + agent workflow FlutterFlow Start from the product the user is building, then expose its behavior. Product + interactions Expo Separate the installed native runtime from compatible updateable content. Host-aware releases Reaktor Blueprint = a language for complete systems One semantic graph • typed ports • reusable regions • explicit runtime boundaries Multiple editing modes, specialized execution, shared authority and evidence Author Graph / statechart / source Product preview + agent edits Qualify Types, effects, compatibility Shadow + independent policy Realize Signed region release Per-host prepare and activation Observe Revision + activation + trace Findings return to the same IDs This is a synthesis of responsibilities, not a claim that any precedent supplies the whole architecture. Proposed integration: keep the editor, semantic model, runtime and delivery protocol separate but coherent. ## Reaktor design decision Section ID: reaktor-design-decision Reaktor design decision Treat Reaktor as the engine, Blueprint as its higher-level system language, and the studio as synchronized product, behavior, code and operational views. ## Boundary / caveat Section ID: boundary--caveat Boundary / caveat This is neither a replacement renderer nor a merger of five products. Capability and authorization remain explicit at every execution boundary. Qualification test. Select a UI element, jump to its statechart, service contract, implementation and deployment, then propose one linked change without recreating identities. Stately / XState Take: Hierarchical and parallel states, typed events, guards, actor ownership, snapshots and microstep inspection. Extend for Reaktor: A qualified statechart dialect for UI, protocols, services and durable processes, with explicit persistence and cancellation profiles. Do not inherit: Do not make all Reaktor computation finite-state or silently add durability to XState-style actor execution. Stately and XState documentation State machines and statecharts XState actor semantics Stately inspection API Unreal Engine / Blueprints Take: Reflected module palette, typed pins, pure/effectful split, reusable assets, compiler findings, instance-aware watches, content cooking and Play-In-Editor. Extend for Reaktor: A system studio over apps, servers, data and infrastructure; Play-in-Shadow; target-specific region packaging and native C++/C# boundaries. Do not inherit: Do not reproduce engine-specific object assumptions, treat every drawn wire as an exec pin, or require giant graphs instead of source. Unreal Blueprint visual scripting Blueprint technical guide Unreal Blueprint debugger Unreal content cooking Cursor Take: Code-and-agent workflow, context/rules, checkpoints, tool integration and review UX. Extend for Reaktor: One selected region drives graph, source, contract and trace views. Agents propose typed region patches with visible blast radius and independently enforced publication. Do not inherit: Prompts/rules are not an authority boundary; a source checkpoint does not roll back databases or external effects. Cursor Agent overview Cursor Agent security Cursor rules FlutterFlow Take: Reusable UI components, forms, trigger-bound action flows, preview and custom code escape hatches. Extend for Reaktor: A product-first Surface lens linked to statecharts, service/data interfaces, authorization, deployment and evidence. Runtime renderer choice stays explicit. Do not inherit: Do not equate a widget tree with the entire system, or promise arbitrary generated-code round trips. FlutterFlow Action Flow Editor FlutterFlow custom code FlutterFlow reusable components Expo Take: Development builds, runtime compatibility, signed updates, staged rollouts and artifact distribution. Extend for Reaktor: A signed region release and dependency vector, with per-host admission and state-safe activation; use existing Expo mechanisms for suitable RN targets. Do not inherit: EAS Update is not assumed to be arbitrary subgraph hot-swap. Native additions need new builds; policy compliance is independent of technical loadability. Expo development builds Expo runtime versions and updates Expo end-to-end update signing Expo update rollouts Official context and precedents: Stately and XState documentation Unreal Blueprint visual scripting Cursor Agent overview FlutterFlow Action Flow Editor Expo runtime versions and updates ## Synchronized authoring and inspection views Section ID: panel-studio Synchronized authoring and inspection views Product preview, graph, statechart, source, traces and agent review retain the same region/revision context. Vector diagram · click a marked item to inspect One selected region synchronizes product, graph, code and evidence Diagram: One selected region synchronizes product, graph, code and evidence REAKTOR STUDIO / Session feature DRAFT r108 HOST: preview-7 ACTUAL: r104 Module palette Compatible with session.in Statechart / actor Request operation Durable workflow Native adapter Reusable region Test / assertion Filter by selected port Composition lens — region: session.join Join intent request : Join Session actor event : Join state : Session Result authority commit : Result Selected contract JoinRequest × SessionProtocol × tenant grant × owned session 2 required pins unbound — saveable draft Source + agent region SessionJoin { receive JoinRequest require SessionGrant await session.join(request) return durableReceipt } Source owner: structured region Product preview Join session Continue • pending receipt Execution + evidence Trace: Join → admitted → committed → receipt Pinned: candidate r108 + artifact sha256:… + scenario v4 Production is not paused by stepping a Shadow instance. Agent patch: 3 entities changed • 2 consumers affected Intent → typed patch → review → Shadow → promotion → per-host activation A checkpoint restores a workspace. It does not undo a payment or a database migration. Illustrative workbench mock. Context-sensitive actions share command IDs and authority; there is no backend connection. ## Reaktor design decision Section ID: reaktor-design-decision-1 Reaktor design decision Borrow the useful editing modes while maintaining one source owner per region. Display desired, candidate and observed revisions visibly. Palettes derive from module contracts. ## Boundary / caveat Section ID: boundary--caveat-1 Boundary / caveat A pretty canvas is not a compiler. Source checkpoints and graph undo are not distributed rollback; production stepping requires explicit operational controls. Qualification test. Rename or move a component. Stable identity survives, source links remain valid, and layout changes do not invalidate executable artifacts. Official context and precedents: Unreal Blueprint debugger Stately inspection API Cursor Agent overview Cursor Agent security FlutterFlow Action Flow Editor Reaktor Visual Language / Blueprints ## Do not base differentiation on a familiar primitive Section ID: panel-precedents Do not base differentiation on a familiar primitive Typed graphs, visual programming, structured agents and simulation each have substantial precedents. Do not base differentiation on a familiar primitive Law / model / proof obligation: Differentiation hypothesis: lower total cost of safe cross-layer change, not novelty of graph syntax. Diagram: Do not base differentiation on a familiar primitive PRECEDENT MAP • REAKTOR’S OPPORTUNITY IS THE COMPOSITION Ptolemy II Hierarchical ports + execution profiles MLIR Dialects + qualified lowering MPS Projectional editing + agent tools Database systems Atomic change + isolation FoundationDB Simulation-supported evolution Kubernetes / OTP Reconciliation + live release Reaktor: shared identity, contracts and governed change across the lifecycle These precedents support specific mechanisms. None is evidence that the complete Reaktor composition already works. ## Reaktor design decision Section ID: reaktor-design-decision-2 Reaktor design decision Ptolemy is especially close architecturally. MPS’s experimental 2026.1 Projectional Agent Toolkit already provides structural model edits and validation to agents. Reaktor should prove its value across runtime, state, authority, deployment and evidence boundaries. ## What this does not establish Section ID: what-this-does-not-establish What this does not establish A catalog of precedents is not a feature-parity comparison or market survey. Integration can also multiply maintenance and semantic obligations if the boundaries are weak. Falsifiable acceptance test. Compare the same nontrivial feature change with ordinary tooling, graph-aware tooling, and graph plus Shadow/governance. Keep the model and requirements fixed. Theory, precedent and Reaktor context: Ptolemy II: hierarchy, ports and models of computation MLIR — Dialect conversion JetBrains MPS — Projectional Agent Toolkit (2026.1, experimental) FoundationDB — A Distributed Unbundled Transactional Key Value Store (SIGMOD 2021) Kubernetes — Controllers Erlang/OTP — Release handling # Astra Reaktor Plan and Roadmap URL: https://reaktor.build/docs/astra-reaktor-plan-and-roadmap Status: design Content revision: 2928edd4e3d0d1f4944ff50f4d660fab29400037b3c0f5a56c019680093bd800 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap","polarity":"Neutral"},{"id":"section-1-the-north-star","anchor":"1-the-north-star","label":"1. The north star","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#1-the-north-star","polarity":"Neutral"},{"id":"section-2-the-strategic-bet-and-the-standard-of-proof","anchor":"2-the-strategic-bet-and-the-standard-of-proof","label":"2. The strategic bet and the standard of proof","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#2-the-strategic-bet-and-the-standard-of-proof","polarity":"Neutral"},{"id":"section-3-greenfield-creation-is-a-first-class-product","anchor":"3-greenfield-creation-is-a-first-class-product","label":"3. Greenfield creation is a first-class product","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#3-greenfield-creation-is-a-first-class-product","polarity":"Neutral"},{"id":"section-4-the-engine-behind-creation","anchor":"4-the-engine-behind-creation","label":"4. The engine behind creation","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#4-the-engine-behind-creation","polarity":"Neutral"},{"id":"section-5-competing-with-builders-and-learning-from-infrastructure","anchor":"5-competing-with-builders-and-learning-from-infrastructure","label":"5. Competing with builders and learning from infrastructure","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#5-competing-with-builders-and-learning-from-infrastructure","polarity":"Neutral"},{"id":"section-6-the-core-a-live-model-with-a-small-semantic-kernel","anchor":"6-the-core-a-live-model-with-a-small-semantic-kernel","label":"6. The core: a live model with a small semantic kernel","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#6-the-core-a-live-model-with-a-small-semantic-kernel","polarity":"Neutral"},{"id":"section-8-a-generating-basis-modules-features-and-capabilities","anchor":"8-a-generating-basis-modules-features-and-capabilities","label":"8. A generating basis: modules, features and capabilities","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#8-a-generating-basis-modules-features-and-capabilities","polarity":"Neutral"},{"id":"section-9-runtime-actors-and-safe-live-evolution","anchor":"9-runtime-actors-and-safe-live-evolution","label":"9. Runtime, actors and safe live evolution","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#9-runtime-actors-and-safe-live-evolution","polarity":"Neutral"},{"id":"section-10-formal-methods-and-simulation-as-everyday-development-tools","anchor":"10-formal-methods-and-simulation-as-everyday-development-tools","label":"10. Formal methods and simulation as everyday development tools","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#10-formal-methods-and-simulation-as-everyday-development-tools","polarity":"Neutral"},{"id":"section-11-claude-codex-and-an-agent-native-system-interface","anchor":"11-claude-codex-and-an-agent-native-system-interface","label":"11. Claude, Codex and an agent-native system interface","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#11-claude-codex-and-an-agent-native-system-interface","polarity":"Neutral"},{"id":"section-13-polyglot-contracts-ffi-and-data-oriented-execution","anchor":"13-polyglot-contracts-ffi-and-data-oriented-execution","label":"13. Polyglot contracts, FFI and data-oriented execution","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#13-polyglot-contracts-ffi-and-data-oriented-execution","polarity":"Neutral"},{"id":"section-17-what-public-v1-means","anchor":"17-what-public-v1-means","label":"17. What public v1 means","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#17-what-public-v1-means","polarity":"Neutral"},{"id":"section-21-measuring-whether-reaktor-is-winning","anchor":"21-measuring-whether-reaktor-is-winning","label":"21. Measuring whether Reaktor is winning","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#21-measuring-whether-reaktor-is-winning","polarity":"Neutral"},{"id":"section-19-roadmap-from-september-2026-to-september-2027","anchor":"19-roadmap-from-september-2026-to-september-2027","label":"19. Roadmap from September 2026 to September 2027","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#19-roadmap-from-september-2026-to-september-2027","polarity":"Neutral"},{"id":"section-18-the-release-must-prove-four-complete-journeys","anchor":"18-the-release-must-prove-four-complete-journeys","label":"18. The release must prove four complete journeys","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#18-the-release-must-prove-four-complete-journeys","polarity":"Neutral"},{"id":"section-7-kotlin-and-the-public-programming-model","anchor":"7-kotlin-and-the-public-programming-model","label":"7. Kotlin and the public programming model","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#7-kotlin-and-the-public-programming-model","polarity":"Neutral"},{"id":"section-12-flows-choreography-and-the-opinionated-datacloud-stack","anchor":"12-flows-choreography-and-the-opinionated-datacloud-stack","label":"12. Flows, choreography and the opinionated data/cloud stack","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#12-flows-choreography-and-the-opinionated-datacloud-stack","polarity":"Neutral"},{"id":"section-14-studio-ides-and-tools-that-gain-power-from-the-graph","anchor":"14-studio-ides-and-tools-that-gain-power-from-the-graph","label":"14. Studio, IDEs and tools that gain power from the graph","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#14-studio-ides-and-tools-that-gain-power-from-the-graph","polarity":"Neutral"},{"id":"section-15-build-deploy-and-operate-one-reproducible-system","anchor":"15-build-deploy-and-operate-one-reproducible-system","label":"15. Build, deploy and operate one reproducible system","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#15-build-deploy-and-operate-one-reproducible-system","polarity":"Neutral"},{"id":"section-20-non-negotiable-december-release-gates","anchor":"20-non-negotiable-december-release-gates","label":"20. Non-negotiable December release gates","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#20-non-negotiable-december-release-gates","polarity":"Neutral"},{"id":"section-22-adoption-distribution-and-the-ten-year-position","anchor":"22-adoption-distribution-and-the-ten-year-position","label":"22. Adoption, distribution and the ten-year position","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#22-adoption-distribution-and-the-ten-year-position","polarity":"Neutral"},{"id":"section-16-current-system-map-and-intended-progression","anchor":"16-current-system-map-and-intended-progression","label":"16. Current system map and intended progression","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#16-current-system-map-and-intended-progression","polarity":"Neutral"},{"id":"section-the-central-design-improvement","anchor":"the-central-design-improvement","label":"The central design improvement","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#the-central-design-improvement","polarity":"Neutral"},{"id":"section-from-an-idea-to-an-application","anchor":"from-an-idea-to-an-application","label":"From an idea to an application","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#from-an-idea-to-an-application","polarity":"Neutral"},{"id":"section-four-linked-planes","anchor":"four-linked-planes","label":"Four linked semantic domains","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#four-linked-planes","polarity":"Neutral"},{"id":"section-graph-transformations-acquire-explicit-laws","anchor":"graph-transformations-acquire-explicit-laws","label":"Graph transformations acquire explicit laws","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#graph-transformations-acquire-explicit-laws","polarity":"Neutral"},{"id":"section-declarative-architecture-with-ordinary-code-inside","anchor":"declarative-architecture-with-ordinary-code-inside","label":"Declarative architecture with ordinary code inside","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#declarative-architecture-with-ordinary-code-inside","polarity":"Neutral"},{"id":"section-graceful-degradation-is-executable-product-behavior","anchor":"graceful-degradation-is-executable-product-behavior","label":"Graceful degradation is executable product behavior","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#graceful-degradation-is-executable-product-behavior","polarity":"Neutral"},{"id":"section-marked-graph-regions-and-code-push","anchor":"marked-graph-regions-and-code-push","label":"Marked graph regions and code push","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#marked-graph-regions-and-code-push","polarity":"Neutral"},{"id":"section-a-practical-chain-from-specification-to-runtime","anchor":"a-practical-chain-from-specification-to-runtime","label":"A practical chain from specification to runtime","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#a-practical-chain-from-specification-to-runtime","polarity":"Neutral"},{"id":"section-evidence-composes-and-expires-with-its-assumptions","anchor":"evidence-composes-and-expires-with-its-assumptions","label":"Evidence composes and expires with its assumptions","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#evidence-composes-and-expires-with-its-assumptions","polarity":"Neutral"},{"id":"section-ai-inside-the-generated-application","anchor":"ai-inside-the-generated-application","label":"AI inside the generated application","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#ai-inside-the-generated-application","polarity":"Neutral"},{"id":"section-offline-and-external-integrations-are-first-class-behaviors","anchor":"offline-and-external-integrations-are-first-class-behaviors","label":"Offline and external integrations are first-class behaviors","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#offline-and-external-integrations-are-first-class-behaviors","polarity":"Neutral"},{"id":"section-evidence-and-sequencing","anchor":"evidence-and-sequencing","label":"Evidence and sequencing","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#evidence-and-sequencing","polarity":"Neutral"},{"id":"section-a-worked-north-star-scenario","anchor":"a-worked-north-star-scenario","label":"A worked north-star scenario","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#a-worked-north-star-scenario","polarity":"Neutral"},{"id":"section-release-and-recovery-are-graph-operations-with-real-state","anchor":"release-and-recovery-are-graph-operations-with-real-state","label":"Release and recovery are graph operations with real state","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#release-and-recovery-are-graph-operations-with-real-state","polarity":"Neutral"},{"id":"section-24-reading-map-and-maintenance-contract","anchor":"24-reading-map-and-maintenance-contract","label":"24. Reading map and maintenance contract","profile":"section","contract":"https://reaktor.build/docs/astra-reaktor-plan-and-roadmap#24-reading-map-and-maintenance-contract","polarity":"Neutral"}],"relations":[{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-essays","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-the-central-design-improvement","role":"source","ordinal":0},{"node":"reaktor-essays","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-atlas-revamp-5.6-ultra","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-from-an-idea-to-an-application","role":"source","ordinal":0},{"node":"reaktor-atlas-revamp-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-workbench-roadmap","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-from-an-idea-to-an-application","role":"source","ordinal":0},{"node":"reaktor-workbench-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-unified-system-graph","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-6-the-core-a-live-model-with-a-small-semantic-kernel","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-unified-system-graph-continuous-zoom","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-four-linked-planes","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"section-continuous-zoom","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-unified-system-graph-flow-entrypoints","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-four-linked-planes","role":"source","ordinal":0},{"node":"reaktor-unified-system-graph","port":"section-flow-entrypoints","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-graph-kernel-analysis","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-graph-transformations-acquire-explicit-laws","role":"source","ordinal":0},{"node":"graph-kernel-analysis","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor_graph_visitors_design","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-graph-transformations-acquire-explicit-laws","role":"source","ordinal":0},{"node":"reaktor_graph_visitors_design","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-stable-foundations-5.6-ultra","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-graph-transformations-acquire-explicit-laws","role":"source","ordinal":0},{"node":"reaktor-stable-foundations-5.6-ultra","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-megascale-strategy","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-graph-transformations-acquire-explicit-laws","role":"source","ordinal":0},{"node":"reaktor-megascale-strategy","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-framework-overview","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-declarative-architecture-with-ordinary-code-inside","role":"source","ordinal":0},{"node":"reaktor-framework-overview","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-core","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-declarative-architecture-with-ordinary-code-inside","role":"source","ordinal":0},{"node":"reaktor-core","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-service","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-declarative-architecture-with-ordinary-code-inside","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-surface-renderers","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-declarative-architecture-with-ordinary-code-inside","role":"source","ordinal":0},{"node":"reaktor-surface-renderers","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-visual-language","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-declarative-architecture-with-ordinary-code-inside","role":"source","ordinal":0},{"node":"reaktor-visual-language","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-capability","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-graceful-degradation-is-executable-product-behavior","role":"source","ordinal":0},{"node":"reaktor-capability","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-notifications-design","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-graceful-degradation-is-executable-product-behavior","role":"source","ordinal":0},{"node":"reaktor-notifications-design","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-component-lifecycle","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-marked-graph-regions-and-code-push","role":"source","ordinal":0},{"node":"reaktor-component-lifecycle","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-actor-model","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-marked-graph-regions-and-code-push","role":"source","ordinal":0},{"node":"reaktor-actor-model","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-distributed-actors","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-marked-graph-regions-and-code-push","role":"source","ordinal":0},{"node":"reaktor-distributed-actors","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-graph-migration-plan","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-marked-graph-regions-and-code-push","role":"source","ordinal":0},{"node":"reaktor-graph-migration-plan","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-ffi-design","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-marked-graph-regions-and-code-push","role":"source","ordinal":0},{"node":"reaktor-ffi-design","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-formal-methods","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-a-practical-chain-from-specification-to-runtime","role":"source","ordinal":0},{"node":"reaktor-formal-methods","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-verified-foundations-fable-5","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-evidence-composes-and-expires-with-its-assumptions","role":"source","ordinal":0},{"node":"reaktor-verified-foundations-fable-5","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-agentic-tooling","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-ai-inside-the-generated-application","role":"source","ordinal":0},{"node":"reaktor-agentic-tooling","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-koog-workbench","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-ai-inside-the-generated-application","role":"source","ordinal":0},{"node":"reaktor-koog-workbench","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-koog-agents","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-ai-inside-the-generated-application","role":"source","ordinal":0},{"node":"reaktor-koog-agents","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-browser-local-ai","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-ai-inside-the-generated-application","role":"source","ordinal":0},{"node":"reaktor-browser-local-ai","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-db","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-offline-and-external-integrations-are-first-class-behaviors","role":"source","ordinal":0},{"node":"reaktor-db","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-server","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-offline-and-external-integrations-are-first-class-behaviors","role":"source","ordinal":0},{"node":"reaktor-server","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-bus-mesh","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-offline-and-external-integrations-are-first-class-behaviors","role":"source","ordinal":0},{"node":"reaktor-bus-mesh","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-mesh","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-offline-and-external-integrations-are-first-class-behaviors","role":"source","ordinal":0},{"node":"reaktor-mesh","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-work","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-offline-and-external-integrations-are-first-class-behaviors","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-flexbuffer-performance-review","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-evidence-and-sequencing","role":"source","ordinal":0},{"node":"flexbuffer-performance-review","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-flatbuffers-flexbuffers-mutable-memory","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-evidence-and-sequencing","role":"source","ordinal":0},{"node":"flatbuffers-flexbuffers-mutable-memory","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-flexbuffer-implementation","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-evidence-and-sequencing","role":"source","ordinal":0},{"node":"flexbuffer-implementation","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-flexbuffer-improvement-plan","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-evidence-and-sequencing","role":"source","ordinal":0},{"node":"flexbuffer-improvement-plan","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-ffi","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-evidence-and-sequencing","role":"source","ordinal":0},{"node":"reaktor-ffi","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-performance-observability","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-evidence-and-sequencing","role":"source","ordinal":0},{"node":"performance-observability","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-desktop-master-plan","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-a-worked-north-star-scenario","role":"source","ordinal":0},{"node":"reaktor-desktop-master-plan","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-graph-hierarchical-ui","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-a-worked-north-star-scenario","role":"source","ordinal":0},{"node":"reaktor-graph-hierarchical-ui","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-build-tools","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-release-and-recovery-are-graph-operations-with-real-state","role":"source","ordinal":0},{"node":"reaktor-build-tools","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-dependeasy","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-release-and-recovery-are-graph-operations-with-real-state","role":"source","ordinal":0},{"node":"reaktor-dependeasy","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-cli","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-release-and-recovery-are-graph-operations-with-real-state","role":"source","ordinal":0},{"node":"reaktor-cli","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-devops","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-release-and-recovery-are-graph-operations-with-real-state","role":"source","ordinal":0},{"node":"reaktor-devops","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-cloud-pane","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-release-and-recovery-are-graph-operations-with-real-state","role":"source","ordinal":0},{"node":"reaktor-cloud-pane","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-shadow-dev-environment","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-release-and-recovery-are-graph-operations-with-real-state","role":"source","ordinal":0},{"node":"shadow-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-module-review","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-24-reading-map-and-maintenance-contract","role":"source","ordinal":0},{"node":"reaktor-module-review","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-module-execution-plan","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-24-reading-map-and-maintenance-contract","role":"source","ordinal":0},{"node":"reaktor-module-execution-plan","port":"page","role":"target","ordinal":0}]},{"id":"astra-reaktor-plan-and-roadmap:references-reaktor-graph-refinement-plan","kind":"references","owner":"astra-reaktor-plan-and-roadmap","incidences":[{"node":"astra-reaktor-plan-and-roadmap","port":"section-24-reading-map-and-maintenance-contract","role":"source","ordinal":0},{"node":"reaktor-graph-refinement-plan","port":"page","role":"target","ordinal":0}]}]} ## Astra Reaktor Plan and Roadmap Section ID: astra-reaktor-plan-and-roadmap Astra Reaktor Plan and Roadmap Author: Astra / Codex. Planning baseline: 7 September 2026. Horizon: 7 September 2026–6 September 2027. First public v1: December 2026. Turn an idea into a distinctive, working application—and keep increasing what it can do. Reaktor should become the standard way people and agents create, compose, understand, change and operate software. It competes directly in greenfield app creation with Emergent, Rork, Lovable, Bolt and similar builders, while also helping developers adopt and improve existing systems. Both paths lead into the same development engine. Claude and Codex supply intelligence. Reaktor supplies reusable full-stack systems, product/design authoring, live preview, typed composition, runtime behavior, integrations, deployment and verification. A person can begin with an idea and a visual conversation; a developer can work directly in code. As the application grows, neither should have to abandon the project and rebuild it on a different foundation. This page is the primary vision, core design, system map and execution plan. It incorporates the detailed core design brief and plans for two primary developers, each working with Codex and Claude. It refines the existing designs and chooses a delivery order; detailed specifications remain in the linked documents. It is a plan, not a declaration that the target architecture is implemented. Current-state statements refer to the local source survey on 7 September, including substantial uncommitted work. The complete internal evidence record is Astra Analysis, which requires authentication. Reading paths: Product creation · Core design · Current status · Release scope · Two-developer roadmap. ## 1. The north star Section ID: 1-the-north-star 1. The north star Reaktor is the forge in which people and agents create, run and continually improve ambitious software. Its core product is a programmable development engine: reusable mechanisms, declarative composition, a live system model, specialized execution, and tools that understand the relationships between them. The goal is to expand what one team can build while increasing confidence in each change. A founder starts with an idea and gets a distinctive functioning application. A developer adds custom behavior without falling out of the framework. A growing team can add native clients, asynchronous workflows, external systems, demanding compute and operational controls while preserving its source, product identity and data. React demonstrated how a compact composition model can support a huge variety of interfaces. Unreal demonstrates the value of durable engine mechanisms, expressive authoring and a shared debugging model. Reaktor extends that ambition across clients, services, actors, data, infrastructure and AI. The destination is broader than a visual app builder or a game-engine analogy: an application can remain understandable, adaptable, testable and programmable throughout its life. The launch must win both the first hour, when an idea becomes an attractive working app, and the hundredth change, when that app has real users and behavior worth preserving. Greenfield creation is a primary product. Existing-project adoption is another entrance into the same engine. ## The central design improvement Section ID: the-central-design-improvement The central design improvement Make one declared relationship useful in many places. A typed connection can determine wiring, generated clients, tracing and impact analysis. A capability requirement can determine implementation, fallback, placement and test scenarios. An actor's state ownership can determine scheduling, persistence, replay and update boundaries. A protocol can determine valid interactions, generated endpoints and failure monitors. A module's assumptions can determine whether a composition is admissible and what evidence it still needs. This gives Reaktor two paths to growing power. Breadth comes from additional orthogonal mechanisms and integrations. Depth comes from making every existing mechanism participate in more of the development lifecycle. A new adapter should unlock existing features on another environment; a new checker should protect many applications; a better model should compose the same verified mechanisms more effectively. These effects can compound, but “exponential” is an ambition to measure rather than a mathematical guarantee. A person should be able to ask the same project: What should this product do, and what design expresses it? What behavior is composed, where does state live, and what is running? Which implementation is possible here, and how does the feature degrade? What would a change affect across source, protocols, data and deployed clients? Which assumptions, checks and measurements justify accepting the change? What exact operation is authorized, and what happened when it ran? The initial proving grounds are multi-user web products, native companion apps and workflow/AI products. BestBuds, Manna, GymBuddy and the surrounding applications exercise real seams. Later, scientific tools, device fleets, enterprise gateways and robotics coordination can use the same composition model with specialized execution profiles. Timing, safety and regulatory claims in those domains require their own implementations and evidence; adopting the graph alone does not establish them. The two Reaktor essays provide the original thesis. This revision joins their strongest ideas and tightens their semantics. It preserves eight years of accumulated mechanisms and product experience, while replacing inconsistent boundaries incrementally. The core north-star design is in sections 6–15; the current implementation map and planned delivery order follow in sections 16–23. ## 2. The strategic bet and the standard of proof Section ID: 2-the-strategic-bet-and-the-standard-of-proof 2. The strategic bet and the standard of proof AI can increase the rate at which software is proposed. Reaktor's bet is that the scarce capability becomes accepting, composing and operating those proposals with confidence. Better models should make Reaktor more valuable: each improvement in reasoning can use the same contracts, counterexamples, simulations and evidence interfaces without requiring the platform to replace its core. The desired advantage is cumulative. A new app starts with substantial engine capability instead of regenerating authentication, state ownership, retries and platform glue from scratch. One typed contract should improve client generation, wiring diagnostics, authorization checks, impact analysis, simulation, deployment planning and agent context. A defect repaired in a reusable module should produce a regression obligation that protects every compatible consumer. An integration should bring its semantics and failure modes into the system model, rather than merely add a button to launch a tool. Advantage to earn Mechanism Evidence that would justify the claim Better first-app creation Intent-to-product composition, distinctive design, functioning backend modules and live preview An unfamiliar brief becomes a usable deployed application, with independently checked behavior and design quality More useful complexity per developer Reusable modules, hierarchical composition, scoped queries and explicit deployment cuts External teams complete a larger change with fewer manual coordination steps and no loss of correctness Higher reliability Structural validation, mediated effects, owned state, bounded model checks and implementation conformance Named failure classes rejected or recovered on the supported matrix, with reproducible artifacts Greater agent productivity Versioned machine interfaces, small context packets, actionable findings and repeatable scenarios The same agent completes matched tasks faster or more often, at measured total cost Less integration work Ordinary APIs plus graph projections and tested adapters An existing application adopts one boundary without a rewrite or a mandatory Reaktor-hosted service Safer operation Revision-bound plans, scoped authority, observed reconciliation and explicit compensation Stale approvals, changed definitions and disallowed effects are rejected; permitted failures produce useful receipts Long-lived ecosystem value Portable formats, compatibility policy, open extension contracts and module conformance Independent modules and applications survive upgrades and remain operable without the original author “More powerful than comparable tools” is the objective, not a fact established by this document. Reaktor must win a measured combination of these outcomes. It should happily retain specialist tools that are better at their domain. A framework that forces users to abandon their best tools has increased its own surface area without necessarily increasing their power. ## Overall design review: what to retain and what to improve Section ID: overall-design-review-what-to-retain-and-what-to-improve Overall design review: what to retain and what to improve The existing work has an unusually valuable combination: live graph infrastructure, KMP/native/Worker reach, full product consumers, binary/native work, actor and capability patterns, visual authoring designs, and extensive tool integrations. The main opportunity is to make their boundaries agree. A broad collection of individually useful mechanisms becomes an engine when a feature can move through authoring, execution, simulation and change without losing its semantics. Core idea to retain Current limit or design gap North-star improvement New power it should unlock Live nested heterogeneous port graph Runtime, editor and architecture representations have different identities and rules Small versioned semantic kernel, explicit runtime islands and source/activation mappings One change can drive code, preview, validation, placement and causal inspection Visitors Traversal order, relation type, visit multiplicity and mutation are not consistently separated Typed analysis/rewrite/observation passes with declared read sets, bounded traversal and invalidation Add cross-cutting functionality once and apply it predictably across many systems Modules as a basis for composition Reuse alone does not establish independent primitives or valid combinations Orthogonal mechanisms, parameterization, specialization, substitution and assumption/guarantee contracts A larger design space without a proportional increase in bespoke glue Feature, adapter and capability Global feature access and boolean/tier availability cannot describe scope or tradeoffs Scoped capabilities, multidimensional offers, hard constraints and explainable strategy selection One feature adapts across devices, providers, permission changes and resource limits Actor model Serial mailbox handling does not contain arbitrary child-coroutine state mutation or create durable acceptance Explicit state ownership, message dispositions, effect re-entry and local/durable execution profiles Reusable concurrent behavior that can later migrate or survive failures under named guarantees Flow and choreography Ports and individual RPCs do not describe a distributed conversation Flow contracts plus projectable protocols, timeouts and runtime conformance Visualize, simulate and change cross-system behavior as a whole FlexBuffers and polyglot FFI A binary representation does not define ownership, streaming or transport semantics One contract compiler, owned/borrowed buffer ABI and explicit local/remote call profiles Reuse native and dynamic implementations without losing control of performance or failure Graph code push Replacing a bundle can invalidate state, authority and in-flight work Marked update regions, compatible host APIs, prepared activation and epoch/state transition plans Change appropriate behavior between deployments with bounded blast radius Formal methods Designed models and passing tests are not yet a connected assurance pipeline Small executable laws, model-to-test conformance and revision-bound evidence Reusable counterexamples and trustworthy automation for specific failure classes Opinionated infrastructure Provider convenience can hide different ordering, consistency and migration semantics Deep reference stack with explicit state authority and qualified adapter profiles Strong defaults, lower integration cost and deliberate migration paths Developer and AI tooling Discovering commands or displaying fixtures is weaker than understanding their semantics Shared project service, source mappings, task/effect contracts and actionable findings Agents and humans work through the same meaningful operations Greenfield creation Existing Composer interaction is not yet a functioning app-production loop Product/design authoring over real modules, isolated build/preview and iterative growth Compete on first-app quality and retain value as application complexity increases The refinements below are normative target decisions. Where an older design implies transparent cross-process actors, universal zero-copy, unrestricted live mutation or whole-system correctness from graph metadata, use the more precise contract here. Historical documents remain linked as design history and implementation detail. ## The improvements that should distinguish the engine Section ID: the-improvements-that-should-distinguish-the-engine The improvements that should distinguish the engine The decisive test is whether Reaktor can compose creation, adaptation, execution and change more effectively than isolated tools. Four integrated capabilities should become its signature: Executable product intent: acceptance journeys connect the user's goal to screens, domain behavior, capabilities and independently checked outcomes. Adaptive composition: the same feature can select a compatible local/native/remote implementation and an explicit fallback, with understandable consequences. Inspectable execution: fast compiled code remains connected to a live model of ownership, effects, state and causal observations. Reusable verification and optimization: a counterexample, profile or invariant becomes an asset that improves future changes and compatible consumers. The core should improve several of these at once. A proposed abstraction earns inclusion by enabling new combinations, eliminating repeated glue, or making a relevant failure class decidable or enforceable. It should be tested against multiple application domains and an ablation that removes it. If it merely renames existing complexity, it has not increased Reaktor's power. ## 3. Greenfield creation is a first-class product Section ID: 3-greenfield-creation-is-a-first-class-product 3. Greenfield creation is a first-class product The first screen should offer Create an app as the primary action, with Open a project alongside it. Creation accepts a natural-language brief, sketches, design references or a starting recipe. It should not require understanding a graph, picking databases or completing an architecture questionnaire. The user can start quickly, while consequential product assumptions remain visible and easy to change. The default creation workspace has a conversation with Claude/Codex, the running product preview, and a navigator for journeys, screens, data and behavior. Code, blueprint, tests and deployment are connected views with progressively deeper controls. A non-programmer works through intention and direct visual feedback; an engineer can edit source and inspect every abstraction. These are two depths of the same project, not separate products with an export cliff. ## From an idea to an application Section ID: from-an-idea-to-an-application From an idea to an application Stage What the user experiences Durable artifact the engine creates Intent Describes the users, outcome, style and target devices; answers only high-impact missing questions Editable product brief, assumptions, constraints and prioritized acceptance journeys Product shape Sees a proposed flow and a meaningful first screen quickly; can change direction before a long build Screen/journey map, domain concepts, roles, navigation and an initial feature plan Design Refines layout, typography, imagery, motion and component behavior in context App-specific tokens, component/variant choices, responsive rules and reference assets with provenance Composition Sees what the app will actually do and what needs a real external connection Selected full-stack modules, contracts, state authority, policies, workflow and deployment intent Build Watches working slices arrive, uses the preview, and requests changes Owned source repository, build lockfiles, semantic manifest, migrations, fixtures and runnable implementation Verify Tries the product and sees concrete issues repaired without losing its design Journey tests, visual/accessibility checks, contract findings and bounded failure scenarios Publish Chooses preview or release and sees what is being connected, provisioned or charged Reviewed deployment plan, environment/secrets bindings, artifact identity and deployment result Grow Adds roles, workflows, integrations or a new client without resetting the app Scoped changes, compatible migrations, updated tests, evidence and preserved user data These are artifacts in a continuous session, not eight mandatory confirmation screens. Low-risk local generation and preview run under a bounded standing grant; the user can interrupt, branch, undo source changes or revisit assumptions. Credential use, paid provisioning, public publication and consequential data changes use the appropriate explicit boundary. The product should ask about user-visible decisions, not internal graph mechanics. This promotes the existing New System Composer and scaffold-from-prompt design into the first public release. It extends them from skeleton generation to functioning behavior. A generated graph alone is not an app; a collection of screens with fake handlers is not a functioning product. ## Full-stack features as the building material Section ID: full-stack-features-as-the-building-material Full-stack features as the building material The creator should compose tested capabilities at feature scale while retaining smaller primitives underneath. “Add sign-in” should connect the screen, identity flow, session lifecycle, backend verification, authorization policy and test fixture. “Add a discussion” should connect navigation, membership, storage, message lifecycle, notification intent and retry behavior. “Add an approval workflow” should include roles, legal transitions, persistence, audit and deadlines. These are recipes over real module APIs, with replaceable UI and domain logic. The agent can specialize the composition instead of copying opaque templates or rewriting core security code. The recipe registry should declare compatible module versions, target support, assumptions, migrations, examples and tests. When a recipe is insufficient, ordinary code and lower-level graph primitives remain available; the platform must not silently force the product back into a template. December needs a small set that spans varied apps: identity and roles; structured data and files; forms/list/detail/search; navigation and responsive layouts; one asynchronous workflow/notification path; an integration boundary; and an optional typed AI call. Advanced payments, collaborative editing, media processing, complex offline sync and regulated-domain guarantees need separately qualified adapters. The product should show what is supported, what is generated custom code and what still needs configuration. ## Design quality belongs on the critical path Section ID: design-quality-belongs-on-the-critical-path Design quality belongs on the critical path Reaktor should generate products with their own visual identity. Machine Signal is the Studio's design system, not a mandatory look for every generated application. Human Signal is a BestBuds reference, not a universal template. App-specific tokens, density, typography, accessibility, platform conventions and motion should derive from the brief and references. The author should be able to select a component in the preview and change its appearance or behavior through direct controls, conversation or code. Selection resolves to a stable screen/component/source identity. A visual edit should preserve bindings and behavior; a logic edit should preserve unrelated styling. Changing a token should show affected screens and visual checks. Reference artwork or a .pen scene is design input, not executable proof of the app. Preview must cover loading, empty, error, denied, offline and successful states. It should run the same application modules as the release lane wherever supported. Simulated integrations are useful during creation, but a “Connect service” gap must remain visible until a real binding is tested. Browser emulation is not evidence that a native app's permissions, background work or signing path works. ## Build apps that can outgrow their first prompt Section ID: build-apps-that-can-outgrow-their-first-prompt Build apps that can outgrow their first prompt The creator must handle follow-up changes that cut across layers: add organizations to a single-user app; change a field without losing data; introduce an approval step; add a mobile client; replace a model provider; split a heavy service into another runtime; or add an external system with weaker guarantees. The engine should explain the impact, generate the migration or adapter, and exercise the affected journeys. Code ownership is practical: normal Git history, readable source, documented build commands, portable data export and the ability to continue in an IDE or with Claude/Codex directly. Reaktor should remain useful after that move, through its runtime modules and project model. Retention should come from continuing value, not making the project impossible to leave. ## 4. The engine behind creation Section ID: 4-the-engine-behind-creation 4. The engine behind creation The creation product needs a real application-production pipeline, in addition to the semantic kernel. It should turn a brief into a buildable project and keep the artifacts synchronized through subsequent changes. Project session: retain the brief, accepted decisions, source revision, design assets, module lockfile, environment, pending changes, preview and evidence. Long agent runs must survive disconnects and be resumable or cancellable. Changing the brief invalidates the affected work rather than launching a full rebuild by default. Planning and generation: decompose work into executable slices with shared contracts and explicit source ownership. Let Claude/Codex specialize the product, reuse engine modules and implement custom code. Parallel agents can work on disjoint slices; the coordinator integrates through versioned source/semantic checks. A second agent's agreement is useful review, not a correctness certificate. Workspace execution: isolate each project's filesystem, processes, network policy, secrets, build cache and preview origin. The public browser creator needs a managed execution lane; advanced users also need a local companion using the same protocol. Choose one runner implementation for December, with durable job status, quotas, cancellation, cleanup and artifact retention. Do not let generated code run inside the control-plane process or inherit its provider credentials. Fast feedback: use published/prebuilt framework artifacts, warm toolchains, compatible recipe caches and impacted-scope checks. A browser user should not wait for a fresh native toolchain bootstrap to see the first web screen. Kotlin/JVM, Worker and native target builds can have different schedules while sharing contracts. Cached evidence must include the source, compiler, dependency, policy and adapter inputs that make it applicable. Target capabilities: express product requirements independently of platform names, then choose an implementation and fallback for each target. A feature can use native hardware, portable code, a remote service or an explicit unavailable state. The creator sees the product consequence—such as background updates stopping or offline capture remaining available—and the engine generates and tests the selected strategy. Shared contracts preserve meaning while UX, permissions and execution remain platform-specific. Provisioning and preview: maintain separate disposable preview and production environments. Bind data/auth/files through the selected recipe, create safe test identities/data, expose an access-controlled preview, and retain the exact revision running there. Offer a simple managed deploy path plus an export/self-host path. Hide routine infrastructure plumbing while showing costs, data location and consequential choices when they matter. Product feedback: map bug reports and selected preview elements back to the journey, source, state and relevant trace. Model/evaluation cost, build failures and repeated repair attempts should be visible enough to stop wasteful loops. Improve recipes and checks from explicit user feedback and anonymized or consented examples; private customer source and data must not silently become shared templates or evaluation fixtures. These are proposed systems with their own status and release gates. The current Reaktor web prototype is not an implemented hosted app factory. The existing framework, Gradle tooling, supervised executor, auth, source maps and product integrations reduce the work, but isolation, resumable build sessions, creation orchestration and browser UX still require implementation. ## 5. Competing with builders and learning from infrastructure Section ID: 5-competing-with-builders-and-learning-from-infrastructure 5. Competing with builders and learning from infrastructure App builders and agent development environments already set a substantial bar. The following capabilities were checked against official documentation on 7 September 2026; they are vendor-documented features, not independently measured success rates. Reaktor's proposed response is an ambition to test, not a claim that competitors cannot support complex applications. Product Documented bar What Reaktor must demonstrate Cursor Agent can edit code, run terminal commands, use browser tools and restore code checkpoints; Cloud Agents provide configured remote execution environments. Agent, Cloud Agents A strong professional coding workflow plus measurable gains from runtime contracts, capability-aware composition, failure simulation and continued changes across clients/data/services; integrate with IDEs while competing on the complete development experience Emergent Its E3 workflow describes brainstorming, phased planning, multi-agent construction, browser testing/repair, preview and deployment; it also documents shared-backend web/mobile creation. E3, web/mobile Equally direct creation, with reusable runtime mechanisms and contracts that measurably improve more difficult follow-up changes Rork New projects target Swift/SwiftUI iPhone apps, Kotlin/Compose Android apps and React web apps; separate clients can share backend/context. Rork Cloud beta provides managed backend facilities. Platform transition, Rork Cloud Native product quality and device behavior, plus shared domain contracts and tested coordination as clients evolve; native generation alone is not distinctive Lovable Prompt/reference-driven creation, visual design guidance and editing, backend integration, publication and documented browser/frontend/edge testing. Quick start, design guidance, testing First-session visual quality and simplicity, with a higher proven ceiling for stateful, native and asynchronous behavior Bolt Design import, generated database/auth paths, source sync and hosting; its documentation explicitly distinguishes source-history restoration from database restoration. Figma, database, GitHub, publication Comparable design-to-working-app speed, with understandable schema/state evolution and recovery across later changes Replit Idea-to-app planning/build/preview/publication, a development environment and documented mobile creation/testing/distribution workflows. First app, mobile A creation product useful to newcomers and professionals, whose engine provides measurable additional expressive range and reliability v0 Full-stack app generation and direct design editing; its September changelog describes branch/preview/PR/merge/deploy flows respecting repository protections. Full-stack apps, changelog Distinctive UI and controlled publishing as a baseline, then stronger demonstrated continuity among behavior, state, contracts and runtime evidence Reaktor should not base its positioning on “others only generate toy screens,” “only Reaktor has testing,” or “only Reaktor supports native apps.” It must match their useful defaults and then show that a richer engine makes more ambitious products easier to create and maintain. The winning comparison spans initial design quality, working behavior, cost, speed, source portability and the twentieth meaningful change. The framework landscape is complementary. Encore already derives application structure from code for tooling and infrastructure; Temporal provides durable execution; Dapr provides portable distributed building blocks; Aspire models resources and their lifecycle. Reaktor should integrate or learn from these mechanisms where useful, while developing its full client-to-runtime creation model. MCP and OpenTelemetry are interoperability foundations, not competing application builders. Claude and Codex are enabling partners throughout. The aim is to make their work more effective inside Reaktor and make Reaktor projects equally usable from their ordinary development environments. ## 6. The core: a live model with a small semantic kernel Section ID: 6-the-core-a-live-model-with-a-small-semantic-kernel 6. The core: a live model with a small semantic kernel Reaktor has one heterogeneous, nested, multilayer logical port graph living through source authoring, build and runtime. Definitions describe the system; activations execute its supported regions; observations report concrete executions; derived views help developers and agents change it. These are connected entities and interpretations in one identity fabric, with distinct owners, revisions and evidence. The Living Graph foundation is the canonical specification; the atlas shows its authoring, query, boundary, trace and change instruments. Reaktor north-star architecture: authoring, semantic compilation, specialized runtime islands and a governed feedback loop Target architecture. These are architectural responsibilities and relationships, not a claim that all components are implemented. ## A small nucleus and extensible domain semantics Section ID: a-small-nucleus-and-extensible-domain-semantics A small nucleus and extensible domain semantics The semantic kernel owns finite data and pure laws for identity, contracts/endpoints, typed relations, containment, versioned facets, snapshots, normalization, validation and patches. It does not own UI layout, payment rules, SQL execution, model inference or cloud APIs. A module attaches domain facets and implements named semantic interfaces: owns state, declares effects, requires capabilities, provides a protocol, supports migration, maps to source or describes cost. Generic analyses use these interfaces instead of a growing switch over every component class. Unknown optional metadata can be preserved; an unknown facet required for correct activation produces an unsupported-contract finding. This borrows the extensibility principle of MLIR interfaces without requiring an MLIR dependency. Module validators and optimizers remain executable extensions with their own trust and test boundary. They can contribute obligations and evidence; they cannot replace fundamental structural checks or grant authority by returning success. The trusted base for a particular claim includes the relevant checker, host, adapter and enforcement path—not just the size of the core package. The kernel exposes definition identity separately from its revision/content digest. A runtime instance adds activation identity and epoch. An observation adds its source, sequence, time and coverage. Operation, conversation, actor and artifact IDs join those records without being conflated with trace IDs or source-file names. Reflected Kotlin class names and runtime object addresses are local implementation details. ## Four linked semantic domains Section ID: four-linked-planes Four linked semantic domains Domain Owns How it changes Definition Contracts, declared topology, owned behavior/state/effects, capabilities and deployment intent Source or authored composition produces an immutable revision through validation Activation Implementation, host/session/tenant, bindings, resources, epoch and lifecycle A host prepares, activates, stops or migrates an owned runtime island Observation Events, traces, state summaries, capability/permission observations and receipts Authorized subscriptions append or refresh records with provenance and freshness Derivation Layout, indexes, dependency slices, plans, checks and optimization proposals Recomputed or incrementally maintained from an identified input revision/cut These domains are typed facets/relations and owned records in one logical graph, not four parallel graph stores. “One model” means common identities, mappings and laws. Source still owns algorithms; a design system owns its tokens; a database owns domain records; a deployment controller owns applied resources. The graph records their relationships and each field's authority. It is not a new database that silently takes ownership of everything it can display. Relations carry a type: containment, dependency, invocation, data flow, navigation, supervision, state ownership, authority, placement or derivation. Canonical dependencies explicitly name consumer and provider. A data-flow view may draw values in the other direction, using an explicit projection. This resolves the directional ambiguity in earlier designs. Scope, semantic layers, detail, revision/time and editor mode vary independently. A composable ordered layer/query stack can combine structure, contracts, state/effects, runtime, authority, navigation, data/analytics, placement/delivery and an agent proposal. Folding preserves exact endpoint identities; layout does not change execution. Source and trace editors can pin different revisions without losing their correspondence. The target interaction is continuous semantic zoom, like moving from Earth to cities and streets: whole application/fleet → runtime island → feature → node → port. Scale bands change detail over the same graph while stable IDs, selected routes, layers and time remain pinned. Scope independently controls query/budget rather than forcing another page. Inspecting a DOM/Compose element highlights its source, bindings/handlers and full operation/state/effect/resource route; reverse navigation reveals the UI affected by a state or service change. Named capture, send, return, notification and analytics routes can be composed, simulated and executed through selected profiles, with per-target run/resume/drain/reconciliation controls. See continuous zoom and UI-to-system mapping. Orchestration is trigger-independent and headless flows are first-class. A typed entry/admission registry accepts UI events, HTTP/service/webhooks, queues/Pub/Sub/state changes, schedules/timers, device streams, CLI/operators, agents through MCP/A2A adapters and lifecycle/protocol continuations. It preserves schema mapping, event/correlation identity, acknowledgement, ordering/backpressure and effective grants. A versioned flow/runbook can join running protocols or streams and produce multiple outcomes; it need not begin at a UI or terminate as a finite DAG. ETL, settlement, incident response, fleet coordination, deployment/migration and native scientific pipelines use the same graph and profile-aware commands. See flow entry and admission contracts. ## Local runtime islands and a federated live view Section ID: local-runtime-islands-and-a-federated-live-view Local runtime islands and a federated live view An island is a lifecycle and mutation boundary controlled by one host: an app process, JVM service, Worker invocation/host profile, Durable Object or native runtime. It owns local activation handles and publishes an authorized structural/observation projection. External systems join through adapters that state coverage and write ownership. Federated queries identify their consistency: a local atomic revision, a vector of source revisions and observation times, or a coordinated causal capture. A disconnected host becomes stale or unknown. Subscription records carry epoch, sequence and resume cursor; missing events trigger resnapshot or an incomplete result. There is no implied instantaneous global graph transaction. The model describes stores, schemas, computation kernels and selected entities without turning every database row, pixel or tensor element into an always-live node. Queries are scoped and budgeted. This lets very large systems stay inspectable while retaining domain-appropriate storage and execution. Ordinary Kotlin and Kotlin DSLs retain general loops, recursion, libraries and custom algorithms. The general Kotlin/behavior profile is required to be Turing-complete in the usual unbounded-memory language model; actual targets retain finite resources and execution budgets. Explicitly reified regions provide additional visual syntax and stronger checks under named computation profiles. Actor, stream, durable-protocol, pure-value, general-code and native profiles have different cycle, state and failure laws; the system is not globally a DAG. Source adapters state which edits round-trip, and opaque bodies remain source-editable without a false claim of complete extraction. ## Keep the graph alive while specializing execution Section ID: keep-the-graph-alive-while-specializing-execution Keep the graph alive while specializing execution Compile stable wiring into direct references or generated calls. Fuse a hot sequence of pure operations when its observable contract permits it. Keep the semantic identity/source mapping and opt-in probes associated with the compiled region. Retain indirection only where it earns value: dynamic binding, policy mediation, instrumentation or an explicitly updateable boundary. This creates a fast execution path and a live descriptive/control path over the same declared program. A trace can explain a fused region without dispatching every arithmetic operation through a graph map. A dynamic region pays a measured boundary cost; a static native kernel need not. Optimizations must preserve the required behavior, ownership and observability contract and identify any reduced inspection granularity. The useful Unreal lesson is the division between durable mechanisms and expressive behavior authoring. Blueprint does not universally disappear into native code: Epic documents its virtual-machine execution and different performance characteristics. Reaktor should make its own static/dynamic tradeoffs explicit. Epic's Blueprint/C++ guidance. ## Visitors become reusable analyses and transformations Section ID: visitors-become-reusable-analyses-and-transformations Visitors become reusable analyses and transformations Keep visitors as pure traversal/query logic over authorized immutable inputs. Build a pass system around them that distinguishes proposals from runtime operations: Pass or operation Result Required contract Analyze Typed findings, indexes, dependency/cost/authority summaries Fixed declared inputs, deterministic analysis, no hidden runtime mutation Rewrite Proposed semantic/source patch and new obligations Expected base revision, read/write scope, preconditions and claimed semantic change Observe Incremental projection from recorded events Sequence/gap handling, freshness and reproducible update rules Install Lifecycle-owned instrumentation/binding handle Explicit effects, dynamic-attachment coverage and tested teardown Execute Run events and receipt for an authorized plan Effect policy, revalidation, budgets and partial-failure semantics Observe, Install and Execute are sibling mechanisms, not permission for an analysis visitor to mutate a live Graph. Environmental IO is collected into explicit input artifacts. Unrestricted Kotlin callbacks cannot be assumed pure merely because an interface is read-only. Traversal specifies relation kinds, boundary rules, deterministic order, cycle behavior, cancellation/budget and visit multiplicity: once per entity, once per edge or per relevant path/state. For example, a service reachable through both guarded and unguarded routes is not protected merely because a visit-once traversal saw the guarded path first. Authorization analysis must propagate relevant path state or solve a suitable fixed point. BFS must not silently promise DFS postorder callbacks. A pass declares required semantic interfaces, input dependencies, result schema, version and preserved analyses. Incremental results must equal a fresh analysis at the same complete input or be invalidated. Lost events, changed policy or an unknown external dependency cannot yield a reused green result. Independent read-only passes can run in parallel; concurrent rewrites need semantic conflict detection. MLIR pass infrastructure is a useful precedent for analysis/transform separation and conservative invalidation. ## Graph transformations acquire explicit laws Section ID: graph-transformations-acquire-explicit-laws Graph transformations acquire explicit laws A rewrite identifies whether it preserves representation, preserves behavior under assumptions, changes product intent or adapts execution within an allowed degradation contract. It returns its patch, source mapping, affected state/effects, preconditions and required checks. The small core laws are executable: rejected patches leave published definitions unchanged; an accepted non-noop patch publishes one valid new revision; readers see a complete old or new definition; equal complete planning inputs produce the same plan; a transformation cannot enlarge authority without a separate grant. Runtime activation and external effects have additional laws in section 9. This turns visitors into a route to much more powerful tooling. A telemetry pass can propose lifecycle-owned probes with cost/data budgets. An auth pass can identify and mediate every declared entry/effect boundary, including future activations. A deployment pass can derive cross-host obligations. An optimization pass can suggest caching, retries, batching or relocation—but must account for freshness, principal scope, duplicated effects and changed failure semantics. Adding a wrapper is not automatically behavior-preserving. See graph-kernel analysis, visitor design, Stable Foundations, Living Graph foundation and mega-scale strategy. Migrate through adapters from the current runtime/editor models, one real feature at a time. ## 7. Kotlin and the public programming model Section ID: 7-kotlin-and-the-public-programming-model 7. Kotlin and the public programming model Reaktor should become the framework that reveals the full reach of Kotlin: one language for reusable domain mechanisms, declarative architecture, concurrency, native clients, backend code, build tooling and generated interfaces. This is an ecosystem ambition, not a claim of endorsement or exclusive suitability. TypeScript and C++ remain first-class authoring and implementation languages; using a Reaktor module from either must not require becoming a Kotlin build expert. ## Why Kotlin is the center Section ID: why-kotlin-is-the-center Why Kotlin is the center Kotlin fits this particular design because several capabilities meet in one toolchain. Multiplatform compilation lets the same pure contracts and behavior target different runtimes. Interfaces, extension functions and DSLs make small composition APIs expressive. Coroutines provide a common way to describe suspended operations, cancellation and streams. Platform source sets and expect/actual give native differences explicit homes. JVM libraries, native interop and JavaScript access bring large existing ecosystems into reach. Platform and UI support still have their own maturity levels. Kotlin platform support, coroutines. The design consequence is share meaning, specialize execution. Share contracts, state transitions, protocol definitions and pure calculations where their semantics agree. Specialize UI conventions, schedulers, storage, binary layouts and device behavior where they differ. A coroutine scope helps express lifetime; it does not automatically make a database transaction durable or make shared actor state isolated. Compiler integration should extract declared structure and generate efficient glue, so users do less bookkeeping and the runtime does less reflection. Start with the current KSP/FlexCoder foundation for declarations, codecs, manifests and source maps. Use a separate, optional compiler analysis for expression-level effect restrictions and lowering of the owned behavior language. KSP cannot inspect statements or expressions; Kotlin's custom compiler plugin API has an ongoing compatibility cost. Keep Reaktor's portable IR and public contracts independent of compiler internals, pin tested compiler versions, and retain explicit declarations as an escape hatch. KSP scope, compiler plugin guidance. The year-one language roles are deliberate: Language Principal contribution Contract with the rest of Reaktor Kotlin General-purpose mechanisms, shared domain behavior, actors, native applications and framework tooling Native authoring model; generated stable manifests and adapters TypeScript / Kotlin-generated JavaScript Web/Worker ecosystem, rapid behavior authoring and the dynamic update lane Normal npm consumption, source maps, explicit host capabilities and runtime compatibility C++ Native libraries, compute kernels, low-level device access and predictable data layouts Stable C-facing ABI, explicit buffer ownership and conformance for supported calls/streams Python Scientific, ML, automation and data ecosystems that extend the kinds of applications Reaktor can build Process-first integration and a measured optional shared-memory/embedded lane, described in section 13 Swift, Rust, Go, Dart, C# and others Existing applications, specialist libraries and ecosystem access Generated or hand-written adapters over the same contracts; promote a language when user value justifies maintaining a full lane This prioritizes additional expressive reach without closing the ecosystem. Rust's ownership tools, Swift's native APIs or Go's deployment characteristics can matter to particular consumers even when Reaktor does not build a complete parallel SDK for each at launch. ## Two entrances, one set of mechanisms Section ID: two-entrances-one-set-of-mechanisms Two entrances, one set of mechanisms Create assembles a new app from intent, design and full-stack modules; Adopt adds useful capabilities to an existing project. Both use the same contracts and runtime. Auth, services, storage and notifications must also work as ordinary libraries. Graph composition adds lifecycle, inspection and cross-module checks; mediated effects and explicit protocols add stronger guarantees. Existing-project adoption level What the developer introduces What becomes possible Inspect Read-only source/runtime adapters A partial system map, source pointers and explicit unknowns Wrap Typed contracts around existing boundaries Generated clients, compatibility checks and boundary diagnostics Compose Declared nodes, ports, routes and owned state Deterministic wiring, lifecycle ownership and impact analysis Mediate Controlled effect handles, policies and instrumented adapters Enforcement at those boundaries, simulation and trace conformance Operate Execution adapters and environment authority Deployment and operational changes with reconciliation and receipts This table describes adoption in existing code. Greenfield onboarding starts with the product creation workspace, which supplies appropriate defaults. ## Declarative architecture with ordinary code inside Section ID: declarative-architecture-with-ordinary-code-inside Declarative architecture with ordinary code inside Keep the familiar roles and make their interactions explicit. A repository exposes domain data access and its consistency contract. An interactor implements a use case through declared dependencies. An actor owns serialized state transitions where that ownership is useful. An adapter implements an external or platform boundary. A UI renderer projects product state into React, Compose or another declared surface. A feature composes these roles; none needs to become a mandatory wrapper around every function. Algorithms remain Kotlin, TypeScript, C++ or Python. Blueprint authoring owns the composition and selected behavior program: typed events, values, branching, bounded iteration, functions, state transitions and effect requests. Flow-based programming gives explicit channels and scheduling; ordinary control-flow nodes remain available where a data-flow representation would be awkward. Cycles declare delay, state or scheduling semantics, so a visual loop does not accidentally become an unbounded synchronous call chain. React and Compose supply a useful law for architecture too: declaration should describe the desired structure; a reconciler computes the change. An architecture declaration must not perform arbitrary effects every time it is evaluated. Resource acquisition belongs to prepared activation; data mutation belongs to an explicit operation. This makes repeated evaluation, preview and rollback of source changes tractable. Source and visual authoring round-trip only where ownership is defined. Reaktor-owned composition has an editable projection; ordinary source exposes editable declared regions or a read-only map. Every generated node retains its source identity. Both directions detect stale edits and ownership conflicts, preserve unrelated code/comments, and report drift. A new authoring surface must consume the shared parser, normalizer and validator rather than invent another graph language. December delivers a small useful subset with a clear extension path. The long-term authoring ceiling includes deeply nested heterogeneous flows, choreography, state machines, domain-specific editors and code islands in the same project. See Framework Overview, Core, Service, React/Compose and Visual Language. ## 8. A generating basis: modules, features and capabilities Section ID: 8-a-generating-basis-modules-features-and-capabilities 8. A generating basis: modules, features and capabilities The eigenvector analogy captures an excellent design objective: find mechanisms with little redundant meaning that combine into a large useful space of systems. The precise engineering metaphor is a generating basis, not literal linear algebra. Software composition has state, ordering, constraints and nonlinear interactions; “fractional combination” should mean specialization, selective use and substitution rather than undefined arithmetic on modules. ## Separate structural vocabulary, behavior and product recipes Section ID: separate-structural-vocabulary-behavior-and-product-recipes Separate structural vocabulary, behavior and product recipes Layer Basis Purpose Semantic structure Identity, entity, typed endpoint/relation, boundary, facet, revision and patch Describe, connect and change systems consistently Behavioral mechanisms Pure transformation, owned state/transition, request, mailbox, stream, lifecycle/task scope, explicit effects, time and protocol Express concurrent and distributed behavior with named laws Full-stack modules Auth, services, repositories, storage, UI/navigation, notifications, sync, media, workflow and AI Reuse difficult mechanisms with ordinary APIs and graph projections Product recipes Parameterized compositions with journeys, design choices, fixtures and migrations Build applications quickly while retaining custom code and module replacement Value, State, Stream, Request and Mailbox are useful public interaction shapes. Their contracts must additionally state ownership, lifetime, errors, ordering, consistency, cancellation and delivery. A state view is not permission to mutate its owner's storage. A Flow is not a durable queue. Actors are a strong choice for serialized long-lived behavior, while a small UI value can use a cheaper owned state scope. Use a small set of composition operations: Operation Meaning Obligation Compose and bind Connect compatible components through declared endpoints Contract, cardinality, lifetime and authority compatibility Nest and expose Form a feature/subgraph with a deliberate public boundary Internal ownership stays local; exported paths preserve policy Specialize Select parameters, strategies and optional facets Required invariants and minimum product behavior still hold Substitute Replace an implementation behind a contract Compatible inputs/results, state, effects, timing and failure profile Replicate or partition Scale independent or coordinated instances Explicit keys, state ownership, ordering and coordination Place or adapt Choose host/provider/native/remote implementation Capability, data movement, latency, authority and recovery requirements Evolve Apply a versioned source/topology/behavior change Compatibility, active-work handling, state migration and evidence refresh The compiler should discharge straightforward obligations automatically and expose the rest as useful findings. Application developers work with features; mechanism authors define the laws that make those features composable. ## A module carries its operating contract Section ID: a-module-carries-its-operating-contract A module carries its operating contract A module package should include namespaced contracts/schema versions, implementation/source digests, supported runtime profiles, state ownership/schema, effects, capability requirements, policy hooks, migrations, cost/budget hints, probes, fixtures and evidence references. Its ordinary API and opt-in graph projection share behavior and tests; the graph wrapper must not reimplement the business logic. Assumptions and guarantees make modules compose usefully. A retry mechanism can require idempotency; an actor can require exclusive transition ownership; an auth boundary can require a verified principal. The checker establishes that the selected composition discharges those requirements on the paths where the guarantee is claimed. Compatible module proofs/tests do not invent unstated product requirements. Introduce a new primitive only when it adds expressive reach, a meaningful law or a large reduction in repeated glue. Require at least two credible consumers, a small example and a counterexample it prevents. Compare with a recipe built from existing mechanisms. Maintain a domain matrix—social/realtime, approval, offline capture, AI tools, native media and existing-service adoption—and measure manual glue, concepts learned and generated-code churn. Remove or merge abstractions whose distinct names do not create distinct useful behavior. ## Feature-capability becomes an adaptive composition system Section ID: feature-capability-becomes-an-adaptive-composition-system Feature-capability becomes an adaptive composition system Keep adapters and capability subinterfaces: a camera adapter can expose capture, front/back selection or streaming without branching on platform names. Improve the design by separating six facts: Installed adapter: which implementation exists in this host/session? Capability offer: what operations and guarantees can it provide? Environment observation: what is known about network, storage, power or resource availability? Permission: has the OS/user granted the privileged operation? Authority: may this principal act on this tenant/resource now? Strategy: which eligible composition satisfies the product's requirements? Plain APIs can retain nullable adapters for basic availability. Modeled features need a structured reason for unavailable, denied, unsupported, stale or unknown states. A single Full/Standard/Basic tier cannot express all relevant differences: an in-app badge does not satisfy a requirement to alert someone whose app is closed. A feature declares hard requirements, preferences and permitted fallback transitions. Offers describe dimensions such as privacy/residency, persistence, timing, quality, hardware, execution mode, latency/cost and authority. Resolve hard constraints first; rank eligible choices with a versioned policy. If none qualify, return a useful unsatisfied requirement or an explicitly permitted degraded mode. Preserve human choice where alternatives change product meaning. A capability plan records the request, selected implementation/profile, rejected alternatives and reasons, environment/permission/policy snapshot, grants, validity/recheck conditions, product consequence and migration of already-active work. Begin with an explainable rule-based resolver; add a solver or learned ranking only when the decision space needs it. Failure of a heuristic is not proof that no valid composition exists. ## Graceful degradation is executable product behavior Section ID: graceful-degradation-is-executable-product-behavior Graceful degradation is executable product behavior For field capture, a feature may require that an attachment remain private and eventually reach its owner. A native camera is preferred; browser upload can satisfy the same product outcome; queued local intent can preserve capture while offline. Sending the file to an unapproved remote processor is not an eligible performance fallback. An absent adapter produces a clear unavailable action or a designed alternative. For reminders, a requirement to notify outside the app can select an authorized push/server route. A badge is a valid alternative only if the product explicitly accepts that weaker behavior. Rebinding an accepted reminder preserves its operation identity and transfers effect ownership through the declared completion protocol. Provider idempotency or reconciliation must resolve an already-dispatched attempt before an alternative can safely run; identity alone does not prevent duplicate delivery. Recheck changing permissions and grants at effect time. Use hysteresis, minimum dwell and measured switching cost for optional performance/quality changes; revocation can demand immediate cessation. Distinguish plans for future operations from migration of active ones. This same mechanism can later select C++ acceleration, local/remote Python work, model providers, rendering strategies or actor hosts. Replace global Feature access in modeled code with a host/session-scoped context that owns installed services, task lifetime, clocks, randomness and effect handles. Keep the current global facade temporarily for explicit legacy contexts. Tenant/account/session state must never be silently inherited from a process-wide registry. A new headset or device category can unlock existing features by satisfying these capability contracts. Platform-specific UX, permissions, performance and conformance still need validation. December should prove two bounded strategy families on real web/native paths; the general optimization space grows from those fixtures. See capability design, Core, notifications and modules/architecture overview. By year end, publish the module/recipe contract and local installation path; by the first anniversary, an independent maintainer should use the same conformance kit. ## 9. Runtime, actors and safe live evolution Section ID: 9-runtime-actors-and-safe-live-evolution 9. Runtime, actors and safe live evolution The runtime interprets a validated composition through named host profiles. Its central responsibilities are resource lifetime, state ownership, communication, effects and change. These responsibilities should be independently useful as libraries and composable through the graph. ## Declaration, preparation, publication and reconciliation Section ID: declaration-preparation-publication-and-reconciliation Declaration, preparation, publication and reconciliation Keep graph construction ergonomic, but have modeled builders produce finite declarations and a deterministic binding plan before effects begin. Provider selection has explicit precedence and ambiguity errors. Navigation/UI behavior is an optional feature of a runtime scope, not an unavoidable dependency of every headless graph. An operation names the state it changes: an authored/desired definition revision, a local active topology/epoch, or externally reconciled resources. Committing a valid desired definition does not establish that it is active everywhere. For a supported local activation, validate the entire plan, prepare owned resources, and publish complete bindings at an explicit commit point. A preparation failure disposes of prepared resources and leaves the prior active topology intact. Arbitrary provisioning is not hidden inside this local atomicity claim; remote resources use explicit effect/reconciliation steps. Readers must never see half-wired local structure as a successful activation. Lifecycle scopes own tasks, adapters, subscriptions and children. Close has a deadline and observable disposition; cancellation propagates through the declared tree. No stopped parent should retain an untracked child executor or telemetry subscription. Compatibility wrappers around current mutable Graph/PortGraph remain while individual features move to this boundary. ## Actors own decisions, not merely a dispatcher Section ID: actors-own-decisions-not-merely-a-dispatcher Actors own decisions, not merely a dispatcher The modeled actor form is a bounded, non-suspending transition from state, message and admitted facts to next state, replies, effect intents and timer changes. The runtime alone publishes the next state. Inputs and published state must be immutable or defensively isolated; a handler cannot mutate already-published state or captured external objects before commit. Effects run outside the turn and return completion/failure messages carrying operation and activation/session identity. Restricted profiles enforce turn budgets through supported constructs and checkpoints. A timeout alone cannot terminate arbitrary Kotlin/native work; a hard termination guarantee needs a host that can enforce it, including isolation where required. Unrestricted handlers retain an explicit weaker profile. This makes asynchronous work composable without allowing its callback to mutate a new session or bypass the mailbox. A long request becomes an operation state machine; it does not hold the actor's mailbox while waiting for an external service. Read-only queries expose immutable snapshots with a version. Synchronous self-requests and request cycles produce a diagnostic or use explicit continuation messages. The current Channel loop is a useful starting point, but limited parallelism and serialized receive calls are not heap isolation or a guarantee about arbitrary launched coroutines. Default to non-reentrant state mutation; support special reentrant or legacy suspend profiles only with declared limitations and tests. Orleans scheduling is a useful reference for the distinction between task serialization and request interleaving. A logical actor identity includes application, environment, tenant, actor type and entity key. State/message schemas and implementation revisions are versioned separately. An activation has a host/incarnation/epoch. Display names, sanitized file paths and KClass identities cannot define durable ownership. Actor profile Acceptance means Guarantees and uses Local Admitted to a bounded in-memory mailbox One owned activation, explicit loss/close rules; useful for UI, sessions and local coordination Durable Committed inbox/admission record under the selected state authority Versioned state, deduplication/replay policy, durable timers and fenced ownership; useful for long-lived keyed behavior Foreign/legacy Whatever the declared adapter can establish Existing actors remain usable with explicit opaque behavior and weaker claims Durable Objects and a JVM/Postgres host can implement named durable profiles. They are not transparently equivalent destinations for arbitrary local ActorNode code. Native dependencies, transaction scope, interleaving, data location and resource limits constrain placement. ## Admission, deadlines and message outcomes Section ID: admission-deadlines-and-message-outcomes Admission, deadlines and message outcomes Every request has a stable message/operation identity, payload/schema identity, destination, deadline and scoped caller provenance. Admission and business completion are separate observations. The deadline includes time waiting to enter the mailbox. Capacity is bounded in messages and bytes with tenant fairness. Messages can be rejected before acceptance, accepted, processing, completed, domain-rejected, failed, cancelled before a defined commit, or unresolved with an unknown outcome. Durable retries retain the same logical operation and record separate attempts. Dropping/coalescing is appropriate for explicitly lossy signals such as progress; it is not valid for an accepted durable command. Concurrent producers have no inherent global order. The actor defines a committed turn sequence and preserves any promised producer/conversation causality. Shutdown drains, persists or rejects work according to its profile and resolves pending local asks. Poison messages, domain errors, transient adapter failures and runtime invariant failures need different supervision policies. Runtime cancellation must not be swallowed as an ordinary restartable error. ## Durable state and effect completion Section ID: durable-state-and-effect-completion Durable state and effect completion Within one transactional authority, commit inbox disposition, state version, reply result, durable timer changes and outbox intents together. A unique operation key plus payload digest distinguishes a safe duplicate from a conflicting request. Deduplication retention is part of the supported retry/replay window. External calls happen after commit. Each effect chooses an explicit completion strategy: Strategy How completion is established Transaction-local The authoritative transaction records both the state change and outcome Provider-idempotent Reuse the provider's supported idempotency key and validate its scope/retention Reconcile after uncertainty Query a durable external reference and determine whether the operation happened Best-effort The product accepts possible loss/duplication within a documented bound Manual resolution Preserve an unknown outcome and the evidence needed to resolve it safely An outbox prevents lost intent; it does not alone prevent duplication at an arbitrary external provider. Compensation is a new domain operation with its own possible failures. Cancellation before a commit can prevent that commit when the boundary supports it. After an external dispatch, cancellation can stop future work while the sent operation may still complete. Cancelling a caller's wait and cancelling a business operation are different actions. Preserve OutcomeUnknown when the system cannot yet establish the result. ## Supervision, passivation and placement Section ID: supervision-passivation-and-placement Supervision, passivation and placement A restart creates a new activation and rebuilds owned resources. A durable restart restores the last committed state; a local restart follows its explicit initial/retained-state policy. Durable passivation closes the active route, finishes or records the current turn, persists timers/outbox state and releases resources. A durable inbox may continue accepting work for reactivation; a local mailbox follows its explicit close policy. Migration transfers a versioned state/protocol/inbox/outbox/timer checkpoint and advances a fenced ownership epoch through the authoritative store. Heartbeats, discovery or Kubernetes readiness are not state ownership. Stale owners must be rejected where state commits occur; already-dispatched external effects still need their own idempotency or reconciliation. Use managed DO placement or a simple qualified store-backed host before inventing a cluster coordinator, gossip protocol and consensus layer. Cross-provider or multi-region movement is a migration with explicit assumptions. Scale actors where independent state keys justify it, and keep ordinary pure functions and bulk processing outside unnecessary mailbox overhead. ## Marked graph regions and code push Section ID: marked-graph-regions-and-code-push Marked graph regions and code push Live evolution has four distinct modes: development reload, configuration/topology reconfiguration, implementation/state migration, and distributed rollout. Support them separately so a fast development loop does not imply arbitrary production replacement. An updateable region declares stable exported contracts, allowed host capabilities/effects, resource budgets, state schema, protocol version, in-flight-work policy and rollback/roll-forward class. Pure/static code can be replaced more easily than a stateful actor or a protocol participant. Unsafely captured native pointers, host objects and mutable closures cannot cross epochs as if they were portable state. The intended Kotlin/JS + Hermes + FFI update lane is: Build a versioned bundle for an exact supported host/engine contract; retain source maps, module locks and provenance. Validate signature, target/policy eligibility, imports/exports, grants, limits and state/protocol compatibility. Instantiate in a separate owned realm/activation; run fixtures and side-effect-free or explicitly isolated probes. Drain or version-route in-flight work at the marked boundary; checkpoint and stage a validated state migration without exposing partially migrated active state. Compare the expected prior epoch and atomically publish the new routing and state ownership within the declared activation domain; route new calls to it and handle old completions by the chosen policy. A migration requiring external commits uses its separate reconciliation protocol. Reconcile health, retain a receipt, and use the declared rollback or roll-forward procedure. Shadow execution cannot freely duplicate external effects. A bundle's signature establishes provenance, not correctness; a failed health check cannot reverse an email, payment or incompatible schema migration. Distribution permissions and store policy remain independent of technical host capability, as detailed in section 13. December makes the ordinary edit/build/preview reload loop strong and admits only bounded topology/configuration change; it does not promise the full Hermes module-replacement pipeline. The year-one advanced update experiment should start with stateless marked logic and compatible host APIs, then earn stateful replacement through migration and failure evidence. This is a route to controlled live programmability, not a reason to postpone creating real apps. See lifecycle, actor model, distributed actors, graph migration and FFI design. ## 10. Formal methods and simulation as everyday development tools Section ID: 10-formal-methods-and-simulation-as-everyday-development-tools 10. Formal methods and simulation as everyday development tools Reaktor's opportunity is to make verification reusable at the same level as composition. A module can bring its own invariants and failure fixtures; a graph can expose the assumptions joining modules; a compiler can report a counterexample; an agent can repair against that concrete obligation. Most users should experience this as better diagnostics and dependable behavior, not a requirement to become verification researchers. ## Match the method to the claim Section ID: match-the-method-to-the-claim Match the method to the claim Claim Appropriate evidence Boundary that must remain explicit Identity, port/cardinality, containment and patch laws Deterministic validators, property tests and selected pure proofs The finite model and parser/validator implementation being checked Actor ownership, admission, shutdown and concurrency State-machine tests, scheduler/interleaving tests and linearizability checks where applicable Modeled transitions and actual mutable/foreign-code escape paths Protocol progress, retry/cancel/migration behavior Bounded state models, generated traces and implementation conformance Failure assumptions, bounds, fairness, external services and versioned histories Codec/FFI correctness and memory safety Independent differential oracles, fuzzing, sanitizers and ABI conformance Exact language/runtime/architecture/buffer profile Capability selection and graph rewrites Constraint checks, counterexamples and old/new behavior comparisons Hard requirements, permitted degradation and semantic assumptions Policy/effect enforcement Negative access tests, mediated handles, isolation and runtime monitors Every real entry/effect path needed for the asserted policy Product behavior and visual quality Independent journeys, device/browser tests and user review Generated tests alone are not an independent acceptance oracle These methods are complementary. There is no total ladder in which a proof about a model automatically outranks missing implementation coverage. Declarations describe intent; static analysis constrains an analyzed program; runtime mediation enforces controlled effects; isolation contains untrusted execution; evidence records what was established. An effect annotation or a ModeledNode marker cannot prevent arbitrary Kotlin/C++ code from performing IO or mutating captured state. Strong profiles need restricted construction/APIs, source/build checks, mediated handles and real process/host isolation when appropriate. An opaque module remains useful. Only claims that depend on its unproven behavior inherit that assumption; unrelated structural facts remain valid. ## A practical chain from specification to runtime Section ID: a-practical-chain-from-specification-to-runtime A practical chain from specification to runtime Start with small executable laws and a finite obligation registry. Use graph constraints to reject invalid compositions. Use a bounded protocol model to generate legal and failing traces. Replay those traces through the actual runtime and adapter harness. Keep independent/reference implementations where bugs in a generated checker and generated implementation could otherwise agree. TLA+/Quint suit temporal and failure interleavings; Alloy can explore finite structural counterexamples; Lean can establish selected pure preservation laws once the model is stable. Choose the smallest useful portfolio rather than make every tool a launch dependency. Conformance is the bridge from model results to shipped code. Quint documentation, Formal Methods design. A finding identifies the violated property, minimal relevant graph/trace, source locations, selected contracts/profiles, assumptions/bounds, tool versions, revision and reproduction command. It distinguishes failed, unknown, incomplete, stale and inapplicable evidence. An agent should be able to repair the exact failure without guessing what a red badge means. Useful core obligations include path-sensitive authority reachability; deterministic wiring and atomic local publication; no stale-epoch state mutation; accepted-message disposition; non-amplifying authority; sound capability selection; incremental/full-analysis agreement; and source/contract correspondence. Counterexamples such as “retry repeats a charge” or “revoked camera permission is cached as granted” should become reusable regression assets. ## Deterministic scenarios over the actual composition Section ID: deterministic-scenarios-over-the-actual-composition Deterministic scenarios over the actual composition Inject time, randomness, scheduling decisions and effect outcomes through explicit host interfaces. The same declared composition can then run under production adapters or a scenario interpreter with virtual time, seeded failures and controlled delivery. Record operation IDs, message order, state revisions and effect completions so a failure can be minimized and replayed. The long-term target is a multi-runtime simulation that preserves protocol and domain semantics while virtualizing hosts. Native compute can run through a qualified deterministic implementation, an independent oracle or an explicitly abstracted boundary. Uncontrolled clocks, external models and opaque device behavior prevent complete deterministic replay; record their inputs/results or show that coverage is absent. Simulation fidelity must be tested against real targets. Make counterfactual exploration a normal product feature: change the network, revoke a grant, slow a consumer, duplicate an event, restart an actor or replace a module, then inspect the affected journey. Performance visitors can compare placements and batching strategies inside that scenario, followed by real profiling before promotion. ## Evidence composes and expires with its assumptions Section ID: evidence-composes-and-expires-with-its-assumptions Evidence composes and expires with its assumptions An assurance record binds claim, scope, method, result, assumptions, bounds, source/artifact/toolchain/profile digests, coverage, provenance and freshness. Its dependency graph identifies which changed inputs invalidate it. A result for an old module or policy must not silently attach to a new activation. Module guarantees hold when their assumptions are discharged in the actual composition and the supporting enforcement/conformance boundary exists. A typed valid app can still implement the wrong product requirement; independent product acceptance remains necessary. December needs real structural/authority checks, named kernel/concurrency regressions, one bounded failure model tied to runtime tests, and a shared finding format. Broader choreography proofs, optimizer equivalence and stateful-update verification follow working semantics and consumer demand. See Formal Methods and Verified Foundations. ## 11. Claude, Codex and an agent-native system interface Section ID: 11-claude-codex-and-an-agent-native-system-interface 11. Claude, Codex and an agent-native system interface Reaktor should give an agent a semantic development environment: the relevant program, available operations, constraints, counterexamples and measured outcomes. Claude and Codex provide planning and generation. Reaktor makes their proposals easier to ground, compose, check and execute, and keeps those benefits when models improve or change. ## A richer interface than isolated tool calls Section ID: a-richer-interface-than-isolated-tool-calls A richer interface than isolated tool calls MCP is a distribution interface for tools and context. A2A is an interoperability interface for agent tasks and artifacts. Under both, Reaktor should expose its own versioned domain protocol: scoped snapshots, queries/subscriptions, typed proposals, validation findings, change plans, execution handles, cancellation and receipts. A client that only supports ordinary MCP still gets useful tools; a richer client can subscribe to a changing graph slice and negotiate typed capabilities without a new natural-language explanation for every step. An A2A task maps to a Reaktor mission/run, artifacts map to versioned source/evidence/proposals, and status updates map to run events. Task completion does not confer deployment authority. Agent cards and advertised skills help discovery; local policy decides which operations and data are accessible. Pin and test protocol versions and optional capabilities rather than treating a protocol logo as compatibility. A2A specification. The common interaction is discover → query an authorized snapshot → receive a scoped context packet → propose → normalize/check → repair from findings → prepare an exact plan → execute under the required authority → observe/reconcile → retain a receipt. CLI, IDEs, Studio, MCP and A2A must use the same operation contracts. The existing read-only MCP tools are a starting point, not the full execution broker. ## Make each unit of context do more work Section ID: make-each-unit-of-context-do-more-work Make each unit of context do more work A context packet should include selected entities/revisions, owners, relevant source spans, contracts, capability choices, dependency and impact slices, protocol obligations, recent traces, verification results and unknowns. A query records why each item was included. Authorization is applied before disclosure, including to graph metadata and logs. Size/time budgets and incremental updates let the agent maintain a useful working set across long projects. The next improvement is obligation-directed development. A requested feature becomes product journeys and a typed change plan. The checker turns unresolved requirements into specific obligations: a missing provider, a forbidden effect path, a state migration, a protocol branch or a platform fallback. Claude/Codex implement those pieces, and the engine determines which obligations are now discharged. The model still exercises judgment; the machine-checkable portion of acceptance becomes stable and reusable. Parallel agents work on explicit source/semantic scopes against a common base revision. Their proposals carry dependency read sets, changed owners and affected obligations. Independent changes can merge; conflicting assumptions require revalidation or human resolution. Budgeted child runs inherit narrower authority and return artifacts, never ambient production credentials. A second model's approval remains review evidence, not a correctness proof. ## Acceleration that compounds across model generations Section ID: acceleration-that-compounds-across-model-generations Acceleration that compounds across model generations Each successful change should leave a reusable asset: a lawful module, better recipe, counterexample, migration, adapter, diagnostic or conformance test. Each failure should reduce repeated work by improving a check or exposing a missing assumption. Reaktor's accumulated value is the amount of difficult behavior its users no longer need a model to reinvent. Measure that claim with matched-model experiments: how much does adding the graph, recipes, capability solver or simulator improve completion and reduce repair cost? Measure context construction and validation overhead too. A subsystem that consumes more time than it saves should be simplified or kept out of the common loop. Memory is a projection of source-backed decisions and evidence with scope, revision and supersession. External documents, retrieved text, logs and comments cannot change policy or approve their own requests. Local edits and previews use proportionate standing grants; sensitive reads, paid provisioning and consequential external effects have their appropriate boundary. ## AI inside the generated application Section ID: ai-inside-the-generated-application AI inside the generated application Model calls, prompts, retrieval, tools, evaluators and agent behaviors become modules with typed input/output, data-access policy, budgets, cancellation, versioned configuration and evaluation fixtures. Put uncertain reasoning inside explicit boundaries and use ordinary actor/protocol/state mechanisms around it. A schema-valid answer is still a model output; business rules and irreversible effects require their own checks. A small specialized model is a later optimization candidate for graph retrieval/ranking, intent-to-DSL suggestions or diagnostic selection. First gather consented training/evaluation data and demonstrate a persistent bottleneck against retrieval and existing models. Require measurable quality, latency, cost and maintenance gains before training. Do not make a new foundation model a prerequisite for Reaktor or a substitute for Claude/Codex. See agentic tooling, Koog workbench, Koog agents and browser/local AI. ## 12. Flows, choreography and the opinionated data/cloud stack Section ID: 12-flows-choreography-and-the-opinionated-datacloud-stack 12. Flows, choreography and the opinionated data/cloud stack Reaktor should make distributed behavior composable without erasing where it runs, where state is authoritative or what failures are possible. The graph provides a shared description; protocols and adapters give each relationship its execution meaning. ## Values, requests, durable work and conversations Section ID: values-requests-durable-work-and-conversations Values, requests, durable work and conversations Mechanism Meaning Reactive flow Local or bridged values/events with declared hot/cold behavior, buffering, subscription and cancellation Service request Typed request/result, identity, deadline, authentication, retry eligibility and transport failure Actor mailbox Accepted messages serialized against an owned state transition model Durable workflow A coordinator owns progress, timers, retries and compensation across steps Choreography Independently owned roles follow one legal conversation contract Mesh/session Live peer/media/data interaction with explicit membership, loss, congestion and reconnection Platform work An OS/host gives opportunities to run under its background/lifetime constraints Compile these mechanisms onto existing hosts and transports. They share identities and contracts, but a Flow is not durable history and a mobile work scheduler is not an exact distributed deadline. A protocol facet declares roles, stable steps, payload schemas, branch owner, observable choices, correlation, states, deadlines, retries, authority and terminal outcomes. From a bounded global protocol, generate role-specific state machines, Kotlin/TypeScript bindings, tests and runtime monitors. Reject choices where a participant cannot determine which legal continuation it must follow. For Requester → Approver → Fulfilment, submission persists a request and deadline; approval controls whether fulfilment may start; timeout changes the domain state; a late external completion is reconciled. Active conversations pin a protocol version. Deploy new and old endpoint support together until drain, or perform an explicit protocol-state migration. Multiparty session types provide useful projectability, communication-safety and progress ideas. Reaktor must separately model crashes, timeouts, provider behavior and upgrades rather than assume the theory covers arbitrary callbacks or network failures. Honda, Yoshida and Carbone. Use choreography where several roles independently own decisions; a simple request or centrally owned workflow need not acquire an unnecessary global language. ## Deep defaults, explicit provider semantics Section ID: deep-defaults-explicit-provider-semantics Deep defaults, explicit provider semantics The reference stack remains deliberately opinionated: Cloudflare is central for edge execution, durable coordination, storage and realtime facilities; GCP supplies heavier compute and Pub/Sub; PostgreSQL is the default primary transactional store. This is how a small team can integrate deeply and ship ambitious applications. Replacement is possible through qualified profiles and migration work, not a promise that every provider is equivalent. Component Reference role Semantic contract to expose Cloudflare Workers Edge APIs, auth, lightweight services, preview and bindings Host lifetime/resource limits, effect authority and deployment version Durable Objects / Reaktor actors Per-key coordination and a managed host for compatible durable actor profiles Owned state, transaction scope, async interleaving, activation and timer semantics GCP Compute Engine + k3s JVM/native services, heavier compute, containers and isolated build workers Region/failure domain, resource ownership, health, rollout and recovery PostgreSQL, hosted initially through Supabase where convenient Primary domain records, transactions and supported inbox/state/outbox Tenant constraints, isolation, conflict/retry policy and migrations ClickHouse OLAP, events and analytical CQRS projections Event/version identity, ingestion watermark, query semantics and rebuild/deletion policy Memgraph Connected data, knowledge/social graphs and declared graph metadata authority/projections Write owner, tenant scope, source revision, lineage and rebuild policy D1 Secondary/control-plane operational records near Workers Adapter-specific transaction/read-session profile and explicit separation from primary product records R2 Files, media, artifacts, exports and snapshots Object/content identity, ownership, checksums, retention and publication metadata GCP Pub/Sub Durable fanout and independently consumed events across systems Subscription mode, ack/retry, replay retention and configured ordering scope Cloudflare Queues Internal edge/background work and worker-to-worker jobs At-least-once delivery, explicit retries/poison handling and no assumed global ordering Local ObjectDB and platform work Device state/cache, offline intent and scheduling opportunities Account-scoped storage, conflict semantics and OS lifetime constraints WebRTC / TURN / SFU / mesh Realtime peer/session and media paths Session identity, membership, credentials, congestion and loss behavior A DO is valuable because it combines keyed coordination and storage, not because all Redis workloads are actors. Prefer actor ownership where the domain benefits; a bulk ephemeral cache or specialist data structure can remain a separate qualified adapter when justified. Cloudflare documents asynchronous interleaving and its storage/lifetime rules, so a single-threaded host still needs the declared actor transition discipline. Durable Object rules. Keep Supabase convenience separate from database semantics: using PostgreSQL allows a deliberate move to another hosted service or a managed k3s deployment with migration, backups and operational work. GCP can similarly be replaced with another qualified compute provider. Kubernetes improves deployment portability, but storage, identities, networking and regional services still require explicit migration. The plan does not assume that running every database yourself is cheaper or easier. ## One authority per datum, explicit projections and completion Section ID: one-authority-per-datum-explicit-projections-and-completion One authority per datum, explicit projections and completion The default business path is authenticated command → authoritative transaction plus outbox → durable event/job → idempotent or reconciling consumer → projection/external effect. A DO-owned coordination aggregate or a deliberately Memgraph-owned document can have its own authority; “Postgres primary” does not mean two stores may both silently own the same state. Keep external IO out of transactions that may retry. PostgreSQL isolation/serialization behavior is a selected adapter profile, not a universal default guarantee. PostgreSQL isolation. Avoid synchronous triple writes to Postgres, ClickHouse and Memgraph. Projections retain source offsets, reducer versions, lag and rebuild procedures. Authorization-critical decisions use an authority/freshness contract that actually supports them. Object publication stages a blob and commits its reference, with orphan cleanup and reconciliation; strong R2 object consistency is not a transaction across all metadata and objects. R2 consistency. Pub/Sub ordering depends on subscription/key/region conditions; its optional exactly-once delivery mode does not make arbitrary business effects exactly once. Cloudflare Queues has at-least-once delivery and does not guarantee publication order. A queue bridge must preserve original operation/event identity and prevent loops; order-sensitive actors need an explicit sequencing owner. Pub/Sub ordering, delivery scope, Queues guarantees, Queues ordering. ## Offline and external integrations are first-class behaviors Section ID: offline-and-external-integrations-are-first-class-behaviors Offline and external integrations are first-class behaviors Persist offline intent with original principal/account scope, operation ID, schema and conflict policy. Reconnect revalidates authority and resolves the same logical operation. Logout, account switch, permission revocation, stale reads and a server accepting work just before the connection fails are normal test cases. A generic replication engine should grow from one proven product slice. Razorpay, Zoho, FCM, Meta/WhatsApp and other business integrations should be replaceable typed modules around real provider contracts. Package verified callbacks/webhooks, scopes, rate limits, deadlines, idempotency/reconciliation, fixtures and compensation with the happy-path API. Treat their exact provider behavior as an adapter support matrix that must be verified when implemented. A small generated app uses only the stores and services it needs. Recipes provide working defaults; advanced users can inspect the data authority, deployment cut and provider assumptions as the application grows. See Service, DB and sync, server discipline, bus, mesh, work and notifications. ## 13. Polyglot contracts, FFI and data-oriented execution Section ID: 13-polyglot-contracts-ffi-and-data-oriented-execution 13. Polyglot contracts, FFI and data-oriented execution Reaktor-FFI should become the common contract and data boundary through which Kotlin, TypeScript, C++ and Python implementations cooperate. Its value is broader than RPC: direct local calls, native buffers, asynchronous streams, remote services and dynamic graph modules can share declared contracts, diagnostics and source mappings. The design grows the existing Switchboard work. Contract, Implementation, Endpoint, Call, Buffer and Activation are its core FFI concepts; cells/trunks are execution/connection constructs around them. They reference the graph kernel's identities rather than create a competing ontology. ## One contract compiler, idiomatic language surfaces Section ID: one-contract-compiler-idiomatic-language-surfaces One contract compiler, idiomatic language surfaces Generate a deterministic descriptor from Kotlin declarations first and accept equivalent descriptors from TypeScript/Python authoring frontends. A method declares stable semantic identity, request/result schemas, call shape, allowed runtime profiles, errors, ordering, cancellation, effects, retry eligibility and budgets. Generate Kotlin suspend/Flow APIs, TypeScript Promise/AsyncIterable, C++ task/stream adapters and Python async/AsyncIterator interfaces. Separate stable method/field IDs, schema/layout revisions, negotiated session dispatch indices, artifact digests, activation epochs and call IDs. A compact routing index can accelerate repeated calls without becoming a collision-prone permanent identity. Specify portable values precisely: integer widths/ranges, null versus absence, defaults, enums/unions, byte order, timestamps, unknown fields and errors. Use a lossless representation for 64-bit integers in JavaScript bindings. Arbitrary objects, captured closures, cyclic heaps and nested streams require an explicit supported handle/reference extension; serializable-looking source types are not automatically portable contracts. Unsupported fields must fail generation. A trusted same-runtime call can use generated direct dispatch while preserving its contract and relevant policy/probes. Serialize where a real boundary requires it. The aim of a “superset of gRPC” is a wider useful execution space, including local synchronous/native calls and data views alongside remote RPC/streams. It should not mean reimplementing every gRPC facility or claiming greater performance before measurement. ## Calls and streams with bounded resource semantics Section ID: calls-and-streams-with-bounded-resource-semantics Calls and streams with bounded resource semantics Local synchronous invocation is allowed only for a compatible bounded executor/profile. It must not silently block a UI thread on a network or on a callback that needs the same executor. Remote calls use an explicit asynchronous shape. Executor affinity and reentrancy rules are part of each binding. Support unary, server-stream, client-stream and bidirectional-stream contracts. Stream frames carry direction, sequence, call identity, bounded payload and lifecycle state. Define start, independent half-close, completion/error, cancellation races, late frames and disconnect. Each local call handle exposes one terminal result; the remote business effect can still have an unknown outcome after disconnection. Demand is bounded by both item credit and byte/memory capacity. Account for queued and retained buffers; application consumption, buffer release, network receipt and external-effect completion are different events. Reserve capacity for cancellation/credit/terminal control frames and use fair bounded queues. Shared connections still have contention; isolated latency classes may need separate transports. A cold Flow starts a call on collection unless explicitly shared. A hot state subscription exposes version/current value and conflation; connection state is separate from the application state. Resume requires a validated cursor/checkpoint and compatible producer history. Reconnection alone does not establish durable or exactly-once delivery. Kotlin StateFlow. gRPC byte flow control and Reaktor item/retention budgets cooperate, but are not identical. Test full queues, slow consumers, stalled readers and cancellation while data capacity is exhausted. gRPC flow control. ## The ABI is an ownership and lifecycle contract Section ID: the-abi-is-an-ownership-and-lifecycle-contract The ABI is an ownership and lifecycle contract Use a versioned C-facing function table with fixed-width fields, opaque endpoint/call/buffer handles and explicit status results. Keep C++ STL types, language exceptions, Kotlin objects and platform-dependent long out of the portable ABI. A borrowed input lives only for the documented synchronous call/callback. Queuing it requires a retain or copy. An owned immutable buffer is freed through its producer's allocator after the last retained view/lease releases it. Async send success establishes that the runtime acquired its retain/copy, not that execution completed. Failed submission leaves caller ownership intact. Close stops admissions, drains/cancels by policy, fences scheduled callbacks and signals a completion barrier before callback context or engine destruction. Buffer leases and activation leases are separate: bytes may outlive retired code if their owner survives, but live JSI objects cannot outlive their runtime improperly. Arenas are reclaimed after the final lease, not merely when one batch callback returns. Translate ordinary exceptions into stable boundary errors. An in-process native memory fault can terminate the process; only an appropriate supervisor/isolation boundary can turn that death into a recoverable endpoint failure. Wire peers send bounded bytes, offsets and negotiated region tokens—not trusted native pointers or allocator instructions. Kotlin/Native scoped allocations and callback references have explicit lifetimes. Kotlin C interop. ## FlexBuffers remains central; different data shapes get suitable lanes Section ID: flexbuffers-remains-central-different-data-shapes-get-suitable-lanes FlexBuffers remains central; different data shapes get suitable lanes Data lane Representation Why it belongs Flexible Validated keyed FlexBuffers plus schema-aware contract checks Evolving records, configuration, tool arguments and inspectable binary payloads Typed record Generated field access over a negotiated compatible layout Frequent small records and commands with low lookup/boxing overhead Bulk Typed segments, arrays/strides or column batches with explicit shape, alignment and ownership Media, sensors, analytics and model inputs where per-element objects are expensive FlexBuffers offers direct access without materializing an entire object and supports typed vectors. It does not make every source value or numeric vector identical to a native memory layout. Validate actual widths, bounds and representation before exposing a typed view. FlexBuffers documentation. For compatible analytical batches, an optional Arrow C Data Interface adapter can preserve arrays across C++/Python boundaries. Its producer/release contract is useful in-process; it is not itself the network transport. Do not impose a full columnar stack on scalar methods. Arrow C Data Interface. Keep adjacent compute kernels in a suitable data layout, batch FFI crossings and expose conversion/copy boundaries to profiling. An optimizer can propose a fused C++ kernel or bulk Python operation, then validate equivalence and measure it. This makes data-oriented design available across languages while leaving the best execution strategy workload-dependent. “Zero-copy” is a property of a particular handoff with compatible representation, lifetime, access rights and host support. TLS/network stacks, heap conversion, strides or object materialization may still copy. The current Kotlin hot reader consumes ByteArray; a JNI direct buffer alone does not make it read native memory. Add measured specialized readers/accessors while retaining a safe copy path. Validate untrusted input before unchecked hot access, and preserve the validity assumptions afterward. A writable JavaScript ArrayBuffer can invalidate a validated native view; TypeScript readonly is not memory protection. Use controlled immutable host access, a sealed copy or a proven exclusive transfer for untrusted modules. Report bytes copied, retained memory and boundary cost instead of advertising universal zero-copy. ## Supported transports are named profiles Section ID: supported-transports-are-named-profiles Supported transports are named profiles Boundary Implementation direction Important difference Kotlin/JVM or Android ↔ C++ JNI shim over the shared ABI; direct/native buffers where proven JVM heap, thread attachment, lifecycle and callback rules Kotlin/Native ↔ C++ C ABI/cinterop and explicit borrowed/owned handles Native runtime internals and C++ ABI are not the public contract Kotlin-JS / TypeScript ↔ Hermes Generated host imports and JSI on an owned serialized executor Engine/JS feature compatibility, runtime-thread access and destruction barriers Process ↔ process / remote service gRPC async profile first; measured local socket/shared-memory extensions later Authentication, framing, restart, disconnect and real deployment cuts Browser / HTTP HTTP unary, server-event subscription and an explicit duplex adapter when needed Browser/proxy transport capability is narrower than the abstract call palette Kotlin/JS ↔ Kotlin/Wasm Generated exports/bridges for a pinned host/compiler profile Kotlin Wasm-GC objects are not ordinary C linear-memory objects Flutter / Dart Typed binary platform channels; optional dart:ffi native lane Isolate/thread scheduling, serialized messages and native callback lifetime Python Async worker/service package first; optional native/bulk extension Interpreter/dependency lifecycle, thread state and packaging matrix The official gRPC-Web implementation documents unary/server streaming rather than universal client/bidirectional streaming. Generate a capability diagnostic or choose a supported duplex path. gRPC-Web. Pin and test the Kotlin-JS, bundler, Hermes and JSI combination. Verify exports, BigInt/Long representation, microtasks, timers and error/source maps using actual generated artifacts. Kotlin-JS export support is not a Hermes compatibility certificate. Kotlin/Wasm and Kotlin-JS/Hermes are separate runtime profiles with different memory/host assumptions. Kotlin-JS interop, Wasm-JS interop. Flutter binary channels and a C ABI can expose the same semantic contract through different execution paths. Callback resources must remain alive until the receiving isolate runs them; close fences native callbacks before destroying their Dart target. Flutter channels, Dart callback lifecycle. ## A practical breakthrough for Python Section ID: a-practical-breakthrough-for-python A practical breakthrough for Python Do not make access to Python's ecosystem wait for transparent Kotlin/Python heap interop. Publish a normal Python package with generated DTOs, errors, async clients/servers, bounded concurrency, cancellation and graph lifecycle. A developer can attach a scientific/ML worker as an ordinary capability and immediately use it from Kotlin, TypeScript or C++ through the declared process contract. Then optimize the expensive data boundary: compatible buffers/column batches, batching and an optional native wheel over the same ABI. A Kotlin/JVM implementation still needs a JVM bridge or service; ctypes cannot turn JVM objects into C functions. Qualify OS/architecture/Python versions and real dependencies instead of inferring mobile support from a desktop wheel. An extension acquires the proper interpreter thread state before touching Python objects and uses event-loop-safe completion. Buffer views keep their exporter/lease alive, validate dtype/strides/byte order/mutability and release exactly once. CPython thread states, Python buffer protocol. The architectural gain is one module contract across process and optimized local profiles. Applications can gain Python's expressive reach first, then choose tighter integration based on measured latency, memory and deployment needs. ## Code push has a host contract and a distribution profile Section ID: code-push-has-a-host-contract-and-a-distribution-profile Code push has a host contract and a distribution profile A marker identifies a module boundary and its transitive dependency closure, not an arbitrary live object. Extract a standalone Kotlin-JS artifact with generated host-capability imports; reject platform-only dependencies and uncontrolled bootstrap state. New native capabilities require a new native host release. Section 9 defines staged activation, state/epoch handling and recovery. Hermes is not process isolation against native faults. A hard timeout requires a proven interrupt mechanism or host/process isolation; a timer scheduled on the same blocked JS executor cannot stop an infinite loop. Public untrusted modules must receive only the capabilities and execution budget the selected host can enforce. Keep development reload, owned web/server deployment and public mobile code delivery as distinct profiles. Apple's current review rules restrict downloaded code that changes functionality and place conditions on permitted software categories/native API exposure. Google Play distinguishes prohibited executable self-updates from certain interpreter/VM paths, which must still meet its policies. JavaScript alone does not authorize arbitrary native-capable updates. An ineligible update uses a normal signed app release while retaining fast development iteration. Apple guidelines, Google Play policy. Recheck the actual app/profile and current rules before distribution. ## Evidence and sequencing Section ID: evidence-and-sequencing Evidence and sequencing The first supported FFI boundary needs schema/ABI negotiation, validation, ownership and close/cancellation tests from the start. Prove one useful call profile before expanding streams and hosts. The baseline source has substantive FlexBuffer/compiler/native work, but transport operations, generic argument decoding and stream semantics remain incomplete. Use a growing golden workload: Kotlin ingests events, C++ computes a batch, eligible Kotlin-JS logic applies a policy, optional Python performs an analysis, and a UI observes versioned state. Add placements/languages one at a time; exercise slow consumers, malformed data, cancellation, provider loss and an update while work is active. Measure scalar, record, bulk and streaming workloads in release builds: latency distribution, CPU, allocations, copy counts, retained bytes, queue bounds, event-loop stalls, artifact size and update interruption. Compare with handwritten bridges and ordinary protobuf/gRPC on the same hardware. Historical codec results do not establish integrated runtime performance. The October review supplies measured codec evidence and four open correctness repros; those gates precede adoption. The full wire-to-mutable-memory book informs the separate mutable lane; LiveFlex is a proposed engine, not an implemented feature. See FlexBuffer implementation, FlexBuffer improvement plan, FFI, FFI design and performance/observability. ## 14. Studio, IDEs and tools that gain power from the graph Section ID: 14-studio-ides-and-tools-that-gain-power-from-the-graph 14. Studio, IDEs and tools that gain power from the graph Studio is the Reaktor engine workspace: a powerful development environment for authoring, composing, debugging and operating a whole software system. Its common graph connects product features to source, behavior, modules, runtime islands and cloud resources. Persistent source, Blueprint, preview and diff editors let a developer work with those representations together. Conductor is an optional integrated tool alongside the editors; conversation is one entrance to creation and continued development. Missions, Graph, Changes, Runs, Evidence and System organize tools and saved perspectives within that persistent workspace. They are not mutually exclusive full-page modes. Project and symbol navigation, Details, run configurations, debugging, the Engine Library and programmable commands support direct work. Map, Trace, Validate and Act remain contextual verbs; auth, data, cloud, AI, testing and UI are domain lenses. The canonical super-IDE atlas defines the latest interaction contract for complete greenfield and brownfield workflows. ## Show the representation that answers the question Section ID: show-the-representation-that-answers-the-question Show the representation that answers the question A nested heterogeneous port graph is the underlying structure, not a requirement to display every object and edge. Use containment and semantic zoom to expand a feature into modules, a module into behavior, or an operation into a causal trace. Show dependency maps, choreography sequences, actor mailboxes, state machines, data lineage, source, timelines and diffs as coordinated projections. Project defaults provide workspace, current change, principal and preferred target/environment. Each editor can follow or pin its own source/definition revision, activation, time and scope; each run retains the immutable configuration and artifacts of its attempt. A historical trace and current source can remain open together without a global selection relabeling either. An engineer should select a slow screen, find the responsible operation and external dependency, open its profile, make a scoped change, and see the resulting evidence without reconstructing context. Large fleet views need authorized summaries and missing-coverage indicators, not a global object download. A product author should be able to ask “why is this action disabled?” and get the missing capability, authority or data precondition, the selected fallback and the relevant source. “What would move offline?” should show supported local behavior, new state ownership, conflict policy and the tests it introduces. “What if this service fails?” should open a bounded scenario before it offers a production action. ## Integrate tools through semantic contracts Section ID: integrate-tools-through-semantic-contracts Integrate tools through semantic contracts Specialist surface What the graph adds Reviewable artifact IntelliJ IDEA and VS Code family Definition/port navigation, capability explanations, cross-language contract errors, impacted tests and graph/source selection Source diff, diagnostic and exact build/run context Debuggers and profilers Trace-to-node/source/epoch mapping, actor mailbox waits, FFI boundary cost and deployment-cut latency Profile/trace linked to artifact, inputs and sampling coverage Tests, benchmarks and fuzzers Scenario selection from changed contracts/effects; reusable failure fixtures; budgets by product journey Test result, minimized counterexample, benchmark distribution and regression attribution Database and analytics tools Authority/projection distinction, schema dependencies, migration impact and query/trace correlation Reviewed migration/query, data lineage and freshness evidence Build, CI and deployment tools Exact module/target closure, toolchain facts, artifact identity and reviewed resource changes Build manifest, deployment receipt and observed reconciliation Design and app-store tooling Component/source mapping, target capability and signing/release constraints Design change, device test result and submission/distribution receipt External business APIs Typed operation, credentials/scopes, rate limits, webhook verification, retry and compensation Validated adapter contract and operation-specific delivery evidence An integration package needs more than a launcher: discovery/schema adapters, query/command definitions, source mappings, effect policy, errors, version compatibility and a conformance fixture. Start with a small depth-first set; a deep profiler or deployment adapter is more valuable than a catalog of unconnected logos. IntelliJ and VS Code extensions should be thin clients of a local/remote Reaktor project service and the shared schema. Use their existing source language services, debuggers and diff/review mechanisms. Keep Reaktor semantic diagnostics distinct from compiler diagnostics and preserve source mappings through generated wrappers. The first release can offer navigation, diagnostics and task/context handoff before complete visual editing in both IDEs. ## A worked north-star scenario Section ID: a-worked-north-star-scenario A worked north-star scenario Consider a field-service product with a customer portal, technician mobile app, dispatcher workspace and AI-assisted report drafting. This is a target demonstration, not a claim about a current shipped recipe. A user creates its journeys and visual identity. The composer selects auth, roles, tasks, files and notifications. A capture feature selects a native camera on a phone, upload in a browser, or an explicit unavailable state; offline submission records intent without pretending approval completed. A job actor owns progress. A choreography defines customer submission, assignment, capture, review and notification, including timeout and duplicate messages. C++ can process image batches locally; Python can analyze data on a permitted worker; TypeScript supplies replaceable report formatting or routing logic. FFI carries declared calls and buffers; capability and authority constraints determine whether local or remote execution is allowed. The simulator exercises disconnect, reassignment and lost-response cases. A test links the accepted product journey to the actor/protocol implementation. Deployment places the portal and edge endpoints on the reference stack, keeps primary records in Postgres and derives analytics. Later, an approved change to marked report logic is tested against saved scenarios and activated only on a compatible update lane. The developer can trace an unexpected report from UI to actor, native/remote computation, model call, data revision and pushed bundle. This is how the core ideas should multiply one another: the same declarations improve authoring, runtime adaptation, simulation, debugging and continued change. The domain code remains replaceable, and a simpler app uses only the mechanisms it needs. Machine Signal remains the workbench token/component source; generated products own their own design identity. December qualifies the supported creation and continued-development slice: source/composition/preview correspondence, readable changes, actionable checks and real deployment outcomes. The engine workspace is the product direction; full atlas parity, every language service and every advanced debugger are sequenced beyond that bounded release. The desktop experience retains its preview status until its own gates pass. See Desktop Master Plan, visual language, graph UI and performance/observability. ## 15. Build, deploy and operate one reproducible system Section ID: 15-build-deploy-and-operate-one-reproducible-system 15. Build, deploy and operate one reproducible system The developer loop must work from published packages and a clean clone. Reaktor should carry a project from its first local build to production and later migration without depending on closed-source BestBuds, sibling repositories, maintainer credentials or unpublished generated output. ## Build facts become part of the system model Section ID: build-facts-become-part-of-the-system-model Build facts become part of the system model Dependeasy should publish versioned build facts from Gradle/KMP and native configuration: modules, source sets, toolchains, targets, artifacts, generated mappings, task dependencies, tests, budgets and host requirements. npm/Vite, CMake, Xcode, Wrangler and other adapters contribute their authoritative facts. CLI, Studio, CI and agent tools consume the same catalog. Reuse the existing supervised executor and source-definition seals. The product graph and build graph are related, distinct projections. A feature may span several artifacts; one artifact may contain many nodes. Record that many-to-many mapping so changing a contract identifies clients, tests and deployables without rebuilding the entire fleet. Published artifacts, compatible warm caches and incremental compilation are product features: they determine whether prompt-to-preview is enjoyable. Cache keys include toolchain, source, configuration and dependency inputs. Generated files should be deterministic; timestamps and local paths belong in provenance rather than semantic content hashes. Verify artifact existence and digest after a successful command. ## Compile deployment boundaries with their costs Section ID: compile-deployment-boundaries-with-their-costs Compile deployment boundaries with their costs The planner maps required capabilities and state authorities onto declared runtime islands and existing infrastructure. Begin with explicit placement and explainable checks, then add cost/latency suggestions from observed workloads. An automatic move must preserve protocol, data-residency, authority and failure constraints and go through the normal change path. Local calls, actor sends, remote requests and durable events have different semantics and costs. A graph edge crossing a deployment cut should reveal the introduced transport, latency, retries, authentication and data movement. This lets Reaktor explain why a composition is expensive and suggest batching, colocating a reducer with its state, or moving a pure compute kernel, with measurements to test the suggestion. Keep schedulers and infrastructure controllers authoritative for what they operate. Reaktor plans and reconciles through adapters; it does not replace Kubernetes scheduling or invent a second distributed desired-state controller for every resource. Customer-owned environments can later attach through scoped outbound agents with explicit identity, revocation and supported operations. ## Release and recovery are graph operations with real state Section ID: release-and-recovery-are-graph-operations-with-real-state Release and recovery are graph operations with real state A release receipt links source/dependency locks, build provenance, artifact and configuration digests, approved effects, executor identity, tests and post-deploy observations. Secrets are resolved at the execution boundary, not embedded in manifests or agent context. Tenant isolation, account switches, credential revocation and sensitive telemetry are tested as normal system behavior. Rehearse backup restoration and recovery for the actual state authority. A source rollback, code rollback, schema rollback and external-effect compensation are different operations. Plans must name the one they support. Native signing and store submission remain target-specific steps; acceptance by a build pipeline is not a store approval or proof of correct device behavior. Maintain budgets for first preview, incremental change, startup, memory, binary size, graph/query overhead, p95/p99 application latency, FFI crossings, deployment recovery and total model/build cost. Each budget names workload, hardware/runtime, measurement method and allowed variance. Optimization proposals carry both a profile and a behavioral conformance result. A faster implementation is promotable only if it preserves the contract being relied on. See build tools, Dependeasy, CLI, DevOps, cloud control and shadow environments. ## 16. Current system map and intended progression Section ID: 16-current-system-map-and-intended-progression 16. Current system map and intended progression “Source present” below means meaningful implementation was inspected. It is not a fresh build, deployment or production-readiness verdict. “Partial” means the implementation and target contract differ materially. Dates describe proposed sequencing. System September 2026 baseline December v1 commitment Following nine months Greenfield Composer Implemented Compose UI, five-step navigation and guarded local prototype states; inspected Create system path changes state, without generation, agent execution or real provisioning Empty-project brief→design→real web app→preview→deploy→follow-up change for supported app classes More domains, richer visual programming and increasingly complex generated systems Creation workspace/runner Existing tooling/auth/build substrate; isolated hosted creation sessions require implementation One managed browser creation lane and compatible local path; resumable bounded jobs, isolated previews and bounded Android/iOS build execution Collaboration, improved cold starts, expanded native build/distribution automation and more environments Product design authoring Substantial design systems/prototypes and native components; no general design-to-behavior fidelity guarantee Distinctive app tokens, editable screens/components, real bindings and visual/journey verification Richer assets, motion, responsive/native parity and design-tool round trips Full-stack recipes Working mechanisms dispersed through products/modules Small versioned recipe set for identity, data, UI, workflow and integration; custom-code escape Independent recipes/modules with conformance, upgrades and broader app classes Semantic kernel Mutable runtime and separate editor/architecture models; canonical IR designed Minimal versioned manifest, portable identity, explicit ownership and deterministic validation for the reference slice Extensible semantic interfaces, incremental compilation and federated projections Runtime/ports/lifecycle Substantive code; partial wiring and lifecycle/ownership defects remain in inspected paths Repair or exclude release-blocking paths; validated prepare/publish boundary and compatibility facade Transactional local reconfiguration and complete activation/epoch correspondence Actors Local mailbox, supervision, timers and persistence hooks; child-work/state and durable-scope gaps Owned local transitions, admission/deadline/close outcomes and stale-completion tests One durable profile, then qualified placement/migration experiments Services/auth Substantial dual-surface implementation and Worker JWT enforcement Published usable APIs, generated client path and tested authorization boundaries Contract evolution, richer policy composition and mediated effects Object DB/data Local stores/raw backups, graph gateways and real product integrations One declared authority, migration and retry-safe reference workflow Product-proven offline intent/sync and additional descriptors Flow/editor GraphDocument/session, layout and runtime views Source-linked inspection and bounded owned-composition editing Broader round-trip authoring and richer semantic debugging Tooling/CLI Discovery, task models and supervised execution exist Independent public CLI, same schema/broker across surfaces More adapters, remote sessions and incremental context Desktop/MCP Native shell and five read tools; some catalog/fixture surfaces coexist Golden journey, proposal/validation API, governed execution through shared broker Richer missions, model checking and multi-agent coordination Reaktor web Compose prototype slice, distinct from desktop Real public creation client over shared project/session APIs; clearly separate any remaining prototype views Deeper collaborative editing and advanced workbench parity where useful Machine Signal Fixed dark runtime tokens; expanded design themes in Pencil Readable, accessible core journey and truthful evidence states Theme/token convergence and higher-value atlas surfaces Build/release Composite/private coupling, manual CI and uneven target evidence Clean public build, automated scoped CI, reproducible artifacts and support matrix Broader platforms, upgrade automation and build-time budgets Verification Tests/harnesses and source guards; formal layer largely designed Named kernel obligations, structured findings, scoped enforcement and one model-to-runtime failure protocol Protocol projection, simulation, module obligations and selected proofs Telemetry/performance Adapter/report substrate and specialized harnesses Correlated reference-slice traces and measured budgets Cross-runtime causal traces, profile links and performance regression corpus FFI/FlexBuffer Substantive codec/KSP/native work; generic decoding, transport and stream gaps Preserve working codec lanes; contract/ownership fixtures and explicit experimental FFI status Conformant C++ call and Python service profiles; streams and specialized buffers advance after conformance and capacity gates Security/secrets Real auth/secrets; MLS++ native core; platform secret boxes incomplete Harden supported auth/operations; exclude incomplete encryption claims Secure storage and protocol persistence before encryption readiness Bus/mesh/work Platform work and specific realtime/PubSub integrations; generalized runtime designed One transaction-backed retry/outbox workflow with explicit effect outcomes Reusable durable adapter, bounded choreography and one scoped mesh use case AI modules Product bot/moderation and design proposals; no universal AI runtime Claude/Codex workflow plus one typed, evaluated model-call example Retrieval/tool/eval modules with budget and data-policy conformance Cloud/fleet Source-discovered tooling and existing k3s/Worker/data paths One reproducible opinionated deploy/observe/recovery lane Qualified environment attachment, explicit data authority and measured placement Visitors and incremental queries Existing DFS/BFS/selectors and telemetry hooks; traversal/path and lifecycle contracts differ Typed Analyze/Rewrite boundary, explicit traversal semantics and path-sensitive regression case Incremental/full equivalence, reusable transforms and dynamic observation coverage Feature/capability Global Feature registry and adapter/capability interfaces; general resolver designed Scoped host/session context and two explicit fallback/permission strategy families Multidimensional planning, runtime adaptation and measured placement choices Compiler/source correspondence Active FlexCoder KSP generation; old Promise processor disabled; general graph/effect compiler absent Deterministic descriptors/source maps and failure on unsupported declarations for the release slice Restricted-profile analysis, richer Blueprint lowering and idiomatic language frontends Choreography Design documents and product-specific conversations; general projector absent Explicit finite workflow/protocol states for the chosen app flow One three-role projector, endpoint monitors and active-version conformance Marked Kotlin-JS code push Hermes/native bring-up and design; complete extraction/activation pipeline absent Development reload and isolated compatibility spikes, with no blanket production OTA claim Stateless owned-host replacement first; stateful/mobile profiles separately gated Python No first-class Reaktor Python runtime/SDK found in the surveyed source No stable Python interop promise; preserve language-neutral contracts Normal async worker/service package; optional measured native/bulk lane Products BestBuds, Manna, GymBuddy and smaller consumers prove different seams Public independent example plus regression slices from internal products External adopters, third-party modules and new domain recipes ## 17. What public v1 means Section ID: 17-what-public-v1-means 17. What public v1 means December v1 is a greenfield app builder backed by a usable runtime and development engine. A user must be able to start from an idea, create a functioning full-stack application, deploy it, own its source, and continue changing it. An SDK release, graph inspector or template launcher alone does not satisfy this promise. It includes a stable core package set and explicitly experimental extensions; it does not declare every existing module or platform stable. The stable launch lane is browser-based creation of responsive multi-user web apps with real auth, persistent data, custom behavior and one asynchronous/integration path. A local developer mode exercises the same project and runtime contracts. Native creation is a required parallel product lane: December must demonstrate generated Android and iOS projects and real device previews for a bounded recipe; broader native support is labeled preview until its own build, capability and distribution gates pass. The target for promoting the native lane is March 2027. Reaktor competes in both web and native creation; maturity is stated separately. Launch scope is two related web recipe classes—a multi-user workspace/portal and a consumer/community or service-coordination product—plus one bounded native variant over the same backend/modules. AI is an optional capability within these recipes. They are representative coverage, not separate hard-coded generators. Tests must include unseen briefs and follow-up changes that exercise custom behavior beyond the templates. The proposed stable set is typed composition/contracts and validation; the supported local runtime/lifecycle/actor subset; service/auth/object-storage boundaries used by the reference application; portable manifests/findings/plans/receipts; and the CLI/agent interface needed for the supported change loop. Unstable integration/UI APIs stay versioned as experimental until their own compatibility gates pass. The public distribution needs an independent repository or package layout for reusable Studio host code now located in BestBuds. Its extraction is a release task: preserve current framework/editor/host ownership boundaries, supply a public reference app, and keep closed product services and data outside the distribution. The user should not need BestBuds credentials to evaluate Reaktor. Proposed launch support is deliberately tiered: Lane December target Release evidence required Public browser creator and managed preview Stable greenfield web journey New user starts from an unseen brief, gets a real working app, deploys, exports and makes a cross-layer follow-up change Kotlin/JVM service/runtime and headless CLI on Linux Supported stable slice Clean CI build, reference app, negative tests, upgrade and recovery exercises TypeScript client/manifest consumption in a normal browser project Supported stable contracts Install from packages, no sibling Kotlin checkout, browser journey and schema compatibility macOS local companion/headless developer path Supported project execution and source ownership on a named tested architecture; full desktop creator UI is preview Open/export project, build, run, validate and use Claude/Codex through the same contracts; browser remains the primary creation UX Android creation preview Required bounded KMP/native recipe demonstration; individual libraries can separately earn stable support Generated app builds/installs; real device capability, denied-permission, persistence and process-recreation journey iOS creation preview Required bounded KMP/native recipe demonstration; stable promotion targeted for March Generated app builds/installs and passes the corresponding real device journey; signing/distribution limitations stated Additional desktop architectures Preview until equivalent evidence exists Explicit tested installer/runtime matrix; no inferred parity from common source Cloudflare Worker and JVM/container deployment Reference adapters with explicit maturity Scoped deployment, observation and recovery tests in a dedicated environment C++ FFI, Wasm, remote actors, generic mesh/sync Experimental Separate manifests and tests; absent guarantees remain explicit This matrix is a September decision proposal. Freeze exact runtimes/toolchains, hardware and module versions by 30 September after clean-build evidence. If capacity is lower than assumed, reduce supported rows early. Do not keep a large support promise and weaken its verification. For the selected December native demonstration, preview means the bounded Android and iOS creation paths actually work with stated limitations; unavailable does not satisfy that commitment. Run the same supported recipe/capability/failure case on both by 30 November. Any reduction to a single native target must be an explicit September scope decision, not a relabeling at launch. ## 18. The release must prove four complete journeys Section ID: 18-the-release-must-prove-four-complete-journeys 18. The release must prove four complete journeys ## Create a real application from an unfamiliar brief Section ID: create-a-real-application-from-an-unfamiliar-brief Create a real application from an unfamiliar brief A new user starts in an empty workspace with an unseen product brief. Reaktor creates a distinctive responsive design, working journeys, real authentication and persistent data, plus the requested custom behavior and one asynchronous/integration boundary. The user can refine a screen visually, change behavior conversationally, run the app as two distinct users, publish a preview and export/rebuild the source. Completion is checked against the brief by independent assertions and human UX review. A second brief exercises the bounded native preview on both Android and iOS, including real navigation, local state, one device capability and its failure path. Native and web clients should share the appropriate service/domain contracts while retaining platform-specific UX. A supplied sample is useful onboarding material but cannot stand in for this creation test. ## Grow the application without throwing it away Section ID: grow-the-application-without-throwing-it-away Grow the application without throwing it away After initial creation, introduce a change the first prompt did not request: organizations and roles, a state/schema migration, a new approval step or another client. Existing test data must survive; unchanged behavior and visual identity must remain intact. The user sees and resolves a deliberate contract/authorization conflict, while Claude/Codex implements the change through normal source and semantic edits. Public reference applications make this reproducible and require no private repository or BestBuds credentials. The managed lane removes local setup friction; the local lane remains independently buildable. A native companion extends shared contracts rather than copying a disconnected backend model. ## Diagnose a failure and recover without duplicating work Section ID: diagnose-a-failure-and-recover-without-duplicating-work Diagnose a failure and recover without duplicating work The scenario injects a lost response, duplicate delivery, process restart and denied access. The developer sees the operation identity, state transition, authorization decision, relevant trace and terminal disposition. A recorded counterexample can be replayed locally. Retrying an accepted operation must not duplicate the tested domain effect, and data belonging to another tenant must remain inaccessible. The model and test boundary must be stated. A simulated external notification cannot establish a real provider's idempotency guarantee. The scenario should include at least one real adapter test in an isolated environment in addition to deterministic simulation. ## Deploy a reviewed revision and establish what happened Section ID: deploy-a-reviewed-revision-and-establish-what-happened Deploy a reviewed revision and establish what happened The developer prepares a plan, sees the target/environment/effects, approves where required, executes the exact plan, and inspects post-deploy evidence. A source or environment change invalidates the previous approval. A failed probe yields an honest partial/failed outcome and a rehearsed recovery action. A stale run never becomes a current health signal. These four journeys are the minimum coherent product. Atlas screen count, module count, a prebuilt sample and generated lines of code are not substitutes. BestBuds contributes actor/auth/messaging regressions; Manna contributes TypeScript/graph-document/auth-boundary regressions; GymBuddy contributes native lifecycle, storage and capability regressions. Existing-project import is an additional compatibility test, not the only entrance under test. ## 19. Roadmap from September 2026 to September 2027 Section ID: 19-roadmap-from-september-2026-to-september-2027 19. Roadmap from September 2026 to September 2027 The delivery team is two primary developers—Reaktor’s original author and Kedarnath—each working with Codex and Claude. Two humans can own complementary lanes and review each other's work; model parallelism still consumes human integration, design and release attention. The proposed split is one lane for creator/design/client composition and one for runtime/data/runner integration. The developers should choose the actual allocation together; this document does not assign personal responsibilities without that decision. Use one shared weekly integration target, two substantial implementation lanes and a single release backlog. Reserve roughly one-third of combined capacity for defects, integration, conformance, documentation and support. These are capacity assumptions to adjust from observed throughput. Agent work should end in an integrated change and evidence against the current revision, not a pile of separately completed branches. Review shared contracts before parallel implementations depend on them. The product critical path remains unfamiliar brief → product/design composition → generated working app → real preview → follow-up change → deploy/export → external user success. Small core improvements belong on that path now: stable contract identity, owned activation scopes, valid wiring, explicit state/effect boundaries and useful findings. Introduce them behind compatibility facades and migrate one generated-app flow plus an internal product flow. A big-bang runtime rewrite, universal compiler or new distributed cluster cannot become a prerequisite for creation. December scope is a stable browser creator for two related web recipe classes, backed by one selected data/deployment recipe, plus bounded Android and iOS creation previews that both actually build and run. Both native previews exercise the same declared recipe and a capability/failure case on their own targets. Broader native maturity can follow; a browser screenshot or success on only one native platform does not satisfy the promised pair. The local companion shares the browser creator's project protocol instead of requiring a second complete authoring UI. Priority and period Outcome Exit evidence and dependency P0 · 7–30 Sep 2026: establish one real creation slice By 15 Sep, select the creator experience, two related web classes, managed runner, authoritative data recipe and bounded Android/iOS recipe. Publish the internal contract sketch for module/actor identity, source ownership, owned scopes and effect outcomes. Characterize current identity/lifecycle/partial-wiring failures while connecting the first generated slice. Empty project produces a designed app with real auth/persistence; clean export builds without BestBuds; release dependency closure and toolchain/support matrix are known. By 30 Sep, the supported path fixes or excludes the characterized unsafe behavior, exposes structured findings and has held-out brief/benchmark fixtures. P0 · Oct 2026: dependable creation and change By 15 Oct, prompt→design→data/workflow preview and scoped follow-up editing work. Complete a transaction-backed command/state/outbox slice, async completion re-entry, capability selection and source/manifest validation for that recipe. Wire one actual deploy/observe path. By 31 Oct, unseen variants work for both web classes; schema and visual changes preserve existing data/behavior; permissions and denied effects are tested; exported source rebuilds independently. First Android and iOS generated recipe projects build, with the first device journey complete and remaining target gaps named. P0 · Nov 2026: prove the complete public product Start external first-time trials by 15 Nov. Finish both bounded native previews, visual iteration, isolation, retry/recovery and deployment. Use one bounded failure model and real runtime trace replay to strengthen the selected workflow. By 30 Nov, all four golden journeys and both Android/iOS capability/failure cases pass for the declared scope; five first-time users attempt held-out briefs; the required success/negative-test gates are met and failures classified. No private source or maintainer intervention is hidden in the public path. P0 · Dec 2026: public v1 Launch the functioning browser creator, stable scoped runtime/packages, Android/iOS previews, public examples/docs and evidence. Feature freeze 1 Dec; release candidate by 14 Dec; public v1 target 21 Dec; 22–31 Dec reserved for release recovery and urgent patches. Every non-negotiable gate applies. If a required lane misses, report the missed scope/release gate explicitly; relabeling a broken preview does not complete v1. P1 · Jan 2027: preserve created apps Fix first-app, cold-start, visual-edit and runtime failures; make upgrades/deprecations and diagnostic support practical. Refine recipes using observed abandonment and repair loops. An external created app performs its first compatible upgrade with design, data and primary journeys preserved. Publish builder/substrate baselines, including losses, and a ranked failure corpus. Stop net-new scope if onboarding or compatibility is still unreliable. P1 · Feb 2027: reusable durable decisions Promote one durable actor/command profile on one authoritative backend: durable admission, atomic inbox/state/outbox, timers, dedup retention, passivation and fenced reactivation. Add finite workflow states and monitors for the same flow. A generated long-lived approval or per-account task survives crash, duplicate delivery, cancellation races and restart with explicit outcomes. State/effects have one authority; stale activations fail closed. No cross-provider actor migration or general cluster is required. P1 · Mar 2027: native and module promotion Promote the bounded native lanes toward supported release status; strengthen TS authoring/client contracts and the module/recipe conformance kit. Android and iOS each pass their declared lifecycle, permission, storage, build/distribution and upgrade gates. One independent developer contributes a module or recipe and upgrades a consumer without private source. A failed platform gate leaves that platform preview, with the reason and next milestone stated. P1 · Apr 2027: one real polyglot boundary Complete a Kotlin↔C++ call profile with stable contract/ABI identity, validated payloads, ownership, error/completion semantics and source mapping. Run it through the same module/capability model. Cross-language golden/fuzz corpus, malformed-input rejection, leak/close tests and a measured workload justify promotion. Streaming, Python in-process embedding and universal target parity remain outside this call-profile claim. P1 · May 2027: conversations and offline intent Project one bounded three-role choreography into endpoint monitors/types/test traces; pin active protocol versions. On the client lane, apply durable intent and conflict policy to one native workflow over the same contracts. Illegal message order and uninformed branch selection produce findings; retry/timeout/version-skew traces conform to the implementation. Offline submit→reconnect produces one logical result within its declared scope; logout, permission revocation and conflicts remain visible. Full multiparty language completeness and generic sync are not implied. P2 · Jun 2027: expand useful integrations Introduce one Python worker/service profile for scientific or AI tasks through a versioned process/service contract, with artifacts, budgets and typed outcomes. Extend capability planning to one customer-owned execution environment using the existing control protocol. A generated app calls real Python work, cancels or reconciles it, retains output provenance and handles unavailable resources. A second environment passes identity/revocation/isolation tests. If both do not fit capacity, choose the one with demonstrated adopter demand; do not maintain two incomplete transports. P2 · Jul 2027: controlled replacement and deeper authoring Pilot signed stateless code replacement in one owned desktop/server runtime after compatibility, authority and rollback prerequisites pass. Improve visual/code/agent edits and impacted checks around the same module boundary. Exact bundle/contract/capability checks, in-flight call handling, rollback and crash/restart evidence pass for the named stateless subset. Stateful replacement, mobile code-delivery claims and arbitrary Python/C++ hot replacement remain separately gated. Visual edits preserve source and semantic identity. P1 · Aug 2027: demonstrate field and ecosystem independence Prioritize external product reliability, recipe/module upgrades, performance and operating cost. Add a narrow proof or stronger conformance claim only where it addresses an observed failure class and links to the shipping implementation. External products survive a compatible release and provider outage; a third-party module upgrades independently; comparative creation/growth results, failures and support ownership are public. No scale or assurance claim exceeds its target, bounds and measured workload. 1–6 Sep 2027: year-one review Evaluate the twelve-month program and choose the next expansion. Compare against September 2026 baselines; retire unhelpful abstractions; promote only proven lanes. Choose the next distribution, choreography, native, Python or performance investment from adoption and maintainer capacity. Priorities define the cut order, not permanent importance. Post-launch dates are forecasts reviewed monthly. The dependency order remains binding: durable actors follow owned local turns and transactional acceptance; choreography projection follows explicit protocol/effect semantics; FFI streams follow call ownership/cancellation; code replacement follows identity, compatibility, authority and recovery; cross-provider placement follows each provider's conformance. Formal methods strengthen these milestones continuously—deterministic checks and executable counterexamples first, deeper models and selected proofs where they earn their cost. Each platform milestone must unlock an observable application capability or improve a difficult follow-up change. Under pressure, cut advanced operator panes, universal visual programming, extra providers/backends, marketplace/collaboration and exotic app domains before weakening the complete creation journey, both promised bounded native previews, data correctness or authority gates. If a gate still fails, publish an honest narrower preview and state the missed commitment; do not substitute an SDK/inspector release for the agreed builder. ## 20. Non-negotiable December release gates Section ID: 20-non-negotiable-december-release-gates 20. Non-negotiable December release gates Every gate is a proposed acceptance requirement. None is reported as passed by this document. Gate Required evidence If it fails Greenfield creation Empty workspace and held-out brief produce a functioning, distinctive app, followed by a cross-layer change Fix or narrow supported app classes; a sample editor or screenshot generator cannot be called this v1 Hosted execution/preview Project isolation, scoped secrets, bounded jobs, cancellation/cleanup, preview access and no cross-project data exposure No safe managed execution means browser v1 is blocked; a local preview cannot silently satisfy the browser promise Native creation claim Android and iOS generated projects build/run, test the bounded capability/failure path and produce the declared artifacts Disclose missed native scope; an unavailable path does not count as the required preview demonstration Public independence Fresh clone/install/build/run using only public dependencies and documented local setup Remove private coupling or reduce the release surface; do not ship a maintainer-only workflow Kernel integrity Regression/property/concurrency tests for port identity, local publication, lifecycle, actor ownership and stale completions; path-sensitive visitor and generated-contract cases Block the affected stable runtime lane Capability behavior Two declared strategy families pass real web/native fallback and permission-change cases; hard requirements cannot silently degrade Fix the strategy or expose unavailable behavior; a misleading success state blocks the claim Authority Tenant/access negative tests, no ambient agent mutation path, exact-plan revalidation and sensitive-output handling Block affected operations; a warning label does not substitute for an authorization boundary Reproducibility Locked dependencies, artifact digest/provenance, declared toolchains and repeatable build instructions Repair build/export path before promising stable distribution End-to-end usefulness Four golden journeys completed by external users without undocumented author intervention Fix the journey or narrow onboarding; a working internal demo is insufficient Failure and recovery Duplicate/restart/timeout tests and one real adapter recovery exercise Do not claim the unproven delivery/recovery guarantee Compatibility Versioned public schemas/APIs, one upgrade exercise, explicit experimental boundaries Keep unstable components outside the stable contract Evidence honesty Source/fixture/observed/unknown distinctions, revision-bound receipts and prototype labeling Remove misleading health or capability claims Operability Install/support guide, issue reporting, security contact and named release owner Finish the operational basics before public 1.0 The date is a forcing function for scope. It does not override a correctness or security gate. If a non-negotiable gate still fails, publish an explicitly labeled preview and report that v1 missed its gate; do not rename an unsafe beta as stable. The working plan is to avoid that outcome by cutting optional scope in September and October. ## 21. Measuring whether Reaktor is winning Section ID: 21-measuring-whether-reaktor-is-winning 21. Measuring whether Reaktor is winning Use two primary outcomes: time to a genuinely usable first application, and verified change throughput as it grows. The second measures accepted changes that satisfy an independent behavior contract per unit of total developer time and cost. Record design/interaction quality, correctness, regressions, human intervention, time, compute/model cost and recovery together. A fast attractive scaffold with broken behavior fails the first outcome; a speed improvement that increases escaped defects fails the second. Publish a benchmark specification and reference briefs. Retain at least six unseen evaluation briefs across the declared app classes, with withheld growth requirements, until each scored run completes; then publish results and rotate the holdouts. Run repeated trials. Test visual quality, real persistence/auth, schema evolution, tenant isolation, duplicate delivery, native capability fallback, deployment recovery and clean export. Existing-project integration is a separate track. Independent assertions and human product review should judge outcomes; do not let the system grade only the tests it generated. Run two comparison tracks. The product track compares Reaktor with Emergent, Rork and other selected builders from the same empty-project brief, time/cost ceiling and target outcomes, using each product's available model and idiomatic stack. Stratify by supported target: a web-only builder's lack of a native lane is a coverage difference, not a failed native-quality trial. Record model differences instead of claiming a controlled same-model experiment when a builder does not expose that choice. The substrate track pins the same Claude/Codex model, configuration and budget with and without Reaktor, giving the baseline competent libraries and specialist tools. This separates whether the product wins from which engine mechanisms contribute. Include cold setup, paid compute/model use, failures and repair/maintenance cost. Initial targets to calibrate during September, rather than advertise as results: First interactive design preview within 10 minutes; first functioning authenticated/persistent journey within 30 minutes; supported deployment within 60 minutes when provider prerequisites are satisfied. Publish cold starts, setup prerequisites and brief complexity separately. Median clean exported-project first-run time under 30 minutes on the supported setup; no BestBuds/private repository credential needed. At least four of five November external trial developers finish the basic journey without unrecorded help. No accepted stale plan or cross-tenant access in the release's specified negative-test matrix. At least 90% completion of the supported golden journey trials by the December candidate, with every failure classified; critical correctness assertions still require 100% pass. By September 2027, demonstrate either a material reduction in total time/cost or higher correct-task completion against a strong same-agent baseline, with no reliability regression. Set the numerical improvement target after collecting the baseline. Also track repeat use, upgrade success, module reuse across products, time to diagnose a failure, escaped regressions, build latency, runtime overhead and context size per resolved task. Stars, generated code volume and polished screenshots are secondary signals. ## Measure the core mechanisms, not only the final demo Section ID: measure-the-core-mechanisms-not-only-the-final-demo Measure the core mechanisms, not only the final demo Run ablations that remove recipe reuse, graph context, capability planning, incremental checks or simulation while keeping the task and agent budget comparable. Record which mechanism increases correctly completed behavior, reduces integration work or prevents a relevant failure. Include its runtime, build and cognitive overhead. Maintain a primitive-coverage matrix across the reference domains: how many mechanisms and custom glue changes are needed to add a new product behavior? Track reusable failure cases, unchanged module reuse, cross-language conversions, memory retained at boundaries and time to make a compatible follow-up change. The desired result is increasing application complexity and verified change throughput without proportional growth in bespoke code, outages or operator effort. Publish uncertainty and cases where a simpler stack wins. ## 22. Adoption, distribution and the ten-year position Section ID: 22-adoption-distribution-and-the-ten-year-position 22. Adoption, distribution and the ten-year position Reaktor becomes a default through repeated creation success, continued usefulness and ecosystem independence. The public creator should make a new idea real. A package should also solve a valuable task in an existing project. Examples should show complete systems; the module format should let another developer add a capability without joining the core team. The release process should let all of them keep upgrading. The recommended public foundation is an inspectable open core with portable schemas, a usable local runtime/tooling path, ordinary package distribution and documented extension contracts. Audit the existing license and all bundled dependencies before choosing release terms; this plan does not silently change them. Hosted collaboration, managed environments, enterprise policy and support can become commercial products without making basic local correctness checks or export dependent on a paid service. Claude/Codex integration should feel native, but the application model should not depend on a single model vendor's conversation format. Reaktor should preserve projects, receipts and invariants when the user changes model or tool. This is how model improvements compound instead of forcing framework migrations. The durable advantage is the combination of lawful composition, real adapters, an executable failure corpus, useful agent context and a trusted compatibility ecosystem. Any individual pane or wrapper is easy to imitate. Maintaining those pieces together across years of application changes is the work that can justify long-term adoption. The first external audience includes founders/designers creating a new product and developers building greenfield apps who want both AI speed and a maintainable foundation. Offer a clear Create path and a professional code-first path into the same artifacts. Existing-project adopters are valuable too, but must not dominate launch messaging. Publish creation examples, a small contract reference, growth/failure-driven tutorials and clear supported/experimental labels. Invite contributors to a recipe, adapter or invariant with a conformance kit, not a sprawling internal backlog. ## Beyond year one: expand the engine's reach Section ID: beyond-year-one-expand-the-engines-reach Beyond year one: expand the engine's reach The ten-year direction is a sequence of earned capabilities, not a fixed calendar of universal promises. First make real app creation and continued growth dependable. Then expand the reusable module/adapter ecosystem and compositional verification. Use those foundations for deeper offline collaboration, scientific/data workflows, native media, independently operated services and device fleets. Eventually, domain-specific execution profiles can bring bounded real-time control or stronger assurance requirements into the same authoring and evidence model. The invariant through that expansion is a compact common core with specialist implementations. Every new domain should contribute reusable contracts, capabilities, protocols or tools back to the engine. Every compiler/runtime optimization should retain the program's meaningful identities and the evidence needed to change it. This is how Reaktor can grow beyond its original analogies without becoming a collection of disconnected products. ## 23. Decisions that keep the vision coherent Section ID: 23-decisions-that-keep-the-vision-coherent 23. Decisions that keep the vision coherent These decisions refine the core design and constrain implementation choices. Detailed subsystem documents retain their useful specifications; where they prescribe incompatible semantics, the decisions below identify what this plan replaces. Each implementation ADR must name its owner, compatibility/migration effect, failure behavior and executable acceptance case. Decision Direction selected by this plan Revisit or promotion gate Core scope and migration Improve identity, contracts, owned lifecycle and mutation atomicity now; introduce the small immutable model through adapters and compatibility facades. Keep provider SDKs, scheduling machinery and product UI outside the pure model. A migrated generated-app flow and internal consumer agree with the new semantics; direct legacy paths have an owner and removal criterion. No big-bang rewrite. One model, explicit artifact owners Share semantic IDs/contracts while source owns algorithms, composition owns declared wiring, providers own applied resources and telemetry owns observations. Define round-trip ownership per field. An import/edit cannot preserve ownership; reject or label the unsupported round trip instead of silently overwriting source. Identity across time and languages Separate definition/contract identity, schema version, logical instance identity, activation epoch and artifact digest. Use portable IDs rather than reflected class names; version aliases and migrations explicitly. Old/current fixtures, renamed source, multiple tenants/sessions and cross-language bindings preserve the intended identity without collisions. Local and durable actor profiles One owned state turn; asynchronous work returns typed completion messages. Local admission is not durable acceptance. Durable profiles add atomic inbox/state/outbox/timers, total message outcomes and fencing. Per-target ownership/fault tests pass; provider placement preserves the declared profile. A scheduler limit or private channel does not establish BEAM-style isolation. Effects, cancellation and recovery Separate operation identity from attempts; declare transaction-local, idempotent-provider, reconcile, best-effort or manual completion strategies. Caller timeout/cancel does not erase a dispatched external effect. Compensation is a new action. Commit/dispatch/ack/cancel crash points have reproducible outcomes; uncertainty is retained until reconciled. No outbox-only exactly-once claim. Flow, workflow and choreography Reactive streams, scheduled opportunities, durable jobs and role protocols keep distinct contracts. Finite choreography projects to role monitors/types/traces; active conversations pin protocol versions. Projectability, legal-message order, timeout/retry and implementation-conformance gates pass for the stated subset. No universal choreography requirement for ordinary service calls. Capabilities and fallback Offers describe available behavior; grants/policy authorize it; a pinned capability plan selects a compatible implementation; receipts record effects. Fallback must preserve minimum guarantees or report unavailable. Residency, privacy, durability, cost and platform constraints are exercised. An outage cannot silently promote a projection to authority or downgrade durable work to memory. Opinionated data/cloud roles Cloudflare handles edge/realtime/bindings; GCP/k3s handles heavier regional workloads. Postgres is the default domain transaction authority, ClickHouse analytics, Memgraph graph knowledge/projections, R2 bytes/artifacts, D1 secondary/control-plane operational data, DO per-key coordination, Pub/Sub facts and Queues jobs. Each datum has one named write authority; alternate profiles prove their transaction/ordering/retry limits. The palette does not require every generated app to provision every service. Provider integration quality Every integration can declare source descriptor, live observer, effect adapter and conformance harness independently. Missing facets stay visible. Prefer established specialist runtimes over building substitute infrastructure. Actual provider failure/permission/ordering/recovery tests justify the advertised capability; configuration never establishes health. Polyglot and code replacement Start with portable contracts; stabilize one FFI call profile before streams. Python first uses a bounded worker/service profile. Code replacement starts with a signed stateless subset on owned hosts. Validation, ownership, cancellation, authority, compatibility and recovery pass separately for each profile. Stateful/mobile replacement receives its own gate. Formal assurance Modules supply conditional obligations and assumptions. Report claim-specific evidence, bounds and implementation linkage; use deterministic checks, properties, model traces and selected proofs as a portfolio. The claimed boundary is enforceable, tests are non-vacuous and the real runtime conforms. A marker interface or mathematical proof alone does not certify arbitrary application code. Creator and professional surfaces Create and Adopt lead into the same owned project. Browser creation is the public primary UX; advanced source/graph tools and the local companion expose greater control. Empty-project and later-growth trials succeed. Professional tooling cannot displace the greenfield product or introduce an export cliff. Public independence and compatibility Extract reusable distribution seams from BestBuds while preserving framework/editor/host boundaries. Publish normal packages, examples, versioned schemas and explicit stable/preview contracts. A clean external environment creates, exports, rebuilds and upgrades without private source, credentials or undocumented toolchains. Two-human delivery and evidence Two developers choose complementary lanes, review shared contracts and integrate weekly; agents implement bounded work with the same checks. Scope follows measured throughput. Monthly outcome review identifies the bottleneck. Add a lane only with accountable integration capacity; do not treat model availability as unlimited human review. ## The next two weeks: 7–20 September 2026 Section ID: the-next-two-weeks-720-september-2026 The next two weeks: 7–20 September 2026 When Action and deliverable Acceptance 7–9 Sep The two developers allocate the two ownership lanes and agree the first complete generated-app flow. Select the two related web classes and bounded Android/iOS recipe; write held-out briefs and follow-up requirements before tuning generation. Named owners, one integrated outcome for the week and a compact launch scope that both can explain. No private product assumptions in the public recipe. 7–10 Sep Capture the current build/dependency/publication closure and toolchain baseline. Inspect the existing dirty work without resetting it. Choose candidate public module/host roots and one managed execution approach. Known private/generated/native dependencies, clean-build blockers and an isolated runner experiment with no ambient product credentials. 9–13 Sep Write the compact identity/ownership and runtime-profile ADRs, plus characterization tests for port identity, invalid lifecycle callbacks, partial wiring, actor scope cancellation and stale completion. Specify actor admission/close outcomes and the first transaction/effect boundary. Failing behavior is reproducible or explicitly bounded; proposed changes have compatibility facades and target tests. The ADRs are small enough to implement in the first vertical slice. 10–15 Sep Connect brief/design artifacts to one generated UI/auth/data flow using real module APIs. Keep initial provider choices explicit in the recipe while hiding routine plumbing from the first-time user. A new test account creates a persisted record and sees it after restart; a visual change preserves bindings; the project exports with complete build inputs. 13–17 Sep Implement the first necessary core fixes and the atomic command/state/outbox or equivalent declared transaction slice. Add operation IDs, typed effect completions, tenant/account scope and meaningful failure findings. Duplicate request, rejected authorization, cancellation/restart and stale-session completion have observable, correct outcomes for this flow. No inference of universal durable actors. 15–18 Sep Run native host/recipe feasibility spikes using existing scaffolds; attempt one capability/permission probe per target and record toolchain/module blockers. Android and iOS evidence is separate; the spike establishes feasibility and remaining work. Full generated projects and device journeys remain October/November acceptance gates. 17–20 Sep Integrate creator, runtime and runner changes; run one untouched held-out brief and growth request. Review the current capability plan, source/semantic diff, artifact and failure receipts together. A recorded end-to-end demo and defect list decide the next week. By 20 Sep, cut or defer work that does not advance the first complete public creation flow; retain the 30 Sep package/support/ADR checkpoint. By 30 September, freeze the initial schema/identity decisions, source ownership, public package/support matrix, licensing/distribution proposal, authority/effect boundary and generated workflow acceptance cases. Later refinements should carry an explicit migration, rather than creating another parallel semantic system. ## 24. Reading map and maintenance contract Section ID: 24-reading-map-and-maintenance-contract 24. Reading map and maintenance contract This page owns the north star, system-level decisions, support promises, sequencing and outcome measures. It specifies the cross-system contracts and refinements needed to make the core ideas work together, and links to detailed subsystem designs and historical audits. The implementation schedule is the selected two-developer program; separate research notes are inputs, not additional promised parallel roadmaps. When an implementation changes status, update the system map and attach revision/target evidence. When a decision changes, record what it supersedes. Keep historical audits available with dates. Need Read next Thesis and architectural tension Essays, Framework Overview Every module's readiness, graph contribution and next tasks Module Review, Module Execution Plan — five ranked tasks per module/target, with integrated priorities and acceptance evidence; this master plan retains calendar and scope authority. Kernel laws and modeled guarantees Graph Kernel, Stable Foundations, Formal Methods Historical implementation audit Verified Foundations, authenticated Astra Analysis Primitives, visitors and adaptation Core, Visitors, Capabilities, Graph Refinement Runtime, communication and data Actors, Service, DB, Bus, Mesh, FFI Agent/human development environment Agentic Tooling, Canonical Atlas, Desktop Master Plan, Visual Language Delivery and integration Build Tools, Cloud, Shadow Environment, Mega-Scale Older roadmaps retain their detailed work and historical rationale. This page supplies the new September 2026–September 2027 ordering; it does not turn an old proposed capability into an implemented one. The complete target is a development engine whose power grows with its modules, models and agents, while its guarantees remain understandable to the people relying on the software. # Reaktor Auth URL: https://reaktor.build/docs/auth-analysis Status: unverified Content revision: ad05d71a28af8fc0f30cf5d8465ee6b40040fc9d0fbe33ad8390eccd35c7a3a0 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/auth-analysis","polarity":"Neutral"},{"id":"section-design-contract","anchor":"design-contract","label":"01. Design Contract","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#design-contract","polarity":"Neutral"},{"id":"section-current-status","anchor":"current-status","label":"02. Current Status","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#current-status","polarity":"Neutral"},{"id":"section-system-shape","anchor":"system-shape","label":"03. System Shape","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#system-shape","polarity":"Neutral"},{"id":"section-core-model","anchor":"core-model","label":"04. Core Model","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#core-model","polarity":"Neutral"},{"id":"section-auth-context","anchor":"auth-context","label":"05. AuthContext and AuthRequirement","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#auth-context","polarity":"Neutral"},{"id":"section-token-families","anchor":"token-families","label":"06. Token Families","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#token-families","polarity":"Neutral"},{"id":"section-runtime-graph","anchor":"runtime-graph","label":"07. Runtime Graph Decomposition","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#runtime-graph","polarity":"Neutral"},{"id":"section-graph-port-auth","anchor":"graph-port-auth","label":"19. Graph and Port Auth","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#graph-port-auth","polarity":"Neutral"},{"id":"section-provider-authorization","anchor":"provider-authorization","label":"31. Provider Authorization: Google and Apple OAuth","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#provider-authorization","polarity":"Neutral"},{"id":"section-open-work","anchor":"open-work","label":"24. Open Work","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#open-work","polarity":"Neutral"},{"id":"section-unified-scope","anchor":"unified-scope","label":"26. Unified Context: resolving tenant vs. context","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#unified-scope","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/auth-analysis#related-docs","polarity":"Neutral"}],"relations":[{"id":"auth-analysis:references-reaktor-ui-ux-audit-2026-09-08-developer-workflow-pass--8-september","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"page","role":"source","ordinal":0},{"node":"reaktor-ui-ux-audit-2026-09-08","port":"section-developer-workflow-pass--8-september","role":"target","ordinal":0}]},{"id":"auth-analysis:references-reaktor-workbench-layers-auth-workspace-projections","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"section-open-work","role":"source","ordinal":0},{"node":"reaktor-workbench-layers","port":"section-auth-workspace-projections","role":"target","ordinal":0}]},{"id":"auth-analysis:references-reaktor-multitenancy","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"section-unified-scope","role":"source","ordinal":0},{"node":"reaktor-multitenancy","port":"page","role":"target","ordinal":0}]},{"id":"auth-analysis:references-security-plan","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"security-plan","port":"page","role":"target","ordinal":0}]},{"id":"auth-analysis:references-secrets-management","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"secrets-management","port":"page","role":"target","ordinal":0}]},{"id":"auth-analysis:references-deep-link-integration","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"deep-link-integration","port":"page","role":"target","ordinal":0}]},{"id":"auth-analysis:references-reaktor-service","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"auth-analysis:references-reaktor-devops","kind":"references","owner":"auth-analysis","incidences":[{"node":"auth-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-devops","port":"page","role":"target","ordinal":0}]}]} ## Reaktor Auth Section ID: preamble Desktop inspection status · 8 September 2026: the Auth pane now has bounded metadata directories and session Postgres connection setup. Framework auth capability does not imply a delivered desktop admin workflow: role administration, credential minting and revocation are still open. See the living UI/UX audit for implemented flows and verification. This is the current source-of-truth document for reaktor-auth as deployed in the BestBuds/Reaktor stack on June 5, 2026. The important shift is complete: Reaktor auth is not a login helper. It is a graph-native principal, token, session, and authorization engine. Provider login, Supabase email credentials, anonymous entry, refresh rotation, PAT exchange, service credentials, delegated tokens, Spring Security, Cloudflare Workers, graph ports, and target-owned E2E tests all converge on the same primitive: AuthContext. ## 01. Design Contract Section ID: design-contract 01. Design Contract The API priority is: expressivity and composability >> simplicity >>> one-shot APIs / bloated APIs The 80% path must stay small: Client calls AuthAdapter.login(...) or a service calls /auth/token. The runtime resolves a principal and mints a short-lived Reaktor token. Servers and Workers verify the token locally. Handlers, graph ports, and actors authorize against AuthContext plus AuthRequirement. The remaining 20% path must still be possible: Graph consumers can mount AuthRuntimeGraph and wire directly to capability ports such as AuthLogin, AuthPat, AuthTokenGrants, and AuthSessions. Infrastructure consumers can drop down to lower-level ports such as AuthPrincipalDirectory, AuthPersonalTokens, AuthSessionLifecycle, and AuthServiceAccounts. Frameworks stay adapters. Spring and Cloudflare do not own the auth model; they translate transport credentials into graph/kernel primitives. ## 02. Current Status Section ID: current-status 02. Current Status Area Status Notes Graph runtime Implemented AuthRuntimeGraph is the JVM composition root and a real child-capable Graph. Kernel authorization Implemented AuthContext, AuthRequirement, and LocalAuthorizer are pure commonMain primitives. Identity model Implemented identity, provider_account, principal, membership, tenant/context, RBAC, sessions, PATs, service accounts, signing keys. User login Implemented server side External ID token -> principal/membership -> session -> rotating refresh + ES256 access token. Anonymous login Implemented core, policy hardening open AuthLogin.anonymous, AnonymousAuthRequest, /auth/anonymous, resolveAnonymousLogin, AuthMethod.ANONYMOUS, credential_type=anonymous, guest role/scope config, session creation, refresh, audit, and Spring public-route wiring exist. App bootstrap policy, visible first-launch UX, per-flow demo limits, Worker route policy, and anonymous-to-provider upgrade are still open. Refresh rotation Implemented One-time-use rkr_ refresh tokens, SHA-256 at rest, family reuse detection. Access tokens Implemented ES256, typ=at+jwt, JWKS, issuer/audience/expiry validation. PATs Implemented rkt_ high-entropy token with offline checksum, hash-at-rest, expiry, scopes, app/audience binding. Legacy rak_ verifies for compatibility. Service accounts Implemented client_credentials, private key JWT or secret auth, audience binding, scope down-scoping. Delegation Implemented token shape RFC 8693 token exchange with user subject and service actor in act. Persisted may_act policy is still future work. Auth audit Implemented auth_audit_event records token mint, exchange, refresh, revoke, and auth failure events without raw tokens or secrets. Spring adapter Implemented SpringDependencyAdapter creates the runtime; WebFlux filter verifies tokens and exposes AuthContext. Worker auth Implemented in consumers BestBuds Workers verify Reaktor JWTs through JWKS. Worker-to-Worker and Worker-to-server calls use service-account JWTs, not static fallback tokens. Target-owned E2E Implemented Karate lives under tests//karate; k6 under tests//k6. Supabase email/password, magic link, and OTP Designed here, not implemented AuthProviderKind.SUPABASE and provider-account storage exist, but there is no Supabase verifier, email facade, password reset facade, or link/upgrade endpoint yet. Supabase proves the email credential; Reaktor still owns principal, membership, sessions, tokens, authorization, audit, and Worker/server verification. Browser BFF / PKCE / DPoP Not implemented Native/mobile login works through provider ID tokens today. Supabase flows make PKCE and deep-link callback handling concrete; BFF cookies and DPoP remain later hardening. ReBAC object tuples Not implemented Kernel has resource-aware requirements; persistent object relationship tuples remain future work. ## 03. System Shape Section ID: system-shape 03. System Shape External credential Google / Apple / Supabase / Reaktor | v AuthRuntimeGraph AuthJwtNode verifies external identity AuthRepositoryNode resolves app, identity, principal, membership, roles, permissions AuthSessionLifecycleNode creates or rotates sessions AuthJwtNode mints ES256 access tokens | v Reaktor access token iss=https://api.reaktor.build/auth aud= sub= principal_type=user|service|agent|actor | v Spring / Worker / graph / actor boundary verify locally -> AuthContext -> LocalAuthorizer/AuthRequirement | v Domain handler The same token can be verified by: ReaktorSecurityWebFilter inside a JVM/Spring server. WorkerJwtVerifier inside Cloudflare Workers. JwtVerifier.verifyReaktorToken(...) in JVM services. Graph-aware consumers that connect to runtime capability ports. No verifier needs the signing secret. Public keys are exposed at /.well-known/jwks.json. ## 04. Core Model Section ID: core-model 04. Core Model The phase-2 schema intentionally separates "who the person is" from "what is acting" and "where that actor has authority". Concept Table / type Meaning App app Product/application namespace. Roles, permissions, contexts, tenants, sessions, and credentials are app-scoped. Identity identity Global human identity. A person can have many provider accounts and app memberships. Provider account provider_account External login method attached to an identity: Google, Apple, Supabase, or Reaktor. Unique by provider, issuer, subject. Principal principal Authorizable caller: USER, SERVICE, AGENT, or ACTOR. The anonymous MVP should reuse USER with identity_id=null and credential_type=anonymous until a separate PrincipalKind.ANONYMOUS is worth the downstream compatibility cost. Membership membership Principal membership in an app, tenant, and optional context. Tenant tenant Organization/unit inside an app. Context context App-local authorization scope for a resource, workflow, tenant slice, or graph context. RBAC role, permission, role_permissions, principal_role App-scoped role/permission grants, optionally context-scoped. Session session Principal login session. Refresh-token families are anchored here. Refresh token refresh_token One-time-use rotating token family. Reuse revokes the family. PAT personal_access_token Long-lived secret handle exchanged for short-lived JWTs. Raw token is shown once; only hash is stored. Service account service_account Machine credential for client_credentials and delegated token exchange. Signing key signing_key Public signing-key metadata and private-key reference. Runtime private keys come from config/secrets. Auth audit event auth_audit_event Append-only security trail for token mint, exchange, refresh, revoke, and failure events. Stores ids, scopes, request metadata, and reason; never raw bearer tokens, refresh tokens, PATs, or service secrets. The canonical schema is reaktor-auth/src/jvmMain/kotlin/dev/shibasis/reaktor/auth/heimdall.sql. It is not a legacy migration script. The intended rebuild path is: psql "$SUPABASE_DB_URL" -f reaktor-auth/src/jvmMain/kotlin/dev/shibasis/reaktor/auth/heimdall.sql Use a full external dump of Supabase heimdall and public data before rebuilding. Restore only data that belongs in the phase-2 schema. The old users / user_role flow is not a supported runtime path. ## 05. AuthContext and AuthRequirement Section ID: auth-context 05. AuthContext and AuthRequirement AuthContext answers one question: who is calling, for what app/tenant/context, with what authority? data class AuthContext( val principal: PrincipalRef, val identityId: String?, val appId: String, val tenantId: String?, val contextId: String?, val sessionId: String?, val tokenId: String?, val credentialId: String?, val issuer: String, val audience: String, val scopes: Set, val roles: Set, val permissions: Set, val method: AuthMethod, val actor: PrincipalRef?, val delegation: Delegation?, ) AuthRequirement is the declarative gate: val canWrite = AuthRequirement( permissions = setOf(PermissionRef(name = "messaging:write")), principalKinds = setOf(PrincipalKind.USER, PrincipalKind.SERVICE), ).audience(bestbudsAppId) LocalAuthorizer evaluates: Missing auth context -> 401. Audience/app/tenant mismatch -> 401 or 403. Wrong principal kind -> 403. Missing scope, permission, or role -> 403. Delegated call without allowDelegation -> 403. Otherwise allow. This is pure commonMain logic, so servers, Workers, graph ports, and future actor mailboxes can share the same authorization law. ## 06. Token Families Section ID: token-families 06. Token Families Credential Format Storage Use External provider token Google/Apple/Reaktor provider token Not trusted as Reaktor API token Login proof only. Reaktor access token ES256 JWT, typ=at+jwt, kid, JWKS Client memory / short-lived bearer API, Worker, graph, and service calls. Refresh token rkr_ opaque token SHA-256 hash in refresh_token User session rotation. One-time-use. PAT rkt_ opaque token with checksum SHA-256 hash in personal_access_token Developer/tool/CI bootstrap, exchanged for access JWT. Service account client_id plus private key JWT or secret service_account row client_credentials and token exchange actor auth. Delegated token ES256 JWT with act claim Short-lived bearer Service acts for a user while retaining actor identity. Access token claims include: { "iss": "https://api.reaktor.build/auth", "aud": "38d1cee3-004d-441f-8f66-ad5060859af1", "sub": "", "jti": "", "sid": "", "identity_id": "", "principal_type": "user", "credential_type": "access_token", "scp": ["profile:read", "messaging:read"], "roles": ["member"], "permissions": ["messaging:read"], "act": { "sub": "" }, "iat": 1760000000, "exp": 1760000900 } The verifier pins issuer, audience where required, expiry, and algorithm. It accepts at+jwt, JWT, or absent JOSE typ; this avoids the Nimbus default processor rejecting every RFC 9068-style access token. ## 07. Runtime Graph Decomposition Section ID: runtime-graph 07. Runtime Graph Decomposition AuthRuntimeGraph is the JVM composition root and is itself a Graph: val runtime = AuthRuntimeGraph.create( adapter = exposedAdapter, config = AuthRuntimeConfig( userAuthenticationProviders = providers, ecJwkJson = ecJwkJson, ecJwkPrevJson = ecJwkPrevJson, ), ) or mounted under another graph: val auth = graph.installAuthRuntime(exposedAdapter, config) The runtime registers only two external dependencies: ExposedAdapter, qualified as reaktorAuth.exposedAdapter. AuthRuntimeConfig, qualified as reaktorAuth.config. Everything else is graph composition. Node Provides Depends on AuthAuditNode AuthAuditSink ExposedAdapter (writes the append-only auth_audit_event trail) AuthRepositoryNode AuthAppCatalog, AuthPrincipalDirectory ExposedAdapter AuthJwtNode JwtMinter, JwtVerifier, AuthExternalIdentityVerifier, signing keys AuthRuntimeConfig AuthPersonalTokenNode AuthPersonalTokens JwtMinter, database-backed token service AuthSessionLifecycleNode AuthSessionLifecycle database-backed session service AuthServiceAccountNode AuthServiceAccounts JwtMinter, database-backed service accounts LoginInteractorNode AuthLogin app catalog, principal directory, external verifier, session lifecycle, minter AuthPatNode AuthPat personal token port AuthTokenGrantNode AuthTokenGrants PAT, service accounts, verifier, minter AuthSessionNode AuthSessions session lifecycle, principal directory, verifier, minter AuthHttpServiceNode AuthHttpService login, PAT, token grants, sessions AuthAppServiceNode AuthAppService app catalog ServiceNode projections route handlers AuthService, AppService This decomposition is the key Reaktor principle in practice. The common API is compact, but graph consumers can compose from lower-level atoms without expanding the top-level API. ## 08. HTTP Surface Section ID: http-surface 08. HTTP Surface The graph capability ports are projected as service handlers. In BestBuds, these are mounted under /auth. Route Capability Behavior POST /auth/sign-in AuthLogin Verifies external provider token, resolves principal/membership, creates session, returns access + refresh. POST /auth/anonymous AuthLogin.anonymous Creates or resumes a server-controlled guest principal for an app/environment, creates a refreshable session, and returns the normal access + refresh token shape with credential_type=anonymous. POST /auth/sign-in with provider=SUPABASE Designed AuthLogin extension Exchanges a verified Supabase access token into a Reaktor session after the Supabase verifier is added. This is the smallest client-first MVP and should not make Supabase JWTs valid Reaktor API bearers. POST /auth/email/start Designed email facade Starts app-policy-checked Supabase email/passwordless flow: magic link or OTP, redirect allowlist, shouldCreateUser, environment, tenant/context hints, rate limits, and audit. POST /auth/email/verify Designed email facade Verifies Supabase email OTP or token hash, resolves/links the provider account, and returns Reaktor tokens. POST /auth/email/password/sign-in Designed password facade Authenticates via Supabase email/password behind Reaktor app policy, then returns Reaktor tokens. POST /auth/email/password/reset/start Designed password facade Starts Supabase password reset with Reaktor redirect policy and audit. POST /auth/email/password/update Designed password facade Completes password update from an authenticated reset/update flow. POST /auth/anonymous/link Designed link facade Verifies the anonymous bearer and a verified Supabase/Google/Apple/Reaktor credential, then attaches identity to the existing guest principal when app policy allows upgrade. POST /auth/token AuthTokenGrants Supports pat, personal_access_token, client_credentials, and RFC 8693 token exchange. POST /auth/pat/mint AuthPat Mints a PAT when authorized by bootstrap token or existing PAT with auth:pat:mint. POST /auth/pat/verify AuthPat Verifies raw PAT and returns token metadata. POST /auth/session/refresh AuthSessions Rotates refresh token; replayed old token revokes the family. POST /auth/session/logout AuthSessions Revokes the refresh-token family for the presented refresh token. POST /auth/session/me AuthSessions Introspects verified bearer claims into principal, scopes, roles, permissions, and actor. POST /auth/session/logout-all AuthSessions Revokes all sessions for the bearer principal. GET /.well-known/jwks.json JwksController Publishes public ES256 keys. GET /app, GET /app/{id} AuthAppService App catalog lookup. Some credential-exchange routes are public at Spring Security because their handler verifies the credential itself. For example, /auth/token cannot require an access token before it mints one, but AuthTokenGrantNode still authenticates the PAT or service account. ## 09. Spring Boundary Section ID: spring-boundary 09. Spring Boundary Spring is intentionally a thin adapter. AuthSpringConfiguration: Reads ExposedAdapter. Reads configured UserAuthenticationProvider beans. Reads reaktor.jwt.ec-jwk and reaktor.jwt.ec-jwk-prev. Creates AuthRuntimeGraph with SpringDependencyAdapter. Exposes AuthServer, AppServer, ReaktorSecurityWebFilter, and JwksController. DefaultSecurityConfig: Installs ReaktorSecurityWebFilter at AUTHENTICATION. Permits infrastructure and credential-exchange routes. Requires authentication for everything else. Uses NoOpServerSecurityContextRepository. ReaktorSecurityWebFilter: Extracts Authorization: Bearer . Verifies Reaktor ES256 signature locally. Converts claims to AuthContext. Places the context in exchange.attributes["reaktor.auth.context"]. Creates a Spring Authentication with SCOPE_, ROLE_, and PERMISSION_ authorities for framework-level integration. Fine-grained authorization still belongs in AuthRequirement plus LocalAuthorizer, not in scattered route-local string checks. ## 10. Cloudflare Worker Boundary Section ID: worker-boundary 10. Cloudflare Worker Boundary BestBuds Workers now treat Reaktor JWTs as the client identity boundary: User-facing routes require Authorization: Bearer . Workers verify against https://api.reaktor.build/.well-known/jwks.json. Audience is pinned to the BestBuds app id 38d1cee3-004d-441f-8f66-ad5060859af1. The legacy X-BestBuds-Dev-User path is gated by ALLOW_USER_HEADER_AUTH=true and is not the production auth path. Service-to-Worker calls support two Reaktor-issued shapes: Reaktor service JWT with principal_type=service, audience-bound and scoped with worker:server. Delegated Reaktor JWT with user subject and service actor. Static Worker fallback tokens are no longer part of the production path. A Worker that needs to call another Worker or reaktorServer mints a short-lived service token through /auth/token with its service-account credentials. ## 11. User Flow Section ID: user-flow 11. User Flow 1 Client receives provider credential 2 Client calls POST /auth/sign-in with appId, provider, idToken, hints 3 AuthJwtNode verifies external identity 4 AuthRepositoryNode resolves app, identity, provider account, principal, membership 5 AuthSessionLifecycleNode creates session + first rotating refresh 6 AuthJwtNode mints ES256 access token 7 Client stores refresh securely and sends access token as bearer 8 Server/Worker verifies locally and builds AuthContext Implemented: Google/Apple/Reaktor-style external verification through configured providers. Anonymous guest-session creation through /auth/anonymous. Identity/principal/membership resolution. Session creation. Rotating refresh. /auth/session/me, logout, logout-all. Still open: Supabase email/password, magic-link, and OTP provider adapter. Anonymous app bootstrap policy, route policy, and anonymous-to-provider link/upgrade. Browser Authorization Code + PKCE — for Reaktor's own browser login. The separate question of obtaining an OAuth grant at the provider is §31. BFF __Host- HttpOnly cookie model. DPoP sender-constrained browser/native tokens. ## 12. Supabase Email, Magic Link, and OTP Auth Section ID: supabase-email-auth 12. Supabase Email, Magic Link, and OTP Auth The Reaktor rule is simple: Supabase can prove an email credential, but it does not become the Reaktor authorization system. Supabase is excellent at hosted email/password auth, magic links, OTP email codes, email templates, SMTP delivery, and provider-side rate limits. Reaktor is the system that turns a verified credential into an app-scoped principal, membership, session, access token, refresh-token family, graph auth context, Worker boundary, and audit trail. A Supabase access token is therefore login proof. It is not a bearer token for Reaktor Workers, graph ports, or services. ## Ownership Boundary Section ID: ownership-boundary Ownership Boundary Layer Owns Supabase Auth Email/password verification, email confirmation, password reset, magic-link and OTP delivery, provider-side session proof, email templates, SMTP integration, provider-side throttles. Reaktor auth App/provider configuration, redirect allowlist, tenant/context hints, identity/provider-account mapping, principal and membership creation, roles/scopes/permissions, Reaktor sessions, Reaktor access and refresh tokens, Worker/server verification, graph authorization, audit, account linking, anonymous upgrade. That boundary keeps provider choice replaceable. A future app can use Supabase, Google, Apple, Reaktor-native email, enterprise SSO, or passkeys without changing the downstream authorization model. ## Current Code Fit Section ID: current-code-fit Current Code Fit The model already has the right slot: AuthProviderKind.SUPABASE exists in the common auth kernel. provider_account is unique by (provider, issuer, subject) and can store Supabase auth.users.id as the subject, the project auth URL as issuer, and the verified email metadata. auth_provider_client can store per-app/per-platform provider config, redirect URLs, issuer, enabled flag, and secret references. LoginRequest(provider=SUPABASE, idToken=) can be the compact exchange DTO once a Supabase verifier exists. The missing implementation pieces are explicit: UserAuthenticationProvider.Supabase(projectUrl, jwksUrl, audiences, issuer). Supabase JWT verification in JwtVerifier with issuer, audience, kid, signature, expiry, and email-verified handling. Optional Reaktor email facade endpoints for policy-controlled start, verify, password sign-in, password reset, and callback handling. Link/upgrade support that can attach a verified Supabase identity to an existing anonymous principal. ## Supported Flow Families Section ID: supported-flow-families Supported Flow Families There should be two integration styles. The first ships quickly; the second is the production browser shape. Flow family Shape When to use Client-first exchange Native, desktop, or SPA client uses Supabase SDK for signUp, signInWithPassword, signInWithOtp, verifyOtp, or PKCE exchange, then sends the resulting Supabase access token to POST /auth/sign-in with provider=SUPABASE. Reaktor verifies the token and returns Reaktor tokens. Fast MVP, native clients, prototypes, and apps that can keep provider SDK state local while still using Reaktor tokens for every backend call. Reaktor email facade Client calls Reaktor endpoints such as /auth/email/start, /auth/email/verify, /auth/email/password/sign-in, /auth/email/password/reset/start, /auth/email/password/update, and /auth/supabase/confirm. Reaktor validates app policy and redirect allowlists, calls Supabase, resolves identities, and returns Reaktor sessions. Production browser auth, BFF flows, store-review flows, multi-app policy, unified audit, and any product that must avoid scattering Supabase configuration across clients. The client-first exchange should be intentionally narrow: POST /auth/sign-in Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "provider": "SUPABASE", "idToken": "", "environment": "PROD", "tenantHint": "optional-app-owned-hint", "contextHint": "optional-app-owned-hint" } The response is the normal LoginResponse.Success with Reaktor access and refresh tokens. The client must call Reaktor APIs with the Reaktor access token, not with the Supabase access token. If the client keeps a Supabase session for provider UX, that session is provider proof only. ## Email and Password Section ID: email-and-password Email and Password Email/password should use Supabase for password storage and verification, then exchange into Reaktor: client -> Supabase signInWithPassword(email, password) -> Supabase access token -> POST /auth/sign-in provider=SUPABASE -> Reaktor principal/session/token set For the facade shape: POST /auth/email/password/sign-in -> validate app + platform + redirect policy -> call Supabase password sign-in -> verify returned Supabase access token -> resolve provider_account + principal + membership -> mint Reaktor access + refresh Password reset should stay policy-aware: POST /auth/email/password/reset/start -> validate email, app, platform, redirect URL, rate limit -> call Supabase resetPasswordForEmail -> send user to Reaktor/Supabase callback POST /auth/email/password/update -> require authenticated reset/update proof -> call Supabase updateUser(password) -> keep or rotate the Reaktor session according to app policy Hosted Supabase projects require email verification by default. Reaktor should honor that: a route that requires a verified account must require emailVerified=true from the verified Supabase claims or callback result. ## Magic Link Section ID: magic-link Magic Link Supabase magic links are passwordless login proof. Reaktor should use them in one of two ways: Client-first: client calls Supabase signInWithOtp(email, ...); the email link returns to the app; the app obtains a Supabase session; the app exchanges the Supabase access token through /auth/sign-in. Facade: client calls /auth/email/start; Reaktor applies app policy and asks Supabase to send a magic link whose callback returns to a Reaktor-controlled route such as /auth/supabase/confirm. Important policy: shouldCreateUser=false for sign-in flows. shouldCreateUser=true only for explicit signup, trial, invite, or anonymous-upgrade flows. Magic-link destination must be an allowlisted redirect URL for the app and platform. The callback must consume the provider proof once and mint a Reaktor session. Never log the full magic link, token_hash, provider access token, provider refresh token, or Reaktor tokens. For PKCE-backed magic links, the email template should carry a token hash to a callback route: https://api.reaktor.build/auth/supabase/confirm?token_hash=&type=email&state= The callback exchanges the hash with Supabase, verifies the resulting session, binds it to the stored Reaktor flow state, and then either sets the future BFF session cookie or redirects the native/web client with an opaque app state that can be exchanged for Reaktor tokens. ## Email OTP Section ID: email-otp Email OTP Email OTP uses the same Supabase passwordless machinery as magic links, but the email template exposes a short numeric code instead of a link. Reaktor should model it as the same start/verify family: POST /auth/email/start Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "method": "email_otp", "email": "person@example.com", "shouldCreateUser": false, "environment": "PROD" } POST /auth/email/verify Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "method": "email_otp", "email": "person@example.com", "otp": "123456", "environment": "PROD" } The verify endpoint returns the same Reaktor token set as any other login. Provider OTPs must be short-lived, rate-limited, single-purpose, and redacted from every log/audit field. Audit should store method=email_otp, provider=SUPABASE, app id, outcome, reason, request metadata, and principal ids after resolution. ## Redirects, Deep Links, and Browser BFF Section ID: redirects-deep-links-and-browser-bff Redirects, Deep Links, and Browser BFF Every redirect is an auth boundary. Reaktor should store app/platform redirect allowlists in auth_provider_client.redirect_uris and reject any callback or start request whose redirect is not allowed. Recommended rules: Exact HTTPS redirects for production web. Universal links / app links for production iOS and Android. Custom schemes only when the platform requires them or for development. Wildcards only for localhost, preview deployments, and controlled development environments. The callback should carry opaque state, not user authority. Reaktor resolves state to server-side flow metadata. The future browser BFF model should use the Supabase PKCE callback as provider proof and then set Reaktor-owned __Host- HttpOnly secure cookies for browser sessions. Supabase sessions are not the browser API bearer; they are input to the Reaktor session minting step. ## Anonymous Upgrade and Account Linking Section ID: anonymous-upgrade-and-account-linking Anonymous Upgrade and Account Linking Anonymous upgrade is a link operation, not a second unrelated user creation: anonymous Reaktor bearer + verified Supabase credential -> verify anonymous Reaktor token -> verify Supabase access token, OTP result, or token_hash callback -> require verified email when app policy requires verified accounts -> create or resolve identity + provider_account(provider=SUPABASE) -> attach identity_id to the existing guest principal -> preserve principal id and intentional guest state -> mint a non-anonymous Reaktor session Never link by unverified email alone. The stable key is provider=SUPABASE + issuer + subject; email is metadata and a recovery hint. Automatic linking by verified email can be a product policy, but it must be explicit and auditable because it changes identity ownership. ## Data and Configuration Section ID: data-and-configuration Data and Configuration Minimum persisted config: auth_provider_client app_id provider = SUPABASE platform = WEB | IOS | ANDROID | DESKTOP | SERVER issuer = https://.supabase.co/auth/v1 client_id = client_secret_ref = redirect_uris = [...] enabled = true Minimum provider account mapping: provider_account provider = SUPABASE issuer = https://.supabase.co/auth/v1 subject = email = email_verified = provider_tenant = The facade flow also needs short-lived server-side flow state. This can start as an implementation-private table or store and later become a graph-visible node: auth_external_flow id state_hash app_id provider method email_hash redirect_uri platform flow_id tenant_hint context_hint code_verifier_ref anonymous_principal_id created_at expires_at consumed_at ## DTO Sketch Section ID: dto-sketch DTO Sketch Keep the high-level API compact. Supabase should add a small email facade, not a large set of special-purpose auth endpoints: data class SupabaseExchangeRequest( val appId: String, val accessToken: String, val tenantHint: String? = null, val contextHint: String? = null, ) data class EmailAuthStartRequest( val appId: String, val email: String, val method: EmailAuthMethod, val shouldCreateUser: Boolean = false, val redirectUri: String? = null, val flowId: String? = null, ) data class EmailAuthVerifyRequest( val appId: String, val email: String, val method: EmailAuthMethod, val otp: String? = null, val tokenHash: String? = null, val state: String? = null, ) data class PasswordSignInRequest( val appId: String, val email: String, val password: String, ) data class PasswordResetStartRequest( val appId: String, val email: String, val redirectUri: String, ) data class PasswordUpdateRequest( val appId: String, val newPassword: String, val state: String? = null, ) LoginRequest(provider=SUPABASE, idToken=...) should remain valid for the client-first exchange. The email facade exists to centralize policy, redirects, rate limits, and audit around Supabase-hosted email flows. ## Security Rules Section ID: security-rules Security Rules Verify Supabase issuer, audience, signature, kid, expiry, and required email verification before resolving identity. Do not trust Supabase role, RLS, or application metadata as Reaktor permissions. Reaktor roles, scopes, and permissions come from Reaktor membership and policy. Do not accept raw Supabase access tokens as API bearer tokens at Workers, Spring routes, graph ports, or service handlers. Keep Supabase service-role keys server-side only, referenced through Secret Manager or Cloudflare secrets. They must never reach browser, mobile, desktop, or generated JS bundles. Use custom SMTP for production email. Provider default email is acceptable only for development and smoke tests. Apply Reaktor-side rate limits to email start, OTP verify, password sign-in, reset start, and callback consumption, even when Supabase also rate-limits. Store only hashed email or redacted email in temporary flow state unless a product reason requires cleartext. Redact magic links, token_hash, OTP values, Supabase access/refresh tokens, Reaktor access tokens, and Reaktor refresh tokens from logs and audit. Treat redirect allowlists as production security config. Preview wildcards should be environment-scoped and removable. ## Acceptance Tests Section ID: acceptance-tests Acceptance Tests Supabase support is not done until these pass: UserAuthenticationProvider.Supabase accepts a real Supabase JWT and rejects wrong issuer, wrong audience, expired token, tampered signature, missing sub, and unexpected algorithm. POST /auth/sign-in provider=SUPABASE returns Reaktor access + refresh and persists provider_account(provider=SUPABASE, issuer, subject). A Worker accepts the returned Reaktor JWT and rejects the raw Supabase JWT. Email/password sign-in returns Reaktor tokens and never exposes a Supabase refresh token as a Reaktor refresh token. Magic-link start respects app redirect allowlist and shouldCreateUser. PKCE/token-hash callback is single-use and produces exactly one Reaktor session. Email OTP verify succeeds once, rate-limits retries, and redacts the OTP from logs and audit. Password reset start rejects non-allowlisted redirects. Anonymous upgrade preserves the principal id, attaches the Supabase identity, and mints a non-anonymous session. Unverified email cannot link or upgrade when policy requires verified email. Supabase service-role secrets are absent from client bundles and generated Kotlin/JS artifacts. ## Supabase Reference Points Section ID: supabase-reference-points Supabase Reference Points This design relies on current Supabase behavior: Email/password auth supports email identities and hosted projects require email verification by default. Passwordless email supports both magic links and OTP codes. Magic links are one-time-use links; Supabase's default request interval is 60 seconds and the default expiry is 1 hour. OTP uses the same passwordless machinery as magic links, with a template that exposes a short code; the default request interval is 60 seconds and expiry is 1 hour. Supabase sessions contain an access JWT and a refresh token. Reaktor treats that session as provider proof and issues its own session/token family. Redirect URLs are configured allowlists. Native/mobile flows need deep links or universal/app links. Identity linking must avoid unverified-email automatic linking because that is a pre-account-takeover risk. ## 13. Anonymous Auth Flow Section ID: anonymous-auth-flow 13. Anonymous Auth Flow Anonymous auth should be a first-class Reaktor grant, not fake Google login, fake Supabase login, or a shared demo credential. The product purpose is clear: Let people try apps built with Reaktor before creating an account. Let Apple App Store and Google Play review staff open the app, inspect the experience, and approve releases without private setup. Support apps whose useful surface is public content, where account creation is not required for reading, browsing, searching, or previewing. Let a product collect local guest state during onboarding and preserve it if the user later upgrades to a real account. This is also a product contract, not only a backend grant. Anonymous guest mode must be visibly reachable from first launch. A reviewer or new user should not need hidden gestures, support instructions, seeded private credentials, or a separate review build to enter the app. The first-run auth screen can still lead with the normal sign-in methods, but it must also show a clear guest/demo entry when the app has anonymous auth enabled. The guest session must expose enough of the real app to test the core feature set. It should not land in an empty shell, a fake marketing tour, or a dead-end placeholder. For public-content apps this usually means real read/search/browse surfaces. For workflow, messaging, marketplace, creator, or collaboration apps, it can mean a seeded demo workspace, ephemeral writes, sample conversations, or other app-owned demo state that exercises the primary flows without exposing private user data or irreversible actions. Apps should be able to customize their anonymous auth and demo policy. Reaktor should provide the primitive; each app decides which guest flows exist and what authority they carry: Policy area Examples Availability Disabled, enabled in review builds only, enabled in production, enabled by country/store channel, enabled by app environment. Entry points "Continue as guest", "Try demo", "Browse public content", store-review deep link, or app-specific onboarding variant. Guest authority Read-only public content, demo workspace read/write, ephemeral local state, scoped server writes, or linkable pre-signup state. Demo data Seeded tenant/context, sample project, public catalog, synthetic conversation, tutorial graph, or no seed for pure public browsing. Upgrade behavior Discard anonymous state, link the guest principal to a provider identity, copy selected guest state, or force sign-in before protected actions. Limits TTL, rate limits, write quotas, media-upload restrictions, purchase disablement, abuse controls, and cleanup policy. The implemented runtime path is anonymous-as-user: POST /auth/anonymous -> resolve app-scoped guest principal -> create session + rotating refresh token -> mint ES256 access token -> return the same AuthContextSnapshot + TokenSet shape as sign-in Recommended token shape: { "sub": "", "identity_id": null, "principal_type": "user", "credential_type": "anonymous", "scp": ["profile:read", "content:read"], "roles": ["guest"] } Why keep principal_type=user for the MVP: AuthMethod.ANONYMOUS already exists in the kernel. The schema already allows principal.identity_id to be null, so no schema rewrite is needed. Existing sessions and refresh-token families are principal-based and can be reused for guest sessions. Downstream BestBuds Workers already accept app users when principal_type=user. Introducing PrincipalKind.ANONYMOUS immediately would force every Worker, route policy, and requirement to learn a new principal kind before the feature is usable. The server must own the guest authority. The anonymous request chooses the app, environment, optional tenant/context hints, and optional profile metadata. It must not choose roles, scopes, principal id, audience, or raw authority. The runtime assigns configured anonymous roles/scopes/permissions and resolves the membership from server-side policy. Implemented in source: AnonymousAuthRequest is part of the common service API. AuthLogin.anonymous is a first-class capability method. AuthHttpServiceNode exposes POST /auth/anonymous. Spring permits /auth/anonymous as a credential-issuing public route. LoginInteractorNode.anonymous validates app id, resolves the guest principal, checks principal and membership status, creates a session, mints credential_type=anonymous, returns the normal token set, and emits audit. AuthRuntimeConfig carries default anonymous roles, scopes, and permissions. Refresh preserves anonymous tokens by inferring a USER principal with identity_id=null and re-minting credential_type=anonymous. Integration tests assert the anonymous handler exists and basic server calls succeed. Still open: Add app-level anonymous policy configuration, either as app config or a dedicated table. The policy should define whether anonymous auth is enabled, which guest/demo flows are exposed, default roles/scopes, demo tenant/context, TTL, write limits, and upgrade behavior. Include anonymous availability and supported flows in the app bootstrap data so first-launch clients can render the guest/demo entry without hard-coded product logic. Add AuthAdapter.loginAnonymous(appId, environment, flowId?) for clients. Update Worker route policy so routes can intentionally allow or reject credential_type=anonymous while still treating the principal as a user. Implement anonymous-to-provider link/upgrade, including Supabase email upgrade. Security rules: Rate-limit POST /auth/anonymous per IP/device/app. Audit anonymous mint, refresh, logout, upgrade, and abuse rejection events. Keep guest scopes narrow by default. Public content can be readable; writes, private data, purchases, messaging, and account operations should require explicit route policy. Treat reviewer/demo flows as production behavior. They should be safe, observable, and revocable, not a special bypass that skips normal app policy. Do not use one global demo account. Each guest needs its own principal/session boundary to avoid state leakage and audit ambiguity. Do not let anonymous sessions become a back door into protected app surfaces. Routes should either accept credential_type=anonymous intentionally or require a non-anonymous method. The upgrade path should be a link operation, not a new unrelated user: anonymous bearer + provider credential -> verify anonymous Reaktor token -> verify Google/Apple/Supabase credential -> create or resolve identity + provider_account -> attach identity_id to the existing guest principal -> keep principal id, membership, roles that should survive, and app data That can later become POST /auth/anonymous/link or an extension of POST /auth/sign-in that accepts the current anonymous bearer. The important property is continuity: any guest-created local state that the app deliberately keeps should move with the same principal when the user becomes registered. Tests should cover: Anonymous login returns access + refresh and credential_type=anonymous. Refresh preserves anonymous credential type. /auth/session/me reports AuthMethod.ANONYMOUS and identityId=null. Guest scopes cannot be expanded by request input. App bootstrap advertises anonymous availability and supported guest/demo flows. First-launch clients render a visible guest/demo entry when the app policy enables it. Worker policy allows public-content routes and rejects protected routes for anonymous tokens. Link/upgrade preserves the principal id and attaches the real identity. ## 14. Refresh Flow Section ID: refresh-flow 14. Refresh Flow Refresh tokens are one-time-use: fresh rkr_A POST /auth/session/refresh -> access JWT + rkr_B -> rkr_A marked used/rotated replay rkr_A -> family revoked -> future rkr_B use fails This is enforced by SessionRefreshService.rotate(...): Tokens are rkr_ + 32 bytes of secure random data. Only SHA-256 hashes are stored. family_id links all rotations in a session family. Reuse of a used token revokes the family. logout revokes one family. logout-all revokes every active session for the principal. ## 15. PAT Flow Section ID: pat-flow 15. PAT Flow PATs are exchange credentials, not API bearer tokens. PAT rkt_... -> POST /auth/token grant_type=pat -> short-lived access JWT -> Worker/server verifies JWT locally Implemented properties: rkt_ prefix. 32-byte secret body. CRC32 checksum for offline typo/tamper rejection before DB lookup. SHA-256 hash at rest. Optional expiry. Scopes. Optional app binding. Allowed audiences. Revocation. last_used_at metadata. /auth/pat/mint requires either: REAKTOR_PAT_BOOTSTRAP_TOKEN, or an existing PAT whose scopes include *, auth:*, or auth:pat:mint. ## 16. Service Account Flow Section ID: service-account-flow 16. Service Account Flow client_credentials is first-class service-principal auth. It does not fake a user. { "grant_type": "client_credentials", "clientId": "messaging-worker", "client_assertion": "", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "audience": "38d1cee3-004d-441f-8f66-ad5060859af1", "scopes": ["worker:server"], "ttlSeconds": 300 } The service account authenticates by: PRIVATE_KEY_JWT: preferred. The assertion is verified against service_account.public_jwks. SECRET: supported for bootstrap; secret hash stored server-side. MTLS: reserved for upstream/proxy termination. Token issuance is audience-bound and down-scoped: If the requested audience is not in allowed_audiences, return unauthorized. If requested scopes exceed the account scopes, only the intersection is granted. Tokens carry principal_type=service and credential_type=client_credentials. ## 17. Delegation Flow Section ID: delegation-flow 17. Delegation Flow Delegation uses RFC 8693 token exchange: { "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "clientId": "messaging-worker", "client_assertion": "", "subjectToken": "", "subject_token_type": "urn:ietf:params:oauth:token-type:access_token", "audience": "38d1cee3-004d-441f-8f66-ad5060859af1", "scopes": ["worker:server"] } The minted token keeps: sub: the user principal. act.sub: the service principal. credential_type: delegation. This means downstream services can audit both subject and actor. The token shape is implemented and live-tested. Persisted may_act policy is still open, so today the grant is controlled by service-account credentials, allowed audiences, and route-level requirements. ## 18. Common Task Recipes Section ID: common-task-recipes 18. Common Task Recipes The common tasks are intentionally small compositions of the same flows. The top-level API should make the 80% path obvious; the lower-level graph and port surfaces keep the remaining 20% possible without adding route-specific one-shot APIs. Task Flows used Result Let a user try a Reaktor app before signup Anonymous + refresh + optional link First launch exposes a visible guest/demo entry; the guest principal receives app-configured scopes and can later link to a real identity. User signs in with Supabase email/password Supabase password proof + Reaktor exchange Supabase verifies the password; Reaktor verifies the provider token and returns Reaktor access + refresh. User signs in with magic link or email OTP Supabase passwordless start/verify + Reaktor exchange Supabase delivers and verifies the email proof; Reaktor consumes it once and creates the app-scoped session. Guest upgrades with Supabase email Anonymous + Supabase proof + link The existing guest principal gains a real identity without losing intentional guest state. Native app signs in and calls a Worker User flow Provider credential becomes a Reaktor access token; Worker verifies locally. App stays signed in for weeks User + refresh Access token stays short-lived; refresh rotates one-time tokens. Developer CLI or MCP calls Reaktor APIs PAT + token exchange Long-lived PAT is exchanged for a short-lived access token. Worker calls another Worker as itself Service account Worker mints client_credentials JWT and sends it as bearer. Worker calls another Worker for a user User + service account + delegation Downstream sees the user subject and the service actor. Worker calls the graph gateway Service account + graph gateway Worker uses service JWT over the Workers VPC HTTP binding. Server handles HTTP auth but keeps policy portable Spring boundary + AuthRequirement Spring authenticates; Reaktor auth authorizes. Graph-aware module composes auth internally Runtime graph + secured ports Ports wire only when the current AuthContext satisfies requirements. Operator investigates auth behavior Audit flow auth_audit_event shows mint, exchange, refresh, revoke, and failure metadata. ## Try an App Before Sign Up Section ID: try-an-app-before-sign-up Try an App Before Sign Up This is the app trial, store-review, and public-content path. The client should show this path on first launch whenever app bootstrap says anonymous auth is enabled. POST /auth/anonymous Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "flowId": "review-demo", "environment": "PROD" } The client receives the normal token set: { "tokenSet": { "accessToken": "", "refreshToken": "rkr_...", "expiresInSeconds": 900 } } Workers and servers still verify the token locally. Public routes can allow credential_type=anonymous; protected routes can require a signed-in method even when principal_type=user is present. If the user later signs in with Google, Apple, Supabase, or Reaktor credentials, the link flow should attach that identity to the same principal so intentional guest state survives account creation. The flowId is app-owned policy, not user-owned authority. A BestBuds-style app might expose public-browse, review-demo, and new-user-trial with different demo data and limits. The server resolves that flow to the actual tenant, context, roles, scopes, quotas, and cleanup policy. ## Sign In with Supabase Email and Password Section ID: sign-in-with-supabase-email-and-password Sign In with Supabase Email and Password The smallest path keeps Supabase SDK work on the client and uses Reaktor only for the provider-token exchange: client signInWithPassword(email, password) -> Supabase access token -> POST /auth/sign-in provider=SUPABASE -> Reaktor access + refresh POST /auth/sign-in Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "provider": "SUPABASE", "idToken": "", "environment": "PROD" } The production facade path should be: POST /auth/email/password/sign-in Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "email": "person@example.com", "password": "", "environment": "PROD" } Both shapes return the same Reaktor token set. Workers never accept the raw Supabase JWT. ## Use Supabase Magic Link or Email OTP Section ID: use-supabase-magic-link-or-email-otp Use Supabase Magic Link or Email OTP Passwordless email starts with a policy-checked request: POST /auth/email/start Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "method": "magic_link", "email": "person@example.com", "shouldCreateUser": false, "redirectUri": "https://bestbuds.ai/auth/callback", "environment": "PROD" } For OTP, use the same endpoint with method=email_otp, then verify: POST /auth/email/verify Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "method": "email_otp", "email": "person@example.com", "otp": "123456", "environment": "PROD" } For PKCE magic links, the callback carries token_hash and opaque state into /auth/supabase/confirm; Reaktor exchanges it once, verifies Supabase, resolves the principal, and returns or installs a Reaktor session. ## Upgrade a Guest with Supabase Email Section ID: upgrade-a-guest-with-supabase-email Upgrade a Guest with Supabase Email The client already has an anonymous Reaktor bearer from /auth/anonymous. It then obtains a verified Supabase proof through password, magic link, or OTP and links that proof to the current principal: POST /auth/anonymous/link Authorization: Bearer Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "provider": "SUPABASE", "idToken": "", "environment": "PROD" } The link endpoint must preserve the principal id, attach the resolved identity, and mint a non-anonymous Reaktor session. If app policy requires verified email, an unverified Supabase email cannot upgrade the guest. ## Sign In and Call a Worker Section ID: sign-in-and-call-a-worker Sign In and Call a Worker This is the main app path. POST /auth/sign-in Content-Type: application/json { "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "provider": "GOOGLE", "idToken": "", "environment": "PROD" } The client receives: { "tokenSet": { "accessToken": "", "refreshToken": "rkr_...", "expiresInSeconds": 900 } } Then the client calls any BestBuds Worker: GET /topMessages Authorization: Bearer The Worker does not call Supabase or the auth server on every request. It uses WorkerJwtVerifier, pins issuer/audience/JWKS, and builds the local user identity from claims. ## Keep a Native Session Alive Section ID: keep-a-native-session-alive Keep a Native Session Alive Mobile and desktop clients keep only the refresh token in secure storage. When the access token is close to expiry: POST /auth/session/refresh Content-Type: application/json { "refreshToken": "rkr_A...", "environment": "PROD" } The response returns a new access token and a new refresh token: { "tokenSet": { "accessToken": "", "refreshToken": "rkr_B...", "expiresInSeconds": 900 } } Clients must replace rkr_A with rkr_B. If rkr_A is replayed, Reaktor treats that as token theft and revokes the whole family. The same session can be introspected later: POST /auth/session/me Authorization: Bearer Content-Type: application/json ## Revoke a Lost Device Section ID: revoke-a-lost-device Revoke a Lost Device For one lost device, revoke the refresh-token family represented by that device's refresh token: POST /auth/session/logout Content-Type: application/json { "refreshToken": "rkr_device_family...", "environment": "PROD" } For every device owned by the current principal: POST /auth/session/logout-all Authorization: Bearer Content-Type: application/json Both paths emit TOKEN_REVOKE audit events. ## Give a CLI or MCP Tool Access Section ID: give-a-cli-or-mcp-tool-access Give a CLI or MCP Tool Access The durable developer secret is a PAT, but the API bearer is still a short-lived JWT. Mint a PAT with an authorized bootstrap token or a PAT that has auth:pat:mint: POST /auth/pat/mint Authorization: Bearer Content-Type: application/json { "name": "mcp-local-dev", "scopes": ["mcp:read", "auth:pat:mint"], "appId": "38d1cee3-004d-441f-8f66-ad5060859af1", "allowedAudiences": ["manna-mcp"], "expiresInDays": 30, "environment": "PROD" } Exchange the PAT before each API session: POST /auth/token Content-Type: application/json { "grant_type": "pat", "rawToken": "rkt_...", "audience": "manna-mcp", "scopes": ["mcp:read"], "ttlSeconds": 900, "environment": "PROD" } The tool sends the returned access token as bearer. This keeps the long-lived PAT out of normal service logs, Worker logs, and graph gateway calls. ## Make Worker-to-Worker Calls as a Service Section ID: make-worker-to-worker-calls-as-a-service Make Worker-to-Worker Calls as a Service Chat uses this path when it calls messaging. The Worker has Cloudflare secrets: BESTBUDS_WORKER_SERVICE_CLIENT_ID BESTBUDS_WORKER_SERVICE_CLIENT_SECRET The Worker mints a short-lived service JWT: POST /auth/token Content-Type: application/json { "grant_type": "client_credentials", "clientId": "bestbuds-worker-service", "clientSecret": "", "audience": "38d1cee3-004d-441f-8f66-ad5060859af1", "scopes": ["worker:server"], "ttlSeconds": 300, "environment": "PROD" } The downstream Worker accepts it only if: principal_type=service. credential_type=client_credentials. aud is the BestBuds app id. scp contains worker:server. In Kotlin/JS Worker code, the common path is not hand-built JSON. Use the Cloudflare binding: val workerServiceAuth = serviceAccountAuth( clientId = secret("BESTBUDS_WORKER_SERVICE_CLIENT_ID"), clientSecret = secret("BESTBUDS_WORKER_SERVICE_CLIENT_SECRET"), audience = BESTBUDS_APP_ID, scopes = listOf("worker:server"), ) val headers = mutableMapOf( "Authorization" to context.serviceAccountBearer(workerServiceAuth), ) ## Call a Worker on Behalf of a User Section ID: call-a-worker-on-behalf-of-a-user Call a Worker on Behalf of a User Use delegation when a service is doing work for a real user and downstream policy/audit must preserve both identities. The user signs in and calls chat with a user access token. Chat authenticates as bestbuds-worker-service. Chat exchanges the user token for a delegated token. Chat calls messaging with the delegated bearer. POST /auth/token Content-Type: application/json { "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "clientId": "bestbuds-worker-service", "clientSecret": "", "subjectToken": "", "subject_token_type": "urn:ietf:params:oauth:token-type:access_token", "audience": "38d1cee3-004d-441f-8f66-ad5060859af1", "scopes": ["worker:server"], "ttlSeconds": 300, "environment": "PROD" } The downstream token has sub= and act.sub=. Normal user routes can still read the caller as the user, while audit and delegation-aware policy can see the service actor. The alternate service-on-behalf-of-user path is the explicit delegated-user header: GET /topMessages Authorization: Bearer X-BestBuds-Delegated-User: {"id":"", ...} This is accepted only with a valid service JWT. The old static Worker token is not accepted. ## Call the Graph Gateway from a Worker Section ID: call-the-graph-gateway-from-a-worker Call the Graph Gateway from a Worker Workers cannot speak Bolt to private Memgraph directly. They call the reaktorServer graph gateway over a Workers VPC HTTP binding, authenticated by the same service-account JWT. val graphGateway = graph( name = "APP_SERVER_HTTP", auth = workerServiceAuth, ) val health = cloudflare.graph(graphGateway) { health() } val result = cloudflare.graph(graphGateway) { queryId("kg.nodeCount.v1") } The gateway verifies the bearer locally with JwtVerifier, requires principal_type=service, credential_type=client_credentials, and worker:server, then runs the registered graph operation. ## Put Auth Behind Spring Without Making Spring the Model Section ID: put-auth-behind-spring-without-making-spring-the-model Put Auth Behind Spring Without Making Spring the Model For JVM servers, Spring owns HTTP interception and Reaktor owns auth semantics. The common route code reads an AuthContext and authorizes declaratively: val requirement = AuthRequirement( permissions = setOf(PermissionRef(name = "messaging:write")), principalKinds = setOf(PrincipalKind.USER), ).audience(BESTBUDS_APP_ID) LocalAuthorizer.authorize(authContext, requirement) This avoids framework lock-in. The same requirement shape can guard a service handler, a Worker helper, or a graph port. ## Compose Auth Inside a Graph-Aware Module Section ID: compose-auth-inside-a-graph-aware-module Compose Auth Inside a Graph-Aware Module Graph consumers can drop below HTTP and compose auth as capability ports: class MessagingNode(graph: Graph) : BasicNode(graph) { val sessions by consumes() val tokenGrants by consumes() val messaging by provides(this) } For capability-level security, wire with secured ports: val canSend = AuthRequirement( permissions = setOf(PermissionRef(name = "messaging:write")), principalKinds = setOf(PrincipalKind.USER, PrincipalKind.SERVICE), ).audience(BESTBUDS_APP_ID) The graph-level path is the 20% escape hatch: swap a verifier node, mount auth as a child graph, require full wiring, or make an authorization requirement part of the graph edge itself. ## Investigate an Auth Incident Section ID: investigate-an-auth-incident Investigate an Auth Incident Operators should query audit metadata, not tokens: select event_type, outcome, grant_type, reason, count(*)::int from heimdall.auth_audit_event where created_at > now() - interval '30 minutes' group by event_type, outcome, grant_type, reason order by event_type, outcome, grant_type, reason; Examples: Many AUTH_FAILURE rows with grant_type=client_credentials usually means a Worker secret mismatch or a disabled service account. TOKEN_EXCHANGE rows show service-on-behalf-of-user activity. Inspect actor_principal_id, subject_principal_id, audience, and scopes. TOKEN_REVOKE rows confirm logout/logout-all and can be correlated with a user's later refresh failures. The table intentionally stores request ids, actor/subject ids, scopes, audience, and reason, never raw refresh tokens, PATs, service secrets, or bearer tokens. ## 19. Graph and Port Auth Section ID: graph-port-auth 19. Graph and Port Auth Graph consumers have two options. For the common path, use the high-level runtime graph: val auth = graph.installAuthRuntime(exposedAdapter, config) val service = auth.service For direct graph composition, consume ports: class Consumer(graph: Graph) : BasicNode(graph) { val tokenGrants by consumes() val sessions by consumes() } For local auth state and policy, use common graph nodes: AuthGraph.install(graph). AuthNode for AuthContextProvider and AuthContextSink. AuthPolicyNode for AuthPolicy. SecuredProviderPort and SecuredConsumerPort for AuthRequirement-guarded ports. This lets auth travel with graph causality instead of disappearing at the HTTP edge. ## 20. Target-Owned Tests Section ID: target-owned-tests 20. Target-Owned Tests The E2E structure mirrors Maestro: tests live under the target they validate. tests/ reaktorServer/ karate/ k6/ notificationServer/ karate/ playwright/ messagingServer/ karate/ support/ karate/ Common commands: npm run test:auth:karate:smoke npm run test:auth:karate:live npm run k6:reaktorServer:auth:smoke npm run k6:reaktorServer:auth:load reaktor reaktorServer karate auth smoke reaktor notificationServer karate auth smoke reaktor messagingServer karate auth smoke reaktor reaktorServer k6 auth smoke reaktor reaktorServer k6 auth load Live evidence from June 5, 2026: Check Result npm run test:auth:karate:smoke Pass, 9/9 live smoke scenarios. KARATE_USE_SERVER_APPLICATION_DB=1 npm run test:auth:karate:live Pass, 23/23 live scenarios against real reaktorServer, Supabase, and deployed Workers. node scripts/run-with-env-files.mjs tmp/karate-fixtures/auth-fixture.env tmp/worker-service-auth.env -- ../reaktor/tools/karate/run-karate.sh --configdir tests/support/karate --tags @service tests/reaktorServer/karate Pass, 5/5 live service-account scenarios using the production bestbuds-worker-service credential. node scripts/run-with-env-files.mjs tmp/karate-fixtures/auth-fixture.env tmp/worker-service-auth.env -- ../reaktor/tools/karate/run-karate.sh --configdir tests/support/karate --tags @delegation tests/messagingServer/karate Pass, 2/2 live Worker delegation scenarios using the production bestbuds-worker-service credential. curl -i https://data-probe.shibasispatnaik.workers.dev/_data/graph/health Pass, HTTP 200 with ok: true, proving Worker -> service JWT -> reaktorServer graph gateway over Workers VPC. ./gradlew :reaktor-auth:jvmTest --console=plain Pass, 48 auth JVM tests including audit, refresh, revoke, PAT, service-account, and token-exchange coverage. npm run k6:reaktorServer:auth:smoke Structurally wired; real run requires local k6 binary. Karate owns correctness: status and JWKS publication. missing/malformed bearer rejection. invalid refresh rejection. graph gateway service-bearer rejection. user access-token introspection. refresh rotation and old-token reuse rejection. client_credentials minting and audience rejection. delegated token exchange. PAT verify/exchange/token-grant/bootstrap. notification Worker user auth and explicit user mismatch rejection. messaging Worker user auth, service-on-behalf-of-user, and delegated JWT access. Live Karate does not create a new service account per run. The stable test credential is injected through the environment or an ignored, owner-only tests/reaktorServer/karate/service-auth.env; the seeder upserts the single karate-service account and reuses it. Disposable rows are limited to user/session/refresh-token/role/PAT fixtures because the refresh flow intentionally rotates and replays a token. k6 owns pressure: low-pressure status/JWKS/auth rejection smoke. explicit request-rate pressure through K6_RPS and K6_DURATION. future spike/soak/SLO budgets. ## 21. Deployment Status Section ID: deployment-status 21. Deployment Status BestBuds production path currently uses: reaktorServer deployed to k3s. reaktor-auth as source of truth for sessions, refresh tokens, PATs, service accounts, token exchange, and ES256/JWKS verification. BestBuds Workers resolving users from Reaktor access tokens before any legacy development header. Notification and messaging Workers tested through target-owned Karate suites. Auth audit events stored in heimdall.auth_audit_event for mint, exchange, refresh, revoke, and failure flows. Live verification on June 5, 2026 showed recent rows for TOKEN_MINT, TOKEN_EXCHANGE, TOKEN_REFRESH, TOKEN_REVOKE, and AUTH_FAILURE. Known deployed Worker versions from the rollout: Worker Version reaktorServer k3s image tag 20260605-1739 chat-service 42703fdb-ff53-43f9-87b9-4b8e657ae208 messaging-service c43238c6-d7c6-4fe8-81dd-3dc49406acb7 social-service 009da7cf-2a48-4f34-b416-0e4414ccd850 media-service e0df6d09-998f-4bcc-a753-fa15ec462d58 sticker-service 5f4a95c2-ef6a-4efc-8ac7-ca49d6e23d26 analytics-service 2194831e-0310-4978-80e5-d696ae77343b data-probe 699e84f2-7595-413c-90c8-029b255ef45b notification-service f4198d6b-6c0b-4f85-875c-01fa777e296e Worker-to-Worker and Worker-to-reaktorServer calls now use service-account JWTs minted through /auth/token; the static fallback token path has been removed. Operational commands: npm run auth:worker-service:provision npm run auth:worker-service:set-cloudflare-secrets ./gradlew :app:jsBrowserProductionLibraryDistribution --rerun-tasks --console=plain The first command creates/rotates the bestbuds-worker-service account in Supabase and writes tmp/worker-service-auth.env with 0600 permissions. The second command pushes the client id/secret to Cloudflare Workers and deletes the legacy BESTBUDS_WORKER_SERVICE_TOKEN secret. The Gradle distribution task is required before Worker deploys because the Worker targets import the generated modules/app/bestbuds-kt production library, not just the incremental compileKotlinJs output. ## 22. Operating Rules Section ID: operating-rules 22. Operating Rules Do not add one-shot auth APIs for every route shape. Add a small graph capability or lower-level port and compose it. Do not put auth policy only in Spring Security or only in Worker middleware. Transport boundaries authenticate; AuthRequirement authorizes. Do not use provider tokens as Reaktor API tokens. Do not store raw production refresh tokens, PATs, or service secrets. The Karate service credential must come from the approved secret store or the ignored, owner-only local env file; it is never a versioned fixture. Do not let new tests live in runner-level folders such as tests/karate or tests/k6. Put them under the target. Do not reintroduce the old users / user_role model as runtime auth. When touching hot paths, add a harness or profile artifact before claiming performance wins. ## 23. Module Review and Assessment Section ID: review 23. Module Review and Assessment A point-in-time review of the whole module (2026-06-05) across architecture, API and developer experience, security posture, completeness, multiplatform, tests, code quality, and operations. The module is under active development; treat this as a snapshot. Overall, the core is strong and well-factored: a pure authorization kernel, a graph-native runtime, real external-provider verification, ES256/JWKS, rotating refresh with reuse-detection, and an append-only audit trail. What remains is mostly hardening and breadth — bounding authority on the credential-issuing paths, securing client token storage, finishing browser/web auth, and routine cleanup. Architecture — strong. The runtime is a graph of twelve nodes (the table in section 07 plus AuthAuditNode) behind a clean dual-surface contract: ordinary consumers use the kernel, the capability interfaces, and the client without ever naming a Graph; graph-aware consumers mount AuthRuntimeGraph, install it under their own graph, or wire to capability ports (section 19). High-level capabilities are graph-free in commonMain; low-level ports are graph-coupled in jvmMain — a deliberate seam. One source-level gap remains: the server's only construction path (AuthRuntimeGraph.create(...)) returns a Graph subtype, and AuthSpringConfiguration reaches into node internals (runtime.jwt.verifier). A small graph-free AuthRuntime facade — an interface aggregating login/pat/sessions/service/verifier/signingKeys, implemented by AuthRuntimeGraph — would let plain servers and the Spring beans depend on a graph-agnostic type. The reaktor-graph artifact dependency itself is expected under the module pattern; the bar is the exposed surface, not a graph-free classpath. API and developer experience — good, with edges. AuthContext / AuthRequirement / LocalAuthorizer are clean, pure, and portable, and the requirement DSL composes well (anyOf / allOf / forUsers / audience / inApp). The main naming cleanup is now explicit: OAuth/JWT scp/scopes remain wire-format names, but the in-memory authorization model treats scopes and permissions as one capability set (PermissionRef). Remaining rough edges: there is no sugar for multi-role requirements, and audience(...) wraps a bare String the constructor wants as Audience. JS/TS export is partial — the request/response DTOs extend Request / Response (which carry a MutableMap header), forcing @Suppress("NON_EXPORTABLE_TYPE") on LoginRequest / LoginResponse, so JS consumers lean on AuthContextSnapshot plus @JsStatic factories rather than a fully-typed surface. The capability interfaces themselves are clean over DTOs. Security posture — solid core; hardening tracked privately. Strengths: ES256/JWKS with algorithm pinning and typ=at+jwt, real RS256 provider-signature verification, one-time rkr_ refresh tokens with family reuse-detection, hash-at-rest for every secret, asymmetric-only service-account assertions, and an audit trail that records reasons/IP/UA and never raw secrets. A set of authorization-hardening items — bounding the authority a mint-capable credential can confer, intersecting delegated-token scope with the subject, enforcing principal status on refresh, and making audience-pinning the bearer filter's default — is tracked in an internal review rather than here; none is a remote-unauthenticated break. One client item belongs in the open: the client caches the raw access and refresh tokens in the local object store (SQLite) as plaintext — mobile clients should back that with the platform keystore (iOS Keychain, Android Keystore / EncryptedSharedPreferences). Use-case completeness. Use case Status Native/mobile login via Google/Apple ID token Implemented Sessions: create / refresh-rotate / reuse-detect / logout / logout-all Implemented Access tokens: ES256/JWKS mint + verify, key rotation Implemented PAT mint / verify / exchange / revoke Implemented (mint authority needs bounding) Service accounts: client_credentials, private-key-JWT / secret Implemented RFC 8693 delegation token shape Implemented (authority-bounding + may_act open) RBAC, multi-tenant / context, resource checks Implemented in kernel Audit trail Implemented Anonymous app trial, store-review, and public-content access Core implemented; app bootstrap policy, route policy, first-launch UX, demo-flow limits, and upgrade remain open Supabase email/password + magic link + OTP Designed here; provider verifier, email facade, callback handling, and tests not implemented Browser web auth (Auth Code + PKCE, BFF cookies, DPoP) Supabase PKCE callback designed; BFF cookies and DPoP not implemented Account linking / identity merge Supabase anonymous-upgrade and link semantics designed; implementation open Status revocation on refresh / access-token denylist Not implemented Per-app provider-client binding (auth_provider_client) Not implemented (config-driven) MFA / step-up / passkeys / rate-limiting Not implemented Multiplatform and client. The login state machine (AuthLoginState: idle → loading/waiting → signing-in → caching → authenticated/failed) is well-modeled and surfaced as a StateFlow that drives Compose/SwiftUI directly. Google works on Android, iOS, and Web; Apple is native on iOS and Web, but on Android needs an app-level web-OAuth flow (a documented, graceful refusal, not a crash); JVM / desktop is a stub. Two gaps: token storage is plaintext (above), and there is no first-class "restore session from cache" entry point independent of provider registration. Tests. Server-side coverage is strong — kernel authorization, graph wiring and handler projection, login/token/PAT/refresh/service-account/delegation flows, JWT round-trips with audience pinning and tamper/algorithm-pinning rejection, refresh reuse-detection, and architecture guardrails. Notable gaps: no test drives the graph-free consumer path; the edge WorkerJwtVerifier (crypto.subtle) is untested; the refresh-rotation concurrency window is untested; and the client adapters have no tests. Code quality. Mostly clean and consistent. Cleanup items: the old LoginInteractor service is vestigial — superseded by LoginInteractorNode, referenced only by its own test; AuthProviderClient is defined twice (kernel and RoleBasedAuth) with field drift (issuer nullability, redirectUris type); the kernel SPI interfaces (Authenticator, TokenIssuer, SessionManager, TokenVerifier, PermissionResolver, TenantResolver) are defined but unimplemented — ship reference implementations or label them explicitly as a future SPI; and error-handling and logging styles differ between the legacy services classes and the runtime nodes. Operational. The audit trail is a real operational strength. Hardening: signing-key configuration should fail closed in production (the ephemeral-key fallback is silent); the tid (tenant) claim is minted only when present, so the multi-tenancy carrier is otherwise inert (see the reaktor-multitenancy doc); key rotation via config swap (ec-jwk + ec-jwk-prev) is sound. Prioritized recommendations. Bound credential-issuance to the caller's authority (PAT mint and token exchange) — specifics in the internal security review. Enforce principal/membership status on refresh; make audience-pinning the default at the bearer filter. Add the graph-free AuthRuntime facade plus a guardrail test that drives auth without naming Graph. Secure client token-at-rest with the platform keystore. Cleanup: delete LoginInteractor, de-duplicate AuthProviderClient, resolve the kernel SPIs, and refresh the section 07 node table. Build out the open use cases: Supabase email/password/magic-link/OTP, anonymous app policy and link/upgrade, browser Authorization Code + PKCE / BFF cookies, account linking/merge, and persisted may_act. ## 24. Open Work Section ID: open-work 24. Open Work The next increments are: Supabase provider adapter: UserAuthenticationProvider.Supabase, issuer / audience / JWKS verification, provider-account resolution, and POST /auth/sign-in provider=SUPABASE. Supabase email facade: start/verify for magic link and OTP, password sign-in, password reset, PKCE/token-hash callback, redirect allowlists, rate limits, and audit. Anonymous app policy and bootstrap: first-launch entry, app-configured guest/demo flows, per-flow limits, Worker route policy, and link/upgrade. Browser Authorization Code + PKCE. BFF __Host- cookie model for web. DPoP for sender-constrained public-client tokens. Persisted may_act delegation policy. ReBAC object tuples for instance-level permissions. First-class session device/IP/user-agent metadata. Mobile auth panes backed by live auth event/session APIs instead of fixtures. The desktop pane no longer uses fixtures: it reads heimdall directly through the workbench kernel, described in Workbench Layers. That is schema access, not the auth service's own APIs, so an API-backed pane is still the target for any surface that cannot reach the database — and for anything the schema does not record, such as session device and address metadata (item 9). Provider authorization (§31): Google and Apple OAuth authorization codes, the provider_grant store, server-side token exchange and refresh, a runtime reader for auth_provider_client, and the provider-side revocation Apple requires on account deletion. ## 25. Design Review: Heimdall as a General-Purpose Auth Solution Section ID: general-review 25. Design Review: Heimdall as a General-Purpose Auth Solution Added 2026-07-01. Sections 01–22 describe how the system works today; §23–§24 assess the code and list open work. This part steps back to a different question: is the underlying model a good basis for a general auth solution that other systems — not just Reaktor's own apps — could adopt? It covers the model verdict, two specific design questions, how Heimdall compares to the wider landscape, and the design changes that would close the gap. It is forward-looking, and in places proposes evolving the model in §04–§05. Terms used here. Authentication (authn) is proving who a caller is; authorization (authz) is deciding what they may do. An IdP (Identity Provider) logs users in; an AS (Authorization Server) issues tokens; a broker delegates login to an external IdP and issues its own tokens on top. RBAC is role-based access control (permissions through roles); ABAC is attribute/condition-based; ReBAC is relationship-based — "you may edit this document because you own the folder it lives in" — which is Google's Zanzibar model, implemented by SpiceDB, OpenFGA, and Ory Keto. PAT is a personal access token; M2M is machine-to-machine; MFA is multi-factor auth; passkey / WebAuthn is phishing-resistant public-key login; SAML / SCIM are the enterprise single-sign-on and user-provisioning standards. ## 25.1 Is this a good model? Section ID: is-it-good 25.1 Is this a good model? Yes — and on two axes it is ahead of most commercial products: how it models AI agents (the AGENT and ACTOR principal kinds) and how it models acting-on-behalf-of (RFC 8693 delegation, preserving both actor and subject). The clean separation of identity (the person), provider account (their external logins), and principal (the thing that acts) is the model's biggest strength and matches how the most sophisticated systems are built. The weak points are three: the tenant/context multi-tenancy model (§25.2, §26), authorization that is RBAC-only today (resource-level permissions need a relationship or policy plane — §28), and the absence of first-party login (no passwords, passkeys, or MFA — §27). ## 25.2 Two model questions Section ID: two-questions 25.2 Two model questions Do you need separate tenant and context? The two ideas are legitimate — even Microsoft Entra keeps "which directory you are in" separate from "which resource a permission applies to." But Heimdall encodes them as two independent optional columns (§04), and that creates an inconsistency: a role grant (principal_role) can be narrowed to a context but never to a tenant. So "Alice is Admin in the Acme tenant" cannot be stated directly — you grant Admin app-wide and re-filter by tenant in application code, or invent a context that stands in for the tenant. By contrast, Auth0 Organizations makes "role R for user U in org O" a first-class, enforced fact. The recommendation is to merge tenant and context into one hierarchical context (§26). Why are roles app-scoped, not context-scoped? This part is correct and worth keeping. "Define a role once per product/app surface, then grant it in a specific place" is what Auth0, Okta, Azure, and Keycloak all do; defining roles per-context would explode the catalog and lose reuse. The role definition stays audience/product-scoped; the grant carries the context. ## 25.3 How Heimdall compares to the landscape Section ID: landscape 25.3 How Heimdall compares to the landscape In shape, Heimdall is a self-hosted, database-first system in the Keycloak/Ory family. It is ahead on agents and delegation, even on token handling, and behind on first-party login, fine-grained (relationship-based) authorization, and enterprise SSO. Product Identity / principal model Multi-tenancy Authorization Agents / M2M / delegation First-party login + MFA Shape Heimdall identity + typed principal (user/service/agent/actor) — strong app + tenant + context (two-axis, weak) RBAC + scope token-exchange / delegation — strong none self-hosted, DB-first broker + AS Auth0 user + linked identities Organizations RBAC + FGA (add-on) M2M apps yes (+ passkeys, MFA) SaaS Okta user + factors orgs / groups groups + policies service apps yes, + SCIM/SAML SaaS, enterprise Keycloak user + federation realms realm/client roles, groups client service accounts yes open-source, self-host Cognito user pools pools (≈ tenant) groups (weak) app clients yes (basic) AWS Clerk user + orgs Organizations org roles / permissions limited yes (passkey-first) SaaS, strong DX WorkOS user + orgs Organizations RBAC + FGA yes via AuthKit, + SAML/SCIM SaaS, enterprise-readiness Stytch member / org Organizations (B2B) RBAC M2M yes (passkeys/OTP) SaaS, B2B Ory Kratos identities namespaces Keto = Zanzibar ReBAC Hydra (OAuth AS) Kratos flows open-source, composable SpiceDB / OpenFGA — (authorization only) namespaces ReBAC only — — authorization engine Entra ID identities directory tenant ≠ RBAC scope tree RBAC with scope hierarchy service principals / managed identities yes cloud Supabase Auth users none (row-level security) RLS in the database service-role key yes (basic) DB-centric The reading: Heimdall's durable edge is the agent/delegation model and the graph integration (§28). The gaps to close for general adoption are first-party credentials + MFA (§27), a relationship/policy authorization plane (§28, and the "ReBAC object tuples" already in §24), the tenant/context model (§26), and enterprise SAML/SCIM (§24). ## 26. Unified Context: resolving tenant vs. context Section ID: unified-scope 26. Unified Context: resolving tenant vs. context A proposed evolution of the §04 model; pairs with the multitenancy doc. In plain terms: instead of separate tenantId and contextId fields that do not compose, model one hierarchical context tree. A tenant is a context near the top. An app surface is also a context. A concrete resource is a context near the bottom. A role granted at any context applies to that context and, when allowed by policy, to everything beneath it. This supports two important cases without building separate auth systems: One product, many app surfaces. A product like Swiggy can have one product root context with child contexts for customer, driver, restaurant, darkstore, support, and internal operations. Each surface can have its own audience, roles, service accounts, and policies, but identities, grants, audits, and tokens stay in one auth system instead of being duplicated per app. Authority at any hierarchy level. A restaurant owner can be admin for a restaurant context, a manager for one outlet, an operator for a menu section, and a user can be admin of their own posts without being admin of someone else's posts. The grant attaches to the context node where authority starts; resource checks resolve whether the requested resource is inside that subtree. audience and context are deliberately different. audience says who the token is for: swiggy.restaurant-api, swiggy.driver-api, reaktor.workbench, etc. context says where the caller's authority applies inside the product/resource hierarchy. New tokens should not need a separate token-facing appId claim; the audience is the app/surface namespace. create table heimdall.context ( id uuid primary key default gen_random_uuid(), audience varchar(160) not null, -- product or app-surface namespace parent_id uuid references heimdall.context(id) on delete cascade, kind varchar(32) not null, -- 'PRODUCT' | 'APP_SURFACE' | 'TENANT' | 'RESOURCE' | ... key varchar(120) not null, name varchar(100) not null, status varchar(50) not null default 'ACTIVE', path ltree, -- materialized path, so "is X under Y?" is one indexed lookup unique (audience, parent_id, key) ); -- Grants, sessions, memberships, PATs, and service accounts each reference one context_id. -- The new context_id replaces the old tenant_id + context_id split. alter table heimdall.principal_role add column context_id uuid references heimdall.context(id); alter table heimdall.membership add column context_id uuid references heimdall.context(id); alter table heimdall.session add column context_id uuid references heimdall.context(id); alter table heimdall.personal_access_token add column context_id uuid references heimdall.context(id); alter table heimdall.service_account add column context_id uuid references heimdall.context(id); A role granted at context C then satisfies a requirement at C or anything beneath C — the same inherited model Azure RBAC and Zanzibar use. The ltree path makes "is this required context under that granted context?" a single indexed comparison rather than a recursive query per check. In the kernel (AuthContext / AuthRequirement), tenantId disappears and the existing contextId becomes the one canonical authority location, with a resolved contextPath. LocalAuthorizer allows the request when the grant's context path is a prefix of the required resource context path. This makes tenant isolation engine-enforced rather than application-enforced (today §05 notes isolation rests on "AuthContext plus resource checks"), removes the tenant/role asymmetry from §25.2, gives the relationship plane in §28 its hierarchy for free, and still scales down cleanly for a simple app: create one product root context and grant there. Migration is intentionally not part of this implementation pass: add the new context table, backfill product/app-surface/tenant/resource contexts from existing tenant and context values, dual-write for one release, switch reads over, then drop tenantId and legacy duplicate context encodings. ## 27. First-Party Credentials and MFA Section ID: first-party-credentials 27. First-Party Credentials and MFA The §23/§24 status lists MFA, passkeys, and Reaktor-native email login as not-yet-implemented or Supabase-delegated. This section sketches the first-party design — the path from "broker" (§12, where Supabase owns the email credential) to a self-contained IdP. Today login happens only through provider_account (federation), plus PATs and service accounts. The AuthMethod enum already has the slots; the missing piece is the credential stores: heimdall.password_credential (id, identity_id fk, hash /*argon2id*/, algo, rotated_at, breached_at, ...) heimdall.webauthn_credential (id, identity_id fk, credential_id bytea unique, public_key, sign_count, transports, aaguid, nickname, created_at, last_used_at) -- passkeys (FIDO2) heimdall.mfa_factor (id, identity_id fk, type /*TOTP|SMS|WEBAUTHN*/, secret_ref /*Secret Manager*/, status, verified_at) heimdall.verification_token (id, identity_id fk, purpose /*email|phone|password_reset|magic_link*/, token_hash, expires_at, used_at) heimdall.recovery_code (id, identity_id fk, code_hash, used_at) -- step-up / assurance: record HOW and HOW STRONGLY a session authenticated alter table heimdall.session add column amr text[] default '{}'; -- e.g. ['pwd','otp','webauthn'] alter table heimdall.session add column acr varchar(32); -- assurance level, e.g. 'aal2' AuthContext already records the auth method; adding amr/acr lets a requirement demand step-up (e.g. AuthRequirement.requiresAcr("aal2") for sensitive actions). New AuthService operations follow the existing facade shape: registerPassword, beginPasskey/finishPasskey (the WebAuthn handshake), enrollTotp/verifyTotp, and the email/OTP flows already designed in §12. A brute-force lockout (a failed-attempt counter, or derived from auth_audit_event over a sliding window) completes it. Crucially, the Reaktor rule from §12 still holds: a credential proves a login; Reaktor still owns principal, membership, session, tokens, authorization, and audit. The first-party layer simply means Reaktor can be the credential store (passkeys, password, MFA) instead of always delegating to Supabase or a social provider — which is what "auth for most systems" requires. ## 28. Graph Amplification: auth that travels with causality Section ID: graph-amplification 28. Graph Amplification: auth that travels with causality Extends §19. The thesis: running auth inside the Reaktor graph is not just convenient wiring — the graph supplies authorization capabilities a standalone library cannot. The component tree can double as the permission hierarchy. Reaktor already arranges an app as a tree of nodes. If each node also stands for a "place" in the context hierarchy (§26), then granting a role on a parent node automatically grants it on everything beneath — exactly the inherited, relationship-based authorization plain RBAC lacks. A Zanzibar-style system needs a graph of objects to reason over; reaktor-graph already is that graph. The kernel's AuthRequirement already carries a resource reference and anyOf/allOf composition (RBAC plus attribute-style conditions); what is missing is a relationship backing for the resource seam, and the graph supplies it. This is the same capability §24 tracks as "ReBAC object tuples." ServiceNode makes authorization part of typed routing. Each request handler is already exposed as a port; attaching an AuthRequirement to the handler means every call is checked uniformly, declared once, on both client and server (today via AuthRequirementInterceptor). SecuredProviderPort / SecuredConsumerPort are capability-based security wired into dependency injection (§19) — a dependency edge that only connects when the caller satisfies a requirement. Very few frameworks have this. The gap: enforcement is currently manual (enforceConnectionSecurity()); making it automatic at wire time would flip the default from "open unless you remember to check" to "closed unless explicitly opened." ActorNode plus AGENT/ACTOR principals plus token-exchange give first-class authorized agents. Run an actor node under a delegated AuthContext (the user's token exchanged with the agent's service identity) and every message it processes is attributed, serialized, and auditable as "agent acting for user" — the same subject/actor pair the audit trail already records (§17). Ambient AuthContext via ports: any node can consume the current caller, typed, without threading it through every call. Aspirational: route guards (an AuthRequirement on a navigation node), and a workbench view that renders the authorization model as a live graph — feasible because scopes, grants, and secured ports are all graph objects. Standalone, Heimdall is a Keycloak/Ory-class library (kernel + interceptors + client). Inside the graph, the component tree becomes the permission hierarchy, dependency wires become capability-secured, AI agents become delegated actor nodes, and the authorization model becomes inspectable. Most of the wiring exists (§19); the high-value next steps are automatic secured-port enforcement, letting graph topology supply the context hierarchy (§26), and route guards. ## 29. Use-Case Archetypes Section ID: use-case-archetypes 29. Use-Case Archetypes A general auth solution has to serve more than one shape of system. These archetypes are the test set: if the model serves all of them, it serves most systems. Archetype Principal kinds Tenancy Authorization need What it stresses Consumer social (the reference app) USER, AGENT (bots), SERVICE (workers) single app, flat simple roles plus per-resource grants (per-chat / per-group) resource-level authorization, agent principals, social login Developer platform USER (devs), SERVICE (CI), AGENT (tools), PATs multi-app PATs, service accounts, app-scoped admin machine-to-machine, PAT lifecycle, multi-app isolation, delegation Personal / single-owner app USER (owner), AGENT (AI assistant) personal, light sharing owner-has-all plus per-workspace shared scope delegation, scope-per-workspace, share links Regulated B2B commerce USER (org members), SERVICE (integrations), ACTOR (delegated ops) multi-tenant organizations org roles plus resource-level plus relationship-based plus immutable audit everything at once — the forcing function Internal back-office USER (employees), SERVICE departmental scopes employee roles, department-scoped, internal SSO internal RBAC, single sign-on Third-party SaaS customers all of the above hard per-customer isolation full IdP (passkeys/MFA), SAML/SCIM, organizations the global-identity assumption breaks The forcing function is regulated B2B commerce (multi-tenant organizations with financial and audit obligations): it needs the context hierarchy (§26), relationship-based visibility (§28), an immutable tamper-evident audit trail, delegation (an operator acting for an account), and strong auth / MFA (§27) — all at once. The consumer-social archetype exercises resource-level grants and agent principals; the developer-platform archetype exercises PATs, service accounts, and multi-app isolation; the personal-app archetype exercises agent delegation and per-workspace contexts. The one assumption to revisit before serving isolated third-party customers is global identity (§04, §25.1): one identity shared across apps suits a single-owner multi-app platform, but not customers who each require a sealed user pool. ## 30. Perspective Reviews Section ID: perspective-reviews 30. Perspective Reviews Security-threat, compliance, developer-experience, and performance lenses. Complements the code/security assessment in §23. ## 30.1 Threat model (STRIDE) Section ID: threat-model 30.1 Threat model (STRIDE) Threat What is defended What is still open Spoofing (faking identity) JWT verification (signature + audience + expiry); typed principals the dev-only header path (ALLOW_USER_HEADER_AUTH, §10) must be provably off in production Tampering (altering tokens) signed ES256 tokens; refresh-token rotation with revoke-on-reuse tokens are not yet sender-bound (DPoP/mTLS, §24), so a stolen token is usable Repudiation (denying an action) append-only audit log with actor vs. subject retention and tamper-evidence (a hash chain) for financial use Information disclosure secrets stored as hashes or references, never raw keep security-critical claims/PII in typed columns, not free-form JSON Denial of service per-role statement timeouts no rate-limiting or account lockout primitive yet Elevation of privilege LocalAuthorizer capability/role checks; secured ports tenant isolation is application-enforced until §26; secured-port enforcement is manual until auto-enforce (§28) The token-theft posture is strong (short-lived access tokens, rotating refresh tokens, reuse detection). The remaining work is token binding, rate-limiting/lockout, and secure-by-default enforcement. ## 30.2 Compliance Section ID: compliance 30.2 Compliance SOC 2 / ISO 27001: the audit trail is in place; add a retention policy, periodic access reviews (exporting who-has-what), and break-glass logging. GDPR: right-to-erasure means deleting an identity must cascade to its provider accounts, memberships, and sessions; add per-context data residency once the unified context hierarchy is real; add consent records if Heimdall ever issues tokens to third-party apps. Regulated / financial: needs an immutable, tamper-evident audit log (it is append-only today; add a hash chain), separation of duties via roles, strong auth / MFA (§27), and KYC linkage through provider accounts. ## 30.3 Developer experience Section ID: dx 30.3 Developer experience Two on-ramps, matching the §01 design contract: simple — an AuthServiceClient plus permits("capability"); powerful — compose an AuthRequirement and gate ports with providesSecured, or mount the runtime with AuthGraph.install(graph). The single most valuable improvement is secure-by-default: today a developer must remember to add the interceptor or call enforceConnectionSecurity(); making enforcement automatic (§28) flips the default from "open unless gated" to "gated unless opened." ## 30.4 Performance and scale Section ID: performance 30.4 Performance and scale Identity resolution is the hot path, so building the AuthContext must stay cheap: verify JWTs statelessly at the edge (no database round-trip, §10), cache the verification keys (JWKS), and cache the resolved context on the client. Keep context ancestry checks cheap by resolving "is X under Y" through a materialized path (ltree) or closure table rather than a recursive query per check (§26). Keep tokens small: prefer audience-bound tokens with server-side fine-grained checks over inlining an unbounded permission set into every JWT. ## 30.5 Build vs. buy Section ID: build-vs-buy 30.5 Build vs. buy Extend Heimdall for graph-native capability security, agent delegation, self-hosting, and Kotlin-multiplatform reach. Reach for Auth0 / Okta / WorkOS when you need turnkey enterprise SSO, SCIM, and a connection marketplace today. The agent/delegation model and the graph amplification are the parts that are not commodities. ## 31. Provider Authorization: Google and Apple OAuth Section ID: provider-authorization 31. Provider Authorization: Google and Apple OAuth Design snapshot: 2026-08-27. Provider authentication resolves a credential to a Reaktor principal. Provider authorization obtains and holds a grant for API calls on the user’s behalf. At this snapshot, reaktor-auth authenticates Google and Apple identities but does not implement provider API authorization; the following design maps the remaining work to the existing schema. ## 31.1 The gap: authentication is not authorization Section ID: authz-gap 31.1 The gap: authentication is not authorization Reaktor asks Google and Apple exactly one question: who is this? It receives an ID token — a signed assertion about identity — verifies it against the provider's JWKS (§06), resolves a principal, and discards it. It never asks the second question: which actions are authorized on your behalf? That second question is answered by an OAuth authorization code, exchanged server-side at the provider's token endpoint for an access token, a refresh token, and a set of granted scopes. reaktor-auth has no code path that requests one, no wire field that carries one, no repository that stores one, and no service that refreshes one. The distinction bites the moment a product wants to read the user's Drive, list their Calendar, send through Gmail, or comply with Apple's account-deletion rule. An ID token does none of those. It is login proof — not a bearer token for provider APIs. This is precisely the boundary §12 draws for Supabase, applied in the other direction. One clarification, because the vocabulary collides. §11 and §24 already list "Browser Authorization Code + PKCE" as open work; that item is about Reaktor's own browser login becoming a proper code flow. This section is about the provider's code flow. They are independent: either can land first, and both use PKCE for the same reason. ## 31.2 What the six client surfaces already offer Section ID: provider-surfaces 31.2 What the six client surfaces already offer Provider Platform SDK in use Captured today Authorization is reached by Distance Google Android GetSignInWithGoogleOption (Credential Manager) idToken a separate AuthorizationClient call (Play Services Identity) returning serverAuthCode + granted scopes new SDK surface Google iOS GIDSignIn idToken addScopes(...), then user.serverAuthCode — which requires serverClientID already configured, code never read Google Web google.accounts.id (One Tap) credential (ID token) google.accounts.oauth2.initCodeClient different GIS namespace, not yet bound Apple iOS ASAuthorizationAppleIDProvider identityToken ASAuthorizationAppleIDCredential.authorizationCode same object already being read Apple Web AppleID.auth authorization.id_token authorization.code same object, field already declared Apple Android none — web flow in a Custom Tab returning code to a deep link AndroidAppleLogin is a fail() stub The encouraging read: on three of the six surfaces the authorization code is already sitting in an object the code parses and throws away. DarwinAppleLogin reads credential.identityToken and ignores credential.authorizationCode. WebAppleLogin reads authorization.id_token while AppleAuthorization.code is declared, typed, non-null, and unused. DarwinGoogleLogin already accepts and configures serverClientID — the only reason it produces no serverAuthCode is that nothing asks for it. The remaining work is plumbing and a server-side exchange, not new provider integrations. ## 31.3 What the schema already anticipated Section ID: authz-schema-today 31.3 What the schema already anticipated heimdall.auth_provider_client (AuthTables.kt) already exists and already carries the full OAuth client registration for a code flow: app_id · provider · platform · client_id · client_secret_ref issuer · apple_team_id · bundle_id · redirect_uris · enabled That is the config half, correctly shaped: keyed per (app, provider, platform), holding a reference to the client secret rather than the secret, with a redirect-URI allowlist and Apple's team/bundle identifiers — which are exactly the inputs to Apple's client-secret JWT (§31.4). It is also entirely inert. AuthProviderClients appears in the table list, has a DTO — declared twice, in both RoleBasedAuth.kt and kernel/AuthKernel.kt, which should be reconciled — and is created by the test fixture. No repository reads it and no interactor uses it. Provider verification today runs off statically constructed UserAuthenticationProvider.Google/Apple audiences in Authentication.kt, not off this table. So the gap is narrower than §31.1 suggests: the client-registration model is designed and migrated. What is missing is the grant, the exchange, and the runtime that reads the registration. ## 31.4 Apple's sharp edges Section ID: apple-specifics 31.4 Apple's sharp edges Sign in with Apple is not Google with different branding. Three of its behaviours cause permanent data loss or scheduled outages if a design ignores them. Name and email arrive exactly once. Apple returns fullName and email only on the first authorization for an app. Every later sign-in returns an identity token carrying a sub and nothing else. DarwinAppleLogin reads it.fullName?.givenName on every login, so a user who revokes and re-authorizes becomes permanently nameless. The fix is at the resolution layer, not the client: persist the name on the first provider_account insert and never overwrite it with a later blank. The client secret is a short-lived JWT, not a string. Apple's token endpoint expects an ES256 JWT signed with a .p8 key, iss = team ID, sub = the service/bundle ID, aud = https://appleid.apple.com, valid for at most six months. It must be minted, cached, and rotated — SigningKeys plus reaktor-secrets work. apple_team_id and bundle_id are in auth_provider_client for this reason. Any design that treats APPLE_CLIENT_SECRET as a static string has a scheduled outage in it. Revocation is a compliance requirement, and Reaktor currently cannot meet it. Apple requires apps offering account deletion to call the token revocation endpoint — which requires having kept the refresh token. AuthAdapter.deactivateAccount revokes Reaktor sessions and soft-deletes the principal, but cannot revoke at Apple, because §31.1 means no provider refresh token was ever stored. This is the one item on the list with an external deadline attached. Also worth recording: @privaterelay.appleid.com addresses only forward from domains registered with Apple, are per-app, and vanish when the user revokes. Store the relay address as the provider_account email, but treat it as non-canonical for anything that matters. ## 31.5 Model addition: the provider grant Section ID: provider-grant 31.5 Model addition: the provider grant provider_account (§04) records who the user is at a provider. It has no column for what the user let us do there — and should not gain one, because grants are per-app, independently revocable, and have a lifecycle of their own: heimdall.provider_grant ( id uuid primary key, provider_account_id uuid not null references heimdall.provider_account(id) on delete cascade, app_id uuid not null references heimdall.app(id), scopes text[] not null default '{}', access_token_ref text, -- Secret Manager reference, never the token access_expires_at timestamptz, refresh_token_ref text, -- ditto; Google issues this only with access_type=offline status varchar(20) not null default 'ACTIVE', -- ACTIVE | EXPIRED | REVOKED granted_at timestamptz not null default now(), last_refreshed_at timestamptz, revoked_at timestamptz -- plus the auditable mixin ); create unique index on heimdall.provider_grant (provider_account_id, app_id); The _ref columns are the load-bearing detail. §30.1 already records the rule — "secrets stored as hashes or references, never raw" — and a provider refresh token is the most dangerous secret this system can hold: it outlives every Reaktor token, grants access to systems Reaktor does not control, and cannot be rotated by Reaktor. It belongs in Secret Manager via reaktor-secrets, with the row holding only the reference, exactly as auth_provider_client.client_secret_ref already does. One enum addition, following the existing shape: AuthCredentialType.PROVIDER_GRANT("provider_grant"), so grants and revocations appear in auth_audit_event beside token mints. No AuthMethod addition. A provider grant is not a way to authenticate to Reaktor. Keeping it out of AuthMethod is what prevents the two concepts from collapsing back together. ## 31.6 Port and service shape Section ID: authz-ports 31.6 Port and service shape Follows the §07 decomposition — one capability port in commonMain, one node in the JVM runtime graph, one interactor with a strategy per provider: // commonMain — graph-agnostic capability port (module layering rule) interface AuthProviderGrants { suspend fun exchange(request: ProviderGrantRequest): ProviderGrantResult suspend fun grant(principalId: String, provider: AuthProviderKind, appId: String): ProviderGrant? suspend fun accessToken(grantId: String): String? // refreshes inside the skew window suspend fun revoke(grantId: String): Boolean // revokes at the provider, then marks the row } AuthProviderGrantNode (jvmMain) mounts it into AuthRuntimeGraph next to AuthTokenGrantNode. ProviderGrantInteractor performs exchange and refresh through a per-provider strategy: GoogleTokenEndpoint, and AppleTokenEndpoint wrapping the ES256 client-secret minter from §31.4. AuthProviderClientRepository finally gives auth_provider_client (§31.3) a reader, and Authentication.kt should source its audiences from it rather than from static construction. accessToken() mirrors AuthAdapter.sessionHeaders(): serve the cached token if it survives the 60-second skew, otherwise refresh, otherwise mark the grant EXPIRED and return null so the caller can prompt for re-consent. TokenRefreshWorker (reaktor-work) exists only as a placeholder shape for proactive refresh. Scheduled refresh is an optimization: the owning auth service must still check expiry and serialize refresh at use time. Device background execution cannot guarantee provider-grant availability. HTTP surface (§08): POST /auth/provider/authorize { appId, provider, authorizationCode, redirectUri?, codeVerifier? } GET /auth/provider/grants -> the caller's grants: provider, scopes, status. Never tokens. POST /auth/provider/grants/{id}/revoke Note the asymmetry that keeps this safe: the provider access token never travels back to the client. The client asks Reaktor to act with a grant; it does not receive the grant. A compromised device then costs the attacker a short-lived, revocable Reaktor session rather than standing access to the user's Google account. A product that genuinely needs a client-side provider token — a browser mounting the Drive picker, say — should request it from the provider directly with a narrow scope and keep it out of Reaktor entirely. ## 31.7 Client surface changes Section ID: client-authz 31.7 Client surface changes The wire type gains one optional field rather than a parallel type, so the existing login path is untouched when nothing requests authorization: interface AuthProviderUser { val idToken: String val authorizationCode: String? // new: non-null only when scopes were requested // ... } Provider authorization becomes an optional capability a provider may implement, rather than a parameter every provider must accept: interface ProviderAuthorization { val supportedScopes: Set suspend fun authorize(scopes: Set): Result } AndroidGoogleLogin, DarwinGoogleLogin, WebGoogleLogin, DarwinAppleLogin, and WebAppleLogin implement it; anything that cannot do it simply cannot be asked, and the type system says so. This holds the §01 contract: the 80% path (login()) does not grow a scopes parameter, and the 20% path stays reachable by asking a provider for the capability. Incremental (scope-up) authorization should be the default: sign the user in with no scopes, then request Drive or Calendar at the moment the feature is first used. Google's consent screen rewards this, and it keeps a first-run login from presenting a wall of permissions the user has no context for. ## 31.8 Flow Section ID: authz-flow 31.8 Flow 1 User already has a Reaktor session (§11) 2 A feature needs provider scope S 3 Client calls ProviderAuthorization.authorize(setOf(S)) 4 Provider SDK returns an AUTHORIZATION CODE (not an access token) 5 Client POSTs /auth/provider/authorize with the code and its Reaktor bearer 6 AuthProviderGrantNode verifies the caller and resolves the provider account 7 ProviderGrantInteractor reads auth_provider_client, exchanges the code at the provider token endpoint (Apple: minting the ES256 client secret first) 8 Access + refresh tokens go to Secret Manager; provider_grant stores refs + scopes 9 auth_audit_event records the grant — provider, app, scopes; never the tokens 10 Server-side features call AuthProviderGrants.accessToken(grantId) and act as the user ## 31.9 Security rules Section ID: authz-security 31.9 Security rules Mirrors §12's rules, in the other direction: A provider grant never authenticates to Reaktor. Holding a Google access token proves nothing about a Reaktor principal. Provider refresh tokens live in Secret Manager, referenced from provider_grant — never in a database column, never in a log, never in an audit payload. Exchange is server-side only. The client sends a code; the client never sees the resulting tokens. PKCE on every browser and native code flow, with the auth_provider_client.redirect_uris allowlist enforced on every exchange. Scopes are recorded, capped per app by configuration, and audited. An app may not exchange a code for scopes it is not configured to hold. Account deactivation must revoke at the provider, not merely mark rows — required by Apple (§31.4), courteous with Google. Grants are per (identity, app), never global. §29's caveat about the global-identity assumption applies with force here: one identity spanning apps must not mean one Drive grant spanning apps. ## 31.10 Increments Section ID: authz-increments 31.10 Increments Carry authorizationCode on AuthProviderUser and read it where it is already free — ASAuthorizationAppleIDCredential.authorizationCode and Apple web authorization.code. No new SDK surface; unblocks Apple revocation compliance. provider_grant table, AuthProviderGrants port, AuthProviderGrantNode, AuthProviderClientRepository, and the Google token-endpoint strategy. Google scope-up across the three client surfaces: Android AuthorizationClient, iOS addScopes, web initCodeClient. Apple token endpoint with the ES256 client-secret minter and rotation, plus first-authorization name capture (§31.4). POST /auth/provider/authorize, grant listing, revocation, and wiring revocation into account deactivation. Proactive refresh via TokenRefreshWorker, the EXPIRED transition, and a re-consent signal to the client. AndroidAppleLogin via Custom Tab plus deep link, closing the stub. Reconcile the duplicated AuthProviderClient DTO (§31.3) and move Authentication.kt audiences onto the table. Steps 1 and 2 are load-bearing; everything after is a strategy or a surface on top of them. ## Related docs Section ID: related-docs Related docs Security Plan - Use before enabling deploy actions, remote agents, or privileged commands. Multitenancy - Use before designing tenant isolation, adding a tenant-scoped store, wiring the tid claim, or building per-tenant quotas/residency/lifecycle; pairs with reaktor-server (high-scale tenancy) and auth-analysis (the membership model). Reaktor Secrets - Use before moving, rotating, distributing, caching, or materializing secrets. Deep Links - Use before adding route-driven external entry points. Service Layer - Use before adding service APIs, splitting reaktor-service out of reaktor-graph, wiring handlers to Spring/Workers, or making modules graph-projectable without hard graph dependencies. DevOps - Use before changing the build/deploy/ops pipeline, the Kotlin platform model, deployment partitioning, gated deploy operations, or the reaktorDesktop Deploy pane; pairs with reaktor-cloud-pane (operator view) and secrets-management. # BestBuds Public and Heimdall Schema Hardening URL: https://reaktor.build/docs/bestbuds-schema-hardening Status: unverified Content revision: c9cae42e6b9c45ca798fd93a2d00c2c35ddeadf1f39a935616888e323599e4f1 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/bestbuds-schema-hardening","polarity":"Neutral"},{"id":"section-current-verdict","anchor":"current-verdict","label":"Current Verdict","profile":"section","contract":"https://reaktor.build/docs/bestbuds-schema-hardening#current-verdict","polarity":"Neutral"},{"id":"section-evidence-snapshot","anchor":"evidence-snapshot","label":"Evidence Snapshot","profile":"section","contract":"https://reaktor.build/docs/bestbuds-schema-hardening#evidence-snapshot","polarity":"Neutral"},{"id":"section-source-anchors","anchor":"source-anchors","label":"Source Anchors","profile":"section","contract":"https://reaktor.build/docs/bestbuds-schema-hardening#source-anchors","polarity":"Neutral"},{"id":"section-design-goal","anchor":"design-goal","label":"Design Goal","profile":"section","contract":"https://reaktor.build/docs/bestbuds-schema-hardening#design-goal","polarity":"Neutral"},{"id":"section-boundary-model","anchor":"boundary-model","label":"Boundary Model","profile":"section","contract":"https://reaktor.build/docs/bestbuds-schema-hardening#boundary-model","polarity":"Neutral"},{"id":"section-required-invariants","anchor":"required-invariants","label":"Required Invariants","profile":"section","contract":"https://reaktor.build/docs/bestbuds-schema-hardening#required-invariants","polarity":"Neutral"}],"relations":[{"id":"bestbuds-schema-hardening:references-reaktor-data-implementation-documents","kind":"references","owner":"bestbuds-schema-hardening","incidences":[{"node":"bestbuds-schema-hardening","port":"page","role":"source","ordinal":0},{"node":"reaktor-data-implementation","port":"section-documents","role":"target","ordinal":0}]}]} ## BestBuds Public and Heimdall Schema Hardening Section ID: preamble :::info[Dated schema evidence] This report retains the July 2026 schema/permission observations and migration design. It is not a fresh October production audit or proof that every proposed change shipped. Revalidate queries, grants, RLS and runtime paths against the current schema before applying the plan. Heimdall owns identity; product tables and compatibility views require their own scoped constraints. The older Supabase-identity audit is retired in the data document register. ::: This page is the working plan for making the BestBuds Postgres schema safe after the Heimdall migration. The current direction is correct: Heimdall owns identity, principals, memberships, sessions, refresh tokens, PATs, service accounts, signing keys, roles, permissions, and audit. The old public schema remains the product data surface for chat, friends, groups, campaigns, onboarding, stickers, moderation, and app-facing compatibility views. The problem is the boundary between them. The public schema was made compatible by wide views over Heimdall. That kept old app queries working, but it also made several hot paths depend on duplicate-producing joins, JSON expression lookups, broad OR predicates, and aggregation through views. That is acceptable for a migration bridge. It is not the shape to scale. ## Current Verdict Section ID: current-verdict Current Verdict Do not optimize the current compatibility layer in place as the long-term model. Use the current compatibility views only as a temporary bridge while moving runtime paths to app-scoped, one-row-per-principal projections and direct product tables. The core issue is not "Postgres is slow" or "Heimdall is slow." The core issue is that the public compatibility layer hides identity resolution, app scoping, legacy alias matching, and user presentation inside broad views that are joined from many product queries. ## Evidence Snapshot Section ID: evidence-snapshot Evidence Snapshot Observed live on July 3, 2026 against Supabase Postgres 15.8: Area Live signal Meaning public.users_view 38 rows for 33 distinct ids The view is not one row per principal. Duplicate users 4 duplicated ids, one with 3 memberships Multi-membership principals fan out through app queries. Messages 656 rows Current timings are not scale evidence. Largest auth tables auth_audit_event 987, refresh_token 792, session 739 Auth tables are still small, but they are already the highest growth path. topMessages fanout 8 relevant chats -> 1120 base message rows -> 3215 after sender join -> 6125 after receiver join users_view joins multiply work and rows. topMessages plan about 53 ms with JIT off Already expensive on tiny data. Lateral top-5 probe about 4 ms with JIT off Query shape, not hardware, is the problem. Refresh-token families 2 families with multiple currently usable tokens Rotation is race-prone. Sticker schema live has tray_icon_r2_key, file_r2_key, size_bytes; current app code expects tray_icon_url, file_url Source/runtime/live drift exists outside auth too. Grants/RLS anon can select Heimdall tables and has CRUD on many public relations Security and operational boundaries are too broad. These counts are small. Any query that already shows fanout, row inflation, or write-race symptoms at this size should be treated as structurally unsafe. ## Source Anchors Section ID: source-anchors Source Anchors The important files are: Layer File Why it matters Heimdall canonical schema reaktor/reaktor-auth/src/jvmMain/kotlin/dev/shibasis/reaktor/auth/heimdall.sql Defines the phase-2 auth model and indexes. Public product schema bestbuds/modules/app/src/jvmMain/kotlin/ai/bestbuds/app/db/schema.sql Defines chat, friends, groups, campaigns, onboarding, stickers, and older compatibility views. Heimdall compatibility views bestbuds/modules/app/src/jvmMain/kotlin/ai/bestbuds/app/db/auth_v2_views.sql Rebuilds users_view, friends_view, groups_view, group_view, and campaigns_view over Heimdall. Worker identity bridge bestbuds/modules/app/src/jsMain/kotlin/ai/bestbuds/app/cloudflare/core/BestBudsRequest.kt Runs resolveBestBudsDataUserId on authenticated requests. Messaging queries bestbuds/modules/app/src/jsMain/kotlin/ai/bestbuds/app/cloudflare/messaging/MessagingWorkerRepository.kt Owns message create/read/reactions/topMessages. Social queries bestbuds/modules/app/src/jsMain/kotlin/ai/bestbuds/app/cloudflare/social/SocialWorkerRepository.kt Owns friends, groups, campaigns, and user profiles. Campaign bot queries bestbuds/modules/app/src/jsMain/kotlin/ai/bestbuds/app/cloudflare/campaign/CampaignEngagementRepository.kt Owns campaign signal aggregation and active-campaign scans. Auth transactions reaktor/reaktor-auth/src/jvmMain/kotlin/dev/shibasis/reaktor/auth/services/SessionRefreshService.kt Owns session creation, refresh rotation, and logout. PAT transactions reaktor/reaktor-auth/src/jvmMain/kotlin/dev/shibasis/reaktor/auth/services/TokenInteractor.kt Owns PAT create/verify/revoke and last_used_at writes. ## Design Goal Section ID: design-goal Design Goal The target state is simple: Heimdall remains the canonical auth database. Public tables remain product facts. Compatibility is explicit, app-scoped, indexed, and bounded. Hot product queries do not join through broad identity views. Legacy identity matching is a data migration problem, not a per-request query problem. Every write path with a uniqueness or single-use invariant is enforced by the database, not only by application order. ## Boundary Model Section ID: boundary-model Boundary Model Treat the database as three layers. Layer Owns Query rule heimdall canonical auth identity, provider accounts, principals, memberships, scopes, RBAC, sessions, refresh tokens, PATs, service accounts, signing keys, audit Auth code can query this directly. Product code should cross through small projections only. public product facts user profile extensions, friends, groups, messages, campaigns, onboarding, stickers, moderation Product queries should stay here after the principal id is known. Compatibility projection app user profile, legacy aliases, display fields needed by old product code Must be app-scoped, one row per principal, indexable, and replaceable. The current users_view mixes all three layers. It returns presentation data, identity aliases, membership state, profile extension data, and embeddings in one view. That makes it convenient, but also makes every downstream join pay for identity resolution. ## Required Invariants Section ID: required-invariants Required Invariants These invariants should become explicit migration gates. Invariant Why it matters Enforcement One canonical BestBuds data user id Avoid per-request id guessing. public.user_profiles.id = heimdall.principal.id for canonical users. One app-facing user row per (app_id, principal_id) Stop view fanout. Compatibility table or materialized projection with unique key. Legacy aliases are indexed rows Avoid OR matching and JSON scans. user_identity_alias(app_id, alias_kind, alias_value) unique index. Public product FKs point at canonical data ids Keep messages/friends/groups/campaigns stable. FK constraints plus repair/backfill checks. Refresh token is single-use under concurrency Prevent parallel refresh reuse from minting two valid successors. Row lock or atomic UPDATE ... RETURNING; optional partial unique invariant. Query ordering matches indexes Keep chat reads bounded. (chat_id, created_at DESC) for message history and top-N. Public views are not security boundaries Avoid broad anon exposure. Revoke broad grants, enable RLS where Supabase roles are used, use service credentials for Workers. ## Replace users_view as a Hot Path Section ID: replace-users-view Replace users_view as a Hot Path The current users_view is useful for compatibility, but it is too broad for hot paths. Current shape: CREATE VIEW public.users_view AS SELECT ... FROM heimdall.principal p LEFT JOIN heimdall.identity i ON p.identity_id = i.id LEFT JOIN LATERAL ( SELECT pa.* FROM heimdall.provider_account pa WHERE pa.identity_id = p.identity_id ORDER BY pa.created_at DESC LIMIT 1 ) pa ON TRUE JOIN heimdall.membership m ON m.principal_id = p.id LEFT JOIN public.user_profiles up ON p.id = up.id LEFT JOIN public.embeddings e ON p.id = e.target_id AND e.target_type LIKE '%User%' WHERE p.kind IN ('USER', 'AGENT', 'ACTOR') AND p.status = 'ACTIVE' AND m.status IN ('ACTIVE', 'INVITED'); Problems: no m.app_id = BestBuds app id filter; one row per matching membership, not one row per principal; lateral provider account lookup on each principal row; JSON merge on every read; embedding join via LIKE '%User%', which is not a precise target type; downstream joins inherit the duplicate rows. The replacement should be a table or materialized projection: CREATE TABLE public.bestbuds_user_projection ( app_id uuid NOT NULL, principal_id uuid NOT NULL REFERENCES heimdall.principal(id) ON DELETE CASCADE, data_user_id uuid NOT NULL REFERENCES public.user_profiles(id) ON DELETE CASCADE, membership_id uuid NOT NULL REFERENCES heimdall.membership(id) ON DELETE CASCADE, status text NOT NULL, display_name text NOT NULL, social_id text, provider text NOT NULL, email text, profile_picture text, data jsonb NOT NULL DEFAULT '{}'::jsonb, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL, PRIMARY KEY (app_id, principal_id), UNIQUE (app_id, data_user_id) ); CREATE INDEX bestbuds_user_projection_email_idx ON public.bestbuds_user_projection (app_id, lower(email)) WHERE email IS NOT NULL; CREATE INDEX bestbuds_user_projection_social_idx ON public.bestbuds_user_projection (app_id, social_id) WHERE social_id IS NOT NULL; This can start as a maintained table populated during login/profile updates. If a view is preferred at first, it still needs DISTINCT ON (p.id) or an equivalent app-scoped selection rule: CREATE VIEW public.bestbuds_users_v2 AS SELECT DISTINCT ON (p.id) p.id, m.id AS membership_id, m.app_id, m.status, ... FROM heimdall.principal p JOIN heimdall.membership m ON m.principal_id = p.id WHERE m.app_id = '38d1cee3-004d-441f-8f66-ad5060859af1'::uuid AND p.kind IN ('USER', 'AGENT', 'ACTOR') AND p.status = 'ACTIVE' AND m.status IN ('ACTIVE', 'INVITED') ORDER BY p.id, m.updated_at DESC NULLS LAST, m.created_at DESC NULLS LAST; The view version is only an intermediate step. The table version gives better control over indexes, update timing, legacy aliases, and profile shape. ## Replace Per-Request Legacy Matching Section ID: legacy-matching Replace Per-Request Legacy Matching resolveBestBudsDataUserId currently tries to identify the product data user by matching: uv.id = auth principal id; uv.social_id = auth social id; uv.data->>'email' = auth email; then tie-breaking by whether the candidate appears in friends, messages, and user profiles. That was reasonable as a one-time repair query. It is not a good per-request runtime query. The migration-safe replacement is an alias table: CREATE TABLE public.user_identity_alias ( app_id uuid NOT NULL, alias_kind text NOT NULL CHECK (alias_kind IN ('principal_id', 'provider_subject', 'email', 'legacy_social_id')), alias_value text NOT NULL, data_user_id uuid NOT NULL REFERENCES public.user_profiles(id) ON DELETE CASCADE, source text NOT NULL DEFAULT 'migration', created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (app_id, alias_kind, alias_value) ); CREATE INDEX user_identity_alias_user_idx ON public.user_identity_alias (data_user_id); Then the runtime lookup becomes deterministic: SELECT data_user_id::text FROM public.user_identity_alias WHERE app_id = $1 AND alias_kind = 'principal_id' AND alias_value = $2 LIMIT 1; During migration, insert aliases for principal id, provider subject, and email. After all product FKs point to canonical principal ids, the runtime resolver can collapse to a direct membership/profile check: SELECT p.id::text FROM heimdall.principal p JOIN heimdall.membership m ON m.principal_id = p.id JOIN public.user_profiles up ON up.id = p.id WHERE p.id = $1 AND m.app_id = $2 AND p.status = 'ACTIVE' AND m.status IN ('ACTIVE', 'INVITED') LIMIT 1; ## Rewrite Message Hot Paths Section ID: message-hot-paths Rewrite Message Hot Paths Message history is the most important read path. Keep this index: CREATE INDEX IF NOT EXISTS idx_messages_chat_created ON public.messages (chat_id, created_at DESC); Do not rely on the checked-in (chat_id, updated_at DESC) index for chat history. The application orders by created_at DESC. topMessages should not rank every message in every relevant chat. Use a bounded per-chat lateral read: WITH relevant_chats AS ( SELECT DISTINCT chat_id, type, entity_id, name, data FROM ( SELECT chat_id, 'direct' AS type, friend_id AS entity_id, name, data FROM public.friends_view WHERE user_id = $1 UNION ALL SELECT chat_id, 'group' AS type, id AS entity_id, name, data FROM public.groups_view WHERE user_id = $1 ) r ) SELECT m.id, m.chat_id, m.value, m.kind, m.sender_id, su.display_name AS sender_name, m.receiver_id, rc.type, rc.entity_id, rc.name AS entity_name, rc.data AS entity_data, m.created_at, m.updated_at FROM relevant_chats rc JOIN LATERAL ( SELECT * FROM public.messages m WHERE m.chat_id = rc.chat_id ORDER BY m.created_at DESC LIMIT 5 ) m ON TRUE JOIN public.bestbuds_user_projection su ON su.app_id = $2 AND su.data_user_id = m.sender_id ORDER BY m.created_at DESC; This shape is bounded by relevant_chats * 5, not by total messages in those chats. Also add this for campaign signals: CREATE INDEX IF NOT EXISTS idx_messages_chat_sender_created ON public.messages (chat_id, sender_id, created_at DESC); That index supports "joined but never messaged" and per-campaign activity checks without repeatedly walking messages by sender alone. ## Campaign and Group Compatibility Section ID: campaign-group-compat Campaign and Group Compatibility campaigns_view and group_view aggregate users through users_view. Once users_view is replaced, the aggregation should join the app-scoped projection or materialize membership summaries separately. Rules: Campaign discovery must have deterministic ordering. Campaign membership checks need both (campaign_id, user_id) and (user_id, campaign_id) access. remainingDays should not be a JSON expression in a hot scheduler query. Group/campaign response assembly should not multiply users because of memberships. Indexes: CREATE INDEX IF NOT EXISTS idx_campaign_users_user_campaign ON public.campaign_users (user_id, campaign_id); CREATE INDEX IF NOT EXISTS idx_group_users_user_group ON public.group_users (user_id, group_id); If active campaign scanning remains a recurring Worker job, add a generated or stored column instead of repeatedly casting JSON: ALTER TABLE public.campaigns ADD COLUMN IF NOT EXISTS remaining_days int; CREATE INDEX IF NOT EXISTS idx_campaigns_remaining_created ON public.campaigns (remaining_days, created_at DESC) WHERE chat_id IS NOT NULL; The Worker can still mirror the value into data for compatibility, but the query predicate should be typed. ## Refresh Rotation Must Be Atomic Section ID: refresh-rotation Refresh Rotation Must Be Atomic The current refresh flow checks used_at in Kotlin and then updates the row. Concurrent calls can both read the token as unused before either update commits. Live data already shows families with multiple usable tokens created milliseconds apart. Use a single atomic update: WITH claimed AS ( UPDATE heimdall.refresh_token SET used_at = now(), rotated_at = now(), updated_at = now() WHERE token_hash = $1 AND used_at IS NULL AND revoked_at IS NULL AND expires_at > now() RETURNING * ) SELECT * FROM claimed; If claimed returns no row, check whether the token exists and is already used. If it is already used, revoke the family: UPDATE heimdall.refresh_token SET revoked_at = now(), updated_at = now() WHERE family_id = $1 AND revoked_at IS NULL; Then insert the successor in the same transaction. This makes the presented token a database-claimed one-time credential rather than an application-level best effort. Add an invariant if the operational model allows it: CREATE UNIQUE INDEX IF NOT EXISTS uq_refresh_one_live_per_family ON heimdall.refresh_token (family_id) WHERE used_at IS NULL AND revoked_at IS NULL; If old sessions can legitimately keep multiple unused roots during migration, run a repair first and add the index only after the duplicates are removed. ## PAT Verification Write Amplification Section ID: pat-write-amplification PAT Verification Write Amplification TokenInteractor.verifyPersonalAccessToken updates last_used_at on every successful verification. That is correct for audit freshness, but it can turn a read-heavy authentication path into a write-heavy hot row. Use a coarse update window: UPDATE heimdall.personal_access_token SET last_used_at = now(), updated_at = now() WHERE token_hash = $1 AND (last_used_at IS NULL OR last_used_at < now() - interval '5 minutes'); For very high volume service tokens, write usage events to audit/telemetry and coalesce last_used_at asynchronously. ## FK and Index Backlog Section ID: fk-index-backlog FK and Index Backlog Add missing FK-side indexes before tables grow. The live audit found these important gaps: Table Missing index Why public.campaign_users (user_id) or (user_id, campaign_id) Current campaigns and discovery by user. public.event_users (user_id) User event lookups and cascades. public.message_reactions (user_id) User reaction lookup and profile deletion. public.user_installed_packs (pack_id) Pack deletion and reverse lookup. heimdall.principal_role (role_id) Role deletion and permission joins. heimdall.role_permissions (permission_id) Permission deletion and reverse lookup. heimdall.membership (tenant_id), (context_id) Tenant/context cleanup and scoped membership operations. heimdall.session (tenant_id), (context_id) Scoped session cleanup. heimdall.auth_audit_event (tenant_id), (context_id) Scoped audit search and FK maintenance. heimdall.personal_access_token (context_id) Context cleanup and scoped token audit. For invitation or email login resolution, also add: CREATE UNIQUE INDEX IF NOT EXISTS uq_identity_primary_email ON heimdall.identity (lower(primary_email)) WHERE primary_email IS NOT NULL; If duplicate emails exist, repair first, then add the unique index. ## Sticker Schema Drift Section ID: sticker-schema-drift Sticker Schema Drift The live/new dump sticker schema uses object-storage keys: sticker_packs.tray_icon_r2_key stickers.file_r2_key stickers.size_bytes Older source and current Worker code still use URL columns: sticker_packs.tray_icon_url stickers.file_url Do not paper over this with a broad view unless old deployed Workers still need it. Pick one of these paths: Update Worker code and DTO mapping to use R2 keys and generate public/signed URLs at the edge. Add temporary compatibility generated views for old callers, with explicit deprecation. The R2-key shape is the better long-term model because it avoids storing derived public URLs in Postgres and lets the media edge own URL policy. ## Grants and RLS Section ID: grants-rls Grants and RLS The current grants are too broad for a production Supabase database. The database should not rely on the fact that Workers normally use privileged connections. Hardening order: Revoke broad anon CRUD on public tables. Revoke anon read access to Heimdall base tables. Expose only narrow read views that are intentionally public. Enable RLS on public tables that can be reached by Supabase roles. Keep Worker/service-role access through explicit service credentials and server-side authorization, not end-user table grants. Add a schema audit check that fails if anon regains DML on product tables or SELECT on Heimdall secrets/session/token tables. Minimum check: SELECT table_schema, table_name, grantee, privilege_type FROM information_schema.table_privileges WHERE table_schema IN ('public', 'heimdall') AND grantee = 'anon' ORDER BY table_schema, table_name, privilege_type; ## Compatibility Migration Plan Section ID: migration-plan Compatibility Migration Plan Use a staged rollout. Do not replace every query and every schema object in one DDL window. ## Stage 0: freeze and audit Section ID: stage-0-freeze-and-audit Stage 0: freeze and audit Record live row counts and duplicate candidates. Dump schema and data. Capture all current grants. Verify public.user_profiles.id rows all exist as Heimdall principals. Identify active public FKs that still point at legacy ids. Identify callers that depend on users_view shape. ## Stage 1: canonical projection Section ID: stage-1-canonical-projection Stage 1: canonical projection Create bestbuds_user_projection. Backfill it from Heimdall membership plus user_profiles. Add one-row-per-principal and one-row-per-data-user constraints. Add email/social indexes. Keep users_view intact for old callers. ## Stage 2: alias table Section ID: stage-2-alias-table Stage 2: alias table Create user_identity_alias. Insert principal id aliases for all canonical users. Insert provider subject aliases where needed. Insert normalized email aliases only when email is verified and conflict-free. Rewrite resolveBestBudsDataUserId to use aliases first, then direct canonical id, with old OR query as a temporary fallback. ## Stage 3: hot query rewrites Section ID: stage-3-hot-query-rewrites Stage 3: hot query rewrites Rewrite topMessages to the lateral top-N shape. Change message sender/receiver joins to bestbuds_user_projection. Rewrite campaign/group aggregations to app-scoped projection. Add deterministic ordering to discovery queries. Keep the old views only for low-volume compatibility routes. ## Stage 4: transaction hardening Section ID: stage-4-transaction-hardening Stage 4: transaction hardening Make refresh rotation atomic. Repair duplicate usable refresh families. Add the refresh-token live-family invariant if safe. Coalesce PAT last_used_at. Wrap multi-statement pack creation in one transaction or one SQL CTE. ## Stage 5: source and live schema convergence Section ID: stage-5-source-and-live-schema-convergence Stage 5: source and live schema convergence Update checked-in schema.sql to match live message indexes. Update sticker schema/code to the R2-key model or add an explicit temporary compatibility view. Move all new auth/public compatibility DDL into canonical migration files. Add a repeatable read-only schema audit script that emits JSON and fails CI on drift. ## Stage 6: security hardening Section ID: stage-6-security-hardening Stage 6: security hardening Apply grant/RLS cleanup. Verify Workers still operate with service credentials. Verify public clients cannot read Heimdall token/session/PAT tables. Add an automated privilege regression check. ## Suggested Query Replacements Section ID: query-replacements Suggested Query Replacements Current query Problem Replacement resolveBestBudsDataUserId OR-matches through users_view Unbounded compatibility lookup, JSON email predicate, tie-breaker scans user_identity_alias lookup, then direct principal/profile check topMessages window ranks all messages in relevant chats O(total messages in chats), row inflation through users_view JOIN LATERAL top 5 per chat getMessages joins sender/reply/reactions through users_view Per-message compatibility view cost Join bestbuds_user_projection by (app_id, data_user_id) campaigns_view aggregates through users_view Duplicate users in JSON and CPU fanout Aggregate through app-scoped projection listActiveCampaignIds casts data->>'remainingDays' JSON expression scan Typed remaining_days column/index Sticker queries use URL columns Source/live drift Use R2 key columns or explicit compatibility view ## Operational Checks Section ID: operational-checks Operational Checks Run these before and after each migration stage. -- users_view fanout SELECT count(*) AS rows, count(DISTINCT id) AS distinct_ids, count(*) - count(DISTINCT id) AS duplicate_rows FROM public.users_view; -- duplicate active projection rows SELECT app_id, principal_id, count(*) FROM public.bestbuds_user_projection GROUP BY app_id, principal_id HAVING count(*) > 1; -- public profile without principal SELECT count(*) FROM public.user_profiles up LEFT JOIN heimdall.principal p ON p.id = up.id WHERE p.id IS NULL; -- messages pointing at missing users SELECT count(*) FILTER ( WHERE NOT EXISTS ( SELECT 1 FROM public.user_profiles up WHERE up.id = messages.sender_id ) ) AS orphan_sender, count(*) FILTER ( WHERE receiver_id IS NOT NULL AND NOT EXISTS ( SELECT 1 FROM public.user_profiles up WHERE up.id = messages.receiver_id ) ) AS orphan_receiver FROM public.messages; -- refresh-token family safety SELECT family_id, count(*) AS usable_tokens FROM heimdall.refresh_token WHERE used_at IS NULL AND revoked_at IS NULL AND expires_at > now() GROUP BY family_id HAVING count(*) > 1; Performance checks: EXPLAIN (ANALYZE, BUFFERS) SELECT ... Use BUFFERS and row counts, not just milliseconds. The live database is still small enough that low timings can hide bad asymptotic behavior. ## Success Criteria Section ID: success-criteria Success Criteria This migration is complete when: public.users_view is no longer used by hot messaging, social, campaign, or auth request paths. There is exactly one app-facing user projection row per BestBuds principal. Legacy id/social/email matching is served by indexed aliases or removed. topMessages scales with number_of_chats * top_n, not total chat history. Message history uses (chat_id, created_at DESC). Refresh rotation cannot mint two live successors for one presented token. PAT verification does not write on every request. Public and live sticker schema agree. Missing FK-side indexes are closed. anon has no broad access to Heimdall base tables and no broad DML on product tables. A read-only schema audit can be run before every deploy and produce the same invariants in JSON. ## Final Position Section ID: final-position Final Position Heimdall is a good canonical auth base. The old public schema can remain a product fact store. The unsafe part is the compatibility layer pretending to be a general user table while joining identity, membership, provider, profile, embedding, and legacy fields on every read. Make compatibility explicit and indexed. Move legacy matching into data. Make hot queries bounded. Enforce transaction invariants in SQL. Then the schema can scale without forcing every Worker request to rediscover the migration history. # Claude Critic Review URL: https://reaktor.build/docs/claude-critic-review Status: historical Content revision: 197dd5cc028837dc863fbb089de4840420218dbbae96347cda9d28c752e5fd5d Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/claude-critic-review","polarity":"Neutral"},{"id":"section-0-executive-summary","anchor":"0-executive-summary","label":"0Executive Summary","profile":"section","contract":"https://reaktor.build/docs/claude-critic-review#0-executive-summary","polarity":"Neutral"},{"id":"section-1-the-scope-problem","anchor":"1-the-scope-problem","label":"1The Scope Problem","profile":"section","contract":"https://reaktor.build/docs/claude-critic-review#1-the-scope-problem","polarity":"Neutral"},{"id":"section-2-the-timeline-contradiction","anchor":"2-the-timeline-contradiction","label":"2The Timeline Contradiction","profile":"section","contract":"https://reaktor.build/docs/claude-critic-review#2-the-timeline-contradiction","polarity":"Neutral"},{"id":"section-3-the-team-scope-mismatch","anchor":"3-the-team-scope-mismatch","label":"3The Team-Scope Mismatch","profile":"section","contract":"https://reaktor.build/docs/claude-critic-review#3-the-team-scope-mismatch","polarity":"Neutral"},{"id":"section-4-the-market-size-question","anchor":"4-the-market-size-question","label":"4The Market Size Question","profile":"section","contract":"https://reaktor.build/docs/claude-critic-review#4-the-market-size-question","polarity":"Neutral"},{"id":"section-5-the-competitive-claims-are-overstated","anchor":"5-the-competitive-claims-are-overstated","label":"5The Competitive Claims Are Overstated","profile":"section","contract":"https://reaktor.build/docs/claude-critic-review#5-the-competitive-claims-are-overstated","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/claude-critic-review#related-docs","polarity":"Neutral"}],"relations":[{"id":"claude-critic-review:references-codex-critic-review","kind":"references","owner":"claude-critic-review","incidences":[{"node":"claude-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"codex-critic-review","port":"page","role":"target","ordinal":0}]},{"id":"claude-critic-review:references-reaktor-competitive-analysis","kind":"references","owner":"claude-critic-review","incidences":[{"node":"claude-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-competitive-analysis","port":"page","role":"target","ordinal":0}]},{"id":"claude-critic-review:references-reaktor-workbench-roadmap","kind":"references","owner":"claude-critic-review","incidences":[{"node":"claude-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-workbench-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"claude-critic-review:references-reaktor-framework-overview","kind":"references","owner":"claude-critic-review","incidences":[{"node":"claude-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-framework-overview","port":"page","role":"target","ordinal":0}]},{"id":"claude-critic-review:references-reaktor-megascale-strategy","kind":"references","owner":"claude-critic-review","incidences":[{"node":"claude-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-megascale-strategy","port":"page","role":"target","ordinal":0}]},{"id":"claude-critic-review:references-graph-kernel-analysis","kind":"references","owner":"claude-critic-review","incidences":[{"node":"claude-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"graph-kernel-analysis","port":"page","role":"target","ordinal":0}]}]} ## Claude Critic Review Section ID: preamble Adversarial review of architecture, feasibility, competition, and go-to-market risk. ## 0Executive Summary Section ID: 0-executive-summary 0Executive Summary Reaktor is a genuinely ambitious vision: a graph-based IDE that unifies architecture visualization, runtime debugging, deployment, analytics, and AI code generation into a single tool for Kotlin Multiplatform apps. The technical intuition is sound — the "typed graph as source of truth" abstraction is powerful, and the existing graph/port/visitor infrastructure in the KMP codebase is real. But ambition without ruthless scoping is a death sentence for small teams. This review identifies 11 categories of risk that, taken together, make the current plan structurally unlikely to succeed on the stated timeline with the stated resources. :::info[Core Concern] Reaktor is attempting to build the equivalent of Xcode + Figma + Datadog + GitHub Actions + Cursor — simultaneously, with a 3-person team, in 60 weeks, on top of a framework that is itself still under active development. The probability of shipping all 6 phases as described is near zero. ::: This is not a dismissal. It's a calibration exercise. The question isn't whether Reaktor is a good idea — it is — but whether the plan is honest about what it will take. ## 1The Scope Problem Section ID: 1-the-scope-problem 1The Scope Problem ## What Reaktor promises to be Section ID: scope What Reaktor promises to be The documents describe Reaktor as a tool where "every person involved in building an app — developer, architect, PM, QA, DevOps, marketing, analyst — can see, understand, modify, deploy, and measure the entire application." This is compared to Unreal Engine's editor. Let's count the distinct product surfaces this implies: Surface Count IDE Screens 5 Type-Aware Inspectors 13 Drawer Tabs 7 Target Personas 6 Platform Targets 3 External Integrations 4 Each of these is a product in itself. The Graph screen alone — with pan/zoom, port-anchored edges, overlay filtering, hover tooltips, group nodes, and keyboard navigation — is a multi-month project for a dedicated team. The analytics dashboard competes with Datadog. The deploy view competes with Vercel. The AI agent competes with Cursor. :::info[Counterargument needed] Which 2-3 of these surfaces deliver 80% of the value? The plan treats all 5 screens as equally important. A credible plan would identify the wedge product and defer the rest. ::: ## The "everything connects to everything" trap Section ID: scope-2 The "everything connects to everything" trap Reaktor's architecture means you can't ship any surface in isolation. The Graph screen needs the graph model. The DevTools screen needs runtime tracing. The Deploy screen needs CI integration. The Insights screen needs telemetry. The AI agent needs the command schema. Each screen depends on 2-3 infrastructure layers that don't exist yet. This creates a "big bang" delivery problem: nothing is valuable until everything works together. That's the opposite of how successful developer tools are built. VS Code shipped as a text editor. Figma shipped as a design tool. Datadog shipped as a monitoring tool. They expanded from a working core. Reaktor's plan delivers the entire surface area simultaneously. ## 2The Timeline Contradiction Section ID: 2-the-timeline-contradiction 2The Timeline Contradiction The project has two timeline documents that contradict each other: DeliverableRoadmap (60 weeks)Plan (8 weeks)Graph screen (pan/zoom, edge routing, filters, tooltips)Phase 1-2: 16 weeks3 days13 type-aware inspectorsPhase 2: 8 weeks5 daysAI agent + MCP serverPhase 3: 8 weeks4 daysCI/CD + live telemetryPhase 4: 8 weeks3 daysCompose/JS web targetPhase 5: 12 weeks5 days :::info[Red Flag] The plan.html document estimates 8 weeks total for work that the roadmap.html document estimates at 60 weeks. One of these is wrong by a factor of 7.5x. If the plan estimates are what the team believes, they are severely underestimating the work. If the roadmap is what they believe, the plan is aspirational fiction. ::: For reference: JetBrains spent years building Fleet. Jetpack Compose took Google 4+ years from announcement to stable. Figma took 3 years to reach its first public release with a 10+ person team. None of these attempted the breadth Reaktor claims in 60 weeks. ## 3The Team-Scope Mismatch Section ID: 3-the-team-scope-mismatch 3The Team-Scope Mismatch The project has 3 contributors: PersonFocusAvailability for WorkbenchShibasis PatnaikArchitecture, graph, workbench, everythingSplit across framework + workbench + appKedarnathComposables, interactionsTactile design system focusManab MohantyPhysics, shadersTactile design system focus The workbench is effectively a single-person project. Shibasis is simultaneously: Maintaining the Reaktor KMP framework (24 modules, 144K lines) Building the BestBuds consumer app (the first customer of Reaktor) Designing and building the Reaktor Workbench Building the Tactile design system Creating the web prototype and documentation :::info[Critical Risk] A single person cannot build, test, document, and maintain a product with 5 major screens, 13 inspectors, a command palette, an AI agent, CI/CD integration, analytics, and a plugin system — while simultaneously maintaining the framework and building an app on top of it. This is a team-of-20 roadmap assigned to a team-of-1. ::: The AI-assisted development argument ("Claude/Gemini write most of the code") is tempting but misleading. AI tools can generate boilerplate and implement well-specified components. They cannot make architectural decisions, debug subtle cross-module interactions, write integration tests, handle production incidents, or maintain coherence across 24 modules. The bottleneck is not typing speed — it's decision bandwidth. ## 4The Market Size Question Section ID: 4-the-market-size-question 4The Market Size Question ## KMP is the initial target Section ID: market KMP is the initial target The roadmap targets the Kotlin Multiplatform ecosystem, estimated at ~100K developers by 2026. But Reaktor doesn't target all KMP developers — it targets KMP developers who: Use the Reaktor framework specifically (currently: 1 app) Want a visual graph-based IDE (a niche preference) Are willing to adopt an alpha-quality tool from a 3-person team Will pay $29-199/month for it The addressable market at launch is realistically in the single digits. The roadmap acknowledges this: Phase 1 success metric is "1 active developer" (the creator). Phase 2 targets "5-10 alpha testers." :::info[Market Risk] The path from "1 user" to "5,000 weekly active developers" (Phase 6 target) requires either (a) Reaktor becoming framework-agnostic, which invalidates the tight KMP integration that is its core differentiator, or (b) KMP adoption exploding and developers choosing Reaktor's graph model over conventional approaches. Neither is guaranteed. ::: ## The chicken-and-egg problem Section ID: market-2 The chicken-and-egg problem Reaktor (the framework) needs developers to adopt it. The Workbench needs Reaktor apps to visualize. The Workbench is the selling point for adopting Reaktor. But the Workbench doesn't work yet. And Reaktor (the framework) has one consumer app. This circular dependency means neither the framework nor the workbench can grow independently. You need both to be good simultaneously, which doubles the development burden on a team that's already overextended. ## 5The Competitive Claims Are Overstated Section ID: 5-the-competitive-claims-are-overstated 5The Competitive Claims Are Overstated ## The "only tool with every checkmark" claim Section ID: competition The "only tool with every checkmark" claim The competitive analysis presents a 14-capability matrix where Reaktor has a checkmark in every row. This is misleading because: Most checkmarks represent plans, not implementations. Deploy/CI dashboard? Doesn't exist. Analytics/telemetry? Doesn't exist. AI code generation? Doesn't exist. Command pattern? Design only. Cross-platform? The Compose/JS target is commented out. The capabilities are chosen to favor Reaktor. The matrix doesn't include: time-to-productivity, community size, documentation quality, third-party integrations, stability, or production readiness — all areas where competitors dominate. Competitors are evaluated on their current shipping product; Reaktor is evaluated on its roadmap. Comparing Cursor's shipping AI to Reaktor's planned AI is not an honest comparison. :::info[Credibility Risk] Claiming feature parity with tools backed by $100M+ in funding and 50-500 person teams — when those features exist only as static mockups — undermines credibility with the developer audience the project needs to attract. Developers are allergic to vaporware claims. ::: ## The "AI tools don't understand architecture" thesis Section ID: competition-2 The "AI tools don't understand architecture" thesis The central competitive argument is that AI coding tools (Claude Code, Cursor, Codex) work with text, not architecture, and that Reaktor's graph provides the missing semantic layer. This was a stronger argument 12 months ago. Today: Claude Code already reads project structure, dependency graphs, and test results as context Cursor indexes entire codebases and understands cross-file dependencies AI agents can already run builds, read stack traces, and navigate code structure MCP servers for IDEs, databases, and cloud services already exist without requiring a specialized graph model The gap Reaktor aims to fill is narrowing from the other direction. The question is whether the gap closes before Reaktor can fill it. ## 6Architectural Risks Section ID: 6-architectural-risks 6Architectural Risks ## The GraphManifest doesn't exist yet Section ID: architecture The GraphManifest doesn't exist yet The entire workbench depends on a KSP-generated GraphManifest.json that maps the app's architecture into a typed graph. This is described as the "Phase 1 foundation." The reaktor-graph-ksp module — the compiler plugin that generates this manifest — does not exist. This is not a small gap. KSP plugins that accurately extract architectural information from arbitrary Kotlin code are extremely hard to build. The plugin needs to: Identify all entity types (screens, services, actions, routes, stores, etc.) from annotations or conventions Resolve cross-module dependencies at compile time Track port connections (ConsumerPort/ProviderPort bindings) across the dependency graph Handle generics, type aliases, expect/actual declarations, and platform-specific code Generate a complete, correct graph that stays in sync as code changes :::info[Technical Risk] If the GraphManifest generator can't accurately capture the app's architecture, the entire workbench is built on a lie. Every screen, inspector, and AI interaction depends on the graph being correct. A graph that drifts from reality is worse than no graph — it actively misleads. ::: ## The port system is the core — and it's unvalidated Section ID: architecture-2 The port system is the core — and it's unvalidated The analysis document itself admits: "The entire ConsumerPort/ProviderPort system — the core of Reaktor — has no visual representation." Port pins in the prototype are "decorative." The graph connects node-to-node, not port-to-port. This means the most fundamental architectural decision — that applications are graphs of typed ports, not just boxes with arrows — has never been validated visually. The team doesn't yet know if port-level granularity helps users or overwhelms them. If it overwhelms them, the entire "typed graph" differentiator collapses into a standard dependency diagram that many tools already provide. ## Live runtime connection is hand-waved Section ID: architecture-3 Live runtime connection is hand-waved The roadmap describes live telemetry, runtime tracing, and real-time graph updates. But the prototype is 100% static data. The architecture for streaming runtime data from a KMP app into the workbench doesn't exist. This requires: An instrumentation layer in the running app A communication protocol (WebSocket? gRPC?) A state synchronization mechanism Performance isolation (the observer can't slow down the observed) Each of these is a multi-week project. Together they constitute an infrastructure layer as complex as the workbench itself. ## 7The Prototype Paradox Section ID: 7-the-prototype-paradox 7The Prototype Paradox ## Beautiful but dangerous Section ID: prototype Beautiful but dangerous The web prototype at reaktor.build is visually impressive: dark IDE aesthetic, resizable panels, sparkline charts, causal traces, heatmaps. It looks like a shipping product. This is a double-edged sword: It sets expectations the team can't meet. Anyone who sees the prototype expects the real product to look and feel this good. But the prototype is a React facade with hardcoded data. The real product will be Compose Desktop, which has worse text rendering, less mature animation APIs, and no CSS. Recreating this visual fidelity in Compose Desktop is a massive effort. It creates an illusion of progress. 6,100 lines of JSX is impressive output. But it's throwaway code — the documents explicitly say "don't try to preserve this codebase." The real progress toward a shipping product is measured in the KMP modules, where the picture is much thinner. The spec coverage is self-reported at 35%. Even as a specification document, 65% of the intended behavior is unspecified. The prototype defines the happy path for 5 screens but doesn't address error states, loading states, empty states, permission boundaries, or data pagination. :::info[Risk] Time spent polishing the prototype is time not spent on the foundation (GraphManifest, runtime bridge, command schema) that determines whether the product can exist at all. The prototype is a compelling demo, not a shipping asset. ::: ## 8The AI Integration Bet Section ID: 8-the-ai-integration-bet 8The AI Integration Bet ## MCP as moat — how defensible is it? Section ID: ai MCP as moat — how defensible is it? The competitive thesis positions Reaktor's MCP server as a unique "semantic layer" that makes AI tools architecturally aware. But MCP is an open protocol. Nothing prevents: JetBrains from building an MCP server that exposes IntelliJ's code model (they have a richer one) Android Studio from exposing Compose's component tree via MCP (Google has the resources) AI tools from building their own architectural understanding without MCP (they're already doing this) The MCP moat depends on Reaktor's graph model being significantly better than what IDE vendors can build. Given that JetBrains has spent 20+ years building code analysis for Kotlin, and Google controls the Compose compiler, this is a bold assumption. ## GraphCommand as AI interface Section ID: ai-2 GraphCommand as AI interface The idea that AI generates structured GraphCommand objects instead of raw code is elegant in theory. In practice: LLMs are trained on code, not on Reaktor's custom command schema. Fine-tuning or heavy prompting is required. If the command schema is too constrained, the AI can't express complex changes. If it's too permissive, you've reinvented "write code." The command system adds a translation layer between intent and code. Every translation layer introduces bugs, latency, and cognitive overhead. Developers who are comfortable with AI-generated code may not want the indirection of a command layer. :::info[Strategic Risk] The AI landscape moves faster than any single team can adapt. Features that seem differentiating today (architecture-aware AI, structured code generation) may be table stakes or obsolete in 12 months. Building a 60-week roadmap around AI capabilities that are moving targets is inherently fragile. ::: ## 9Business Model Concerns Section ID: 9-business-model-concerns 9Business Model Concerns ## Pricing assumes value that doesn't exist yet Section ID: business Pricing assumes value that doesn't exist yet TierPriceRequiresStatusWorkbench$29/moGraph + IDE bridge + 5 screensNot builtAI Features$79/mo/seatLLM pipeline + MCP + AgentNot builtEnterprise$199/mo/seatCollab + SSO + Plugins + Self-hostedNot built The revenue model depends on reaching Phase 4+ before generating meaningful income. At $29/month for 5-10 alpha testers (Phase 2), that's $145-290/month in revenue — roughly 0.1% of a single engineer's fully-loaded cost. The business is not self-sustaining until Phase 5-6 with hundreds of paying users. ## The open-source tension Section ID: business-2 The open-source tension The framework modules are open source; the workbench is commercial. But the workbench's value depends on the framework having a large user base. If the framework doesn't grow, there's nobody to sell the workbench to. If the framework does grow, contributors may build open-source alternatives to the workbench (the graph model is public). This is the classic open-core tension, and it's harder to navigate when the open-source layer has minimal adoption. ## 10Existential Risks Section ID: 10-existential-risks 10Existential Risks ## What if KMP doesn't win? Section ID: existential What if KMP doesn't win? Reaktor is deeply coupled to Kotlin Multiplatform. If KMP's adoption plateaus (it's still a fraction of Flutter's user base), Reaktor's addressable market stays small. The plugin architecture (Phase 6) promises framework-agnostic support, but by then the product needs to have been self-sustaining for 30+ weeks on KMP revenue alone. ## What if the graph model is wrong? Section ID: existential-2 What if the graph model is wrong? The entire product is built on the premise that a typed architecture graph is the right abstraction for application development. But most successful developer tools are not graph-based. IDEs are text-based. Design tools are canvas-based. CI tools are pipeline-based. The graph abstraction is popular in game engines (Unreal Blueprints) and workflow tools (n8n), but it's unproven for application architecture. If developers prefer reading code over reading graphs — and decades of evidence suggests they do — the entire product premise is invalid regardless of execution quality. ## What if one person gets sick? Section ID: existential-3 What if one person gets sick? With effectively one person building the workbench and framework, any interruption — illness, burnout, life events, a day job conflict — stops all progress. There's no redundancy, no institutional knowledge beyond one person's head, and no onboarding path for new contributors (the codebase spans 24 modules across 3 repositories with a custom build system). :::info[Bus Factor] Bus factor is 1. For a project with a 60-week roadmap and commercial ambitions, this is an existential risk that no amount of technical excellence can mitigate. ::: ## 11The Steel Man — What Could Go Right Section ID: 11-the-steel-man-and-mdash-what-could-go-right 11The Steel Man — What Could Go Right A devil's advocate review is only credible if it acknowledges the genuine strengths. Here's what Reaktor has going for it: :::info[Real Technical Foundation] The graph, port, and visitor abstractions in the KMP codebase are real, working code — not slides. 144K lines across 24 modules is substantial. The ReaktorComposeSemanticsInspector alone (2,300 lines) demonstrates deep Compose internals knowledge. This isn't vaporware from someone who can't code. ::: :::info[The Prototype Is Genuinely Good] The web prototype demonstrates exceptional taste. The visual design, information density, and interaction patterns are at or above the level of shipping developer tools. If execution matches the vision, the product could be compelling. ::: :::info[The Graph Insight Is Correct] AI tools do lack architectural understanding. A typed graph is a better abstraction for AI interactions than raw source code. The observation that AI needs a semantic layer is correct even if Reaktor's specific approach to providing it is uncertain. Someone will build this. Reaktor has a head start on the idea. ::: :::info[AI-Augmented Solo Development Is Real] The prototype itself is evidence. 6,100 lines of coherent, visually polished UI code generated rapidly through Claude + GPT collaboration. If this velocity applies to the KMP workbench, the timeline estimates are less absurd than they look. The question is whether AI-assisted development scales to systems programming as well as it scales to UI prototyping. ::: :::info[Timing Could Be Perfect] KMP is maturing. Compose Multiplatform is stabilizing. The AI-native developer tools market is nascent. If Reaktor ships a credible MVP in the next 6-12 months, it enters a market that's hungry for exactly this kind of tool, before the big players consolidate. ::: ## 12Risk Scorecard Section ID: 12-risk-scorecard 12Risk Scorecard Risk CategorySeverityLikelihoodMitigationScope exceeds capacityCriticalVery HighRuthless scoping to 1-2 screens for MVPTimeline contradiction (8w vs 60w)HighCertainPick one timeline and plan honestlyBus factor = 1CriticalMediumRecruit 1-2 contributors; document architectureGraphManifest generator doesn't existCriticalMediumBuild this first, before any UI workKMP market too smallHighMediumDesign graph model to be framework-portable from day 1AI moat is temporaryMediumMediumShip fast; first-mover advantage is real but decaysCompetitive claims damage credibilityMediumHighOnly claim what's shipped; label everything else as roadmapPrototype sets unachievable expectationsMediumMediumSet expectations that Compose Desktop will look differentBusiness model unsustainable pre-Phase 4MediumHighSeek grant funding or consulting revenue bridgeGraph abstraction rejected by developersHighMediumUser testing with 5+ external KMP developersPort-level granularity overwhelms usersMediumMediumDefault to node-level; ports as progressive disclosure ## Recommendations Section ID: recommendations Recommendations If the author were to ask "What should I do differently?", here are the highest-leverage changes: Ship GraphManifest first. Before any more UI work, build the KSP plugin that generates the graph from real code. This is the foundation everything depends on. If it can't be built, know that now. Cut the MVP to Graph + DevTools. Two screens, one inspector, no AI, no deploy, no insights. Prove that the graph visualization is valuable to at least 5 developers who aren't you. Stop claiming shipped features that are mockups. The competitive matrix should distinguish "shipped," "in progress," and "planned." Developer trust is earned through honesty, not feature count. Find 2-3 external KMP developers to test with. The biggest unknown is whether the graph abstraction resonates. Test this with real users before building 13 inspectors for a model nobody has validated. Reconcile the timelines. Pick one number and build a plan that's honest about it. A credible 6-month plan for a focused MVP is better than a 60-week plan for everything. Address the bus factor. Write an architecture guide. Record decision rationale. Make it possible for someone else to contribute. Devil's Advocate Review · Claude This review is adversarial by design. It highlights risks, not certainties. The strongest ideas survive the hardest scrutiny. ## Related docs Section ID: related-docs Related docs Codex Critic - Use before expanding scope or trusting a broad roadmap. Competitive Landscape - Use when clarifying Reaktor's graph-native differentiation, competitor pressure, and where to integrate instead of compete. Strategic Roadmap - Use for strategic framing and product sequencing. Framework Overview - Use to understand the full Reaktor model before diving into graph, visitors, modules, control plane, or subsystem docs. Mega-Scale Strategy - Use for enterprise-adoption strategy, the open-source vs commercial split, and sequencing the distributed-tier roadmap without diluting the single-threaded-actor core. Graph Kernel - Use to keep the core language small while modules add vocabulary. # Claude Dev Environment URL: https://reaktor.build/docs/claude-dev-environment Status: historical Content revision: 6f00143b079e3468ef25d09a0c22b7241dab57aebdfab334f3b862ff36d69dc5 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/claude-dev-environment","polarity":"Neutral"},{"id":"section-summary","anchor":"summary","label":"1. Executive summary","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#summary","polarity":"Neutral"},{"id":"section-current","anchor":"current","label":"2. Current state","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#current","polarity":"Neutral"},{"id":"section-why","anchor":"why","label":"3. Why a moving shadow","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#why","polarity":"Neutral"},{"id":"section-inspiration","anchor":"inspiration","label":"4. Prior art","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#inspiration","polarity":"Neutral"},{"id":"section-principles","anchor":"principles","label":"5. Principles","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#principles","polarity":"Neutral"},{"id":"section-surfaces","anchor":"surfaces","label":"6. Stateful surfaces to shadow","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#surfaces","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#related-docs","polarity":"Neutral"},{"id":"section-observability","anchor":"observability","label":"19. Observability","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#observability","polarity":"Neutral"},{"id":"section-references-3","anchor":"references-3","label":"Peer designs in this repo","profile":"section","contract":"https://reaktor.build/docs/claude-dev-environment#references-3","polarity":"Neutral"}],"relations":[{"id":"claude-dev-environment:references-shadow-dev-environment","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"shadow-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-operations","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"page","role":"source","ordinal":0},{"node":"operations","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-performance-observability","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-observability","role":"source","ordinal":0},{"node":"performance-observability","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-reaktor-notifications-design","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-references-3","role":"source","ordinal":0},{"node":"reaktor-notifications-design","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-deep-link-integration","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-references-3","role":"source","ordinal":0},{"node":"deep-link-integration","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-auth-analysis","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-references-3","role":"source","ordinal":0},{"node":"auth-analysis","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-security-plan","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-references-3","role":"source","ordinal":0},{"node":"security-plan","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-graph-kernel-analysis","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-references-3","role":"source","ordinal":0},{"node":"graph-kernel-analysis","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-reaktor_graph_visitors_design","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-references-3","role":"source","ordinal":0},{"node":"reaktor_graph_visitors_design","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-codex-dev-environment","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"codex-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-secrets-management","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"secrets-management","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-reaktor-devops","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-devops","port":"page","role":"target","ordinal":0}]},{"id":"claude-dev-environment:references-flexbuffer-improvement-plan","kind":"references","owner":"claude-dev-environment","incidences":[{"node":"claude-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"flexbuffer-improvement-plan","port":"page","role":"target","ordinal":0}]}]} ## Claude Dev Environment Section ID: preamble Historical proposal. The Reaktor Shadow textbook pages and Operations & Reliability supersede this draft. In particular, moving-base publication differs from pinned replay, store materialization is explicit, deterministic fidelity is qualified, production read-through is denied and pinned cases obey deletion policy. The original prose below is preserved for lineage. Dev runs against a continuously-refreshed shadow of production: the last 7 days of Supabase rows, Memgraph nodes, R2 objects, worker payloads, and JVM API traces — plus a hand-curated set of pinned crashes and anomalies that never expire. All testing, load testing, and exploratory debugging happens here. Built as a graph visitor (per Reaktor Spec §28) extended end-to-end across the actual data surfaces in BestBuds. Builds on — reaktor-shadow First consumer BestBuds dev cluster Window rolling 7-day + permanent pinned fixtures Drivers Keploy · k6 · Maestro Status Design Stateful surfaces — 7 (Postgres · Memgraph · R2 × 2 · Workers AI · Sheets · JVM) Cloudflare workers in scope — 10 Storage budget — ~50 GB at peak Refresh cadence — hourly capture · nightly trim PII handling — scrub at capture (not query) Side-effect safety — tenant prefix + outbox interceptor ## 1. Executive summary Section ID: summary 1. Executive summary "Dev" today means an empty database and a stubbed worker — production bugs lived in a state of the world the staging environment never produced. The shadow dev environment fixes this by making production state the default state of dev: the same Supabase tables, the same Memgraph subgraphs, the same R2 objects, the same chat-message shapes, all updated continuously and trimmed to a rolling 7-day window. Any captured trace can be replayed against your branch — like Keploy, but covering all six Reaktor transports (HTTP · LOCAL · PEER · PUBSUB · QUEUE · WORKFLOW), every database, and the full causal chain of downstream calls a request triggers. The architecture has three loops: Capture loop — a ShadowCaptureVisitor attaches to every ServiceNode, RepositoryNode, and WorkerBase in production. Every request/response pair, every DB write, every external call is encoded as a FlexBuffer envelope tagged with a capture.id and stored in R2 partitioned by hour. Logical replication mirrors Postgres into a shadow database. R2 reads through to production for cache misses. Refresh loop — nightly Worker trims captures older than 7 days, except for those marked pinned=true by either a human or the anomaly detector. Postgres shadow vacuums tombstoned rows; Memgraph snapshots roll forward. Replay loop — devs run shadow replay (CLI, also a Workbench button); the engine reconstructs the request context, deflects external API calls to deterministic stubs, executes against the branch, and diffs the response + causal chain against the captured baseline. Used in CI, load tests, and interactive debugging. :::note[spec alignment] Directly extends Reaktor Spec §28 (reaktor-shadow): "reaktor-shadow is itself a Visitor on the graph… captures the complete dependency graph of downstream calls triggered by this request… replaying one captured request replays the entire causal chain — not just the HTTP surface." This design takes that captures-as-visitor primitive and extends it from a per-request testing tool into a permanent dev environment that always reflects current production reality. ::: ## 2. Current state Section ID: current 2. Current state ## 2.1 What dev/test infrastructure exists today Section ID: current-2 2.1 What dev/test infrastructure exists today SurfaceTodayStatusDev PostgresNone — devs share staging Supabase or run an empty local Postgres.missingDev MemgraphNone — dev hits the same GCP CE Memgraph as staging.missingDev R2None — dev writes leak into the production IMAGES bucket.unsafeTraffic captureNone — only Kermit log lines via Loki (planned, not deployed).missingOutbox / idempotencyNot implemented — the spec calls for it but no reaktor_outbox or *_idempotency tables exist yet.missingNightly backupbestbudsArchiver (Worker, cron 0 3 * * *) dumps Postgres → R2 BACKUPS bucket.prototypeTest frameworkMaestro flows in bestbuds/maestro/; nothing beyond.prototypen8n workflows10 workflows for deploys, builds, k8s sync — none for shadow refresh.unrelatedKeploy / k6 / load testMentioned in spec §28.2; not wired.missing ## 2.2 The honest gap Section ID: current-3 2.2 The honest gap Today a dev with a branch has three options, all bad: (a) run nothing, write code blind; (b) wire their laptop to staging and hope they don't fat-finger a destructive query; (c) spin up an empty local Postgres + Memgraph + Workers and hand-craft fixtures that never resemble production. Option (c) is what most teams settle for, and it's why every "this worked in staging" bug exists. ## 3. Why a moving shadow Section ID: why 3. Why a moving shadow ## Bugs live in production shapes Section ID: bugs-live-in-production-shapes Bugs live in production shapes The user with 4,200 chat messages, the group with 87 members, the friend graph with a 6-hop cycle — these don't appear in fixtures. Reproducing requires the actual data; recent actual data, because schemas and content drift week to week. ## Load tests are useless without realistic mix Section ID: load-tests-are-useless-without-realistic-mix Load tests are useless without realistic mix k6 scripts that hit /api/feed at uniform 100 rps don't predict the production failure mode where one user with 12,000 friends makes a single read that joins 12,000 rows. Real traffic patterns are the input; synthetic load is the multiplier. ## Edge cases need permanence Section ID: edge-cases-need-permanence Edge cases need permanence A crash from January that took 6 hours to root-cause must be reproducible in October — not "if you can find the row in the backup." Pinned fixtures keep the weird ones forever. ## Side effects need a sandbox Section ID: side-effects-need-a-sandbox Side effects need a sandbox Devs experimenting can't be allowed to send real FCM notifications, write to the real Manna Google Sheet, or trigger Workers AI charges. Shadow stack means side effects are intercepted at the visitor. ## Privacy by construction Section ID: privacy-by-construction Privacy by construction PII scrubbed once at capture time beats scrubbing on every query. Shadow data is already safe to look at; devs don't need to remember to anonymise. ## Replay closes the regression loop Section ID: replay-closes-the-regression-loop Replay closes the regression loop Every captured request is a candidate test case. CI replays the last week of distinct traffic against the PR branch. If the response shape or P95 latency drifts, the PR is flagged — same model as Keploy, but covering all transports. ## 4. Prior art Section ID: inspiration 4. Prior art ToolWhat it does wellAdopted precedent · proposed extensionKeployeBPF/proxy capture of HTTP traffic; auto-generates regression tests; replay with assertion diffing.Take: the capture/replay/diff model. Add: capture at the Service layer (visitor) instead of HTTP, so all six transports are covered; capture downstream causal chain, not just request/response.GoReplayTCP-level traffic shadowing — splits live traffic to a shadow service for soak testing.Take: the "split live traffic" idea. Add: the shadow service doesn't have to handle real load — it can sample and persist for later replay.mirrordRuns a local process "inside" a remote pod's network/file/env namespaces.Take: the "your laptop is the cluster" feeling. Add: the design requires isolation — devs hit the shadow stack, not prod.Replay.io / rrDeterministic record/replay of an entire program execution, including non-determinism (syscalls, RNG, time).Take: "record once, debug forever" pinning of weird traces. Add: capture operates at the service layer, not the syscall layer — much coarser, but covers distributed systems.Stripe's Capture & ReplayInternal tool that records production webhook deliveries and replays them against dev for integration testing.Take: the dedup + replay-against-branch ergonomics. Add: covers more than webhooks — every async hop in the graph.Supabase branching / Neon branchingCheap database forks per branch via copy-on-write storage.Take: "DB per branch" for write isolation. Add: the shadow source is fresher than backup, and Memgraph + R2 also need branching. :::note[positioning] Shadow Dev Environment sits where Keploy and Neon-branch would sit if you composed them: capture/replay plus per-branch DB forks plus outbound side-effect stubbing. None of those products do all three; Reaktor's graph kernel makes it natural because the same visitor catches all three. ::: ## 5. Principles Section ID: principles 5. Principles ## 1 · Capture is a visitor, not a proxy Section ID: 1--capture-is-a-visitor-not-a-proxy 1 · Capture is a visitor, not a proxy Per spec §28.1: ShadowCaptureVisitor attaches at the graph layer. Every transport, every node, one mechanism. No sidecar, no service mesh, no eBPF. ## 2 · The shadow IS dev Section ID: 2--the-shadow-is-dev 2 · The shadow IS dev There is no separate "dev environment". The shadow stack is dev. Devs run their branch against shadow workers, shadow Postgres, shadow Memgraph, shadow R2. ## 3 · Moving by default, pinned by exception Section ID: 3--moving-by-default-pinned-by-exception 3 · Moving by default, pinned by exception The default is a 7-day rolling window — every captured trace older than that is trimmed. Exceptions (crashes, anomalies, hand-curated edge cases) are pinned and never expire. ## 4 · Side effects fail loudly in shadow Section ID: 4--side-effects-fail-loudly-in-shadow 4 · Side effects fail loudly in shadow Every external call (FCM, APNs, Workers AI, Google Sheets) hits a stub by default. Bypassing requires explicit --allow-real-effects + a confirmation prompt. ## 5 · PII scrubbed at capture Section ID: 5--pii-scrubbed-at-capture 5 · PII scrubbed at capture Names, emails, phone numbers, message bodies, location coordinates — replaced with deterministic fakes (same input → same fake) before anything hits R2. The shadow store contains no real PII. ## 6 · Replay must be deterministic Section ID: 6--replay-must-be-deterministic 6 · Replay must be deterministic Time, RNG, IDs, external calls — all read from the captured envelope, not the system. A replay that gives a different answer means the code changed, not the environment. ## 7 · One refresh job per surface Section ID: 7--one-refresh-job-per-surface 7 · One refresh job per surface Each stateful surface has its own refresh worker — Postgres has a logical-replication subscriber, Memgraph has a nightly snapshot importer, R2 has an event-driven mirror. Failures are isolated; one stuck refresh doesn't poison the rest. ## 8 · Tenant prefix everywhere Section ID: 8--tenant-prefix-everywhere 8 · Tenant prefix everywhere Shadow tenants live as shadow_$tenant — IDs prefixed, indexes prefixed, R2 keys prefixed. Prod queries with the wrong prefix hit nothing; shadow queries can't accidentally hit prod. ## 6. Stateful surfaces to shadow Section ID: surfaces 6. Stateful surfaces to shadow From a fresh audit of bestbuds/targets/*Server, cloud/, and the JVM reaktorServer: SurfaceBinding(s)Shadow strategyRefresh ratePostgres (Supabase)supabase · supabasedirect (Hyperdrive)Logical replication slot → shadow DB; 7-day TTL on row shadow_inserted_at; vacuum nightly.continuous (≤5 s lag)CockroachDBcockroach · cockroachdirectSame approach (CDC feed → shadow cluster).continuousMemgraph (GCP CE)JVM memgraphDriver()Daily Cypher DUMP DATABASE snapshot → R2; shadow Memgraph imports on schedule. Plus a delta capture of write Cyphers from the visitor for incremental replay.nightly snapshot + delta capture continuousR2 IMAGESIMAGES bucket (10 worker readers, mediaServer writes)Read-through proxy in front of shadow_IMAGES. On read miss, fetch from prod, store in shadow. Captured writes go only to shadow.on-demand (read-through) + bulk seedR2 BACKUPSBACKUPS (archiver-only)Not shadowed — already a backup of prod; shadow can read it for cold restore.n/aCloudflare Workers AIAI binding (botServer)Capture every textGeneration request + response; replay returns cached response keyed by SHA-256(prompt + model + params). Falls back to live Workers AI only with explicit flag.per-call cacheGoogle Sheetscredentials.json in reaktorServerCaptured write payloads go to a shadow spreadsheet in a sandbox Google account, never the prod Manna sheet.per-call deflectionService bindingsAPP_SERVICE in 4 workersRouted to shadow worker instances, never prod.per-callJVM reaktorServer APIREST + GraphQL on /apps/*, /graphqlCaptured by ShadowCaptureVisitor (this is the visitor's natural attach point on JVM).per-requestFCM / APNs(planned per notifications doc)Captured → null-sink in shadow; never delivered. Replay produces the same captured "would have sent" record.per-call :::warning[key insight] Every Cloudflare worker (analyticsServer, chatServer, stickerServer, configServer, mediaServer, notificationServer, socialServer, messagingServer, botServer) shares the same Hyperdrive bindings + R2 bucket. Shadowing one set of bindings feeds all 9 workers. The shadow surface area is far smaller than the worker count suggests. ::: ## 7. Side-effect classification Section ID: sideeffects 7. Side-effect classification Replay correctness hinges on knowing which calls are safe to re-execute (idempotent reads, deterministic computations) vs which would produce duplicate real-world effects. Three categories, each with a default behaviour: CategoryExamplesDefault in shadowOverridePure / idempotent readsPostgres SELECT, Memgraph MATCH, R2 GET, public HTTP GET with cache headersExecute against shadow storenone neededIdempotent writesUPSERT by primary key, R2 PUT (key-addressed)Execute against shadow storenone neededNon-idempotent writesSQL INSERT without dedup key, bus publish without outbox, FCM/APNs send, Google Sheets append, Workers AI inference, payment, emailIntercepted — return captured response from envelope--allow-real-effects + per-call confirmation The visitor classifies on capture using two signals: HttpMethod for HTTP (GET/HEAD/OPTIONS → idempotent), and explicit @SideEffect(idempotent = true|false) annotations on Reaktor service handlers. Handlers without an annotation default to non-idempotent (safe default — better to over-stub than over-fire). ## 8. Stack diagram Section ID: arch 8. Stack diagram ┌────────────────────────── PRODUCTION ────────────────────────────────┐ │ user request │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ Cloudflare Worker / JVM Service │ │ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ │ │ ServiceNode │ │ │ │ │ │ ├─ ShadowCaptureVisitor.intercept(req) │ │ │ │ │ │ │ ↓ writes envelope → R2 captures bucket │ │ │ │ │ │ ├─ RepositoryNode → Postgres (logical replication) │─┼──┐ │ │ │ ├─ GraphNode → Memgraph (CDC + nightly dump) │ │ │ │ │ │ └─ ActorNode → bus publish (outbox) │ │ │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────│────────────────────────────────────┘ │ replication / capture ▼ ┌────────────────────────── SHADOW STACK ──────────────────────────────────┐ │ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │ │ │ shadow Postgres │ │ shadow Memgraph │ │ shadow R2 │ │ │ │ logical replica │ │ snapshot + delta │ │ read-through │ │ │ │ 7d window + pinned │ │ rebuilt nightly │ │ + write capture │ │ │ └──────────────────────┘ └──────────────────────┘ └──────────────────┘ │ │ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │ │ │ captures bucket │ │ stubs registry │ │ pin index │ │ │ │ FlexBuffer envelopes │ │ AI / Sheets / FCM │ │ DB-backed list │ │ │ │ partitioned by hour │ │ replay responses │ │ of permanent IDs │ │ │ └──────────────────────┘ └──────────────────────┘ └──────────────────┘ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Shadow workers (mirror of prod fleet) │ │ │ │ analyticsServer · chatServer · stickerServer · configServer · │ │ │ │ mediaServer · notificationServer · socialServer · messagingServer · │ │ │ │ botServer — all with shadow bindings │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ dev branch / CI replay │ │ ┌───────────────────┴──────────────────────────────────────────────────┐ │ │ │ ShadowReplay engine · CLI · CI job · Workbench panel │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────┘ ▲ │ nightly trim · anomaly auto-pin ┌───────────────────────────┐ │ ShadowRefresh Worker │ │ cron: 0 4 * * * UTC │ └───────────────────────────┘ ## 9. Capture path Section ID: capture 9. Capture path ## 9.1 The visitor Section ID: capture-2 9.1 The visitor class ShadowCaptureVisitor( private val sink: CaptureSink, private val scrubber: PiiScrubber, private val sampler: CaptureSampler, ) : Visitor() { override fun visitServiceNode(node: ServiceNode): ExitScope { node.intercept(object : ServiceInterceptor { override suspend fun intercept(req: Request, chain: ServiceChain): Response { if (!sampler.shouldCapture(req)) return chain.proceed(req) val captureId = Uuid.v7().toString() val downstream = mutableListOf() // Push a CaptureContext into the coroutine context so that child // service / DB / actor calls all append to `downstream`. return withCaptureContext(CaptureContext(captureId, downstream)) { val startedAt = Clock.System.now() val response = try { chain.proceed(req) } catch (t: Throwable) { sink.captureError(captureId, t); throw t } val finishedAt = Clock.System.now() sink.write(CaptureEnvelope( id = captureId, tenantId = req.tenantId, transport = req.transport, request = scrubber.scrub(req), response = scrubber.scrub(response), downstream = downstream.toList(), startedAt = startedAt, durationMs = (finishedAt - startedAt).inWholeMilliseconds, handlerNode = node.id, )) response } } }) return NoOpExit } override fun visitRepositoryNode(node: RepositoryNode): ExitScope { /* append to downstream */ } override fun visitActorNode(node: ActorNode): ExitScope { /* append to downstream */ } } ## 9.2 What an envelope contains Section ID: capture-3 9.2 What an envelope contains { "id": "01HXKQF8M7...", // UUID v7 (time-sortable) "tenantId": "shadow_bestbuds", "transport": "HTTP", // HTTP | LOCAL | PEER | PUBSUB | QUEUE | WORKFLOW "handlerNode": "ChatService.sendMessage", "request": { "method": "POST", "path": "/chats/{id}/message", "params": { "id": "chat_42" }, "headers": { "x-user": "user_b3ad...", "x-trace": "..." }, "body": "" // scrubbed }, "response": { "status": 201, "body": "" }, "downstream": [ { "kind": "sql.query", "target": "supabase", "durationMs": 8, "rows": 1 }, { "kind": "r2.put", "target": "IMAGES", "durationMs": 42, "bytes": 81920 }, { "kind": "bus.publish", "target": "chat.message.sent", "durationMs": 2 }, { "kind": "ai.generation", "target": "@cf/meta/llama-3", "durationMs": 340, "tokensIn": 120 } ], "startedAt": "2026-05-27T18:42:19Z", "durationMs": 412, "tags": { "client": "android-1.4.2", "build.sha": "a3c...", "anomaly": null }, "pinned": false } ## 9.3 Sampling Section ID: capture-4 9.3 Sampling Default sample rate: 5% of normal traffic. Sufficient to cover the long tail without overflowing R2. 100% on error: any request with response.status >= 500 or an uncaught exception is captured regardless of sample. 100% on slow: any request whose durationMs exceeds the p99 budget for its endpoint. Cohort burst: 100% for users tagged debug.session_id by the dev tools panel — for "trace this user end-to-end" debugging. Selector knob: per-endpoint rate overrides in shadow-config.toml so high-value endpoints (auth, payments when added) can be captured at 100%. ## 10. Shadow stores per surface Section ID: stores 10. Shadow stores per surface ## 10.1 Postgres / Supabase / Cockroach Section ID: stores-2 10.1 Postgres / Supabase / Cockroach Mechanism: logical replication. Supabase exposes WAL via the wal2json output plugin. A long-running Worker (or a JVM service in shadow) subscribes to a replication slot named shadow_replica and applies changes to shadow_db on a separate cluster. 7-day TTL: every row gets a shadow_inserted_at TIMESTAMPTZ DEFAULT now() column added in the shadow schema (no change to prod schema). Nightly DELETE FROM ... WHERE shadow_inserted_at < now() - interval '7 days' AND id NOT IN (SELECT id FROM shadow_pinned). Vacuum follows. Pinned table: shadow_pinned (table_name, row_id, pinned_at, pinned_by, reason). Anomaly detector + manual curator both insert here. Per-branch fork: if Neon/Supabase branching is enabled, each dev branch gets a copy-on-write fork of the shadow DB at branch creation. Writes during dev stay in the fork; the underlying shadow continues to refresh from prod. Tenant prefix: shadow records get tenant_id = 'shadow_' || original_tenant_id rewritten on replication. ## 10.2 Memgraph Section ID: stores-3 10.2 Memgraph Mechanism: Memgraph supports DUMP DATABASE for snapshots and triggers for change capture. Hybrid: Nightly snapshot: shadow-refresh Worker shells into the prod Memgraph, runs DUMP DATABASE to a Cypherl file, uploads to R2, then a shadow Memgraph instance imports it. Delta capture: the ShadowCaptureVisitor also captures Cypher writes (CREATE/MERGE/DELETE) on every request. Between snapshots, deltas can be replayed to bring shadow forward, or to replay one specific write sequence in isolation. Tenant scoping: every shadow query is automatically rewritten to add WHERE n.tenant_id STARTS WITH 'shadow_' — protects against accidentally querying prod data. ## 10.3 R2 IMAGES Section ID: stores-4 10.3 R2 IMAGES Mechanism: read-through caching with copy-on-write writes. class ShadowR2Binding( private val shadow: R2Bucket, // shadow_IMAGES private val production: R2Bucket, // IMAGES (read-only) ) : R2Bucket { override suspend fun get(key: String): R2Object? { shadow.get(key)?.let { return it } val upstream = production.get(key) ?: return null shadow.put(key, upstream.body, metadata = mapOf("shadow.cached" to "true")) return upstream } override suspend fun put(key: String, body: ByteArray) = shadow.put(key, body) } ## 10.4 Workers AI Section ID: stores-5 10.4 Workers AI Captures every textGeneration call's input/output. Replay returns the cached response keyed by SHA-256(prompt + model + temperature + maxTokens). Identical inputs always produce the captured output; novel inputs (in dev where prompts change) either fail fast (--strict) or fall through to live Workers AI (--allow-novel). ## 10.5 Google Sheets / Firebase / FCM / APNs Section ID: stores-6 10.5 Google Sheets / Firebase / FCM / APNs Stubbed by default. Captured request payloads are logged to a side store so devs can inspect "what would have been sent" without anything actually leaving the shadow cluster. A single shadow Manna sheet in a sandbox Google account can be enabled per-tenant for integration tests that need a real write. ## 11. The 7-day window + pinned fixtures Section ID: window 11. The 7-day window + pinned fixtures ## 11.1 Two-tier retention Section ID: window-2 11.1 Two-tier retention ROLLING WINDOW PINNED FIXTURES ────────────────────── ───────────────────── moves with wall clock permanent ~7 days deep no TTL ~50 GB at peak grows slowly auto-trimmed nightly human + AI curated ┌─────────────────────────┐ ┌──────────────────────────┐ │ captures from last 7d │ ─ promote ▶│ pinned (5,000 + entries) │ │ - 5% sample of normal │ on anomaly │ - "the OOM from Jan" │ │ - 100% on error/slow │ / manual │ - "12k-friend user" │ │ - 100% for debug.uid │ pin │ - "race in chat init" │ └─────────────────────────┘ └──────────────────────────┘ │ ▼ trim job: 0 4 * * * ## 11.2 Pin reasons (canonical list) Section ID: window-3 11.2 Pin reasons (canonical list) ReasonWho pinsWhy permanentcrashauto — any 5xx + stack trace pattern not seen in last 7dBug class proven real; must remain reproducible.slow_outlierauto — request that exceeded p99.9 of its endpointLoad-test corpus for "what makes this endpoint slow."schema_edgeauto — request body that hit a rare combination of optional fieldsTest coverage for combinations CI fixtures never produce.cohort_extremeauto — top-1% input size (largest payload, deepest graph, most friends)Performance ceiling testing.incident_reprohuman — engineer pins during incident retroPermanent regression test for "the X bug."release_baselineauto — one capture per endpoint snapshotted at each tagged release"Did this PR change behaviour vs the v1.4 baseline?"customer_reporthuman — support engineer pins when a user complaint comes inReproducer attached to the support ticket. ## 11.3 Storage maths Section ID: window-4 11.3 Storage maths Average envelope ~4 KB (compressed FlexBuffer). At 50 rps production traffic × 5% sample = 2.5 captures/sec = 216,000/day = 6.5M/week. At 4 KB each that's ~26 GB for the rolling window. Pinned set assumed to grow to ~50,000 entries over 12 months = ~200 MB. Postgres shadow data depends on retention; a 7-day cut of BestBuds today is ~12 GB. Total shadow R2 + Postgres footprint at maturity: under 50 GB — fits comfortably in a single Hyperdrive-backed Postgres + R2 free tier. ## 12. Replay engine Section ID: replay 12. Replay engine ## 12.1 CLI ergonomics Section ID: replay-2 12.1 CLI ergonomics # replay one capture against the local dev worker shadow replay 01HXKQF8M7XYZ # single capture by ID # replay last hour of /api/feed against branch shadow replay --endpoint /api/feed --since 1h --against http://localhost:8787 # replay every pinned crash against my branch (regression suite) shadow replay --pinned --reason crash --against http://localhost:8787 # load-test: replay last 24h at 5x speed shadow replay --since 24h --speedup 5 --against http://staging-shadow # diff replay output against captured baseline shadow replay --since 1h --diff --against http://localhost:8787 # → reports: 2 response body diffs, 1 status diff, 1 P95 regression ## 12.2 What gets replayed Section ID: replay-3 12.2 What gets replayed Replay isn't just "re-execute the request" — it reconstructs the captured causal chain: Set Clock, Random, Uuid to deterministic streams seeded from captureId. Wrap every external binding (R2, Workers AI, Sheets, FCM) so that calls matching the captured downstream return the captured response. Issue the captured request with all original headers preserved (except x-trace, which gets a fresh one tagged shadow.replay-of=). Compare the new response + downstream chain to the captured baseline. Report diffs structurally: status mismatch, header diff, body diff (with FlexBuffer-aware path-level reporting), missing downstream call, extra downstream call, latency regression. ## 12.3 Three replay modes Section ID: replay-4 12.3 Three replay modes ## strict Section ID: strict strict Response must match the captured baseline byte-for-byte (after FlexBuffer canonicalisation). Used in CI for regression detection. ## tolerant Section ID: tolerant tolerant Schema match + value equivalence (numbers within ε, timestamps modulo replay clock, IDs allowed to differ if downstream-consistent). Used during refactors. ## exploratory Section ID: exploratory exploratory Diff reported but never fails. Used for "I'm trying something new, just show me what changed." Most-used mode interactively. ## 13. Stubbing dangerous side effects Section ID: stubs 13. Stubbing dangerous side effects The replay engine consults a StubRegistry before any external call leaves the shadow: object StubRegistry { private val stubs = mapOf( CallKind.AI_TEXT_GENERATION to CachedByPrompt, CallKind.SHEETS_APPEND to NullSink(captureFor = "sheets-writes.jsonl"), CallKind.FCM_SEND to NullSink(captureFor = "fcm-sends.jsonl"), CallKind.APNS_SEND to NullSink(captureFor = "apns-sends.jsonl"), CallKind.SUPABASE_AUTH_LINK to DeterministicSuccess, CallKind.WEBHOOK_OUTBOUND to NullSink(captureFor = "webhooks-out.jsonl"), ) fun strategyFor(call: CallKind): StubStrategy = stubs[call] ?: if (call.isIdempotent) PassThrough else FailWithGuidance(call) } FailWithGuidance throws an exception with a message like "Call to POST https://api.stripe.com/charges blocked in shadow mode. Add a stub via StubRegistry.register(CallKind.STRIPE_CHARGE, …) or replay with --allow-real-effects." — surfaces the dangerous call instead of silently letting it through. :::danger[never silently fall through] The only path that lets a real side effect leave the shadow cluster is an explicit --allow-real-effects flag combined with a per-call confirmation. This is a deliberate design constraint: silent fall-through is how dev environments end up sending real notifications to real users in the middle of the night. ::: ## 14. Anomaly detection & auto-pinning Section ID: anomaly 14. Anomaly detection & auto-pinning A scheduled Worker runs every 15 min over the rolling capture stream and pins anything that looks unusual: Stack-trace clustering — captured 5xx errors with stack traces are hashed (top 10 frames, normalised). A new cluster (or a cluster that hasn't appeared in 30 days) auto-pins one exemplar. Latency outliers — per-endpoint p99.9 over a 24h window; any capture exceeding it gets pinned with reason slow_outlier. Payload extremes — for each endpoint, track the 99th percentile of payload size. Captures above pin with reason cohort_extreme. Schema-edge detection — track which combinations of optional fields appear in request bodies. A combination not seen in the last 30 days auto-pins. Causal-chain depth — captures whose downstream.length is above p99 (deep graph fan-out) pin. Pin budget: anomaly detector pins at most 50 captures per day per category, to keep the pinned set from ballooning. Excess go into a candidate queue for human curation in the Workbench. ## 15. Privacy & PII scrubbing Section ID: privacy 15. Privacy & PII scrubbing Scrubbing happens once at capture time, before anything is written to R2 or shadow Postgres. The shadow store contains no real PII; devs cannot accidentally see it. Field typeDetectionReplacementName (display, full)Schema annotation @Pii(.Name) + heuristicsDeterministic faker: same input always → same fake name. Preserves uniqueness for join testing.EmailRegex + schemashadow_$hash@example.testPhoneRegex + schema+1-555-$hash6Message bodySchemalorem_ipsum_of_length(original.length)Coordinates (PostGIS)SchemaSnap to ~1 km grid + add ±500 m jitterPhotos in R2R2 metadata + content-typeReplace with same-size placeholder PNGOAuth tokens, JWTsDetected by prefix (eyJ…, ghp_…)Token revoked + replaced with shadow_-prefixed forgery Deterministic-faker key: a per-tenant secret HMAC key, scoped only to the capture-time scrubber. Same key for the life of the shadow cluster — so the same user is always "Alice Wonderland" in shadow, every replay. Devs can join across tables. ## 15.1 Auditing Section ID: privacy-2 15.1 Auditing Every capture's scrubManifest records which fields were scrubbed and by which rule. A nightly compliance job samples 100 random captures, decrypts the manifest, and verifies that no raw PII slipped through (e.g. a free-form text field that wasn't annotated). Failures alert the data-team channel. ## 16. Tenant isolation Section ID: tenant 16. Tenant isolation Three layers of "you can't accidentally hit prod": ID prefix — all shadow tenant IDs, user IDs, room IDs are rewritten shadow_. Prod has no such IDs; any query with the prefix returns empty against prod, any query without returns empty against shadow. Bucket / database prefix — separate R2 bucket (shadow_IMAGES), separate Postgres database (shadow_db), separate Memgraph (shadow-memgraph on a sandbox GCP project). Credential isolation — shadow credentials are scoped at the Cloudflare account + GCP project level. The prod service account literally cannot reach shadow infrastructure and vice versa. ## 17. Time travel Section ID: timetravel 17. Time travel Every capture envelope carries startedAt. Replay can pin to any historical moment within the retention window: shadow replay --as-of 2026-05-20T14:30:00Z --endpoint /api/feed --since 1h The engine restores the shadow Postgres + Memgraph to that timestamp via SELECT * FROM ... AT TIMESTAMP (CockroachDB native), or via Postgres logical replay rewind, then runs the requested captures. For points outside the 7-day window, the cold restore from the nightly bestbudsArchiver backup is used (slower, ~10 minutes to materialise). ## 18. Load testing from real patterns Section ID: load 18. Load testing from real patterns The capture corpus is also a load-test corpus. Per spec §28.2: shadow load --since 7d --speedup 10x --target http://staging-shadow --duration 30m # Internally: # 1. Sample captures from last 7d, weighted by endpoint frequency in prod. # 2. Replay them at 10x the original arrival cadence. # 3. k6 collects per-endpoint latency histograms, errors, throughput. # 4. Export to Mimir; Grafana panels render against the performance-observability # pipeline (https://reaktor.build/docs/performance-observability). Pattern fidelity: traffic is replayed with the same inter-arrival distribution as production — bursts, idle periods, diurnal cycles — not as a uniform RPS stream. This catches issues that uniform load tests miss (queue depth spikes, cache stampedes). ## 19. Observability Section ID: observability 19. Observability Every capture and replay emits OTel spans into the same Grafana LGTM pipeline described in performance-observability §17. Two service names: service.name = "shadow-capture" — the visitor itself. Tells you capture overhead, sample drops, scrubber failures. service.name = "shadow-replay" — every replay run. Tells you replay duration, diffs detected, false-positive rate. The Workbench gets a Shadow tab showing: captures/sec live, pinned set size, oldest unpinned capture, today's replay diff count, anomaly auto-pin rate. ## 20. Workbench & CLI Section ID: workbench 20. Workbench & CLI ## 20.1 Workbench panel Section ID: workbench-2 20.1 Workbench panel A dedicated Shadow panel in the Reaktor Desktop workbench (lives alongside the existing Blueprint editor): Capture stream — live tail of incoming captures, filter by endpoint / tenant / status. Click → inspect envelope. Pinned fixtures — browsable, searchable, pinnable/unpinnable. Each entry shows: pin reason, age, last replayed, recent diff count. Replay against branch — pick any capture, hit "Replay against my branch" → opens a diff view (response, downstream, latency). Anomaly candidates — the queue the auto-pinner couldn't keep up with; human-curator approves or dismisses. Refresh status — when did Postgres replication last lag? When did Memgraph last snapshot? When did the trim job last run? ## 20.2 CLI verbs Section ID: workbench-3 20.2 CLI verbs VerbWhat it doesshadow capture --pause / --resumeToggle the production visitor (e.g. before a sensitive release).shadow inspect Pretty-print one capture envelope (request, response, downstream chain, tags).shadow replay …(See §12.)shadow pin --reason customer_report --note "ticket #42"Manually pin.shadow load …(See §18.)shadow diff Compare two captures (useful during refactors: did v2 produce the same chain as v1?).shadow restore --as-of Restore the shadow stack to a historical moment.shadow seed Apply a curated seed (e.g. "100 users with synthetic friend graphs of depth 6"). ## 21. CI integration Section ID: ci 21. CI integration Three CI jobs per PR, all running against the shadow stack: CI · job 1~2 min ## Replay pinned regression suite Section ID: replay-pinned-regression-suite Replay pinned regression suite shadow replay --pinned --strict --against $PR_BRANCH. Every pinned crash and incident-repro fixture must still produce the captured response. Failure blocks merge. CI · job 2~3 min ## Replay yesterday's traffic sample Section ID: replay-yesterdays-traffic-sample Replay yesterday's traffic sample shadow replay --since 24h --sample 1% --tolerant. A random 1% of the last day's captures replayed in tolerant mode. Catches behavioural drift that pinned fixtures don't cover yet. CI · job 3~10 min (nightly) ## Load test from last week's patterns Section ID: load-test-from-last-weeks-patterns Load test from last week's patterns shadow load --since 7d --speedup 5x --duration 8m. Runs nightly on main, not per-PR. Latency histograms feed the perf dashboard; regressions vs the previous nightly create a ticket. ## 22. BestBuds wiring Section ID: bestbuds 22. BestBuds wiring WhereChangebestbuds/cloud/k3s/shadow/New: Helm chart for shadow Postgres, shadow Memgraph, shadow worker fleet, OTel collector. Sits next to the existing observability stack.bestbuds/cloud/cloudflare/shadow/New: Wrangler configs for shadow-$worker mirroring each of the 10 production workers, plus the shadow_IMAGES R2 bucket and the captures R2 bucket.bestbuds/modules/app/src/jvmMain/.../ShadowCaptureFilter.ktNew: Spring filter that installs ShadowCaptureVisitor on the JVM reaktorServer when the SHADOW_CAPTURE_ENABLED=true env is set in prod.bestbuds/modules/app/src/jsMain/.../ShadowCaptureMiddleware.ktNew: Worker middleware that wraps every Hono route on every worker. Same envelope schema, same R2 sink.bestbuds/.github/workflows/shadow-replay.ymlNew: 3 CI jobs above.bestbuds/tools/shadow/New: the shadow CLI (Kotlin/JVM binary, distributed via Homebrew tap).bestbuds/targets/reaktorWeb/public/docs/This doc lands here.bestbuds/cloud/cloudflare/wrangler.json (root)Add a new Hyperdrive binding shadow_supabase pointing at the shadow Postgres. Workers detect env.SHADOW_MODE and pick the binding accordingly. ## 22.1 First slice: chatServer Section ID: bestbuds-2 22.1 First slice: chatServer Start with one worker — chatServer — because it has the richest traffic and an obvious high-value debug surface. Validate the capture path on one worker before fanning out to the other nine. ## 23. Phased plan Section ID: plan 23. Phased plan Phase 0~3 days ## Spec the envelope & pin schema Section ID: spec-the-envelope--pin-schema Spec the envelope & pin schema CaptureEnvelope, PinReason, StubStrategy, ShadowConfig in reaktor-shadow commonMain. FlexBuffer schemas + serde. Unit tests on round-trip. Phase 1~1 week ## Capture path on one worker Section ID: capture-path-on-one-worker Capture path on one worker ShadowCaptureVisitor in TS for chatServer. Captures envelopes to shadow_captures R2 bucket. PII scrubber for chat-message fields. 5% sampling. Done when: 24h of chatServer traffic visible in R2 as well-formed envelopes, <1% capture overhead per request. Phase 2~1 week ## Shadow Postgres via logical replication Section ID: shadow-postgres-via-logical-replication Shadow Postgres via logical replication Provision shadow Supabase project. Set up wal2json replication slot. Subscriber Worker applies changes to shadow with tenant prefix rewrite + shadow_inserted_at column. Trim job. Done when: shadow DB lags prod by < 5 s and 7-day trim works. Phase 3~1 week ## Shadow R2 + Memgraph + stubs Section ID: shadow-r2--memgraph--stubs Shadow R2 + Memgraph + stubs Read-through R2 binding. Nightly Memgraph dump + import. Workers AI cache stub. Sheets / FCM null sinks. Done when: a dev can run chatServer locally against the full shadow stack and observe end-to-end requests producing no real side effects. Phase 4~1 week ## Replay engine + CLI Section ID: replay-engine--cli Replay engine + CLI The shadow CLI with replay, inspect, pin, diff. Three replay modes (strict/tolerant/exploratory). Diff reporter. Done when: a captured request from yesterday can be replayed against the local branch and produces a structured diff. Phase 5~½ week ## Anomaly detector + pin queue Section ID: anomaly-detector--pin-queue Anomaly detector + pin queue Scheduled 15-min Worker doing stack-trace clustering + latency outliers + payload extremes. Pin budget (50/cat/day). Candidate queue surfaces in Workbench. Phase 6~1 week ## Roll capture to all 10 workers Section ID: roll-capture-to-all-10-workers Roll capture to all 10 workers Apply the Phase-1 middleware to every worker. Tune per-endpoint sample rates. Validate scrubber coverage on every endpoint's schema. Phase 7~½ week ## CI integration Section ID: ci-integration CI integration Three CI jobs above. PR-comment formatting for diff reports. Phase 8~1 week ## Load test + Workbench Shadow panel Section ID: load-test--workbench-shadow-panel Load test + Workbench Shadow panel shadow load verb + k6 integration. The Workbench Shadow tab. Grafana dashboards for capture/replay metrics. Phase 9~1 week ## Time travel + per-branch DB forks Section ID: time-travel--per-branch-db-forks Time travel + per-branch DB forks shadow restore --as-of. Supabase branching for per-PR DB forks (only if Supabase enables it on the account tier). :::tip Total: ~7–8 engineer-weeks, parallelisable across an infra engineer (Phases 2/3/9) and a framework engineer (Phases 0/1/4/5/7). Phase 1 unlocks all CI value; Phases 2–3 unlock dev-can-actually-use-this; Phases 4+ are progressive polish. ::: ## 24. Risks & open questions Section ID: risks 24. Risks & open questions ## Risks Section ID: risks-2 Risks Capture overhead in prod. The visitor sits in every request path. Target: <1% latency overhead at p95 with 5% sampling. Mitigation: capture envelope assembly is async, writes batched to R2 every 200 ms, dropped on backpressure. Logical replication lag. If shadow DB lags prod by minutes, recent captures replay against stale data. Mitigation: monitor replication slot lag as a first-class metric; alert if > 30 s. R2 cost. 26 GB rolling + 200 MB pinned at $0.015/GB/mo = trivial. Class A writes at 216k/day × $0.0045 per 1k = ~$0.03/day. Capture egress for replay is the wild card — if devs replay aggressively, bandwidth costs spike. Mitigation: replay reads stay within Cloudflare's network (free). PII scrubber misses a field. A new schema field added without @Pii annotation could leak real PII into shadow. Mitigation: nightly compliance sampler (§15.1) + a schema-evolution CI check that flags any new free-form text field without an explicit PII annotation. Memgraph snapshot freshness. Nightly is too stale for some bugs. Mitigation: the delta-capture stream allows fine-grained roll-forward; the snapshot interval can shrink to 6h if needed. Stub registry stales. When prod adds a new external API, the stub registry doesn't know about it — replay either fails or fires the real call. Mitigation: FailWithGuidance default + a CI check that scans Kotlin/TS for new HTTP-client construction. Replay non-determinism. A handler that reads system time, RNG, or hostname without going through the framework will not be deterministic. Mitigation: a BlockHound-style runtime check (in CI only) that catches System.currentTimeMillis, UUID.randomUUID, etc. outside the framework's clock / id facilities. Per-branch DB fork cost. If we go the Supabase-branching route, every PR creates a DB fork. Mitigation: only branch on demand (when a dev explicitly runs shadow branch create), prune after 7 days of inactivity. ## Open questions Section ID: risks-3 Open questions Does the shadow stack live in a separate Cloudflare account, or same-account-different-zone? Separate is safer (isolation), same is cheaper (no inter-account billing). Memgraph CE on GCP has a per-instance cost; do we run one shadow Memgraph 24/7 or spin one up on demand for replay sessions? On-demand is cheaper but adds 2-min startup latency to replay. Capture corpus retention beyond 7 days for pinned + 30 days for stack-trace fingerprints — is that GDPR-safe given the scrubber? Likely yes (no real PII), but legal sign-off needed before public launch. Do we expose shadow access to external contributors (if Reaktor is open-sourced)? Probably no — captures still encode tenant-specific shapes that could be reverse-engineered. Integration with the existing bestbudsArchiver: should the archiver's nightly Postgres dump become the cold-restore source for shadow, or is that a separate path? How does this compose with reaktor-notifications' outbox pattern when that lands? The outbox row IS already a perfect capture; we may be able to bootstrap from outbox content rather than installing a separate visitor. ## 25. References Section ID: references 25. References ## Spec sections this design extends Section ID: references-2 Spec sections this design extends §28 Reaktor Shadow: Testing & Quality Infrastructure — the "capture as a visitor" foundation this doc operationalises into a permanent dev environment. §21.8 Transactional outbox — the pattern that lets us safely capture publish intentions without firing them in shadow. §21.9 Idempotent consumers — replay correctness depends on this; the bus design assumes consumers handle duplicates. §29 Performance: Measurement, Profiling, and Optimization — load testing & OTel pipeline this doc plugs into. §29.4 Automated performance testing — Keploy / k6 / Maestro integration assumed. ## Peer designs in this repo Section ID: references-3 Peer designs in this repo performance-observability — Grafana LGTM pipeline shadow capture/replay flows into; Keploy + k6 driver runners. reaktor-notifications-design — uses outbox; FCM/APNs stubs from §13 reuse the same null-sink pattern. deep-link-integration — same graph-visitor pattern (RouteIndexVisitor, BackStackPlannerVisitor); a deep-link tap is a typical capture target. auth-analysis — service principals + tenant API keys; shadow runs as a dedicated service principal. security-plan — PII scrubbing rules; shadow extends them with the deterministic-faker key. graph-kernel-analysis — visitor + facets foundation. reaktor-graph-visitors-design — base classes ShadowCaptureVisitor extends. ## Files inventoried during the design Section ID: references-4 Files inventoried during the design bestbuds/wrangler.json (root) — Hyperdrive bindings: supabase, supabasedirect, cockroach, cockroachdirect; R2: IMAGES. bestbuds/targets/{analytics,chat,sticker,config,bot,bestbudsArchiver,media,notification,social,messaging,prototype}{Server,Worker}/wrangler.json — 10 production workers + 1 archiver + 1 prototype. bestbuds/targets/reaktorServer/src/main/kotlin/ai/bestbuds/server/ServerApplication.kt — Spring Boot REST + GraphQL surface, memgraphDriver() on lines 18, 294. bestbuds/targets/reaktorServer/.../MannaKnowledgeGraphGraphQl.kt — Cypher queries; node labels (Domain, Resource, Chapter, Tenant, Task) and edges (ChapterEdge, TaskDependencyEdge, TaskResourceEdge, GoalTaskEdge). bestbuds/modules/app/src/jvmMain/kotlin/ai/bestbuds/app/db/schema.sql — Postgres schema (user_profiles, friends, groups, group_users, embeddings, heimdall.personal_access_token). bestbuds/n8n/workflows/ — 10 deploy / build / sync workflows; none for shadow refresh yet. ## External tools cited Section ID: references-5 External tools cited Keploy — capture/replay regression testing GoReplay — TCP traffic mirroring mirrord — local-process-in-remote-pod Replay.io — deterministic record/replay Supabase Branching Neon Branching Memgraph DUMP DATABASE Supabase logical replication Cloudflare R2 event notifications k6 load testing Doc lineage. Authored 2026-05-28. Grounded in Reaktor Spec §28 (the visitor-based capture primitive) and a fresh inventory of BestBuds' actual production data surfaces (10 Cloudflare workers, 4 Hyperdrive bindings, 2 R2 buckets, 1 JVM service, 1 Memgraph on GCP CE, plus Workers AI + Google Sheets + planned FCM/APNs). Cross-linked to the deep-link, performance, and notifications design briefs published this week. ## Related docs Section ID: related-docs Related docs Shadow Dev - Use before building production-like test and replay environments. Codex Dev Env - Use only when comparing prior shadow environment proposals. Perf and Observability - Use before optimizing or adding instrumentation. Reaktor Secrets - Use before moving, rotating, distributing, caching, or materializing secrets. DevOps - Use before changing the build/deploy/ops pipeline, the Kotlin platform model, deployment partitioning, gated deploy operations, or the reaktorDesktop Deploy pane; pairs with reaktor-cloud-pane (operator view) and secrets-management. FlexBuffer Plan - Use for history only; prefer the FlexBuffer Binary Serialization document. # Nexergy on Reaktor — Commerce Substrate Design URL: https://reaktor.build/docs/claude-nexergy-appweb-analysis Status: unverified Content revision: 0344aaa52927e07d687e001f007af438d9f689ea6294841eb389b1f325321759 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis","polarity":"Neutral"},{"id":"section-system-map","anchor":"system-map","label":"System map","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#system-map","polarity":"Neutral"},{"id":"section-0-executive-summary","anchor":"0-executive-summary","label":"0. Executive summary","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#0-executive-summary","polarity":"Neutral"},{"id":"section-1-competition-scan","anchor":"1-competition-scan","label":"1. How B2B commerce actually operates (competition scan)","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#1-competition-scan","polarity":"Neutral"},{"id":"section-2-capability-map","anchor":"2-capability-map","label":"2. The commerce capability map → Reaktor","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#2-capability-map","polarity":"Neutral"},{"id":"section-3-design-tenets","anchor":"3-design-tenets","label":"3. Design tenets","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#3-design-tenets","polarity":"Neutral"},{"id":"section-4-existing-modules","anchor":"4-existing-modules","label":"4. Existing modules, applied to Nexergy","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#4-existing-modules","polarity":"Neutral"},{"id":"section-sources","anchor":"sources","label":"Sources","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#sources","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/claude-nexergy-appweb-analysis#related-docs","polarity":"Neutral"}],"relations":[{"id":"claude-nexergy-appweb-analysis:references-codex-nexergy-appweb-analysis","kind":"references","owner":"claude-nexergy-appweb-analysis","incidences":[{"node":"claude-nexergy-appweb-analysis","port":"section-sources","role":"source","ordinal":0},{"node":"codex-nexergy-appweb-analysis","port":"page","role":"target","ordinal":0}]},{"id":"claude-nexergy-appweb-analysis:references-reaktor-db","kind":"references","owner":"claude-nexergy-appweb-analysis","incidences":[{"node":"claude-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-db","port":"page","role":"target","ordinal":0}]},{"id":"claude-nexergy-appweb-analysis:references-reaktor-service","kind":"references","owner":"claude-nexergy-appweb-analysis","incidences":[{"node":"claude-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"claude-nexergy-appweb-analysis:references-reaktor-bus-mesh","kind":"references","owner":"claude-nexergy-appweb-analysis","incidences":[{"node":"claude-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-bus-mesh","port":"page","role":"target","ordinal":0}]},{"id":"claude-nexergy-appweb-analysis:references-reaktor-multitenancy","kind":"references","owner":"claude-nexergy-appweb-analysis","incidences":[{"node":"claude-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-multitenancy","port":"page","role":"target","ordinal":0}]},{"id":"claude-nexergy-appweb-analysis:references-reaktor-surface-design-and-ownership","kind":"references","owner":"claude-nexergy-appweb-analysis","incidences":[{"node":"claude-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-surface-design-and-ownership","port":"page","role":"target","ordinal":0}]}]} ## Nexergy on Reaktor — Commerce Substrate Design Section ID: preamble Nexergy Energy is a real B2B biomass trader-aggregator (a live startup, nexergyenergy.in). This is the production design for that platform, built on Reaktor. It keeps every feature from the prototype and the v2.0 PRD and rebuilds the whole thing as compositions of Reaktor primitives, grounded in how B2B commerce actually operates. Assume Reaktor itself is feature-complete; this doc is about the proposed compositions and commerce substrate. Nexergy is the intended product — not a template or a sample app. ## System map Section ID: system-map System map The whole platform at a glance. Read top-down: every experience composes commerce capabilities; each capability is a recipe/wiring over the new commerce substrate; the substrate stands on the existing Reaktor foundation and data tiers. Cross-cutting concerns span every layer. EXPERIENCE Buyer App · Ops Console · Procurement · Marketing + Leads └ reaktor-ui / tactile · deep-link · i18n · offline sync COMMERCE Catalog/Search · RFQ → Quote · Pricing + Tax · OMS · CAPABILITIES WMS/Inventory · TMS/Logistics · Payments + Escrow · (recipes) Returns/RMA · Credit/Financing · Reconciliation · Notifications · Analytics/KPIs · Fraud/Risk COMMERCE ★ reaktor-catalog ★ reaktor-ledger ★ reaktor-fulfillment SUBSTRATE products · SKUs · stock · money · order · PO · (NEW) specs · price books escrow · credit · shipment · returns carbon + OMS/TMS recipes ◆ audit journal ◆ compliance / document gates REAKTOR graph (workflows · guards · routing) · actor (mailboxes) · FOUNDATION server (saga · outbox · CQRS · event-sourcing) · bus-mesh · (existing) service · multitenancy · auth · notifications · work · analytics-telemetry · capability DATA & RUNTIME Postgres · Memgraph · D1 · Durable Objects · R2 · Pub/Sub+Queues runtime: Edge = Cloudflare Workers ‖ Core = JVM / k3s ─────────────────────────────────────────────────────────────────────────── cross-cutting: supplier anonymity · audit trail · compliance gates · OTel legend: ★ new full-stack module ◆ new thin primitive · existing The event spine threads it all: every state change (a ledger posting, an order transition, a dispatch ping) is one effectively-once reaktor-bus envelope — and the CQRS read models, notifications, analytics/KPIs, the audit journal, escrow-release triggers, and credit-underwriting signals all subscribe to that one stream. The §2 table is this same map with each capability's exact Reaktor realization. ## 0. Executive summary Section ID: 0-executive-summary 0. Executive summary Nexergy is the target platform. What is not a vertical is the code: there is no reaktor-biomass module. Nexergy composes a small set of full-stack Reaktor modules — most already in the framework — plus a thin commerce substrate proposed for Reaktor. The proposed module is reaktor-ledger: the primitives are factored to be general (good module hygiene, and the engine grows for later apps), but the deliverable here is Nexergy itself. :::info[The thesis, in one breath] Reaktor is the engine; Nexergy is a real platform we ship on it. Everything the Nexergy PRD needs — the full composable-commerce surface (catalog, cart/RFQ, pricing, promotions, tax, OMS, inventory, WMS, logistics, payments, reconciliation, returns, credit, search, fraud, analytics) — maps onto Reaktor with just 3 new full-stack modules + 2 thin primitives. We factor those modules as general primitives (reaktor-ledger, not reaktor-biomass) so the engine keeps its convex set, but every line here is in service of shipping Nexergy. ::: Two market truths reshaped this revision (see §1): Embedded credit is the moat, not a "future feature." OfBusiness — the model Nexergy's PRD explicitly copies — earns ~43% of revenue from lending, underwritten from its own transaction data. Pure marketplaces (Buyofuel) get out-competed by full-stack trader-aggregators that own inventory + logistics + working-capital credit. The PRD defers credit to Phase 3; the market says it is the business. So this design makes financing a first-class subsystem — and, happily, it needs no new module (it is reaktor-ledger credit accounts underwritten by the audit/analytics stream). Commerce is a known capability map. "How ecommerce operates" is not mysterious — composable commerce decomposes into packaged business capabilities, and the OMS lifecycle is a canonical flow: capture → validate → reserve → allocate → fulfil → deliver → return/close → analyse. We map that map onto Reaktor and find the gaps are small. The recommendation in numbers: 3 new modules (reusable everywhere): reaktor-ledger (keystone), reaktor-catalog, reaktor-fulfillment. 2 thin cross-cutting primitives: an audit journal and compliance/document gates — both ride the event spine. OMS / WMS / TMS / procurement / escrow / returns / financing are recipes — named compositions of graph + actor + server + ledger + catalog + bus. Tax/GST, reconciliation, fraud/risk, promotions, search, recommendations = wiring over existing modules. No new modules. ## 1. How B2B commerce actually operates (competition scan) Section ID: 1-competition-scan 1. How B2B commerce actually operates (competition scan) ## The biomass field Section ID: biomass-field The biomass field Player Model Reach What Nexergy learns Buyofuel Pure marketplace (buyer↔seller) ~3k businesses, ~10k MT/day, 7+ states, ~$2.6M raised Marketplaces scale listings, not reliability — the gap Nexergy attacks BiofuelCircle Marketplace + transport coordination + settlement ~$62M valuation (Pune) The leader already went full-stack on logistics + payments; a thin marketplace is not enough Farm2Energy Feedstock/biomass supply energy crops, aggregation Upstream supply security matters; first-party procurement is defensible ## The horizontal trader-aggregators (the real playbook) Section ID: horizontal The horizontal trader-aggregators (the real playbook) Player Vertical Signal OfBusiness Steel, cement, polymers, chemicals, solar ~$5B; 55% materials / 43% lending / 2% SaaS — financing is the profit engine Infra.Market Construction materials Closest analog: commodity, own-brand + inventory + credit Udaan FMCG/long-tail B2B ₹5,700cr revenue FY24; inventory + logistics + payments + credit bundled Zetwerk / Moglix / Bizongo Manufacturing / MRO / packaging All full-stack: marketplace alone loses to inventory + workflow + finance :::tip[The lesson, and Nexergy's wedge] Across every successful B2B commodity platform the winning shape is identical: own the inventory, own the logistics, embed the credit, hoard the transaction data, and use that data to underwrite financing competitors can't. Nexergy's PRD already chose the trader-aggregator shape (first-party stock, supplier anonymity, guaranteed supply). This design adds the missing moat — embedded working-capital finance (§9) — and grounds the rest in the standard commerce capability map. ::: ## The canonical commerce decomposition Section ID: decomposition The canonical commerce decomposition Composable commerce ("MACH": Microservices, API-first, Cloud-native, Headless) breaks a platform into packaged business capabilities: catalog/PIM, cart, pricing, promotions, tax, OMS, inventory, search, recommendations, payments, CMS. The OMS lifecycle is a fixed eight-stage flow: capture → validate → reserve → allocate → fulfil → deliver → return/close → analyse. Warehousing further splits into OMS (orders), IMS (inventory), WMS (warehouse ops), TMS (transportation — what the PRD loosely calls "LMS"), and WCS (equipment). :::note[Reaktor is composable commerce — without the integration tax] MACH's weakness is that the packaged capabilities are N separate SaaS vendors stitched by APIs — data silos, reconciliation drift, and brittle glue. Reaktor delivers the same composability where the capabilities are modules wired on one graph, sharing one event spine and one ledger. You get best-of-breed decomposition and a single source of truth. That is the design's competitive claim. ::: ## 2. The commerce capability map → Reaktor Section ID: 2-capability-map 2. The commerce capability map → Reaktor The whole surface, and where each piece lives. Only the bold rows are new; everything else is existing modules + wiring. Capability (how commerce uses it) Reaktor realization New? Storefront / CMS / lead capture reaktor-ui + Workers (the already-shipped expo site) — Catalog / PIM (products, SKUs, specs, taxonomy) reaktor-catalog module Search & discovery (spec filters, facets) reaktor-catalog + reaktor-db search projection (Postgres FTS / Memgraph) wiring Cart / RFQ (B2B quote-to-order) reaktor-graph workflow + catalog spec-match wiring Pricing & rating (cost build-up, contract vs spot) reaktor-service rating service + reaktor-graph margin guards wiring Promotions / volume & seasonal discounts reaktor-catalog price books + policy guards wiring Tax / GST (IGST·CGST·SGST, TDS, reversal on returns) rating service + reaktor-ledger postings wiring OMS (capture→…→analyse lifecycle) reaktor-fulfillment (Order actor + reaktor-server saga) module Inventory / IMS (stock by cluster, reservations) reaktor-ledger stock accounts module WMS (bins, FIFO, quality zones, quarantine) reaktor-ledger + Cluster actor + reaktor-work recipe Logistics / TMS (carrier, route, e-way, GPS, POD) reaktor-fulfillment Shipment actor + reaktor-bus telemetry recipe Payments / PSP (UPI, gateway, NEFT, escrow) reaktor-service adapters + reaktor-ledger wiring Reconciliation & settlement (payout↔order match, supplier payout) reaktor-work + reaktor-ledger matching recipe Returns / RMA / reverse logistics (authorize, reverse-ship, refund, tax reversal) reaktor-fulfillment recipe + reaktor-ledger reversal + compliance gate recipe Credit / embedded finance (limits, BNPL, invoice financing) reaktor-ledger credit accounts + analytics underwriting recipe Fraud / risk (anomalies, credit risk) reaktor-analytics-telemetry + reaktor-auth policy + audit stream wiring Notifications (email/SMS/WhatsApp/push) reaktor-notifications — Recommendations / demand forecasting reaktor-analytics-telemetry + AI (reaktor-koog / browser-local) wiring Identity, RBAC, B2B gate, org isolation, supplier anonymity reaktor-auth + reaktor-multitenancy wiring Audit log (immutable, hash-chained) + compliance gates audit journal + document gates thin primitives Analytics / BI / KPIs reaktor-analytics-telemetry — ## 3. Design tenets Section ID: 3-design-tenets 3. Design tenets Six rules. If a feature obeys them, it gets no new module. Conserved quantities are ledgers, never columns. Stock, money, escrow, credit, carbon — append-only, double-entry. Balance = a fold. Oversell and lost money become structurally impossible, and audit + reconciliation fall out for free. Entities with invariants are actors. Order, Escrow, Shipment, SKU×Cluster stock — ActorNode with a serialized mailbox. Stock allocation (the classic WMS race) becomes one mailbox per stock position. Lifecycles are graph workflows. RFQ→Quote, the eight-stage OMS flow, shipment states, approval chains — reaktor-graph workflows with transition guards. Cross-entity orchestration is a saga. "Accept ⇒ reserve ⇒ invoice ⇒ escrow ⇒ dispatch ⇒ settle" is a reaktor-server saga over the transactional outbox: reliable, idempotent. Events are the spine. Every state change is one reaktor-bus envelope (effectively-once). CQRS read models, notifications, analytics, the audit journal, escrow triggers, and fraud signals all subscribe to that one stream. The data is the moat. The same event stream that powers audit underwrites embedded credit. Transaction history → risk scoring → working-capital offers competitors cannot replicate. :::note[Module-layering rule — honored by every new module] Per Reaktor's layering rule (reference impl: reaktor-auth), reaktor-ledger, reaktor-catalog, and reaktor-fulfillment each use reaktor-graph internally (LedgerNode / CatalogNode / OrderNode projections for the workbench and agents) but also expose a plain, graph-agnostic API (LedgerClient, CatalogService, OrderService). ::: ## 4. Existing modules, applied to Nexergy Section ID: 4-existing-modules 4. Existing modules, applied to Nexergy reaktor-graph — RFQ→Quote, every entity state machine, persona routing (Buyer / Ops / internal are graph scopes), and approval chains are workflows + guards. reaktor-service — every API is a typed Service with Spring/Workers adapters. Supplier anonymity is enforced here: buyer-facing projections strip supplier identity and surface only the cluster. External adapters: UPI/Razorpay, WhatsApp/Twilio, carrier & e-way APIs, Tally/Zoho. reaktor-server — the OMS/WMS/TMS spine: saga, outbox, CQRS read models, event-sourcing (the ledger + audit substrate), idempotency/retries/circuit-breakers for payment and carrier calls. JVM/k3s + Workers edge. reaktor-db — five-tier persistence (authoritative Postgres/Memgraph; edge D1/DO; R2 for documents; Pub/Sub+Queues spine) and server-authoritative sync for offline-first buyer/ops mobile (draft RFQs, offline POD capture). reaktor-bus-mesh — inventory movements, order transitions, dispatch pings, settlement and escrow triggers, GPS telemetry — effectively-once. Mesh (WebRTC/CRDT) optional for field devices in low-connectivity clusters. reaktor-actor — Order, Escrow, Shipment, SKU×Cluster positions as location-transparent actors (k3s or Durable Objects); serialized mailboxes, no distributed locks. reaktor-multitenancy — buyer-org isolation and an internal supplier scope buyer projections can never read: anonymity by construction (RLS + mandatory parameterization), not by filtering. reaktor-auth — GST-verified B2B onboarding gate, the PRD's RBAC matrix (Owner/Procurement/Finance/Ops/Plant/Viewer), approval limits as policy, the anonymity masking boundary, and credit-risk gates. reaktor-notifications — RFQ/quote/order/dispatch/payment events → email/SMS/WhatsApp/push. reaktor-analytics-telemetry — PRD KPIs (fulfillment, OTD, RFQ→order conversion, margin, inventory turns), buyer intelligence, fraud anomaly signals, and credit underwriting features. reaktor-work — reorder-point checks, SLA timers (4-hour RFQ), nightly reconciliation, settlement runs, report/CSV generation (the shipped lead-export cron is the seed). reaktor-capability — device/network tiers drive mobile offline degradation. reaktor-ui / tactile — Compose Multiplatform buyer app, ops console, internal tools; multi-language i18n; the prototype's token + tweak design system becomes the visual layer. deep-link-integration powers quote and tracking links. reaktor-koog / browser-local AI power demand forecasting and assisted RFQ. ## 5. New module #1 — reaktor-ledger (the keystone) Section ID: 5-reaktor-ledger 5. New module #1 — reaktor-ledger (the keystone) A generic append-only, double-entry, event-sourced ledger for any conserved quantity. Core abstraction: Account (typed unit), Posting (balanced transfer), Entry (atomic, sums to zero), Balance (a fold). Every Account is an ActorNode → postings serialize → no oversell, no double-spend. Reservations are first-class (reserve → commit | release) — that is stock allocation. Unit-generic: stock (MT per SKU×Cluster), money (₹ AR/AP/cash), escrow (held funds), credit (buyer exposure vs limit), carbon (credits). Built on: reaktor-server event-sourcing + reaktor-actor + reaktor-db + reaktor-bus. Powers in Nexergy: WMS inventory, invoicing/AR, supplier settlement/AP, escrow, credit/embedded finance (§9), sustainability carbon balance, and the audit journal (§8). Reconciliation is ledger matching. Powers elsewhere: any wallet, payout system, inventory app, loyalty program, or carbon exchange. ## 6. New module #2 — reaktor-catalog (PIM) Section ID: 6-reaktor-catalog 6. New module #2 — reaktor-catalog (PIM) What can be bought/sold, and on what terms. Core abstraction: Product → SKU/variant → typed spec attributes (fuel grades: GCV/NCV, moisture, ash, fines, bulk density), Taxonomy, PriceBook (base rates by cluster/season → also the promotions surface), MOQ, Availability (a projection over the stock ledger). Spec-matching drives RFQ sourcing ("≥3,400 kcal, ≤15% ash"); search is a reaktor-db projection (FTS/Memgraph), replacing the PRD's Elasticsearch. Powers elsewhere: every storefront/PIM — a parts database, a fashion catalog, a grocery SKU tree. ## 7. New module #3 — reaktor-fulfillment (the order domain) Section ID: 7-reaktor-fulfillment 7. New module #3 — reaktor-fulfillment (the order domain) The order/quote/PO/shipment entity family + lifecycle templates + OMS/TMS recipes. Core abstraction: Quote, Order, PurchaseOrder, Shipment, Return — each an ActorNode with a reaktor-graph lifecycle. A sales order and a purchase order are one primitive in two directions (Nexergy sells to buyers and buys from manufacturers), so OMS and procurement share one engine. OMS = the eight-stage flow (capture→…→analyse) as a workflow + the fulfillment saga. TMS / logistics = the Shipment actor + a logistics saga (carrier selection, vehicle/route, e-way bill, GPS activation, POD) + bus telemetry. (Note: the PRD's "LMS" is transportation = TMS; warehouse LMS = labour management, out of scope for a 3PL-light trader.) Returns / RMA = a Return workflow (authorize → RMA number → reverse-ship → inspect → reaktor-ledger reversal: stock back + refund + GST reversal), gated by compliance docs. WMS is not here — it is reaktor-ledger (stock) + the Cluster actor + reaktor-work (reorder). Inventory is a ledger, not an order concept. :::tip[Minimal variant] reaktor-fulfillment is the most collapsible of the three (its entities are graph nodes; its orchestration is server sagas). You could ship only reaktor-ledger + reaktor-catalog and express orders/POs/shipments/returns as app-level recipes. I recommend keeping it so OMS/TMS aren't re-coded per app — but it is the honest place to cut if module count must shrink. ::: ## 8. Cross-cutting thin primitives Section ID: 8-cross-cutting 8. Cross-cutting thin primitives Audit journal — the PRD's immutable compliance log. Because entities are event-sourced and every posting/saga step is already an event, audit is a reaktor-graph command interceptor writing each mutation into an append-only, hash-chained, tenant-scoped journal (a special ledger account-of-events) plus a query projection (who · what · ref · when · severity). New as a primitive, nearly free in cost; can live inside reaktor-server. It is also the underwriting data for §9. Compliance / document gates — Buyer PO, QC cert, E-way bill, weighbridge, POD, GST docs are R2 objects attached to entities; gates are reaktor-graph transition guards ("no dispatch without E-way + weighbridge", "no escrow release without POD"). Reusable as KYC/contract gating anywhere. No module needed: tax/GST (rating service + ledger postings), reconciliation (work + ledger matching), fraud/risk (analytics anomalies + auth policy + audit stream), promotions (catalog + guards), search/recommendations (db projection + analytics). ## 9. The financing layer — embedded working capital Section ID: 9-financing 9. The financing layer — embedded working capital The moat the PRD under-weights, and the reason trader-aggregators beat marketplaces. It needs no new module. Credit limit = a reaktor-ledger exposure account per buyer (utilized vs approved). Underwriting = reaktor-analytics-telemetry features over the audit journal transaction history (order frequency, on-time payment, volume, dispute rate) → a risk score behind a reaktor-auth policy. This is the data moat: Nexergy underwrites from data no bank or new entrant has. Products = buyer BNPL (30/45/60-day terms), invoice financing, and supplier early-payment — all just ledger postings against the credit account, gated by limit policy. Recovery & risk = overdue exposure raises fraud/risk signals and tightens limits automatically via the same event stream. This turns Nexergy from a margin-only trader (8–15%) into a margin + financing business — the OfBusiness shape — using infrastructure the design already has. ## 10. Putting it together — Nexergy as recipes Section ID: 10-recipes 10. Putting it together — Nexergy as recipes RFQ → Quote (workflow): submit RFQ → reaktor-catalog spec-match → stock checked via reaktor-ledger availability across nearby clusters → rating service prices (cost build-up + margin guard + tax) → reaktor-auth approval if below floor → quote published, reaktor-notifications fires. Supplier never surfaced. Sales-order fulfillment (saga over the outbox), mapped to the canonical eight stages: OMS stage Primitive Effect Capture reaktor-fulfillment Order actor Order created Validate graph guards + reaktor-auth (+ credit check, §9) Terms/credit OK Reserve reaktor-ledger reservation on SKU×Cluster No oversell Allocate Cluster actor selects lot (FIFO, distance) Lot bound Fulfil Shipment actor + TMS saga E-way, GPS, compliance gate Deliver POD gate satisfied → bus event Quality window opens Return/close escrow release (POD+QC) → supplier AP; or Return/RMA recipe Settled or reversed Analyse reaktor-analytics-telemetry KPIs, underwriting features (every stage) audit interceptor Immutable journal entry WMS reorder loop: reaktor-work reads the stock ledger; balance < reorder point ⇒ bus event ⇒ auto-PurchaseOrder (same fulfillment engine, supplier direction) ⇒ inbound ⇒ QC gate ⇒ stock credit on acceptance. Reconciliation: nightly reaktor-work matches PSP payouts ↔ invoices in the ledger; mismatches raise exceptions inside the marketplace dispute window; GST output/input reconciles for GSTR filing. ## 11. Runtime topology Section ID: 11-runtime 11. Runtime topology Two planes — the split Reaktor already targets, and the stack the prototype already chose (Cloudflare): Edge (Workers / DO / D1 / R2 / Queues): lead capture, buyer-facing reads (CQRS projections), notifications, per-order/shipment Durable-Object actors, document storage, the bus. Core (JVM / k3s via reaktor-server): heavy sagas, the authoritative ledger, pricing, underwriting, settlement runs, analytics rollups, Postgres/Memgraph authority. Sync: reaktor-db server-authoritative sync feeds the offline-first Compose mobile apps. The PRD's recommended AWS + Postgres + Mongo + Elasticsearch + Socket.io stack is superseded — Reaktor's cloud plane replaces it, and Nexergy runs on the same substrate as BestBuds. ## 12. Why these are Reaktor primitives, not a Nexergy vertical Section ID: 12-primitives-not-vertical 12. Why these are Reaktor primitives, not a Nexergy vertical The discipline behind the module choices: we add general primitives, never a reaktor-biomass. The test that a primitive is factored correctly is that it is not biomass-specific — it would serve a different app unchanged. reaktor-ledger, reaktor-catalog, and reaktor-fulfillment all pass that test, which is exactly why they belong in Reaktor rather than inside the Nexergy app: Primitive Biomass-specific? The same primitive, unchanged, also serves reaktor-ledger No — it is conserved quantities any wallet, payout, inventory, loyalty, or carbon system reaktor-catalog No — it is products/SKUs/specs any storefront / PIM reaktor-fulfillment No — it is order/PO/shipment/returns any OMS/WMS/TMS That generality is a consequence of clean factoring, not the goal — the goal is to ship Nexergy. But it is why building Nexergy this way leaves the engine stronger for whatever Reaktor builds next. :::info[The Unreal analogy] Existing Reaktor modules are the engine subsystems — rendering (reaktor-ui), physics/consistency (reaktor-actor), networking (reaktor-bus-mesh), persistence (reaktor-db), gameplay framework (reaktor-graph). The three new modules add a commerce gameplay framework: reaktor-ledger (economy), reaktor-catalog (item database), reaktor-fulfillment (quests/missions). Nexergy is a real, shipping title built on that engine — designed and built in full, the way you'd build any game, not as a tech demo. ::: ## 13. Migration from the prototype Section ID: 13-migration 13. Migration from the prototype Keep the design system. Tokens + tweak harness become the reaktor-ui layer; the three personas become graph scopes. Replace the mock. window.NEXERGY_ACTIONS → reaktor-service clients; in-memory NEXERGY_DATA mutations → real ledger postings + saga steps; the audit array → the audit journal. Phase it (commerce-realistic): Phase 1 — reaktor-catalog + RFQ/quote workflow + reaktor-fulfillment Order + reaktor-ledger (money) + audit + tax. Single Brahmapur cluster, edge + JVM. Phase 2 — stock ledger (WMS) + TMS/GPS + payments adapters + reconciliation + credit/embedded finance (moved up — it is the moat). Phase 3 — returns/RMA, carbon accounts, demand forecasting — each just new account types or recipes, no new code. The lead funnel is already on-substrate (CF/D1/R2/cron) — promote /api/materials|rfqs|orders from placeholders to reaktor-service handlers. ## 14. Module scorecard Section ID: 14-scorecard 14. Module scorecard Primitive New? Built on Reused by reaktor-ledger module server (event-sourcing), actor, db, bus wallets, marketplaces, inventory, loyalty, carbon, embedded finance reaktor-catalog module db, service every storefront / PIM / search reaktor-fulfillment module (collapsible) graph, actor, server, ledger, catalog any OMS/WMS/TMS/returns app audit journal thin primitive ledger journal + graph interceptor every regulated app + underwriting compliance/document gates thin primitive db (R2) + graph guards KYC, contracts, logistics financing, tax/GST, reconciliation, fraud, promotions, search, anonymity, OMS/WMS/TMS wiring / recipes existing modules — Net: the entire composable-commerce surface, plus the embedded-finance moat, on 3 modules + 2 thin primitives + recipes — zero vertical code in the framework. ## Sources Section ID: sources Sources Competition and commerce-operations scan: OfBusiness model · Buyofuel / Tracxn profile · BiofuelCircle · Udaan model · Composable commerce / MACH · OMS / fulfillment flow · Embedded B2B finance · Ecommerce returns / reconciliation / GST. Design · Claude · features from the Nexergy v2.0 PRD, re-expressed as Reaktor primitives + wiring, grounded in the B2B commerce competitive landscape. Prototype scan: Codex Nexergy appWeb Analysis. ## Related docs Section ID: related-docs Related docs Nexergy Energy - Use before building Nexergy Energy on Reaktor, scoping its commerce/inventory/logistics/ledger primitives, or designing its OMS/WMS/LMS platform surfaces on the graph. Data Layer - Use before choosing a store, designing offline-first sync, or deciding authority vs cache vs projection for a datum; the centerpiece is the tier 1↔2/3 server-authoritative sync engine. Service Layer - Use before adding service APIs, splitting reaktor-service out of reaktor-graph, wiring handlers to Spring/Workers, or making modules graph-projectable without hard graph dependencies. Reaktor Bus - Use before designing durable async events, jobs, fan-out, queues, Pub/Sub, outbox, DLQ, replay, or graph-visible delivery. Multitenancy - Use before designing tenant isolation, adding a tenant-scoped store, wiring the tid claim, or building per-tenant quotas/residency/lifecycle; pairs with reaktor-server (high-scale tenancy) and auth-analysis (the membership model). 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. # Codex Critic Review URL: https://reaktor.build/docs/codex-critic-review Status: historical Content revision: 69a0832a290f89fc45a27002ae14578883b8239b99b3534fa6d3b8c4d54567d2 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/codex-critic-review","polarity":"Neutral"},{"id":"section-1-executive-verdict","anchor":"1-executive-verdict","label":"1. Executive Verdict","profile":"section","contract":"https://reaktor.build/docs/codex-critic-review#1-executive-verdict","polarity":"Neutral"},{"id":"section-2-core-counterarguments","anchor":"2-core-counterarguments","label":"2. Core Counterarguments","profile":"section","contract":"https://reaktor.build/docs/codex-critic-review#2-core-counterarguments","polarity":"Neutral"},{"id":"section-3-code-grounded-objections","anchor":"3-code-grounded-objections","label":"3. Code-Grounded Objections","profile":"section","contract":"https://reaktor.build/docs/codex-critic-review#3-code-grounded-objections","polarity":"Neutral"},{"id":"section-4-security-and-operational-critique","anchor":"4-security-and-operational-critique","label":"4. Security And Operational Critique","profile":"section","contract":"https://reaktor.build/docs/codex-critic-review#4-security-and-operational-critique","polarity":"Neutral"},{"id":"section-5-agents-and-command-queue-critique","anchor":"5-agents-and-command-queue-critique","label":"5. Agents And Command Queue Critique","profile":"section","contract":"https://reaktor.build/docs/codex-critic-review#5-agents-and-command-queue-critique","polarity":"Neutral"},{"id":"section-6-testing-critique","anchor":"6-testing-critique","label":"6. Testing Critique","profile":"section","contract":"https://reaktor.build/docs/codex-critic-review#6-testing-critique","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/codex-critic-review#related-docs","polarity":"Neutral"}],"relations":[{"id":"codex-critic-review:references-claude-critic-review","kind":"references","owner":"codex-critic-review","incidences":[{"node":"codex-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"claude-critic-review","port":"page","role":"target","ordinal":0}]},{"id":"codex-critic-review:references-reaktor-competitive-analysis","kind":"references","owner":"codex-critic-review","incidences":[{"node":"codex-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-competitive-analysis","port":"page","role":"target","ordinal":0}]},{"id":"codex-critic-review:references-reaktor-workbench-roadmap","kind":"references","owner":"codex-critic-review","incidences":[{"node":"codex-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-workbench-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"codex-critic-review:references-codex-roadmap","kind":"references","owner":"codex-critic-review","incidences":[{"node":"codex-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"codex-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"codex-critic-review:references-reaktor-megascale-strategy","kind":"references","owner":"codex-critic-review","incidences":[{"node":"codex-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-megascale-strategy","port":"page","role":"target","ordinal":0}]},{"id":"codex-critic-review:references-reaktor-framework-overview","kind":"references","owner":"codex-critic-review","incidences":[{"node":"codex-critic-review","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-framework-overview","port":"page","role":"target","ordinal":0}]}]} ## Codex Critic Review Section ID: preamble Skeptical counterarguments against the full Reaktor control-plane vision. ## 1. Executive Verdict Section ID: 1-executive-verdict 1. Executive Verdict The strongest criticism is that Reaktor is trying to become a framework, runtime, cross-platform app architecture, DB/auth/service substrate, deploy plane, observability product, visual workbench, and agent command system at the same time. That ambition may be correct long term, but the current evidence does not yet justify trusting the full control-plane vision. 8/10 ## Scope Risk Section ID: scope-risk Scope Risk The roadmap expands every visible prototype tab into a production subsystem before one narrow loop has proven itself end to end. 9/10 ## Trust Risk Section ID: trust-risk Trust Risk The workbench wants to inspect, edit, test, deploy, query data, manage auth, and run agents. That is dangerous until identity, audit, rollback, and permissions are hard guarantees. 7/10 ## Architecture Risk Section ID: architecture-risk Architecture Risk A graph-first runtime can become a useful abstraction, but it can also become a private platform tax that makes normal app behavior harder to reason about. 5/10 ## Salvageability Section ID: salvageability Salvageability The idea is not invalid. The codebase has real graph, port, service, auth, DB, worker, and desktop-engine substrate. The issue is sequence and proof. :::note The critic's version of the roadmap is simple: stop proving that the workbench can display a beautiful universe; prove that it can safely explain and change one real production-shaped flow better than existing tools. ::: ## What would change this verdict Section ID: what-would-change-this-verdict What would change this verdict A live WorkbenchManifest generated from BestBuds source/runtime without static scenario data. One traced flow from UI click to graph route, interactor, cache, service, worker, DB, telemetry, and test result. Security posture moved from "known TODO" to enforced: signed service identity, worker auth, session lifecycle, redaction, audit. A command queue that can preview and apply one low-risk change with deterministic source diffs, tests, rollback, and commit linkage. A ruthless reduction of workbench tabs until the first end-to-end proof is real. ## 2. Core Counterarguments Section ID: 2-core-counterarguments 2. Core Counterarguments Claim in favor of ReaktorDevil's advocate responseHow to answer the criticism"Graph-first app composition makes systems visible and controllable."Graph-first can also hide normal program flow behind custom ports, routes, and lifecycle conventions. If only the framework author can debug it fluently, the abstraction has failed.Show that a new contributor can trace and modify one BestBuds flow faster with Reaktor than with normal IDE search, logs, and tests."The workbench can become the control plane for apps."A control plane is not a UI. It is a trust boundary. The prototype currently demonstrates layout, not safe authority over code, data, auth, tests, or deploys.Implement read-only first. Then add commands with explicit capability scopes, dry runs, audit logs, rollbacks, and approvals."AI agents can operate through a command queue."The command queue can create the illusion of safety while moving risk into command generation, validation, and review. Bad commands with good formatting are still bad changes.Restrict early agent output to scout reports and test suggestions. Allow writes only for narrow command types with deterministic validators."Reaktor unifies Kotlin, JS, C++, Cloudflare, desktop, web, mobile, DB, auth, and deploy."Unification is only valuable if it reduces operational complexity. Today it risks multiplying build, runtime, and debugging failure modes across too many stacks.Prove a smaller unification boundary first: graph plus typed services plus telemetry for BestBuds chat."The prototype already shows the desired product."The prototype can anchor product direction, but it can also bias the team toward implementing every screen instead of validating the highest-risk assumptions.Keep the prototype as a vision artifact; use production-readiness gates to remove or label every fake surface."BestBuds can dogfood Reaktor."BestBuds itself has unfinished flows and security gaps. A dogfood app with unresolved product behavior can hide whether Reaktor is helping or merely adding more moving parts.Pick one mature BestBuds slice and freeze it as the dogfood target. Do not use every incomplete product area as proof. ## The biggest conceptual challenge Section ID: the-biggest-conceptual-challenge The biggest conceptual challenge Reaktor wants to be both the abstraction layer and the tool that explains the abstraction layer. That creates a circular risk: the workbench may look uniquely useful because the framework introduces concepts that require a workbench to understand. The product needs to prove it also improves work on code that did not create the need for a custom visual explanation. ## 3. Code-Grounded Objections Section ID: 3-code-grounded-objections 3. Code-Grounded Objections The current codebase has real substance, but several details cut against the idea that the production workbench is near. These are not fatal; they are evidence that the roadmap must be sequenced much more conservatively. AreaObserved source realityCritical readSeverityGraph exportReaktorGraphDocument.kt exports visible nodes and containment/navigation/data edges, but omits route nodes as first-class entities, source ownership, port types, service catalogs, stores, auth requirements, deploy targets, telemetry links, and test links.The current export is a graph sketch, not a workbench manifest. Building a production UI on top of it would force the web layer to invent missing meaning.HighSource of truthThe web prototype depends on scenario*.jsx, global window.ENTITIES, and window.BUNDLE; the server has /apps/{appId}/graph; the desktop engine has runtime graph state.There are already multiple competing truths: static scenario, runtime graph, source code, generated build output, and desired command state.HighFeature slotsGlobal Feature slots initialize auth, database, dependency adapter, theme, telemetry, and other runtime capabilities.Global slots are pragmatic, but a control plane needs isolation. Multiple app sessions, tests, previews, and agents can interfere if global state is not scoped carefully.MediumLifecycle and navigationGraph.dispatch handles cross-graph navigation through containers; RouteNode has TODOs around only allowing one stateful node to connect.The runtime has powerful behavior, but the edge cases are exactly where a visual workbench must be trustworthy. TODOs in navigation semantics undermine edit/apply confidence.MediumCompiler metadataReaktorProcessor.kt returns immediately, disabling the KSP metadata path.Without source metadata, the workbench will struggle to map runtime entities to precise files, ownership, codegen targets, and affected tests.HighCloudflare worker authBestBudsWorker.kt rejects enabled auth with a message that worker auth is not wired yet.A deploy/control plane over workers cannot be production-ready while service authentication is explicitly disabled at the worker wrapper layer.HighAuth parityAuth has meaningful kernel/server code, but Android Apple login is still TODO and session refresh/revoke/audit lifecycle is not fully unified.The auth system is promising but uneven. The workbench must not present provider health, session controls, or RBAC editing as mature before parity and lifecycle are enforced.HighBestBuds flowsChat has real orchestration, but profile edit, campaign joins/details, event actions, image picking, call actions, and some user state flow work remain partial or TODO.Using all of BestBuds as proof overstates maturity. Use the strongest slice, not the whole product surface.MediumTelemetryGraphTelemetry observes lifecycle/backstack/port listeners for existing nodes and BestBuds has analytics contracts.This is a start, not an observability product. The hard work is correlation, retention, sampling, query APIs, cost, privacy, and release comparison.MediumBuild complexityThe stack spans Gradle/KMP, Karakum, TypeScript, Vite, Cloudflare, Wrangler, CMake, C++, iOS, Android, desktop, and server.The tooling matrix is a strategic liability unless the workbench demonstrably reduces it. Otherwise Reaktor becomes a platform maintenance project before it becomes a product.High ## Counterargument to the counterargument Section ID: counterargument-to-the-counterargument Counterargument to the counterargument The codebase is not empty. The graph runtime, typed service model, object DB, auth kernel, Cloudflare bridge, desktop semantics inspector, and BestBuds chat orchestration are legitimate foundations. The critic's point is that legitimacy at the substrate layer does not automatically make the full workbench product legitimate. The next proof has to be narrower and harder. ## 4. Security And Operational Critique Section ID: 4-security-and-operational-critique 4. Security And Operational Critique :::note Primary concern: Reaktor's most attractive capabilities are also its most dangerous. A tool that can inspect data, edit auth, run agents, deploy workers, and apply code commands must be treated as privileged infrastructure, not as a frontend project. ::: RiskWhy it mattersMinimum acceptable postureTrust-on-header identityBestBuds service clients pass serialized user headers, and workers read the current user from request context. This is not a production identity boundary unless the header is signed and verified upstream.Access tokens only. Worker middleware validates issuer, audience, expiry, tenant, app id, and required scopes. Dev impersonation must be isolated and labeled.Raw chat socket identityChat WebSocket connection passes userId and userName in query params. The code comments already call out the need for signed auth.Short-lived room tokens, server verification, replay protection, expiry tests, and no user-controlled display identity without server trust.Secrets in config/scriptsHardcoded database connection details and command-line deploy tokens have appeared in configuration/scripts. A workbench that indexes and deploys this system can accidentally expose them.Secret scanner in CI and deploy gates, manifest redaction, no secret values in UI, and config moved to proper secret stores.DB console temptationA database tab that can query Postgres, D1, R2, Durable Objects, SQLite, and Memgraph is an exfiltration and destructive-write surface.Read-only by default, scoped credentials, query allowlists, tenant enforcement, result redaction, row limits, audit logs, and write operations only through migrations/commands.Deploy button riskA polished deploy UI can make dangerous deploys feel routine. Without policy gates, it centralizes blast radius.Dry-run first, environment locks, required tests, migration checks, approvals, rollback plan, health checks, and explicit production capability grants.Agent authorityAgents that can propose or apply changes become privileged contributors. Their mistakes can be subtle and pass shallow UI tests.Read-only scouting at first. Later, constrained command types, deterministic validators, mandatory diff review, source ownership checks, and test gates.Audit gapsA control plane without a complete audit trail cannot be trusted after an incident.Every read of sensitive data, every command, every deploy, every auth change, every agent action, and every secret check must produce immutable audit records. ## Red-line rule Section ID: red-line-rule Red-line rule Do not allow the workbench to mutate production code, data, auth, or deploy state until it can prove who initiated the action, what capability authorized it, what exact diff or query ran, what tests guarded it, how to revert it, and where the audit record lives. ## 5. Agents And Command Queue Critique Section ID: 5-agents-and-command-queue-critique 5. Agents And Command Queue Critique The command queue is the most important idea in the agent story, but it is not automatically safe. A queue can serialize bad ideas as efficiently as good ones. ## Command shape is not semantic safety Section ID: command-shape-is-not-semantic-safety Command shape is not semantic safety A typed command like ConnectPortsCommand can be syntactically valid and still be architecturally wrong. The validator needs domain checks, not just schema checks. ## Agent scouting can become noise Section ID: agent-scouting-can-become-noise Agent scouting can become noise Gemini-style codebase scouting for dead code, coverage, inefficiencies, and harness tightening is useful only if findings are deduplicated, ranked, reproducible, and tied to commands/tests. ## Commit linkage can create false confidence Section ID: commit-linkage-can-create-false-confidence Commit linkage can create false confidence Showing which commit followed which commands is necessary, but not sufficient. The UI also needs to show uncommitted drift, failed commands, reverted commands, and tests skipped. ## Hard questions for the agent model Section ID: hard-questions-for-the-agent-model Hard questions for the agent model QuestionWhy it is uncomfortableGood answerWho owns a command authored by an AI agent?Blame and review cannot be delegated to a model. Production changes need accountable human ownership.Every agent command has a human approver, source owner, and audit actor distinct from model identity.Can an agent make changes outside the graph abstraction?Many important changes are not graph nodes: build scripts, secrets, migrations, tests, CI, native code, generated artifacts.Commands must support non-graph scopes explicitly, or the UI must admit those changes are outside Reaktor's safe edit model.What happens when a command partially applies?Real code edits can leave build output, generated files, lockfiles, and DB migrations out of sync.Command application must be transactional at the worktree level, with rollback and dirty-state detection.Can scout jobs see secrets or private production data?Broad codebase scans can collect sensitive config, logs, or environment output.Read scopes, path allowlists, secret redaction, and result filtering are required before scout jobs run automatically.How are duplicate or contradictory agent proposals handled?Codex, Claude, Gemini, and human commands may overlap or conflict.Queue-level conflict detection using file ownership, graph entity IDs, migration targets, and source spans. ## 6. Testing Critique Section ID: 6-testing-critique 6. Testing Critique Playwright and Maestro are appropriate tools, but UI test quantity is not the same as correctness. The risk is building a large suite that proves the facade stays clickable while the real system remains unverified. Testing claimCritical responseBetter standard"Every tab and flow has Playwright coverage."This can still test static scenario data. It proves rendering and crash-free behavior, not integration truth.Tests must run against live or recorded production-shaped API fixtures generated from the same manifest builder."Maestro covers mobile-like web flows."Maestro can exercise browser/device workflows indirectly, but it is not a replacement for browser-native assertions, network mocking, accessibility checks, and visual regression.Use Playwright for web correctness and Maestro where it adds cross-device or app-shell value. Do not force one tool to own everything."Regression tests protect command execution."Tests that run after a command are only useful if the command-to-test mapping is correct and failure blocks apply/deploy.Affected-test mapping must be part of the manifest. Unknown impact should widen the test set, not skip tests."Crash-free is production-ready."Crash-free is the floor. A control plane can be crash-free and still authorize the wrong user, leak data, deploy the wrong artifact, or show stale graph state.Add security, freshness, audit, stale-state, concurrency, permission, and rollback tests."Mock data lets us test all states."Mock data can encode false assumptions. It often tests what designers expect, not what systems produce.Recorded fixtures should be generated from real services and schema-versioned. Hand-authored mocks should be labeled design-only. ## Tests the critic would require before expanding scope Section ID: tests-the-critic-would-require-before-expanding-scope Tests the critic would require before expanding scope Manifest freshness test: source/runtime change appears in the workbench without hand-editing scenario files. Auth negative tests: invalid token, expired token, wrong audience, missing scope, and cross-tenant access fail everywhere. Command rollback test: failed command leaves the worktree, manifest, queue, and UI in a consistent state. Deploy dry-run test: production deploy cannot start with failing tests, missing secrets, or pending migrations. DB redaction test: sensitive fields are masked in the UI and never appear in logs. Agent scout reproducibility test: the same input produces a stable finding ID and no duplicate queue spam. ## 7. Product And Adoption Risk Section ID: 7-product-and-adoption-risk 7. Product And Adoption Risk ## The buyer may not exist yet Section ID: the-buyer-may-not-exist-yet The buyer may not exist yet It is unclear whether Reaktor is primarily an internal development workbench, a framework for building apps, a low-code/visual architecture tool, an AI engineering control plane, or an observability/deploy console. Each buyer has different willingness to adopt a new runtime. ## The adoption cost is high Section ID: the-adoption-cost-is-high The adoption cost is high To get the full value, teams may need to adopt graph nodes, ports, Feature slots, typed service contracts, command queues, telemetry conventions, and deploy adapters. That is a lot before value is obvious. ## Existing toolchains are good enough in pieces Section ID: existing-toolchains-are-good-enough-in-pieces Existing toolchains are good enough in pieces IDE search, GitHub, CI, Datadog-style observability, Backstage-style catalogs, Postman-style API tools, deploy dashboards, and DB consoles already solve parts of this. Reaktor must prove the integration is worth switching costs. ## Dogfood can mislead Section ID: dogfood-can-mislead Dogfood can mislead BestBuds can prove Reaktor works for the author's architecture, but it may not prove broader market fit. A second app or external repo should eventually validate that Reaktor can model unfamiliar systems. ## Positioning critique Section ID: positioning-critique Positioning critique Possible positioningCritic's concernSharper versionFrameworkFrameworks compete on simplicity, stability, docs, ecosystem, and migration path. Reaktor is currently too broad and internally evolving."A graph runtime for KMP apps with typed service and port introspection."WorkbenchA workbench without a stable runtime contract becomes a UI chasing internal implementation details."A read-only graph and trace explorer for Reaktor apps, with safe commands later."AI coding control planeThis is the highest-risk and most crowded framing. It also requires strong command validation and trust infrastructure."A constrained command queue where agents can propose changes against a live app manifest."Internal platformInternal tools can tolerate rough edges, but that may hide product weaknesses."Dogfood-only until one BestBuds flow is objectively easier to operate through Reaktor." ## 8. Safer Narrow Path Section ID: 8-safer-narrow-path 8. Safer Narrow Path The critic is not saying "stop." The critic is saying "compress the ambition into a proof that can fail." If the proof succeeds, the broader roadmap becomes much more credible. ## Recommended constraint Section ID: recommended-constraint Recommended constraint :::note For the next milestone, Reaktor should be read-only except for one low-risk command type. The workbench should focus on truth, traceability, and trust before edit power. ::: MilestoneScopeProof requiredDo not do yet1. Live manifestBestBuds graph, routes, nodes, ports, services, stores, source paths, tests, deploy targets.Graph/Search/Drawer render from /workbench/apps/{appId}/manifest; static scenarios are test fixtures only.Do not build DB editing, auth editing, deploy execution, or agent writes.2. One traced flowBestBuds chat send or login flow.Trace includes UI event, route, node, interactor, cache, service, worker, DB, telemetry, and tests.Do not trace every route until one trace is complete and trusted.3. Security baselineWorker auth, token verification, redaction, audit skeleton, secret scanning.Negative auth tests pass and sensitive data cannot be displayed or logged by default.Do not expose production DB or deploy actions.4. Command previewOne safe command, such as adding metadata or generating a test stub.Preview, apply, rollback, tests, and commit linkage work in an isolated worktree.Do not let agents apply arbitrary diffs.5. Read-only deploy and DBCatalogs, status, dry-runs, schema introspection, redacted sample reads.No direct production writes; all sensitive access audited.Do not add write consoles or one-click production deploy. ## Kill criteria Section ID: kill-criteria Kill criteria If the workbench cannot generate a live manifest without hand-authored scenario data, pause UI expansion. If source mapping remains unreliable, do not implement agent writes or command apply. If worker auth and signed identity are not enforced, do not expose production service controls. If one traced flow cannot beat normal IDE/log/test debugging, reconsider the value proposition. If every new feature requires bespoke adapters and exceptions, reduce the abstraction surface. ## Most constructive critique Section ID: most-constructive-critique Most constructive critique Reaktor should stop trying to prove that the whole future exists. It should prove that one real BestBuds flow becomes explainable, testable, and safely changeable in a way that normal tools do not match. That proof would make the rest of the roadmap much easier to believe. This review is intentionally adversarial. It is meant to strengthen execution by identifying where the roadmap could overreach, not to dismiss the underlying idea. ## Related docs Section ID: related-docs Related docs Claude Critic - Use as a second-opinion and adoption-risk check. Competitive Landscape - Use when clarifying Reaktor's graph-native differentiation, competitor pressure, and where to integrate instead of compete. Strategic Roadmap - Use for strategic framing and product sequencing. Codex Roadmap - Read first when deciding what must become real and in what order. Mega-Scale Strategy - Use for enterprise-adoption strategy, the open-source vs commercial split, and sequencing the distributed-tier roadmap without diluting the single-threaded-actor core. Framework Overview - Use to understand the full Reaktor model before diving into graph, visitors, modules, control plane, or subsystem docs. # Codex Dev Environment URL: https://reaktor.build/docs/codex-dev-environment Status: historical Content revision: 45e48f440f4b6aa4411381f536db057dc87b5c63b7b9b9ec7e435be7764ae424 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/codex-dev-environment","polarity":"Neutral"},{"id":"section-summary","anchor":"summary","label":"1. Summary","profile":"section","contract":"https://reaktor.build/docs/codex-dev-environment#summary","polarity":"Neutral"},{"id":"section-spec-alignment","anchor":"spec-alignment","label":"2. Spec alignment","profile":"section","contract":"https://reaktor.build/docs/codex-dev-environment#spec-alignment","polarity":"Neutral"},{"id":"section-target-shape","anchor":"target-shape","label":"3. Target shape","profile":"section","contract":"https://reaktor.build/docs/codex-dev-environment#target-shape","polarity":"Neutral"},{"id":"section-capture-plane","anchor":"capture-plane","label":"4. Capture plane","profile":"section","contract":"https://reaktor.build/docs/codex-dev-environment#capture-plane","polarity":"Neutral"},{"id":"section-data-plane","anchor":"data-plane","label":"5. Data plane","profile":"section","contract":"https://reaktor.build/docs/codex-dev-environment#data-plane","polarity":"Neutral"},{"id":"section-shadow-capsules","anchor":"shadow-capsules","label":"6. Shadow capsules","profile":"section","contract":"https://reaktor.build/docs/codex-dev-environment#shadow-capsules","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/codex-dev-environment#related-docs","polarity":"Neutral"}],"relations":[{"id":"codex-dev-environment:references-shadow-dev-environment","kind":"references","owner":"codex-dev-environment","incidences":[{"node":"codex-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"shadow-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"codex-dev-environment:references-operations","kind":"references","owner":"codex-dev-environment","incidences":[{"node":"codex-dev-environment","port":"page","role":"source","ordinal":0},{"node":"operations","port":"page","role":"target","ordinal":0}]},{"id":"codex-dev-environment:references-claude-dev-environment","kind":"references","owner":"codex-dev-environment","incidences":[{"node":"codex-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"claude-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"codex-dev-environment:references-performance-observability","kind":"references","owner":"codex-dev-environment","incidences":[{"node":"codex-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"performance-observability","port":"page","role":"target","ordinal":0}]},{"id":"codex-dev-environment:references-secrets-management","kind":"references","owner":"codex-dev-environment","incidences":[{"node":"codex-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"secrets-management","port":"page","role":"target","ordinal":0}]},{"id":"codex-dev-environment:references-reaktor-devops","kind":"references","owner":"codex-dev-environment","incidences":[{"node":"codex-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-devops","port":"page","role":"target","ordinal":0}]},{"id":"codex-dev-environment:references-flexbuffer-improvement-plan","kind":"references","owner":"codex-dev-environment","incidences":[{"node":"codex-dev-environment","port":"section-related-docs","role":"source","ordinal":0},{"node":"flexbuffer-improvement-plan","port":"page","role":"target","ordinal":0}]}]} ## Codex Dev Environment Section ID: preamble Historical proposal. Read Reaktor Shadow for the current textbook direction and Operations & Reliability for the reconciled source state. This draft's capsule/environment ideas are retained as history; they do not establish shipped materialization, universal replay or permanent retention. Design for a BestBuds/Reaktor development environment that is continuously refreshed from production-shaped data and traffic while staying safe, redacted, replayable, and resettable. Author Codex Date 2026-05-28 Scope Supabase, Cloudflare D1, Workers, Durable Objects, R2, Memgraph, server APIs Status Design proposal ## 1. Summary Section ID: summary 1. Summary The development environment should not be a hand-maintained mock universe. It should be a moving shadow of production: the latest active traffic and data, plus a curated library of rare crashes, slow paths, invalid payloads, data-shape surprises, and incident traces that must never regress again. The right abstraction is reaktor-shadow: an application-layer capture, materialization, and replay system. Keploy remains a useful runner for HTTP-style regression tests, but Reaktor should capture above raw HTTP so one trace can include a Worker request, service handler, D1 query, Durable Object message, R2 object reference, Supabase row closure, Memgraph subgraph, queue event, and downstream server response. ## Moving window Section ID: moving-window Moving window Keep a rolling 7-day active dataset generated from real traffic, recently touched entities, and dependency closures. ## Pinned anomalies Section ID: pinned-anomalies Pinned anomalies Preserve crash, timeout, DLQ, auth, media, graph, and high-latency capsules beyond the moving window until they are fixed and covered. ## Writable overlays Section ID: writable-overlays Writable overlays Developers and CI write only to disposable overlays. The golden shadow snapshot is immutable and can be recreated every day. :::tip Definition of done: a developer can run ./shadow env pull rolling-7d, boot BestBuds against the shadow bindings, replay the last week of representative traffic plus pinned anomalies, and load test at 1x/2x/5x without touching production. ::: ## 2. Spec alignment Section ID: spec-alignment 2. Spec alignment The Reaktor spec places reaktor-shadow in the tooling layer and intelligence/tooling plane. It calls for application-layer production traffic capture, local/CI replay, graph-community-scoped regression matrices, visual snapshot diffing, Keploy integration, and k6/Gatling load generation from captured traffic patterns. Spec conceptConcrete interpretation for BestBudsreaktor-shadowOwns capture manifests, redaction, resource dependency closure, replay fixtures, and shadow environment hydration.Application-layer captureCapture typed Service envelopes and graph events, not raw packets. The same envelope works on Spring, Workers, queues, Pub/Sub, WebSocket, and Durable Object messages.Keploy-style regressionKeploy can replay HTTP captures, but Reaktor wraps it with service-aware fixtures and response comparators that understand allowed drift.Graphify community scopingA change in chat nodes replays chat community traffic first; auth, media, notification, and campaign capsules run only when impacted or on nightly builds.Performance section 29k6/Gatling scripts are generated from captured rates, payload sizes, and route mixes. CI can replay at 1x/2x/5x against the shadow environment. ## 3. Target shape Section ID: target-shape 3. Target shape Production Workers / Spring / DO / D1 / R2 / Supabase / Memgraph / Queues | | application-layer capture + resource references + redaction v Shadow Lake R2 raw bodies + trace artifacts D1/Postgres catalog index pinned capsule registry graph/community labels from reaktor-graphify | | nightly + on-demand materializers v Shadow Environments shadow-current rolling 7-day moving window shadow-pinned/* incident/anomaly capsules shadow-pr- ephemeral CI overlay shadow-local- developer overlay | | replay + load + UI + workbench v Tests, local dev, Reaktor Desktop, CI gates, agent diagnosis ## Environment classes Section ID: target-shape-2 Environment classes EnvironmentPurposeMutation policyLifetimeshadow-currentDefault shared dev baseline, built from latest active production traffic.Read-only base plus resettable overlay.Rebuilt daily or every 6 hours when traffic grows.shadow-pinnedCurated anomaly and incident corpus.Immutable capsules; overlays for replay.180 days by default, longer for unresolved incidents.shadow-pr-CI and load-test target for a branch.Disposable write overlay.Destroyed after PR close or 48 hours.shadow-local-Developer sandbox with realistic data.Disposable write overlay.Self-service recreate. ## 4. Capture plane Section ID: capture-plane 4. Capture plane Capture should happen at the same typed boundary the app already uses: Reaktor service handlers, graph actions, repository calls, bus envelopes, and actor/worker messages. Raw HTTP capture is not enough because BestBuds spans Cloudflare Workers, Durable Objects, queues, R2, Supabase/Postgres, Memgraph, and JVM services. ## Shadow envelope Section ID: capture-plane-2 Shadow envelope { "schemaVersion": "reaktor.shadow.v1", "captureId": "sha256(traceId + spanId + route + capturedAt)", "traceId": "00-...", "capturedAt": "2026-05-28T10:30:00Z", "source": { "env": "prod", "service": "messaging-service", "runtime": "cloudflare-worker" }, "route": { "method": "POST", "pattern": "/messages/{chatId}", "transport": "HTTP" }, "graph": { "appId": "bestbuds", "nodeId": "ChatInteractor", "community": "chat" }, "request": { "headersAllowlist": { "traceparent": "...", "x-app-build": "..." }, "bodyRef": "r2://shadow-raw/2026/05/28/body.req.flex", "redaction": "policy:user-content-v1" }, "response": { "status": 200, "bodyRef": "r2://shadow-raw/2026/05/28/body.res.flex", "comparator": "json-shape-and-stable-fields" }, "resources": [ { "type": "supabase", "table": "messages", "keys": ["msg_..."], "mode": "read-write" }, { "type": "durable-object", "class": "ChatRoom", "idHash": "room_...", "snapshotRef": "r2://..." }, { "type": "r2", "bucket": "media", "keyHash": "img_...", "transform": "thumbnail-or-placeholder" } ], "timing": { "durationMs": 84, "dbMs": 22, "workerCpuMs": 8 }, "classification": { "sample": "rolling", "anomalyScore": 0.12, "retention": "7d" } } ## Capture adapters Section ID: capture-plane-3 Capture adapters SurfaceCapture hookWhat to storeWhat not to storeCloudflare WorkerstracedHandler() / Service.toHono() wrapperRoute pattern, status, timing, sanitized request/response, binding names, subrequest count, Worker CPU.Raw cookies, auth tokens, full IPs, secret bindings.Durable ObjectsActor mailbox wrapper plus periodic admin snapshot endpointMessages, alarms, state snapshot refs, storage operation counts, WebSocket events.Unredacted room text or user identity outside policy.D1Query wrapper around typed D1 bindingParameterized SQL template hash, row keys, changed row ids, timing, error class.SQL with substituted literals, unbounded result sets.R2Object access wrapperObject key hash, content type, size, transform policy, thumbnail/generated placeholder refs.Original private media unless explicitly approved.Supabase/PostgresService repository instrumentation plus logical export jobTable row ids, FK closure, query hash, pg_stat statement hash, sanitized row snapshot.Credentials, raw PII, full unrelated tenant tables.Memgraph on GCP CEGraphDb wrapper plus Cypher export jobTouched nodes/edges, query templates, route/community labels, compact subgraph export.Full graph dump unless needed for a pinned incident.Server APIsOtelServiceInterceptor plus ShadowServiceInterceptorTyped request/response envelopes, dependency refs, response comparator, graph node attribution.Plaintext secrets, bearer tokens, personal headers. ## 5. Data plane Section ID: data-plane 5. Data plane The shadow environment needs data closure, not a blind production clone. A captured trace is useful only if the rows, objects, graph nodes, Durable Object state, and feature flags it depends on can be materialized together. ## Resource materializers Section ID: data-plane-2 Resource materializers Production sourceShadow targetMaterialization strategySupabase/PostgresShadow Supabase project or Postgres schemaExport rows touched in the rolling window plus FK closure. Tokenize user identity, preserve referential integrity, store base snapshot as immutable schema and developer writes in overlay schema.Cloudflare D1Shadow D1 database per environmentUse scheduled export/backup and row filters keyed by trace resource refs. Recreate daily; apply pinned capsule migrations on top.Durable ObjectsShadow DO namespaceAdd explicit snapshot/restore command per DO class. Snapshots write to R2 and restore into a shadow namespace. If a DO cannot snapshot, replay its mailbox log from the capsule.R2Shadow R2 bucketCopy safe objects, generate placeholders for sensitive media, preserve metadata and object sizes when performance behavior depends on it.MemgraphShadow Memgraph on GCP CE or local containerCypher export of touched subgraphs plus anomaly subgraphs. Keep tenant labels, replace direct user fields, rebuild indexes before replay.Workers secrets/configGCP Secret Manager + Wrangler env secretsUse non-prod credentials and provider sandboxes. No production token is captured into shadow. :::warning Important: the shadow dataset is production-shaped, not production-identical. The goal is preserving behavior, topology, cardinality, route mix, and failure modes while stripping identity, secrets, and unnecessary private payloads. ::: ## Base plus overlay Section ID: data-plane-3 Base plus overlay shadow-current-base-2026-05-28 supabase_base schema immutable sanitized rows d1_base database immutable export r2_base bucket prefix copied/transformed objects memgraph_base imported subgraph do_base snapshots per-class snapshot refs shadow-local-ovd supabase_overlay schema developer writes d1_overlay database developer writes r2_overlay prefix new objects memgraph_overlay local changes do_overlay namespace actor state mutations ## 6. Shadow capsules Section ID: shadow-capsules 6. Shadow capsules A shadow capsule is the unit of replay. It packages traffic, resource closure, expected outcomes, comparators, and retention metadata. Rolling capsules expire quickly. Pinned capsules preserve incidents and weird edge cases. ## Capsule taxonomy Section ID: shadow-capsules-2 Capsule taxonomy ClassTriggerRetentionReplay cadenceRollingRepresentative successful traffic from the latest 7 days, sampled by route/community/user segment.7 days hot, replaced continuously.Local smoke, nightly, selected PRs.LatencyP95/P99 route spike, slow query, Worker CPU warning, Memgraph slow Cypher.30 days or until budget covered.Performance PRs, nightly load.Crash5xx, uncaught exception, mobile crash breadcrumb, Durable Object panic, queue DLQ.180 days minimum.Every PR touching the graph community.AnomalyRare data shape, invalid payload, auth-provider edge case, media object mismatch, graph disconnected component.Until explicitly retired.Community-scoped PR replay.IncidentHuman-pinned production bug, support ticket, Grafana alert, deploy rollback.Until postmortem action closes.Release gate and regression suite. ## Pinning rules Section ID: shadow-capsules-3 Pinning rules Pin any trace with 5xx, timeout, retry exhaustion, DLQ write, crash breadcrumb, auth rejection after valid input, media upload failure, or data-integrity violation. Pin any trace whose latency is above route budget by 2x or is in the top 0.5% for a service. Pin any trace manually linked to a support ticket, incident, customer complaint, or team debugging session. Deduplicate by route + error class + stack fingerprint + graph community + resource shape hash. Retire only after a replay test exists, passes on main for 14 days, and the owning team accepts the removal. ## 7. Materialization workflow Section ID: materialization 7. Materialization workflow Materialization converts capture refs into a runnable shadow environment. It should be deterministic, repeatable, and cheap enough to run nightly. Step 1 - Select window and capsules Select representative rolling traffic for the latest 7 days, then union pinned capsules relevant to the target environment. Partition by graph community so small PRs do not hydrate the world. Step 2 - Compute resource closure For every selected trace, walk resource refs: Supabase rows, D1 rows, Durable Object snapshots, R2 objects, Memgraph nodes/edges, feature flags, and provider stubs. Add parent rows and foreign-key dependencies. Step 3 - Redact and tokenize Apply deterministic tokenization for ids and relationship fields, synthetic replacements for direct PII, media transformations, geo bucketing, and header allowlists. Emit a redaction report with rejected fields. Step 4 - Hydrate targets Create or reset shadow Supabase/Postgres schema, D1 database, R2 prefixes, DO namespace, Memgraph instance, Workers env bindings, and non-prod secrets. Base is immutable; overlays take writes. Step 5 - Verify replay Replay a smoke subset and verify status, schema shape, stable fields, graph side effects, idempotency records, and resource writes. Publish a ShadowManifest artifact. ## Developer commands Section ID: materialization-2 Developer commands # Pull the current moving shadow into local config ./shadow env pull rolling-7d # Boot BestBuds with shadow bindings and disposable overlay ./shadow run local -- ./targets/appServer/dev.sh # Replay one incident capsule against a local branch ./shadow replay capsule incident-chat-send-timeout-2026-05-21 # Run route-mix load test generated from captured traffic ./shadow load rolling-7d --rate 2x --duration 15m # Refresh Cloudflare Worker secrets/bindings for shadow env ./shadow sync cloudflare --env shadow-current ## 8. Replay and testing Section ID: replay 8. Replay and testing Replay has two layers. Keploy-style HTTP replay verifies externally visible API behavior. Reaktor replay verifies the full service graph, including non-HTTP work: Durable Object state transitions, queue messages, Pub/Sub events, R2 writes, Memgraph mutations, and repository side effects. RunnerInputChecksUsed inKeployHTTP request/response envelopes generated from ShadowEnvelope.Status, body shape, stable fields, error class, latency baseline.PR API regression.Reaktor service replayTyped ServiceRequest plus dependency capsule.Handler output, repository reads/writes, idempotency, telemetry spans, graph node attribution.Local, CI, workbench.Durable Object replayMailbox log or object snapshot plus messages.State transition, alarms, WebSocket fanout, storage ops.Chat/realtime regressions.k6/GatlingRoute mix, payload sizes, concurrency, think time from rolling traffic.Throughput, P95/P99, error rate, resource saturation.Nightly and release gates.Playwright/MaestroUser journeys bound to shadow accounts and graph routes.Crash-free UI, route state, visual snapshots, accessibility, app vitals.Feature PRs and smoke tests. ## Response comparison policy Section ID: replay-2 Response comparison policy Strict: deterministic internal service outputs, schema migrations, idempotency records, auth decisions. Shape plus stable fields: API responses with generated ids, timestamps, signed URLs, pagination cursors. Statistical: load-test latency, fanout count, retry distribution, Worker CPU, Memgraph query timing. Side-effect: R2 object created, D1 row inserted, DO state changed, notification attempt classified. ## 9. Workbench integration Section ID: workbench 9. Workbench integration The Reaktor workbench should make the shadow environment visible and usable. It should not only show dashboards; it should let developers select a graph community, inspect captured traces, hydrate a shadow dataset, replay a capsule, and see the exact graph nodes and resources involved. Workbench surfaceShadow featureRun AppLaunch BestBuds against shadow-current, selected pinned capsule, or a PR overlay.GraphColor nodes by captured traffic volume, replay failures, latency deltas, and pinned anomalies.DatabaseBrowse only shadow Supabase/D1/R2/Memgraph/DO data, with redaction badges and source trace refs.TestsShow capsules as test inventory: rolling, latency, crash, anomaly, incident. Run scoped replay from UI.InsightsDisplay route mix, drift from production, anomaly fingerprints, and replay history.DeployBlock release until impacted shadow capsules pass and latency drift is within budget. ## 10. Security and governance Section ID: security 10. Security and governance :::danger Hard boundary: no production credentials, tokens, cookies, raw private media, direct user identifiers, or unredacted personal fields enter the shadow environment. ::: ## Redaction contract Section ID: security-2 Redaction contract Data classShadow handlingUser identityDeterministic pseudonymous ids; optional test-user mapping for login flows. No prod auth tokens.Email, phone, display nameSynthetic replacements with stable shape and locale where needed.Free text messagesPolicy decision: redact by default, preserve only approved bug capsules with irreversible tokenization.MediaGenerated placeholder, blurred thumbnail, or synthetic object with same size/content type.LocationCoarse geohash or region bucket; never exact coordinates unless generated.Secrets and headersAllowlist trace/build/debug headers only. Everything else dropped or hashed.Deletion requestsDelete from rolling store and pinned capsules unless a legal hold exists; maintain tombstone index. ## Access model Section ID: security-3 Access model Developers get read access to shadow data and write access only to their overlays. Production capture service has write-only access to raw shadow lake and no read access to developer overlays. Materializers run as service principals with explicit scopes for Supabase export, D1 export, R2 copy, DO snapshot, and Memgraph export. Every capsule read, hydrate, replay, and export emits an audit record. All shadow secrets live in GCP Secret Manager and are synced to Cloudflare Worker shadow environments as non-prod secrets. ## 11. Rollout plan Section ID: rollout 11. Rollout plan Phase 0 - Policy and schemas Define ShadowEnvelope, ShadowResourceRef, ShadowCapsule, redaction policies, retention classes, access roles, and comparator types. Phase 1 - Service capture Add ShadowServiceInterceptor to server APIs and Worker service wrappers. Capture route pattern, request/response shape, timing, graph node id, and resource refs. Phase 2 - Shadow lake and catalog Write raw sanitized bodies to R2, index envelopes in D1/Postgres, expose catalog queries by time, route, service, graph community, and anomaly fingerprint. Phase 3 - Data materializers Implement Supabase row closure, D1 snapshot import, R2 copy/transform, Durable Object snapshot/restore, and Memgraph subgraph export/import. Phase 4 - Replay runners Build Reaktor replay runner, Keploy adapter, k6 generator, response comparators, side-effect checkers, and report artifacts. Phase 5 - Dev and CI integration Add ./shadow CLI, PR overlays, GitHub Actions workflow, workbench panels, and release gates. ## 12. Risks and mitigations Section ID: risks 12. Risks and mitigations RiskMitigationPII leaks into devFail-closed redaction policy, field classifiers, denylisted headers, automated scans before materialization, audit logs for capsule access.Shadow accidentally writes to productionSeparate credentials, separate Cloudflare envs, separate Supabase/D1/R2/DO/Memgraph targets, network egress guardrails, write-block tests.Durable Object state is not enumerableAdd explicit snapshot endpoints and mailbox logging per DO class; use replay from mailbox when snapshots are unavailable.Dataset becomes too expensiveRolling 7-day default, sampled success traffic, pinned anomaly dedupe, R2 lifecycle rules, materialize by graph community.Replay is nondeterministicFreeze clocks, stub third-party providers, compare allowed drift, seed ids, preserve idempotency keys, record dependency responses.Schema drift breaks old capsulesVersion every envelope and capsule, run migration adapters, mark un-migratable capsules as archived but inspectable.Developers distrust the environmentPublish freshness, source traffic window, replay pass rate, redaction report, and drift score in the workbench. ## Open decisions Section ID: risks-2 Open decisions Whether the shadow catalog index lives in D1, Postgres, or both. How much free-text chat content can be safely preserved after tokenization. Whether every PR gets a full overlay or only graph-community overlays. Whether Memgraph shadow runs on the existing GCP CE host, a second CE host, or local containers for developer mode. Whether Keploy is embedded as the HTTP runner only, or exposed directly to developers as a first-class tool. ## Related docs Section ID: related-docs Related docs Shadow Dev - Use before building production-like test and replay environments. Claude Dev Env - Use only when comparing prior shadow environment proposals. Perf and Observability - Use before optimizing or adding instrumentation. Reaktor Secrets - Use before moving, rotating, distributing, caching, or materializing secrets. DevOps - Use before changing the build/deploy/ops pipeline, the Kotlin platform model, deployment partitioning, gated deploy operations, or the reaktorDesktop Deploy pane; pairs with reaktor-cloud-pane (operator view) and secrets-management. FlexBuffer Plan - Use for history only; prefer the FlexBuffer Binary Serialization document. # Codex Nexergy Energy on Reaktor URL: https://reaktor.build/docs/codex-nexergy-appweb-analysis Status: unverified Content revision: 6234610da8e3cbd099a8d7df3417a9d1435b722806eeb79d40cc49135393badd Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis","polarity":"Neutral"},{"id":"section-1-high-level-platform-design","anchor":"1-high-level-platform-design","label":"1. High-Level Platform Design","profile":"section","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis#1-high-level-platform-design","polarity":"Neutral"},{"id":"section-2-market-scan","anchor":"2-market-scan","label":"2. Market Scan","profile":"section","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis#2-market-scan","polarity":"Neutral"},{"id":"section-3-commerce-operating-model","anchor":"3-commerce-operating-model","label":"3. Commerce Operating Model","profile":"section","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis#3-commerce-operating-model","polarity":"Neutral"},{"id":"section-4-product-invariants","anchor":"4-product-invariants","label":"4. Product Invariants","profile":"section","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis#4-product-invariants","polarity":"Neutral"},{"id":"section-5-module-targeting","anchor":"5-module-targeting","label":"5. Module Targeting","profile":"section","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis#5-module-targeting","polarity":"Neutral"},{"id":"section-6-the-reaktor-commerce-substrate","anchor":"6-the-reaktor-commerce-substrate","label":"6. The Reaktor Commerce Substrate","profile":"section","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis#6-the-reaktor-commerce-substrate","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/codex-nexergy-appweb-analysis#related-docs","polarity":"Neutral"}],"relations":[{"id":"codex-nexergy-appweb-analysis:references-claude-nexergy-appweb-analysis","kind":"references","owner":"codex-nexergy-appweb-analysis","incidences":[{"node":"codex-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"claude-nexergy-appweb-analysis","port":"page","role":"target","ordinal":0}]},{"id":"codex-nexergy-appweb-analysis:references-reaktor-service","kind":"references","owner":"codex-nexergy-appweb-analysis","incidences":[{"node":"codex-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"codex-nexergy-appweb-analysis:references-reaktor-db","kind":"references","owner":"codex-nexergy-appweb-analysis","incidences":[{"node":"codex-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-db","port":"page","role":"target","ordinal":0}]},{"id":"codex-nexergy-appweb-analysis:references-reaktor-work","kind":"references","owner":"codex-nexergy-appweb-analysis","incidences":[{"node":"codex-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"codex-nexergy-appweb-analysis:references-reaktor-surface-design-and-ownership","kind":"references","owner":"codex-nexergy-appweb-analysis","incidences":[{"node":"codex-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-surface-design-and-ownership","port":"page","role":"target","ordinal":0}]},{"id":"codex-nexergy-appweb-analysis:references-reaktor-surface-renderers","kind":"references","owner":"codex-nexergy-appweb-analysis","incidences":[{"node":"codex-nexergy-appweb-analysis","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-surface-renderers","port":"page","role":"target","ordinal":0}]}]} ## Codex Nexergy Energy on Reaktor Section ID: preamble This is the target architecture for Nexergy Energy on Reaktor. Nexergy Energy is the platform itself: a real trader-aggregator startup and operating business. It assumes Reaktor itself is feature complete enough for Nexergy: graph workflows, service transports, auth, multitenancy, actors, bus, work, storage adapters, media, notifications, telemetry, deployment, workbench inspection, and graph visitors are available. This document is not a Reaktor backlog. It is the product and module architecture for Nexergy Energy. The product features remain: public lead capture, buyer onboarding, RFQs, quotes, purchase orders, OMS, WMS, LMS/TMS, payments, settlements, supplier management, sustainability reporting, internal operations, analytics, and audit trails. The implementation model is Reaktor-native: reusable full-stack modules plus graph wiring. The rule stays strict: do not create reaktor-biomass or reaktor-nexergy. Biomass is Nexergy Energy product configuration: material taxonomy, quality specs, cluster geography, supplier anonymity, margin policy, sustainability formulas, and operating playbooks. Reaktor gets generic modules because that is how the engine stays coherent; Nexergy Energy remains the actual platform being built. Think of Reaktor as the Unreal-style engine under Nexergy Energy. The Reaktor modules are durable engine systems. Nexergy Energy wires those systems into one trader-aggregator platform. ## 1. High-Level Platform Design Section ID: 1-high-level-platform-design 1. High-Level Platform Design Nexergy Energy should be understood as one operating platform with multiple surfaces over one set of authoritative facts. The surfaces are product graphs. The subsystems are service-backed operating domains. The reusable Reaktor modules are the engine substrate underneath them. External users and channels Guest site | Buyer portal | WhatsApp/API | Internal ops | Supplier ops | Warehouse | Logistics | Finance/Admin | Nexergy Energy platform graphs PublicGraph | BuyerGraph | OpsGraph | SupplierOpsGraph | WarehouseGraph | LogisticsGraph | FinanceGraph | AdminGraph | Operating subsystems Demand/CRM -> Party/KYC -> Catalog/PIM -> RFQ/Quote/Pricing -> Contract/OMS/PO Procurement -> Inventory/WMS/QC -> Fulfillment -> Logistics/LMS/TMS -> POD/Claims Finance/AR/AP/Tax -> Payments/Settlement -> Credit/Working Capital -> Sustainability/Traceability Documents/Evidence -> Audit/Compliance/Policy -> Integrations -> Notifications -> Reporting | Reaktor engine substrate graph/workflows | service/server | commerce | inventory | logistics | ledger | auth/tenant | db/media/bus/work | Runtime and data authority Postgres/Hyperdrive | D1/Durable Objects | R2 | queues/pubsub | analytics/search | Cloudflare/JVM targets The subsystem map is: Subsystem What it owns for Nexergy Energy Primary Reaktor substrate Channel and experience surfaces Public site, buyer portal, ops console, supplier intake, warehouse desk, logistics desk, finance/admin surfaces. reaktor-graph, reaktor-service, reaktor-auth Demand and CRM Lead capture, contact routing, qualification, buyer onboarding, RFQ conversion, campaign/source attribution. reaktor-commerce, reaktor-notifications, reaktor-ledger Identity, tenant, party, and KYC Buyer orgs, plants, suppliers, carriers, financiers, contacts, GST/KYC, tenant scopes, roles, redaction boundaries. reaktor-auth, reaktor-multitenancy, reaktor-commerce Catalog, PIM, and material specs Biomass material taxonomy, grades, units, GCV/ash/moisture attributes, packaging, substitutions, buyer-visible projections. reaktor-commerce, reaktor-db Market intelligence and pricing Price books, quote inputs, freight estimates, margin guardrails, benchmark rates, source availability, approval thresholds. reaktor-commerce, reaktor-ledger, analytics projections RFQ and quote desk Requirement normalization, quote versions, quote approval, expiry, negotiation, buyer acceptance or rejection. reaktor-commerce, reaktor-graph, reaktor-work Contracts and standing orders Rate contracts, call-offs, reserved capacity, SLAs, amendments, penalties, buyer commitments, supplier commitments. reaktor-commerce, reaktor-ledger OMS and purchase orders Orders, splits, holds, substitutions, cancellations, buyer POs, supplier POs, promise state, claim triggers. reaktor-commerce, reaktor-graph, reaktor-ledger Procurement and supplier management Supplier contracts, source plans, capacity, internal supplier POs, backup sourcing, supplier scorecards, settlement readiness. reaktor-commerce, reaktor-inventory, reaktor-ledger Inventory, WMS, and warehouse control Stock lots, reservations, receiving, QC hold, putaway, pick/load, transfers, cycle counts, adjustments, replenishment. reaktor-inventory, reaktor-media, reaktor-ledger Quality and traceability QC evidence, lab values, certificates, acceptance/rejection, retest, origin records, traceability bundle. reaktor-commerce, reaktor-inventory, reaktor-media, reaktor-ledger Fulfillment and allocation Availability-to-promise, order allocation, source-to-stock decision, fulfillment readiness, shipment handoff. reaktor-commerce, reaktor-inventory, reaktor-logistics Logistics, LMS, and TMS Pickup/drop schedules, lanes, carriers, vehicles, drivers, tracking events, weighbridge slips, POD, freight exceptions. reaktor-logistics, reaktor-notifications, reaktor-ledger Finance, tax, and accounting spine Buyer receivables, supplier payables, invoices, credit notes, debit notes, GST/TDS artifacts, margin, reconciliation facts. reaktor-commerce, reaktor-ledger, accounting adapters Payments and settlement Payment proof, payment gateway or bank adapter events, supplier settlement release, early payment, reconciliation, payout evidence. reaktor-ledger, reaktor-commerce, reaktor-bus Credit and working capital Buyer credit limits, payment terms, credit breach approvals, supplier early payment, invoice discounting integration, risk holds. App package first, reaktor-commerce, reaktor-ledger Claims, returns, and issue resolution Quality complaint, shortage, rejection, replacement load, credit note, supplier claim, support escalation, evidence review. reaktor-commerce, reaktor-logistics, reaktor-ledger Documents, media, and evidence Contracts, buyer POs, supplier POs, invoices, QC certificates, weighbridge slips, POD photos, evidence bundles. reaktor-media, reaktor-ledger, R2 Sustainability and ESG Coal displacement, biomass usage facts, carbon estimates, certificates, ESG exports, buyer sustainability reports. App package, reaktor-ledger, analytics projections Audit, compliance, policy, and redaction Immutable command journal, approval trails, supplier anonymity, document access, retention, legal hold, replay, evidence export. reaktor-ledger, reaktor-auth, graph visitors Workflow and SLA automation RFQ timers, approval routing, retries, reminders, shipment delay handling, settlement gates, recurring exports. reaktor-graph, reaktor-work, reaktor-bus Notifications and communications Email, SMS, WhatsApp, app notifications, ops alerts, buyer status updates, supplier/internal reminders. reaktor-notifications, reaktor-bus, reaktor-work Reporting, analytics, and intelligence RFQ conversion, quote win/loss, stock turns, delivery SLA, margin leakage, supplier performance, demand forecast. reaktor-db, reaktor-ledger, analytics/search Integrations and adapters ERP, accounting, payment, bank, WhatsApp, GPS, weighbridge, carrier, tax, credit bureau, financier, BI exports. reaktor-service, reaktor-bus, reaktor-secrets Admin, configuration, and workbench Tenant setup, roles, product config, approval policy, redaction policy, graph snapshots, deploy inspection, agent review. reaktor-graph, reaktor-cloud, reaktor-secrets, workbench Runtime and data authority Authoritative relational state, edge read models, single-writer hot aggregates, documents, events, search, analytics. Postgres/Hyperdrive, D1, Durable Objects, R2, queues/pubsub The key design constraint is that these are Nexergy Energy subsystems, not one module per subsystem. Reaktor gets only the reusable primitives that make the subsystems composable: commerce, inventory, logistics, ledger, graph workflows, service contracts, auth/tenancy, media, bus, work, and storage. ## 2. Market Scan Section ID: 2-market-scan 2. Market Scan The competition confirms that biomass ecommerce is not a simple storefront. Buyers want supply assurance, quality evidence, pricing confidence, delivery control, invoices, sustainability records, and fewer coordination loops. Suppliers want demand, production planning, logistics, payments, and ledger visibility. The strongest competitors already sell pieces of this operating system. Source What they signal Reaktor implication Buyofuel Marketplace positioning, broad biofuel catalog, buyer RFQ, seller listings, trade updates, tracking, sustainability reporting, and an inventory app. Nexergy needs RFQ, catalog, tracking, inventory, and sustainability parity, but not the open seller marketplace model. Buyofuel buyers Buyers can browse inventory, raise RFQs, receive counter offers, track purchase-order dispatches, download documents, and get CO2 reports. Buyer portal must be procurement-grade: RFQ, quote, PO, order tracking, documents, and sustainability exports are table stakes. Buyofuel inventory Raw material inflow, finished product outflow, low-stock alerts, analytics, and manufacturing integration. reaktor-inventory must cover WMS plus production-adjacent stock planning, not only ecommerce stock counts. BiofuelCircle marketplace Three-sided marketplace with verified suppliers, quote comparison, delivery planning, inventory/invoice views, transport, trade finance, and supplier ledgers. Nexergy should internalize these capabilities but expose them as Nexergy-controlled projections, not direct buyer-supplier matching. BiofuelCircle supply chain as a service Direct procurement from farmers, local transport, customized storage, reverse supply chain, biomass banks, and farm-to-fuel execution. The source-to-stock and source-to-delivery paths are as important as the buyer-facing order path. BiofuelCircle Envira Quality-assured briquettes with GCV, ash, moisture, testing, origin, and traceability. Quality, traceability, and certificate primitives must be generic, then configured for biomass specs. Moglix Business Enterprise procurement, vendor management, VMI, category management, strategic cost management, supply-chain finance, P2P automation, contract optimization, custom storefronts. Nexergy needs an enterprise procurement operating spine: contracts, price books, VMI, P2P integration, cost analytics, and supplier risk. Credlix and Oxyzo PO finance, invoice discounting, vendor finance, purchase finance, buyer creditworthiness, and working-capital products. Credit and financing must be modeled now as service contracts and ledger facts, even if underwriting is integrated later. Udaan Mobile-first B2B buying with quick KYC, competitive prices, credit, fast delivery, returns, repeat orders, and delivery tracking. Buyer UX must hide operational complexity behind fast repeat procurement, delivery status, credit, and simple issue resolution. Shopify Admin API and commercetools APIs Mature commerce platforms expose products, inventory, orders, shipping/fulfillment, payments, webhooks, staged/published product projections, and inventory entries as clean resource domains. Reaktor modules should expose clean resource contracts and projections, not screens that directly own business state. The strategic difference for Nexergy Energy: competitors lean toward marketplace, managed marketplace, or procurement platform. Nexergy Energy's PRD is sharper: Nexergy is the counterparty. Buyers buy from Nexergy. Suppliers sell to Nexergy. Supplier identity is hidden. Nexergy wins by controlling supply, quality, delivery, finance, and accountability. ## 3. Commerce Operating Model Section ID: 3-commerce-operating-model 3. Commerce Operating Model Every serious ecommerce platform is a set of operating loops, not a website. Loop Typical ecommerce meaning Nexergy meaning Demand capture Search, storefront, campaign, lead, cart, RFQ Public site, WhatsApp/contact, lead, buyer onboarding, plant requirement, RFQ Catalog and PIM Product, SKU, attributes, variants, media, search, merchandising Biomass material taxonomy, specs, grade, GCV/ash/moisture bands, packaging, substitution policy Pricing and promise Price book, discount, tax, availability-to-promise, SLA Quote, margin guardrail, freight estimate, inventory/source check, delivery promise Order orchestration Order state machine, split, cancel, substitute, reserve, invoice Nexergy quote acceptance, buyer PO, order confirmation, source/reserve, invoice, SLA Procurement Vendor, supplier PO, inbound, receiving Supplier contract, procurement plan, supplier PO, pickup readiness, inbound stock, settlement WMS Receive, QC, putaway, pick, pack, load, count, adjust Cluster/hub stock, biomass QC hold, weighbridge, stock lot, reservation, dispatch readiness LMS/TMS Shipment, carrier, route, tracking, POD, freight reconciliation Trucking, pickup/drop schedule, GPS/manual events, POD, weighbridge slip, freight charge, exception Finance Payment, receivable, payable, refund, credit Buyer AR, supplier AP, margin, GST/TDS, credit limit, payment proof, settlement release Returns and claims Return, replacement, refund, RTO, warranty Quality complaint, short delivery, rejection, replacement load, credit note, supplier claim Trust and compliance Audit, fraud, policy, data retention Supplier anonymity, approval policy, immutable audit, evidence bundles, sustainability certificates Intelligence Analytics, recommendation, forecasting, experimentation RFQ conversion, price trends, stock turns, supplier score, demand forecast, margin leakage Nexergy Energy should not split these capabilities into isolated product silos. It should expose them as coherent platform surfaces backed by graph-wired recipes over reusable Reaktor modules. ## 4. Product Invariants Section ID: 4-product-invariants 4. Product Invariants The PRD defines Nexergy Energy as a hybrid trader-aggregator. The Reaktor graph must preserve that operating model. Invariant Reaktor meaning Nexergy is the counterparty Buyer-facing orders, invoices, support, and guarantees are issued by Nexergy. Supplier contracts and supplier POs are internal procurement records. External users are buyers and guests Buyer portal and public landing are external. Supplier tools are internal or tightly permissioned intake surfaces, never public seller storefronts. Supplier anonymity is mandatory Buyer-facing service responses expose cluster, quality, availability, traceability, and Nexergy assurance, not supplier identity. Inventory and supply assurance are the moat Stock control, source planning, reservations, backup suppliers, quality evidence, and delivery SLAs are first-class. Ops console is the wedge Internal ops coordinates RFQ, quote, procurement, inventory, fulfillment, finance, support, and audit before full self-serve scale. Credit is part of commerce Buyer credit, supplier early payment, settlement timing, invoice discounting, and credit breach approvals are modeled from day one. The old prototype's producer portal becomes NexergySupplierOpsGraph: internal procurement or controlled supplier intake. It is not a buyer-visible seller marketplace. ## 5. Module Targeting Section ID: 5-module-targeting 5. Module Targeting Minimize modules by extracting only generic, high-leverage primitives. OMS, WMS, LMS, procurement desk, supplier portal, buyer portal, and finance console are Nexergy Energy platform surfaces built from these modules, not framework modules themselves. Module Role Why it is a module reaktor-commerce Party, account, catalog/PIM, channel, RFQ, quote, price book, contract, order, PO, invoice, claim, approval, commerce projections. Generic trade vocabulary; Nexergy Energy uses it for trader-aggregator procurement and sales. reaktor-inventory Availability, stock lot, reservation, inventory movement, warehouse, zone/bin, WMS task, QC hold, cycle count, replenishment. Quantity truth needs strong authority and audit rules; Nexergy Energy uses it for cluster stock and supply assurance. reaktor-logistics Shipment, lane, route, carrier, vehicle, driver, tracking event, POD, freight charge, delivery exception. Movement execution needs its own authority; Nexergy Energy uses it for biomass pickup, delivery, and proof. reaktor-ledger Immutable command journal, domain event stream, audit trail, inventory ledger, finance ledger, hash chain, evidence export, replay. Audit and ledger are cross-cutting primitives; mutable rows are not enough for finance, inventory, or compliance. Existing or assumed-complete Reaktor modules carry the rest: Existing Reaktor surface Used for reaktor-graph Platform graph, workflow graph, policy graph, state machines, graph visitors, snapshots, workbench rendering. reaktor-service Typed service contracts, operation identity, clients, route mounting, service nodes. reaktor-server Idempotency, retries, circuit breakers, rate limits, outbox, service interceptors, resilience. reaktor-bus Domain events, async commands, fan-out, DLQ, idempotent consumers, integrations. reaktor-work Scheduled work, long-running jobs, recurring exports, retries, reminders, SLA timers. reaktor-auth and reaktor-multitenancy Buyer orgs, supplier scopes, internal roles, service principals, agent permissions. reaktor-db Data descriptors, relational authority, projections, sync policy, analytics stores. reaktor-media Contracts, buyer POs, supplier POs, invoices, QC certificates, weighbridge slips, POD photos, evidence bundles. reaktor-notifications Email, SMS, WhatsApp, app push, workflow notifications, ops alerts. reaktor-cloud and reaktor-secrets Cloudflare/JVM deployment, bindings, secrets, materialized infrastructure. Do not extract reaktor-finance yet. Start with finance contracts inside reaktor-commerce and immutable facts in reaktor-ledger. Extract reaktor-credit or reaktor-finance only if lending, underwriting, NBFC workflows, or multi-product financial services become a first-class platform business. ## 6. The Reaktor Commerce Substrate Section ID: 6-the-reaktor-commerce-substrate 6. The Reaktor Commerce Substrate reaktor-commerce should be small but expressive. It owns the business vocabulary of buying and selling. It does not own storage topology, UI, or domain-specific taxonomy. Primitive Notes Party Buyer, supplier, carrier, financier, internal entity, trading participant. Account Commercial account with credit terms, tax profile, billing profile, allowed channels, and contacts. Location Plant, warehouse, supplier yard, carrier hub, billing address, delivery address. CatalogItem Generic sellable item or service. Biomass briquette is app config, not a framework type. Spec Attribute schema for quality and eligibility: GCV, ash, moisture, size, grade, packaging, shelf life, compliance. Channel Buyer portal, ops console, mobile app, API, WhatsApp, internal procurement desk. PriceBook Base price, validity, tax, freight component, margin policy, customer terms, price source. RFQ Negotiated demand with specs, quantity, delivery schedule, plant, payment terms, and SLA. Quote Versioned offer with price, validity, sourcing plan, promise, and approval state. Contract Long-term supply, rate contract, standing order, reserved capacity, penalty/SLA, amendment trail. Order OMS aggregate with state, lines, splits, substitutions, cancellations, promises, holds, and external refs. PurchaseOrder Buyer PO and supplier PO are two projections, with different visibility and policy. Invoice Tax invoice, proforma, credit note, debit note, settlement invoice, payment schedule. Claim Quality claim, shortage, rejection, replacement, credit, escalation. Approval Margin override, credit breach, settlement release, QC rejection, contract change, inventory adjustment. Projection Buyer, supplier, finance, warehouse, logistics, and admin projections over the same trade facts. The module should expose DTOs, Service contracts, graph nodes, policy hooks, projection helpers, and visitors. It should not contain Nexergy words such as biomass, briquette, husk, GCV target, or Brahmapur. ## 7. Inventory and WMS Section ID: 7-inventory-and-wms 7. Inventory and WMS reaktor-inventory owns physical and logical quantity truth. Primitive Notes StockLot Quantity of a catalog item at a location with owner, status, quality state, traceability, and cost basis. Availability Sellable, reserved, committed, inbound, blocked, QC hold, damaged, expired, transferred. Reservation Temporary or firm claim on stock for quote, order, contract, transfer, or production job. InventoryMovement Append-only movement from one state/location/owner to another, backed by reaktor-ledger. Warehouse Hub, yard, store, dark store, factory, supplier yard, or partner location. WmsTask Receive, inspect, putaway, pick, pack, load, transfer, count, adjust, quarantine. QualityHold Pending QC, accepted, rejected, retest, rework, customer-specific hold. CycleCount Count plan, variance, approval, correction movement, reason code. ReplenishmentPlan Reorder point, safety stock, forecast, source plan, and replenishment recommendation. Nexergy Energy maps clusters and hubs into Warehouse and Location. Moisture, ash, fines, GCV, NCV, feedstock, packaging, grade, and certificate requirements are Spec and StockLot attributes. The module stays generic, but the platform behavior is Nexergy-specific. ## 8. Logistics and LMS/TMS Section ID: 8-logistics-and-lmstms 8. Logistics and LMS/TMS reaktor-logistics owns movement execution. Primitive Notes Shipment Delivery unit with lines, origin, destination, promised date, current state, and proof requirements. ShipmentPlan Route, vehicle type, capacity, loading window, delivery window, cost estimate, SLA. Carrier Internal fleet, transporter, 3PL, courier, rail, ocean, or app-specific partner. Vehicle and Driver Vehicle metadata, compliance docs, capacity, assignment, and driver contact policy. TrackingEvent GPS, carrier API, mobile app, WhatsApp, manual update, gate scan, weighbridge event. ProofOfDelivery Signature, photo, receiver identity, GPS pin, weighbridge slip, discrepancy note. FreightCharge Estimate, actual, surcharge, detention, demurrage, penalty, pass-through policy. LogisticsException Delay, breakdown, shortage, rejected load, route diversion, failed delivery. For Nexergy Energy this becomes plant delivery orchestration: pickup planning, truck assignment, weighbridge evidence, route tracking, POD, freight reconciliation, and delivery exceptions. ## 9. Ledger and Audit Section ID: 9-ledger-and-audit 9. Ledger and Audit reaktor-ledger is the keystone module. It is not just audit logging. It is the immutable fact system for operations, finance, inventory, replay, dispute resolution, and agent-safe changes. Ledger stream Example entries Command journal Quote.Approve invoked by actor, request hash, auth context, idempotency key, result hash. Domain event stream RFQSubmitted, QuoteAccepted, OrderConfirmed, StockReserved, ShipmentDelivered, InvoiceGenerated. Inventory ledger Inbound to QC hold, QC hold to available, available to reserved, reserved to shipped, adjustment. Finance ledger Buyer receivable, supplier payable, payment received, credit note, settlement released, margin booked. Compliance audit Supplier identity redacted, document downloaded, price override approved, credit breach approved. Minimum primitives: LedgerStream: named append-only stream per tenant, aggregate, or bounded context. LedgerEntry: event type, schema version, actor, tenant, command id, causation id, correlation id, trace id, timestamp, payload hash, previous hash. LedgerProjection: read model built from one or more streams. EvidenceBundle: exportable package for dispute, tax, compliance, audit, or investor review. RetentionPolicy: retention, legal hold, redaction, access policy, deletion exceptions. ReplayCursor: deterministic replay and projection rebuild checkpoints. Graph visitors should enforce ledger coverage: any mutating finance, inventory, approval, settlement, credit, supplier visibility, or QC operation must append the required ledger facts. ## 10. Nexergy Energy Platform Graphs Section ID: 10-nexergy-energy-platform-graphs 10. Nexergy Energy Platform Graphs Nexergy Energy is one platform composed from product graphs over the reusable modules. Graph Audience Responsibility NexergyPublicGraph Guest Marketing, material proof, lead capture, RFQ CTA, sustainability positioning, WhatsApp/contact routing. NexergyBuyerGraph Buyer org users Plants, team roles, RFQs, quotes, orders, invoices, deliveries, documents, issues, sustainability reports, repeat orders. NexergyOpsGraph Nexergy operations RFQ inbox, quote desk, procurement desk, order desk, inventory view, fulfillment desk, exceptions, approvals, audit. NexergySupplierOpsGraph Internal procurement or permissioned supplier intake Supplier contracts, capacity, inbound lots, QC docs, pickup readiness, settlement artifacts. Not buyer-facing. NexergyWarehouseGraph Hub/warehouse team Receipts, QC hold, stock lots, putaway, reservations, pick/load, transfers, cycle counts, adjustments. NexergyLogisticsGraph Logistics desk or transport partner Dispatch planning, vehicle assignment, route status, tracking events, POD, freight exceptions. NexergyFinanceGraph Finance/admin Buyer credit, invoices, receivables, payments, supplier payables, settlements, GST/TDS artifacts, margin. NexergyAdminGraph Admin/compliance Tenant policy, RBAC, approval rules, redaction rules, audit, reports, integrations, retention. These graphs are filtered projections over one source of truth. A buyer sees a Nexergy quote and a delivery promise. Ops sees the sourcing plan. Finance sees AR/AP and margin. Supplier ops sees procurement and settlement. The graph enforces which projection is legal. This is Nexergy Energy's operating system. ## 11. Service Map Section ID: 11-service-map 11. Service Map Use stable operation identities. Routes can move; operation names should stay durable graph facts. Service Module Responsibilities Example operations LeadService reaktor-commerce plus app config Public lead capture, consent, qualification, lead to buyer/RFQ conversion. Lead.Capture, Lead.Qualify, Lead.ConvertToRFQ PartyService reaktor-commerce Buyer orgs, plants, suppliers, carriers, financiers, contacts, GST/KYC, address book. Party.CreateBuyer, Party.Verify, Party.AddLocation CatalogService reaktor-commerce Product/material taxonomy, specs, grades, substitutions, buyer-visible catalog projections. Catalog.DefineItem, Catalog.PublishProjection, Catalog.Search MarketIntelService reaktor-commerce plus analytics Price trends, source availability, demand signals, benchmark rates, competitor parity. MarketIntel.PriceTrend, MarketIntel.SourceAvailability RfqService reaktor-commerce RFQ intake, requirement normalization, SLA timers, assignment, procurement-plan draft. RFQ.Submit, RFQ.Normalize, RFQ.Assign, RFQ.Close PricingService reaktor-commerce Price books, margin guardrails, freight estimate, taxes, quote approval thresholds. Price.Calculate, Price.ApproveOverride, Price.Lock QuoteService reaktor-commerce Nexergy quote, quote versions, expiry, acceptance, rejection, conversion to order. Quote.Create, Quote.Approve, Quote.Accept, Quote.Expire ContractService reaktor-commerce Rate contracts, standing orders, supply commitments, amendments, SLA penalties. Contract.Create, Contract.Amend, Contract.ScheduleCalloff OrderService reaktor-commerce OMS aggregate, splits, cancellation, substitution, holds, promise, invoice trigger. Order.Create, Order.Confirm, Order.Split, Order.Cancel PurchaseOrderService reaktor-commerce Buyer PO and supplier PO projections, amendments, document linkage. BuyerPO.Attach, SupplierPO.Issue, PO.Amend ProcurementService reaktor-commerce Supplier contracts, source planning, capacity, backup source protocol, procurement price history. Procurement.Plan, SupplierCapacity.Reserve, SupplierPO.Request InventoryService reaktor-inventory ATP, stock lots, reservations, committed/inbound stock, holds, adjustments, transfers. Stock.Receive, Stock.Reserve, Stock.Release, Stock.Adjust WarehouseService reaktor-inventory WMS tasks, QC hold, putaway, pick, load, cycle count, variance. Warehouse.Putaway, Warehouse.Pick, Warehouse.CycleCount QualityService reaktor-commerce plus reaktor-inventory Specs, QC evidence, certificates, rejection, replacement, supplier score. QC.RecordResult, QC.ApproveLot, QC.RejectLot FulfillmentService reaktor-commerce plus reaktor-logistics Allocation, fulfillment order, readiness, shipment creation, dispatch handoff. Fulfillment.Allocate, Fulfillment.MarkReady, Fulfillment.CreateShipment LogisticsService reaktor-logistics LMS/TMS: lane, vehicle, carrier, route, tracking, POD, freight, delay exception. Shipment.Dispatch, Shipment.Track, Shipment.UploadPOD, Shipment.Close FinanceService reaktor-commerce plus reaktor-ledger AR/AP, invoice, payment proof, reconciliation, credit, settlement, margin, GST/TDS. Invoice.Generate, Payment.Record, Settlement.Release CreditService app package first, later optional reaktor-credit Buyer credit limit, payment terms, supplier early payment, invoice discounting, risk holds. Credit.CheckLimit, Credit.ApproveBreach, Finance.OfferEarlyPayment SustainabilityService app package plus reaktor-ledger Biomass usage, coal displacement, carbon estimate, certificate, ESG export. Sustainability.Calculate, Certificate.Issue, Report.Export DocumentService reaktor-media PO, invoice, QC certificate, contract, weighbridge slip, POD, evidence export. Document.Upload, Document.Sign, Document.GetRedacted AuditService reaktor-ledger Command journal, audit facts, actor attribution, evidence bundles, replay pointers. Audit.Append, Audit.Query, Audit.ExportEvidence ReportingService reaktor-db plus analytics KPI, margin, inventory turns, SLA, RFQ conversion, supplier scorecards, delivery performance. Report.Query, Metric.Snapshot, Dashboard.Project ## 12. Workflow Recipes Section ID: 12-workflow-recipes 12. Workflow Recipes Workflows stay in reaktor-graph. OMS, WMS, LMS, procurement, and finance are graph recipes over services and actors. Workflow State owner Critical path Lead to RFQ Lead and RFQ capture lead -> qualify -> create buyer/org -> submit RFQ -> assign ops owner RFQ to quote RFQ and Quote normalize need -> check catalog/spec -> estimate freight -> check ATP/source -> price -> approve -> send quote Quote to order Quote and Order buyer accepts -> attach buyer PO -> credit check -> confirm order -> reserve stock or source supply Source to stock Procurement and StockLot plan supply -> issue supplier PO -> schedule pickup -> receive inbound -> QC -> stock lot -> supplier payable Availability to promise Inventory and Quote check stock -> reserve -> if short, source -> if risk, human approval -> publish promise Order to delivery Order and Shipment allocate -> create fulfillment -> pick/load -> dispatch -> track -> POD -> close shipment Delivery to cash Invoice and Payment generate invoice -> send -> collect -> reconcile -> release supplier settlement -> close margin Issue to resolution Claim complaint -> evidence review -> replacement/credit/rejection -> supplier claim if needed -> ledger close Supplier early payment Settlement and Credit supplier payable -> eligibility -> discount/fee -> approval -> payout -> ledger Sustainability certificate SustainabilityReport delivered biomass facts -> formula -> certificate -> buyer ESG export -> evidence bundle Every workflow declares command, aggregate, auth, idempotency key, timeout, retry policy, ledger requirements, failure states, and projection rules. A Reaktor visitor should reject workflows that mutate money, stock, quality, or supplier visibility without ledger and approval coverage. ## 13. Ecommerce Back Office Recipes Section ID: 13-ecommerce-back-office-recipes 13. Ecommerce Back Office Recipes These are not modules. They are compositions. Back office system Built from OMS reaktor-commerce orders, quotes, contracts, POs, claims, approvals; reaktor-graph workflows; reaktor-ledger events. WMS reaktor-inventory stock lots, reservations, movements, WMS tasks, QC holds, cycle counts; reaktor-media documents. LMS/TMS reaktor-logistics shipment, route, carrier, tracking, POD, freight, exceptions; reaktor-notifications updates. PIM/catalog reaktor-commerce catalog item, spec, attributes, search projection, staged/published projections. Procurement desk reaktor-commerce procurement, supplier contract, supplier PO, capacity, price history; reaktor-ledger and reaktor-inventory. Finance desk reaktor-commerce invoice/payment/settlement; reaktor-ledger finance streams; reaktor-auth approvals. Support/claims reaktor-commerce claim, document evidence, shipment data, QC evidence, credit note/replacement workflow. Intelligence desk reaktor-db, reaktor-ledger projections, market intelligence service, forecasting, scorecards. This gives the Flipkart/Myntra-style operating surface without baking Flipkart/Myntra-specific systems into Reaktor. ## 14. Data Authority and Runtime Topology Section ID: 14-data-authority-and-runtime-topology 14. Data Authority and Runtime Topology Reaktor should make data authority a deployment decision behind typed services. Data/runtime Role in Nexergy Postgres / Hyperdrive / JVM Postgres Authoritative relational state for parties, catalog, RFQs, quotes, orders, POs, contracts, permissions, finance. D1 Edge MVP tables, public lead capture, edge read models, dedup/outbox where appropriate, lightweight ops state. Durable Objects Single-writer hot aggregates: order coordinator, reservation coordinator, shipment tracker, idempotency authority, rate limiter, live ops session. R2 Documents: POs, invoices, contracts, QC certificates, weighbridge slips, POD photos, exports, evidence bundles. Pub/Sub / Cloudflare Queues through reaktor-bus Domain events, async commands, retries, DLQ, reporting fan-out, notifications, integrations. Analytics store RFQ conversion, quote win/loss, stock turns, margin leakage, supplier performance, delivery SLA, sustainability metrics. Search index Catalog search, spec search, buyer order search, ops work queues, supplier/internal search. Reaktor snapshots Workbench, docs, graph diffs, agent context, deployment review, audit context. ## 15. Security, Tenancy, and Redaction Section ID: 15-security-tenancy-and-redaction 15. Security, Tenancy, and Redaction Supplier anonymity is a business model rule. It must be enforced in service DTOs, projections, graph visitors, and tests. Required policies: Every protected route and operation declares an AuthRequirement. Every request carries tenant, principal, role, organization, and channel. Buyer users see buyer org data, plant data, Nexergy quotes/orders, delivery status, invoices, redacted quality evidence, and sustainability reports. Buyer-facing DTOs never include supplier id, supplier legal name, supplier price, supplier contact, raw procurement terms, or supplier settlement state. Internal users see supplier data only through explicit roles and approval scopes. Finance, credit, settlement, QC rejection, supplier contract, price override, and inventory adjustment require immutable ledger entries and approvals. Agent access is read/propose by default. Graph mutation, deploy, finance, credit, and auth admin remain explicitly gated. Export and document download events are ledgered with actor, purpose, tenant, and target. ## 16. Build Sequence Section ID: 16-build-sequence 16. Build Sequence Because Reaktor is assumed complete, the build sequence is product-first. ## Phase 0: Freeze the vocabulary Section ID: phase-0-freeze-the-vocabulary Phase 0: Freeze the vocabulary Convert the prototype sample data into typed fixtures. Remove buyer-facing producer portal language. Define canonical aggregates: party, catalog item, spec, RFQ, quote, contract, order, buyer PO, supplier PO, stock lot, reservation, shipment, invoice, payment, settlement, claim, ledger entry. Define buyer, internal, supplier-ops, warehouse, logistics, finance, and admin projections. ## Phase 1: Ledger and contracts first Section ID: phase-1-ledger-and-contracts-first Phase 1: Ledger and contracts first Implement reaktor-ledger as the first new primitive. Define service contracts for lead, party, catalog, RFQ, quote, contract, order, PO, procurement, inventory, warehouse, logistics, finance, documents, audit, sustainability, and reporting. Add graph visitors for ledger coverage, redaction coverage, idempotency coverage, approval coverage, and data-authority coverage. ## Phase 2: Ops-first MVP Section ID: phase-2-ops-first-mvp Phase 2: Ops-first MVP Build NexergyOpsGraph, NexergyBuyerGraph, and NexergyPublicGraph. Back lead, RFQ, quote, order, stock lot, document, and audit flows with real persistence. Keep supplier operations internal. Make buyer portal a projection over the same records. ## Phase 3: Commerce, inventory, and logistics extraction Section ID: phase-3-commerce-inventory-and-logistics-extraction Phase 3: Commerce, inventory, and logistics extraction Extract reaktor-commerce once RFQ/quote/order/PO/invoice/contracts stabilize. Extract reaktor-inventory once stock lot/reservation/movement/WMS tasks need independent authority. Extract reaktor-logistics once shipment/tracking/POD/freight is reusable outside Nexergy. ## Phase 4: B2B depth Section ID: phase-4-b2b-depth Phase 4: B2B depth Add standing orders, rate contracts, buyer credit limits, supplier early payment, market-intelligence dashboards, supplier scorecards, price trend reports, and VMI/replenishment planning. Add WhatsApp, payment, accounting, GPS, and ERP adapters behind ports. Add repeat order, delivery schedule edits, claim resolution, and evidence exports. ## Phase 5: Scale and automation Section ID: phase-5-scale-and-automation Phase 5: Scale and automation Add automated pricing, demand forecasting, source optimization, stock rebalancing, credit/risk suggestions, and sustainability analytics. Add mobile buyer, warehouse, and logistics flows. Add agent-assisted ops in the workbench with read/propose permissions and strict approval gates. ## 17. Non-Goals Section ID: 17-non-goals 17. Non-Goals No reaktor-biomass, reaktor-nexergy, or biomass-specific framework module. No public supplier marketplace unless the PRD changes. No direct buyer-supplier messaging. No separate workflow engine duplicating reaktor-graph. No OMS/WMS/LMS modules as monoliths; they are recipes over generic modules. No finance, credit, inventory, quality, or audit mutation without ledger-backed idempotency and actor attribution. No hard dependency on one deployment topology; Cloudflare-first and JVM/Postgres must both be possible behind the same service contracts. ## 18. Final Shape Section ID: 18-final-shape 18. Final Shape Nexergy Energy is the production platform. Reaktor is the engine underneath it, and the same engine discipline keeps Nexergy focused while the underlying primitives stay reusable. reaktor-graph workflows, policies, visitors, platform graphs, snapshots, workbench inspection reaktor-service + reaktor-server + reaktor-bus + reaktor-work typed operations, resilience, idempotency, outbox, events, scheduled work reaktor-commerce party, catalog, channel, RFQ, quote, contract, order, PO, invoice, claim, approval, projection reaktor-inventory availability, stock lot, reservation, WMS task, QC hold, movement, replenishment reaktor-logistics shipment, route, carrier, vehicle, tracking, POD, freight, delivery exception reaktor-ledger command journal, audit, domain events, inventory ledger, finance ledger, replay, evidence export platform graph: Nexergy Energy biomass specs, clusters, supplier anonymity, margin rules, sustainability formulas, buyer and ops experience That is the intended split: Nexergy Energy gets a focused, production-grade platform, while Reaktor stays a small set of expressive engine modules instead of accumulating vertical product modules. ## Sources Scanned Section ID: sources-scanned Sources Scanned Buyofuel home, buyers, sellers, inventory management, and sustainability reporting BiofuelCircle home, marketplace, procurement service, supply chain as a service, sales service, value added services, and Envira Moglix Business, Moglix retail marketplace, Credlix, Oxyzo, and Udaan Shopify Admin API, commercetools products API, and commercetools inventory API ## Related docs Section ID: related-docs Related docs Nexergy on Reaktor (Claude) - Use when designing the production Nexergy Energy system on Reaktor, scoping the ledger/catalog/fulfillment modules, designing embedded-finance/credit on the ledger, or turning the Nexergy prototype into a production system. Service Layer - Use before adding service APIs, splitting reaktor-service out of reaktor-graph, wiring handlers to Spring/Workers, or making modules graph-projectable without hard graph dependencies. Data Layer - Use before choosing a store, designing offline-first sync, or deciding authority vs cache vs projection for a datum; the centerpiece is the tier 1↔2/3 server-authoritative sync engine. Work - Use before changing background scheduling, worker contracts, WorkRequest/WorkConstraints, BestBuds workers, edge/web scheduling, work telemetry, or graph projection for work. 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. React x Compose - Use before touching the React/Compose bridge. # Codex Roadmap URL: https://reaktor.build/docs/codex-roadmap Status: superseded Content revision: 0110f58f3cd31e4f501ee3555bec287c4db3c71080527de12e98daf202290c5a Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/codex-roadmap","polarity":"Neutral"},{"id":"section-1-summary","anchor":"1-summary","label":"1. Summary","profile":"section","contract":"https://reaktor.build/docs/codex-roadmap#1-summary","polarity":"Neutral"},{"id":"section-2-evidence-from-the-current-code","anchor":"2-evidence-from-the-current-code","label":"2. Evidence From The Current Code","profile":"section","contract":"https://reaktor.build/docs/codex-roadmap#2-evidence-from-the-current-code","polarity":"Neutral"},{"id":"section-2a-deeper-code-level-analysis","anchor":"2a-deeper-code-level-analysis","label":"2A. Deeper Code-Level Analysis","profile":"section","contract":"https://reaktor.build/docs/codex-roadmap#2a-deeper-code-level-analysis","polarity":"Neutral"},{"id":"section-3-target-architecture","anchor":"3-target-architecture","label":"3. Target Architecture","profile":"section","contract":"https://reaktor.build/docs/codex-roadmap#3-target-architecture","polarity":"Neutral"},{"id":"section-4-prototype-feature-map","anchor":"4-prototype-feature-map","label":"4. Prototype Feature Map","profile":"section","contract":"https://reaktor.build/docs/codex-roadmap#4-prototype-feature-map","polarity":"Neutral"},{"id":"section-5-implementation-phases","anchor":"5-implementation-phases","label":"5. Implementation Phases","profile":"section","contract":"https://reaktor.build/docs/codex-roadmap#5-implementation-phases","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/codex-roadmap#related-docs","polarity":"Neutral"}],"relations":[{"id":"codex-roadmap:references-reaktor-workbench-roadmap","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-workbench-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"codex-roadmap:references-reaktor-implementation-plan","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-implementation-plan","port":"page","role":"target","ordinal":0}]},{"id":"codex-roadmap:references-graph-kernel-analysis","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"section-related-docs","role":"source","ordinal":0},{"node":"graph-kernel-analysis","port":"page","role":"target","ordinal":0}]},{"id":"codex-roadmap:references-reaktor-agentic-tooling","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-agentic-tooling","port":"page","role":"target","ordinal":0}]},{"id":"codex-roadmap:references-reaktor-architecture-analysis","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-architecture-analysis","port":"page","role":"target","ordinal":0}]},{"id":"codex-roadmap:references-reaktor-framework-overview","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-framework-overview","port":"page","role":"target","ordinal":0}]},{"id":"codex-roadmap:current-astra-reaktor-plan-and-roadmap","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"page","role":"source","ordinal":0},{"node":"astra-reaktor-plan-and-roadmap","port":"page","role":"target","ordinal":0}]},{"id":"codex-roadmap:current-reaktor-module-execution-plan","kind":"references","owner":"codex-roadmap","incidences":[{"node":"codex-roadmap","port":"page","role":"source","ordinal":0},{"node":"reaktor-module-execution-plan","port":"page","role":"target","ordinal":0}]}]} ## Codex Roadmap Section ID: preamble Code-grounded roadmap for turning the Reaktor Workbench prototype into a real control plane. ## 1. Summary Section ID: 1-summary 1. Summary Reaktor already has more real infrastructure than the prototype suggests. The graph runtime, port model, object DB, service abstraction, auth kernel, Cloudflare bridge, Compose desktop workbench, graph document export, and BestBuds app graph are present. The missing work is a production control plane that connects those pieces to the web prototype's screens and replaces every static scenario with live, typed state. ## Keep Section ID: keep Keep The existing Reaktor runtime model should remain the center: Graph, Node, RouteNode, ports, lifecycle, DI, and Feature slots. The desktop engine and server graph endpoint are the first real workbench spine. ## Replace Section ID: replace Replace Replace targets/reaktorWeb/src/mock-services.js, static scenario*.jsx catalogs, fake DB/auth/agent data, and no-op buttons with a WorkbenchService contract and safe command queue. ## Converge Section ID: converge Converge Unify the React web prototype, Compose desktop workbench, and Spring/Cloudflare service layers around one serializable WorkbenchManifest and WorkbenchEvent stream. :::note Definition of reality: a visible workbench feature is real only when it reads from live or recorded production-shaped data, every command is persisted and auditable, every mutating action has authorization and rollback semantics, and tests prove crash-free behavior for the screen and the underlying service contract. ::: ## 2. Evidence From The Current Code Section ID: 2-evidence-from-the-current-code 2. Evidence From The Current Code AreaStatusObserved sourceWhat it meansGraph runtimeReal../reaktor/reaktor-graph, ../reaktor/reaktor-graph-portLifecycle, navigation, auto-wiring, typed providers/consumers, and port events exist. The graph screen should consume this instead of hand-authored entity arrays.Flow editorReal../reaktor/reaktor-flow, modules/engine/src/main/kotlin/ai/bestbuds/reaktor/ReaktorWorkbench.ktCompose desktop already builds a visual graph from a live Graph. Web should share the same manifest/model, not create a second graph language.Graph document exportPartialmodules/engine/src/main/kotlin/ai/bestbuds/reaktor/ReaktorGraphDocument.kt, targets/reaktorServer/.../ServerApplication.kt/apps/{appId}/graph exists and exports nodes/edges. It needs file ownership, stable IDs, tests, deploy targets, telemetry links, auth/service/DB metadata, and versioning.BestBuds dogfood graphRealmodules/app/src/commonMain/kotlin/ai/bestbuds/app/BestBuds.ktThe app has chat, campaign, discover, events, friends, profile, dev, onboarding, repositories, and interactors. It is a valid first production target for the workbench.Auth kernel and adaptersPartial../reaktor/reaktor-authAuth models, staged login state, JWT verification, server interactor, RBAC schema, PAT contracts, and web Apple/Google providers exist. Android Apple and complete session/refresh/audit/runtime enforcement still need work.Database layerPartial../reaktor/reaktor-db, targets/reaktorServer/.../ServerApplication.ktSQLite object store and GraphDb/Memgraph are real. DB console functionality is currently static and needs adapters for Postgres, D1, Durable Objects, R2, local SQLite, and Memgraph with redaction and RBAC.Cloudflare bridgePartial../reaktor/reaktor-cloudflare, modules/app/src/jsMainTyped bindings and service-to-Hono bridge exist. Deploy/run/test screens still need a deployment control plane and environment-aware service registry.TelemetryPartial../reaktor/reaktor-telemetry, modules/app/src/commonMain/.../analyticsGraph instrumentation and analytics sinks exist. The insights UI needs ingestion, storage, query APIs, span correlation, and release comparison.Agents and command queueFacadetargets/reaktorWeb/src/screen-agent.jsx, scenario-v3.jsxCodex, Claude, Gemini, commits, and pending commands are static. Need a persistent queue, command validators, codegen workers, git boundaries, and audit.Prototype actionsFacadetargets/reaktorWeb/src/mock-services.jsHot reload, deploy, rollback, tests, IDE open, apply/revert commands, and agent actions return mocked logs. This file must disappear from production builds. ## 2A. Deeper Code-Level Analysis Section ID: 2a-deeper-code-level-analysis 2A. Deeper Code-Level Analysis This section is grounded in the actual Reaktor and BestBuds source. The main conclusion is stronger than the first scan: the prototype is a facade, but the repos already contain enough real runtime surfaces to make the facade honest without inventing a parallel architecture. ## Runtime substrate that should be reused Section ID: runtime-substrate-that-should-be-reused Runtime substrate that should be reused LayerActual sourceObserved behaviorWorkbench implicationGraph orchestration../reaktor/reaktor-graph/src/commonMain/.../core/Graph.kt, Node.kt, RouteNode.kt, ContainerNode.ktGraph delegates lifecycle, DI, concurrency, navigation, and port containment. dispatch handles cross-graph navigation through containers. autoWire() connects consumers to local providers or DI fallback.The graph tab should not infer routes from static JSON. It should render real Graph, ContainerNode, RouteNode, attached nodes, back stack roots, lifecycle state, and auto-wire failures.Port and edge model../reaktor/reaktor-graph-port/src/commonMain/.../port, .../edge/Edge.kt, .../graph/connect.ktProvider and consumer ports are typed by (Type, Key). Edges reject already-connected consumers, emit connect/disconnect events, and carry a deterministic qualifier.Data edges in the workbench should show exact provider/consumer type, key, owner node, connection state, and errors from requireFullyWired(), not only a display label.Typed services../reaktor/reaktor-graph/src/commonMain/.../service/Service.kt, RequestHandler.kt, ServiceInterceptor.ktService owns typed handlers, client invocation, request/response serializers, route patterns, environment propagation, and interceptors.Deploy, testing, auth, DB, and API tabs should be derived from handler catalogs and transport metadata. Service calls should be traceable through a common interceptor rather than manually instrumented per screen.Cloudflare runtime bridge../reaktor/reaktor-cloudflare/src/jsMain/.../Router.kt, Bindings.kt, CloudflareApi.ktService.toHono() maps typed handlers onto Hono routes and injects CloudflareContext. Bindings cover D1, R2, KV, Durable Objects, service bindings, secrets, vector, AI, and Hyperdrive.The deployment and database tabs can introspect real worker bindings and routes. Production work should replace ad hoc worker UI data with a CloudflareTargetCatalog.Object and graph persistence../reaktor/reaktor-db/src/commonMain/.../ObjectDatabase.kt, core/ObjectStore.kt, graph/GraphDbPolicy.ktObject stores emit DB events and maintain per-key flows/cache. Graph DB policies enforce mandatory tenant parameterization and tenant filters in Cypher.The DB tab should surface stores, keys, flows, cache policy, graph query policy, and tenant safety checks. Writes should become migration or command records.Auth substrate../reaktor/reaktor-auth/src/commonMain/.../AuthAdapter.kt, kernel/AuthKernel.kt, jvmMain/.../LoginInteractor.kt, api/AuthServer.ktThe client adapter has explicit login states, provider registry, server sign-in, and session caching. The kernel models principals, tenants, scopes, permissions, roles, token claims, and authorization decisions. The JVM server verifies provider JWTs and mints access/PAT tokens.The auth tab should be backed by provider health, login-state telemetry, RBAC catalog, token/session lifecycle, PAT operations, and authorization decision traces. Static role matrices are not enough.Telemetry../reaktor/reaktor-telemetry/src/commonMain/.../GraphTelemetry.kt, bestbuds/modules/app/src/commonMain/.../analyticsGraph telemetry observes lifecycle, back stack, screen views, and existing port listeners. BestBuds has analytics event contracts and an analytics worker endpoint.Insights should start by correlating graph node IDs, route changes, service calls, DB events, and BestBuds analytics events into one entity timeline.Desktop enginebestbuds/modules/engine/src/main/kotlin/ai/bestbuds/reaktor/ReaktorGraphDocument.kt, ReaktorComposeSemanticsInspector.kt, ReaktorRuntime.ktThe engine already initializes desktop/test/server features, exports a graph document, and captures Compose semantics/source/bounds every 350ms while enabled.This is the first real workbench host. The web prototype should consume engine/server contracts and the desktop workbench should consume the same manifest version. ## BestBuds is a concrete dogfood app, not a toy fixture Section ID: bestbuds-is-a-concrete-dogfood-app-not-a-toy-fixture BestBuds is a concrete dogfood app, not a toy fixture Product areaActual sourceCurrent realityRoadmap consequenceRoot app graphbestbuds/modules/app/src/commonMain/kotlin/ai/bestbuds/app/BestBuds.ktApp id 38d1cee3-004d-441f-8f66-ad5060859af1. Root nodes include config, messages, stickers, user, chat, social, and user interactors. Home contains Chat, Campaign, Discover, Events, Friends, Profile, and Dev graphs.The manifest builder should use this as its baseline fixture and acceptance target. Every graph tab feature should work against this real app id.Routes and screensBestBuds.kt plus modules/app/src/commonMain/.../uiRoutes include /, /onboarding, /home, /chats, /chats/{id}, profile/friend/group routes, campaigns, events, friends, profile edit/create, and dev.The Run App tab should support route dispatch and route-param editing against these actual route bindings. The Testing tab should map specs to these flows.Chat orchestrationdata/interactors/ChatInteractor.kt, data/repositories/MessageRepository.ktChat has cache-first open, background revalidation, WebSocket receive/send, optimistic messages, retry/discard, reaction queuing, typing, presence, pagination, and group-member hydration.DevTools should be able to trace one chat send through UI state, interactor, cache, socket, backend echo, reaction updates, and telemetry. Gemini scouting can target TODOs around signed socket auth, heartbeat, multi-device presence, and privacy.User/session orchestrationdata/repositories/UserRepository.ktUser login goes through Feature.Auth, records pending provider/status in KV, handles timeout/failure, persists the user, hydrates stickers/profile, and supports logout. There are explicit TODOs around flow-based user state.Auth and DevTools should show current login stage, pending provider, cached user, hydration work, and failure state. Auth refresh/session tests should be part of production readiness.Social and messaging servicesdata/social/SocialService.kt, data/services/MessagingService.kt, data/analytics/AnalyticsService.ktTyped handlers exist for friends, groups, current/discover campaigns, profile, onboarding questions/responses/complete, top messages, chat messages, send, bot send, reactions, and analytics ingest.The API catalog should be generated from typed service classes. Mock endpoint lists in the prototype should be replaced by real handler metadata plus environment URLs.Cloudflare workersmodules/app/src/jsMain/kotlin/ai/bestbuds/app/cloudflareMessaging and social workers mount typed services through bestBudsWorker. Worker auth is explicitly disabled until JWT verification is wired. Bot agents are registered in AgentRegistry.kt.Deploy view should know the worker service, bindings, auth posture, endpoint list, and security blockers. AI tab can start with the real Workers AI bot registry instead of invented model cards. ## Current graph document export is useful but too thin Section ID: current-graph-document-export-is-useful-but-too-thin Current graph document export is useful but too thin ReaktorGraphDocument.kt currently exports app id/label, visible nodes, containment/navigation/data edges, display labels, graph names, routes attached to nodes, and provider/consumer keys. It intentionally hides RouteNode from visible nodes and normalizes IDs from graph labels plus route or node labels. Missing from exportWhy it mattersWhere to get itStable source-aware IDsIDs based on labels and routes can shift when labels change. Commands, tests, telemetry, and commits need stable identity.Combine graph/node runtime id, class fqcn, route pattern, source file, and optional KSP metadata.Route nodes and route bindingsNavigation debugging needs route payload type, path params, attached nodes, source route, target route, and container activation.RouteNode.pattern, routeBinding, navigationTargets(), ContainerNode.graphs, back stack entries.Port type metadataProvider/consumer keys alone cannot prove type safety or explain auto-wire misses.ProviderPort.key.type, ConsumerPort.key.type, qualifiers, edge source/destination, PortEvent.Services and worker endpointsDeploy, testing, auth, API docs, and DevTools all need real handlers.Service.handlers, RequestHandler.method, routePattern, worker wrappers under modules/app/src/jsMain.Stores, cache policy, and DB bindingsThe DB tab cannot be production-ready without knowing which nodes read/write which stores and backing resources.RepositoryNode store names, ObjectDatabase.events, Cloudflare bindings, Postgres/D1/R2 declarations, GraphDb policies.Auth requirementsUsers need to know whether a route/service/action is unauthenticated, user-scoped, admin-scoped, PAT-scoped, or currently unsafe.AuthKernel, AuthServer, LoginInteractor, worker auth config, service middleware/interceptors.Tests and deploy targetsCommand queue, affected-tests view, and deploy gates need source-to-test and source-to-deploy mapping.tests/ folders, Gradle tasks, npm scripts, Wrangler/Partykit targets, Playwright/Maestro specs.Known incompleteness markersThe workbench should expose incomplete production behavior rather than hide it behind polished UI.TODO/FIXME scanners over BestBuds/Reaktor, disabled KSP processor, disabled worker auth, stub platform adapters, mocked web services. ## Prototype-to-real replacement map Section ID: prototype-to-real-replacement-map Prototype-to-real replacement map Prototype file/surfaceCurrent behaviorReplacementtargets/reaktorWeb/src/scenario.jsx, scenario-v3.jsx, window.ENTITIES, window.BUNDLEStatic graph, commands, auth, DB, deploy, tests, agents, and metrics.GET /workbench/apps/{appId}/manifest plus recorded fixtures generated from the same endpoint for offline tests.mock-services.jsEvery action sleeps and returns a fake log, including deploy, rollback, test run, command apply/revert, IDE open, and agent calls.WorkbenchServiceClient with typed calls for command preview/apply/revert, test run, deploy dry-run/promote, source open, agent job, and runtime session control.workbench-domain.jsxDomain helpers read global browser variables and local React state.Move to a typed client-side store fed by manifest snapshots and event streams. Keep UI-only helpers, but remove production reads from global scenario data.screen-agent.jsxCodex, Claude, Gemini, command queue, commits, and pending work are scenario objects.Persistent command queue, agent job table, git commit mapping, read-only Gemini scout jobs, and queue items linked to commands/tests/commits.screen-database.jsxStatic resource list and sample rows.Read-only adapters for ObjectStore, Postgres/Supabase, D1, R2, Durable Objects, and Memgraph, with redaction and write commands only.screen-testing.jsxStatic suites and proxy rules.Test inventory scanner plus runners for Playwright, Maestro, Gradle, and service replay. Results link to manifest entities and command gates.screen-deploy.jsxMock release activity over static topology.Deploy catalog from npm scripts, Wrangler/Partykit configs, server deploy scripts, k3s scripts, secrets check, dry-run plan, approval gates, and rollback records. ## Production blockers found in code Section ID: production-blockers-found-in-code Production blockers found in code BlockerEvidenceRequired fix before calling it productionWorker auth is not wiredbestbuds/modules/app/src/jsMain/.../core/BestBudsWorker.kt rejects enabled auth with BestBuds worker auth is not wired yet.Add JWT verification middleware using reaktor-auth token verification, wire service requirements, and expose auth posture in the Deploy/Auth tabs.User identity is passed as a serialized header in product servicesSocialService and MessagingService use userHeaders(user); workers read currentUserOrNull.Replace trust-on-header behavior with signed access tokens and typed auth requirements. Keep impersonation only in explicit dev/test mode.Chat socket identity is raw query dataChatInteractor.connectWebSocket passes userId and userName via query and comments that signed token auth is needed.Issue short-lived room tokens, verify them in the PartyKit/chat worker, and add tests for rejected/expired tokens.Session lifecycle is incompleteLoginInteractor mints access tokens and creates a random refresh token, but complete refresh persistence/revoke/audit flow is not unified in the runtime.Persist refresh sessions, add revoke/rotate endpoints, expose active sessions in Auth, and add regression tests for refresh/revoke.Compiler metadata path is disabled../reaktor/reaktor-compiler/src/.../ReaktorProcessor.kt returns immediately.Either restore KSP metadata generation or explicitly replace it with Gradle/source scanning for source file, ownership, command, and test mapping.Secrets/config leakage risktargets/reaktorServer/.../ServerApplication.kt contains hardcoded database configuration, and deploy scripts include sensitive command-line tokens.Move credentials to secret stores, add a scanner gate, and prevent Deploy tab from exposing secret values in logs or manifests.Platform auth parity is unevenAndroid Apple login is a TODO; web providers exist but still need production configuration and parity tests.Make provider support visible per platform and enforce parity tests before a provider is marked healthy.Several BestBuds user flows are visibly incompleteProfile edit/save, campaign join/details, event actions, image picker, and call actions still have TODOs or partial behavior.The workbench should mark these as incomplete product capabilities and generate command/test plans rather than displaying them as finished. ## Concrete first implementation delta Section ID: concrete-first-implementation-delta Concrete first implementation delta :::note Recommended next code milestone: extend ReaktorGraphDocument.kt into a versioned WorkbenchManifest, expose it from targets/reaktorServer, generate a checked-in fixture from the live BestBuds graph, and migrate the Graph/Search/Drawer portions of targets/reaktorWeb away from scenario*.jsx. That gives the team a real spine before touching deploy, DB, auth, agents, or testing. ::: ## 3. Target Architecture Section ID: 3-target-architecture 3. Target Architecture The clean structure is a layered control plane. Screens are thin. Domain logic lives in typed services. Runtime adapters are explicit and replaceable. Mutations go through commands. Low-level escape hatches exist only behind capability checks. Source Apps BestBuds and future Reaktor apps expose graphs, routes, services, repositories, auth, deploy targets, and tests. Manifest Builder Runtime reflection plus Gradle/KSP metadata produces a stable WorkbenchManifest. Workbench Service Typed APIs provide graph, runtime, DB, auth, testing, deploy, telemetry, agents, and commands. Command Queue All mutations become validated sealed commands with preview, apply, revert, commit, and audit records. Web/Desktop UI React prototype and Compose desktop consume the same contract and render mode-specific views. ## Core packages to introduce or promote Section ID: core-packages-to-introduce-or-promote Core packages to introduce or promote Package/moduleResponsibilityWhy it belongs herereaktor-workbench-coreShared serializable models: manifest, events, commands, queue records, adapters, RBAC scopes.This is framework-level and should serve BestBuds, Manna, and any future Reaktor app.reaktor-workbench-serviceService contract and server implementation for graph/runtime/DB/auth/testing/deploy/agent APIs.Prevents every UI surface from inventing direct transport and filesystem access.bestbuds/modules/engineDogfood host, desktop shell, app registration, live preview, graph document builder until promoted.Already contains real workbench code and should be the proving ground before framework extraction.targets/reaktorWebProduction web shell for remote workbench access.Keep the UI investment, but make it a client of WorkbenchService rather than a static scenario viewer.targets/reaktorServerLocal/cloud control-plane backend, app graph endpoint, GraphQL, Memgraph, auth, deploy/test bridges.Already exposes /apps/{appId}/graph; extend it into a real workbench API. ## Shape of the shared contract Section ID: shape-of-the-shared-contract Shape of the shared contract sealed interface WorkbenchCommand { val id: CommandId val appId: AppId val target: WorkbenchTarget val author: WorkbenchActor val reason: String val risk: CommandRisk } data class AddNodeCommand(...) data class ConnectPortsCommand(...) data class UpdateRouteCommand(...) data class UpdateAuthPolicyCommand(...) data class CreateMigrationCommand(...) data class RunTestSuiteCommand(...) data class DeployReleaseCommand(...) data class AgentScoutCommand(...) data class WorkbenchManifest( val app: WorkbenchApp, val graph: GraphManifest, val sources: SourceIndex, val services: ServiceCatalog, val stores: StoreCatalog, val auth: AuthCatalog, val tests: TestCatalog, val deploy: DeployCatalog, val telemetry: TelemetryCatalog ) ## 4. Prototype Feature Map Section ID: 4-prototype-feature-map 4. Prototype Feature Map Every row below corresponds to visible functionality in targets/reaktorWeb/src. The target is not "make buttons click"; the target is production behavior with mock data only where explicitly labeled as recorded fixtures or test mode. Prototype areaCurrent behaviorReal substrateWork to make it realAcceptance criteriaGraphStatic entities and edges in scenario*.jsx.Graph, PortCapability, ReaktorFlowGraph, ReaktorGraphDocument.Serve graph manifests from live app graph. Add stable IDs, source paths, routes, ports, DI, stores, services, tests, deploy targets, telemetry nodes, and focus queries.Graph view renders BestBuds from /apps/{appId}/graph; selecting a node opens real metadata; no production dependency on window.ENTITIES.Run AppVisual fake devices and state controls.Compose desktop preview in modules/engine, BestBuds GraphApplication, web/app targets.Add runtime session manager, app preview launch, hot reload, route dispatch, device profiles, network modes, logs, state snapshots, and click-to-inspect bridge.User can launch BestBuds in phone/desktop viewport, navigate actual graph routes, inspect UI tree, and see runtime errors/logs.DevToolsStatic blast radius, commands, and mini device.Graph edges, lifecycle flows, port events, telemetry spans, source index.Capture navigation transitions, port invocations, DB/service calls, payload previews, affected tests, source jump, and diff linkage.Clicking a live action produces a trace showing route, node, port, service, cache, network, DB, and telemetry events.DeployMock deploy/rollback logs and static topology.npm deploy scripts, Wrangler targets, k3s scripts, Spring server deploy, n8n workflow definitions.Build deploy catalog, environment inventory, CI run adapter, migration planner, canary/rollback model, secret validation, and release health monitor.Deploy button starts a real gated release job or opens a dry-run plan; production deploy requires RBAC and passing tests.InsightsStatic funnels, costs, retention, error cards.reaktor-telemetry, BestBuds analytics queue/service, Firebase/OTel adapters.Create telemetry ingestion store, query endpoints, release correlation, entity-to-metric links, cost adapters, and trace sampling controls.Insights cards are backed by a named data source, time range, and query; graph nodes show current p95/error/funnel impact.AgentStatic Codex/Claude/Gemini personas, fake chat, fake queue, fake commits.Codex CLI/worktrees, git, tests, graph manifest, command model.Build agent registry, conversation store, scout jobs, command proposal API, review gates, command-to-commit grouping, and worktree isolation.Gemini scout can run a real read-only scan; queued findings produce commands; committed groups show actual git commits and executed command IDs.DatabaseStatic catalogs for Supabase, Memgraph, D1, Durable Objects, R2, SQLite.Reaktor object store, Memgraph/Neo4j GraphDb, Exposed/Supabase, Cloudflare bindings.Implement adapters, schema introspection, read-only query console, migrations, relationship explorer, explain plans, PII redaction, and write approvals.Schema/data tabs query real or recorded data source; writes create migration commands, not direct DB edits.AuthStatic provider, role, session, audit views; local state toggles.reaktor-auth AuthKernel, RBAC schema, AuthService, LoginInteractor, adapters.Expose provider health, role/permission CRUD via commands, session lookup/revoke, PAT flows, audit stream, provider parity tests, and RBAC middleware status.Revoking a session calls a real endpoint; role matrix changes generate audited policy commands; provider status reflects actual config/test results.TestingStatic suites plus calls to mocked runTests.tests/ structure, Playwright specs, Maestro flows, Gradle tests, Keploy config.Build test inventory scanner, runner API, artifact store, coverage-to-graph mapping, replay/proxy manager, device lab adapter, and flaky-test tracker.Run buttons execute named suites; result rows link to artifacts, graph nodes, source files, and command gates.AIStatic model registry, notebooks, gateway, evals, costs.Cloudflare Workers AI wrapper, agent concepts, possible OpenAI/Gemini adapters.Implement provider registry, model usage logs, prompt/eval store, gateway policies, safety checks, cost collection, and notebook execution sandbox.AI tab displays real configured providers, model calls, eval runs, and cost estimates from logs.Shell, search, drawerMostly local state over static data.Workbench manifest, command queue, source index, app registry.Centralize state orchestration, persisted preferences, RBAC-aware actions, deep links, keyboard shortcuts, source search, and drawer tabs backed by APIs.Every sidebar/search/drawer result comes from the manifest or a service query and survives refresh. ## 5. Implementation Phases Section ID: 5-implementation-phases 5. Implementation Phases P0 Freeze the contract and remove ambiguity Turn the prototype into a written/API contract before adding more surface area. 1 week Define WorkbenchManifest, WorkbenchEvent, WorkbenchCommand, CommandQueueRecord, and WorkbenchCapability. Tag prototype-only static data and block it from production builds with a lint/test check. Create API fixtures from real BestBuds graph export so UI can migrate one endpoint at a time. Define RBAC scopes for read graph, run app, query DB, modify auth, run tests, deploy, and run agents. Document destructive action rules: no direct writes except through commands with preview and rollback metadata. Add a production readiness checklist per screen and keep it next to Playwright specs. P1 Make the graph and shell live Replace static graph/search/sidebar/drawer data with the real app manifest. 2-3 weeks Promote and enrich ReaktorGraphDocument.kt into a reusable manifest builder. Extend /apps/{appId}/graph to /workbench/apps/{appId}/manifest with version, schema, source, and capability metadata. Add stable IDs that do not depend on object identity alone; include route path, graph path, node type, and source fingerprint. Add a web data layer: useWorkbenchManifest, useCommandQueue, useWorkbenchSearch. Keep local fixtures only as recorded offline mode and Playwright fixtures. Make graph focus, blast radius, affected tests, and sidebar groups derived selectors over manifest data. P2 Build the command queue before mutating anything The workbench must never apply hidden edits. Commands are the safety boundary. 3-4 weeks Implement sealed command classes and validators for graph, source, DB, auth, testing, deploy, and agent actions. Persist queue records with status: drafted, proposed, reviewed, ready, running, applied, reverted, failed, committed. Support dry-run, diff preview, conflict detection, dependency ordering, and rollback metadata. Group executed commands by actual git commit and show pending commands separately in Agent view. Map every UI mutating button to either a command proposal or an explicitly disabled state with reason. Add command audit entries with actor, RBAC scopes, source IP/session, approval chain, and resulting artifacts. P3 Make Run App and DevTools production-grade Connect the visual workbench to a real running app session and trace stream. 4-6 weeks Create WorkbenchRuntimeSession for desktop, web preview, Android simulator, and iOS simulator modes. Expose route dispatch, back stack, lifecycle state, selected UI element, component tree, logs, and errors. Instrument port invocations, service calls, repository cache hits, DB access, websocket events, and analytics emissions. Bridge Compose semantics inspector data into the shared manifest/runtime event stream. Implement hot reload as a real build/reload operation with failure state and logs. Make DevTools timelines replayable and link each event to graph nodes and source paths. P4 Make Database and Auth consoles real These screens are sensitive; implement read-first, RBAC-first, command-first behavior. 4-5 weeks Build DB adapters for local SQLite object stores, Supabase/Postgres, Memgraph, D1, Durable Objects, and R2 metadata. Default all database views to read-only and redact secrets/PII by policy. Route schema changes through migration commands with dry-run and rollback sections. Expose auth providers, RBAC roles, permissions, user-role bindings, sessions, PATs, and audit logs from reaktor-auth. Finish provider parity gaps: Android Apple, session refresh lifecycle, revoke flows, and service middleware enforcement status. Move hard-coded credentials and platform secret TODOs into proper secret storage before production access. P5 Make Testing, Deploy, and Insights operational Workbench decisions should be gated by test evidence and production telemetry. 4-6 weeks Scan tests/, Gradle tasks, Playwright, Maestro, Keploy, n8n, and deploy scripts into a TestCatalog. Add a runner API that can execute suites, stream logs, collect artifacts, and map failures to graph nodes. Build deploy adapters for Wrangler workers, app web, analytics/sticker services, Spring server, k3s, Android, and iOS distribution. Implement environment inventory, release manifests, migrations, canary gates, rollback gates, and health checks. Wire telemetry ingestion to graph entities, route spans, release versions, cost data, funnel events, and crash/error cards. Make the Deploy button a real pipeline starter only after RBAC, command review, tests, and environment checks pass. P6 Make agents and AI useful, bounded, and auditable Gemini scouts broadly, Codex proposes/builds, Claude critiques/tests, but the queue remains the source of truth. 4-6 weeks Create agent registry and conversation store with model, tool, permission, trigger, and scope metadata. Implement Gemini scout jobs for dead code, harness gaps, coverage mapping, inefficiencies, dependency drift, and stale generated wrappers. Make agents output structured findings and commands, never untracked source mutations. Run codegen in isolated worktrees and attach diffs, tests, and commit metadata back to queue records. Build AI provider registry, gateway logs, eval runs, safety checks, usage costs, and notebook sandbox for the AI tab. Add audit rules for every agent action: inputs, model, prompt version, files read, files changed, tests run, reviewer, and commit. ## 6. BestBuds Dogfood Gaps The Workbench Should Expose Section ID: 6-bestbuds-dogfood-gaps-the-workbench-should-expose 6. BestBuds Dogfood Gaps The Workbench Should Expose The first honest proof is BestBuds. The workbench should surface these as real graph findings, not hidden TODOs. GapCurrent source signalWorkbench behavior to implementEdit profile is not implementedEditProfileScreen.kt throws TODO; ProfileScreen.kt has save TODO.Graph should mark route/screen as incomplete, Testing should show missing flow, Agent/Gemini should propose bounded implementation commands.Campaign actions are placeholdersCampaignScreen.kt and DiscoverScreen.kt have TODO click actions.Blast radius should link campaign UI buttons to missing interactor/service endpoints and tests.Private events actions and image picker are incompletePrivateEventsScreen.kt, CreateEventScreen.kt.Testing catalog should show absent event creation/upload flows; command queue should generate media/event service work.Call action is not implementedChatScreen.kt call TODO.Graph should expose action node as incomplete and link to media/work/notification capabilities needed.Auth provider parity is incompleteAndroidAppleLogin.kt TODO; auth/session lifecycle partial.Auth tab should show provider parity status by platform and Testing should gate releases on adapter contract tests.Secrets and credentials need hardeningServerApplication.kt contains direct Supabase connection data; reaktor-security platform secret boxes are TODO.Deploy screen should fail production readiness until secrets are moved into approved secret stores and platform boxes are implemented. ## 7. Testing Strategy Section ID: 7-testing-strategy 7. Testing Strategy ## Contract tests Section ID: contract-tests Contract tests Manifest schema golden tests for BestBuds graph export. Command validation tests for every command type and failure mode. Auth provider parity tests across Android, Darwin, Web, Desktop, and server verification. DB adapter tests with local fake drivers and redaction assertions. ## UI and workflow tests Section ID: ui-and-workflow-tests UI and workflow tests Keep Playwright for reaktorWeb tab coverage, keyboard flows, command queue, graph interactions, and crash-free behavior. Use Maestro for mobile BestBuds app flows and web smoke where it provides useful black-box coverage. Add screenshot/artifact checks for visual regressions and component overlap. Map every UI test to graph nodes so blast radius can show affected coverage. ## Production-readiness gates Section ID: production-readiness-gates Production-readiness gates GateRequired evidenceNo static production dataBuild/test fails if production bundle imports mock-services.js or uses scenario-v3.jsx as primary data.Every button has behaviorPlaywright action inventory asserts each enabled control either triggers an API call, command, navigation, test run, or explicitly visible state change.No unsafe writesDB/auth/deploy mutations create queue records and require RBAC plus dry-run preview before apply.Graph is source of truthGraph/search/sidebar/drawer data comes from manifest selectors; fixtures are only used in offline or test mode.Dogfood coverageBestBuds graph, run preview, tests, deploy, auth, DB, and telemetry have at least one live integration path each. ## 8. Risks And Mitigations Section ID: 8-risks-and-mitigations 8. Risks And Mitigations ## Risk: the UI outpaces the substrate again Section ID: risk-the-ui-outpaces-the-substrate-again Risk: the UI outpaces the substrate again Mitigation: no new prototype-only tabs. Every new visual component must be backed by a domain selector, API fixture, or command contract before polish work. ## Risk: graph manifest becomes another static snapshot Section ID: risk-graph-manifest-becomes-another-static-snapshot Risk: graph manifest becomes another static snapshot Mitigation: include manifest versioning, runtime session IDs, event streams, and tests that compare live graph construction against exported graph documents. ## Risk: command queue can damage source or production Section ID: risk-command-queue-can-damage-source-or-production Risk: command queue can damage source or production Mitigation: apply commands only inside isolated worktrees or controlled deploy jobs, require dry-run diffs, record rollback metadata, and gate destructive operations by RBAC. ## Risk: auth/DB consoles expose sensitive data Section ID: risk-authdb-consoles-expose-sensitive-data Risk: auth/DB consoles expose sensitive data Mitigation: read-only by default, redaction policies, scoped credentials, audit logs, session-aware access, and production write lockouts until secret storage is fixed. ## Risk: agents create unreviewable complexity Section ID: risk-agents-create-unreviewable-complexity Risk: agents create unreviewable complexity Mitigation: agents output findings and typed commands. Human or policy gates approve execution. Git commits are linked to commands and tests. ## Risk: two workbenches diverge Section ID: risk-two-workbenches-diverge Risk: two workbenches diverge Mitigation: desktop Compose and web React must consume the same manifest, command queue, and workbench services. UI differences are allowed; domain differences are not. ## Near-Term Execution Order Section ID: near-term-execution-order Near-Term Execution Order Create WorkbenchManifest and update ReaktorGraphDocument.kt to produce the first version from BestBuds. Add /workbench/apps/{appId}/manifest and a small web fetch layer in targets/reaktorWeb. Migrate Graph, sidebar, search, and inspector summary from static scenario data to the manifest. Implement command queue storage and make all mock mutating actions create queue records instead. Wire Testing tab to the existing tests/ inventory and run at least Playwright suites through a real runner API. Wire Auth and Database tabs read-only to real catalogs, then add command-backed mutations. Make Gemini scout real as a read-only job that reports findings and proposes commands. Generated from a scan of /Users/ovd/dev/reaktor, /Users/ovd/dev/bestbuds/modules/app, /Users/ovd/dev/bestbuds/modules/engine, /Users/ovd/dev/bestbuds/targets/reaktorServer, and /Users/ovd/dev/bestbuds/targets/reaktorWeb. Place: /Users/ovd/dev/bestbuds/roadmap-codex.html. ## Related docs Section ID: related-docs Related docs Strategic Roadmap - Use for strategic framing and product sequencing. Implementation Plan - Use when converting roadmap intent into engineering tracks. Graph Kernel - Use to keep the core language small while modules add vocabulary. Control Plane - Use when exposing Reaktor safely to humans and agents. Workbench Gaps - Use when prioritizing visible workbench functionality. Framework Overview - Use to understand the full Reaktor model before diving into graph, visitors, modules, control plane, or subsystem docs. # CompanyOS — TypeScript / Vite / Reaktor Migration Plan URL: https://reaktor.build/docs/companyos-migration-plan Status: unverified Content revision: 488ab48b32b51442a9dbaf3c490c35cf15511df4fda77490ea0449cedf63c6e5 Verification: {"at":null,"revision":null,"evidence":[]} Sources: [] Graph declarations: {"ports":[{"id":"page","anchor":"","label":"Document","profile":"document","contract":"https://reaktor.build/docs/companyos-migration-plan","polarity":"Neutral"},{"id":"section-situation","anchor":"situation","label":"1. Situation & Goals","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#situation","polarity":"Neutral"},{"id":"section-current","anchor":"current","label":"2. Baseline Architecture & Domain Shape","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#current","polarity":"Neutral"},{"id":"section-stack","anchor":"stack","label":"3. Target Stack — TypeScript + Vite + Cloudflare","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#stack","polarity":"Neutral"},{"id":"section-decompose","anchor":"decompose","label":"4. Decomposition with Reaktor Principles","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#decompose","polarity":"Neutral"},{"id":"section-graph","anchor":"graph","label":"5. Reaktor-Graph + Reaktor-Service Adoption","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#graph","polarity":"Neutral"},{"id":"section-browser","anchor":"browser","label":"6. Browser Automation via Cloudflare Browser Rendering","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#browser","polarity":"Neutral"},{"id":"section-dual-runtime","anchor":"dual-runtime","label":"6a. Dual-runtime execution — local Playwright ↔ Cloudflare DO","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#dual-runtime","polarity":"Neutral"},{"id":"section-agent-drive","anchor":"agent-drive","label":"6b. Agent-driven operation — Claude / Codex","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#agent-drive","polarity":"Neutral"},{"id":"section-recipes","anchor":"recipes","label":"7. Automation Recipes","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#recipes","polarity":"Neutral"},{"id":"section-perf","anchor":"perf","label":"8. Performance — Lighthouse Profiling & Acceleration","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#perf","polarity":"Neutral"},{"id":"section-tests","anchor":"tests","label":"9. Tests — Using & Refining Codex's Suites","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#tests","polarity":"Neutral"},{"id":"section-phases","anchor":"phases","label":"10. Migration Phases","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#phases","polarity":"Neutral"},{"id":"section-risks","anchor":"risks","label":"11. Risk Matrix","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#risks","polarity":"Neutral"},{"id":"section-decisions","anchor":"decisions","label":"12. Open Decisions","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#decisions","polarity":"Neutral"},{"id":"section-appendix","anchor":"appendix","label":"13. Appendix — File / Action Map","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#appendix","polarity":"Neutral"},{"id":"section-tier-a-incremental-in-browser-graph-runtime","anchor":"tier-a-incremental-in-browser-graph-runtime","label":"Tier A (incremental): in-browser graph runtime","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#tier-a-incremental-in-browser-graph-runtime","polarity":"Neutral"},{"id":"section-everything-from-reaktor-map","anchor":"everything-from-reaktor-map","label":"Everything-from-Reaktor map","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#everything-from-reaktor-map","polarity":"Neutral"},{"id":"section-related-docs","anchor":"related-docs","label":"Related docs","profile":"section","contract":"https://reaktor.build/docs/companyos-migration-plan#related-docs","polarity":"Neutral"}],"relations":[{"id":"companyos-migration-plan:references-reaktor-service","kind":"references","owner":"companyos-migration-plan","incidences":[{"node":"companyos-migration-plan","port":"section-graph","role":"source","ordinal":0},{"node":"reaktor-service","port":"page","role":"target","ordinal":0}]},{"id":"companyos-migration-plan:references-reaktor-graph-migration-plan","kind":"references","owner":"companyos-migration-plan","incidences":[{"node":"companyos-migration-plan","port":"section-tier-a-incremental-in-browser-graph-runtime","role":"source","ordinal":0},{"node":"reaktor-graph-migration-plan","port":"page","role":"target","ordinal":0}]},{"id":"companyos-migration-plan:references-reaktor-work","kind":"references","owner":"companyos-migration-plan","incidences":[{"node":"companyos-migration-plan","port":"section-everything-from-reaktor-map","role":"source","ordinal":0},{"node":"reaktor-work","port":"page","role":"target","ordinal":0}]},{"id":"companyos-migration-plan:references-reaktor-surface-renderers","kind":"references","owner":"companyos-migration-plan","incidences":[{"node":"companyos-migration-plan","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-surface-renderers","port":"page","role":"target","ordinal":0}]},{"id":"companyos-migration-plan:references-performance-observability","kind":"references","owner":"companyos-migration-plan","incidences":[{"node":"companyos-migration-plan","port":"section-related-docs","role":"source","ordinal":0},{"node":"performance-observability","port":"page","role":"target","ordinal":0}]},{"id":"companyos-migration-plan:references-shadow-dev-environment","kind":"references","owner":"companyos-migration-plan","incidences":[{"node":"companyos-migration-plan","port":"section-related-docs","role":"source","ordinal":0},{"node":"shadow-dev-environment","port":"page","role":"target","ordinal":0}]},{"id":"companyos-migration-plan:references-reaktor-surface-design-and-ownership","kind":"references","owner":"companyos-migration-plan","incidences":[{"node":"companyos-migration-plan","port":"section-related-docs","role":"source","ordinal":0},{"node":"reaktor-surface-design-and-ownership","port":"page","role":"target","ordinal":0}]}]} ## CompanyOS — TypeScript / Vite / Reaktor Migration Plan Section ID: preamble Public migration plan. This page documents the CompanyOS migration direction that is safe to publish: the TypeScript/Vite cutover, Reaktor decomposition, graph/service adoption, browser automation shape, performance harnesses, and phase gates. Private operational details remain in the local-only private runbooks. Target: targets/companyOS (companyos-bestbuds) → company.bestbuds.ai. Authoritative code-side doc: bestbuds/AGENTS.md (the repo guide). If this plan and the code disagree, the code wins — verify before acting. Compiled: 2026-06-05. Updated: 2026-06-07. Status: TS/Vite, the typed CompanyOS service contract, Browser Run-backed portal session plumbing, and the Cloudflare Workflow DAG runner are now landed in targets/companyOS. The CompanyOS Playwright suite and data-hygiene checks are the migration's acceptance gate (§9). Contents Situation & Goals Baseline Architecture & Domain Shape Target Stack — TypeScript + Vite + Cloudflare Decomposition with Reaktor Principles Reaktor-Graph + Reaktor-Service Adoption Browser Automation via Cloudflare Browser Rendering 6a. Dual-runtime execution — local Playwright ↔ Cloudflare DO 6b. Agent-driven operation — Claude / Codex Automation Recipes Performance — Lighthouse Profiling & Acceleration Tests — Using & Refining Codex's Suites Migration Phases Risk Matrix Open Decisions Appendix — File / Action Map ## 1. Situation & Goals Section ID: situation 1. Situation & Goals CompanyOS is the BestBuds Ventures portal-orchestrator / back-office cockpit: company pulse, finance & runway, people/payroll, cap table & equity, contracts, compliance DAGs, a portal control room, Browser Run session control, and an evidence/audit trail. It is the single-tenant operating surface for the Compliance OS product thesis. ## Baseline snapshot (2026-06-05) Section ID: baseline-snapshot-2026-06-05 Baseline snapshot (2026-06-05) This was the starting point that the migration plan was written against. The 2026-06-07 implementation snapshot below records the parts now landed. Area Baseline size / shape Delivery Build-free static SPA: public/ served verbatim; no bundler, no node_modules, no build step Runtime React 18.3.1 UMD + @babel/standalone compiling JSX in the browser on every load, all from unpkg.com CDN Source ~8.7k lines: 20 .jsx screens/shell/store + 6 .js data/auth + 1 Worker State A single useReducer "god store" (store.jsx, 308 lines, ~25 action types) Data window.MANNA global, assembled from data*.js (incl. data_archive.js, 2,836 lines inline) Routing None — state.screen string + a SCREENS map; the site is a single / route Types None (plain JS/JSX) Auth Cloudflare Worker BFF (src/index.js, 526 lines): Google OIDC → reaktor-auth token exchange, HTTP-only cookie session, server-side refresh, tenant + RBAC gate Tests New Codex Playwright suite at tests/companyOS/playwright/ (see §9) ## Current implementation snapshot (2026-06-07) Section ID: current-implementation-snapshot-2026-06-07 Current implementation snapshot (2026-06-07) Area Landed shape Delivery companyos-bestbuds now builds through TypeScript + Vite with worker/index.ts and dist/client assets. Service contract src/core/service/companyOSService.ts defines stable CompanyOS.* operations for graph queries, portal sessions, and workflow runs; the Worker routes through the shared Reaktor service router. Browser Run PortalSession is a Durable Object backed by the BROWSER binding; it keeps the Cloudflare browser session id, reconnects with Playwright connect(), streams screenshots over WebSocket, and explicitly closes the browser on session close. Workflow DAGs src/core/workflow/dagPlanner.ts validates DAGs, rejects cycles/missing edges, topologically orders steps, and classifies sensitive nodes as human gates; worker/dag-workflow.ts executes the plan through Cloudflare Workflows. Runtime API CompanyOS.Workflow.Plan, Start, Get, and SignalGate are mounted under /api/workflows/*, with a local-plan fallback when the Workflow binding is absent. Local runtime Headed local Playwright session with CDP take-control: scripts/portal-session-headed.mjs opens a real Chromium (operator logs in), scripts/portal-session-drive.mjs attaches via connectOverCDP and drives to the next gate; shared hand-back machine scripts/lib/session-machine.mjs. Verified end-to-end (attach → auto → gate-suspend → resume). GST adapter scripts/portal-adapters/gst.mjs — login autofill (real selectors) + GSTR-3B step list with encoded human gates (data / approval / dsc); .env/Keychain secret resolver scripts/lib/secrets.mjs (GST_USERNAME/GST_PASSWORD, git-ignored). Tests The CompanyOS Playwright suite covers the shared service contract, Worker routing, Browser Run wiring, Workflow binding, DAG planning, and human-gate safety. ## Goals (this plan) Section ID: goals-this-plan Goals (this plan) TypeScript + Vite — kill in-browser Babel + CDN React; real bundling, types, code-splitting (§3). Decompose heavily with Reaktor principles — atomic design, typed ports, actors, small composable APIs; dissolve the god-store (§4). Same move we made on the reaktor engine and other modules. Adopt reaktor-graph + reaktor-service and everything else from Reaktor that fits — reaktor-auth, reaktor-cloudflare, reaktor-db, reaktor-performance, reaktor-telemetry, reaktor-work (§5). Real portal automation on Cloudflare Browser Rendering — replace the session simulation with human-in-the-loop driven browser sessions, behind hard safety gates (§6). Lighthouse profiling + acceleration via the existing reaktor-performance harness, with CI budgets (§8). ## Non-goals / invariants (do not break) Section ID: non-goals--invariants-do-not-break Non-goals / invariants (do not break) The auth contract is frozen. App id 38d1cee3…, tenant 0d72c513…, cookie names (companyos_at/rt/profile), /auth/* routes, SCREEN_PERMISSIONS, role labels, and the companyos:* scope model must stay byte-compatible so scripts/provision-auth.mjs, existing sessions, and the Google OAuth origin keep working. company.bestbuds.ai never goes dark. Every phase ships; the cutover is parallel-scaffold then swap. The human-in-the-loop safety boundary is a product feature, not a gap: CompanyOS never solves CAPTCHAs, never relays/scrapes OTPs, never automates DSC signing; final portal submits require director approval; cookies are discarded on close; no plaintext secrets/OTPs/PINs are stored or logged. These invariants survive the migration and become tests (§9). ## 2. Baseline Architecture & Domain Shape Section ID: current 2. Baseline Architecture & Domain Shape ## Baseline file map (targets/companyOS, pre-cutover) Section ID: baseline-file-map-targetscompanyos-pre-cutover Baseline file map (targets/companyOS, pre-cutover) src/index.js Worker BFF: /auth/config|login|session|logout, ensureSession (refresh), authorize() tenant+RBAC gate, summarizeSession→allowedScreens, run_worker_first public/ index.html loads React/ReactDOM/Babel (CDN) + data*.js + every *.jsx via