Stability levels

@open-matrix/core is on 0.1.0. The surface is intentionally fluid while the protocol settles. This page documents how stability is communicated today and what consumers can rely on.

Present-state markers in source

The codebase carries five stability signals, all readable from source. None of them are enforced by tooling; they are conventions code review and CHANGELOG entries respect.

Marker	Where it appears	What it means
Exported from src/index.ts	The root barrel	Public surface. Breaking changes get an entry in the deprecations page and a migration note.
Exported in package.json exports (deep subpath)	package.json:23-324	Public surface. Same guarantees as the root barrel.
@deprecated JSDoc tag	Inline	Will be removed in a future minor. Replacement is named in the JSDoc.
@experimental JSDoc tag	Inline	Surface may change without a deprecation cycle. Used sparingly.
Not exported from any .ts barrel	Internal modules	Implementation detail. May be moved/renamed any commit. Do not import.

There is no published @stable tag — the absence of @deprecated and @experimental on a publicly exported symbol implies stability within the current minor. This is by convention, not enforcement.

Examples from current source

Stable, used everywhere. MatrixActor, MatrixRuntime, MatrixActorHtmlElement, InMemoryTransport, NatsTransport, IMatrixContext, MxEnvelope, ActivityFrame, resolveConfiguredPackageConfig. None of these carry @deprecated. They are exported from both the root barrel and a deep subpath.

Deprecated. Examples readable in source:

• IRuntimeConfig.host: @deprecated Use domStrategy instead. Legacy host for backwards compat during migration. (runtime/IRuntimeConfig.ts:17)
• MatrixRuntime.getComponent(): @deprecated Use transport-based communication instead. (runtime/MatrixRuntime.ts:754)
• InMemoryTransportOptions.realm: @deprecated Use root. (transport/InMemoryTransport.ts:13)
• INatsTransportOptions.realm: @deprecated Use root instead. Kept as alias for backward compatibility. (transport/NatsTransport.ts:43)
• MatrixActorHtmlElement.realm: @deprecated Use root instead. (framework/MatrixActorHtmlElement.ts, getter on the element class)

The realm → root migration is the largest of the in-flight renamings; both spellings work today and the deprecated alias is kept until consumers migrate. See Deprecated APIs.

What we promise consumers within 0.x

• Public symbols (src/index.ts exports + package.json exports) get a deprecation cycle of at least one minor before removal. The @deprecated JSDoc is the source of truth.
• We do not promise type-level non-breaking changes within 0.x. Adding optional fields, narrowing return types, and tightening generics are normal.
• The wire protocol (MxEnvelope, system ops, six declarations, root prefixing) is treated more strictly than the SDK surface. Wire-breaking changes go through WORKSTREAMS/core-and-packaging/ review, not via the SDK changelog.

Note: Once @open-matrix/core reaches 1.0, the deprecation policy will become semver-formal: any breaking change to a publicly exported symbol requires a major bump. We are not there yet.

Tracking removal targets

When something is marked @deprecated, we record the removal target on Deprecated APIs. Removal targets are minor versions, not absolute dates. The page is the single source for "is this still safe to use?".

Status of UI primitives

Browser-side primitives (MxSplit, MxTheme, MxTopicTag, primitive-elements) are exported from src/framework/components/ and considered stable for shell composition. UI primitives intentionally trail the headless surface — if the actor protocol changes, components follow. There is no separate semver track for UI components yet.

Status of LISP / membrane / topology

src/lisp/, src/core/membrane/, and src/topology/ are publicly exported but are treated as experimental in practice. They are not yet considered part of the standard package-author surface. If you build on them, expect movement. The exports are kept stable as they evolve.

What this page is NOT

Status: target state, not yet implemented. A formal CI gate that fails when an @deprecated symbol is removed without an entry in the deprecations page is on the backlog (see WORKSTREAMS/package-structure/CI-BACKLOG.md). Today the gate is code review.

See also

• Public API ledger — the canonical export list.
• Deprecated APIs — what's on the way out.
• Migration guides — per-version walkthroughs.

Source: projects/matrix-3/packages/core/package.json:23-324 (exports), projects/matrix-3/packages/core/src/index.ts (root barrel), @deprecated JSDoc tags throughout src/.