App Interconnect
A Nimi app does not live inside Realm — it connects to it. This page explains how that connection works: how an app reads Realm, how it earns the right to write, and how Realm concepts translate for outside systems.
How Apps Connect To Realm
| Path | Purpose |
|---|---|
| REST | Typed Realm reads / mutations under admitted contracts |
| WebSocket | Realtime delivery of canonical events |
Apps connect to Realm through admitted REST + WS surfaces; they do not invent their own protocols. Authorization is bearer token issued under admitted token issuance flow.
App Modes And Realm Authority
A render-app reads Realm; an extension-app reads and writes Realm within its admitted binding scope.
| Mode | Realm read | Realm write | Concurrent count per world |
|---|---|---|---|
render-app | yes | no | many |
extension-app | yes | yes | at most one active per world |
A world's at-most-one-active-extension-app rule comes from this: if two extension-apps could both write Realm canonical state for the same world simultaneously, the canonical state would race.
Interop Mapping
Realm interop mapping translates Realm concepts to / from external open-spec anchors (cross-protocol mappings). It bridges:
| Bridge | Purpose |
|---|---|
| World state contract ↔ external state representations | When a Realm world's state needs to be visible externally |
| World history contract ↔ external history representations | Cross-platform history compatibility |
| Runtime memory ↔ Realm memory | Replication semantics |
| Runtime agent ↔ Realm agent | Identity bridging |
| Transit contract ↔ external transit shapes | Cross-protocol transit compatibility |
The interop mapping is the formal translation layer. It doesn't mutate Realm; it projects Realm into shapes that other systems can consume.
Reader Scenario: An App Reads Then Acts
A render-app wants to display a world; later, the user upgrades to an extension-app that mutates state.
- Render-app starts. App reads Realm under render mode.
- User wants more. User upgrades the relationship to extension-app mode.
- App-world binding. The extension-app binds to the world (one active at a time).
- Mutation. The extension-app submits typed commit envelopes for state mutations.
- Realm admits. Each mutation passes admitted authorization matrix.
- Audit lineage. Each mutation recorded.
The transition from render-only to extension-with-write requires explicit binding. There is no silent privilege escalation.
Reader Scenario: A Realtime Event Stream
An app wants to react to canonical events as they happen.
- Subscribe. App opens a WebSocket subscription to Realm under admitted subscription surface.
- Realtime delivery. Events arrive as they commit.
- App reacts. Typed event handlers under admitted shapes.
- Connection lifecycle. Reconnect, backpressure, etc. under admitted connection contract.
Realtime is admitted; apps do not invent their own polling protocols when realtime is available.
Reader Scenario: External System Bridges Realm
An external system wants to mirror Realm world history.
- Read via interop mapping. External system reads Realm history under admitted interop mapping.
- Translate to external shape. The mapping projects Realm concepts to external open-spec representations.
- External system consumes. No mutation flowing back unless admitted.
The bridge is one-directional read by default. A bidirectional bridge requires admitted bidirectional contract — not implicit.
Boundary Summary
| Concern | Owner |
|---|---|
| Realm canonical truth | Realm kernel |
| App access to Realm | Admitted REST + WS surfaces |
| App-world binding | App authorization preset + binding contract |
| Realtime delivery | Admitted subscription surface |
| External system bridges | Realm interop mapping |
| Cross-protocol shape | Interop mapping bridge |