Compatibility

Compatibility in Matrix has two axes that often get conflated:

1. Package version compatibility — does @open-matrix/chat@0.2.3 work with @open-matrix/director@0.5.1?
2. Runtime/host compatibility — does this package run on this Host release / Node.js version / browser version?

This page documents what the catalog currently surfaces about each. The short answer: very little is enforced; most compatibility is conventional.

Package version compatibility

Today

Standard npm dependency declarations live in package.json:

{
  "dependencies": {
    "@open-matrix/core": "^1.0.2"
  }
}

The artifact registry and the package catalog do not independently track compatibility. The npm install resolver handles dependency-graph satisfaction at install time using the same semver rules npm has always used.

The catalog stores the version per package but does not store dependency ranges or peer requirements. You cannot ask "what packages are compatible with @open-matrix/core@1.0.2" through registry.search.

Target state

The discovery-metadata spec (WORKSTREAMS/core-and-packaging/MATRIX-DISCOVERY-METADATA-SPEC.md) introduces CapabilityDeclaration.requires / provides:

// Future manifest shape
capabilities: {
  requires: [
    { capability: "inference", versionRange: "^1" }
  ],
  provides: [
    { capability: "chat", version: "0.2" }
  ]
}

When this lands, the catalog will be able to answer "what providers satisfy { capability: "inference", versionRange: "^1" }?" That is a real compatibility query distinct from npm's package-version resolution.

This is target state. Today the field is a flat capabilities: string[] on both ends.

Runtime / Host compatibility

Today

There is no first-class runtime-compatibility field. A package may informally encode requirements via:

• package.json.engines.node — npm's standard Node-version range. Enforced by npm install if the consumer has engine-strict=true. No Matrix-side enforcement.
• package.json.engines["@open-matrix/core"] — convention but not standardized.
• A capability string like "matrix-host:1.x" — purely declarative.

The Host loader (ServiceRegistryActor, host-service, etc.) does not check any of these before mounting.

Target state

The runtime-environment workstream (WORKSTREAMS/runtime-environment-multi-instance/) specifies a RuntimeConfig that includes Host/runtime version constraints. When that schema is enforced, the catalog can surface "this package requires matrix-host >= 1.5" and the Host can refuse to start an incompatible runtime.

Cross-package version pinning today

The current pre-launch practice is lockstep release. Most @open-matrix/* packages share major versions and are released together. Mixing versions is supported by npm semver, but not common in practice.

The bundled-package store (<host-home>/packages/system/, <host-home>/packages/global/) is populated by seedBundledHostPackages from a single hivecast wrapper bundle, so all default packages on a fresh install share the same hivecast release line. This sidesteps fine-grained compatibility checking — the question becomes "are you on a recent hivecast release?" rather than "are these specific versions compatible?"

What the catalog DOES surface

Field	What it tells you
version	Latest known version of the package. Not a constraint.
inferredKind, declaredKind	What category the package is. Compatible categories are conventional, not enforced.
capabilities[]	Free-form claims. Currently the only proxy for "this provides X."
webapp.shells[]	Which shells this app surface is intended for.

What it does NOT surface

• Dependency ranges between Matrix packages.
• Required Host version.
• Required Node.js version (npm carries this; the catalog doesn't duplicate).
• Required browser features.
• Required NATS protocol version.

See also

• Version ranges
• Capabilities
• Discovery metadata spec
• WORKSTREAMS/runtime-environment-multi-instance/

Source: Today's catalog has no compatibility-typed fields. Target state is in the discovery-metadata spec and runtime-environment workstream.