@open-matrix/package-runtime (1.1.32)
Installation
@open-matrix:registry=npm install @open-matrix/package-runtime@1.1.32"@open-matrix/package-runtime": "1.1.32"About this package
Package runtime
Shared package resolution, configuration, execution, and runtime transport ownership.
Browser views through the hosted provider
Declare a view's entry in browser.views[].module, relative to its package.
The same normalized package declaration feeds Directory projection and
MatrixHttpAssetEndpointActor: the published view ID and digest identify the
bytes served by component.module.get. A hosted package serves its declared
entries and their reachable digest-named chunks, using Core's loader grammar;
it does not expose arbitrary package files as modules. Cached page entries can
request a chunk first after the provider restarts. Source rebuilds discard old
graph bytes, and release replacement clears the provider cache.
tests/package-web-module.spec.ts covers the hosted graph, chunk-first loading,
refusals and replacement; tests/application-directory-projection.spec.ts
compares the actual projection with the same byte provider. Installed Settings
and Fleet views use this path. Demos H7 (home-profile.ts) follows the private
Profile owner, while S30 (fleet-workflow.ts) exercises the Fleet route; their
installed browser walks remain required separately from these module tests.
Runtime and transport
host/toolchain-environment.js supplies the explicit child-tool environment for
native coding, workspace and integration owners. It preserves configured tool
directories, adds the selected Node and platform system directories, and never
changes the parent runtime environment or imports a host's credentials.
connectMatrixRuntimeTransport creates the host-owned NATS connection and transport;
connectMatrixRuntime also creates its actor runtime.
Both native NATS and WebSocket connections apply
MATRIX_RUNTIME_NATS_CONNECTION_POLICY from the first dial: transient failures retry
indefinitely, with a 5,000 ms timeout per dial. waitOnFirstConnect keeps a slow broker
handshake from becoming a fatal startup error. Terminal connection closure remains
visible through connection.closed() to the foreground lifecycle owner.
The Node WebSocket adapter supplies the close notification missing when an upgrade
is aborted, so the same dial budget also covers a proxy that stalls the upgrade.
HTTP 502/503 and reset responses continue through the existing retry policy.
Foreground shutdown runs the package shutdown hook for both process signals and terminal
connection closes. Cleanup is bounded by the host supervisor's measured 5,000 ms
SIGTERM-to-SIGKILL grace. A terminal close sets exit code 1 before cleanup starts, and shutdown
removes both signal listeners immediately so a subsequent SIGINT or SIGTERM retains Node's default
forced-termination behavior if cleanup hangs.
When a host supplies credentialProvider, the transport starts the core
NatsCredentialRefresh before dialing. It renews at four fifths of an issuer-reported
lifetime (exp - iat, or the browser-compatible four-minute fallback), refreshes immediately
on a disconnect, and lets both native and WebSocket reconnect authenticators read the latest
JWT and seed. Explicit transport shutdown stops the renewal timer.
The current runtime JWT remains in transport-private state. Callers request proof through core's opaque request marker; request serialization injects the current JWT for that one wire operation, so actors cannot discover or cache a shared bearer service. Each runtime installs only the verifier used to admit signed peer credentials. Credentials issued before runtime tags remain valid through their signed Matrix runtime id, authority and subtree metadata until expiry.
Machine-backed foreground runs reserve a persisted, monotonically increasing activation
generation beside the private machine.json. Registry claim, renewal, and release all carry
that generation, so a successor fences a live predecessor and the predecessor cannot release
the successor's claim while shutting down. Existing machine identity files are statted before
hardening: files already restricted to 0600 are left alone, while an EPERM or EACCES from
a provisioning-owner mismatch emits one warning naming the path without blocking startup.
The launcher and direct foreground runner share the replacement-event filter; an event only
prompts an activation-qualified Registry renewal, whose generation comparison decides whether
the process exits. If a multi-entry reclaim is refused, any stale-generation or replaced refusal
takes precedence over non-terminal refusal codes so the losing process is fenced.
Run pnpm test, pnpm type-check, and pnpm build from this package. The first-dial
regression uses a disposable local nats-server, resolved by the shared test utilities
(NATS_SERVER_BINARY can select an installed binary). It covers delayed broker startup
and eight simultaneous provider connections whose first handshakes time out. An
old-policy negative control requires the same ProtocolHandler.dial timeout seen in
mass starts. No Docker or live estate is used. Existing WebSocket shutdown and recovery
coverage remains in sdk/command-line/tests/unit/websocket-peer-lifecycle.spec.ts.
websocket-handshake-lifecycle.spec.ts in the same directory exercises HTTP errors,
resets, stalled upgrades, recovery, and SIGTERM against a local HTTP proxy and broker.
See the runtime contract for boot and shutdown ownership.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @nats-io/nats-core | ^3.3.1 |
| @nats-io/services | ^3.4.0 |
| @open-matrix/contracts | 1.1.32 |
| @open-matrix/core | 1.1.32 |
| @open-matrix/credential-plane | 1.1.32 |
| @open-matrix/identity-client | 1.1.32 |
| @open-matrix/interface-renderer | 1.1.32 |
| @open-matrix/nats-auth | 1.1.32 |
| nats | ^2.29.3 |
| ws | ^8.21.0 |
Development Dependencies
| ID | Version |
|---|---|
| @matrix/test-utils | 1.1.32 |
| @types/node | ^20.0.0 |
| @types/ws | ^8.18.2 |
| tsx | ^4.15.6 |
| typescript | ^5.7.0 |