REFERENCE

MEX format

Normative reference for the MEX (Mixed Experience) package format.

Version: 0.3.0 · Status: Draft · Date: 2026-04-05

A MEX file is a self-contained, portable archive that packages a Samoza application — UI surfaces, backend logic, data stores, AI agents, and spatial world layout — into a single deployable unit. This page is the normative reference. For a friendlier introduction, see the MEX concept page.

File format

A MEX is a ZIP archive with a fixed top-level layout:

my-app.mex/
├── manifest.yaml          ← required: top-level manifest
├── topology.yaml          ← required: Space–Path Graph
├── spaces/                ← required: per-space directories
│   └── <space-name>/
│       ├── space.yaml     ← required: per-space manifest
│       └── <type-specific contents>
├── world/                 ← optional: spatial world layout
│   └── layout.yaml
└── recognizers/           ← optional: event recognizers
    └── ...

The MIME type is application/vnd.samoza.mex+zip. The conventional file extension is .mex.

Manifest schema

The top-level manifest.yaml:

apiVersion: samoza/v1
kind: MEX
metadata:
  name: my-app
  version: 1.2.0
  publisher: samoza-research
  created: 2026-04-30T10:00:00Z
spec:
  topology: topology.yaml
  spaces:
    - dashboard
    - store
    - camera
integrity:
  algorithm: sha256
  files:
    - path: topology.yaml
      hash: a1b2c3...
    - path: spaces/dashboard/index.html
      hash: d4e5f6...
    # ... one entry per file in the archive
signature:                          # optional but recommended
  algorithm: ed25519
  publicKey: <base64>
  signature: <base64>               # signs the manifest excluding this field

Topology schema

topology.yaml declares the Space–Path Graph:

apiVersion: samoza/v1
kind: Topology
metadata:
  name: my-app
  owner: you@example.com
spaces:
  - name: dashboard
    type: UI
    capabilities: [sys.log]
  - name: store
    type: DATA
    capabilities: [data.read, data.write, sys.log]
    path: /data
  - name: camera
    type: IO
    capabilities: [sensors.subscribe, sys.log]
paths:
  - from: dashboard
    to: store
    name: read-store
  - from: camera
    to: store
    name: archive-frames

Space types

Type	Required directory contents	Forbidden
`UI`	`index.html`, `assets/`, optional `space.yaml`	`core.wasm`
`IO`	`core.wasm`, `space.yaml` (with sensor declarations)	`index.html`
`DATA`	`core.wasm`, `space.yaml` (with persistence config)	`index.html`
`CHAT`	`core.wasm`, `space.yaml` (with LLM config)	`index.html`
`CALL`	`core.wasm`, `space.yaml` (with service binding)	`index.html`

The validator enforces these constraints structurally before extraction completes.

Capabilities

A space declares the capabilities it will use. The full set:

sys.log
sys.sleep
sys.yield
net.emit_to
net.recv_next
data.read
data.write
data.list
data.delete
agent.invoke_df
agent.invoke_af
agent.invoke_llm
events.register_recognizer
events.subscribe
ic.lookup
ic.store
sensors.subscribe
sensors.read
actuators.lock
actuators.command
actuators.release
audio.capture
audio.playback
node.info

zrun enforces capability declarations at the ABI boundary. A guest that calls data.write without declaring it aborts with a capability violation.

Integrity and signing

Two layers, both optional but recommended:

Integrity (SHA-256). Every file in the archive has a hash entry in manifest.yaml. zrms verifies all hashes before instantiating any space. A tampered file fails the check.

Signature (Ed25519). The publisher signs the manifest hash (excluding the signature field itself). zrms verifies the signature against a configured publisher set. An unsigned MEX or one signed by an untrusted publisher is rejected — depending on cluster policy.

Validation levels

Level	Validates	When
Structural	Directory shape, manifest schema, file presence	At build, on extract
Semantic	References resolve, capabilities valid, types match	Before scheduling
Runtime	Capability use, declared events emitted	Continuously, at runtime

Each level is strictly stronger than the last. A topology that passes all three is “verified.”

Spatial world declaration

A MEX may include a world/layout.yaml that declares the physical space the application is for — locations, oriented faces, routes. zdesk terminals use this to render position-aware viewports.

apiVersion: samoza/v1
kind: World
metadata:
  name: factory-floor
locations:
  - id: assembly-line-A
    bounds: { x: [0, 10], y: [0, 30] }
    faces:
      - direction: north
        ui: dashboard
  - id: shipping-bay
    bounds: { x: [10, 20], y: [0, 15] }