Matrix Package Lifecycle

Appearance

Deployment profile schema ​

A Host's deployment profile is the union of three shapes. They live in three locations and serve three roles. There is no single deployment-profile.json today — that's target state.

Layout summary ​

<host-home>/
├── host.json                                 ← IMatrixHostConfig
├── credentials/
├── runtimes/
│   ├── RUNTIME-HOST-SYSTEM.json              ← IHostRuntimeRecord
│   ├── RUNTIME-HOST-CHAT.json
│   └── ...
├── runtime-env/
│   ├── RUNTIME-HOST-SYSTEM.json              ← IMatrixPackageEnvironment
│   ├── RUNTIME-HOST-CHAT.json
│   └── ...
├── logs/
├── packages/
└── ...

IMatrixHostConfig — host.json ​

projects/matrix-3/packages/host-service/src/types.ts:50-60:

ts
interface IMatrixHostConfig {
  readonly kind: "MatrixHostConfig";
  readonly version: 1;
  readonly home: string;
  readonly externalUrl?: string;
  readonly http: IHostHttpConfig;
  readonly transport: IHostTransportConfig;
  readonly auth: IHostAuthConfig;
  readonly runtimeStorage: IHostRuntimeStorageConfig;
  readonly packageStorage: IHostPackageStorageConfig;
}

Sub-shapes:

ts
interface IHostHttpConfig {
  readonly host: string;
  readonly port: number | null;
}

interface IHostTransportConfig {
  readonly authorityRoot?: string;
  readonly addressRoot?: string;
  readonly spaceId?: string;
  readonly routeKey?: string;
  readonly publicNamespace?: string;
  readonly root: string;             // @deprecated; use authorityRoot
  readonly nats: IHostNatsTransportConfig;
}

interface IHostNatsTransportConfig {
  readonly mode: "embedded" | "external";
  readonly url?: string;
  readonly wsUrl?: string;
  readonly credentialsRef?: string;
  readonly port?: number;
  readonly wsPort?: number;
  readonly dataDir?: string;
  readonly pidFile?: string;
  readonly binaryPath?: string;
}

interface IHostAuthConfig {
  readonly mode: "local-client" | "public-session";
  readonly sessionSecret?: string;
  readonly actorTimeoutMs?: number;
  readonly providers?: { readonly google?: { ... }; };
}

interface IHostRuntimeStorageConfig {
  readonly recordsDir: string;        // typically "runtimes"
  readonly logsDir: string;           // typically "logs/runtimes"
}

interface IHostPackageStorageConfig {
  readonly globalDir: string;         // typically "packages/global"
  readonly systemDir: string;         // typically "packages/system"
}

IHostRuntimeRecord — <host-home>/runtimes/<id>.json ​

projects/matrix-3/packages/host-service/src/types.ts:81-97:

ts
interface IHostRuntimeRecord {
  readonly runtimeId: string;
  readonly packageRef?: string;
  readonly packageDir?: string;
  readonly environment?: string;
  readonly pid?: number;
  readonly status: "starting" | "running" | "stopping" | "stopped" | "failed";
  readonly startup?: "manual" | "auto";
  readonly restart?: "never" | "always" | "on-failure";
  readonly startedAt?: string;
  readonly stoppedAt?: string;
  readonly updatedAt: string;
  readonly runtimeMount?: string;
  readonly controlMount?: string;
  readonly runtimeWireRoot?: string;
  readonly localMounts: readonly string[];
  readonly metadata: Record<string, unknown>;
}

metadata typically contains source, target, envFile, transport, controlReadyTimeoutMs, autoStartPriority, serve boolean, webapp route info, etc.

IMatrixPackageEnvironment — <host-home>/runtime-env/<id>.json ​

Same shape as .matrix/<env>.environment.json (see Config contract schema). Written by writeHostRuntimeEnvironment at up time.

How they connect ​

host.json
   │
   │ transport.root
   ▼
runtime-env/<id>.json
   │
   │ runtime.root, runtime.runtimeMount, http.port
   ▼
runtime process
   │
   │ packageDir, command, args, env
   ▲
runtimes/<id>.json

The runtime record points at both the package directory (so the runner imports the right runtime.entry) and the env file (so the runner reads transport / http / mount info). Together they reproduce the runtime's startup conditions.

Hivecast install defaults ​

hivecast install writes a default profile that brings up the ten runtime records listed in packages/hivecast/bin/hivecast.mjs:28-39. Override or extend with explicit hivecast up calls afterward.

Target state — unified schema ​

A single deployment-profile.json would replace host.json + runtimes/*.json + runtime-env/*.json with one document. The reconciler would diff that profile against live state and apply the delta. Filed in WORKSTREAMS/runtime-environment-multi-instance/. Today the three-shape layout is the live reality.

See also ​

Source: projects/matrix-3/packages/host-service/src/types.ts defines IMatrixHostConfig, IHostRuntimeRecord, and friends; packages/mx-cli/src/utils/package-environment.ts defines IMatrixPackageEnvironment.