@open-matrix/runtime-launcher3 (0.1.15)
Installation
@open-matrix:registry=npm install @open-matrix/runtime-launcher3@0.1.15"@open-matrix/runtime-launcher3": "0.1.15"About this package
@open-matrix/runtime-launcher3
@open-matrix/runtime-launcher3 is the Node executable-edge composition package for Matrix package launch. It currently exposes two deliberately distinct paths:
- the historical launcher, retained as an explicitly named legacy Anti-Corruption Layer; and
- the staged native Generic Host composition root created by
CreateNativeHostedPackageLauncher.
Legacy aggregate ownership contract
CreateHostedPackageLauncher wraps the historical aggregate launchPackage() operation in one LegacyPackageLaunchHostedService. The operation adapter performs only the pre-launch cancellation check and must return any constructed RunningPackage unchanged. The hosted service owns the post-return cancellation check, startup compensation, ordinary stop, and disposal transaction.
The aggregate remains owned until RunningPackage.stop() succeeds. A transient stop or startup-compensation failure therefore:
- remains observable to the caller;
- leaves the host in a non-terminal lifecycle state;
- retains the exact
RunningPackageinstance; - discards only the failed in-flight attempt;
- permits a later
Host.StopAsync()orHost.DisposeAsync()call to retry cleanup with the same aggregate; - releases ownership only after cleanup succeeds; and
- does not repeat an already completed stop during later disposal.
This retryable-resource-transaction contract prevents the Anti-Corruption Layer from concealing or orphaning the only cleanup-capable reference. Owner specifications cover both an explicit second shutdown attempt and disposal following a failed explicit stop, as well as late-startup cancellation whose first compensation attempt fails.
Native ownership model
The native launcher constructs an inert IHost and defers external work until host startup. Hosted resources are registered in dependency order:
- resolved package-launch plan;
- NATS transport connection;
- telemetry provider;
MatrixRuntimelifecycle;- package startup;
- runtime presence, heartbeat, and registry claims.
Generic Host stops those resources in reverse dependency order. Presence drains and publishes departure while package, runtime, telemetry, and transport are still available. Runtime cleanup completes before telemetry shutdown. Transport shutdown is terminal and occurs last.
NATS lifecycle contract
The connection factory in @open-matrix/package-runtime owns one immutable reconnect policy shared by native NATS and WebSocket NATS clients:
- a 5-second connection timeout;
- reconnect enabled;
- unlimited reconnect attempts while the host remains operational;
- a 500-millisecond reconnect delay;
- up to 250 milliseconds of reconnect jitter.
Transient connectivity is handled by the client reconnect loop. Orderly terminal shutdown is owned by NativeTransportResource and the underlying NatsTransport:
- startup flush proves the connection is operational before dependents start;
- subscriptions are unsubscribed before connection drain;
drain()flushes pending protocol work and closes the active NATS session cooperatively;close()is used only when the drained connection is not already closed;- repeated host stop or disposal is idempotent and does not repeat completed phases.
A failed earlier consumer phase must prevent telemetry and transport teardown so retry retains every dependency required to finish cleanup.
Native NATS executable canary
The ./native-nats-canary subpath and canary:nats package command provide a bounded executable-edge proof harness. The canary does not construct MatrixRuntime, start package actors, deploy anything, restart a broker, or mutate a founder/user service. It:
- obtains a real provider connection through
connectMatrixRuntimeTransport; - flushes startup readiness;
- creates a unique semantic subscription and proves publish/flush loopback;
- forces one client-side reconnect by default;
- proves a second loopback through the reconnected session and automatically restored subscription;
- releases the subscription and performs cooperative transport drain/terminal close;
- reports a credential-free JSON evidence record;
- preserves both operational and cleanup failures when both occur.
Run it only against an explicitly selected test broker and Matrix root:
MATRIX_NATS_URL=nats://127.0.0.1:4222 \
MATRIX_ROOT=com.example.canary \
pnpm --dir sdk/runtime-launcher canary:nats
JWT authentication is optional but atomic: MATRIX_NATS_JWT and MATRIX_NATS_SEED must be provided together. MATRIX_NATS_CANARY_TIMEOUT_MS defaults to 15000. MATRIX_NATS_CANARY_REQUIRE_RECONNECT defaults to true and may be set to false only for a deliberately narrower connectivity/drain diagnostic; that narrower mode does not satisfy the reconnect acceptance gate.
Owner specifications inject the provider connector and use the real NatsTransport over a deterministic connection double. They prove subscription readiness, two loopbacks around reconnect, cooperative cleanup after success, and cleanup after an operational failure. Those specifications establish the executable transaction contract; only a successful run against a real disposable NATS endpoint supplies live canary evidence.
Executable-edge forced termination
@open-matrix/hosting-node translates SIGINT and SIGTERM into cooperative StopApplication requests and deliberately never calls process.exit. An executable may opt into bounded escalation through the ./node-forced-termination subpath:
import { StartNodeForcedTerminationPolicy } from '@open-matrix/runtime-launcher3/node-forced-termination';
const forcedTermination = StartNodeForcedTerminationPolicy({
GracePeriodMilliseconds: 30_000,
ExitCode: 1,
});
The first configured signal preserves cooperative shutdown and arms one unref'ed grace-period timer. A second signal, or expiry of that deadline, performs exactly one forced exit. The policy removes every signal registration and releases the timer before invoking the irreversible exit port. Explicit disposal cancels escalation without terminating the process, and stale deadline callbacks are inert.
The policy is intentionally opt-in. Reusable hosting infrastructure does not hide an unconditional process-termination decision, and tests inject signal, scheduling, and exit ports rather than mutating process-global state.
Proof boundary
Owner specifications live in src/__tests__/hosted-launch.spec.ts, src/__tests__/native-hosted-launch.spec.ts, src/__tests__/native-nats-canary.spec.ts, and src/__tests__/node-forced-termination.spec.ts. Repository acceptance additionally requires a frozen workspace installation, the complete package suite, a successful real-endpoint native NATS canary, source/dependency guards, and the Matrix Generic Host evidence ledger against one exact current head.
This package must not publish, deploy, restart services, or mutate a founder/user environment as part of integration proof.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @open-matrix/contracts | 0.1.9 |
| @open-matrix/core | 0.1.14 |
| @open-matrix/credential-plane | 0.1.2 |
| @open-matrix/hosting | 0.1.2 |
| @open-matrix/hosting-node | 0.1.2 |
| @open-matrix/identity-client | 0.1.3 |
| @open-matrix/nats-auth | 0.1.12 |
| @open-matrix/package-runtime | 0.1.16 |
| @open-matrix/runtime-hosting | 0.1.2 |
| @open-matrix/sqlite-store | 1.0.5 |
| @open-matrix/subjects | 0.1.5 |
| @opentelemetry/api | ^1.9.1 |
| @opentelemetry/core | ^1.30.1 |
| @opentelemetry/resources | ^1.30.1 |
| @opentelemetry/sdk-trace-base | ^1.30.1 |
| @opentelemetry/sdk-trace-node | ^1.30.1 |
| nats | ^2.29.3 |
Development Dependencies
| ID | Version |
|---|---|
| @types/node | ^25.0.10 |
| tsx | 4.15.6 |
| typescript | 5.6.3 |