World Model Contract
This document defines the target canonical model World composes and publishes as the runtime dataset.
The World model is not a screen layout, not a service payload, and not a runtime adapter payload. It is the single composed platform state every runtime consumes unchanged. Service-owned domain objects enter this model through the object source contract.
Current GET /world/session responses still expose the runtime v2
surface-shaped contract described in world-contract.md.
That contract is the current compatibility output. This document defines the
model that should replace Surface-centered runtime composition as World is
rebuilt.
Ownership
Services own domain truth and object sources:
| Service responsibility | Examples |
|---|---|
| Identity | member identity, auth state, account permission facts |
| Domain state | message threads, calendar entries, social conversations, places, findings |
| Domain actions | send message, create appointment, join community, open place |
| Domain permissions | who may view, mutate, reply, invite, share, or delete |
The object source contract
defines how service-owned domain objects are shaped before World composes them
into canonical objects[].
World owns composition:
| World responsibility | Meaning |
|---|---|
| Workspace | The member's current composed working set |
| Relationships | Cross-service references and context |
| Authority | The command routing and permission envelope presented to runtimes |
| Focus | Which object or workspace item is active |
| Order | Member-scoped ordering where order is part of workspace state |
| Placement | Carry, field, detached, shared, or other non-domain placement |
| Fallbacks | Explicit unavailable, unsupported, empty, and permission-denied states |
Runtimes own projection:
| Runtime responsibility | Meaning |
|---|---|
| Capability matching | Declare supported rendering, input, projection, and fallback capabilities |
| Presentation grouping | Build platform-native scene structures from runtime data |
| Degradation | Preserve semantics when a capability is unavailable |
| Equivalence | Keep object identity, actions, permissions, and focus intact |
Runtimes own execution:
| Runtime responsibility | Meaning |
|---|---|
| Rendering | Platform-native visual, spatial, audio, or haptic presentation |
| Input | Pointer, touch, keyboard, controller, gaze, voice, or future input |
| Sensors | Camera, compass, location, anchors, and device state |
| Lifecycle | App startup, suspension, refresh, retry, and local performance |
| Accessibility | Platform accessibility implementation |
Canonical Shape
A World model has this top-level shape:
| Field | Type | Meaning |
|---|---|---|
contract |
object | {name: "elonn.world.model", version: 1} |
member |
object | Authenticated member context without reusable credentials |
capability_request |
object | Runtime-declared capabilities and constraints |
workspace |
object | Member-scoped composed workspace state |
objects |
array | Canonical World objects keyed by stable World object id |
relationships |
array | Cross-object and cross-service relationships |
contexts |
array | Context/control groups tied to objects or workspace state |
field |
object | World-anchored field state composed from Maps and services |
findings |
array | Discovered candidates composed from Find |
actions |
array | Semantic command descriptors routed through World |
fallbacks |
array | Explicit unavailable, unsupported, empty, and denied states |
sources |
array | Diagnostic source metadata; never a runtime endpoint list |
World model ids are stable within the authenticated member's workspace and must not require a runtime to know service table names, service hosts, or current layout containers.
World Object
objects[] contains canonical objects that can be presented by any runtime
class. These objects come from service object sources, World composition state,
Field composition, or finding promotion. They must not be discovered by reading
compatibility surface records.
| Field | Type | Meaning |
|---|---|---|
world_object_id |
string | Stable World id for this composed object |
object_type |
string | Semantic type such as message_thread, calendar_event, place, member, conversation, finding, or resource |
source |
object | {service, resource_type, resource_id} reference to the authority |
title |
string | Human-readable title |
summary |
string|null | Optional descriptive metadata |
state |
object | Domain-neutral state needed for presentation and routing |
permissions |
object | Effective member permissions |
actions |
array | References to actions[] by id, in producer order |
relationships |
array | References to relationships[] by id |
placement |
object|null | Non-domain placement when World owns it |
focus |
object|null | Focus metadata when this object is active or focusable |
The state object must not contain raw service implementation state. If a
service field is necessary for runtimes, it must be named as a domain concept
and documented in that service contract.
Workspace
workspace describes the member's composed working set without assuming docks,
rails, sidebars, cards, panels, or a stack-oriented screen layout.
| Field | Type | Meaning |
|---|---|---|
workspace_id |
string | Member-scoped workspace id |
active_context_id |
string|null | Active context/control group |
active_object_id |
string|null | Active World object |
items |
array | Ordered workspace item references |
focus_order |
array | Ordered focusable item ids |
placements |
array | Carry, field, detached, shared, anchored, or future placement records |
continuity |
object | State needed to preserve member continuity across refreshes |
workspace.items[] references World objects or contexts. It must not be a list
of runtime widgets. A runtime may project workspace items as panels, sheets,
markers, volumes, lists, command palettes, or another presentation primitive.
Contexts
contexts[] contains navigation and control groups that are meaningful only in
relation to an active object, workspace, field, or finding set.
| Field | Type | Meaning |
|---|---|---|
context_id |
string | Stable context id |
kind |
string | object_context, workspace_context, field_context, find_context, or future semantic kind |
title |
string | Context title |
target |
object | Object, workspace, field, or finding target |
items |
array | Navigation/control rows with semantic action references |
actions |
array | Command references for the context |
fallback |
object|null | Explicit empty, unavailable, or unsupported state |
A context is not a right rail. A right rail is one possible runtime presentation of a context for a screen runtime.
Actions
actions[] contains semantic command descriptors. Actions are not URLs from a
runtime's perspective, even when the current transport is a World URL.
| Field | Type | Meaning |
|---|---|---|
action_id |
string | Stable action id within the model |
type |
string | Semantic action type |
label |
string | Display label |
target |
object | Object, workspace, field, finding, or service target |
method |
string | Command method such as GET, POST, or PATCH when transport is HTTP |
command |
object | World-routed command descriptor |
controls |
array | Producer-described fields for member input |
availability |
object | Enabled, disabled, denied, or unavailable state |
fallback |
object | Required fallback when unsupported |
Runtimes dispatch World-published action descriptors. They must not infer service behavior from ids, labels, URLs, or object types.
Field And Findings
field is the World model's world-anchored region. It may contain places,
markers, anchors, volumes, routes, annotations, or future spatial objects.
findings[] are discovered candidates. A finding may become a World object
when World composes it into the workspace, but the finding itself remains a
candidate owned by Find until a service or World action promotes, opens, or
translates it.
Surface Compatibility
Surface concepts are compatibility concepts in the target architecture:
| Current concept | Target model location |
|---|---|
| Surface identity | world_object_id or workspace item id |
| Stack membership | workspace.items[] and focus_order[] |
| Focus surface | workspace.active_object_id plus focus metadata |
| Right rail surface | contexts[] |
| Dock item | Workspace or service action projected by a runtime |
| Surface placement | workspace.placements[] |
| Surface Object | A World object of type resource with normalized runtime-safe content |
If surface.elonn.local remains during migration, it is a persistence source
feeding World. It is not the conceptual center of the platform model.
Conformance
A canonical World model fixture is conforming when all of these are true:
- Every object has a source authority, stable id, title, permissions, and action references.
- Every action has a semantic type, target, availability, and fallback.
- Workspace order and focus are explicit.
- Context/control groups are tied to targets and do not assume a rail, dock, panel, or stack.
- Field objects and findings are represented without requiring a screen projection.
- Unsupported capabilities can be represented through explicit fallback states.
- At least two runtimes can project the same fixture without changing object identity, action meaning, permissions, or authority.
Executable fixtures live in runtime-dataset-v1. The fixture set proves one canonical runtime dataset can support screen and spatial runtime projections while preserving semantic identity.