Provider Source Contract

Status: Normative service-to-World input contract for future providers.

The Provider Source Contract defines how services publish domain data to World. It is not a runtime payload. It is not a renderer contract. It is the boundary where service-owned facts enter World composition before World produces the World Dataset Contract.

Position

Platform Service
  -> Provider Source Contract
  -> World composition
  -> World Dataset Contract
  -> Runtime
  -> Platform Renderer

Services own domain data, permissions, actions, relationships, resources, and service-specific state. World owns composed object identity, effective runtime state, cross-service relationships, World-dispatched action endpoints, runtime dataset sections, and orchestration.

Runtimes must never consume provider source payloads directly.

Contract

Provider source payloads use:

{
  "contract": {
    "name": "elonn.world.provider_source",
    "version": 1
  }
}

The fresh World repository contains the executable fixture:

tests/fixtures/provider-source-contract.json

It also contains the normative schema:

schemas/provider-source-v1.schema.json

Sections

Provider source payloads are sectioned to align with the World Dataset Contract without becoming the runtime dataset.

Section	Meaning
provider	Provider identity and service authority.
objects	Service-owned domain objects using provider source identity.
relationships	Service-owned relationships between provider source references.
actions	Service-owned action descriptors before World routing.
collections	Service-owned grouping, ordering, and pagination facts.
resources	Service-owned fetchable resources referenced by objects.
extensions	Provider extension records that World may ignore or normalize.

The objects, relationships, actions, collections, resources, and extensions sections each carry name, version, and items.

Source References

Provider source references identify service-owned records before World assigns World object ids.

{
  "provider": "fixture.find",
  "source_type": "place",
  "source_id": "zeitgeist"
}

Providers publish source references. World composes stable World object ids. Providers must not publish world_object_id, runtime object ids, or World command endpoints.

Objects

Provider objects describe what exists in the service domain.

Required common fields:

Field	Meaning
source	Provider source reference.
type	Semantic object type.
title	Human-readable object title.
summary	Runtime-safe summary.
visibility	Service-owned visibility facts.
permissions	Service-owned permission facts.
actions	Provider action ids available for the object.
resources	Resource references by provider resource id.
metadata	Runtime-safe domain state.

World may normalize object types, permissions, actions, resources, collections, and relationships before publishing the World Dataset Contract.

Actions

Provider actions describe what the service can do. They do not describe how a runtime should call World.

Required fields:

Field	Meaning
id	Stable provider action id within the provider source payload.
type	Semantic action type.
label	Human-readable label.
target_source	Provider source reference for the action target.
availability	Explicit enabled, disabled, denied, or unavailable state.
input	Provider-described input controls.
command	Optional provider command descriptor for World relay.

Provider actions must not include endpoint, url, or href fields for runtime command dispatch. World publishes runtime-dispatchable action endpoints in the World Dataset Contract.

Provider command descriptors are for World only. They may declare provider, operation, and runtime-safe metadata. They must not declare provider URLs, runtime endpoints, renderer behavior, or platform behavior. Runtimes never receive provider commands and never call provider action routes directly.

Collections

Provider collections describe service-owned grouping, ordering, and pagination facts.

Required fields:

Field	Meaning
id	Stable provider collection id.
type	Semantic collection type.
title	Human-readable title.
summary	Runtime-safe summary.
ordering	Provider-owned ordering fact.
pagination	Provider-owned pagination state.
items	Provider source references.
metadata	Runtime-safe domain state.

World decides whether a provider collection becomes a runtime collection, participates in another collection, or is ignored for the current runtime context.

Resources

Provider resources describe fetchable service-owned assets.

Required fields:

Field	Meaning
id	Stable provider resource id.
kind	Semantic resource kind such as thumbnail, avatar, document, audio, video, or model.
media_type	Media family or concrete media type.
href	Provider-owned fetch reference for World to normalize.
label	Human-readable label.
cache	Provider cache facts.
metadata	Runtime-safe resource state.

World decides how resources are exposed in the World Dataset Contract.

World Ingestion

Fresh world.elonn.local ingests provider source payloads as data. A provider source payload is supplied to World composition, validated against elonn.world.provider_source version 1, and then mapped into existing World Dataset sections.

World ingestion:

• composes World-owned object, action, relationship, collection, and resource ids from provider source references;
• publishes World action endpoints for provider actions;
• maps provider collections to World collection items that reference World object ids;
• maps provider resources to World resources and object resource references;
• carries provider extensions through the extensions section;
• records provider dependencies, validation errors, and degraded-reference warnings in metadata;
• contains no provider-specific parsing or branching.

Live provider HTTP acquisition is separate from ingestion. World acquisition uses configured provider-source endpoints such as POST /find/provider-source, forwards caller-supplied provider request bodies, and passes successful responses into the same generic ingestion path. Acquisition does not parse provider object fields and does not know whether a payload came from Find, a fixture, or a future provider.

Provider Action Dispatch

Provider action dispatch completes the provider-backed loop without exposing provider commands to runtimes.

The flow is:

Provider Source action command
  -> World internal command map
  -> World Dataset action endpoint
  -> Runtime calls /world/actions/{action_id}
  -> World validates action availability
  -> World relays command through configured provider transport
  -> Provider action result
  -> Normalized World action response

World dispatch:

• resolves provider commands from provider-source action metadata;
• refuses disabled, denied, or unavailable provider actions before relay;
• relays through configured provider action endpoints;
• sends elonn.world.provider_action_command version 1 payloads;
• accepts only validated elonn.world.provider_action_result version 1 payloads with provider, operation, target source, persistent-state, and refresh facts;
• reacquires provider source data and can return a refreshed World Dataset after provider action completion when the provider result requests refresh;
• does not reconstruct provider routes from action ids, labels, object types, source ids, or runtime behavior.

Provider action routes are service-owned. For the first provider-backed loop, Find accepts World relays at POST /find/provider-actions. Runtimes must never call that route.

Forbidden Content

Provider source payloads must not contain renderer, runtime, or platform terms. Forbidden concepts include HTML, CSS, DOM, Android, SwiftUI, Jetpack Compose, Unity, XREAL, renderers, panels, docks, rails, stacks, cards, markers, meshes, platform view hierarchies, surface_runtime, field_runtime, and runtime_panel.

Provider source payloads must not require a runtime to understand service schemas, database ids, provider routes, or platform UI behavior.

Conformance

A Provider Source Contract implementation is conforming when:

• the payload declares elonn.world.provider_source version 1;
• the payload validates against schemas/provider-source-v1.schema.json;
• every section uses name, version, and items where applicable;
• objects publish source identity, type, title, summary, visibility, permissions, actions, resources, and metadata;
• actions publish semantic descriptors without World or runtime endpoints;
• collections publish grouping, ordering, pagination, and provider source item references;
• relationships reference provider sources, not World ids;
• resources publish fetchable service assets without renderer instructions;
• forbidden renderer, runtime, platform, and legacy runtime-shape terms are rejected;
• World can compose the provider payload into the World Dataset Contract without requiring runtime changes;
• World ingestion handles the payload without provider-specific parsing or branching;
• live provider-source acquisition remains transport-only and feeds the same ingestion path as fixture-backed provider sources;
• provider action dispatch resolves provider commands internally, relays through configured provider action transports, and never exposes provider commands to runtimes.