Elonn Docs Platform Documentation

World Contract

Status: Normative World contract source. Sections that explicitly describe GET /world/session compatibility output record current implementation reality, not design authority for new runtime dataset work.

World is the runtime composition authority. Runtimes read World, render the dataset World returns, and send runtime writes back through World command URLs. Runtimes must not call API, Social, Messages, Maps, Time, Surface, Find, or provider services directly for runtime state.

The fresh World rebuild starts from the sectioned World Dataset Contract documented in world-dataset-contract.md. That World Dataset Contract is the active target for new runtime work.

The target runtime endpoint is GET /world/runtime. It returns the canonical runtime dataset defined by world-model-contract.md and runtime-contract.md. Every runtime consumes that same logical dataset unchanged.

GET /world/session is the current runtime v2 compatibility bootstrap contract. It contains shell primitives, services, controls, objects, actions, capabilities, and Surface runtime state. It is not the target dataset.

GET /world/translated exposes an older expanded-screen compatibility proof. It is migration evidence only and must not replace the canonical runtime dataset.

This document describes both the target World runtime endpoint and the current compatibility output during migration.

See the captured JSON artifact: world-session-dataset.json.

Target Runtime Dataset Request

GET /world/runtime

Headers:

Header Required Meaning
Accept: application/json yes Runtime expects JSON
Cookie: elonn_api_token=... web Browser credential
Authorization: Bearer <elonn_api_token> native Native runtime credential
X-Elonn-Runtime yes Runtime capability declaration

Query parameters may include runtime location, sensor, or capability context needed for World to compose field and fallback state. World must not return sample, development, provider-specific, or inferred location data when the runtime omits real location input.

Top-level shape:

Field Type Meaning
contract object {name: "elonn.runtime.dataset", version}
member object Authenticated member context without reusable credentials
capabilities object Declared, applied, and unsupported runtime capabilities
workspace object Working set, focus, order, placement, and continuity
objects array Runtime-presentable World objects
contexts array Navigation/control intent tied to objects, workspace, field, or findings
actions array World-routed command descriptors
field object World-anchored field state
findings array Discovered candidates from Find
fallbacks array Explicit unavailable, unsupported, denied, empty, or degraded states
sources array Diagnostic source metadata, never runtime service endpoints

Runtimes render the dataset with platform-native capabilities. World must not emit panels, surfaces, stacks, rails, docks, renderer hints, HTML, or platform UI instructions as canonical runtime data.

Compatibility Request

GET /world/session

Headers:

Header Required Meaning
Accept: application/json yes Runtime expects JSON
Cookie: elonn_api_token=... web Browser credential
Authorization: Bearer <elonn_api_token> native Native runtime credential
X-Elonn-Runtime yes JSON runtime capability declaration

Query parameters:

Parameter Type Default Meaning
lat float none Member/device latitude for field objects
lon float none Member/device longitude for field objects
radius integer 1000 Field radius in meters
categories comma-separated string or repeated values all standard field categories Field category filter

If lat and lon are omitted, field_runtime.origin is null and field_runtime.objects is empty. The runtime still renders the field shell and controls. Runtimes must not substitute a sample, development, previously hardcoded, or provider-specific location.

Compatibility Translated Endpoint

GET /world/translated

Headers are the same as GET /world/session.

World builds the canonical model from the same composed state used by GET /world/session, then returns the older expanded-screen compatibility output:

Field Type Meaning
contract object {name: "elonn.home.runtime", version, translator: "expanded_screen"}
capabilities object Applied capability information
presentation object Translator presentation groups
objects array Translated World objects with stable world_object_id, source, title, permissions, action references, and presentation hints
contexts array Translated context/control groups; runtimes choose the visual form
actions array Runtime-dispatchable semantic actions with action_id, type, label, target, method, command, controls, availability, and fallback
workspace object Translated focus, order, and placement
field object Translated field state
fallbacks array Explicit degraded, unavailable, unsupported, or denied states

Existing runtimes may use this endpoint during migration to inspect and render proof output. New runtime work must use the canonical runtime dataset instead. Runtime writes still go through World-published commands and relay URLs. Runtimes must not call services directly from object source references.

Translated object records carry action references by action_id. Runtimes must resolve those references against the top-level actions array and dispatch the published command.url; they must not reconstruct service or World URLs from object identity.

Translated context records carry context_id, target, items, and action references. Context items are navigation/control intent, not a rail, sidebar, or panel requirement. For example, Messages publishes context items for the thread list, start-thread action, and translated thread objects; Web currently renders those items in its right-side area, while another runtime may render the same items differently.

Response

Top-level shape:

Field Type Meaning
service string elonn_world
contract object {name: "elonn.home.runtime", version: 2}
runtime_session object Runtime session metadata
capabilities object Requested runtime capabilities and primitives provided by World
shell object Shell primitives, including the ordered dock
field_runtime object Field contract consumed by runtimes
surface_runtime object Surface/stack/persistence contract consumed by runtimes
status object Service status counts
services array Ordered generic service descriptors

runtime_session:

Field Type Meaning
user_id integer Authenticated member id; do not send this back from the runtime
persistence_authority string world

Field Runtime

field_runtime is composed by World from Maps. Runtimes must not call Maps directly.

Field Type Meaning
contract object {name: "elonn.field.runtime", version: 2}
origin object|null {latitude, longitude} for the returned field object set
radius_meters integer Applied field radius
field_width integer Logical projection width for non-spatial renderers
controls array Declarative selectors and toggle groups with semantic actions
objects array Generic object envelopes to project as markers or cards
source object Diagnostic source metadata; not a runtime endpoint

field_runtime.objects[]:

Field Type Meaning
id string Stable object id from source data when available
type string Semantic object type, currently place
category string Product data used by controls; runtimes do not interpret its meaning
title string Display title
summary string Display summary
presentation object Generic card/marker preferences
location object Latitude, longitude, distance, bearing, and local offsets
actions array Semantic actions available for the object
attribution object Provider label, URL, and required-display flag

The same object envelope is used for findings, translated Surface Objects, and generic panel items where possible. Object actions are ordered descriptors, not string action names. Labels and availability are producer-owned data.

field_runtime.controls[] contains id, type, label, summary, and ordered items. Each item contains display data, selected state, and an attached action. Adding a category or radius choice changes World data only.

Shell Dock

shell.dock.items[] is the ordered runtime navigation model. Each item has id, label, icon, essential, and an attached semantic action. Runtimes must not synthesize service names, ordering, or service-specific click logic.

Surface Runtime

surface_runtime is the primary runtime layout and persistence contract. World reads it from Surface with trusted member context and adds World relay command URLs.

Required fields:

Field Type Meaning
surfaces array Durable surface records
stacks array Ordered surface stacks
viewports array Runtime viewport hints
commands object World relay write URLs

Minimum command set:

Command URL Body
focus_surface /world/surface/stacks/carry_primary/focus {"surface_id": "surface_social"}
reorder_stack /world/surface/stacks/carry_primary/reorder {"surface_order": ["surface_social", "surface_calendar"]}
update_placement /world/surface/surfaces/{surface_id}/placement {"placement_mode": "...", "placement": {...}}
translate_surface /world/surface/surfaces/{surface_id}/translate {}
open_finding /world/surface/surfaces/{surface_id}/open {}

Runtimes use only published commands. They must not reconstruct these routes from naming conventions when a command is absent.

Surface may create or repair member-scoped default stacks before World returns the session payload. That is upstream service behavior. After the runtime receives /world/session, the returned surface_runtime is authoritative: runtimes render what World returned and do not synthesize missing carry surfaces, remove existing surfaces, or create local replacement stacks.

See surface-contract.md for the full surface object, stack object, placement, and persistence rules.

Panel Payloads

GET /world/panels/{service} returns a service-owned panel payload consumed by runtimes through World.

Required fields:

Field Type Meaning
kind string Service identifier, e.g. social, time, find, messages
view string Active view within the panel
title string Display title
summary string One-line summary
nav array Service-owned navigation items inside the panel payload
sections array Panel body sections and items
actions object Top-level action map
action_descriptors array Ordered semantic actions and producer-described form controls

Each nav item has an id, a label, and an optional action URL. Items without action are labels, not buttons. Each section has a title and an items array. Each item has an id, title, optional summary, optional metadata, and optional actions.

Panel payloads are transient service content unless World also supplies a durable surface record for the object. A panel payload must not be treated as a durable surface by itself. Real workspace pages such as Social, Messages, and Time are rendered into durable center-stack surfaces when those surfaces exist; the panel payload is the data source, not the user-visible container.

Social uses the durable surface_social center-stack surface for its dashboard and category pages. The runtime must not route Social dashboard/category clicks through generic blank modal panel chrome.

If sections is empty, runtimes must still render title and summary plus an empty state. If nav is empty, the panel surface must not invent items. Canonical right rail content comes from surface_runtime.stacks[right_context], not from runtime-inferred panel navigation. Unknown service-specific fields must be ignored.

When action_descriptors is present, it is the renderable action source. A submit_form descriptor contains id, label, type, method, url, and ordered controls. Controls contain id, type, label, required, default, and optional selector options. Runtimes render these controls without maintaining action-id-specific form registries.

Services

services[] contains generic descriptors with id, label, icon, entry_surface_id, content_source, presentation, objects, and actions. The presentation.workspace primitive currently selects carry, field, or find. content_source identifies the World URL for service content. When a service has moved to translated World objects/actions but the legacy panel URL remains available, World may mark that object with compatibility: true and a specific compatibility_scope.

presentation.renderer is an optional specialization hint. A runtime may register a richer renderer for a known hint, but it must render the service through the generic panel/card path when the hint is unknown or unsupported. Opening, navigation, and content loading resolve through the descriptor; a runtime must not select behavior from a service id or URL prefix.

Errors

Status Runtime behavior
401 Set runtime status to auth required and show login
403 Show permission error; do not retry as another member
5xx or network failure Set runtime status to unavailable and offer retry

Runtime Rules

  • World response data wins over local UI state.
  • Unknown additive fields and services must use the Runtime Contract fallback policy.
  • Runtimes must render from shell, services, surface_runtime, and field_runtime; contract v1 compatibility fields are not emitted.
  • Runtimes must route writes through surface_runtime.commands.
  • Runtimes render lower dock items only from shell.dock.items[].
  • Runtimes render canonical right rail content from right_context surfaces.
  • Runtimes open place findings through commands.open_finding; they do not call Maps or tile-discovery services to construct a map contract.
  • Runtimes must never send runtime_session.user_id or any other member id back to World.

Related contracts