Runtime Architecture Review

Status: Historical architecture review. Non-normative.

This narrative consolidates the runtime architecture discussion that followed the Web, Android, iPad, and Cardboard runtime work. It is an architecture review memo, not a runtime contract. The normative runtime contract remains Runtime Contract. This memo records the design question that must be resolved before the platform keeps expanding runtime behavior around assumptions that may not hold.

Use this memo as historical context only. It is not active planning guidance, and no existing runtime described here is a design authority for the current runtime dataset rebuild.

1. The Pattern That Emerged

Over the past several months, Elonn has evolved by building multiple runtimes while also trying to define the architecture those runtimes consume. Web came first as the most practical reference runtime. Android followed. iPad added another device class. Cardboard then forced the architecture into a much less forgiving environment, where camera passthrough, stereoscopic rendering, field projection, limited interaction, Bluetooth mouse input, zoom, parallax, and compact spatial UI made every unclear assumption visible.

At first, each runtime problem appeared to be a local implementation issue. The Cardboard camera view became one image when it should have been split with parallax adjustment. The center stack rendered as isolated objects instead of full panels moving one behind another. The right rail filled with labels and oversized controls instead of useful contextual navigation. Mouse clicks did not land. Service buttons appeared where right rail navigation should have been. Messages lacked clear recipient addressing. Panel actions were unclear. The runtime contract used terminology that seemed precise until a new runtime interpreted it differently.

Those issues were frustrating because they looked like failures of attention, but the deeper pattern was architectural. Each new runtime exposed ambiguity in the conceptual model rather than merely exposing platform-specific bugs. Web, Android, iPad, and Cardboard all had to answer the same question in different ways: what is the runtime actually consuming?

Historically, the answer has been "surfaces." Surface language appears throughout the architecture. The center stack is a stack of surfaces. The left rail contains surfaces. The right rail contains surfaces. Findings become surfaces. Translated web resources become Surface Objects. Panels load into surfaces. Surface persists placement, focus, order, and member-specific runtime state. World composes surface_runtime into /world/session. Runtimes render surfaces.

That answer worked tolerably while the product was mostly imagined as panels on a screen. It became less stable as Elonn moved toward field rendering, XR, Cardboard, and future spatial runtimes. A place in the field is not obviously a surface. A marker is not obviously a surface. A message thread can be a rail row, center panel, notification, object in space, compact preview, or spoken prompt. A future avatar or holographic annotation should not need to pretend to be a panel-shaped surface in order to exist.

The runtime work therefore raised a more fundamental question: is Surface actually the right architectural primitive?

2. The Original Runtime Architecture Problem

The intended Elonn architecture has a strong core idea. Services own domain truth. World is the only runtime-facing composition boundary. Surface owns durable presentation state. Runtimes adapt the World contract to a device. In that model, a runtime should never need to call Social, Messages, Time, Maps, Find, API, or Surface directly. It should not need to know where a conversation is stored, how a finding was produced, how a place was resolved, how a message thread is persisted, or how a calendar entry is mirrored. The runtime should receive a complete contract from World and render it.

That direction is sound. The problem is that the implementation and the documentation still contain competing interpretations of the model.

The Runtime Contract says every runtime implements a shell: lower dock, center stack, left rail, right rail, field layer, and finding overlay. The center stack is supposed to be a stack of full surfaces, not a list of object cards or compact previews. The right rail is supposed to contain contextual surfaces matching the active center surface or active workspace. World and Surface are supposed to supply canonical rail content; runtimes are not supposed to infer right rail navigation from a center panel's nav field.

But the code and behavior show that the contract is not yet fully decisive. Web still contains significant right-context construction logic. It can synthesize rail surfaces from panel navigation, field controls, find composer data, or fallback profiles. Surface seeds default right rail surfaces for Social, Calendar, Messages, Field, and Find. Services publish panel payloads with nav, actions, and URLs. World relays many service routes and rewrites actions. Cardboard and Android have their own normalization and interpretation layers.

That means the runtime contract is partly declarative and partly reconstructed by existing runtimes. A new runtime still has to infer behavior from Web, Android, or Cardboard. That violates the project goal: a new runtime should be buildable from the contract, service contracts, examples, and conformance checks without reading existing runtime code.

The right rail became the clearest symptom. It was supposed to be a contextual UI region. Instead, it became a collision point between service panel payloads, Surface defaults, World route relays, runtime fallback logic, and UI rendering choices. Some entries were labels instead of actions. Some actions were raw URLs. Some content duplicated panel titles. Some controls were oversized. Some items were not clickable. Some service buttons appeared in the wrong place. The right rail did not make sense because the architecture had not defined what kind of thing it was.

The center stack exposed the same issue in another form. The expectation was clear: full panels one behind another, moving like a vertical carousel. But if the runtime receives surfaces, panels, objects, payloads, and service hints without a clean hierarchy, the renderer can easily collapse the stack into isolated cards or object fragments. The bug is visual, but the cause is conceptual.

Messages revealed the same boundary problem at the service level. The service should own message threads, recipients, messages, and message actions. World should compose and route those into the runtime contract. Runtime should render them. But the payload shape mixed domain data, panel state, navigation rows, action URLs, form descriptors, guidance text, and selected-thread state. That made it hard to distinguish service truth from runtime presentation.

The recurring failure is not that Elonn lacks code. It is that the platform has not cleanly separated domain objects, runtime objects, presentation containers, layout state, and rendered UI.

3. The Surface/Object Boundary

The Surface/Object boundary is now the primary design question.

A surface is currently treated as a durable runtime entity. It has identity, title, type, service binding, content source, runtime state, permissions, rendering hints, placement, focus, stack membership, and commands. It can be stacked, opened, translated, detached, reordered, or focused. That is useful, but it is not the same thing as the underlying product concept.

A message thread is not a surface. A conversation is not a surface. A calendar appointment is not a surface. A task is not a surface. A place is not a surface. A finding is not inherently a surface. A member profile is not inherently a surface. Those are domain objects.

A domain object is the thing Elonn actually knows about. Services should own domain objects. API owns members and identity. Messages owns message threads and messages. Social owns profiles, communities, conversations, social events, replies, presence, and Social DMs. Time owns calendars, appointments, and tasks. Maps owns field data and places. Find owns queries and findings. These concepts remain valid no matter how any runtime presents them.

A runtime object is a normalized, runtime-safe representation of a domain object. It carries identity, type, title, summary, relationships, safe content, capability hints, and semantic actions. It does not expose service database details, arbitrary HTML, scripts, provider response formats, or runtime-specific UI decisions.

A presentation object is how a runtime chooses to show something. It might be a panel, card, list row, marker, annotation, 3D mesh, hologram, notification, avatar label, voice response, or something not yet invented.

A surface should be narrower than all of those. A surface should mean a durable presentation container: a member-scoped place where one or more runtime objects may be carried, focused, arranged, persisted, shared, hidden, pinned, detached, or anchored. A surface is not the fundamental content primitive. It is a workspace/container primitive.

This distinction matters because a surface-centered architecture applies pressure to make every visible thing a surface. A field marker becomes a surface. A rail item becomes a surface. A find composer becomes a surface. A right rail control group becomes a surface. A translated web page becomes several surfaces. Eventually "surface" means anything visible, which makes it too broad to guide implementation.

An object-centered architecture is more durable. A place can exist as a domain object from Maps or Find. World can normalize it as a runtime object. A runtime can show it as a field marker. If the member opens it, World can attach workspace state and possibly associate it with a durable surface/container. The same object can later appear in a rail, center workspace, field annotation, or 3D scene without changing its identity.

That model also handles future spatial computing more naturally. A hologram should not need to be called a surface. An avatar should not need to be called a panel. A field marker should not need to be a stack item. The runtime should receive meaningful objects and presentation context, then render those objects according to capability.

So the architectural center should not be Surface. It should be domain objects normalized into runtime objects, composed by World with workspace and authority context. Surface, if retained, should be a supporting primitive for durable presentation/container state.

4. Services, World, and Runtime Responsibilities

Under a cleaner model, services own domain concepts, domain state, domain actions, and domain permissions. They do not own rendering. They do not know whether a runtime will represent their data as a panel, marker, list item, notification, hologram, 3D object, field annotation, or any future primitive.

That means service interfaces should become less panel-shaped.

Messages should publish message threads, participants, messages, recipient options, unread state, and semantic actions such as start thread, send message, select thread, or mark read. It should not need to publish right rail navigation. Social should publish profiles, communities, conversations, social events, Social DMs, presence, discovery relationships, visibility, and social actions. Time should publish calendars, appointments, tasks, recurrence, reminders, authority, and available commands. Find should publish findings, query state, provider context, ranking, source metadata, and finding actions. Maps should publish field objects, places, coordinates, bearings, attribution, field width, and spatial context.

World should then become the true composition authority. It should not merely relay service panel payloads. It should compose domain objects, relationships, authority, workspace context, action routing, and runtime-safe object representations. World is where cross-service meaning belongs: a Social event mirrored into Time, a Messages thread tied to API member identity, a place finding opened into field or carry context, a member appearing across Social and Messages, a Find result becoming an object the runtime can act on.

World should compose an object graph plus workspace context. It should know which objects are relevant to the member and runtime session, what actions are available, what relationships exist, what workspace or field context applies, and what durable presentation state has been saved. It should publish that as the runtime contract.

Runtime then owns presentation. It decides whether an object becomes a panel, marker, row, card, mesh, annotation, or other native representation. Runtime owns rendering, interaction, gestures, projection, animation, local input, camera behavior, parallax, zoom, accessibility, and platform controls. Runtime should not infer service semantics from URL strings, service IDs, hardcoded renderer names, or panel nav arrays.

This model clarifies what the runtime should receive. It should receive normalized runtime objects, semantic actions, relationships, workspace state, placement context, and capability-compatible hints. It should not receive service-specific HTML or panel-shaped service payloads as the primary contract. Panel content may remain as one possible content body, but a panel is not the architecture.

The contract should therefore become object-first and presentation-context second. Surfaces should appear only where durable presentation containers are actually needed.

5. Re-examining surface.elonn

The most difficult unresolved question is whether surface.elonn is needed as a separate service.

The strongest argument for Surface is that it owns durable member-specific presentation state. That includes saved placement, stack membership, focus, order, opened/carried state, pinned state, hidden state, sharing, anchoring, and cross-runtime continuity. If those are truly independent platform concerns, then a Surface service can be justified as a bounded context.

But that argument only works if Surface owns information that no other layer should own.

Services already own identity-adjacent domain permissions and domain actions. World already owns runtime composition, authority, cross-service integration, workspace context, and routing. Runtime owns panels, markers, 3D meshes, interaction, rendering, and device adaptation. If Surface mostly translates domain objects into another representation called surfaces, it is not adding a durable source of truth. It is a middle layer.

That does not prove Surface should be removed. It means Surface must be evaluated by ownership, not by inertia.

If durable workspace state belongs in World, Surface as a separate service may not be necessary. World could store that a member has object X open in workspace Y, object Z focused, a place field anchored, a thread carried, or a container saved at a placement. In that model, "surface" becomes a World-owned workspace/container record, not a separate service.

If durable presentation state is complex enough to deserve its own authority, Surface may remain, but it should be narrowed. It should not seed service-specific right rail content. It should not own domain translation. It should not create product-specific runtime defaults. It should only own durable presentation/container state.

The translation role is especially suspect. Translating a web resource into a runtime-safe object is not obviously the same responsibility as storing stack order and placement. Web resource translation may belong to Find, to a dedicated extraction/translation service, or to World composition. It does not naturally belong with presentation persistence unless the architecture explicitly defines Surface as the authority for runtime-safe object materialization. That would be a much broader claim than "Surface owns stacks and placement."

The right question is therefore not "can we delete Surface?" The right question is: what unique truth does Surface own?

If the answer is durable workspace/container state, decide whether that belongs inside World or justifies a separate service. If the answer is translation, that likely belongs elsewhere. If the answer is renderable versions of service objects, that is probably World composition. If the answer is panels, rails, and stack defaults, that is not a clean service boundary.

The concern is valid: Surface may have been created because the architecture was missing a concept, not because the platform needed a separate service. The missing concept was durable workspace presentation state. That concept is real. The open question is whether it deserves a service boundary.

6. Existing Runtimes Are Not Precedent

The existing runtimes should not be used as design sources for the future architecture.

Web is not the reference outcome. Android is not the reference outcome. iPad is not the reference outcome. Cardboard is not the reference outcome. Each runtime is useful evidence because it exposed ambiguity, coupling, and missing platform concepts. None of them should answer architectural questions by precedent.

The correct question is not:

How does Web render this?
How does Android handle this?
How does Cardboard arrange this?

The correct question is:

What object exists?
What can the member do with it?
What state must persist?
What context is required?
What authority governs the action?
What capabilities does the target runtime have?
What translated presentation best satisfies those semantics?

This matters most for rendering behavior. The current top dock, bottom dock, left rail, center stack, and right rail are not universal rendering behavior. They are one conventional screen projection. They may be acceptable for some screen runtimes, but they are too narrow to define Elonn across tablets, headsets, room-scale spatial runtimes, nonvisual surfaces, and future runtime classes.

Rendering behavior should mean semantic obligations, not geometry. Every runtime must be able to make relevant objects perceivable, expose valid actions, preserve focus and workspace continuity, distinguish carry from field state, surface context and controls, represent findings, preserve permissions, and route mutations through World. No universal contract should require those obligations to be represented as docks, rails, sidebars, stacks, sheets, panels, cards, or holograms.

Those are presentation choices.

7. World And Translators

The long-term platform shape should be:

Services -> World canonical model -> Translators -> Runtime adapters

Services own domain truth. World owns the canonical composed object/workspace graph. Translators convert that canonical graph into runtime-specific payloads. Runtime adapters render the translated payload and handle device input, sensors, camera, lifecycle, accessibility implementation, local performance, and platform APIs.

Translators should be first-class platform components, not private logic hidden inside runtimes. A translator receives the canonical World model, member/runtime context, and a capability declaration. It emits the payload a runtime class can consume. A compact screen translator, expanded screen translator, tablet/stage translator, passthrough headset translator, and room-scale spatial translator may produce very different presentation contracts while preserving the same objects, actions, permissions, focus, workspace state, field state, findings, and fallbacks.

That is the mechanism that lets one service or World change propagate across runtimes without each runtime becoming its own product implementation. A Messages change should alter the canonical World object graph once. Translator tests should prove that the change appears correctly in the payloads for every supported runtime capability class. Runtime adapters should not rediscover the meaning of the change.

Under this model, runtimes do not infer service meaning, construct right rail content, own workspace rules, decide object identity, or invent action semantics. They implement rendering and interaction for a translated contract.

Conformance should therefore test semantic equivalence, not identical layout. Given one canonical World fixture, every translator must prove that the same domain objects are reachable, the same actions are available, the same permissions apply, focus and workspace state are preserved, field objects and findings are represented, context/control groups are available, and unsupported capabilities degrade explicitly.

8. The Future Runtime Model

The architecture should be evaluated from first principles, not from the need to preserve previous work.

The central decision is whether Elonn is surface-centered, runtime-centered, or World/object/translator-centered. The evidence points toward World/object/translator-centered.

A more durable model is:

Services -> Domain Objects
World -> Canonical Object Graph + Workspace Context + Authority
Translators -> Runtime-Specific Contracts
Runtime Adapters -> Device-Native Presentation

If Surface remains, it should be a supporting persistence authority:

Surface -> Durable Presentation/Container State -> World

That means World has two broad inputs: domain truth from services and durable presentation/workspace state from Surface or its replacement. World produces the canonical model. Translators produce runtime-specific contracts. Runtime adapters render those contracts.

This model lets Elonn support current 2D interfaces and future spatial runtimes without forcing every concept into a panel-shaped surface. A calendar appointment can be a timeline item, notification, floating reminder, or holographic marker. A place can be a field marker, map object, rail row, or carried detail view. A message thread can be a compact nav item, full conversation view, notification, or spatial object. An avatar can exist as an avatar, not as a surface pretending to be one.

The current architecture already has strong pieces. API as identity authority is sound. Time has real domain concepts. Messages now has a clearer boundary from Social DMs. Maps as field authority is sound. Find as finding authority is sound. World as the composition authority is sound. Runtime adapters as device-specific renderers are sound only if they remain adapters rather than product implementations. The glossary and conformance-corpus direction are also important strengths.

The weak pieces are the layers that blur domain, workspace, and presentation: panel payloads, right rail synthesis, service nav arrays, URL-shaped actions, Surface-seeded service rails, and runtime inference from service-specific payloads.

The next architecture pass should answer these questions explicitly:

• What are the canonical domain objects?
• What is the normalized runtime object shape?
• What state is workspace state?
• What state is durable presentation/container state?
• What state is runtime-local only?
• What actions are semantic commands rather than URLs?
• What exactly does World compose?
• What exactly does Surface uniquely own, if anything?
• What translator outputs are needed for each runtime capability class?
• What should a new runtime be able to implement without reading any existing runtime?

The previous runtime work should not be dismissed. It exposed the real problem. Cardboard, Android, iPad, and Web each forced the architecture to reveal where it was relying on implicit assumptions. But those runtimes are not examples to preserve. The right response is not to patch each runtime until it looks acceptable. The right response is to define the canonical World model and translator layer clearly enough that every runtime consumes translated platform semantics without guessing.

The disciplined conclusion is this:

Surface may still be useful, but Surface is not the center of the architecture.

The center should be domain objects normalized into a canonical World object graph, composed with workspace and authority context, translated for runtime capability classes, then rendered by thin runtime adapters. If surface.elonn remains, it must earn its place by owning durable presentation/container state that clearly belongs neither to services, nor World, nor runtime adapters. If it cannot make that case, its responsibilities should be absorbed into a cleaner World-owned workspace model or split into narrower services with clearer authority.