World Dataset Contract

Status: Normative contract for the fresh world.elonn.local rebuild.

The World Dataset is the runtime-facing contract for Elonn. It is produced by World and consumed by runtimes. Providers may later contribute data to World, but they do not define this contract.

The initial implementation is fixture-backed on purpose. A runtime must be able to render a useful interactive environment from this contract before any real provider is connected.

Endpoint

POST /world/session

Request example:

{
  "contract": {
    "name": "elonn.world.session_request",
    "version": 1
  },
  "provider_source_profile": "runtime_conformance",
  "context": {
    "intent": "discover_places",
    "query_text": "coffee",
    "scope": "nearby"
  },
  "runtime": {
    "name": "html"
  },
  "capabilities": {
    "screen": true,
    "spatial_markers": false,
    "touch": true
  },
  "selected_object_id": "world_object_place_zeitgeist",
  "selected_collection_id": "world_collection_nearby_places",
  "pagination_cursor": "nearby:2",
  "runtime_state": {
    "runtime_session_id": "previous_session_123"
  }
}

The response is an elonn.world.dataset v1 document. Runtimes must not call provider services for runtime state. Persistent actions must use endpoints from the actions section.

The request body may declare elonn.world.session_request version 1. If it does, World validates the contract name and version before composing a dataset. World ignores request-body member identity. Trusted member context comes from World's server boundary, currently the trusted X-Elonn-Member-Id header in the fresh World service or the configured development fallback in local tests.

Invalid World requests return elonn.world.error version 1:

{
  "contract": {
    "name": "elonn.world.error",
    "version": 1
  },
  "status": "error",
  "code": "invalid_world_request",
  "message": "World request failed validation.",
  "errors": [
    {
      "field": "runtime",
      "message": "runtime must be a string or object."
    }
  ]
}

provider_source_profile is a World-owned acquisition profile. It is not a provider name, provider endpoint, or renderer instruction. When present, World decides which providers to query and how to compose their provider source payloads into the World Dataset. Runtimes must not send provider routes, consume provider source payloads directly, or read provider command metadata.

Provider acquisition profiles are private World configuration. A runtime may name a World profile or provide semantic context such as intent, query text, scope, selected object, location, time, and runtime capability. World resolves that request into provider acquisition internally. The runtime contract has no provider_source_requests field, no provider id field, and no provider endpoint field.

When a runtime dispatches a World action, World returns an elonn.world.action_result v1 response. The response tells the runtime whether the command was accepted, rejected, failed validation, changed persistent state, made no semantic change, or returned a refreshed dataset. When the response contains a dataset, the runtime replaces its authoritative local runtime state from that dataset.

When a runtime dispatches a provider-backed World action, it must send the same World-owned profile and context needed for World to refresh the dataset.

World validates provider action results before accepting them. A provider HTTP success is not enough: the response must declare elonn.world.provider_action_result version 1 and include provider, operation, target source, persistent-state, and refresh facts. If the result asks for a provider-source refresh, World reacquires provider data through the same World-owned profile/context path before returning the refreshed dataset.

Contract Sections

Every section is independently versioned with name and version. The section schemas are executable contract files, not placeholders. The live fixture-backed World Dataset must validate against every section schema before a provider or runtime implementation is treated as conforming.

Section	Meaning
dataset	Dataset identity, version, world version, and runtime session id.
identity	Trusted member context and visibility scope.
context	Runtime situation such as selected object, selected collection, pagination cursor, prior runtime session, intent, scope, and query text.
objects	Canonical World Objects that can be rendered or acted on.
relationships	Directed links between World Objects.
actions	World-dispatched actions available to objects.
collections	World-owned grouping, ordering, and pagination.
layout	Runtime-neutral relevance and region hints.
capabilities	Runtime declaration and constraints World applied.
permissions	Default and object-specific permission facts.
resources	Fetchable assets referenced by objects.
extensions	Future extension records. Unknown extensions are ignored.
metadata	Generation and fixture/provider metadata.

Schema files live with the fresh World service:

schemas/world-dataset-v1.schema.json
schemas/world-session-request-v1.schema.json
schemas/world-error-v1.schema.json
schemas/world-action-result-v1.schema.json
schemas/world-section-identity-v1.schema.json
schemas/world-section-context-v1.schema.json
schemas/world-section-objects-v1.schema.json
schemas/world-section-relationships-v1.schema.json
schemas/world-section-actions-v1.schema.json
schemas/world-section-collections-v1.schema.json
schemas/world-section-layout-v1.schema.json
schemas/world-section-capabilities-v1.schema.json
schemas/world-section-permissions-v1.schema.json
schemas/world-section-resources-v1.schema.json
schemas/world-section-extensions-v1.schema.json
schemas/world-section-metadata-v1.schema.json

The current schema conformance suite validates the fixture-backed dataset against the section schemas and requires concrete item structures for objects, relationships, actions, collections, resources, layout, capabilities, permissions, and metadata. The fixture dataset remains the reference implementation for the canonical model while the model is stabilizing.

The metadata section includes provider dependency records, state_continuity, plus provider_source_errors and provider_source_warnings. Errors identify provider acquisition or validation failures that prevented a provider payload from being composed. Warnings identify degraded but usable provider data, such as object resource references, relationship endpoints, action targets, or collection items that could not be composed into World ids.

state_continuity records the selected object, selected collection, pagination cursor, previous runtime session id, and any selected-state fields World had to reconcile because the requested ids were not present in the composed dataset. Runtimes use this data to preserve local selection and context after accepted, rejected, validation-failed, no-op, and refreshed-dataset action responses.

Objects

Objects describe what exists. They are not UI components.

Current fixture object types include:

["activity", "community", "conversation", "document", "event", "person", "place", "tool"]

Object example:

{
  "id": "world_object_place_zeitgeist",
  "type": "place",
  "title": "Zeitgeist Coffee",
  "summary": "Coffee shop in Pioneer Square.",
  "source": {
    "provider": "fixture",
    "source_type": "place",
    "source_id": "zeitgeist"
  },
  "resources": [
    {
      "kind": "thumbnail",
      "resource_id": "world_resource_zeitgeist_thumbnail"
    }
  ]
}

Runtimes must render unknown object types generically.

The fixture model includes carry-anchored member, community, conversation, document, activity, and tool objects, plus field-anchored place and event objects. These anchors live in object metadata as semantic state; runtimes decide how to project carry and field objects into their own coordinate systems.

Objects also publish availability with state, reason, and optional required_capability. Availability states are enabled, disabled, denied, and unavailable. Runtimes render these states; they do not recalculate them.

Collections

Collections describe how World groups and orders objects. A runtime must not infer these groupings by object type.

Current fixture collections include:

[
  "world_collection_navigation",
  "world_collection_search_results",
  "world_collection_nearby_places",
  "world_collection_today_events",
  "world_collection_recent_conversations",
  "world_collection_favorites",
  "world_collection_suggested_people",
  "world_collection_community_feed",
  "world_collection_resources"
]

Collection example:

{
  "id": "world_collection_nearby_places",
  "type": "nearby_places",
  "title": "Nearby Places",
  "ordering": "world_ranked",
  "pagination": {
    "mode": "complete",
    "next_cursor": null
  },
  "items": [
    {"object_id": "world_object_place_zeitgeist"},
    {"object_id": "world_object_place_library"}
  ]
}

The fixture dataset intentionally includes runtime-useful collections that a new runtime should render directly: navigation, search results, nearby places, today's events, recent conversations, favorites, suggested people, community feed, and resources. Runtimes must not reconstruct these collections from object types or service-specific assumptions.

Collections publish availability with the same state vocabulary as objects and actions. A collection may be present but unavailable when a runtime lacks a capability required to use it.

Relationships

Relationships describe the graph context around objects. Current fixture relationship types include circle_member, member_of, hosted_by, participant, actor, about, attached_to, located_near, near, and discovers.

Runtimes may present relationship context, but they must not infer service business rules from relationship type names.

Action Semantics

Actions are World-dispatched and runtime-neutral. The fixture action registry defines generic actions such as open, inspect, message, social_dm, reply, query, save, share, join, attach, and navigate.

Text-entry actions such as message, social_dm, reply, and query publish their required input descriptors in the dataset. Runtimes render the input and dispatch the World endpoint; they do not implement Messages, Social, Find, or Time business behavior.

Actions publish availability. enabled actions may be dispatched through their World endpoint. disabled, denied, and unavailable actions remain visible with their reason so the runtime can present the state without guessing.

World action results use this normalized shape:

{
  "contract": {
    "name": "elonn.world.action_result",
    "version": 1
  },
  "status": "accepted",
  "action_id": "world_action_world_object_place_zeitgeist_open",
  "type": "open",
  "target_id": "world_object_place_zeitgeist",
  "result": {
    "outcome": "refreshed_dataset",
    "message": "Open command accepted and returned a refreshed World Dataset.",
    "persistent_state_changed": false,
    "reason": null,
    "validation_errors": [],
    "replace_dataset": true
  },
  "dataset": {}
}

status is one of accepted, rejected, validation_failed, or no_op. result.outcome is one of accepted, rejected, validation_failed, persistent_state_changed, no_op, or refreshed_dataset.

A conforming runtime must render these outcomes from the response itself:

Outcome	Runtime behavior
accepted	Show the World-provided message and keep local state unless dataset is present.
rejected	Show the reason and leave local state unchanged.
validation_failed	Show field validation errors and leave local state unchanged.
persistent_state_changed	Show that World accepted a persistent change; replace local state only if dataset is present.
no_op	Show the no-op message and leave local state unchanged.
refreshed_dataset	Replace local state from the returned World Dataset.

Resources

Resources describe what can be fetched. Objects reference resources by id.

Current fixture resource kinds include:

["avatar", "thumbnail", "document", "icon"]

Resource example:

{
  "id": "world_resource_blueprint_markdown",
  "kind": "document",
  "media_type": "markdown",
  "href": "/fixtures/resources/world-blueprint.md",
  "label": "World blueprint markdown",
  "cache": {
    "mode": "runtime_cacheable"
  }
}

Runtimes decide how or whether to fetch resources based on capability, cache policy, bandwidth, and platform constraints.

Resources publish availability. A resource may exist in the dataset but be unavailable when the runtime lacks a capability such as audio or spatial media.

Permissions And Availability

The permissions section indexes permission and availability facts across the dataset. It includes default permission booleans, the canonical availability state list, object permission overrides, action availability overrides, collection availability overrides, and resource availability overrides.

This lets a runtime render allowed, denied, disabled, unavailable, and missing-capability states from the World Dataset alone. Services contribute facts, but World decides the effective runtime state.

Actions

Actions describe what the user can do. Runtimes dispatch the published endpoint and must not reconstruct commands from object type, labels, provider ids, or source references.

Action example:

{
  "id": "world_action_world_object_conversation_ada_message",
  "type": "message",
  "label": "Message",
  "target_id": "world_object_conversation_ada",
  "method": "POST",
  "endpoint": "/world/actions/world_action_world_object_conversation_ada_message",
  "availability": {
    "state": "enabled",
    "reason": null
  },
  "input": [
    {
      "id": "body",
      "type": "text",
      "required": true
    }
  ]
}

Disabled actions remain in the dataset with explicit availability:

{
  "type": "share",
  "availability": {
    "state": "disabled",
    "reason": "sharing_not_enabled_in_fixture"
  }
}

Runtime Requirements

A conforming runtime:

• requests POST /world/session;
• sends World-owned profile and semantic context, not provider ids or provider routes;
• validates dataset.name, dataset.version, and each section version;
• builds local indexes for objects, relationships, actions, collections, and resources;
• renders collections rather than inventing grouping;
• resolves object resources through the resources section;
• dispatches only World-published action endpoints;
• includes the same World-owned acquisition context when dispatching an action that depends on provider-backed data;
• renders normalized action outcomes from elonn.world.action_result without service-specific logic;
• consumes a refreshed World Dataset from a normalized action response when World returns one;
• renders unknown object, collection, action, resource, and extension types generically;
• does not call providers directly;
• does not require existing Web, Android, iPad, XR, or legacy World behavior.

Harness Acceptance Scenarios

The contract HTML runtime harness is the first conformance consumer for this contract. It must prove that a runtime can consume the World Dataset Contract without provider knowledge or existing runtime behavior.

Scenario	Required runtime behavior
unsupported_dataset_version	Reject a dataset version the runtime does not support.
unsupported_section_version	Reject a section version the runtime does not support.
unknown_object_type	Render the object generically from common object fields.
unknown_collection_type	Render the collection generically from collection fields and item references.
disabled_action	Display the action as unavailable and preserve the World-provided reason.
permission_denied_action	Display the action as unavailable without inventing permission logic.
missing_resource_reference	Render a missing-resource state without failing the dataset.
empty_collection	Render the empty collection state from the collection itself.
paginated_collection	Expose pagination state from the collection without inferring additional items.
unsupported_capability_constraints	Surface World-applied constraints without changing business state.
unknown_extension	Ignore the unknown extension safely while keeping the rest of the dataset usable.
action_dispatch	Dispatch only the action endpoint published by World.
provider_backed_dataset	Request provider-backed data through a World-owned acquisition profile and render the resulting sections generically.
provider_backed_action_response	Dispatch a provider-backed World action and replace local runtime state from the returned World Dataset.
action_outcome_matrix	Render accepted, rejected, validation failure, persistent-state changed, no-op, and refreshed-dataset outcomes generically.

Non-Goals

The World Dataset Contract does not contain renderer-specific concepts, provider payloads, HTML, CSS, platform view hierarchies, or service-specific runtime instructions.