Deprecated APIs

This page tracks every @deprecated JSDoc tag on a public-facing symbol in @open-matrix/core. Symbols listed here still work today, but they will be removed in a future minor. The replacement is named in each row; migrate ahead of time.

The deprecation policy is in Stability levels. The full list below is harvested from @deprecated JSDoc tags in projects/matrix-3/packages/core/src/.

Note: Some @deprecated tags appear on internal types not directly exported. They are not listed here. This page only covers symbols a package author can actually import or call. Internal renames are out of scope; the source is authoritative.

The big rename: realm → root

The largest in-flight migration is the rename of realm to root everywhere — it cascades through transports, contexts, options types, JSDoc fields, and configuration. The new name reflects the DNS-style authority root we settled on (COM.NIMBLETEC.RICHARD-SANTOMAURO) rather than the older "single-token realm" idea.

Both spellings work today. The deprecated alias is kept until consumers migrate.

Where	Old	New
InMemoryTransportOptions	realm?: string	root?: string
INatsTransportOptions	realm?: string	root?: string
ICreateTransportConfig	realm?: string	root?: string
ICreateBrowserNatsTransportConfig	realm?: string	root?: string
MatrixActorHtmlElement.realm (getter)	realm	root
MatrixDSLHost.realm	realm	root
IRecordStore filter realm field	realm	root
InteractionRecord.realm	realm	root
RealmContext (type)	RealmContext	RootContext
createRealmContext / deriveRealmContext	functions	createRootContext / deriveRootContext

These all have @deprecated Use root. (or similar) inline. Mechanical migration is safe — a global search-replace from realm to root works for most cases.

Status: target state, not yet implemented. The realm aliases are kept until a future minor (likely 0.2.0 or 0.3.0). No removal date is committed; track the workstream WORKSTREAMS/core-and-packaging/ for the cut.

Runtime config

Symbol	Replacement	Notes
IRuntimeConfig.host	IRuntimeConfig.domStrategy	host was the legacy DOM host; domStrategy is the strategy injection point.
MatrixRuntime.getComponent(id)	Transport-based communication	Use runtime.subscribe(...) / RequestReply to talk to actors instead of grabbing the instance.

The host field is still wired up but routes to the same registry the new strategy uses (runtime/MatrixRuntime.ts:98-99).

Mock runtime

Symbol	Replacement	Notes
MockRuntime getInstance cheat (per JSDoc, MockRuntime.ts:156)	Transport-based comms	Reaching into a MockRuntime for a live actor instance bypasses the bus. Use it only as a last resort and never in production code.

Security defaults

Symbol	Replacement	Notes
LEGACY_PERMISSIVE_POLICY (or similar legacy default in core/security/defaults.ts)	DEFAULT_SECURITY_POLICY	Defaults are now secure-by-default; the legacy permissive policy is preserved for compatibility tests.

Federation request-reply

Symbol	Replacement	Notes
IRrRequestOptions.realm (deprecated alias)	IRrRequestOptions.targetRoot	Same rename theme; cross-root request-reply uses targetRoot.
IRrRequestOptions.fallbackParentRealm	IRrRequestOptions.fallbackParentRoot	Same.

TransportRegistry — global singleton

Symbol	Replacement	Notes
Global singleton accessor on TransportRegistry	new TransportRegistry() per runtime	The class still has static helpers tagged @deprecated; the recommended path is per-runtime instances injected via runtime.transportRegistry.

Composite / dynamic component definitions

Symbol	Replacement	Notes
IDynamicComponentDefinition.shellTag	IDynamicComponentDefinition.tag	Same field, renamed. The old name is kept as an alias.

Browser-side legacy fields

Symbol	Replacement	Notes
MatrixDSLHost.realm	MatrixDSLHost.root	The bootstrap host's root identifier.
MatrixDSLHost.legacyHostElement (or similar)	MatrixDSLHost.localRoot	Same realm → root theme.

Internal types — flagged here for context only

The core/actor/ directory carries a stack of @deprecated tags pointing each old type at its current name (e.g., IMessageMeta, IDispatchPriorities, IBecomePayload). These are internal types not part of the public surface; the deprecations exist because the file structure was reorganized. Application code should never have imported them directly.

How to find the deprecation in source

Every entry above corresponds to a @deprecated JSDoc tag in projects/matrix-3/packages/core/src/. Run:

grep -rn "@deprecated" projects/matrix-3/packages/core/src --include="*.ts" | grep -v "\.d\.ts"

That command produces the live list; this page summarizes it. When in doubt, the source is authoritative.

Removal targets

Status: target state, not yet implemented. Removal targets are not committed to specific minor versions. The pattern is: deprecate in N, give one minor of grace, remove in N+1 minimum. For symbols deprecated around 0.1.x, removal is candidate for 0.3.x at the earliest. Track per-symbol removal in PR descriptions and changelogs as they happen.

Migration

For each deprecation, the JSDoc names the replacement. The mechanical pattern:

1. Read the JSDoc — it tells you what to use instead.
2. Find your usages: grep -rn '<deprecated symbol>' projects/matrix-3/packages/<your-package>/src.
3. Mechanically replace.
4. Run your tests.

For larger renames (e.g., realm → root cascade), see Migration guides.

See also

• Stability levels — the deprecation policy.
• Public API ledger — the live exports list.
• Migration guides — version-by-version walkthroughs.

Source: @deprecated JSDoc tags throughout projects/matrix-3/packages/core/src/. Highlighted files: runtime/IRuntimeConfig.ts:17, runtime/MatrixRuntime.ts:98,754, transport/InMemoryTransport.ts:12,45, transport/NatsTransport.ts:43, transport/createTransport.ts:7, transport/createBrowserNatsTransport.ts:6, framework/MatrixActorHtmlElement.ts:485, core/MockRuntime.ts:156, core/security/defaults.ts:11,134.