CONCEPTS

MEX — the package format

Mixed Experience archives — the self-contained, signed, portable unit of deployment.

A MEX (Mixed Experience) file is the executable file format for Samoza OS. A .mex is a self-contained, portable archive that packages an entire Samoza application — UI surfaces, backend logic, data stores, AI agents, spatial layout — into a single deployable unit.

What’s in a MEX

my-app.mex (a ZIP archive)
├── manifest.yaml          ← top-level: name, version, signing, integrity
├── topology.yaml          ← the Space–Path Graph
├── spaces/
│   ├── dashboard/         ← UI space — HTML/CSS/JS assets
│   │   ├── index.html
│   │   └── assets/...
│   ├── store/             ← DATA space — WASM + capabilities
│   │   └── core.wasm
│   └── camera/            ← IO space — WASM + sensor declarations
│       └── core.wasm
├── world/                 ← optional spatial layout
│   └── layout.yaml
└── recognizers/           ← optional event recognizers
    └── ...

The directory structure carries semantics. A UI space directory cannot contain WASM; an IO space directory must. The compiler enforces these constraints when the archive is built.

Six properties

The MEX format has six explicit design goals:

  1. Self-contained. A single .mex file holds everything needed to deploy. No external dependencies at deploy time.
  2. Type-safe. Directory structure enforces space type constraints.
  3. Portable. Runs on any Samoza-compatible runtime — edge devices, cloud clusters, single-board computers.
  4. Verifiable. SHA-256 integrity checks plus Ed25519 signing. A tampered package is detectable before execution.
  5. Spatial. Applications can declare a physical world layout — locations, oriented faces, routes — that zdesk terminals render as position-aware viewports.
  6. Streamable. ZIP allows incremental extraction; large packages can begin deploying before full transfer completes.

The producer side

Several tools produce MEX archives:

  • The Anglish compiler (anglish.dev) — high-level declarative authoring.
  • The mex build toolchain — direct authoring against the MEX schema.
  • Third-party generators — anything that emits valid manifest.yaml + topology.yaml plus the assets.

All produce the same on-disk format and pass through the same validator before deployment.

The consumer side

┌────────────────────────────────────────────────────────────────┐
│                        MEX ecosystem                           │
│                                                                │
│  ┌────────────┐   ┌────────────┐   ┌────────────┐             │
│  │  Anglish   │   │   mex      │   │   zrms     │             │
│  │  Compiler  │──►│  Toolchain │──►│  Deployer  │             │
│  │            │   │            │   │            │             │
│  │ .ang → AIR │   │ .mex files │   │ Running    │             │
│  └────────────┘   └────────────┘   │ topology   │             │
│                                    └─────┬──────┘             │
│                                          │                     │
│                        ┌─────────┬───────┴──────┬───────┐     │
│                        ▼         ▼              ▼       ▼     │
│                     ┌──────┐ ┌──────┐      ┌───────┐ ┌─────┐ │
│                     │ zrun │ │zedge │      │zevents│ │zdesk│ │
│                     │ WASM │ │assets│      │events │ │ UI  │ │
│                     └──────┘ └──────┘      └───────┘ └─────┘ │
│                                                                │
│       Intent       Package       Orchestration     Runtime     │
└────────────────────────────────────────────────────────────────┘

zrms extracts the MEX, validates it, and hands sub-trees to the right runtime: zrun for WASM spaces, zedge for static UI assets, zevents for recognizers, zdesk for the UI surfaces.

Integrity and signing

Every MEX has a manifest.yaml with:

  • A SHA-256 hash of every file in the archive.
  • A SHA-256 hash of the manifest itself (excluding the signature field).
  • An optional Ed25519 signature over the manifest hash.
  • The publisher’s public key fingerprint.

zrms checks the integrity hashes before extracting and (optionally) verifies the signature against a configured publisher set. A tampered or unsigned archive is rejected before any code runs.

Validation levels

Validation runs at three levels, each strictly stronger than the last:

LevelCheckedWhen
StructuralDirectory shape, manifest schema, file presenceAt build, on extract
SemanticTopology references resolve, capabilities valid, types matchAt extract, before scheduling
RuntimeCapability use, declared boundaries hold, declared events emittedAt runtime, continuously

The first two are “is this a valid MEX?”. The third is “is this MEX behaving as it claimed to?”

Why a single archive

Two reasons.

Reproducibility. A .mex is a complete bill of materials. Re-running the build from the same source produces a byte-identical archive. The MEX is the source of truth, not the running cluster’s state.

Deploy and audit. A signed .mex is what you ship across an air-gap, hand to compliance, or roll back to. There’s no “what’s actually running?” question — the archive tells you, the signature proves it, and the runtime executes exactly that.

See also