This document describes the intended system architecture. GitHub issues own current status and proof; COMMAND_MATRIX.md defines command expectations and SECURITY.md records security findings.
First-party apps run as web projections in the browser's opaque sandboxed frames. Runtime checks each app's signed launch token and actor before it performs an effect. Home can currently obtain every app's capability, so a compromised Home can reach those apps' authority. The target limits Home to delegation and gives each app a separate, revocable capability. The WASM Component authoring path runs in Wasmtime with memory and fuel limits and Runtime Bus hostcalls.
Providers run as native operating-system processes with the Runtime user's rights. Only the model provider is partly confined. The trusted shell helper also runs as a native host process. The web Terminal is disabled by default; host developer mode and closed guest registration are required to enable it. An enabled Terminal runs commands with the host user's rights.
The seed operator can read hosted data, wallet keys and recovery material. Passkeys control sign-in; stored data and keys remain accessible to the Runtime account and root while Home is locked. Protection against hosted operators and root, and against other software or OS users while a self-hosted Home is locked, is the target of hosted protection and locked Home protection. An unlocked self-hosted Home trusts its owner and their host software. Recovery from a stolen device or profile key requires a new identity.
The isolation plan records the remaining gates. Source checks describe this source tree. Accepted installed proof binds the exact Runtime, components and app assets to the journeys tested on that device.
The target keeps the trusted Runtime small. Ordinary executable capsules run without ambient authority and request scoped effects through Runtime-owned capability checks. Providers implement service and protocol behavior outside the trusted core. Content hashes establish integrity, not publisher identity, authority, or availability.
PRINCIPLES.md owns these rules. The glossary owns product terminology, and CAPSULE_MODEL.md supplements this document with capsule layers and lifecycle.
The four quadrants divide responsibility within the ElastOS World Computer model. Together they describe one product with one trusted-core boundary. The division keeps protocol behavior out of Runtime and prevents apps from regaining ambient internet authority.
| Quadrant | Responsibility | In this repo | Must not become |
|---|---|---|---|
| Home (PC2) | Human front door, object browser, spaces, people, app install/launch UX | Home, System, Inbox, Library, Documents, browser host adapters | trusted-core policy logic or protocol implementation |
| Runtime | Isolation, verification, principals, sessions, capabilities, object routing, audit | elastos Runtime core, capsule launch, provider routing, Home authority checks |
app business logic, social-network bridge, wallet app, or storage backend |
| Carrier | Endpoint-authenticated transport for objects, messages, streams, discovery, sync, replication, and content delivery | Carrier abstraction and provider-facing transport contracts | chat-only transport, raw gossip exposed to apps, or replacement for capabilities |
| Blockchain | DID/EID, wallet signing, provenance anchors, publisher identity, receipts/licensing hooks | Runtime-facing provider boundary for identity/provenance operations | app database, mandatory UX blocker, DeFi-first layer, or runtime business logic |
Executable effects enter Runtime through a substrate-specific surface. Components use ElastOS Bus. Web projections and MicroVMs use narrow, capsule-scoped Runtime adapters. Every surface enters Runtime's authority and routing boundary. Runtime handles core operations directly and sends provider-backed effects through the provider registry.
Discovery and trust records do not grant authority. Runtime owns authority, routing, lifecycle, and audit; providers own operation and protocol semantics. Carrier is an endpoint-authenticated off-box transport selected below Runtime routing, not a capsule API. Endpoint authentication does not prove message authorship. Principle 4 owns the full boundary. See CARRIER.md and BROWSER_CAPSULE.md for their concrete contracts.
This is the implemented contract shape, not a claim that every product App has
migrated substrates. In the current source, the Component runner is exercised
by a conformance fixture and authoring template; all shipped first-party UI Apps
remain elastos.runtime-projection/v1 web projections.
A verified signed collaboration-network profile supplies the Runtime's bounded bootstrap peers and authenticates the content-addressed default-conversation grant. The Runtime collaboration service, durable core, and transport driver own that authority and give Carrier only opaque signed envelopes. Configured Chat text receives typed projections from the Runtime-owned product port and never receives tickets, endpoints, raw sockets, or Carrier topics. The collaboration candidate's bounded People discovery uses the same Runtime-owned path. Wider discovery rendezvous and the old Services remote-Exit social/contact path remain separate work.
Sequencing and incomplete work belong in GitHub issues. This document defines the following authority and recovery invariants:
- A passkey proves local principal authority. It is not a DID, wallet key, decryption key, or source of ambient administrator authority.
- Each principal owns a distinct
localhost://Users/<principal-root>area. Closing enrollment does not revoke existing principals. - Removing a credential revokes access, not storage. Recovery or reassignment must prove the exact principal, root, and protection key before changing bindings or data.
- Recovery must validate every declared protected object before mutation, revoke replaced sessions, and leave an audit trail. It must not fall back to a device-global key.
- Protection configured, root encrypted, and root recoverable are separate claims. Private-data acceptance owns coverage and exclusions.
The glossary defines principals, passkeys, DIDs, CIDs, IPLD, and human-readable names. The architecture keeps their authority claims separate.
Do not add a did:localhost shortcut unless ElastOS defines and implements a
DID method for it. Local accounts already have runtime principals and
localhost://Users/<principal-root> roots. If a user wants to claim alice
globally, that claim must go through an EID/DID-chain namespace or equivalent
registry with consensus-backed uniqueness, transfer, expiry, recovery, and
signed ownership. Local display handles can collide; global names cannot.
An authority decision must verify every principal ID, DID, signature, CID, or signed head it relies on. An unverified handle string cannot carry authority. A CID does not need its own DID by default. A mutable object or collection may later have a signed object identity or object DID that points to successive CID revisions.
WebAuthn relying-party scope is part of the authority contract. Hosted Home uses the hosted HTTPS origin; localhost development uses loopback HTTP origins; installed PWAs inherit their install origin. These worlds do not share passkeys unless a future native/mobile adapter is modeled as an explicit proof adapter. Malformed or insecure browser origins must fail closed instead of falling back to the runtime host authority.
Published objects should use IPLD-compatible content graphs when the graph aids traversal, provenance, signed heads, or availability receipts. IPLD is the object graph model. Carrier provides coordination and transport. The content provider owns publish, fetch, status, and repair policy. See CONTENT_AVAILABILITY.md.
Person or agent
|
Home front door and active shell projection
|
Runtime launch and orchestration authority
|
executable capsule instance (boundary depends on substrate)
|
+-- Component ----------------> ElastOS Bus ------------+
| |
+-- Web / MicroVM / other --> narrow Runtime adapter ---+
|
v
Runtime effect authority
and routing
|
+----------------------+------------------+
| |
v v
Runtime-owned operation provider-backed effect
|
v
provider operation
|
v
local host adapter or Runtime-selected Carrier route
The target isolates ordinary executable capsules from host authority. Their manifests declare an execution or data contract but grant no authority. Exact fields and accepted combinations belong in CAPSULE_AUTHORING.md. The Capsule Runtime contract binds an artifact, session, capabilities, resources, state, and lifecycle. User-scoped authority also requires a verified principal. The contract should remain stable across compatible substrates.
ElastOS does not split information systems and operational systems into parallel authority stacks. A document read, sensor observation, model request, payment, rights change, and physical actuation all enter the same typed Runtime boundary. Their provider contracts impose different authority, timing, retry, settlement, and safety requirements.
The admitted provider contract describes operation semantics and hazards. Runtime sets and enforces the minimum classification and may strengthen it. A capsule declaration cannot downgrade that policy. A remote destination admits the operation independently, and a physical controller retains its local interlocks and final safety decision. Runtime does not replace a hard real-time controller.
Consequence-aware effects defines observation, actuation, settlement, ownership, and local-safety rules. It is a cross-cutting Runtime/provider contract, not another quadrant or a raw device API.
The target architecture keeps the capsule contract stable while host adapters present capsule output differently. An adapter may use a browser, native window, embedded webview, or device-owned display. These are presentation choices, not separate capsule contracts or support claims.
Capsules depend on the Capsule Runtime contract, not a presentation host. A web projection declares its browser entrypoint and projection metadata; the host adapter decides how to present it. See INSTALL.md for the contract and install/update acceptance for platform evidence.
Keep these concerns separate:
- Launch authority determines who may start a capsule.
- Session authority determines what the caller may do after connecting.
- The surface adapter determines how the capsule UI is rendered.
A web surface is only a rendering adapter. It does not define identity or authority. The Home shell contract owns sign-in, shell selection, child-message routing, launch grants, and browser-session behavior. CARRIER.md owns peer admission and member/guest boundaries.
The Windows plan runs the Linux Runtime inside WSL2 under the same Runtime and provider contracts. A planned Windows launcher would handle start, stop, update, and Home opening. Later native Windows adapters still belong behind the same Runtime and Browser contracts. See WINDOWS.md.
The Runtime core is the host-side enforcement authority. It owns capsule admission, signature verification, capability enforcement, trusted object routing, and the configured execution boundaries and lifecycle. Work that does not need that authority belongs in a capsule, provider, or explicit operator service. The Capsule Runtime is the per-capsule execution surface, not the host Runtime core.
Runtime owns sign-in authority. Home presents sign-in and Runtime facts through shell projections. A shell role is descriptive; it grants no authority. Runtime admits installed identities and checks each requested effect. See HOME_SHELL_HOST_CONTRACT.md for the current identity, lifecycle, and intent contract.
Interaction equality is part of the same rule: a visible human action and an agent request must reach the same capability-scoped Runtime operation. Human and agent architecture defines the corresponding principal, profile, session, capsule, and delegation model.
Home shell browser state may persist safe window and route descriptors for restoration, but not Browser VM Chromium profile disks, launch tokens, authority objects, or provider state. Restored windows must reacquire their Runtime lifecycle normally.
Ordinary capsules contain application, viewer, shell, or content behavior. Provider capsules are explicit service-plane exceptions with narrow declared authority. Package roles, types, execution ABIs, and checked authoring examples belong in CAPSULE_AUTHORING.md. All capsule effects still cross Runtime authority checks.
Games, local model files, and similar downloadable data are content capsules. Their stable identity is the CID of the complete immutable bundle. Signed catalog entries point to that identity, availability receipts state who retains it, and Runtime records local admission. None of those projections is a service offer.
The planned Get operation lets Home request an exact content capsule. Runtime will verify the caller and publisher, select content and availability providers, fetch and pin the CID, admit it atomically, and write a receipt. External repositories remain behind gateway provider capsules. They may import approved bytes into this normal content path but may not become ambient capsule networking or a second install rail. See Content capsule distribution.
The current catalog projects installed capsules. Network catalog discovery and Get admission remain implementation work.
These decisions keep the layers from collapsing into one another:
| Boundary | Consequence |
|---|---|
| Trusted core | Runtime contains only enforcement that must be trusted. UI and protocol policy remain outside it. |
| Capsule ABI | The checked Component and Bus contracts are the executable Component path. WASI Preview 1 is rejected at product admission. Shipped first-party UI Apps remain web projections until migrated explicitly. |
| Host adapters | HTTP, browser messaging, loopback, stdio, and in-process calls may implement an adapter, but do not become capsule APIs. |
| Provider namespace | A provider exposes a typed Runtime-facing contract. Its protocol, topology, and local bridges stay behind that contract; Runtime owns hosted model credentials. |
| Release trust | Runtime verifies expected hashes, signatures, and publisher policy regardless of the transport that delivered an artifact. |
| Carrier | Carrier is the endpoint-authenticated transport selected by Runtime for peer, message, stream, and content traffic. It does not prove message authorship, grant capabilities, or replace local dispatch. |
A boundary is still present when every component runs on one machine. Local placement may remove a network hop, but it must not remove caller validation, capability checks, provider policy, or audit. Conversely, moving a provider or engine off-box must not give ordinary capsules a transport-specific API. Provider discovery can offer a candidate endpoint; only an explicit, principal-scoped grant can make it usable.
The network boundary requires:
- Ordinary executable capsules have no ambient network.
- Components use ElastOS Bus; web projections use narrow Runtime adapters.
- Carrier and providers mediate allowed external communication.
Launch policy follows:
- Normal app capsules should launch rootless, without a TAP device or guest IP requirement.
- Internet access should require an explicit Runtime capability rather than a default NIC inside the capsule.
- Guest networking remains an explicit compatibility mode for provider capsules that require raw TCP or guest-facing network services.
Executable capsules express intent, and Runtime decides how to fulfill it.
A private network follows the same rule. Signed membership admits devices to a network, while named service access still requires source and destination Runtime authorization. Optional TUN, Exit, and LAN Gateway functions are compatibility providers behind that policy, not a second capsule network ABI. See PRIVATE_NETWORK.md.
NAMESPACES.md defines accepted schemes, current roots, and URI examples. Runtime checks capabilities and dispatches namespace operations; providers keep backend identifiers, credentials, synchronization, and transport below stable handles. HTTP and tunnels are edge transports, not trust boundaries. CONTENT_AVAILABILITY.md owns publication, fetch, repair, backend selection, IPLD graphs, and availability receipts.
Integrity, publisher trust, availability, rights, key release, and decryption are separate claims. Runtime checks authority and routes each protected-content operation to its owning provider. Ordinary capsules receive neither raw keys nor provider credentials. PROTECTED_CONTENT.md owns the access sequence and failure rules; CONTENT_AVAILABILITY.md owns publication and retrieval.
The protected-content and dKMS capsule contract is placement-neutral. A same-node key or dKMS implementation uses a private Runtime-owned adapter. A first-party production dKMS hop that crosses an ElastOS machine boundary uses Carrier as its canonical transport, while the dKMS protocol keeps its own end-to-end node authorization, encryption, signing, freshness, replay defense, and rights binding above Carrier. Carrier authenticates endpoints; it does not authorize key release. Raw CEKs never enter Runtime, Carrier, or an ordinary App. Runtime selects placement and transport; the caller does not name a dKMS peer, host path, backend, or pipe. A quorum placed on one machine is development evidence rather than proof of distributed custody.
Runtime validates a signed token against the capsule caller, action, resource, and constraints before provider routing. The token does not prove principal or session authority. Runtime verifies that context separately for user-scoped effects.
PRINCIPLES.md, ESP v0, and the Capsule interface contract define the authority boundary. Current token fields and ordered validation are enforced by Runtime code and tests; this architecture document does not duplicate them.
A CID lets Runtime detect whether fetched bytes match a trusted content reference. It does not establish who published the reference, whether the content is current, or whether it will remain available. Admission therefore also verifies the expected publisher, signatures, manifest, and policy. Mutable heads need their own rollback and freshness rules.
A trust label may inform admission policy and audit, but it grants no authority. Runtime must still verify the artifact signature against publisher policy and validate every requested effect.
| Layer | Protection |
|---|---|
| Content hash | Integrity of the referenced bytes |
| Signature | Control of a signing key; publisher policy identifies the trusted signer |
| Browser sandbox | Opaque app frames; Home still has cross-app capability authority |
| Capabilities | Authority for a checked resource operation |
| Encryption | Confidentiality only for content covered by the relevant key contract |
- Runtime loads its local identity and installed-component metadata. Each authority subsystem loads only the state its contract marks durable.
- The trusted Runtime core initializes execution boundaries, verification, capability enforcement, object routing, and the provider registry.
- Runtime serves the neutral Home front door. Principal and child-app authority remain unavailable until their required proofs and scoped grants validate.
- Runtime accepts requests, validates capabilities, manages capsule lifecycle, and routes authorized effects to providers.
The Component capsule contract is the checked elastos:bus@v1 WIT surface, not
a conceptual API in this document. Web projections, MicroVMs, and other
substrates use documented, capsule-scoped Runtime adapters. Every ingress
surface enters Runtime's authority and routing boundary. Runtime-owned
operations terminate there; provider-backed effects use the provider registry.
Orchestration surfaces can request lifecycle actions and present grant review.
Ordinary capsules can invoke only the resources covered by their scoped
authority. Runtime alone mints grants, records trusted audit facts, and owns
lifecycle cleanup. See ESP_V0.md,
CAPSULE_INTERFACE_CONTRACT.md,
HOME_SHELL_HOST_CONTRACT.md, and the WIT
definitions under elastos/wit/ for exact operations.
Provider capsules handle provider-scoped requests behind the Runtime provider registry. Provider-specific transports and behavior remain behind the Runtime boundary.
Provider namespaces and operations belong in their contract documents, not in a universal CRUD interface or hand-maintained architecture table. New provider families must define a typed contract before becoming visible in Home. The documentation index lists the current provider contracts.
For model inference, Runtime owns hosted credentials, exact HTTPS destinations, caller authority and selection policy. The confined provider owns backend adaptation, streaming, cancellation and error translation. Every hosted request, including one on a saved operator connection, needs the owner's exact Inbox approval and a matching Runtime grant; End stops its sends. Model output can propose another typed effect but cannot authorize it. See MODEL_PROVIDER.md.
Home and other orchestration surfaces request actions through scoped Runtime interfaces. Runtime validates the caller and mints target-scoped grants; transport, route, and UI placement do not confer authority. The exact Home messages, browser-origin checks, and launch-token rules belong in HOME_SHELL_HOST_CONTRACT.md.