Objects

Every addressable thing in Xema — an agent, a workflow, an artifact, a connector binding, a skill, an execution environment, even a capability grant — is a typed XemaObject. Objects are the universal noun of Xema: the Shell lists them, the Capability Gateway authorizes against them, and biomes compose by emitting and consuming them without needing to know about each other.

XemaObject — the typed envelope

Every object carries the same shape:

ts
1interface XemaObject<TKind extends XemaObjectKind, TPayload> {
2  readonly ref: XemaObjectRef;
3  readonly kind: TKind;
4  readonly scope: SpaceRef;            // xema://… — one address, one owner tier
5  readonly owner: SubjectRef;
6  readonly version: SemverVersion;
7  readonly lifecycle: ObjectLifecycle; // draft | published | archived
8  readonly payload: TPayload;
9}

The contract lives in @xemahq/contracts under the /object subpath — biome authors and platform services consume the same types.

Refs — the universal address

A XemaObjectRef is a typed URL into the Object Model:

text
1xema://<scope-path>/<kind>/<slug>[@<version>]
2
3Examples:
4  xema://orgs/acme/projects/main/agent/[email protected]
5  xema://system/capability/kb.page.read@1
6  xema://store/biome/[email protected]
7  xema://orgs/acme/projects/main/workflow/escalation
8  xema://orgs/acme/projects/main/artifact/spec-2026-05-001

Refs are stable, addressable, and unambiguous. They are what the Shell, the Capability Gateway, the Object Browser UI, and agents pass around when they refer to "the thing".

Object kinds

An object kind is an open, lower-case kebab-case name of at most 64 characters, contributed by the biome that owns the noun (see XemaObjectKind). The kernel's XemaObjectKind constant names the kinds that the kernel and the system biomes own. Highlights:

  • Identity and packaging: Biome, App, AppClient, AudiencePolicy, ExternalSubject, DelegatedSession.
  • Agent runtime: Agent, Skill, Tool, Model, ModelResolutionRule.
  • Workflow: Workflow, WorkflowRun, GateAction.
  • Connectivity and data: Connector, ConnectorBinding, MountSource, ArtifactType, Artifact.
  • Knowledge and documents: KnowledgeSpace, KnowledgePage, ChartRuntime, PresentationRuntime, WidgetKind. Authored Templates and DesignSystems use the generic Resource object kind with their resource kind in the address.
  • Authorization: Capability, ExecutionEnvironment, CapabilityGrant, ApprovalRule.
  • Runtime and bookkeeping: Memory, MemoryRelation, Session, EventStream, EventSubscription, ContributionEntry.

Any other biome adds its own kinds without a kernel change. The kernel validates only the shape of a kind, so a consumer never assumes it knows every kind.

The scope / lifecycle / version triad

Three orthogonal axes describe every object.

Scope — who owns it

SpaceRef is the one ownership reference, and SpaceKind its one closed vocabulary of seven tiers. A registry that owns fewer declares an admissible subset over it, never a copy of it. Skill and agent resolution use these five, ranked most-specific-first:

User > Project > Org > Biome > System

App and Session are ranked too — the rank map covers all seven kinds, with App the most specific of them all — but no registry that resolves by slug admits them as owners, so they never appear in this comparison. Their rank exists so that widening a registry's admissible subset never has to invent an order.

Precedence is "most specific wins". A user-authored agent shadows a project-authored agent of the same slug; a project-authored agent shadows the org's; the org's shadows a biome-shipped one; biome-shipped shadows kernel-shipped.

Lifecycle — readiness

ObjectLifecycle is closed: draft | published | archived. Resolution refuses to serve a non-published version — fail-fast. archived objects are kept for lineage but never resolved.

Version — immutable identity

Every object carries a semver version. Published versions are immutable; draft revisions live alongside the latest published version. Run-, session-, and app-level lockfiles pin exact versions so re-runs are reproducible — see Lockfiles.

XVFS — the virtual filesystem

Xema projects the Object Model into a path-addressable namespace called XVFS (Xema Virtual Filesystem). Nothing lives on disk — paths resolve to XemaObjectRef.

The path segment after the scope is the singular, kebab-case XemaObjectKind — agent, skill, workflow, concept, execution-environment — never a plural noun:

text
1/system/<kind>/<slug>[@<version>]
2/orgs/<org>/<kind>/<slug>[@<version>]
3/orgs/<org>/projects/<project>/<kind>/<slug>[@<version>]
4/users/<userId>/<kind>/<slug>[@<version>]
5/biomes/<biomeId>/<kind>/<slug>[@<version>]

/store/biomes/<biomeId> is recognised by the parser but not yet routable — it fails with XVFS_PATH_NOT_IMPLEMENTED.

"Everything is a file" is a discovery metaphor, not a literal claim. The Shell, the Object Browser, and agents use XVFS paths to navigate; underneath, every path resolves to a typed XemaObject.

How objects reach the registry

Objects are not stored twice. object-registry-api is a read-mostly union catalog: the source of truth stays with the owning service, and each owner projects a complete snapshot of its own slice.

Ownership is single-writer — exactly one service owns each source slice, and a projection replaces that slice atomically. Thirteen services publish today, among them biome-host-api (biomes), skill-registry-api (skills), llm-registry-api (agents and models), knowledge-base-api (spaces and pages), artifact-store-api (artifacts) and xema-shell-api (the concept pages you are reading).

There are two ingestion paths, deliberately both:

  • Push — the owner emits xema.object-registry.projection.published.v1 when its data changes.
  • Pull — the registry fans out GET /describe-objects to every owner at boot and on POST /sync. This closes the window a freshly restarted replica would otherwise sit blind in, and it is the only path for owners that wire no event transport.

A missing owner degrades freshness for its own slice alone; it never gates the registry's boot.

Reading

GET /xema-objects (filter by kind, or by scope as an XVFS scope-path prefix), GET /xema-objects/by-ref, and GET /objects/by-space (a SpaceRef and every descendant). A tenant-scoped BFF mirror of all three sits under /bff.

In practice you reach them through xema objects list and xema objects get in the CLI, ls / cat / concepts in the Shell, the Object Browser and Concepts pages in the web host, and lockfile resolution — the registry backs the agent, workflow, deliverable-spec and skill lockfile source kinds.

Writing

POST /xvfs/write upserts through the Shell and is gated on the xema:object.write@1 capability; a denial returns XVFS_WRITE_DENIED (403). Write paths must not carry an @version suffix — the registry assigns the version on upsert.

Previous: ← Overview Next: Capabilities →