Biome Concepts

A biome is a folder bundle with a xema-biome.json manifest at its root. It is the unit through which Xema gains a domain, integration, product surface, or shared platform capability.

The manifest declares what the biome ships and what every executable component requires. The platform decides where a component can run by matching those declarations against the installation and available execution targets.

Three extension channels

A biome extends Xema through exactly three explicit channels:

1. Components — executable or materialized artifacts declared in xema.components[].
2. Convention content directories — multi-file content such as Agents, Skills, Workflows, deliverable specs, and workspace manifests.
3. Contribution envelopes — typed single-file records under contributions/ or xema.contributions.inline[].

This separation matters. A service, an Agent definition, and a capability record have different lifecycle and runtime needs; the manifest represents each without treating all extension content as executable code.

The manifest

xema-biome.json is a wrapped { "name", "version", "xema": { … } } document. A server biome requires at least one component:

1{
2  "name": "@acme/customer-operations",
3  "version": "1.0.0",
4  "xema": {
5    "id": "customer-operations",
6    "displayName": "Customer Operations",
7    "scope": "platform",
8    "target": "server",
9    "components": [
10      {
11        "key": "content",
12        "kind": "content",
13        "artifact": { "kind": "package-content", "path": "." },
14        "entrypoint": { "kind": "materialize" },
15        "protocol": { "kind": "none" },
16        "executionModes": ["materialized"],
17        "requirements": {
18          "tenancy": { "allowed": ["org", "project"], "tenantContext": "verified" },
19          "isolation": { "minimum": "none" },
20          "trust": { "minimum": "untrusted" },
21          "locality": { "allowed": ["cloud", "customer-private"] },
22          "state": { "kind": "stateless" },
23          "resources": { "minimum": { "cpu": "1m", "memory": "1Mi", "ephemeralStorage": "1Mi" } },
24          "runtime": { "kind": "none" },
25          "io": { "ingress": "none", "egress": "none", "rawBody": false, "devices": [] },
26          "scaling": {
27            "mode": "singleton",
28            "concurrency": { "handling": "serial", "maximumPerInstance": 1 },
29            "readiness": { "kind": "none" },
30            "drain": { "kind": "none" },
31            "hints": { "cpu": "batch", "memory": "steady", "startup": "fast" }
32          }
33        }
34      }
35    ]
36  }
37}

Key fields:

The generated Manifest Reference is the field-by-field source of truth.

Components

xema.components[] replaces the retired ships.apis[] model. A component can be content, web, adapter, service, worker, or job. Its artifact.path is the authoritative filesystem location.

Every component declares its runtime contract:

• tenancy and verified tenant context;
• minimum isolation and trust;
• permitted locality;
• stateless, ephemeral, or durable state requirements;
• resource and optional accelerator needs;
• runtime and version range;
• ingress, egress, raw-body, and device needs;
• scaling, concurrency, readiness, drain, and scheduling hints.

The host can therefore refuse an unsatisfied installation rather than starting a component under weaker conditions.

Scope tiers and boundaries

Customer and third-party biomes use the platform scope. The lower kernel, system, and base scopes build Xema's own foundation.

Biomes do not import other biomes' implementation. They communicate through capabilities and published contracts. This is what keeps one domain release from becoming a source-level dependency of every other domain.

Permissions

requiresCapabilities and permission hints describe install intent. They do not grant runtime authority.

Runtime invocation still evaluates:

• the acting subject and delegation;
• Agent arming;
• resource reach and ownership;
• Space and Execution Environment;
• policy, approvals, quotas, and placement obligations.

Fresh-instance model

A biome is not synonymous with a prebuilt Xema application. A new customer can begin with the base platform and create only the integration and domain biomes it needs. Existing domain biomes demonstrate the extension model; they are not required dependencies of a fresh installation.

Next: Authoring →