Package lifecycle

A Matrix package passes through seven stages between the day a package author runs mx init and the day a runtime backed by that package is shut down. Each stage corresponds to a specific CLI command and a specific section of this site.

The seven stages

#	Stage	Command(s)	What happens
1	Author	mx init, mx actor, mx element, mx webapp, mx cqrs, mx actor-element	Scaffold a package on disk; create matrix.json, src/, tests/.
2	Build	pnpm build (per package) or node build.mjs	Compile TypeScript and bundle browser assets into dist/.
3	Test	pnpm test (per package)	Run package-local tests against built artifacts.
4	Publish	mx pack, mx publish	Pack the package into a tarball; push it to a registry.
5	Install	mx install <pkg>, hivecast install	Copy the published artifact (or local source) into a Host's package store.
6	Run	mx run, mx up, hivecast up, matrix up	Start a runtime that loads the package and mounts its actors.
7	Operate	hivecast status, hivecast runtimes, mx info, mx outdated, mx update-fork, hivecast down, mx uninstall	Inspect, update, supervise, and remove.

Each stage has its own section in this site:

Stage	Section
1 Author	Authoring
2-3 Build & Test	Local Development
4 Publish	Publishing
5 Install	Installing
6 Run	Running
7 Operate	Running (logs, health, update, rollback)

Stage diagram

flowchart LR
    A[mx init] --> B[pnpm build]
    B --> C[pnpm test]
    C --> D[mx pack]
    D --> E[mx publish]
    E --> F[mx install / hivecast install]
    F --> G[hivecast up / matrix up]
    G --> H[Operate: status, logs, update]
    H -->|new version| C
    H -->|stop| I[hivecast down]
    I -->|remove| J[mx uninstall]

Stage gating

The lifecycle is not strictly serial. Some stages can be skipped for specific shapes:

• A library package has no Run stage on its own — its install and build are real, but it executes only when imported by another package's runtime.
• A web app package without a service factory still has a Build and Run stage; mx run . --env <name> --serve mounts the asset endpoint without starting a service factory.
• Local development can skip Publish entirely: see Deployless lifecycle.

What enforces correctness at each gate

Gate	Enforced by
Author	mx init writes a manifest that validateManifestForMxCli accepts
Build	The package's own pnpm build script
Test	The package's own pnpm test script (CLAUDE.md Rule 10)
Publish	mx publish runs ensurePublishPreflight (packages/mx-cli/src/commands/publish.ts:49-86) which re-validates the manifest, checks the runtime entry exists, and confirms the package declares at least one of: root actor, component, webapp, or matrix.service.json factory
Install	mx install runs the install lifecycle hooks (validate, migrate, seed, verify) declared in matrix.json:install
Run	Host Service supervises the runtime; the runtime's matrix.service.json factory must exist, export the named function, and survive its --check invocation

See also

• Deployless lifecycle
• Authoring → Scaffold a package
• Local Development → Build
• Publishing
• Installing
• Running

Source: Each stage's commands are in projects/matrix-3/packages/mx-cli/src/commands/ and projects/matrix-3/packages/host-service/src/cli.ts.