Migration guides

This page collects the version-by-version migration walkthroughs for breaking changes in @open-matrix/core. The SDK is still on 0.x; the only cross-cutting migration in flight today is the realm → root rename, plus the retirement of the daemon-driven runtime path. Both are covered below.

Migration 1 — realm → root (in flight, no committed removal date)

The Matrix authority root is a DNS-style identifier (COM.NIMBLETEC.RICHARD-SANTOMAURO) carried as the root field on transports, contexts, and configuration. Earlier code used the single-word realm for the same concept. Both names work today; new code uses root.

Symbols affected

Where	Old name	New name
InMemoryTransportOptions	realm	root
INatsTransportOptions	realm	root
ICreateTransportConfig	realm	root
ICreateBrowserNatsTransportConfig	realm	root
MatrixDSLHost.realm	realm	root
MatrixActorHtmlElement.realm	realm	root
IRecordStore filter	realm	root
IRecordStore filter	baseRealm	baseRoot
IRecordStore filter	targetRealm	targetRoot
InteractionRecord	realm, baseRealm, targetRealm	root, baseRoot, targetRoot
Context type	RealmContext	RootContext
Context constructor	createRealmContext	createRootContext
Context derive	deriveRealmContext	deriveRootContext
IRrRequestOptions	realm, fallbackParentRealm	targetRoot, fallbackParentRoot
SessionInfoService field	realm	root
Public/internal getters	.realm	.root

Mechanical migration in your package

1. Search for realm in your source.

   grep -rn "realm" projects/matrix-3/packages/<your-package>/src --include="*.ts"

2. Decide for each match whether it's the deprecated identity field or something domain-specific.
   • Field on a Matrix transport/context/options object → migrate.
   • Domain term in your package (e.g., a "game realm") → leave alone.
3. Migrate one file at a time. Replace realm with root in JSDoc, in field accesses, in option names. Both spellings work, so you can do this gradually without breaking anything.
4. Run your package tests between batches. pnpm --filter <name> test.
5. Search for type aliases like RealmContext and rename to RootContext.

Edge cases

• realm as part of a URL or NATS subject literal. Don't migrate. The wire format keeps backward-compatible aliases.
• realm appearing in deprecated JSDoc strings. When you see @deprecated Use root., that's the SDK's notice; your package shouldn't need to keep both spellings — pick the new one.
• Cross-package imports of context types. RealmContext is still exported as an alias of RootContext in some files. Imports of either work.

When the aliases go away

Status: target state, not yet implemented. A specific minor for removal is not committed. The pattern documented in Stability levels suggests the alias survives at least one minor after the rename was introduced, possibly longer because the cascade is broad. Track removal in WORKSTREAMS/core-and-packaging/.

Migration 2 — matrixd daemon → Host Service

Conceptually a deployment migration, but it has SDK consequences. The retired matrixd daemon path is intentionally disabled for product work. Packages and tests that bring up a Host should use Host Service:

Old	New
matrixd init && matrixd start	hivecast install && hivecast start
matrixd up <package>	matrix run <package> (delegates to Host Service)
matrixd join <cloud>	hivecast login --device --cloud <cloud>
Daemon dist/matrixd.js as the entrypoint	host-service package + mx-cli

The daemon entrypoint still exists as a compatibility wrapper that exits with a guidance message. Tests that built on createDaemonHarness continue to work — the harness now drives Host Service via the same install/start scripts.

What this means for your package

• Don't add new product behaviour to packages/daemon. No actors, HTTP, OAuth, sessions, UI, inference, billing, identity, provisioning, package execution. See root CLAUDE.md § "THE RULES" #1.
• Use matrix run <package> to launch a runtime in dev. Not matrixd up.
• For installer flows, use hivecast install / hivecast start. Not matrixd init.

Tests

createDaemonHarness is deliberately named after the legacy entry; it works against Host Service today. Existing tests need no changes. New tests should still call createDaemonHarness — the API is stable. The internal name will change with a future deprecation cycle.

Migration 3 — 0.0.x → 0.1.x (historical)

The SDK shipped 0.1.0 as the post-rebuild baseline. Pre-0.1 code does not exist as a deployed artifact in this repo; there is no canonical migration path because the rebuild was a clean cut. If you have inherited code from the pre-0.1 MatrixComponent / MatrixComposite lineage:

• The two are unified into MatrixActor. Replace extends MatrixComponent and extends MatrixComposite with extends MatrixActor. Children are lazy — zero overhead unless you add some.
• The browser shell base became MatrixActorHtmlElement. Replace extends FabricElement (or whatever the legacy class was called).
• The runtime is unified: MatrixRuntime. No more BrowserRuntime/HeadlessRuntime split — pass domStrategy: new BrowserDomStrategy() for browser, omit for headless.

How a future migration guide should look

When the next minor lands with breaking changes, add a section here following this template:

## Migration N — <change>

### What changed
- (one-line summary)

### Symbols affected
| Where | Old | New |
|---|---|---|

### Mechanical migration steps
1. ...
2. ...

### Edge cases
- ...

### Codemod (if available)
```bash
npx @open-matrix/codemod <change-name> projects/matrix-3/packages/<your-package>/src

The codemod path doesn't exist today. Adding one is target state.

## See also

- [Deprecated APIs](./deprecated-apis.md) — the full deprecation list.
- [Stability levels](../overview/stability-levels.md) — the deprecation policy.

> **Source:** `@deprecated` JSDoc tags through `projects/matrix-3/packages/core/src/`, root `CLAUDE.md` § "THE RULES" #1 (retired-daemon rule).