ELONN

2026-08-12

Status: Draft Architecture Specification

---

Purpose

Elonn is a distributed object-oriented computing platform.

The platform enables people, intelligent systems, software services, and external systems to cooperate through a common architectural model based upon canonical data and published contracts.

Elonn separates presentation, world construction, orchestration, reasoning, Service discovery, and domain behavior into independent architectural responsibilities.

Those responsibilities are assigned to clear owners that evolve independently while remaining interoperable through stable contracts and canonical structures.

This document defines the architecture of the Elonn platform.

---

Documentation

Project-wide documentation structure, authority, publication locations, and required artifacts are defined by the Canonical Structure Guide:

https://dev.elonn.com/public/canonical-structure-guide.md

Scope

This specification defines:

• the architectural organization of the platform;
• the responsibilities assigned to architectural components;
• the relationships between those components;
• the canonical communication model;
• the role of the Canonical Data Model;
• the role of Service Contracts;
• the role of Conductor-owned Service Registry;
• architectural conformance.

This specification does not define:

• implementation details;
• programming languages;
• storage technologies;
• deployment topology;
• user interface design;
• individual Service behavior.

Those subjects are defined by the documentation responsible for each component.

---

Architectural Philosophy

The Elonn architecture is intended to remain stable while implementations evolve.

Architectural decisions should strengthen the platform's long-term consistency rather than optimize for individual implementations.

---

The Member Experiences One World

Members do not interact with independent Services.

Members experience a single coherent world.

The platform combines the capabilities of many Services into one consistent experience regardless of the Runtime through which that world is presented.

---

Objects Before Interfaces

Objects are the fundamental units of canonical information.

Interfaces present Objects through Runtime-specific interaction models.

Presentation may change.

Object identity shall not.

---

Meaning Before Presentation

Canonical structures define meaning.

Runtimes define presentation.

The same Dataset shall have the same meaning regardless of whether it is presented by a browser, desktop application, mobile device, spatial computer, voice interface, or future Runtime.

---

Contracts Before Implementations

Architectural components communicate exclusively through published contracts.

Contracts define communication.

Implementations satisfy contracts.

Implementations do not redefine contracts.

---

Architecture Before Technology

The architecture intentionally avoids dependence upon specific technologies.

Programming languages, databases, frameworks, transports, operating systems, model vendors, and deployment environments will change throughout the lifetime of the platform.

The architecture should not.

---

One Responsibility Per Component

Every architectural responsibility belongs to exactly one component.

Responsibilities are not shared.

Responsibilities are not duplicated.

Components cooperate through contracts rather than shared implementation.

---

Orchestration Before Capability

The platform distinguishes between orchestration, discovery, and capability.

Conductor determines how a Call is fulfilled.

Services provide capabilities.

Conductor owns Service Registry and provides Service discovery.

Models provide reasoning implementation.

Services may expose reasoning capabilities through Service contracts.

Provider integration belongs to the Services that use those Providers.

This separation permits capabilities to evolve independently without altering the architecture.

---

Domains Before Systems

Every Service owns one domain.

No Service owns the platform.

The platform coordinates Services without absorbing their responsibilities.

---

Evolution Through Extension

The platform grows by introducing new Runtimes, Services, Providers, Models, Service Publications, and canonical extensions.

Architectural boundaries should change only when the architecture itself has become insufficient.

---

The Platform Has Two Planes

The Member Plane performs work on behalf of Members.

The Admin Plane observes and administers the platform's architectural components.

The Admin Plane does not participate in Member-plane execution, and Member-plane execution does not depend upon the Admin Plane.

Administrative authority is distinct from Member-plane authority.

---

Platform Architecture

The Elonn platform is organized around independent architectural components, implementation technologies, and external resources.

Member
    │
    ▼
Runtime
    │
    ▼
API
    │
    ▼
World
    │
    ▼
Conductor
    ├──────────────► Models
    └──────────────► Services
                       ├────────► Service Publications
                       ├────────► Services
                       └────────► External Providers (outside Elonn)
    │
    ▼
World
    │
    ▼
Runtime
    │
    ▼
Member

Every architectural responsibility has one owner.

Communication across architectural boundaries is governed by published contracts.

No component depends upon the internal implementation of another component.

The platform architecture above describes the Member Plane — the flow of execution performed on behalf of a Member.

Admin operates on a separate Admin Plane:

Admin
    ├──────────────► Runtime
    ├──────────────► API
    ├──────────────► World
    ├──────────────► Conductor
    ├──────────────► Models
    └──────────────► Services

Each path above is bidirectional: components report administrative observation to Admin, and Admin issues authorized administrative operations to each component's administrative interface.

Admin-plane communication does not pass through World or Conductor merely because Member-plane communication to that component does.

---

Terminology

API

The public entry point into the platform responsible for member authentication.

---

Call

The canonical request transmitted across an architectural boundary.

Every Call is defined by the Canonical Data Model and interpreted according to the governing contract.

---

Canonical Data Model

The authoritative definition of every canonical structure exchanged throughout the platform.

The Canonical Data Model defines structure.

Contracts define meaning.

---

Component

An independently deployable architectural unit responsible for one architectural function.

---

Contract

A published agreement governing communication across an architectural boundary.

---

Dataset

The canonical response exchanged across architectural boundaries.

Datasets consist exclusively of canonical structures.

---

Member

A person interacting with the platform.

---

Model

A reasoning implementation coordinated by Conductor.

Models are not architectural components.

---

Object

The fundamental unit of information within the Canonical Data Model.

Objects represent identity.

All remaining canonical structures describe, organize, relate, or interact with Objects.

---

Provider

A Provider is an external source of information, capability, computation, or infrastructure used by one or more Services.

Providers are not architectural components of Elonn.

A Provider may be public or private and may be used independently by multiple Services.

---

Runtime

The architectural component responsible for member interaction and presentation.

---

Service Registry

The Conductor-owned Service discovery responsibility that indexes Service Publications.

Service Registry makes Service Publications discoverable to Conductor and exposes derived index facts for Conductor reasoning.

Service Registry does not decide which Service fulfills a Call.

Service Registry does not define Service behavior, duplicate Service contracts, or perform domain behavior.

---

Service Publication

A Service-published document that identifies the Service, describes its selectable capabilities, and locates its published Service Contract.

Service Publication is the authority for deciding whether to consider a Service.

Service Publications are indexed by Conductor through Service Registry.

Service Publications are not Datasets.

---

Service

An architectural component responsible for one platform domain.

Services provide capabilities to Conductor and authorized Services through published Service contracts.

Mind, Find, Maps, Storage, Paint, Messages, Time, and future platform capabilities are implemented as Services.

---

World

The architectural component responsible for constructing the member's world from canonical information.

---

Conductor

The orchestration component of the platform.

Conductor coordinates Models and Services to satisfy canonical Calls received from World.

Conductor owns Service Registry.

---

Admin

The architectural component responsible for administrative observation, control, and management of the platform's architectural components.

Admin operates on the Admin Plane. Admin is not a Service.

---

Admin Plane

The architectural plane through which Admin observes and controls the platform's architectural components, distinct from the Member Plane.

---

Administrative Interface

The administrative communication surface a Platform Component exposes to Admin, architecturally distinct from that component's Member-plane interface.

---

Member Plane

The architectural plane through which the platform performs work on behalf of Members: Runtime, API, World, Conductor, Services, Providers, and Models.

---

Platform Components

The Elonn platform is implemented as a collection of independent architectural components.

Each component owns one architectural responsibility.

Components communicate exclusively through published contracts.

Components depend upon contracts rather than implementations.

Architectural responsibilities shall not overlap.

Ownership and access are distinct.

Ownership means responsibility for behavior, contract, data semantics, and conformance.

Access means permitted communication through a published contract or, for Providers, Service-owned implementation integration.

Access to a capability does not transfer ownership of that capability.

---

Runtime

A Runtime is the member's interface to the platform.

A Runtime receives member interaction, communicates with the platform, and presents the member's world using the capabilities of its execution environment.

Examples include web browsers, desktop applications, mobile applications, wearable devices, spatial computing devices, and future execution environments.

A Runtime SHALL:

• receive member interaction;
• authenticate Members through the API;
• construct canonical Calls;
• submit Calls to World;
• receive canonical Datasets from World;
• present those Datasets;
• execute Runtime-specific presentation behavior.

A Runtime SHALL NOT:

• determine member intent;
• perform orchestration;
• communicate directly with Conductor;
• communicate directly with Services;
• communicate directly with Models.

The Runtime owns presentation.

The Runtime presents canonical Datasets received from World. It does not determine their canonical content or meaning.

---

API

The API is the public entry point into the platform.

The API establishes authenticated Member identity before a request enters the architectural flow.

The API SHALL:

• authenticate Members;
• issue signed access tokens;
• validate authentication credentials;
• expose public authentication endpoints.

The API SHALL NOT:

• construct the Member's world;
• perform orchestration;
• invoke Services;
• perform reasoning.

Following authentication, Runtime requests are directed to World.

---

World

World constructs the Member's world.

World receives canonical Calls from Runtime, maintains world continuity, submits Calls requiring platform execution to Conductor, receives canonical Datasets from Conductor, composes the resulting World Dataset, and returns that Dataset to Runtime.

World constructs the canonical Dataset representing the Member's world. It does not determine how that Dataset is presented.

World does not own orchestration.

World does not own presentation.

World SHALL:

• receive canonical Calls from Runtime;
• validate Runtime requests;
• determine whether a request may be satisfied locally;
• submit canonical Calls to Conductor when platform execution is required;
• receive canonical Datasets from Conductor;
• compose canonical World Datasets;
• preserve world continuity;
• apply canonical Placement;
• return canonical Datasets to Runtime.

World SHALL NOT:

• determine member intent;
• coordinate Models;
• invoke Services;
• perform presentation.

World communicates only with Runtime and Conductor.

---

Conductor

Conductor is the orchestration component of the platform.

Conductor receives canonical Calls from World and coordinates the work required to satisfy those Calls.

Conductor owns orchestration, including Service Registry.

Conductor does not own domain behavior.

Conductor SHALL:

• receive canonical Calls from World;
• evaluate the current execution context;
• determine how a Call should be fulfilled;
• index Service Publications through Service Registry;
• search indexed Service Publications through its Service Registry;
• coordinate one or more Models;
• coordinate one or more Services;
• receive canonical Datasets from participating Services;
• assemble a canonical Dataset;
• return that Dataset to World.

Conductor SHALL NOT:

• present information;
• own domain data;
• implement Service-specific behavior.

Conductor communicates only with World, Models, and Services.

---

Services

Services provide platform capabilities.

Every Service owns one platform domain.

A Service publishes one canonical Service contract defining the interface through which its capabilities may be consumed by authorized platform components and other Services.

Services expose platform interfaces.

Services do not expose public client interfaces.

Members, Runtimes, and external clients never invoke Services directly.

A Service SHALL:

• own one domain;
• publish and maintain one Service contract;
• publish a Service Publication that identifies the Service and its Service contract;
• authenticate and authorize callers;
• accept requests defined by its published Service contract;
• perform domain-specific behavior;
• return responses defined by its published Service contract;
• communicate with other Services only through their published Service contracts;
• use Providers when required to perform domain-specific behavior.

A Service SHALL NOT:

• expose a public client interface;
• accept direct Member or Runtime access;
• perform platform orchestration;
• assume responsibilities belonging to another Service;
• depend upon the internal implementation of another Service.

Services may independently use the same Provider.

Use of a Provider does not establish ownership of that Provider or create a dependency between Services using it.

Conductor consumes Service contracts as an authorized platform component.

Services may consume other Services when their domain behavior requires capabilities provided by those Services.

The same Service contract governs every authorized consumer. Services do not publish consumer-specific contracts.

Service-to-Service communication is authenticated, authorized, and contract-governed.

Service-to-Service communication does not transfer ownership of domain behavior.

Service contracts shall not require circular dependencies between Services to complete.

A Service domain may be reasoning.

Reasoning Services are Services and conform to the same Service rules as every other Service.

Examples of first-party Services include:

• Mind
• Find
• Maps
• Messages
• Paint
• Storage
• Time

Additional Services may be introduced without changing the platform architecture.

---

Providers

Providers supply external information, capabilities, computation, or infrastructure used by Services.

Providers exist outside the Elonn architecture and are not owned by the Services that use them.

A Provider may be used by one Service or by multiple Services independently.

Services are responsible for integrating the Providers they use and for translating Provider-specific behavior and data into the canonical structures and behavior defined by their Service contracts.

Provider-specific protocols, credentials, data structures, and implementation details shall not cross a Service boundary.

Use of the same Provider by multiple Services does not create a relationship between those Services.

Replacing a Provider used by a Service shall not require architectural changes elsewhere in the platform.

---

Models

Models perform reasoning.

Models are implementation technologies rather than architectural components.

Models communicate only with Conductor.

Models SHALL:

• receive reasoning requests from Conductor;
• perform reasoning;
• return reasoning results to Conductor.

Models SHALL NOT:

• communicate directly with Runtime;
• communicate directly with API;
• communicate directly with World;
• communicate directly with Services.

The platform architecture is independent of any particular Model implementation, reasoning technique, or vendor.

---

Admin

Admin is the administrative component of the platform.

Admin provides administrative observation, control, and management of the platform's architectural components.

Admin operates on the Admin Plane. It does not participate in Member-plane execution.

Admin is not a Service.

Admin SHALL:

• observe the administrative state reported by architectural components;
• issue authorized administrative operations to the component that owns the affected state or behavior;
• maintain administrative and operational history, including metrics, events, execution records, diagnostics, and audit records;
• maintain administrative identity, authentication, and authorization distinct from Member-plane identity and authorization;
• communicate with each architectural component only through that component's own administrative interface.

Admin SHALL NOT:

• publish a Service Publication or Service Contract;
• be indexed by Service Registry;
• be selected by Conductor to fulfill a Member Call;
• modify a component's domain state or storage directly, bypassing that component's administrative interface;
• become an alternative source of domain truth for a component it administers;
• introduce identifiers, metadata, or other administrative concerns into Member-plane communication solely for administrative purposes.

---

Architectural Boundaries

Architectural components communicate exclusively through published boundaries and contracts.

Components exchange canonical structures.

Components do not depend upon the internal implementations of other components.

Public access terminates at the platform boundary.

Member-facing access occurs through Runtimes.

Public authentication access occurs through the API.

Authenticated Runtime access to platform execution occurs through World.

Conductor, Services, and Models are internal platform interfaces.

Services are never directly exposed to Members, Runtimes, or external clients.

---

Runtime ↔ API

The Runtime communicates with the API to establish Member identity.

The API authenticates the Member and issues an access token.

The API does not construct the Member's world.

---

Runtime ↔ World

The Runtime submits canonical Calls to World and receives canonical Datasets from World.

World determines the canonical content returned in response to a Call.

The Runtime determines how that content is presented to the Member.

The Runtime shall preserve the meaning of the canonical Dataset it receives.

---

World ↔ Conductor

World submits canonical Calls requiring platform execution to Conductor.

Conductor coordinates the work required to satisfy those Calls and returns canonical Datasets to World.

World does not invoke Services or Models on behalf of the Member.

Conductor owns platform orchestration.

---

Conductor ↔ Models

Conductor coordinates Models when reasoning is required.

Models perform reasoning and return results to Conductor.

Models do not participate directly in communication with World, Runtime, or Services.

---

Service Publications

Services publish Service Publications.

Service Publications identify Services, describe selectable capabilities, and locate published Service contracts.

Service Publication is the authority for deciding whether to consider a Service.

Conductor indexes Service Publications into its Service Registry.

Conductor uses its Service Registry to search indexed Service Publications before selecting candidate Services.

Conductor retrieves the current Service contract when a candidate Service needs to be validated for invocation.

Services do not use the Service Registry as a capability interface.

Services may publish updated Service Publications when their contract publication changes.

Service Publications do not define endpoint paths, request schemas, response schemas, authorization rules, privacy rules, side effects, error semantics, Service-specific structures, or operational invocation semantics.

Service Publications do not redefine Service behavior, duplicate Service contracts, or authorize use of a Service capability by themselves.

Authorization to use a Service remains the responsibility of the called Service.

---

Service Access

Services expose authenticated platform interfaces defined by their published Service contracts.

They do not expose public client interfaces as part of the platform architecture, other than a Service's own human-facing interface under § Service Interfaces.

Conductor may invoke Services according to their published contracts.

A Service may invoke another Service according to that Service's published contract when the calling Service is authenticated and authorized to do so.

The same Service contract governs every authorized consumer. Services do not publish consumer-specific contracts.

Service-to-Service communication does not transfer ownership of domain behavior. Each Service remains responsible for its own domain.

Nested Service calls shall preserve authentication, authorization, and distributed tracing.

Service discovery occurs through Conductor-owned Service Registry.

A Service contract shall not require another Service contract that requires the original Service contract in order to complete.

---

Service Interfaces

A Service may provide its own human-facing interface in addition to its canonical Service contract.

Elonn Runtimes shall interact with Services through the platform architecture and shall not depend on a Service's human-facing interface.

A Service's human-facing interface is not an Elonn Runtime and does not define canonical representation or presentation requirements for Runtimes.

Service capabilities exposed through a human-facing interface and through the canonical Service contract should operate on the same underlying service state and behavior.

---

Services ↔ Providers

Services may use Providers to obtain external information, capabilities, computation, or infrastructure required by their domain behavior.

A Service owns its integration with a Provider.

It does not own the Provider.

Multiple Services may independently use the same Provider.

Each Service remains responsible for translating Provider-specific behavior and data into the structures and behavior defined by its own Service contract.

Provider-specific protocols, credentials, data structures, and implementation details do not cross the Service boundary.

Use of a common Provider does not create an architectural relationship between the Services using it.

External formats terminate at the Service boundary. Services return canonical data according to their contracts.

---

Admin ↔ API

Admin observes administrative information reported by API and issues authorized administrative operations to API's administrative interface.

API performs administrative operations affecting authentication, member access state, and credentials.

Admin does not directly modify API's authentication or member storage.

---

Admin ↔ World

Admin observes administrative information reported by World and issues authorized administrative operations to World's administrative interface.

World performs administrative operations affecting its configuration, maintenance state, and diagnostics.

Admin does not directly modify World's storage.

---

Admin ↔ Conductor

Admin observes administrative information reported by Conductor, including Service and Models transaction execution records that Conductor orchestrates in both directions, and issues authorized administrative operations to Conductor's administrative interface.

Conductor performs administrative operations affecting Service Registry availability, orchestration configuration, and maintenance state.

Admin does not select Services on Conductor's behalf and does not bypass Service Registry.

---

Admin ↔ Models

Admin observes administrative information reported by Models, including model and provider usage, cost, and latency, and issues authorized administrative operations to Models' administrative interface.

Models performs administrative operations affecting model and provider availability, credentials, and usage limits.

Admin does not perform reasoning and does not communicate directly with a Model implementation or Provider.

---

Admin ↔ Service

Admin observes administrative information reported by a Service, limited to that Service's own internal behavior, and issues authorized administrative operations to that Service's administrative interface.

A Service performs administrative operations affecting its own configuration, maintenance state, and Provider integration.

Admin does not invoke a Service's published Service Contract and is not indexed by Service Registry.

---

Admin ↔ Runtime

Admin observes administrative information reported by a Runtime instance, limited to capabilities the Runtime explicitly exposes, and may issue a defined set of administrative operations to the Runtime's administrative interface.

Administrative control of a Runtime does not imply unrestricted control of a Member's device.

---

Boundary Integrity

Architectural boundaries define authority as well as communication.

A component may communicate across an architectural boundary only when that communication is permitted by the applicable contract.

Permitted platform communication paths are:

• Runtime to API;
• Runtime to World;
• World to Conductor;
• Conductor to Models;
• Conductor to Services;
• Service to Service.

The following paths are prohibited:

• Member to Service via the platform architecture (i.e. bypassing World and Conductor to reach a Service's platform interface);
• Runtime to Conductor;
• Runtime to Service;
• Runtime to Model;
• World to Service;
• World to Model;
• Model to Service;
• Member to Admin via the platform architecture (Admin's administrative interface is not a Member-facing interface).

Service-to-Service communication is explicitly permitted when authenticated, authorized, and governed by the called Service's published contract.

A Member may access a Service's own human-facing interface directly, under § Service Interfaces. This does not exercise the Runtime, World, or Conductor architecture and is not a Member-to-Service path within the meaning of this section — it is a separate, bounded surface a Service may choose to offer, governed by § Service Interfaces rather than this permitted/prohibited path list.

Admin-plane communication is governed separately from the Member-plane paths above. Permitted administrative communication paths are:

• Admin to API;
• Admin to World;
• Admin to Conductor;
• Admin to Models;
• Admin to Service;
• Admin to Runtime.

Each path is bidirectional: administrative observation flows from the component to Admin, and authorized administrative operations flow from Admin to that component's administrative interface. Admin is not indexed by Service Registry and is never selected by Conductor to fulfill a Member Call.

Services may communicate with Providers as required by their domain behavior.

Provider access does not constitute communication across an Elonn architectural boundary because Providers exist outside the Elonn architecture.

Required circular Service dependencies are prohibited.

A Service may access another Service, but no Service may require a dependency loop to satisfy its published contract.

Maintaining these boundaries preserves domain ownership, prevents implementation coupling, and permits Services and platform components to evolve independently.

---

Canonical Data Model

The Canonical Data Model defines the common language of the Elonn platform.

Every canonical structure exchanged across an architectural boundary is defined by the Canonical Data Model.

The Canonical Data Model establishes structure.

Architectural contracts establish meaning.

Implementations consume those contracts.

The Canonical Data Model is independent of:

• programming languages;
• operating systems;
• serialization formats;
• storage technologies;
• deployment topology;
• Runtime implementation;
• Service implementation;
• Provider implementation;
• Model implementation.

---

Canonical Structures

The Canonical Data Model defines the platform's canonical structures.

Core structures include:

• Call
• Dataset
• Object
• Collection
• Relationship
• Action
• Resource
• Placement
• Context

These structures provide the vocabulary shared by every architectural component.

---

Objects

Objects are the fundamental units of information within the platform.

Objects represent identity.

All remaining canonical structures organize, describe, relate, locate, or interact with Objects.

An Object may evolve throughout its lifetime.

Its identity shall remain stable.

---

Canonical Authority

Every canonical structure has exactly one authoritative definition.

Canonical structures shall not be redefined by:

• architectural components;
• Services;
• Providers;
• contracts;
• implementations;
• documentation.

The Canonical Data Model is the sole authority defining canonical structures.

---

Composition

Architectural components compose canonical structures.

They do not redefine them.

Contracts describe how canonical structures are exchanged across architectural boundaries.

Implementations determine how those structures are produced and consumed.

Canonical meaning remains independent of implementation.

---

Canonical Publication

The authoritative Canonical Data Model is published at:

https://dev.elonn.com/public/canonical/

The canonical JSON definitions are normative.

The accompanying Markdown documentation explains those definitions for human readers.

This specification references the Canonical Data Model.

It does not redefine it.

---

Service Contract Model

Every Service publishes exactly one Service contract.

A Service contract defines the complete platform interface of that Service.

No Service behavior exposed to the platform shall exist outside the published contract.

---

Contract Authority

A Service contract defines:

• Service identity;
• Service purpose;
• platform endpoints;
• authentication requirements;
• authorization requirements;
• request structures;
• response structures;
• canonical structures used by the Service;
• error semantics;
• compatibility requirements.

Implementations conform to Service contracts.

Service contracts do not conform to implementations.

---

Contract Structure

Every Service contract consists of:

• a canonical JSON representation;
• a Markdown representation.

The canonical JSON representation is normative.

The Markdown representation documents that canonical definition for human readers.

Neither representation may contradict the other.

---

Contract Discovery

Published Service contracts are located through Service Publications indexed by the Service Registry.

Service Registry is Conductor-owned.

Conductor indexes Service Publications published by Services.

Service Registry is the authoritative Service discovery responsibility for indexed Service Publications.

It does not redefine Service behavior.

It does not duplicate Service contracts.

It does not replace Service contracts.

The Service Publication is the compact discoverable publication.

The Service Publication is not a Dataset.

The Service Publication is the authority for deciding whether to consider a Service.

The Service contract is the authoritative interface.

The Service contract is the authority for using a Service.

---

Canonical Structures

Service contracts reference canonical structures.

They do not redefine canonical structures.

Existing canonical structures shall be reused whenever they accurately represent the required concept.

When no suitable canonical structure exists, a Service may define Service-specific structures or propose a canonical extension.

---

Contract Evolution

Service contracts evolve independently of implementations.

Backward compatibility should be preserved whenever practical.

Breaking changes require a contract revision.

Every revision shall be documented by the owning Service.

---

Contract Governance

The Contract Authoring Guide defines the required structure, publication requirements, and governance of Service contracts.

This specification defines the architectural role of Service contracts.

It does not redefine contract authoring requirements.

The Contract Authoring Guide is located at https://dev.elonn.com/public/guides/contract-authoring-guide.md

---

Identity and Authentication

Identity enters the platform through the API.

The API authenticates Members before any platform execution occurs.

Architectural components trust authenticated identity.

They do not authenticate Members independently.

Authentication establishes identity.

Authorization determines what an authenticated identity is permitted to do.

These responsibilities remain distinct throughout the platform.

---

Member Identity

A Member authenticates through the API.

Following successful authentication, the API issues a signed access token.

The Runtime presents that token when communicating with World.

World validates the token before accepting a Call.

Member credentials do not proceed beyond the API boundary.

---

Component Identity

Architectural components authenticate one another independently of Member authentication.

Component authentication establishes the identity of the calling component.

Member identity and component identity represent different concepts.

Both may exist simultaneously during execution.

---

Trust Boundaries

Every architectural boundary establishes trust independently.

Authentication at one boundary does not eliminate the responsibility to authenticate at the next boundary.

Each component authenticates callers for every permitted communication path.

---

Authorization

Authorization determines whether an authenticated identity may perform a requested operation.

Authorization decisions belong to the architectural component responsible for the protected capability.

Authentication identifies.

Authorization permits.

---

Security Principles

Architectural components SHALL:

• authenticate callers;
• validate received credentials;
• preserve authenticated identity;
• reject invalid authentication;
• protect implementation secrets.

Architectural components SHALL NOT:

• expose Member credentials;
• expose Provider credentials;
• expose implementation secrets across architectural boundaries;
• expose internal execution state outside published contracts.

Security mechanisms may evolve independently provided architectural contracts remain satisfied.

---

Member Authentication

Authentication establishes Member identity before a Member enters the platform.

The API is responsible for authentication.

Runtimes are responsible for presenting an authentication experience appropriate to their execution environment.

The architecture distinguishes between authentication and the user experience used to perform authentication.

---

Authentication Experiences

A Runtime may authenticate a Member in one of two ways.

Platform Authentication

The platform provides a standard web-based authentication experience.

Browser-based Runtimes may redirect the Member to this authentication experience.

The platform authentication experience communicates with the API to authenticate the Member.

Upon successful authentication, the Member returns to the originating Runtime with an authenticated identity.

---

Runtime Authentication

A Runtime may provide its own authentication experience.

Native desktop applications, mobile applications, spatial computing devices, and future Runtimes may authenticate Members directly through the API.

The authentication experience is determined by the Runtime.

Authentication itself remains the responsibility of the API.

---

Browser Authentication Flow

Member
    │
    ▼
Web Runtime
    │
    ▼
Platform Authentication
    │
    ▼
API
    │
    ▼
Authenticated Member
    │
    ▼
Access Token
    │
    ▼
Web Runtime
    │
    ▼
World

---

Native Runtime Authentication Flow

Member
    │
    ▼
Runtime
    │
    ▼
API
    │
    ▼
Authenticated Member
    │
    ▼
Access Token
    │
    ▼
World

---

Authentication Result

Successful authentication establishes:

• authenticated Member identity;
• an access token representing that identity;
• an authenticated Runtime.

Authentication does not construct the Member's world.

The Member enters the platform only after the Runtime submits its first Call to World.

---

Authentication Independence

Authentication is independent of Runtime implementation.

Every Runtime authenticates through the API.

Different Runtimes may provide different authentication experiences while preserving the same architectural behavior.

The introduction of a new Runtime shall not require changes to the platform authentication architecture.

---

Extension Model

The Elonn platform is designed to evolve through extension rather than modification.

New capabilities are introduced by adding Services, Providers, Models, Runtimes, Service Publications, or canonical extensions rather than modifying established architectural boundaries.

---

Architectural Stability

Architectural boundaries are intended to remain substantially more stable than implementations.

Most platform growth should occur through:

• additional Services;
• additional Providers;
• additional Models;
• additional Runtimes;
• additional Service Publications;
• canonical extensions.

The architecture should change only when existing architectural responsibilities have become insufficient.

---

Adding a Runtime

A Runtime extends the ways Members interact with the platform.

Examples include:

• web browsers;
• desktop applications;
• mobile applications;
• wearable devices;
• spatial computing devices;
• future execution environments.

Every Runtime communicates through the Runtime-World contract.

Every Runtime preserves canonical meaning.

Presentation may differ.

Meaning shall not.

---

Adding a Service

A Service extends the capabilities of the platform.

Every Service owns one domain.

Every Service publishes one Service contract and one Service Publication that makes that contract indexable by Conductor.

Conductor and authorized Services consume a Service through that Service's published contract.

A Service may communicate with other Services when its domain behavior requires their capabilities.

A Service may use Providers when its domain behavior requires external information, capability, computation, or infrastructure.

Adding a Service shall not require modification of existing Services.

---

Adding a Provider

A Provider extends the external information, capabilities, computation, or infrastructure available to one or more Services.

A Service may introduce, replace, or remove a Provider without changing the platform architecture or its published Service contract, provided the Service continues to satisfy that contract.

Multiple Services may independently integrate the same Provider.

Adding a Provider does not add an architectural component or establish a relationship between Services that use it.

---

Adding a Model

Models extend the reasoning capabilities available to Conductor.

The architecture does not prescribe:

• reasoning technique;
• model vendor;
• model topology;
• execution environment;
• implementation technology.

Replacing or adding Models shall not require architectural changes elsewhere in the platform.

---

Canonical Evolution

The Canonical Data Model evolves deliberately.

Existing canonical structures should be reused whenever possible.

New canonical structures should be introduced only when existing structures cannot accurately represent the required concept.

Canonical evolution should strengthen consistency across the platform.

---

Conformance

An implementation conforms to this specification only if it satisfies the requirements applicable to the architectural components it implements.

Conformance is determined by architectural behavior rather than implementation technology.

---

Runtime Conformance

A conforming Runtime SHALL:

• authenticate Members through the API;
• communicate only with API and World;
• construct canonical Calls;
• present canonical Datasets;
• preserve canonical meaning.

---

API Conformance

A conforming API SHALL:

• authenticate Members;
• issue signed access tokens;
• establish authenticated identity;
• expose only public authentication interfaces.

---

World Conformance

A conforming World SHALL:

• communicate only with Runtime and Conductor;
• construct canonical World Datasets;
• preserve world continuity;
• determine canonical world content without performing presentation.

---

Conductor Conformance

A conforming Conductor SHALL:

• communicate only with World, Models, and Services;
• coordinate platform execution;
• coordinate reasoning;
• coordinate Services;
• own Service Registry;
• index Service Publications published by Services;
• search indexed Service Publications through its Service Registry;
• return canonical Datasets to World;
• remain independent of domain behavior.

---

Service Conformance

A conforming Service SHALL:

• own one platform domain;
• publish one Service contract;
• publish a Service Publication that makes its Service contract indexable by Conductor;
• accept authorized calls from Conductor and Services through its published Service contract;
• communicate with other Services only through their published Service contracts;
• use Providers only as Service-owned implementation integrations;
• avoid required circular Service dependencies;
• own its domain behavior;
• remain independent of presentation and orchestration.

---

Provider Conformance

Providers are external to the Elonn architecture and therefore do not conform to this specification.

Services that use Providers remain responsible for satisfying their Service contracts and all applicable architectural requirements.

Provider-specific protocols, credentials, data structures, and implementation details shall not cross the Service boundary.

The use, replacement, or failure of a Provider shall not alter the architectural responsibilities of the Service using it.

---

Model Conformance

A conforming Model SHALL:

• communicate only with Conductor;
• perform reasoning only;
• remain independent of Runtime, World, and Services.

---

Operational Independence

Architectural behavior is independent of deployment topology.

The responsibilities assigned by this specification remain unchanged regardless of how components are deployed.

Components may execute:

• within one process;
• across multiple processes;
• on one machine;
• across multiple machines;
• on-premises;
• in cloud infrastructure;
• in hybrid deployments;
• within future execution environments.

Deployment choices do not alter architectural responsibilities.

---

Implementation Independence

The platform does not require a particular:

• programming language;
• framework;
• operating system;
• storage engine;
• transport implementation;
• rendering engine;
• reasoning technology.

Implementations may evolve independently while preserving architectural contracts.

---

Performance

Caching, indexing, batching, streaming, asynchronous execution, parallel execution, and future optimization techniques may be employed provided they preserve canonical meaning and contractual behavior.

Performance is an implementation concern.

Correctness is an architectural concern.

---

Long-Term Evolution

The architecture is intended to remain substantially more stable than the implementations built upon it.

Future capabilities should emerge through:

• new Services;
• new Providers;
• new Models;
• new Runtimes;
• new Service Publications;
• canonical extensions.

Architectural boundaries should evolve rarely and deliberately.

---

Normative References

The following documents form part of the Elonn architectural specification.

Canonical Data Model

Defines every canonical structure exchanged throughout the platform.

https://dev.elonn.com/public/canonical/

---

Contract Authoring Guide

Defines the required structure, publication requirements, governance, and lifecycle of every published Service contract.

https://dev.elonn.com/public/contract-authoring-guide.md

---

Component Specifications

Each architectural component publishes its own specification describing its responsibilities, behavior, internal architecture, and implementation constraints.

Component specifications expand upon this document.

They do not redefine it.

---

Service Contracts

Every Service publishes one Service contract.

That contract defines the complete platform interface of the Service.

---

Closing Statement

This specification defines the architecture of the Elonn platform.

The platform separates presentation, world construction, orchestration, reasoning, Service discovery, domain behavior, and implementation from architecture.

Architectural components communicate exclusively through canonical structures and published contracts.

By preserving these boundaries, the platform remains extensible, independently deployable, replaceable, technology-independent, and capable of evolving without fundamental architectural change.