Manna HLD — Implementation on Reaktor Graph and Surface

26 September 2026 · Architecture proposal · Revision 4 · Source-grounded implementation plan

This is the canonical Reaktor-site HLD for the updated Manna product design, including the retained full knowledge graph. It specifies how the mobile app and desktop website compose Reaktor capabilities, what can be reused, what must be implemented, and how the existing catalogue moves without losing meaning.

Read with the Framework Overview, Graph Substrate Redesign, Module Review and Surface textbook. The implementation follows those shared primitives while keeping Manna's domain rules and brand in Manna.

The companion Functional Design Handoff contains the expanded 42 desktop and 43 mobile screen specification, complete canvas register and interaction contracts.

1 Architecture decision

Manna’s target architecture is a modular Kotlin Multiplatform application on Reaktor, with a shared domain model and command contracts, native mobile presentation through Surface Compose, and a new desktop website. The full knowledge graph remains a first-class product surface. It will become a navigable, permission-filtered map of all retained knowledge, rather than requiring every record and relationship to be loaded into every client.

The implementation has three cooperating graphs. The domain graph holds knowledge, memories, course structure, evidence, intentions and relationships. The execution graph owns software components, typed ports, actors, services and lifecycles. The presentation graph is a bounded projection used by the map and its inspectors. Stable references connect them; a chapter or note does not become a permanently running actor. This is the distinction required by the updated product specification, section 17. S01

The server plane is shared Reaktor Server plus Cloudflare Workers, composed with the rest of the Reaktor stack. Reaktor Server supplies reusable auth, graph-database access and other qualified platform services to many Reaktor apps. It may also mount narrow APIs for in-house apps such as BestBuds and Manna. Keep the host's hardcoded domain knowledge minimal: Manna policy belongs in Manna-owned modules, generic capabilities belong in Reaktor, and the host assembles their typed services. Sharing infrastructure does not merge app identities, ownership or private records. A separate Manna JVM server is not the target.

The proposed target uses Supabase PostgreSQL for transactional records and their change log, R2 for original artifacts, Memgraph for graph traversal and map projections, and derived search indexes for retrieval. Retain the existing graph data and reusable Memgraph deployment. Stop legacy writers, capture a verified authoritative snapshot and transform it in an isolated namespace before transferring ownership. Canonical-record migration does not require replacing the provisioned graph service or discarding its data. Only the new command service accepts product writes after cutover.

The first useful release connects capture, exact retrieval, one course, one mission, a small learning loop, simple rhythms and the full graph. Population-scale learned ranking, arbitrary generated interfaces, distributed runtime hot replacement and a universal sync engine are not prerequisites.

2 Existing implementation and reuse

This baseline comes from the local source tree inspected on 26 September 2026. The inspected HEADs were BestBuds b831f8bb, Reaktor 6972db56 and Manna 2cb36aa; uncommitted changes were present. These identifiers anchor the review but do not describe an immutable build of the inspected working trees. No production capacity or deployment qualification is inferred from source inspection.

The generic Reaktor Graph Protocol document explicitly identifies itself as a specification. Manna will not require its proposed mesh or credited streams to deliver the product. Likewise, Conductor's local workspace execution is not a delegated multi-user authorization service. S12, S15

3 System structure

Open diagram at full size

Reaktor Server, currently hosted at BestBuds targets/reaktorServer, is the shared JVM host on the existing k3s plane. The repository location does not make it a BestBuds-only backend. Cloudflare Workers are the edge and distributed service hosts in the same server plane. Services use Reaktor Graph, typed ports, Service/Request/Response contracts, actors and adapters across those hosts. Start with explicit build-time composition of qualified modules; a new dynamic plugin system is not a prerequisite.

For example, auth registration and graph query execution are reusable platform capabilities. A Manna course-evidence command is an app API: its adapter resolves an admitted application scope and invokes Manna's policy handler through typed ports. BestBuds can mount its own APIs using the same auth and storage substrate without introducing Manna's course rules into the generic graph gateway.

The default placement for domain transactions, pooled graph access and substantial server work is Reaktor Server's JVM modules. Use Workers for edge-specific services and workloads that fit existing Worker/coordination capabilities. Each command has one registered authoritative handler, whether it runs on JVM or a Worker; other hosts delegate through its contract. Jobs may have separate process roles when measured isolation or scaling needs justify them, while remaining part of the shared Reaktor server plane.

Both hosts validate their trust boundary. Derive application, tenant, principal and delegated scope from verified credentials plus registered configuration; never select another app's data from an untrusted request field. An upstream service credential authenticates the hop, not unrestricted authority on behalf of a person. Apply bounded query policies, per-app budgets and scoped caches. Shared graph-database access is not public arbitrary-query access. The existing fixed tenant/audience routes require qualification and adaptation before serving this broader app model. S14

Memgraph and search answer derived queries. A response carries its source watermark, projection generation and authorized scope. Newly committed writes may be visible immediately through the transactional read model while a map overlay reports that indexing is pending. The application never labels an old source current merely because an API request just completed.

4 Code ownership and package plan

The following package layout is proposed. We start with logical packages and extract build modules only where platform boundaries or independent consumers require them.

Reaktor's generic canvas boundary remains compose-flow → reaktor-flow → product host. Manna imports graph facilities through the supported Reaktor façade. Product concepts such as capability evidence or chapter coverage do not enter the generic canvas. The existing TypeScript ScopeGraph implementation remains a useful web adapter; common query and projection fixtures will prevent it and the Compose path from drifting. S05, S07

The BestBuds build already has an optional Manna composite-build hook. Use the composition/build boundary to assemble Manna server modules into Reaktor Server and integration tests without making BestBuds product or workbench code a dependency of the Manna mobile app. Keep app contract versions, schema ownership, migrations and release gates identifiable inside the shared host. Reaktor Server's current engine dependency is existing coupling to reduce where practical, not a pattern to extend. S02, S14

Reaktor capability mapping

Use small runtime scopes for the active workspace, mounted routes and bounded jobs. Candidate owners include a continuation controller, a capture upload actor, a rhythm planning actor and an effect reconciliation actor. Persist workflow state outside actor memory; a restarted activation loads its checkpoint and lease before continuing. Do not allocate an actor for every knowledge entity or serialize all users through one global mailbox.

Start remote contracts with versioned JSON and explicit limits. Generate or maintain conformance-checked TypeScript projections of Kotlin contracts rather than hand-copying domain rules. Adopt binary codecs only for measured hot paths, retaining a readable inspection form and compatible schema negotiation.

Graph composition, ports and lifetimes

Open diagram at full size

MannaGraph owns session hydration, platform capability offers, target adapters and workspace navigation. A WorkspaceGraph(workspaceRef) binds the permitted repositories, query providers, command gateway and continuation state. Feature graphs compose Home, Memory, Courses, Missions, Rhythms, Map, People and Ask Manna through typed RouteBinding entries. They share references and contracts rather than reaching into another screen's controller.

provides / consumes and autoWire() compose a scoped provider set. Resolve the active workspace's bindings before considering any fallback; a missing private provider must never silently select a public or different-tenant provider. Graph construction validates required ports and reports missing capabilities explicitly. The Graph Kernel, Component Lifecycle and Actor Model supply the shared model.

Use controllers/interactors for pure orchestration and screen state, ServiceNode for typed remote boundaries, and actors for work whose state transitions must serialize. Capture upload, an active learning session and effect reconciliation are useful actor responsibilities. Pure course coverage or graph filtering can remain ordinary functions. A workflow does not gain durability merely because it runs in an actor mailbox.

When a route detaches, cancel its subscriptions, viewport requests and media handles. Retain the draft, source position and continuation checkpoint through the durable owner. Background jobs continue only after explicit admission to that owner; a new activation recovers its lease and checkpoint. Supervision may restart a local actor, while the command/effect ledger prevents repeating already accepted work. This separates runtime lifecycle from the user's promise that a capture will survive process loss.

Typed maps, visitors and source ownership

The domain graph, runtime graph and map scene share references without pretending to be the same objects. A selected chapter can join to its exact source, course coverage, owning query operation and observed request trace. A definition reference identifies the code contract; an activation reference identifies one running instance. Changing an overlay never changes those underlying identities.

Use bounded visitors for dependency closure, course coverage, provenance inspection, correction impact and authorized map projection. Each pass declares input revisions, relation kinds, depth/result budgets and output provenance. It returns facts or a proposed patch. A correction-impact visitor can nominate recomputation work, but only the owning command handler commits it. It must not mutate records while traversing them.

The wider immutable graph IR, unified visitors and visual compilation paths in the Graph Substrate design are evolving framework work. Manna starts with stable domain schemas and adapters over implemented runtime/document APIs. New generic schema, selection, patch or observation primitives belong in Reaktor and receive shared conformance tests. Product concepts such as rhythm qualification, chapter completion and evidence strength remain Manna policy.

Capability offers and deliberate fallback

Capability discovery describes what a target can do; identity, consent and execution policy decide what it may do. Store the selected capability strategy with the operation where it affects interpretation. Never infer capability parity from a multiplatform declaration alone. Follow Reaktor capabilities and the Surface application patterns.

5 Domain model and identity

Open diagram at full size

Every durable entity has a namespaced identity, owner scope and revision. A reference identifies an entity and, where required, an exact revision or source selector. Display labels, database internal IDs, renderer paths and array positions are not portable identity.

A relationship is independently identifiable and versioned. It retains its exact endpoints, direction, kind, conditions, explanation and provenance. Parallel relationships and self-relations are preserved where valid. Presentation bundling never changes the semantic relation.

A legacy chapter identified by resource key and ordinal receives a stable unit identity scoped to the imported source edition. The import ledger retains the original ordinal and key. Later reordering changes order metadata, not the identity of the chapter or historical evidence. Reading order, prerequisite, optional supplement, related concept and demonstrated capability remain distinct relation kinds.

Identity merges are reviewed mappings, not destructive record replacement. Exact, broader, narrower, related and possible-match mappings retain their meanings. An accepted merge preserves aliases and the original source objects, records its proposal and receipt, and invalidates dependent projections. Reversal restores identity resolution without deleting the historical decision.

6 Storage and consistency

Authoritative ownership

The proposed target stores personal state, commitments, consent, evidence, agreements, domain revisions and canonical relation records in PostgreSQL. Ownership and scope fields are mandatory; queries and applicable row policies enforce them. Flexible versioned payloads can supplement typed columns, but cannot replace constraints for identities, ownership, revisions and money-related records.

R2 holds original audio, handwriting images, uploaded documents, attachments and exported packages. A source record contains the immutable object reference, digest, media type, rights and processing policy. Media bytes are not embedded in graph nodes. Access uses short-lived, purpose-appropriate grants and private caching rules.

Memgraph becomes a rebuildable typed adjacency and map index after catalogue cutover. PostgreSQL full-text retrieval is the initial search baseline; pgvector or another already-supported vector adapter is added only after evaluating scoped retrieval and invalidation. No new database is required merely to support recommendations.

The frozen catalogue export and retained source database are the migration authority until reconciliation passes. No live legacy gateway is required for the new product. Keep the source database recoverable and use a separate namespace or projection generation for transformation. Preserve existing IDs where compatible and record every necessary mapping. D1 can remain the backing store for retained MCP/OAuth state independently of the old UI; moving that state is a separate, validated decision. Inventory and archive other D1 data before deciding which records enter the new product.

Command transaction

All UI, MCP, AI and automation mutations enter one typed command path. The proposed envelope carries an operation ID, authenticated principal context, owner scope, expected entity revisions, idempotency key, command version and typed payload. The server derives authority from the verified session or delegation; it does not trust client-supplied principal or tenant fields.

Within one owner transaction, a handler checks permission and current revisions, applies the domain change, records its receipt and appends an outbox event. Repeating the same idempotency key and payload returns the original outcome; using the key with a different payload is rejected. A revision conflict returns the current revision and a reviewable conflict rather than overwriting another device's work.

Outbox workers update projections using a durable cursor and event deduplication. They record event time, receipt time, origin, correlation and correction references. Rebuilds run into a new projection generation and switch only after validation. Deletes, revoked grants and retractions generate invalidation work as well as additions.

External effects use explicit states: proposed, authorized, submitted, succeeded, failed or outcome unknown. A network timeout after submission is not proof of failure. Reconcile the provider's request identity before retrying; use provider idempotency where available. Compensation is a separate recorded operation, not a claim of atomicity across systems.

7 The full knowledge graph map

Semantic scale and map behavior

Open diagram at full size

The map must cover the entire authorized knowledge graph while drawing a bounded working set. The default scale ladder is overview areas, topic or project clusters, resources and objectives, units or chapters, and exact source segments with evidence. Users may mix levels by expanding one scope, inspect cross-area links, search directly for a node, bookmark a view and return through breadcrumbs.

Layers select relation families and overlays: knowledge structure, course order, capability requirements, work and dependencies, people and shared scopes, time and activity, and evidence or uncertainty. A layer is a projection policy; it does not create a separate copy of the graph. Filters affect both graph and list results under the same authority and revision.

Reaktor already supplies scope projection, focus, collapse boundaries, layout and graph lenses. The Manna design reuses those semantics with a Manna graph-query provider and scale-aware read models. Current kgToScopeGraph derives some visual edge IDs from array indices and renders resource links through chapter entry points. Those are display choices, not acceptable canonical identities for migration or portable source relations. S05, S07

Bounded query contract

The proposed GraphQuery includes the selected scope, authorized purpose, requested relation families, semantic level, optional viewport bounds, snapshot cursor, depth and result budgets. The service fixes a revision for pagination and returns nodes or aggregate nodes, relationships or bundles, unloaded endpoint references, authorized counts, continuation information, layout generation and evidence watermark.

Authorization is applied before traversal, aggregation, counts, ranking and layout. A cluster must not reveal hidden membership through its label, size, edge count or coordinates. Cache keys include workspace, authorization epoch, projection revision, layer/filter policy and requested region. Revocation invalidates those entries; an unknown authorization state denies sensitive expansion.

Clustering first follows authored domains and project scopes; deterministic structural clustering can refine large areas. Stable cluster identities, pinned landmarks and versioned positions preserve the mental map. A layout worker updates affected regions incrementally. Panning must not trigger a global force-layout pass or relocate unrelated neighborhoods.

Spatial indexes and semantic scope indexes serve visible regions plus a small prefetch margin. Cancel obsolete viewport requests, reuse unchanged scene objects and bound the client cache by bytes and node count. At a coarse level, relationship bundles resolve to their authorized members; expansion retains the original direction and endpoints. A partial result explicitly says more data is available, rather than suggesting the graph ends there.

Rendering and scale qualification

The web implementation starts from the existing controlled ScopeGraphFlow integration and its selection/layer state. The native path consumes equivalent projections through reaktor-flow. A renderer-independent scene contract and shared fixtures are required; a complete React-to-Compose bridge is not.

Native and web rendering keep camera motion, hover, gesture tracking and hit testing local. Use semantic zoom to vary labels and detail, not to query for every animation frame. Larger scenes may require a batched Canvas or GPU renderer behind the same scene contract; choose that only when the existing renderer misses measured budgets.

The map must have keyboard navigation, search, an accessible list, inspectable relation descriptions and essential action parity on mobile. Verification must cover the real migrated graph and synthetic 10× and 100× cardinalities with high-degree hubs, parallel edges and deep scopes. These are load-test sizes, not a promise that the present implementation already serves them.

8 Surface and application state

One state owner and two rendering families

Open diagram at full size

Graph-owned controllers and interactors expose immutable screen models through typed ports and StateFlow. Views emit semantic events such as RecordProgress, OpenSource, ChangeRhythm or AcceptProposal. Components receive models and actions; they do not discover repositories or providers internally.

Surface owns control behavior, local interaction state, accessibility semantics, appearance and motion. Manna owns persistent drafts, navigation entries and domain policy. Existing Surface Draft revision checks help reject stale edit acknowledgments, but do not substitute for durable storage or server concurrency control. S08

Android and iOS use Surface Compose. The browser keeps the existing React host during migration and consumes shared application contracts through a bounded Kotlin/JS subscription adapter. For controls needed by the first release, implement a qualified Surface web realization with the same behavior traces and theme roles. Full React Strict DOM, portable composition and optional interop remain later framework work. Unqualified controls remain explicit gaps rather than being presented as cross-platform parity. S09

React subscriptions must provide stable snapshots for unchanged data and consistent unsubscribe behavior. This follows React's external-store contract; rendering cannot mutate shared application state. React external store reference

Manna appearance and adaptive layout

Create Manna theme tokens from the current Pencil design, with one authored source for color roles, typography, spacing, radii and density. Surface appearances consume them. Reuse the HumanSignalSurface composition pattern, without importing BestBuds branding or duplicating operator Machine Signal tokens. Pencil scenes remain design specifications and test references, never runtime screenshots. S16

Choose layouts from actual available width, input capabilities and local constraints. A desktop supporting inspector becomes a mobile sheet; both bind to the same selected entity. Resizing, route restoration or changing theme must preserve draft identity, scroll anchor, source position and an active session. Motion and optional haptics stay local, respect reduced-motion preferences and stop when the region is hidden.

The map is a specialized canvas inside a Surface shell. Surface provides search, layers, controls, dialogs, sheets and inspector components. The canvas owns camera and scene rendering, while the application graph owns selection, saved views, grants and commands.

Product composition over Surface primitives

Create Manna organisms from the implemented control behaviors: a Capture composer from fields, attachment actions and a revisioned draft; a Course continuation card from progress, source and action models; a Rhythm editor from selection and validation controls; and a Map inspector from tabs, lists, sheets and dialogs. The same organism contracts drive desktop supporting panels and mobile route/sheet layouts. The Surface ownership model and behavior contracts keep interaction state separate from durable application truth.

Manna's tokens feed ThemeSnapshot and Surface appearances. Typography, spacing, contrast, focus visibility, text scaling and motion preference are part of qualification. Layout width is not the only input: touch, keyboard, safe areas, accessibility and available capabilities also matter. A successful press animation indicates contact; a committed receipt establishes success. Persist the draft owner before changing themes, layouts or routes.

If agent-generated UI is introduced later, constrain it to a versioned catalogue of approved organisms and typed actions. Validate the declaration, bindings, permissions and resource budget before activation. Keep trusted consent and destructive-action controls code-owned. Generation failure restores the manual surface and existing draft. This follows the proposed dynamic UI and verification path; arbitrary code generation is not the first-release renderer.

9 Memory and exact sources

Capture commits an original record before optional extraction or classification. The client first persists a local operation and artifact reference; uploads proceed through a resumable object-store adapter. OCR, transcription, parsing and embeddings are derived jobs with model version, source version and processing permission. A failed model cannot make the original note disappear.

A source selector can identify a page and region, text quote with offsets, chapter, video or audio interval, or a provider-native anchor. Resolution checks rights, access and the exact source revision. A changed source produces a broken or remappable anchor state; the system never silently substitutes a different passage. Preserve human annotations and corrections separately from extraction output.

Retrieval distinguishes external claims, personal hypotheses, historical beliefs and current decisions. Search results retain provenance and valid-as-of information. Correcting a transcript or retracting a claim schedules downstream updates to search, context, recommendations and evidence. Tombstones and minimal audit facts follow the retention policy; an append-only log cannot preserve deleted private payloads indefinitely.

The first complete loop is capture → retrieve → exact source → use in a mission → pause → recover. It works without classification, an assessment, or cloud model access.

10 Courses learning and evidence

CourseVersion owns ordered UnitVersions and provider requirements. LearningParticipation records the person's intent and chosen scope. ProgressObservation records manual or provider status and exact resume position. Catalogue search, readable content, playback, progress read and progress write are separate connector capabilities.

Course completion, chosen-path coverage and capability evidence have separate projections and denominators. An independent success can justify an optional skip or route change; it cannot mark an unwatched provider lesson complete. A course revision does not rewrite historical observations. Remapping participation to a new edition requires an explicit mapping and visible gaps.

CapabilityRecipe uses typed requirement expressions: all required branches, alternatives, thresholds where defined, role or tool contributions, and an integration task. Planning evaluates these expressions under context and evidence rules. Ordinary shortest-path search or the current legacy prerequisite BFS is insufficient for composite capability planning.

Attempts reference a task version, artifact, assistance used, collaborators, allowed tools and conditions. Evaluations reference a rubric, evaluator and uncertainty. Estimates are versioned derivations that can weaken after contradictory evidence; an absent attempt remains unknown. A supported outcome and a person's unaided capability are different conclusions even when they cite the same artifact.

Domain packs supply objectives, mappings, reviewed task formats, rubrics, retention or safety constraints and rhythm qualification rules. Start with the illustrated mathematics and ISP workflow. Language and music can support recordings and practice continuity before automated assessment is validated. Unsupported pronunciation dimensions remain unassessed. Exam preparation keeps edition or exam-year scope and distinguishes official requirements from empirical past-paper coverage.

Generated assessment items require review appropriate to the claim. Withdrawal invalidates dependent evaluations and public claims through traceable correction. Practice, Arena rating, professional reliability and published capability do not share one universal score.

11 Missions rhythms and time

Mission owns the desired outcome, next action, acceptance rule, bounded effort and dates. PlanRevision records a baseline, constraints and decisions. Suggestions do not become accepted commitments until the appropriate command succeeds. Shared Reaktor and BestBuds work refers to one actual Session, with separate acceptance evidence for each outcome.

A Rhythm has exactly one ScheduleSpec: quota, calendar recurrence or validated cron. Mode is normal, maintenance, paused or ended; observed adherence is a different value. Qualification includes activity, dose, distinct-day or separation rules and substitution policy. RhythmCredit derives from actual sessions under a particular rhythm revision. Parent totals use the union of sessions and time.

Calendar recurrence retains start time, named zone, rule, additions, exclusions and per-occurrence overrides. One, future and whole-series edits preserve occurrence identity and the original occurrence key. Implement and test RFC 5545 semantics, including invalid local dates and relevant daylight-saving boundaries. A replacement session is separately identified rather than silently altering recurrence history. iCalendar reference

The initial cron import accepts the brief's numeric five-field POSIX profile only. Parse scheduling fields, never shell commands. Reject unsupported seconds/vendor syntax, test day-of-month/day-of-week behavior and document skipped/repeated-clock policies. Quotas retain their own calendar or rolling-window semantics and are not converted into fake cron expressions.

A reusable durable scheduler hosted through Reaktor Server owns the due-work ledger in PostgreSQL; Manna supplies schedule semantics and registered handlers. Leased jobs carry application/tenant scope, schedule revision, occurrence identity, effect key and a fencing token. Execution workers recheck revision and permission before effect submission. Cloudflare coordination or Pub/Sub can dispatch work where qualified, while the durable owner stays explicit. Platform TaskManager handles opportunistic device work; an in-process ActorNode timer does not establish durable scheduling.

Reuse existing notifications and edge coordination where useful. A Durable Object can wake or coordinate work, but it must not become a second owner of the schedule. Its alarms are at-least-once, so they enter the same deduplication path. Cloudflare alarm reference

Missed technical execution uses an explicit skip, coalesce, bounded reschedule or review policy. Human missed sessions do not create mandatory debt. Accepted fixed commitments and protected intervals constrain the planner; infeasibility remains visible rather than being hidden by invented capacity.

12 Recommendations and graph intelligence

The initial recommender is deterministic and inspectable. A request contains purpose, available time, allowed categories, hard constraints, exploration allowance and attention policy. Candidate providers use permitted graph traversal, search, incomplete course position, rhythm opportunities and reviewed capability gaps. Eligibility is checked before candidate generation and again before display or action.

Each decision stores the candidate references, actual selection reasons, policy version, evidence snapshot, displayed slate and validity interval. Exposure is recorded separately from feedback. No response is unknown; a click is not learning gain. Declining a suggestion does not reduce access or become an ability or motivation judgement.

Starting a session pins its intention and selected context. A refresh cannot replace the activity mid-session. Save, not now, not relevant, already know and change direction update the appropriate preference or recommendation record; they do not manufacture evidence or commitments.

Add learned rankers, embeddings or GNN candidate generators behind the same provider ports only after time-based evaluation against the deterministic baseline. Keep model and feature versions, explicit cold-start behavior and rollback. A learned relationship enters a proposal queue and cannot modify prerequisites, permissions or verified claims directly. Exploration and authority checks remain outside the model's discretion.

13 Context AI and bounded automation

Extend the existing ContextPacket contract additively or through a negotiated new version. Include purpose, selected source versions and selectors, permitted output actions, size budget, sensitivity, local-only policy, provenance and expiry. The current packet correctly leaves source revision and freshness unknown when the source cannot prove them; the new implementation must preserve that honesty. S12

Ask Manna retrieves authorized evidence, builds a reviewable context packet, selects an allowed provider, and returns a cited answer or typed proposal. Local-only means the approved local route or an explicit unavailable state. It never silently falls back to hosted inference. Audio retention, runtime processing, personalization and training consent are independently controlled.

Conductor provides useful provider, context and run concepts. Manna's production inference adapter must add end-user tenancy, budgets, content handling and cancellation. The local OS-owner coding-agent host is not exposed as a multi-user server, and consumer CLI sessions are not assumed to be a production inference backend.

An AutomationRule has a versioned trigger, condition, proposed effect, scoped grant, expiry and limits. Domain events nominate rules; a serialized owner workflow checks deduplication, cooldown, causation chain and maximum hops. The resulting action passes through the same proposal, authority and command/effect path as a human action.

The shared attention service reserves optional-notice budget transactionally by person, window and notice identity. It merges rule and recommendation notices, applies digest/quiet/focus policy, and distinguishes accepted commitment reminders. Concurrent rules cannot each spend the entire daily budget. Uncertain delivery is reconciled rather than receiving a new notification identity.

MCP exposes bounded queries and explicit commands over these same services. Keep the existing public catalogue and private workspace distinction. Read-only tool annotations describe behavior but are not authorization. Source text and retrieved instructions remain data, and cannot award payments, expand grants or call external tools.

14 People exchange and BestBuds integration

Integrate BestBuds through typed references and scoped adapters for membership, project participation, communication and accepted responsibilities. Membership in a shared project does not expose private notes, learning history or the entire personal graph. A person can teach in one relationship and learn in another without disclosing unrelated records.

Requests and offers reference capabilities or reviewed external work. Engagement records bind parties, deliverables, time window, permissions and agreed terms. Acceptance changes shared responsibilities only after the required parties act. A private plan remains a personal overlay until explicitly shared.

Arena is a voluntary workflow with a versioned task family, tool policy, labeled AI participants, rubric and rating uncertainty. Public capability assertions require their own evidence path. Creator attribution, usage, eligible agreements, funded obligations and payment receipts are separate records; retrieval or a model response cannot create an entitlement.

Implement these policies in Manna, reusing Reaktor service, auth, media and execution contracts. Reuse BestBuds transport and membership integrations where available; do not import its workbench pane bodies into Manna screens. Payment execution is a later adapter with reconciliation and audit, not a dependency of the initial learning loop.

15 End to end command flows

Course position and a qualifying session

The player or manual progress form writes a ProgressObservation against a specific unit version. The service authorizes the source and participation, rejects stale revisions and commits one observation plus its outbox event. CourseView changes independently from capability estimates. If actual work was performed, a separately identified Session can qualify for a rhythm through its declared rule. One session contributes once even if it supports both a learning intention and a project.

Proposal and external calendar change

The planner reads an authorized constraint snapshot and creates a proposed block. The user reviews the concrete interval, affected calendar, recurrence scope and permission. Acceptance commits the internal decision and pending effect. The connector submits with a stable operation identity. A lost response produces outcome unknown; reconciliation locates the existing provider event before any repeat. The UI distinguishes accepted internal intent from confirmed external placement.

Open diagram at full size

Correction and revoked access

A correction creates a new source or claim revision and a supersession relation. The outbox schedules recomputation of dependent projections. Access revocation advances an authorization epoch immediately; query and context services stop admission even while background cache purges are pending. Clients purge affected cached records when notified or on their next authority refresh. An offline device cannot be promised instantaneous revocation; its permitted offline scope and expiry must be explicit.

Find a source on the map

Search returns a permitted entity reference and its cluster path at a stated projection revision. The map loads ancestor summaries and the bounded target neighborhood, then moves its camera. Opening the node uses the same exact-source command as the list or course view. Unknown source text, broken anchors and partial neighborhoods remain visible.

16 Offline operation and recovery

Persist drafts, selected scope, source position, continuation records and a pending-command journal through Reaktor data adapters. Qualify native SQLite and browser persistence separately; the existing database API is not proof that each target has a complete sync implementation.

Each pending command has a stable operation ID, expected revision, local sequence and visible state. Reconnection reauthenticates, sends bounded batches, deduplicates at the server and receives receipts plus projection cursors. A failed acknowledgement can be retried without creating a second capture or session. Conflicting edits surface both values or an explicit domain merge; there is no blanket last-writer-wins rule for permissions, evidence, source text or commitments.

Offline actions are capability-specific. Local capture, cached-source reading and draft preparation can work offline. New sharing grants, consequential publication, external bookings and payments require current server authorization. A queued offline proposal is not displayed as an accepted shared commitment.

Restore uses a versioned manifest covering records, relationships, aliases, source objects, source selectors, progress, schedule definitions, occurrence identity and evidence lineage. Test restoration into a separate environment, rebuild projections and compare semantic inventories. Deletion policy also governs backups, expiry and any retained minimal audit record.

17 Legacy migration and retained infrastructure

Migration boundary

This is a product replacement with selective infrastructure reuse. The old website, mobile shell, app workflows, background jobs and product API implementations have no uptime requirement during migration. Development can proceed in capability milestones without operating two versions of Manna. Maintenance downtime is acceptable for retained MCP and auth integration as well; preserving them does not promise uninterrupted sessions or traffic.

The retained-asset register is part of P0. For each asset record its current owner, location, dependencies, target owner, retain/adapt/archive decision, export or backup, and acceptance evidence. The following is the baseline, not an exhaustive inventory of production resources.

The current worker co-locates product routes with MCP and OAuth. Retire or replace only the product parts; extract or rehost the retained entrypoints first. The old worker deployment may be replaced by a smaller gateway. Its domain, auth clients and databases are separately owned assets, not disposable side effects of removing its UI. S03

Preserve before transforming

Inventory the authoritative graph and selected product state under the intended workspace identities: resources, editions, ordered chapters, resource and chapter relationships, tasks, goals, schedules, graph documents and personal workspace state. Capture versioned exports, object hashes and schema manifests. Historical README counts and embedded snapshots are not a current authoritative inventory.

Build a deterministic import ledger from legacy namespaces to canonical IDs. Preserve ordinal interpretation, original explanations, synthetic-anchor markers, parallel relations and unmapped values. Quarantine unresolved endpoints and edition conflicts. Existing tasks import as historical or draft intentions unless the owner deliberately recommits.

The current Manna browser projections and GraphQL transformations are reference evidence, not the lossless migration boundary. In particular, array-index visual edge IDs and first-chapter visual routing must not redefine original relationship endpoints. Compare the raw authoritative export with the new model. No running copy of the old website is needed for that comparison. S05

Planned downtime and one new writer

Open diagram at full size

1. Register retained assets. Separate reusable graph, MCP, auth and hosting resources from old product code. Capture recovery material and contract fixtures; identify every writer, including agents, scheduled jobs and graph loaders.
2. Stop and freeze. Take the old app out of service, stop those writers, drain or account for in-flight operations, and capture a consistent final snapshot across the relevant stores. A final snapshot after the freeze is the default; no change feed or live dual-running scheme is required. Retained MCP writes remain disabled until the new write path is ready.
3. Import in isolation. Import into a staging namespace, construct canonical IDs and the import ledger, then build new graph/search projections. Keep the original graph, auth records and restore material intact while validating the conversion.
4. Verify data and retained contracts. Compare counts by kind, exact endpoints, order, properties, aliases, ownership and anchors. Exercise restore and representative paths through the new API, MCP, course, map and export. Check auth client registrations, redirects, identity bindings and public/private isolation against captured contracts.
5. Reconnect retained infrastructure. Point MCP adapters and auth callbacks at the qualified new implementation. Select the reconciled data/projection generation and make the new command service the sole product writer. Existing MCP consumers may reconnect or reauthenticate; new grants must not inherit broader authority accidentally.
6. Launch new Manna. Bring up the new mobile/web experience once its release gates pass. Observe receipts, projection lag and client behavior. Archive retired product code and selected exports; remove obsolete routes/jobs only after confirming that retained assets no longer depend on them. Keep the graph and reusable infrastructure under their recorded owners.

If validation fails before launch, leave the app in maintenance and repair or re-import from the preserved snapshot. Recovery does not require resuming the old product. After launch, preserve new writes when reverting a new release; any data restore must reconcile post-cutover operations. Private records and public catalogue exports are verified separately. Keeping backups and rollback capability is independent of keeping old Manna operational.

18 Performance reliability and operations

These are proposed qualification budgets, not current measurements. Establish the baseline on named mobile devices, browsers and network profiles, then tune without changing the semantic guarantees.

Reuse ReaktorPerformanceHarness, its report/budget models and GraphTelemetry. Correlate operation, entity revision, projection generation, authorization epoch, provider request and effect receipt. Measure query breadth, omitted counts, cache bytes, source lag, callback lifecycle, media decode cost and model cost. Sensitive text, audio, tokens and private graph contents are excluded from default telemetry. S13

Use shared Reaktor Server, Cloudflare Workers and the existing k3s, Supabase, Memgraph, R2, coordination and observability environments. Separate development and production identities, application/tenant namespaces, grants and object prefixes. Deployment recipes build the correct Kotlin/JS or shared-server JVM artifacts, apply app-owned schema migrations, run affected-app contract checks and roll out by workspace. A shared host change must qualify the impacted BestBuds, Manna and generic services; one app's deployment cannot silently change another's authority or schema. New public-read endpoints require an explicit public projection; infrastructure service tokens never make a private query public.

Recovery objectives, backup frequency and retention are release decisions to measure and approve before multi-user rollout. A backup job passing does not establish a successful restore. Offline mobile reminders and server notices must reconcile their delivery identity rather than racing as unrelated channels.

19 Delivery plan and acceptance

The first engineering milestone should be one complete capture-to-source-to-map loop on web and Android, with iOS lifecycle and storage qualification beginning in P0. Desktop Compose is a development harness, not a substitute for the requested website. Milestones are acceptance units rather than ungrounded calendar estimates.

Tests combine pure domain/property tests, shared projection fixtures, service integration, migration/restore rehearsals, Surface behavior traces, Playwright web journeys, native device journeys and performance harnesses. Assertions bind to the exact source revision, target and scope. The Pencil designs specify outcomes and states; they are not evidence that runtime behavior passes.

20 Decisions to settle before implementation expands

The recommended architecture is concrete enough to begin P0. Four decisions require early evidence because they affect compatibility or ownership, rather than ordinary coding choices.

Catalogue authority. Confirm the exact authoritative export source and agree on PostgreSQL canonical records plus a Memgraph projection at cutover. Preserve the existing knowledge graph and provisioned service; keep its frozen source recoverable until reconciliation passes. Old application uptime is not a condition of this work.

Surface web qualification. Prove a revisioned form, list-detail layout and graph inspector in the React host against the native behavior traces. Decide the minimum supported web realization from that evidence; do not make a universal renderer bridge the critical path.

Identity and service registration. Shared Reaktor Server plus Workers is the decided hosting model. Inventory and reuse Manna's auth provider clients, MCP client registrations, application/tenant mappings, domains and bindings. Qualify callback, audience and issuer configuration for each target, and choose the exact app-service registrations and handler placement. App admission must stay scoped even though the host and authentication provider are shared with BestBuds and other Reaktor apps.

Provider and retention policy. Choose the first course, calendar, speech and inference adapters; specify their actual capabilities, rights, local-only support and retention. Unsupported capabilities produce explicit states. Transactional payment work and public assessment claims wait for their own qualification.

The principal delivery risks are loss of legacy relationship meaning, unauthorized derived information, two competing state owners, misleading progress aggregation, non-idempotent effects, and assuming framework plans are already implemented. The architecture addresses them through stable identities, one command path, controlled projections, explicit authority, runtime receipts and phased qualification.

21 Reaktor integration and framework growth

This HLD uses the framework across the full product lifecycle. The table makes additional integration points explicit; conditional capabilities enter only when a Manna journey needs them and the target implementation is qualified. The Module Execution Plan remains the framework-wide work register.

A connected development and verification loop

Represent the product's source/definition reference, target build, application activation, operation ID and related domain references in correlated diagnostic context. The Workbench Layers, Tooling Layer and DevTools describe how the operator can move from a failed user journey to its owning service, state transition and source. Integration starts from qualified existing probes; the proposed Graph Protocol can later carry the same references without becoming a prerequisite.

For example, a capture that remains pending should expose the local receipt, upload attempt, service command outcome and projection watermark. The operator can distinguish an offline device, expired grant, failed upload, accepted command or lagging projection. A test fixture cannot supply the missing live observation. Diagnostic exports redact private content and retain only the necessary scoped identifiers and evidence.

Use deterministic and property tests for graph identity, relationship preservation, AND/OR requirement evaluation, revision conflicts and single-session accounting. Model the small recurrence/effect state machines where exhaustive interleavings help: duplicate wakeup, lease expiry, uncertain provider response, revocation and restart. Formal methods can strengthen those bounded contracts; a model result is evidence about the model until implementation trace conformance is demonstrated.

Framework improvements are pulled through complete Manna journeys: capture and recovery first; source-to-map navigation next; course/session evidence; then rhythm scheduling and scoped assistance. Each slice contributes reusable tests and adapters back to Reaktor. This preserves the full architectural scope while keeping delivery tied to a working product outcome.

22 Source references

Source roots below are the sibling manna, reaktor and bestbuds repositories. Paths identify inspected sources; closed-source paths are references, not downloadable public artifacts. Proposed packages are identified in the HLD. The supplied product brief and Pencil file remain design inputs; their contents are not embedded in this publication.

S01 Product requirements

Supplied Manna-Design.pdf, 47 pages, especially sections 4, 7–11 and 17–19. Pencil design: BestBuds modules/manna.pen; the expanded handoff contains 42 desktop and 43 mobile screens. Owner clarification on 26 September 2026 removes old-app uptime as a migration requirement and retains valuable graph, MCP, auth and infrastructure assets.

S02 Repository composition

BestBuds AGENTS.md and settings.gradle.kts; Manna settings.gradle.kts.

S03 Current legacy API boundary

Manna targets/appWeb/worker/index.ts, worker/mcp/oauth.ts, worker/private-boundary.e2e.test.ts and worker/mcp/server.ts. Revision 3 also checked targets/appWeb/migrations/0007_mcp_oauth_and_workspace.sql and targets/appWeb/wrangler.json for retained OAuth client/principal state, MCP routes and infrastructure bindings. These are source observations, not a live production inventory.

S04 Native baseline

Manna modules/app/src/commonMain/kotlin/dev/shibasis/manna/Manna.kt.

S05 Legacy graph and transformation

Manna targets/appWeb/src/bestbuds-workspace/WorkspaceGraphView.tsx, src/unified-graph/kgToScopeGraph.ts, worker/bestbudsGraphql.ts; Reaktor reaktor-graph-port/ts/src/scope/ScopeGraphFlow.tsx and its scope projection/types.

S06 Graph runtime

Reaktor reaktor-graph-runtime/README.md and src/commonMain/kotlin/dev/shibasis/reaktor/graph/core/Graph.kt, core/node/ActorNode.kt, ServiceNode.kt; Reaktor AGENTS.md.

S07 Graph editor

Reaktor reaktor-flow/README.md; src/commonMain/kotlin/dev/shibasis/reaktor/flow/graph/document/GraphDocument.kt, GraphEditorSession.kt; graph/model/ReaktorGraphLens.kt; schema and editor common tests.

S08 Implemented Surface primitives

Reaktor reaktor-surface/src/commonMain/kotlin/dev/shibasis/reaktor/surface/Behavior.kt, Draft.kt; reaktor-surface-compose/src/commonMain/kotlin/dev/shibasis/reaktor/surface/compose/SurfaceTheme.kt and control implementations.

S09 Surface target architecture

BestBuds targets/reaktorWeb/docusaurus/docs/reaktor-surface.md, reaktor-surface-renderers.md and reaktor-surface-implementation-plan.md.

S10 Persistence and scheduling substrate

Reaktor reaktor-db/README.md, src/commonMain/kotlin/dev.shibasis.reaktor.db/adapters/SyncAdapter.kt; reaktor-work/src/commonMain/kotlin/dev/shibasis/reaktor/work/TaskManager.kt.

S11 Authority contracts

Reaktor reaktor-auth-core/src/commonMain/kotlin/dev/shibasis/reaktor/auth/kernel/AuthKernel.kt and Authority.kt; Manna private boundary and OAuth sources in S03.

S12 Context and agents

Manna targets/appWeb/worker/mcp/context.ts; Reaktor reaktor-conductor/README.md, especially Manna context and local-data limitations.

S13 Services and observation

Reaktor reaktor-service/src/commonMain/kotlin/dev/shibasis/reaktor/service/Service.kt; reaktor-telemetry/.../GraphTelemetry.kt; reaktor-performance/.../ReaktorPerformanceHarness.kt, ReaktorPerformanceModels.kt and ReaktorPerformanceBudgets.kt.

S14 Hosting and control plane

BestBuds targets/reaktorWeb/docusaurus/docs/reaktor-workbench-layers.md and AGENTS.md infrastructure sections. Revision 4 also inspected targets/reaktorServer/src/main/kotlin/ai/bestbuds/server/ServerApplication.kt, GraphGateway.kt, MannaKnowledgeGraphGraphQl.kt, ReaktorInit.kt and targets/reaktorServer/build.gradle.kts. They show the current shared auth/app/graph host, Manna-specific GraphQL, fixed tenant/audience wiring and engine dependency. The owner clarified the intended multi-app server plane as Reaktor Server plus Cloudflare Workers with minimal hardcoded domain logic.

S15 Planned Graph Protocol

BestBuds targets/reaktorWeb/docusaurus/docs/reaktor-graph-protocol.md.

S16 Theme composition example

BestBuds modules/design/src/commonMain/kotlin/ai/bestbuds/design/surface/HumanSignalSurface.kt.

External interface references checked for this HLD: Cloudflare Durable Object alarms, RFC 5545 iCalendar, and React useSyncExternalStore.