Overview

The Xema system layer lets humans, agents, workflows, and external apps share one substrate of typed objects, capability-mediated invocations, and installable software bundles called biomes.

---

Who Xema is for

• Org admins deciding which biomes to install, what each one is allowed to do, and how external audiences reach the org.
• Biome authors packaging domain capabilities — agents, skills, workflows, connectors, document templates, UI surfaces — without reaching into other biomes or platform internals.
• Integrators embedding Xema into their own customer-facing products through delegated identities and scoped capability grants.
• Agents that need a stable, self-describing surface to discover what exists, what they may invoke, and why a call was denied.

---

The four primitives + Agent Composition

Agent capability in Xema is built from exactly four primitives:

• Skill — a folder bundle that teaches an agent how to do something.
• Tool — an executable capability (MCP-exposed or kernel-built-in) an agent can call.
• Model — an LLM provider/model pair, resolved per-invocation by the Model Resolution Matrix.
• Agent — an agent definition (identity, prompt, intrinsic skills, intrinsic tools).

Agent Composition wires them together: an agent armed with skills and tools whose sub-agents are themselves fully-armed composition nodes. The same composition is usable as both an interactive-session agent and a workflow step.

Xema does not add a fifth primitive. The Object Model, Capability Protocol, and the biome package format are the substrate over which the four primitives compose.

---

The four-concept runtime model

Every capability call in Xema is described by exactly four concepts working together:

• Space — where the data lives and who owns it (a hierarchical URI from System down to User, with a data-classification floor).
• Execution Environment — which trust profile applies to this call (system, org, project, app, session, sandbox, public, store-review, trusted-dev).
• Execution Context — the per-invocation envelope binding subject, Space, Environment, capability, and input.
• Policy — the decision protocol that turns an Execution Context into allow / deny / needs_approval plus obligations and route hints.

A Subject invokes a Capability exposed by a Biome, against an object in a Space, from an Execution Environment, executed by a Runner, when Policy allows it.

---

Seven conceptual architecture layers

These are a product-explanation model, from infrastructure to experience. They are not the repository's dependency tiers. Code and biome boot order use the four enforced scope tiers kernel, system, base, and platform.

---

The Xema System Interface (XSI)

XSI is the stable external interface every biome, app, agent, workflow, and external surface speaks. One protocol, five planes:

1. Object Model — the typed universe of things Xema knows about (XemaObject, XemaObjectKind), each anchored to a Space.
2. Contribution Protocol — how new objects and behaviors enter the platform (kernel-typed envelope, closed ContributionKind enum, backend slot registry).
3. Capability Protocol — how those objects are invoked. Every call carries an Execution Context and routes through the capability router.
4. Execution Environment Protocol — which trust profile applies to a call. Nine built-in environments: system, org, project, app, session, sandbox, public, store-review, trusted-dev.
5. Manifest / Wire — how all of the above are declared in the biome manifest through requires, contributions, requiresCapabilities[], exposesCapabilities[].

---

The eight primitives

Every concept the runtime mediates falls into one of eight primitives:

1. Subject — who is calling (user, agent, app client, external subject, service, runner).
2. Capability — what is being invoked (<domain>:<resource>.<verb>@<major>).
3. Biome — the installable bundle exposing the capability.
4. Object — the typed thing the capability touches (XemaObject).
5. Space — where the object lives and who owns it.
6. Execution Environment — what trust profile the call runs under.
7. Runner — where the implementation actually executes (embedded / local-module / remote).
8. Policy — the decision protocol that mediates everything above.

Plus the per-invocation envelope that wires them together: Execution Context.

---

Deployment profiles

Xema deploys in four profiles from the same codebase. There is no separate product model between development and production.

The profile records deployment intent; it is not a code-path fork. KernelStateProfile has exactly these three members, and every one of them resolves to the same coordination-store adapter — the member count is a deployment detail, not a different implementation. There is no in-process, embedded-file or single-binary variant of the kernel state, and the relational store is never a substitute for it. The same is true one level up: the set of backing services a deployment provisions is identical across profiles, so a behaviour that only appears in production is a configuration difference, never a different code path.

Capability calls produce identical PolicyDecision outputs across all three profiles for the same ExecutionContext.

---

Where to go next

• Objects — how Xema represents every addressable thing as a typed XemaObject.
• Capabilities — the invocation plane every biome calls through.
• SDK / Getting Started — author your first biome manifest.
• Manifest Reference — the generated, field-by-field current manifest contract.

---

Next: Objects →