@open-matrix/core (1.1.33)
Installation
@open-matrix:registry=npm install @open-matrix/core@1.1.33"@open-matrix/core": "1.1.33"About this package
@open-matrix/core
Matrix runtime SDK — actors, Web Components, transports, serialization, and LISP-on-Protocol.
NatsTransport.disconnect() drains an active broker connection before closing it.
If the connection is already disconnected, it closes directly: draining requires
a broker response and would otherwise prevent shutdown throughout an outage.
NatsCredentialRefresh preserves the four-minute cadence for providers without
lifetime metadata and renews at four fifths of an explicitly supplied JWT lifetime.
Renewal delays are capped at the signed 32-bit setTimeout ceiling.
Install
npm install @open-matrix/core
Usage
Headless Actor (daemon-side)
import { MatrixActor } from '@open-matrix/core';
class PingActor extends MatrixActor {
static accepts = {
ping: { message: 'string' },
};
static emits = {
pong: { echo: 'string', ts: 'number' },
};
onPing(payload: { message: string }) {
this.emit('pong', { echo: payload.message, ts: Date.now() });
}
}
Browser Web Component
import { MatrixActorHtmlElement } from '@open-matrix/core/framework/MatrixActorHtmlElement';
class StatusPanel extends MatrixActorHtmlElement {
static accepts = { showStatus: { text: 'string' } };
static template = `<div id="status"></div>`;
static styles = `#status { font-family: monospace; padding: 8px; }`;
onShowStatus(payload: { text: string }) {
this.shadowRoot!.querySelector('#status')!.textContent = payload.text;
}
}
customElements.define('status-panel', StatusPanel);
Programmatic Runtime
import { InMemoryBroker, InMemoryTransport, MatrixRuntime } from '@open-matrix/core';
const broker = new InMemoryBroker();
const transport = new InMemoryTransport(broker, { name: 'demo' });
const runtime = new MatrixRuntime({ transport });
What's Included
| Category | Key Exports |
|---|---|
| Core | MatrixActor, Supervisor, HeadlessComponentRegistry |
| Framework | MatrixActorHtmlElement, MxContract, MxInterface, MxProxy |
| Runtime | MatrixRuntime, HeadlessHost, ConsoleLogger |
| Transports | InMemoryBroker, NatsTransport, FederationTransportAdapter |
| Messaging | TopicRouter, SubscriptionBag, RequestReply |
| Components | ComponentLoader, per-occurrence mount disposal, verified byte sources |
| LISP | Interpreter, EvalContext, parseSExpr |
| Serialization | serialize, parse, 5-format parity |
| Flow | @open-matrix/core/flow/form: graph, toSource, fromSource, printFluent |
135 named exports total. Full type declarations included.
Component definitions round-trip their registered componentType, stable id, and initial state
through JSON, fluent, S-expression, HTML, and topics forms. HTML definitions use the same structural
parser in browsers and Node, so nested components retain their own operations on every host. Topics
include an @matrix-schema data declaration even when optional human-readable comments are disabled.
Requirements
- Node.js >= 20
- TypeScript >= 5.0 (for type checking)
License
MIT
Session credential redaction
redactSessionContent replaces recognized credential spans in message text and titles.
redactSessionState applies that rule to decoded JSON string values while retaining untouched
serialized bytes, deep structure and JSON keys; non-JSON state uses the content rule.
Keys are identifiers and are not renamed or scanned. Unlike telemetry’s redactCredentialsDeep,
session persistence does not infer credentials from field names or truncate deep documents.
Temporary definition interests
Keepers using ContainerBehaviour expose retention.inspect, retention.retain and
retention.release through KEEPER_ACCEPTS. The existing admitted caller context supplies
the holder's home, principal and optional delegate. Caller-supplied holder fields confer no
authority. An interest protects a saved definition owned by this keeper; it neither grants
access to its borrowed rows nor retains their activations. Qualifiers and other homes are
refused unless the actual owner supports that resource; this first slice supports saved forms.
Inspect first for this owner's incarnation. Retain with the collection row's exact target
reference, a caller-scoped id, an ISO issuedAt and lifetimeMilliseconds. The deadline is
fixed by those inputs, so a retry does not renew it. Release with the returned id,
incarnation and the retained revision (expectedRevision). A repeated release returns
the same acknowledgement. A stale owner, expired interest, different command content or
unowned target produces a typed refusal. A new owner incarnation retains no old interests.
saved-form.remove and the saved collection's remove action both refuse with
SAVED_FORM_RETAINED while any temporary interest remains. After release or expiry,
forgetting still requires the form's current revision and its owner's ordinary authority.
Release itself never deletes a definition or source. Inspection covers only this owner and
caller, never global absence. There is no lease timer or background scan: owner operations
prune expired bookkeeping, and the delete decision reads expiry itself. Bookkeeping,
including released acknowledgements, is capped at 1,000 per owner and ends at the original
deadline or owner replacement. A durable saved form remains in its existing store after
an owner restart; the temporary interests are not durable pins.
Run (demo "S90") in the Shell for the executable manual and real two-scope cleanup.
Focused owner tests: TSX_TSCONFIG_PATH=tsconfig.build.json node --import tsx --test src/runtime/__tests__/container-retention.spec.ts from this package. The identical Omega
program is tested by node --import tsx --test tests/retention.spec.ts from
applications/demos; its browser journey uses the actual Shell keeper. That test prints
owner-call count, CPU, elapsed time and created/released/reclaimed counts; S90 also reads
the owner's existing $counters. These are local operation costs, not an estate memory saving.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @nats-io/nats-core | ^3.3.1 |
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/federation | 1.1.33 |
| @open-matrix/omega-core | 1.1.33 |
| @open-matrix/subjects | 1.1.33 |
| @opentelemetry/api | ^1.9.1 |
| morphdom | ^2.7.8 |
| nats.ws | ^1.30.3 |
| tweetnacl | ^1.0.3 |
Development Dependencies
| ID | Version |
|---|---|
| @matrix/test-utils | 1.1.33 |
| @types/node | ^20.0.0 |
| esbuild | ^0.27.7 |
| nats | ^2.29.3 |
| tsx | ^4.15.6 |
| typescript | ^5.7.0 |