@zlink-systems/framework 0.10.0

package/dist/contracts/Locations/Writes.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkLocationWriteStatus = exports.ZLinkLocationWriteIntent = void 0;
+var ZLinkLocationWriteIntent;
+(function (ZLinkLocationWriteIntent) {
+    ZLinkLocationWriteIntent[ZLinkLocationWriteIntent["NewClaim"] = 1] = "NewClaim";
+    ZLinkLocationWriteIntent[ZLinkLocationWriteIntent["Renew"] = 2] = "Renew";
+    ZLinkLocationWriteIntent[ZLinkLocationWriteIntent["Takeover"] = 3] = "Takeover";
+})(ZLinkLocationWriteIntent || (exports.ZLinkLocationWriteIntent = ZLinkLocationWriteIntent = {}));
+var ZLinkLocationWriteStatus;
+(function (ZLinkLocationWriteStatus) {
+    ZLinkLocationWriteStatus["Stored"] = "stored";
+    ZLinkLocationWriteStatus["IgnoredStale"] = "ignoredStale";
+    ZLinkLocationWriteStatus["RejectedConflict"] = "rejectedConflict";
+})(ZLinkLocationWriteStatus || (exports.ZLinkLocationWriteStatus = ZLinkLocationWriteStatus = {}));

package/dist/contracts/Locations/index.d.ts

@@ -0,0 +1,12 @@
+export type { ZLinkLocationOptions } from './Options';
+export { zlinkDefaultLocationOptions } from './Options';
+export type { ZLinkLocationStore, ZLinkStoreCondition, ZLinkStoreKey, ZLinkStoreMutation, ZLinkStorePutVersion, ZLinkStoreReadResult, ZLinkStoreScanCursor, ZLinkStoreScanItem, ZLinkStoreScanPage, ZLinkStoreScanRequest, ZLinkStoreScanResult, ZLinkStoreValue, ZLinkStoreVersion, ZLinkStoreWriteRequest, ZLinkStoreWriteResult } from './Stores';
+export { ZLinkLocationKind, ZLinkLocationRole } from './Values';
+export { ZLinkFrameworkRuntimeState, ZLinkObjectRole } from './Rows';
+export type { ZLinkClientServerServerDescriptor, ZLinkFanoutPublisherDescriptor, ZLinkMeshNodeDescriptor, ZLinkObjectCapability, ZLinkObjectMaintenancePolicyKind, ZLinkPopulationCapacity, ZLinkSpotTypeCapacity } from './Rows';
+export type { ZLinkClientServerServerDescriptorKey, ZLinkFanoutPublisherDescriptorKey, ZLinkLocationPage, ZLinkMeshNodeDescriptorKey, ZLinkPageRequest } from './Keys';
+export * from './Writes';
+export * from './Diagnostics';
+export * from './RuntimeQuery';
+export * from './Readiness';
+export * from './RelocationStore';

package/dist/contracts/Locations/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkObjectRole = exports.ZLinkFrameworkRuntimeState = exports.ZLinkLocationRole = exports.ZLinkLocationKind = exports.zlinkDefaultLocationOptions = void 0;
+var Options_1 = require("./Options");
+Object.defineProperty(exports, "zlinkDefaultLocationOptions", { enumerable: true, get: function () { return Options_1.zlinkDefaultLocationOptions; } });
+var Values_1 = require("./Values");
+Object.defineProperty(exports, "ZLinkLocationKind", { enumerable: true, get: function () { return Values_1.ZLinkLocationKind; } });
+Object.defineProperty(exports, "ZLinkLocationRole", { enumerable: true, get: function () { return Values_1.ZLinkLocationRole; } });
+var Rows_1 = require("./Rows");
+Object.defineProperty(exports, "ZLinkFrameworkRuntimeState", { enumerable: true, get: function () { return Rows_1.ZLinkFrameworkRuntimeState; } });
+Object.defineProperty(exports, "ZLinkObjectRole", { enumerable: true, get: function () { return Rows_1.ZLinkObjectRole; } });
+__exportStar(require("./Writes"), exports);
+__exportStar(require("./Diagnostics"), exports);
+__exportStar(require("./RuntimeQuery"), exports);
+__exportStar(require("./Readiness"), exports);
+__exportStar(require("./RelocationStore"), exports);

package/dist/contracts/RouteMesh/Contracts.d.ts

@@ -0,0 +1,102 @@
+import type { ActorRef, RoutingId } from '../Common';
+export interface ZLinkActorMembership {
+    readonly actor: ActorRef;
+    readonly actorType: string;
+    readonly membershipEpoch: bigint;
+}
+export interface ZLinkLocationOptionValues {
+    readonly ownerLeaseRenewIntervalMs: number;
+    readonly ownerLeaseTtlMs: number;
+    readonly pollingIntervalMs: number;
+    readonly storeFailureGraceMs: number;
+    readonly ownerLeaseFencingMarginMs: number;
+    readonly ownerLeaseRenewTimeoutMs: number;
+    readonly routeCacheMaxAgeMs: number;
+    readonly messageFollowDurationMs: number;
+    readonly sessionRelocationSealTimeoutMs: number;
+    readonly relocationCutoverWaitTimeoutMs: number;
+    readonly relocationPayloadChunkLimitBytes: number;
+    readonly relocationInFlightPayloadBudgetBytes: number;
+    readonly relocationNodeInFlightPayloadBudgetBytes: number;
+}
+export type ZLinkMessageSurface = 'node' | 'channel' | 'spot' | 'instance_spot' | 'logical_multicast' | 'actor' | 'stream' | 'classic_fanout' | 'actor_transfer';
+export type ZLinkMessageKind = 'send' | 'request' | 'response' | 'error' | 'publish' | 'control';
+export type ZLinkRequestFailureReason = 'timeout' | 'cancelled' | 'shutdown';
+export declare class ZLinkRequestFailureError extends Error {
+    readonly reason: ZLinkRequestFailureReason;
+    constructor(reason: ZLinkRequestFailureReason, message: string, cause?: unknown);
+}
+export interface ZLinkRouteMeshRuntimeOptions {
+    mesh(meshName: string): ZLinkMeshPlacementRuntimeOptions;
+    channel(channelName: string): ZLinkMeshChannelRuntimeOptions;
+}
+export interface ZLinkMeshPlacementRuntimeOptions {
+    placementWeight: number;
+}
+export interface ZLinkMeshChannelRuntimeOptions {
+    weight: number;
+}
+export declare enum ZLinkPeerState {
+    Connecting = 0,
+    Ready = 1,
+    Draining = 2,
+    NotConnected = 3,
+    NotRequired = 4
+}
+export declare enum ZLinkTopologyReason {
+    RuntimeNotReady = 0,
+    NoReadyPeer = 1,
+    NoReadyTarget = 2,
+    LocationUnavailable = 3,
+    CapacityExceeded = 4,
+    Draining = 5,
+    InternalFailure = 6
+}
+export interface ZLinkPeerStatus {
+    readonly nodeRid: RoutingId;
+    readonly state: ZLinkPeerState;
+    readonly unavailableReason?: ZLinkTopologyReason;
+}
+export declare enum ZLinkTopologyState {
+    Starting = 0,
+    Ready = 1,
+    Degraded = 2,
+    Stopping = 3,
+    Stopped = 4,
+    Failed = 5
+}
+export interface ZLinkChannelStatus {
+    readonly channelName: string;
+    readonly isReady: boolean;
+    readonly readyTargetCount: number;
+}
+export interface ZLinkPlacementStatus {
+    readonly isAvailable: boolean;
+    readonly activeActorCount: number;
+    readonly activeSpotCount: number;
+    readonly unavailableReason?: ZLinkTopologyReason;
+}
+export interface ZLinkRouteMeshStatus {
+    readonly meshName: string;
+    readonly state: ZLinkTopologyState;
+    readonly isReady: boolean;
+    readonly readyPeerCount: number;
+    readonly channels: readonly ZLinkChannelStatus[];
+    readonly peers: readonly ZLinkPeerStatus[];
+    readonly placement: ZLinkPlacementStatus;
+    readonly sequence: bigint;
+    readonly observedAt: Date;
+}
+export interface ZLinkObservationLoss {
+    readonly coalescedCount: bigint;
+    readonly discardedTerminalCount: bigint;
+}
+export interface ZLinkObservedStatus<TStatus> {
+    readonly status: TStatus;
+    readonly loss: ZLinkObservationLoss;
+}
+export interface ZLinkRouteMeshRuntime {
+    snapshot(meshName: string): ZLinkRouteMeshStatus;
+    observe(meshName: string, capacity?: number, signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkRouteMeshStatus>>;
+    isReady(meshName: string): boolean;
+}

package/dist/contracts/RouteMesh/Contracts.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkTopologyState = exports.ZLinkTopologyReason = exports.ZLinkPeerState = exports.ZLinkRequestFailureError = void 0;
+class ZLinkRequestFailureError extends Error {
+    reason;
+    constructor(reason, message, cause) {
+        super(message, { cause });
+        this.name = 'ZLinkRequestFailureError';
+        this.reason = reason;
+    }
+}
+exports.ZLinkRequestFailureError = ZLinkRequestFailureError;
+var ZLinkPeerState;
+(function (ZLinkPeerState) {
+    ZLinkPeerState[ZLinkPeerState["Connecting"] = 0] = "Connecting";
+    ZLinkPeerState[ZLinkPeerState["Ready"] = 1] = "Ready";
+    ZLinkPeerState[ZLinkPeerState["Draining"] = 2] = "Draining";
+    ZLinkPeerState[ZLinkPeerState["NotConnected"] = 3] = "NotConnected";
+    ZLinkPeerState[ZLinkPeerState["NotRequired"] = 4] = "NotRequired";
+})(ZLinkPeerState || (exports.ZLinkPeerState = ZLinkPeerState = {}));
+var ZLinkTopologyReason;
+(function (ZLinkTopologyReason) {
+    ZLinkTopologyReason[ZLinkTopologyReason["RuntimeNotReady"] = 0] = "RuntimeNotReady";
+    ZLinkTopologyReason[ZLinkTopologyReason["NoReadyPeer"] = 1] = "NoReadyPeer";
+    ZLinkTopologyReason[ZLinkTopologyReason["NoReadyTarget"] = 2] = "NoReadyTarget";
+    ZLinkTopologyReason[ZLinkTopologyReason["LocationUnavailable"] = 3] = "LocationUnavailable";
+    ZLinkTopologyReason[ZLinkTopologyReason["CapacityExceeded"] = 4] = "CapacityExceeded";
+    ZLinkTopologyReason[ZLinkTopologyReason["Draining"] = 5] = "Draining";
+    ZLinkTopologyReason[ZLinkTopologyReason["InternalFailure"] = 6] = "InternalFailure";
+})(ZLinkTopologyReason || (exports.ZLinkTopologyReason = ZLinkTopologyReason = {}));
+var ZLinkTopologyState;
+(function (ZLinkTopologyState) {
+    ZLinkTopologyState[ZLinkTopologyState["Starting"] = 0] = "Starting";
+    ZLinkTopologyState[ZLinkTopologyState["Ready"] = 1] = "Ready";
+    ZLinkTopologyState[ZLinkTopologyState["Degraded"] = 2] = "Degraded";
+    ZLinkTopologyState[ZLinkTopologyState["Stopping"] = 3] = "Stopping";
+    ZLinkTopologyState[ZLinkTopologyState["Stopped"] = 4] = "Stopped";
+    ZLinkTopologyState[ZLinkTopologyState["Failed"] = 5] = "Failed";
+})(ZLinkTopologyState || (exports.ZLinkTopologyState = ZLinkTopologyState = {}));

package/dist/contracts/RouteMesh/RuntimeTopology.d.ts

@@ -0,0 +1,165 @@
+import type { RoutingId } from '../Common';
+import type { ZLinkApplicationJobQueueProfile, ZLinkCoreHwmProfile } from '../Dispatch';
+import type { ZLinkPeerState, ZLinkTopologyReason, ZLinkTopologyState, ZLinkObservedStatus } from './Contracts';
+import type { ZLinkFrameworkRuntimeState } from '../Locations';
+export declare enum ZLinkFrameworkRelocationOutcome {
+    Relocated = 0,
+    Blocked = 1
+}
+export declare enum ZLinkFrameworkRelocationMode {
+    PlannedMaintenance = 0,
+    RollingUpdate = 1
+}
+export declare enum ZLinkFrameworkRelocationReason {
+    None = 0,
+    TargetUnavailable = 1,
+    StoreUnavailable = 2,
+    RelocationDisabled = 3,
+    StateIncompatible = 4,
+    DeadlineExceeded = 5,
+    RelocationFailed = 6,
+    RuntimeNotReady = 7,
+    ManualTopologyUnsupported = 8,
+    ShutdownRequested = 9,
+    OperationInProgress = 10
+}
+export interface ZLinkFrameworkRelocationOptions {
+    readonly mode: ZLinkFrameworkRelocationMode;
+    readonly targetApplicationVersion?: bigint;
+    readonly deadlineMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ZLinkFrameworkRelocationResult {
+    readonly mode: ZLinkFrameworkRelocationMode;
+    readonly effectiveTargetApplicationVersion: bigint;
+    readonly outcome: ZLinkFrameworkRelocationOutcome;
+    readonly reason: ZLinkFrameworkRelocationReason;
+}
+export declare enum ZLinkFrameworkTerminationOutcome {
+    Stopped = 0,
+    ForceStopped = 1
+}
+export declare enum ZLinkFrameworkTerminationReason {
+    None = 0,
+    DeadlineExceeded = 1,
+    TeardownFailed = 2
+}
+export interface ZLinkFrameworkTerminationResult {
+    readonly outcome: ZLinkFrameworkTerminationOutcome;
+    readonly reason: ZLinkFrameworkTerminationReason;
+}
+export interface ZLinkFrameworkLifecycleOptions {
+    readonly deadlineMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ZLinkFrameworkRuntimeStatus {
+    readonly state: ZLinkFrameworkRuntimeState;
+    readonly isReady: boolean;
+    readonly acceptingWork: boolean;
+    readonly capacity: ZLinkHostCapacityStatus;
+    /**
+     * True when every relocation this source started reached its Message
+     * Follow route removal point and its cutover retransmission window ended
+     * (spec 30 §11) — the source-published SafeToShutdown observation.
+     */
+    readonly safeToShutdown: boolean;
+    readonly deadline?: Date;
+    readonly relocationResult?: ZLinkFrameworkRelocationResult;
+    readonly terminationResult?: ZLinkFrameworkTerminationResult;
+    readonly sequence: bigint;
+    readonly observedAt: Date;
+}
+export interface ZLinkCoreHwmStatus {
+    readonly configuredMemoryLimitBytes?: bigint;
+    readonly configuredBudgetBytes?: bigint;
+    readonly configuredProfile: ZLinkCoreHwmProfile;
+    readonly effectiveBudgetBytes: bigint;
+    readonly totalAppliedHwmBytes: bigint;
+    readonly coreQueueAccountedBytes: bigint;
+    readonly applicationAccountedBytes: bigint;
+    readonly currentAccountedBytes: bigint;
+    readonly provisionalAccountedBytes: bigint;
+    readonly peakAccountedBytes: bigint;
+    readonly completionCurrentAccountedBytes: bigint;
+    readonly completionPeakAccountedBytes: bigint;
+    readonly completionPendingMessageCount: bigint;
+    readonly totalMessagingAccountedBytes: bigint;
+    readonly monitorQueueAppliedHwmBytes: bigint;
+    readonly monitorQueueAccountedBytes: bigint;
+    readonly totalInstanceAppliedHwmBytes: bigint;
+    readonly totalInstanceAccountedBytes: bigint;
+    readonly blockedRatioPpm: bigint;
+    readonly activeDirectionalQueueCount: bigint;
+    readonly activeCompletionDirectionalQueueCount: bigint;
+    readonly activeSendQueueCount: bigint;
+    readonly activeReceiveQueueCount: bigint;
+    readonly outstandingApplicationLeaseCount: bigint;
+    readonly retiredQueueCount: bigint;
+    readonly deferredOriginCreditBytes: bigint;
+}
+export interface ZLinkApplicationJobQueueStatus {
+    readonly configuredProfile: ZLinkApplicationJobQueueProfile;
+    readonly configuredManualMax?: bigint;
+    readonly configuredPauseThresholdPercent: number;
+    readonly configuredResumeThresholdPercent: number;
+    readonly effectiveProcessorCount: bigint;
+    readonly effectiveMaxQueuedApplicationJobs: bigint;
+    readonly pausePermitCount: bigint;
+    readonly resumePermitCount: bigint;
+    readonly reservedSupplyPermits: bigint;
+    readonly queuedApplicationJobs: bigint;
+    readonly permitsInUse: bigint;
+    readonly peakPermitsInUse: bigint;
+    readonly pressureState: 'running' | 'paused';
+    readonly currentPauseDurationSeconds: number;
+    readonly capacityWaiters: bigint;
+    readonly capacityWaitCount: bigint;
+    readonly capacityWaitDurationSeconds: number;
+}
+export interface ZLinkHostCapacityStatus {
+    readonly measurementEpoch: bigint;
+    readonly coreHwm: ZLinkCoreHwmStatus;
+    readonly applicationJobQueue: ZLinkApplicationJobQueueStatus;
+}
+export interface ZLinkFrameworkRuntime {
+    readonly status: ZLinkFrameworkRuntimeStatus;
+    observe(signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkFrameworkRuntimeStatus>>;
+    resetCapacityMetrics(): void;
+    relocate(options: ZLinkFrameworkRelocationOptions): Promise<ZLinkFrameworkRelocationResult>;
+    shutdown(options?: ZLinkFrameworkLifecycleOptions): Promise<ZLinkFrameworkTerminationResult>;
+}
+export type ZLinkClientServerRole = 'client' | 'server' | 'clientAndServer';
+export interface ZLinkClientServerTargetStatus {
+    readonly nodeRid: RoutingId;
+    readonly weight: number;
+    readonly state: ZLinkPeerState;
+    readonly unavailableReason?: ZLinkTopologyReason;
+}
+export interface ZLinkClientServerStatus {
+    readonly channelName: string;
+    readonly localRole: ZLinkClientServerRole;
+    readonly state: ZLinkTopologyState;
+    readonly isReady: boolean;
+    readonly readyTargetCount: number;
+    readonly targets: readonly ZLinkClientServerTargetStatus[];
+    readonly sequence: bigint;
+    readonly observedAt: Date;
+}
+export interface ZLinkClientServerRuntime {
+    snapshot(channelName: string): ZLinkClientServerStatus;
+    observe(channelName: string, capacity?: number, signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkClientServerStatus>>;
+    isReady(channelName: string): boolean;
+}
+export interface ZLinkFanoutStatus {
+    readonly channelName: string;
+    readonly state: ZLinkTopologyState;
+    readonly isReady: boolean;
+    readonly readyPublisherCount: number;
+    readonly publishers: readonly import('./Contracts').ZLinkPeerStatus[];
+    readonly sequence: bigint;
+    readonly observedAt: Date;
+}
+export interface ZLinkFanoutRuntime {
+    snapshot(channelName: string): ZLinkFanoutStatus;
+    observe(channelName: string, capacity?: number, signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkFanoutStatus>>;
+}

package/dist/contracts/RouteMesh/RuntimeTopology.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkFrameworkTerminationReason = exports.ZLinkFrameworkTerminationOutcome = exports.ZLinkFrameworkRelocationReason = exports.ZLinkFrameworkRelocationMode = exports.ZLinkFrameworkRelocationOutcome = void 0;
+var ZLinkFrameworkRelocationOutcome;
+(function (ZLinkFrameworkRelocationOutcome) {
+    ZLinkFrameworkRelocationOutcome[ZLinkFrameworkRelocationOutcome["Relocated"] = 0] = "Relocated";
+    ZLinkFrameworkRelocationOutcome[ZLinkFrameworkRelocationOutcome["Blocked"] = 1] = "Blocked";
+})(ZLinkFrameworkRelocationOutcome || (exports.ZLinkFrameworkRelocationOutcome = ZLinkFrameworkRelocationOutcome = {}));
+var ZLinkFrameworkRelocationMode;
+(function (ZLinkFrameworkRelocationMode) {
+    ZLinkFrameworkRelocationMode[ZLinkFrameworkRelocationMode["PlannedMaintenance"] = 0] = "PlannedMaintenance";
+    ZLinkFrameworkRelocationMode[ZLinkFrameworkRelocationMode["RollingUpdate"] = 1] = "RollingUpdate";
+})(ZLinkFrameworkRelocationMode || (exports.ZLinkFrameworkRelocationMode = ZLinkFrameworkRelocationMode = {}));
+var ZLinkFrameworkRelocationReason;
+(function (ZLinkFrameworkRelocationReason) {
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["None"] = 0] = "None";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["TargetUnavailable"] = 1] = "TargetUnavailable";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["StoreUnavailable"] = 2] = "StoreUnavailable";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["RelocationDisabled"] = 3] = "RelocationDisabled";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["StateIncompatible"] = 4] = "StateIncompatible";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["DeadlineExceeded"] = 5] = "DeadlineExceeded";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["RelocationFailed"] = 6] = "RelocationFailed";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["RuntimeNotReady"] = 7] = "RuntimeNotReady";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["ManualTopologyUnsupported"] = 8] = "ManualTopologyUnsupported";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["ShutdownRequested"] = 9] = "ShutdownRequested";
+    ZLinkFrameworkRelocationReason[ZLinkFrameworkRelocationReason["OperationInProgress"] = 10] = "OperationInProgress";
+})(ZLinkFrameworkRelocationReason || (exports.ZLinkFrameworkRelocationReason = ZLinkFrameworkRelocationReason = {}));
+var ZLinkFrameworkTerminationOutcome;
+(function (ZLinkFrameworkTerminationOutcome) {
+    ZLinkFrameworkTerminationOutcome[ZLinkFrameworkTerminationOutcome["Stopped"] = 0] = "Stopped";
+    ZLinkFrameworkTerminationOutcome[ZLinkFrameworkTerminationOutcome["ForceStopped"] = 1] = "ForceStopped";
+})(ZLinkFrameworkTerminationOutcome || (exports.ZLinkFrameworkTerminationOutcome = ZLinkFrameworkTerminationOutcome = {}));
+var ZLinkFrameworkTerminationReason;
+(function (ZLinkFrameworkTerminationReason) {
+    ZLinkFrameworkTerminationReason[ZLinkFrameworkTerminationReason["None"] = 0] = "None";
+    ZLinkFrameworkTerminationReason[ZLinkFrameworkTerminationReason["DeadlineExceeded"] = 1] = "DeadlineExceeded";
+    ZLinkFrameworkTerminationReason[ZLinkFrameworkTerminationReason["TeardownFailed"] = 2] = "TeardownFailed";
+})(ZLinkFrameworkTerminationReason || (exports.ZLinkFrameworkTerminationReason = ZLinkFrameworkTerminationReason = {}));

package/dist/contracts/RouteMesh/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Contracts';
+export * from './RuntimeTopology';

package/dist/contracts/RouteMesh/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Contracts"), exports);
+__exportStar(require("./RuntimeTopology"), exports);

package/dist/contracts/Spots/Builders.d.ts

@@ -0,0 +1,10 @@
+import type { RoutingId } from '../Common';
+export interface ZLinkSpotNodeBuilder {
+    routingId(routingId: RoutingId): this;
+    setRoutingIdPrefix(prefix: string): this;
+    enableRouter(endpoint: string, routingId?: RoutingId, connect?: string | readonly string[]): this;
+    connectRouter(endpoint: string): this;
+    connectRouter(peerRid: RoutingId, endpoint: string): this;
+    enablePubSub(endpoint: string, routingId?: RoutingId, connect?: string | readonly string[]): this;
+    connectPeerPub(endpoint: string): this;
+}

package/dist/contracts/Spots/Builders.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/Spots/Contracts.d.ts

@@ -0,0 +1,110 @@
+import type { ZLinkActor } from '../Actors';
+import type { ZLinkChannelRequestCall, ZLinkPublishCall, ZLinkSendCall } from '../Channels';
+import type { RoutingId, SpotId, Type, ZLinkMessageMetadata } from '../Common';
+import type { ZLinkSpotTimerHandler } from '../Handlers';
+import type { ZLinkTimer, ZLinkTimerOptions } from '../Timers';
+import type { ZLinkEntrySpot, ZLinkInstanceSpot, ZLinkSpot, ZLinkSpotRelocationReadyCall } from './ZLinkSpot';
+export interface ZLinkActorHandlerRegistry {
+    addHandler<THandler>(handlerType: Type<THandler>, packetName?: string): this;
+}
+export interface ZLinkSpotHandlerRegistry extends ZLinkActorHandlerRegistry {
+    addPacket<THandler>(handlerType: Type<THandler>): this;
+    addSubscribe<THandler>(handlerType: Type<THandler>, channelName: string, topic: string): this;
+}
+export interface ZLinkInstanceSpotHandlerRegistry {
+    addPacket<THandler>(handlerType: Type<THandler>): this;
+}
+export interface ZLinkWorkerCall<T> {
+    timeoutMs(durationMs: number): ZLinkWorkerCall<T>;
+    submit(signal?: AbortSignal): Promise<T>;
+    yield(signal?: AbortSignal): Promise<T>;
+}
+export interface ZLinkSpotCommonContext<TSpot = ZLinkSpot> {
+    readonly meshName: string;
+    readonly spotId: SpotId;
+    readonly objectGeneration: number;
+    readonly nodeRid: RoutingId;
+    readonly outbound: ZLinkSpotOutbound;
+    addTimer<THandler extends ZLinkSpotTimerHandler<TSpot>>(name: string, periodMs: number, handlerType: Type<THandler>, options?: ZLinkTimerOptions, signal?: AbortSignal): Promise<ZLinkTimer>;
+    /**
+     * Runs synchronous CPU work on the bounded worker-thread pool.
+     * The function is serialized into an isolated worker, so it must be self-contained
+     * and return a value supported by the structured clone algorithm.
+     */
+    runCpuWorker<T>(work: (signal: AbortSignal) => T): ZLinkWorkerCall<T>;
+    /** Runs asynchronous I/O work without occupying a CPU worker thread. */
+    runIoWorker<T>(work: (signal: AbortSignal) => Promise<T>): ZLinkWorkerCall<T>;
+}
+export interface ZLinkSpotContext<TActor extends ZLinkActor = ZLinkActor, TSpot extends ZLinkSpot<TActor> = ZLinkSpot<TActor>> extends ZLinkSpotCommonContext<TSpot> {
+    readonly handlers: ZLinkSpotHandlerRegistry;
+    relocationReady(): ZLinkSpotRelocationReadyCall;
+    leaveActor(actor: TActor, signal?: AbortSignal): Promise<void>;
+    close(signal?: AbortSignal): Promise<boolean>;
+}
+export interface ZLinkInstanceSpotContext extends ZLinkSpotCommonContext<ZLinkInstanceSpot> {
+    readonly handlers: ZLinkInstanceSpotHandlerRegistry;
+    close(signal?: AbortSignal): Promise<boolean>;
+}
+export interface ZLinkEntrySpotContext<TActor extends ZLinkActor = ZLinkActor, TEntrySpot extends ZLinkEntrySpot<TActor> = ZLinkEntrySpot<TActor>> extends ZLinkSpotCommonContext<TEntrySpot> {
+    readonly handlers: ZLinkSpotHandlerRegistry;
+    destroyActor(actor: TActor, signal?: AbortSignal): Promise<void>;
+}
+export interface ZLinkSpotOutbound {
+    sendToSpot(spotId: SpotId, message: unknown): ZLinkSpotSendCall;
+    requestToSpot(spotId: SpotId, request: unknown): ZLinkSpotRequestCall;
+    publish(channelName: string, topic: string, event: unknown): ZLinkPublishCall;
+    sendToChannel(channelName: string, message: unknown): ZLinkSendCall;
+    requestToChannel(channelName: string, request: unknown): ZLinkChannelRequestCall;
+}
+export interface SpotRef {
+    readonly spotId: SpotId;
+    readonly objectGeneration: bigint;
+    readonly meshName: string;
+    readonly nodeRid: RoutingId;
+}
+export interface ZLinkSpotSendCall {
+    metadata(key: string, value: string): this;
+    metadata(metadata: ZLinkMessageMetadata): this;
+    instanceSpot(): this;
+    instanceSpot(instanceSpotType: string): this;
+    inMesh(meshName: string): this;
+    submit(signal?: AbortSignal): Promise<void>;
+}
+export interface ZLinkSpotRequestCall {
+    metadata(key: string, value: string): this;
+    metadata(metadata: ZLinkMessageMetadata): this;
+    instanceSpot(): this;
+    instanceSpot(instanceSpotType: string): this;
+    inMesh(meshName: string): this;
+    timeout(timeoutMs: number): this;
+    submit<TReply>(signal?: AbortSignal): Promise<TReply>;
+    yield<TReply>(signal?: AbortSignal): Promise<TReply>;
+}
+export declare enum ZLinkSpotCreateState {
+    Existing = "existing",
+    Created = "created",
+    Rejected = "rejected"
+}
+export interface ZLinkSpotCreateResult {
+    readonly spot: SpotRef;
+    readonly state: ZLinkSpotCreateState;
+    readonly reply?: unknown;
+}
+export interface ZLinkSpotInfo {
+    readonly spotId: SpotId;
+}
+export interface ZLinkSpotManager {
+    create(spotType: string): ZLinkSpotCreateCall;
+    getOrCreate(spotId: SpotId, spotType: string): ZLinkSpotGetOrCreateCall;
+    find(spotId: SpotId, signal?: AbortSignal): Promise<SpotRef | undefined>;
+    close(spot: SpotRef, signal?: AbortSignal): Promise<boolean>;
+}
+export interface ZLinkSpotCreateCall {
+    inMesh(meshName: string): this;
+    request(request: unknown): this;
+    timeout(timeoutMs: number): this;
+    submit(signal?: AbortSignal): Promise<ZLinkSpotCreateResult>;
+    yield(signal?: AbortSignal): Promise<ZLinkSpotCreateResult>;
+}
+export interface ZLinkSpotGetOrCreateCall extends ZLinkSpotCreateCall {
+}

package/dist/contracts/Spots/Contracts.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotCreateState = void 0;
+var ZLinkSpotCreateState;
+(function (ZLinkSpotCreateState) {
+    ZLinkSpotCreateState["Existing"] = "existing";
+    ZLinkSpotCreateState["Created"] = "created";
+    ZLinkSpotCreateState["Rejected"] = "rejected";
+})(ZLinkSpotCreateState || (exports.ZLinkSpotCreateState = ZLinkSpotCreateState = {}));

package/dist/contracts/Spots/SpotKind.d.ts

@@ -0,0 +1,8 @@
+export declare enum ZLinkSpotKind {
+    Invalid = "invalid",
+    Entry = "entry",
+    User = "user",
+    Instance = "instance"
+}
+export declare function zlinkSpotKindToWire(kind: ZLinkSpotKind): number;
+export declare function zlinkSpotKindFromWire(value: number): ZLinkSpotKind;

package/dist/contracts/Spots/SpotKind.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotKind = void 0;
+exports.zlinkSpotKindToWire = zlinkSpotKindToWire;
+exports.zlinkSpotKindFromWire = zlinkSpotKindFromWire;
+var ZLinkSpotKind;
+(function (ZLinkSpotKind) {
+    ZLinkSpotKind["Invalid"] = "invalid";
+    ZLinkSpotKind["Entry"] = "entry";
+    ZLinkSpotKind["User"] = "user";
+    ZLinkSpotKind["Instance"] = "instance";
+})(ZLinkSpotKind || (exports.ZLinkSpotKind = ZLinkSpotKind = {}));
+function zlinkSpotKindToWire(kind) {
+    switch (kind) {
+        case ZLinkSpotKind.Entry: return 1;
+        case ZLinkSpotKind.User: return 2;
+        case ZLinkSpotKind.Instance: return 3;
+        default: return 0;
+    }
+}
+function zlinkSpotKindFromWire(value) {
+    switch (value) {
+        case 1: return ZLinkSpotKind.Entry;
+        case 2: return ZLinkSpotKind.User;
+        case 3: return ZLinkSpotKind.Instance;
+        default: return ZLinkSpotKind.Invalid;
+    }
+}