Biomes

A biome is Xema's unit of extension and distribution. It packages a coherent domain or integration without modifying the Kernel or reaching into another biome's implementation.

A biome may ship:

Agents and Skills;
Workflows and structured deliverable specifications;
capability and connector contributions;
workspace manifests and provisioning scaffolds;
UI bundles and host-surface contributions;
optional services, workers, jobs, or adapters;
install-time permission and integration requirements.

Biomes are how an organization grows a fresh Xema installation into the platform it needs. The base platform supplies shared operating capabilities; customer and domain biomes add the business layer.

The current manifest model

Every biome has a xema-biome.json manifest. The current contract is component-based: xema.components[] is the authoritative list of artifacts the biome ships. The earlier ships.apis[] shape is retired.

Each component declares:

key and kind — content, web, adapter, service, worker, or job;
artifact.kind and artifact.path — the package content, web bundle, host module, or OCI image;
entrypoint and protocol — how the host starts it and how other platform surfaces interact with it;
executionModes — materialized, web-hosted, shared-host, composed, isolated, or runner;
requirements — tenancy, isolation, trust, locality, state, resources, runtime, I/O, scaling, readiness, and drain behavior.

This makes runtime requirements machine-readable. Placement and deployment do not depend on a folder name or an undocumented convention.

jsonc

1{
2  "name": "@acme/operations",
3  "version": "1.0.0",
4  "xema": {
5    "id": "operations",
6    "displayName": "Operations",
7    "scope": "platform",
8    "target": "server",
9    "components": [
10      {
11        "key": "operations-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": "steady", "memory": "steady", "startup": "fast" }
32          }
33        }
34      }
35    ]
36  }
37}

Use the generated Manifest Reference for the exact schema. It is generated from the same contract the host validates.

Scope tiers and dependency rules

xema.scope is one of four enforced boot and dependency tiers:

Scope	Purpose
`kernel`	The smallest platform foundation
`system`	System-wide operating services
`base`	Shared capabilities used by domain products
`platform`	Domain, integration, and customer biomes

Third-party and customer biomes use platform. Lower tiers are reserved for the platform foundation.

The important boundary is capability-based composition:

Kernel packages do not import biomes.
One biome does not import another biome's implementation.
Cross-biome work happens through published contracts and capabilities.

This lets domain teams evolve independently while preserving one policy and audit funnel.

Content and contributions

Biomes extend Xema through three explicit channels:

Components describe every executable or materialized artifact.
Convention content directories hold multi-file content such as Agents, Skills, Workflows, workspace manifests, and deliverable specs.
Contribution envelopes under contributions/ or xema.contributions.inline[] carry typed single-file extension records.

Nothing is loaded merely because arbitrary code exists in the bundle.

The Agent and provisioning directories have manifest rosters that are cross-validated against files. Drift fails activation rather than silently omitting content.

A manifest can declare required and exposed capabilities plus human-readable permission hints. That declaration is not itself a grant.

At installation, the platform presents the requested capability set and permission context for review. At runtime, every capability invocation is checked again against the acting subject, resource, Space, Execution Environment, Agent arming, and current policy.

A biome therefore cannot turn a manifest declaration into authority by itself.

Distribution and supply chain

Biomes can be distributed as OCI artifacts. The distribution model supports signatures, provenance evidence, content-addressed locks, and offline verification workflows.

Published versions are immutable inputs to installation and deployment. Promotion and rollback are deliberate lifecycle operations; a mutable source directory is not a production version.

See Biome Supply Chain and Versioning.

What a new customer should build

A new installation should start with the Xema foundation and add only the domain biomes it needs. A useful first decomposition is:

one integration biome defining provider-neutral capability contracts and canonical events;
one domain biome containing the first Agents, Skills, Workflows, and experience contributions;
separate web components when a customer-specific product surface is needed.

Existing Xema application biomes are examples of what can be built, not a mandatory application portfolio.

Previous: ← Conversation channels Next: Shell →