coakka-v2-connector-node 1.3.1

package/CONSUMING.md

@@ -0,0 +1,48 @@
+# Consuming `coakka-v2-connector-node`
+
+The Node.js runtime package is a binary tarball that embeds the native v2
+runtime. Applications normally do not need to pass a native library path.
+
+```ts
+import {
+  ConnectorStartSpec,
+  EndpointFlag,
+  localRoute,
+  PayloadFormat,
+  PayloadIdentity,
+  RuntimeHost,
+} from "coakka-v2-connector-node";
+```
+
+For local development or diagnostics, an explicit native library path can be
+provided:
+
+```ts
+RuntimeHost.start(startSpec, "/abs/path/to/libcoakka_runtime_v2.so");
+```
+
+The environment override is:
+
+```sh
+COAKKA_RUNTIME_LIB=/abs/path/to/libcoakka_runtime_v2.so
+```
+
+Current embedded native package:
+
+- native core version: `1.3.1`
+- native package version: `1.3.1+bda2ef5`
+- platforms: `macos-aarch64`, `linux-aarch64`, `linux-x86_64`,
+  `windows-aarch64`, `windows-x86_64`
+
+One Node.js process may start one active `RuntimeHost`. Close it from the app
+lifecycle hook before starting another host in the same process.
+
+First-run helpers:
+
+```ts
+const requestIdentity = PayloadIdentity.text("demo.echo.request.v1");
+const routes = [localRoute("svc.echo")];
+```
+
+Use `PayloadFormat.TEXT` for plain text in user-facing code. `PLAIN_TEXT`
+remains as a compatibility alias for the legacy wire-format name.

package/LICENSE.md

@@ -0,0 +1,115 @@
+# CoAkka Public Artifact Preview License 1.0
+
+Effective: 2026-07-19
+
+This repository is the public binary artifact surface for CoAkka. It contains
+headers, native libraries, connector packages, Maven artifacts, checksums, and
+artifact metadata. It is not a source-build repository.
+
+Unless a specific release artifact includes different license terms, the
+artifacts in this repository are made available under the following preview
+terms.
+
+This is not an OSI-approved open source license. The separate
+`coakka-samples` repository may use a permissive open source license for sample
+code and documentation; that sample license does not change the terms for the
+artifacts distributed from this repository.
+
+## Definitions
+
+`Artifacts` means the CoAkka binaries, headers, libraries, connector packages,
+Maven artifacts, container-bundle files, checksums, manifests, and release
+metadata distributed from this repository or from an official release page for
+this repository.
+
+`Production` means any environment that serves live end-user traffic, live
+customer data, live operational data, revenue-generating workloads, or
+customer-facing workloads outside development, test, CI, sample execution, or
+proof-of-concept evaluation.
+
+`Official sample images` means container images published by the CoAkka
+project or repository owner, including the current
+`docker.io/gabrielgun1983/*` sample image namespace and any future images
+published under an official CoAkka container namespace, that bundle unmodified
+artifacts solely to run official CoAkka samples.
+
+## Allowed Use
+
+You may download, copy, and use the artifacts from this repository to:
+
+- evaluate CoAkka locally
+- run the official public samples
+- build proof-of-concept integrations
+- run development and test environments for applications that integrate with
+  CoAkka
+- run CI jobs, automated tests, and integration verification for
+  non-production applications or evaluations
+- run company evaluations, proofs of concept, and integration tests,
+  including evaluations inside commercial organizations
+- redistribute unmodified CoAkka artifacts inside local development, test, or
+  sample environments, provided this notice and the included checksums or
+  manifests remain available
+- pull, cache internally, and run official sample images for local development,
+  CI, test, sample execution, proof-of-concept integration, and evaluation
+
+## Reserved Uses
+
+The following uses require a separate written license:
+
+- selling, hosting, or offering CoAkka artifacts as a managed runtime service
+- running CoAkka artifacts in production systems
+- bundling CoAkka artifacts into a product distributed to customers
+- redistributing CoAkka artifacts as part of a paid product, support package,
+  appliance, cloud image, or hosted service
+- offering a product or service that presents modified CoAkka artifacts as
+  official CoAkka artifacts
+- removing or obscuring copyright, license, checksum, or provenance notices
+- reverse engineering artifacts except where that restriction is prohibited by
+  applicable law
+- using the CoAkka name, package names, artifact names, image names, or other
+  project identifiers in a way that implies endorsement of an unofficial fork,
+  hosted service, or product
+
+## Official Samples
+
+Official sample images may bundle unmodified artifacts solely so users can run
+official CoAkka samples without installing the artifacts manually.
+
+This sample-image permission does not grant third parties the right to create,
+publish, sell, host, or distribute derivative images for production, customer
+distribution, hosted services, paid support packages, appliances, or cloud
+marketplace offerings.
+
+## Production Use
+
+These preview terms are intended for developer evaluation, sample execution,
+non-production proof-of-concept work, CI, and integration testing. Production
+use, hosted service use, customer distribution, and paid redistribution require
+explicit release terms or a separate written agreement.
+
+For production, hosted service, customer distribution, paid redistribution, or
+other commercial rights, contact the project through `SUPPORT.md`.
+
+## No Warranty
+
+The artifacts are provided as-is, without warranties or conditions of any kind,
+to the maximum extent permitted by applicable law.
+
+## Limitation Of Liability
+
+To the maximum extent permitted by applicable law, the project contributors and
+artifact publishers are not liable for any direct, indirect, incidental,
+special, consequential, exemplary, or other damages arising from use of the
+artifacts.
+
+## No Patent Or Trademark Grant
+
+These preview terms do not grant patent rights, trademark rights, or rights to
+use the CoAkka name beyond the limited artifact and sample uses allowed above.
+Trademark use is governed by `TRADEMARKS.md`.
+
+## Legal Notice
+
+This file is not legal advice. If your intended use depends on legal
+interpretation of these terms, consult your own counsel or request a separate
+written agreement.

package/README.md

@@ -0,0 +1,147 @@
+# coakka-v2-connector-node
+
+Node.js connector package for the CoAkka runtime v2.
+
+Current package shape:
+
+- `RuntimeHost.start(...)` as the preferred single-process lifecycle entrypoint
+- `ConnectorOrchestrator.start(...)` remains as the compatibility name for the
+  same runtime host
+- `NodeRuntimeClient` as the lower-level request/reply engine
+- `submitRequestTyped(...)`, `submitRequestJson(...)`, `submitRequestRaw(...)`
+- `terminalEvents({ signal, bufferCapacity })`
+- typed payload identity helpers around `messageType`, `payloadSchemaVersion`,
+  and `payloadFormat`, including `PayloadIdentity.text(...)`
+- `localRoute(...)` for same-process targets so first-run samples do not spell
+  host/port placeholders or endpoint flag numbers by hand
+- control snapshot apply helpers
+- monitor doorbell wait helpers
+- delivered-request lane enabled by default for request/reply hosts, with an
+  advanced override for measured one-way-only hosts
+
+Request/reply lane in Node.js now has two host API shapes over the same runtime contract:
+
+- `ask...`: submit and wait inline
+- `submitRequest...` + `terminalEvents(...)`: submit now, consume terminal outcome (`response` or `deadletter`) later through an async iterator
+
+`terminalEvents(...)` is a connector-owned API shape, not a separate transport mode.
+
+## Before / After
+
+Before, local application code had to start from the connector-internal
+orchestration name:
+
+```ts
+import {
+  ConnectorOrchestrator,
+  PayloadFormat,
+  PayloadIdentity,
+} from "@coakka/v2-connector-node";
+
+const connector = ConnectorOrchestrator.start({
+  systemName: "customer-local",
+  nodeId: "customer-local-node",
+  routes: [],
+});
+const requestIdentity = new PayloadIdentity(
+  "customer.create.request.v1",
+  1,
+  PayloadFormat.JSON,
+);
+
+try {
+  const response = await connector.askJson(
+    "customer-api",
+    "customer.create",
+    { name: "Ada" },
+    requestIdentity,
+  );
+} finally {
+  connector.close();
+}
+```
+
+After, the same single-process runtime is named as the application-owned host:
+
+```ts
+import {
+  PayloadFormat,
+  PayloadIdentity,
+  RuntimeHost,
+} from "@coakka/v2-connector-node";
+
+const runtime = RuntimeHost.start({
+  systemName: "customer-local",
+  nodeId: "customer-local-node",
+  routes: [],
+});
+const requestIdentity = new PayloadIdentity(
+  "customer.create.request.v1",
+  1,
+  PayloadFormat.JSON,
+);
+
+try {
+  const response = await runtime.askJson(
+    "customer-api",
+    "customer.create",
+    { name: "Ada" },
+    requestIdentity,
+  );
+} finally {
+  runtime.close();
+}
+```
+
+`ConnectorOrchestrator` remains available for existing code. New local-first
+Spring Boot, Quarkus, CRUD, and script-style examples should prefer
+`RuntimeHost` so the first screen reads as one embedded runtime owner, not a
+remote connector setup.
+
+`separateDeliveredRequestLane` defaults to `true`. Most request/reply services
+should leave it alone so inbound handler work stays separate from
+reply/deadletter matching. Set it to `false` only for advanced, measured,
+mostly one-way hosts.
+
+Hot-path reading note:
+
+- false-sharing is not the first-order hot-path concern for this Node.js layer
+  in the same way it is for the native C++ connector
+- the current Node connector cost center is more likely to sit in:
+  - native binding boundary and runtime read/write calls
+  - wire-codec encode/decode and JS object mapping
+  - async iterator buffering around `terminalEvents(...)`
+  - event-loop and worker handoff topology
+- only revisit cacheline-style hardening here if this layer later moves toward
+  packed native-side state, off-heap rings, or a flatter shared-memory layout
+
+Install dependencies for local development:
+
+```sh
+cd node
+npm install
+```
+
+Build:
+
+```sh
+npm run build
+```
+
+The build stages release-shaped native libraries from:
+
+```text
+v2/staging/native/1.3.1+bda2ef5/
+```
+
+Test:
+
+```sh
+npm test
+```
+
+Packaged consumer smoke:
+
+```sh
+npm run smoke:packaged
+```

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { COAKKA_V2_NATIVE_CORE_VERSION, COAKKA_V2_NATIVE_GIT_COMMIT, COAKKA_V2_NATIVE_PACKAGE_VERSION, COAKKA_V2_NODE_VERSION, } from "./packaging.js";
+export { BusinessStatus, DeliveryHint, EndpointFlag, MessageKind, OverloadMode, PayloadFormat, PayloadIdentity, RequestTerminalEventKind, RouteStrategy, localRoute, requireValidConnectorConfig, requireValidRuntimeOverloadPolicy, requireValidRoute, toConnectorConfig, type ConnectorConfig, type ConnectorStartSpec, type EndpointSpec, type MaybePromise, type ObservedDeadletter, type RuntimeOverloadPolicy, type RequestTerminalEvent, type RequestTerminalEventDeadletter, type RequestTerminalEventResponse, type RouteSpec, type SubmittedRequest, } from "./models.js";
+export { ConnectorOrchestrator, RuntimeHost, RuntimeLibraryResolver, } from "./orchestrator.js";
+export { DeadletterError, NodeRuntimeClient, type HandlerFn, type MonitorSnapshot, type RuntimeClientStats, type DeadlettersOptions, type TerminalEventsOptions, } from "./runtime-client.js";
+export type { ControlEnvelope, RouteSnapshotPayload, TransportDeadletter, TransportEnvelope, } from "./protobuf.js";
+export { COAKKA_ABI_VERSION, COAKKA_OK, HOST_HANDLES_ENABLE_MONITOR, HOST_HANDLES_SEPARATE_DELIVERED_REQUEST_LANE, type HostHandlesSnapshot, type RuntimeConfigSnapshot, type RuntimeHealthSnapshot, type RuntimeInfoSnapshot, type RuntimeStatsSnapshot, } from "./runtime-ffi.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { COAKKA_V2_NATIVE_CORE_VERSION, COAKKA_V2_NATIVE_GIT_COMMIT, COAKKA_V2_NATIVE_PACKAGE_VERSION, COAKKA_V2_NODE_VERSION, } from "./packaging.js";
+export { BusinessStatus, DeliveryHint, EndpointFlag, MessageKind, OverloadMode, PayloadFormat, PayloadIdentity, RequestTerminalEventKind, RouteStrategy, localRoute, requireValidConnectorConfig, requireValidRuntimeOverloadPolicy, requireValidRoute, toConnectorConfig, } from "./models.js";
+export { ConnectorOrchestrator, RuntimeHost, RuntimeLibraryResolver, } from "./orchestrator.js";
+export { DeadletterError, NodeRuntimeClient, } from "./runtime-client.js";
+export { COAKKA_ABI_VERSION, COAKKA_OK, HOST_HANDLES_ENABLE_MONITOR, HOST_HANDLES_SEPARATE_DELIVERED_REQUEST_LANE, } from "./runtime-ffi.js";

package/dist/models.d.ts

@@ -0,0 +1,119 @@
+export declare enum MessageKind {
+    UNSPECIFIED = 0,
+    REQUEST = 1,
+    RESPONSE = 2,
+    EVENT = 3
+}
+export declare enum BusinessStatus {
+    UNSPECIFIED = 0,
+    OK = 1,
+    ERROR = 2
+}
+export declare enum DeliveryHint {
+    UNSPECIFIED = 0,
+    ROUTER_DEFAULT = 1,
+    PREFER_LOCAL = 2,
+    REQUIRE_LOCAL = 3,
+    REQUIRE_REMOTE = 4
+}
+export declare enum PayloadFormat {
+    UNSPECIFIED = 0,
+    JSON = 1,
+    PROTOBUF = 2,
+    THRIFT = 3,
+    MSGPACK = 4,
+    TEXT = 5,
+    PLAIN_TEXT = 5,
+    BINARY = 6
+}
+export declare enum RouteStrategy {
+    UNSPECIFIED = 0,
+    SINGLE_OWNER = 1,
+    WEIGHTED_ROUND_ROBIN = 2,
+    RENDEZVOUS_HASH = 3
+}
+export declare enum EndpointFlag {
+    NONE = 0,
+    LOCAL = 1,
+    UNAVAILABLE = 2
+}
+export declare enum OverloadMode {
+    REJECT = 0,
+    DROP_EXPIRED_FIRST = 1,
+    DROP_ONE_WAY_FIRST = 2
+}
+export interface RuntimeOverloadPolicy {
+    ingressMode?: OverloadMode;
+    localDeliveryMode?: OverloadMode;
+    remoteOutboundMode?: OverloadMode;
+    remoteOutboundReplyReserveSlots?: number;
+}
+export type MaybePromise<T> = T | Promise<T>;
+export declare class PayloadIdentity {
+    readonly messageType: string;
+    readonly payloadSchemaVersion: number;
+    readonly payloadFormat: PayloadFormat;
+    constructor(messageType: string, payloadSchemaVersion?: number, payloadFormat?: PayloadFormat);
+    isTyped(): boolean;
+    requireTyped(what?: string): PayloadIdentity;
+    static text(messageType: string, payloadSchemaVersion?: number): PayloadIdentity;
+}
+export interface EndpointSpec {
+    host: string;
+    port: number;
+    weight?: number;
+    flags?: number;
+}
+export interface RouteSpec {
+    target: string;
+    endpoints: readonly EndpointSpec[];
+    strategy?: RouteStrategy;
+    routeKeyHint?: string;
+    flags?: number;
+}
+export interface ConnectorConfig {
+    systemName: string;
+    nodeId: string;
+    routes: readonly RouteSpec[];
+    strictNoDrop?: boolean;
+    queueCapacity?: number;
+    enableMonitor?: boolean;
+    separateDeliveredRequestLane?: boolean;
+    generation?: number;
+    overloadPolicy?: RuntimeOverloadPolicy;
+}
+export interface ConnectorStartSpec extends ConnectorConfig {
+}
+export interface SubmittedRequest {
+    messageId: string;
+    correlationId: string;
+}
+export declare const RequestTerminalEventKind: {
+    readonly RESPONSE: "response";
+    readonly DEADLETTER: "deadletter";
+};
+export type RequestTerminalEventKind = (typeof RequestTerminalEventKind)[keyof typeof RequestTerminalEventKind];
+export interface RequestTerminalEventResponse {
+    kind: typeof RequestTerminalEventKind.RESPONSE;
+    requestMessageId: string;
+    correlationId: string;
+    envelope: import("./protobuf.js").TransportEnvelope;
+}
+export interface RequestTerminalEventDeadletter {
+    kind: typeof RequestTerminalEventKind.DEADLETTER;
+    requestMessageId: string;
+    correlationId: string;
+    deadletter: import("./protobuf.js").TransportDeadletter;
+}
+export type RequestTerminalEvent = RequestTerminalEventResponse | RequestTerminalEventDeadletter;
+export interface ObservedDeadletter {
+    deadletter: import("./protobuf.js").TransportDeadletter;
+    requestMessageId: string | null;
+    correlationId: string | null;
+    matchedPendingRequest: boolean;
+}
+export declare function requireValidRoute(route: RouteSpec): RouteSpec;
+export declare function localRoute(target: string, port?: number): RouteSpec;
+export declare function requireValidRuntimeOverloadPolicy(policy: RuntimeOverloadPolicy, what?: string): RuntimeOverloadPolicy;
+export declare function requireValidConnectorConfig(config: ConnectorConfig): ConnectorConfig;
+export declare function toConnectorConfig(startSpec: ConnectorStartSpec): ConnectorConfig;

package/dist/models.js

@@ -0,0 +1,150 @@
+export var MessageKind;
+(function (MessageKind) {
+    MessageKind[MessageKind["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    MessageKind[MessageKind["REQUEST"] = 1] = "REQUEST";
+    MessageKind[MessageKind["RESPONSE"] = 2] = "RESPONSE";
+    MessageKind[MessageKind["EVENT"] = 3] = "EVENT";
+})(MessageKind || (MessageKind = {}));
+export var BusinessStatus;
+(function (BusinessStatus) {
+    BusinessStatus[BusinessStatus["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    BusinessStatus[BusinessStatus["OK"] = 1] = "OK";
+    BusinessStatus[BusinessStatus["ERROR"] = 2] = "ERROR";
+})(BusinessStatus || (BusinessStatus = {}));
+export var DeliveryHint;
+(function (DeliveryHint) {
+    DeliveryHint[DeliveryHint["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    DeliveryHint[DeliveryHint["ROUTER_DEFAULT"] = 1] = "ROUTER_DEFAULT";
+    DeliveryHint[DeliveryHint["PREFER_LOCAL"] = 2] = "PREFER_LOCAL";
+    DeliveryHint[DeliveryHint["REQUIRE_LOCAL"] = 3] = "REQUIRE_LOCAL";
+    DeliveryHint[DeliveryHint["REQUIRE_REMOTE"] = 4] = "REQUIRE_REMOTE";
+})(DeliveryHint || (DeliveryHint = {}));
+export var PayloadFormat;
+(function (PayloadFormat) {
+    PayloadFormat[PayloadFormat["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    PayloadFormat[PayloadFormat["JSON"] = 1] = "JSON";
+    PayloadFormat[PayloadFormat["PROTOBUF"] = 2] = "PROTOBUF";
+    PayloadFormat[PayloadFormat["THRIFT"] = 3] = "THRIFT";
+    PayloadFormat[PayloadFormat["MSGPACK"] = 4] = "MSGPACK";
+    PayloadFormat[PayloadFormat["TEXT"] = 5] = "TEXT";
+    PayloadFormat[PayloadFormat["PLAIN_TEXT"] = 5] = "PLAIN_TEXT";
+    PayloadFormat[PayloadFormat["BINARY"] = 6] = "BINARY";
+})(PayloadFormat || (PayloadFormat = {}));
+export var RouteStrategy;
+(function (RouteStrategy) {
+    RouteStrategy[RouteStrategy["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    RouteStrategy[RouteStrategy["SINGLE_OWNER"] = 1] = "SINGLE_OWNER";
+    RouteStrategy[RouteStrategy["WEIGHTED_ROUND_ROBIN"] = 2] = "WEIGHTED_ROUND_ROBIN";
+    RouteStrategy[RouteStrategy["RENDEZVOUS_HASH"] = 3] = "RENDEZVOUS_HASH";
+})(RouteStrategy || (RouteStrategy = {}));
+export var EndpointFlag;
+(function (EndpointFlag) {
+    EndpointFlag[EndpointFlag["NONE"] = 0] = "NONE";
+    EndpointFlag[EndpointFlag["LOCAL"] = 1] = "LOCAL";
+    EndpointFlag[EndpointFlag["UNAVAILABLE"] = 2] = "UNAVAILABLE";
+})(EndpointFlag || (EndpointFlag = {}));
+export var OverloadMode;
+(function (OverloadMode) {
+    OverloadMode[OverloadMode["REJECT"] = 0] = "REJECT";
+    OverloadMode[OverloadMode["DROP_EXPIRED_FIRST"] = 1] = "DROP_EXPIRED_FIRST";
+    OverloadMode[OverloadMode["DROP_ONE_WAY_FIRST"] = 2] = "DROP_ONE_WAY_FIRST";
+})(OverloadMode || (OverloadMode = {}));
+export class PayloadIdentity {
+    messageType;
+    payloadSchemaVersion;
+    payloadFormat;
+    constructor(messageType, payloadSchemaVersion = 1, payloadFormat = PayloadFormat.UNSPECIFIED) {
+        this.messageType = messageType;
+        this.payloadSchemaVersion = payloadSchemaVersion;
+        this.payloadFormat = payloadFormat;
+    }
+    isTyped() {
+        return (this.messageType.trim() !== "" &&
+            this.payloadSchemaVersion >= 1 &&
+            this.payloadFormat !== PayloadFormat.UNSPECIFIED);
+    }
+    requireTyped(what = "payload identity") {
+        if (this.messageType.trim() === "") {
+            throw new Error(`${what} requires messageType`);
+        }
+        if (this.payloadSchemaVersion < 1) {
+            throw new Error(`${what} requires payloadSchemaVersion >= 1`);
+        }
+        if (this.payloadFormat === PayloadFormat.UNSPECIFIED) {
+            throw new Error(`${what} requires declared payloadFormat`);
+        }
+        return this;
+    }
+    static text(messageType, payloadSchemaVersion = 1) {
+        return new PayloadIdentity(messageType, payloadSchemaVersion, PayloadFormat.TEXT);
+    }
+}
+export const RequestTerminalEventKind = {
+    RESPONSE: "response",
+    DEADLETTER: "deadletter",
+};
+export function requireValidRoute(route) {
+    if (route.target.trim() === "") {
+        throw new Error("route requires target");
+    }
+    if (route.endpoints.length === 0) {
+        throw new Error(`route target=${route.target} requires at least one endpoint`);
+    }
+    return route;
+}
+export function localRoute(target, port = 9001) {
+    return {
+        target,
+        endpoints: [{ host: "127.0.0.1", port, flags: EndpointFlag.LOCAL }],
+    };
+}
+export function requireValidRuntimeOverloadPolicy(policy, what = "overloadPolicy") {
+    if ((policy.ingressMode ?? OverloadMode.REJECT) !== OverloadMode.REJECT) {
+        throw new Error(`${what}.ingressMode currently supports only REJECT`);
+    }
+    if ((policy.localDeliveryMode ?? OverloadMode.REJECT) !== OverloadMode.REJECT) {
+        throw new Error(`${what}.localDeliveryMode currently supports only REJECT`);
+    }
+    if ((policy.remoteOutboundReplyReserveSlots ?? 0) < 0) {
+        throw new Error(`${what}.remoteOutboundReplyReserveSlots must be >= 0`);
+    }
+    return policy;
+}
+export function requireValidConnectorConfig(config) {
+    if (config.systemName.trim() === "") {
+        throw new Error("connector config requires systemName");
+    }
+    if (config.nodeId.trim() === "") {
+        throw new Error("connector config requires nodeId");
+    }
+    if ((config.queueCapacity ?? 128) < 1) {
+        throw new Error("connector config requires queueCapacity >= 1");
+    }
+    if ((config.generation ?? 1) < 1) {
+        throw new Error("connector config requires generation >= 1");
+    }
+    if (config.overloadPolicy != null) {
+        requireValidRuntimeOverloadPolicy(config.overloadPolicy, "connector config overloadPolicy");
+    }
+    if (config.routes.length === 0) {
+        throw new Error("connector config requires at least one route");
+    }
+    for (const route of config.routes) {
+        requireValidRoute(route);
+    }
+    return config;
+}
+export function toConnectorConfig(startSpec) {
+    requireValidConnectorConfig(startSpec);
+    return {
+        systemName: startSpec.systemName,
+        nodeId: startSpec.nodeId,
+        routes: startSpec.routes,
+        strictNoDrop: startSpec.strictNoDrop ?? true,
+        queueCapacity: startSpec.queueCapacity ?? 128,
+        enableMonitor: startSpec.enableMonitor ?? true,
+        separateDeliveredRequestLane: startSpec.separateDeliveredRequestLane ?? true,
+        generation: startSpec.generation ?? 1,
+        overloadPolicy: startSpec.overloadPolicy,
+    };
+}

package/dist/orchestrator.d.ts

@@ -0,0 +1,80 @@
+import type { PathLike } from "node:fs";
+import { type ConnectorConfig, type ConnectorStartSpec, DeliveryHint, type ObservedDeadletter, type PayloadIdentity, type RequestTerminalEvent, type SubmittedRequest } from "./models.js";
+import type { TransportEnvelope } from "./protobuf.js";
+import type { HandlerFn, DeadlettersOptions, MonitorSnapshot, RuntimeClientStats, TerminalEventsOptions } from "./runtime-client.js";
+import { NodeRuntimeClient } from "./runtime-client.js";
+export declare class RuntimeLibraryResolver {
+    static readonly envVar = "COAKKA_RUNTIME_LIB";
+    static resolve(explicitPath?: string | PathLike, candidateNames?: readonly string[]): string;
+    static platformId(osName?: NodeJS.Platform, archName?: NodeJS.Architecture): string;
+    static normalizeOs(osName: string): string;
+    static normalizeArch(archName: string): string;
+    static runtimeResourceFileNamesForCurrentPlatform(osName?: NodeJS.Platform): string[];
+    private static resolveEmbedded;
+    private static searchCandidates;
+    private static requireExisting;
+}
+declare class ControlApi {
+    private readonly orchestrator;
+    constructor(orchestrator: ConnectorOrchestrator);
+    applySnapshot(generation: number, routes: ConnectorConfig["routes"], sourceConnector?: string, seq?: number, overloadPolicy?: ConnectorConfig["overloadPolicy"]): void;
+}
+declare class MonitorApi {
+    private readonly orchestrator;
+    constructor(orchestrator: ConnectorOrchestrator);
+    isEnabled(): boolean;
+    snapshot(signalCount?: number): MonitorSnapshot;
+    awaitNext(timeoutMs?: number): Promise<MonitorSnapshot | null>;
+    awaitAppliedGenerationAtLeast(generation: number, timeoutMs?: number): Promise<MonitorSnapshot | null>;
+}
+export declare class ConnectorOrchestrator {
+    readonly runtimeLibPath: string;
+    readonly startSpec: ConnectorStartSpec;
+    readonly client: NodeRuntimeClient;
+    private static active;
+    static start(startSpec: ConnectorStartSpec, runtimeLibPath?: string | PathLike): ConnectorOrchestrator;
+    readonly control: ControlApi;
+    readonly monitor: MonitorApi;
+    private closed;
+    private constructor();
+    askTyped(source: string, target: string, payload: Uint8Array, payloadIdentity: PayloadIdentity, timeoutMs?: number, operation?: string, deliveryHint?: DeliveryHint, headers?: Record<string, string>): Promise<TransportEnvelope>;
+    askJson(source: string, target: string, payload: Record<string, unknown>, payloadIdentity: PayloadIdentity, timeoutMs?: number, operation?: string, deliveryHint?: DeliveryHint, headers?: Record<string, string>): Promise<Record<string, unknown>>;
+    askRaw(request: TransportEnvelope, timeoutMs?: number): Promise<TransportEnvelope>;
+    submitRequestTyped(source: string, target: string, payload: Uint8Array, payloadIdentity: PayloadIdentity, timeoutMs?: number, operation?: string, deliveryHint?: DeliveryHint, headers?: Record<string, string>): SubmittedRequest;
+    submitRequestJson(source: string, target: string, payload: Record<string, unknown>, payloadIdentity: PayloadIdentity, timeoutMs?: number, operation?: string, deliveryHint?: DeliveryHint, headers?: Record<string, string>): SubmittedRequest;
+    submitRequestRaw(request: TransportEnvelope): SubmittedRequest;
+    terminalEvents(options?: TerminalEventsOptions): AsyncIterableIterator<RequestTerminalEvent>;
+    deadletters(options?: DeadlettersOptions): AsyncIterableIterator<ObservedDeadletter>;
+    sendOneWayTyped(source: string, target: string, payload: Uint8Array, payloadIdentity: PayloadIdentity, deliveryHint?: DeliveryHint, headers?: Record<string, string>): void;
+    sendOneWayJson(source: string, target: string, payload: Record<string, unknown>, payloadIdentity: PayloadIdentity, deliveryHint?: DeliveryHint, headers?: Record<string, string>): void;
+    submitEnvelope(envelope: TransportEnvelope): void;
+    submitTypedEnvelope(envelope: TransportEnvelope): void;
+    submitRawEnvelope(envelope: TransportEnvelope): void;
+    registerHandler(target: string, handler: HandlerFn, typedReplies?: boolean): void;
+    registerRawHandler(target: string, handler: HandlerFn): void;
+    clientStats(): RuntimeClientStats;
+    runtimeInfo(): import("./runtime-ffi.js").RuntimeInfoSnapshot;
+    runtimeConfig(): import("./runtime-ffi.js").RuntimeConfigSnapshot;
+    health(): import("./runtime-ffi.js").RuntimeHealthSnapshot;
+    stats(): import("./runtime-ffi.js").RuntimeStatsSnapshot;
+    runtimeSnapshot(): {
+        runtimeInfo: import("./runtime-ffi.js").RuntimeInfoSnapshot;
+        runtimeConfig: import("./runtime-ffi.js").RuntimeConfigSnapshot;
+        connector: RuntimeClientStats & {
+            separateDeliveredRequestLane: boolean;
+            systemName: string;
+            nodeId: string;
+        };
+        health: import("./runtime-ffi.js").RuntimeHealthSnapshot;
+        stats: import("./runtime-ffi.js").RuntimeStatsSnapshot;
+    };
+    applySnapshot(generation: number, routes: ConnectorConfig["routes"], sourceConnector?: string, seq?: number, overloadPolicy?: import("./models.js").RuntimeOverloadPolicy | undefined): void;
+    monitorIsEnabled(): boolean;
+    monitorSnapshot(signalCount?: number): MonitorSnapshot;
+    awaitNextMonitor(timeoutMs?: number): Promise<MonitorSnapshot | null>;
+    awaitAppliedGenerationAtLeast(generation: number, timeoutMs?: number): Promise<MonitorSnapshot | null>;
+    close(): void;
+}
+export declare const RuntimeHost: typeof ConnectorOrchestrator;
+export type RuntimeHost = ConnectorOrchestrator;
+export {};