@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-entry-activation.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkEntrySpotActivation = void 0;
+const contracts_1 = require("../../contracts");
+const abort_1 = require("../abort");
+const routing_id_1 = require("../routing-id");
+const actors_1 = require("../actors");
+const configuration_1 = require("../configuration");
+const workers_1 = require("../workers");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const spot_actor_packet_dispatch_1 = require("./spot-actor-packet-dispatch");
+const spot_actor_join_dispatch_1 = require("./spot-actor-join-dispatch");
+const spot_handler_registry_1 = require("./spot-handler-registry");
+const spot_outbound_1 = require("./spot-outbound");
+const spot_provider_1 = require("./spot-provider");
+const spot_serial_turn_executor_1 = require("./spot-serial-turn-executor");
+const spot_serial_executor_1 = require("./spot-serial-executor");
+const spot_closing_1 = require("./spot-closing");
+const spot_timer_1 = require("./spot-timer");
+const spot_context_1 = require("./spot-context");
+const spot_routed_spot_packet_dispatch_1 = require("./spot-routed-spot-packet-dispatch");
+const actor_handoff_1 = require("../actors/actor-handoff");
+const spot_lifecycle_metrics_1 = require("./spot-lifecycle-metrics");
+class ZLinkEntrySpotActivation {
+    options;
+    serial;
+    spotSerialExecutor;
+    timers;
+    actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
+    handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(this.actorHandlers);
+    outbound;
+    workerRuntime;
+    lifecycleMetrics;
+    packetDispatch;
+    actorPacketDispatch;
+    initialized = false;
+    disposed = false;
+    actorDispatch;
+    entrySpot;
+    context;
+    constructor(options) {
+        this.options = options;
+        this.serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(false, options.nativeSpot.routingId);
+        this.spotSerialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(this.serial, contracts_1.ZLinkUserSpotExecutionMode.PerActor, options.nativeSpot.routingId);
+        // Entry Spot lifecycle, timers and detached continuations use this serial
+        // executor. Actor packets use the target actor mailbox.
+        this.outbound = new spot_outbound_1.DefaultZLinkSpotOutbound({
+            serial: this.serial,
+            channelClient: options.channelClient,
+            spotPublisherClient: options.spotPublisherClient,
+            routedTransport: options.routedTransport,
+            spotRouterChannelIdForMesh: options.spotRouterChannelIdForMesh,
+            meshName: options.spotNodeName
+        });
+        this.timers = new spot_timer_1.ZLinkSpotTimerRegistry(options.metrics, () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        this.lifecycleMetrics = new spot_lifecycle_metrics_1.ZLinkSpotLifecycleMetrics(options.metrics);
+        this.workerRuntime = options.workerRuntime ?? new workers_1.ZLinkWorkerRuntime();
+        this.context = (0, spot_context_1.createEntrySpotContext)({
+            spotId: String(options.nativeSpot.routingId),
+            objectGeneration: toContextGeneration(entrySpotGeneration(options.nativeSpot)),
+            nodeRid: options.nodeRid,
+            handlers: this.handlers,
+            outbound: this.outbound,
+            timers: this.timers,
+            serial: this.serial,
+            getEntrySpot: () => this.entrySpot,
+            spotNodeName: options.spotNodeName,
+            providerResolver: options.providerResolver,
+            runtimeEventPublisher: options.runtimeEventPublisher,
+            workerRuntime: this.workerRuntime,
+            destroyActor: options.entryActorRuntime === undefined
+                ? undefined
+                : (nodeRid, actor, signal) => options.entryActorRuntime.destroyActor(options.nativeNode, nodeRid, actor, signal)
+        });
+        this.entrySpot = undefined;
+        (0, spot_handler_registry_1.applyEntrySpotHandlerRegistrations)(this.handlers, options.entrySpotType, {
+            actorSendHandlers: options.actorSendHandlers,
+            actorRequestHandlers: options.actorRequestHandlers,
+            packetHandlers: options.packetHandlers,
+            subscriptionHandlers: options.subscriptionHandlers
+        });
+        this.packetDispatch = new spot_routed_spot_packet_dispatch_1.ZLinkRoutedSpotPacketDispatch({
+            resolveActivation: (spotId) => spotId === this.spotId
+                ? {
+                    spotId: this.spotId,
+                    spot: this.entrySpot,
+                    serial: this.serial,
+                    handlers: this.handlers
+                }
+                : undefined,
+            providerResolver: options.providerResolver,
+            dispatchErrors: options.dispatchErrors
+        });
+        this.actorPacketDispatch = new spot_actor_packet_dispatch_1.ZLinkSpotActorPacketDispatch({
+            spot: () => this.entrySpot,
+            spotId: () => String(this.options.nativeSpot.routingId),
+            registry: this.actorHandlers,
+            resolveActor: (targetActorId) => this.options.entryActorRuntime?.resolveActor(targetActorId),
+            routeBeforeLocal: (target) => this.options.entryActorRuntime?.routePacket(target.actorId, target.parts, target.returnResponse, target.remoteBoundSessionTarget, target.fallbackActorRef),
+            onRemoteBoundSessionTarget: (targetActorId, target) => this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(targetActorId, target),
+            onDisconnectActor: (actor) => this.notifyDisconnectActor(actor),
+            actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(this.options.boundSessionRuntime),
+            actorErrorSender: this.options.boundSessionRuntime?.sendActorError.bind(this.options.boundSessionRuntime),
+            providerResolver: this.options.providerResolver,
+            messageSerializers: this.options.messageSerializers,
+            dispatchErrors: this.options.dispatchErrors
+        });
+    }
+    /**
+     * The Entry Spot serial dispatch line for Entry Spot-owned callbacks such as
+     * lifecycle, timers, request continuations and worker completions. Actor
+     * packets use the target actor mailbox instead.
+     */
+    get serialExecutor() {
+        return this.serial;
+    }
+    get nodeRid() {
+        return this.options.nodeRid;
+    }
+    get spotId() {
+        return this.options.nativeSpot.routingId;
+    }
+    dispatchSubscriptionRecord(topic, parts, sourceRid) {
+        if (this.actorDispatch === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Entry Spot '${this.options.spotNodeName}' subscription runtime is not configured.`);
+        }
+        return this.actorDispatch.dispatchSubscriptionRecord(topic, parts, sourceRid);
+    }
+    dispatchPacket(packetName, payload, context, returnResponse) {
+        return returnResponse
+            ? this.packetDispatch.request(this.spotId, packetName, payload, context)
+            : this.packetDispatch.send(this.spotId, packetName, payload, context);
+    }
+    dispatchPacketEncoded(packetName, decodePayload, context, returnResponse) {
+        return returnResponse
+            ? this.packetDispatch.requestEncoded(this.spotId, packetName, decodePayload, context)
+            : this.packetDispatch.sendEncoded(this.spotId, packetName, decodePayload, context);
+    }
+    async create() {
+        const entrySpot = await (0, spot_provider_1.createProviderInstance)(this.options.entrySpotType, this.options.providerResolver, this.context);
+        this.entrySpot = entrySpot;
+        Object.defineProperty(this.entrySpot, 'context', {
+            configurable: true,
+            enumerable: false,
+            value: this.context
+        });
+        await (0, spot_timer_1.addEntrySpotTimerRegistrations)(this.timers, this.options.entrySpotType, this.entrySpot, this.serial, { timerHandlers: this.options.timerHandlers }, {
+            providerResolver: this.options.providerResolver,
+            spotNodeName: this.options.spotNodeName,
+            spotId: this.context.spotId,
+            runtimeEventPublisher: this.options.runtimeEventPublisher
+        });
+    }
+    async configure() {
+        await this.entrySpot.configure?.();
+    }
+    async initialize() {
+        await this.serial.execute(() => this.entrySpot.onInitialize?.());
+        this.attachActorJoinDispatch();
+        this.initialized = true;
+        this.lifecycleMetrics.opened('entry');
+    }
+    async dispose(deadline) {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const errors = [];
+        const cleanup = async (operation) => {
+            try {
+                await operation();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        };
+        if (this.initialized) {
+            await cleanup(() => this.serial.execute(() => (0, spot_closing_1.invokeSpotClosing)(this.entrySpot.onClosing?.bind(this.entrySpot), contracts_1.ZLinkSpotCloseReason.HostShutdown, deadline)));
+        }
+        await cleanup(() => this.actorDispatch?.dispose());
+        await cleanup(() => this.timers.dispose());
+        await cleanup(() => this.spotSerialExecutor.close());
+        await cleanup(() => (0, handler_instance_scope_1.disposeLifecycleHandlers)(this.entrySpot));
+        await cleanup(() => this.options.nativeSpot.dispose());
+        if (this.initialized) {
+            this.lifecycleMetrics.closed('entry');
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, 'Entry Spot cleanup failed.');
+    }
+    notifyCreateActor(actor, createRequest, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        return this.serial.execute(async () => await this.entrySpot.onCreateActor?.(actor, createRequest)
+            ?? { accepted: true });
+    }
+    notifyJoinActor(actor, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        return this.serial.execute(() => notifyEntryActorJoined(this.entrySpot, actor));
+    }
+    /**
+     * Completes the stateful MeshNode return-to-Entry-Spot path after Core has
+     * accepted the membership reply. The native receive path performs the same
+     * actor-manager transaction in its admission callback.
+     */
+    async commitServiceActorJoin(actor, handoffBacklog = [], signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const notifyJoined = () => this.notifyJoinActor(actor, signal);
+        if (this.options.entryActorRuntime === undefined) {
+            await notifyJoined();
+        }
+        else {
+            await this.options.entryActorRuntime.commitActorTransaction(actor, notifyJoined);
+        }
+        if (handoffBacklog.length > 0) {
+            await this.replayActorBacklog(actor, handoffBacklog);
+        }
+    }
+    /**
+     * Entry Spot membership does not have an application admission callback.
+     * The shared core round-trip therefore accepts a valid returning Actor and
+     * runs only the post-commit membership notification.
+     */
+    attachActorJoinDispatch() {
+        const dispatch = new spot_actor_join_dispatch_1.ZLinkSpotActorJoinDispatch({
+            nativeSpot: this.options.nativeSpot,
+            createReceived: this.options.createReceived,
+            createTopicMessage: this.options.createTopicMessage,
+            serial: this.serial,
+            actors: {
+                resolveActor: (actorId) => this.options.entryActorRuntime?.resolveActor(actorId),
+                getTarget: () => this.entrySpot,
+                defaultAccept: true,
+                transfer: this.options.actorTransferRuntime === undefined ? { kind: 'disabled' } : {
+                    kind: 'enabled',
+                    runtime: this.options.actorTransferRuntime
+                },
+                commitNativeActor: (actor) => this.commitEntryActorTransaction(actor),
+                commitTransferredActor: async (actor, backlog) => {
+                    await this.commitEntryActorTransaction(actor);
+                    return await this.replayActorBacklog(actor, backlog);
+                }
+            },
+            packets: {
+                handle: (delivery) => this.dispatchActorPacket(delivery),
+                bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid, declaredTarget) => {
+                    if ((0, routing_id_1.routingIdsEqual)(sourceNodeRid, this.options.nativeNode.routingId)) {
+                        return;
+                    }
+                    const target = declaredTarget
+                        ?? this.options.boundSessionRuntime?.resolveRemoteBoundSessionTarget(sourceNodeRid, sourceSessionRid);
+                    if (target !== undefined) {
+                        this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(actor.actorId, {
+                            ...target,
+                            sessionNodeRid: sourceNodeRid,
+                            sessionRid: sourceSessionRid
+                        });
+                    }
+                    this.options.nativeNode.bindRemoteActorSession(actor, sourceNodeRid, sourceSessionRid);
+                },
+                replyNoBind: (info, parts, result) => this.replyActorNoBind(info, parts, result)
+            },
+            boundSessionRuntime: this.options.boundSessionRuntime,
+            messageSerializers: this.options.messageSerializers,
+            providerResolver: this.options.providerResolver,
+            dispatchErrors: this.options.dispatchErrors,
+            detachedTaskRunner: this.options.detachedTaskRunner
+        });
+        dispatch.configureSubscriptions(this.handlers.snapshot());
+        dispatch.attach();
+        this.actorDispatch = dispatch;
+    }
+    async commitEntryActorTransaction(actor) {
+        const notifyJoined = () => this.serial.execute(() => notifyEntryActorJoined(this.entrySpot, actor));
+        const runtime = this.options.entryActorRuntime;
+        if (runtime === undefined) {
+            await notifyJoined();
+            return;
+        }
+        await runtime.commitActorTransaction(actor, notifyJoined);
+    }
+    notifyLeaveActor(actor, signal, _actorRef, _membershipEpoch) {
+        (0, abort_1.throwIfAborted)(signal);
+        return this.serial.execute(() => this.entrySpot.onLeaveActor(actor));
+    }
+    notifyDisconnectActor(actor, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        return this.serial.execute(() => this.entrySpot.onDisconnectActor?.(actor));
+    }
+    async dispatchActorPacket(delivery) {
+        const { actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, messageFollowOrigin } = delivery;
+        const handoff = this.options.actorHandoffRuntime?.capture(actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin, (replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef) => this.spotSerialExecutor.executeActor(actorId, () => this.dispatchActorPacketInsideMailbox({
+            actorId,
+            parts: replayedParts,
+            returnResponse: replayReturnResponse,
+            remoteBoundSessionTarget: replayRemoteBoundSessionTarget,
+            fallbackActorRef: replayFallbackActorRef
+        })));
+        if (handoff !== undefined)
+            return await handoff;
+        return this.spotSerialExecutor.executeActor(actorId, () => this.dispatchActorPacketInsideMailbox(delivery));
+    }
+    async replayActorBacklog(actor, backlog) {
+        return await (0, actor_handoff_1.replayActorHandoffBacklog)(backlog, (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.spotSerialExecutor.executeActor(actor.context.actorId, () => this.dispatchActorPacketInsideMailbox({
+            actorId: actor.context.actorId,
+            parts,
+            returnResponse,
+            remoteBoundSessionTarget,
+            fallbackActorRef
+        })), (index) => this.options.runtimeEventPublisher?.publish({
+            sourceName: 'zlink.framework.actor-handoff',
+            timestamp: new Date(),
+            marker: 'backlog_enqueued',
+            actorId: actor.context.actorId,
+            index
+        }));
+    }
+    async dispatchActorPacketInsideMailbox(delivery) {
+        return this.actorPacketDispatch.dispatchDelivery(delivery);
+    }
+    replyActorNoBind(info, parts, result) {
+        this.options.nativeNode.replyActorNoBind(info, parts, result);
+    }
+}
+exports.ZLinkEntrySpotActivation = ZLinkEntrySpotActivation;
+function notifyEntryActorJoined(entrySpot, actor) {
+    const callback = entrySpot.onJoinedActor;
+    return callback === undefined
+        ? Promise.resolve()
+        : callback.call(entrySpot, actor);
+}
+function toContextGeneration(generation) {
+    if (generation < 0n || generation > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new configuration_1.ZLinkConfigurationException(`Entry Spot object generation '${generation}' cannot be represented by the Node.js public context.`);
+    }
+    return Number(generation);
+}
+function entrySpotGeneration(spot) {
+    return spot.lifecycleGeneration
+        ?? spot.status?.().lifecycleGeneration
+        ?? 0n;
+}

package/dist/runtime/spots/spot-handle.d.ts

@@ -0,0 +1,28 @@
+import type { RoutingId, ZLinkFrameworkRuntimeState, ZLinkSpotKind } from '../../contracts';
+declare const spotHandleBrand: unique symbol;
+export interface SpotHandle {
+    readonly meshName: string;
+    readonly spotId: RoutingId;
+    readonly [spotHandleBrand]: never;
+}
+export interface ZLinkSpotHandleResolver {
+    resolveSpotHandle(meshName: string, spotId: RoutingId, signal?: AbortSignal): Promise<SpotHandle | undefined>;
+}
+export interface ZLinkActorSpotHandleResolver {
+    resolveActorSpotHandle(meshName: string, actorId: string, signal?: AbortSignal): Promise<SpotHandle | undefined>;
+}
+export interface ResolvedSpotHandle {
+    readonly meshName: string;
+    readonly nodeRid: RoutingId;
+    readonly spotId: RoutingId;
+    readonly spotKind?: ZLinkSpotKind;
+    readonly spotGeneration?: bigint;
+    /** Current state of the owning MeshNode, when the Location Store provides it. */
+    readonly targetNodeState?: ZLinkFrameworkRuntimeState;
+}
+type SpotHandleResolver = (signal?: AbortSignal) => Promise<ResolvedSpotHandle | undefined>;
+export declare function createSpotHandle(spotId: string, initial: ResolvedSpotHandle, refresh: SpotHandleResolver): SpotHandle;
+export declare function createSpotHandle(spotId: string, refresh: SpotHandleResolver): SpotHandle;
+export declare function resolveSpotHandle(handle: SpotHandle, signal?: AbortSignal): Promise<ResolvedSpotHandle | undefined>;
+export declare function refreshSpotHandle(handle: SpotHandle, signal?: AbortSignal): Promise<ResolvedSpotHandle | undefined>;
+export {};

package/dist/runtime/spots/spot-handle.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpotHandle = createSpotHandle;
+exports.resolveSpotHandle = resolveSpotHandle;
+exports.refreshSpotHandle = refreshSpotHandle;
+const handleStates = new WeakMap();
+function createSpotHandle(spotId, initialOrRefresh, refresh) {
+    const initial = typeof initialOrRefresh === 'function' ? undefined : initialOrRefresh;
+    const handle = Object.freeze({
+        meshName: initial?.meshName ?? '',
+        spotId
+    });
+    handleStates.set(handle, typeof initialOrRefresh === 'function'
+        ? { current: undefined, refresh: initialOrRefresh }
+        : { current: initialOrRefresh, refresh: refresh });
+    return handle;
+}
+async function resolveSpotHandle(handle, signal) {
+    const state = requireHandleState(handle);
+    return state.current ?? await refreshSpotHandle(handle, signal);
+}
+async function refreshSpotHandle(handle, signal) {
+    const state = requireHandleState(handle);
+    state.refreshing ??= state.refresh(signal).then((resolved) => {
+        state.current = resolved;
+        return resolved;
+    }).finally(() => {
+        state.refreshing = undefined;
+    });
+    return await state.refreshing;
+}
+function requireHandleState(handle) {
+    const state = handleStates.get(handle);
+    if (state === undefined) {
+        throw new TypeError('SpotHandle was not created by this framework runtime.');
+    }
+    return state;
+}

package/dist/runtime/spots/spot-handler-registry.d.ts

@@ -0,0 +1,52 @@
+import type { Type, ZLinkActor, ZLinkEntrySpot, ZLinkInstanceSpotHandlerRegistry, ZLinkSpot, ZLinkSpotHandlerRegistry } from '../../contracts';
+import type { ZLinkEntrySpotActorRequestHandlerRegistration, ZLinkEntrySpotActorSendHandlerRegistration, ZLinkEntrySpotPacketHandlerRegistration, ZLinkEntrySpotSubscriptionHandlerRegistration, ZLinkSpotActorRequestHandlerRegistration, ZLinkSpotActorSendHandlerRegistration, ZLinkSpotPacketHandlerRegistration, ZLinkSpotSubscriptionHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
+import { ZLinkActorPacketKind, ZLinkSpotActorHandlerRegistryRuntime } from '../actors';
+export interface ZLinkSpotHandlerRegistration {
+    readonly kind: 'packet' | 'subscribe' | 'actorSend' | 'actorRequest' | 'spotHandler';
+    readonly handlerType: Type;
+    readonly packetName?: string;
+    readonly channelName?: string;
+    readonly topic?: string;
+    readonly actorType?: Type<ZLinkActor>;
+}
+export declare class DefaultZLinkSpotHandlerRegistry<TActor extends ZLinkActor = ZLinkActor> implements ZLinkSpotHandlerRegistry {
+    private readonly actorHandlers?;
+    private readonly entries;
+    constructor(actorHandlers?: ZLinkSpotActorHandlerRegistryRuntime | undefined);
+    addHandler<THandler>(handlerType: Type<THandler>, packetName?: string): this;
+    addActorPacket<THandler, TRegisteredActor extends ZLinkActor>(handlerType: Type<THandler>, actorType: Type<TRegisteredActor>): this;
+    addPacket(handlerType: Type, packetName?: string): this;
+    packet(packetName: string, handlerType: Type): this;
+    addActorPacketRegistration(kind: ZLinkActorPacketKind, handlerType: Type, actorType: Type<TActor>, packetName: string): this;
+    actorSend(packetName: string, handlerType: Type, actorType?: Type<TActor>): this;
+    actorRequest(packetName: string, handlerType: Type, actorType?: Type<TActor>): this;
+    addSubscribe(handlerType: Type, channelName: string, topic: string): this;
+    subscribe(channelName: string, topic: string, handlerType: Type): this;
+    addSpotHandler(handlerType: Type): this;
+    snapshot(): readonly ZLinkSpotHandlerRegistration[];
+}
+/**
+ * Exposes only the actor-free handler surface permitted for Instance Spots while
+ * retaining the common immutable registration snapshot used by dispatch.
+ */
+export declare class DefaultZLinkInstanceSpotHandlerRegistry implements ZLinkInstanceSpotHandlerRegistry {
+    private readonly registrations;
+    constructor(registrations: DefaultZLinkSpotHandlerRegistry);
+    addPacket<THandler>(handlerType: Type<THandler>): this;
+    snapshot(): readonly ZLinkSpotHandlerRegistration[];
+}
+interface ZLinkEntrySpotHandlerRegistrationSet {
+    readonly actorSendHandlers?: readonly ZLinkEntrySpotActorSendHandlerRegistration[];
+    readonly actorRequestHandlers?: readonly ZLinkEntrySpotActorRequestHandlerRegistration[];
+    readonly packetHandlers?: readonly ZLinkEntrySpotPacketHandlerRegistration[];
+    readonly subscriptionHandlers?: readonly ZLinkEntrySpotSubscriptionHandlerRegistration[];
+}
+interface ZLinkUserSpotHandlerRegistrationSet {
+    readonly actorSendHandlers?: readonly ZLinkSpotActorSendHandlerRegistration[];
+    readonly actorRequestHandlers?: readonly ZLinkSpotActorRequestHandlerRegistration[];
+    readonly packetHandlers?: readonly ZLinkSpotPacketHandlerRegistration[];
+    readonly subscriptionHandlers?: readonly ZLinkSpotSubscriptionHandlerRegistration[];
+}
+export declare function applyEntrySpotHandlerRegistrations(registry: DefaultZLinkSpotHandlerRegistry, entrySpotType: Type<ZLinkEntrySpot>, registrations: ZLinkEntrySpotHandlerRegistrationSet): void;
+export declare function applySpotHandlerRegistrations(registry: DefaultZLinkSpotHandlerRegistry, spotType: Type<ZLinkSpot>, registrations: ZLinkUserSpotHandlerRegistrationSet): void;
+export {};

package/dist/runtime/spots/spot-handler-registry.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkInstanceSpotHandlerRegistry = exports.DefaultZLinkSpotHandlerRegistry = void 0;
+exports.applyEntrySpotHandlerRegistrations = applyEntrySpotHandlerRegistrations;
+exports.applySpotHandlerRegistrations = applySpotHandlerRegistrations;
+const configuration_1 = require("../configuration");
+const actors_1 = require("../actors");
+const Attributes_1 = require("../../contracts/Handlers/Attributes");
+class DefaultZLinkSpotHandlerRegistry {
+    actorHandlers;
+    entries = [];
+    constructor(actorHandlers) {
+        this.actorHandlers = actorHandlers;
+    }
+    addHandler(handlerType, packetName) {
+        const metadata = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'spotActorSend' || entry.kind === 'spotActorRequest');
+        const resolvedPacketName = packetName ?? metadata?.packetName;
+        if (metadata === undefined || resolvedPacketName === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor packet handler '${handlerType.name}' must declare a packet name.`);
+        }
+        return this.addActorPacketRegistration(metadata.kind === 'spotActorSend'
+            ? actors_1.ZLinkActorPacketKind.Send
+            : actors_1.ZLinkActorPacketKind.Request, handlerType, Object, resolvedPacketName);
+    }
+    addActorPacket(handlerType, actorType) {
+        const metadata = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'spotActorSend' || entry.kind === 'spotActorRequest');
+        if (metadata?.packetName === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor packet handler '${handlerType.name}' must declare a packet name.`);
+        }
+        return this.addActorPacketRegistration(metadata.kind === 'spotActorSend' ? actors_1.ZLinkActorPacketKind.Send : actors_1.ZLinkActorPacketKind.Request, handlerType, actorType, metadata.packetName);
+    }
+    addPacket(handlerType, packetName) {
+        const declared = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType)
+            .find((entry) => entry.kind === 'packet')?.packetName;
+        this.entries.push({ kind: 'packet', handlerType, packetName: packetName ?? declared ?? handlerType.name });
+        return this;
+    }
+    packet(packetName, handlerType) {
+        return this.addPacket(handlerType, packetName);
+    }
+    addActorPacketRegistration(kind, handlerType, actorType, packetName) {
+        this.entries.push({
+            kind: kind === actors_1.ZLinkActorPacketKind.Send ? 'actorSend' : 'actorRequest',
+            handlerType,
+            actorType,
+            packetName
+        });
+        this.actorHandlers?.addPacket({
+            kind,
+            packetName,
+            actorType,
+            handlerType
+        });
+        return this;
+    }
+    actorSend(packetName, handlerType, actorType = Object) {
+        return this.addActorPacketRegistration(actors_1.ZLinkActorPacketKind.Send, handlerType, actorType, packetName);
+    }
+    actorRequest(packetName, handlerType, actorType = Object) {
+        return this.addActorPacketRegistration(actors_1.ZLinkActorPacketKind.Request, handlerType, actorType, packetName);
+    }
+    addSubscribe(handlerType, channelName, topic) {
+        if (channelName.trim().length === 0) {
+            throw new configuration_1.ZLinkConfigurationException('SPOT subscribe channel name must not be empty.');
+        }
+        if (topic.trim().length === 0) {
+            throw new configuration_1.ZLinkConfigurationException('SPOT subscribe topic must not be empty.');
+        }
+        if (this.entries.some((entry) => entry.kind === 'subscribe'
+            && entry.handlerType === handlerType
+            && entry.channelName === channelName
+            && entry.topic === topic)) {
+            return this;
+        }
+        this.entries.push({ kind: 'subscribe', handlerType, channelName, topic });
+        return this;
+    }
+    subscribe(channelName, topic, handlerType) {
+        return this.addSubscribe(handlerType, channelName, topic);
+    }
+    addSpotHandler(handlerType) {
+        this.entries.push({ kind: 'spotHandler', handlerType });
+        return this;
+    }
+    snapshot() {
+        return [...this.entries];
+    }
+}
+exports.DefaultZLinkSpotHandlerRegistry = DefaultZLinkSpotHandlerRegistry;
+/**
+ * Exposes only the actor-free handler surface permitted for Instance Spots while
+ * retaining the common immutable registration snapshot used by dispatch.
+ */
+class DefaultZLinkInstanceSpotHandlerRegistry {
+    registrations;
+    constructor(registrations) {
+        this.registrations = registrations;
+    }
+    addPacket(handlerType) {
+        this.registrations.addPacket(handlerType);
+        return this;
+    }
+    snapshot() {
+        return this.registrations.snapshot();
+    }
+}
+exports.DefaultZLinkInstanceSpotHandlerRegistry = DefaultZLinkInstanceSpotHandlerRegistry;
+function applyEntrySpotHandlerRegistrations(registry, entrySpotType, registrations) {
+    for (const handler of registrations.actorSendHandlers ?? []) {
+        if (handler.entrySpotType === entrySpotType) {
+            registry.addActorPacketRegistration(actors_1.ZLinkActorPacketKind.Send, handler.handlerType, handler.actorType, handler.packetName);
+        }
+    }
+    for (const handler of registrations.actorRequestHandlers ?? []) {
+        if (handler.entrySpotType === entrySpotType) {
+            registry.addActorPacketRegistration(actors_1.ZLinkActorPacketKind.Request, handler.handlerType, handler.actorType, handler.packetName);
+        }
+    }
+    for (const handler of registrations.packetHandlers ?? []) {
+        if (handler.entrySpotType === entrySpotType) {
+            registry.addPacket(handler.handlerType, handler.packetName);
+        }
+    }
+    for (const handler of registrations.subscriptionHandlers ?? []) {
+        if (handler.entrySpotType === entrySpotType) {
+            registry.addSubscribe(handler.handlerType, handler.channelName, handler.topic);
+        }
+    }
+}
+function applySpotHandlerRegistrations(registry, spotType, registrations) {
+    for (const handler of registrations.actorSendHandlers ?? []) {
+        if (isSpotImplementation(handler.spotType, spotType)) {
+            registry.addActorPacketRegistration(actors_1.ZLinkActorPacketKind.Send, handler.handlerType, handler.actorType, handler.packetName);
+        }
+    }
+    for (const handler of registrations.actorRequestHandlers ?? []) {
+        if (isSpotImplementation(handler.spotType, spotType)) {
+            registry.addActorPacketRegistration(actors_1.ZLinkActorPacketKind.Request, handler.handlerType, handler.actorType, handler.packetName);
+        }
+    }
+    for (const handler of registrations.packetHandlers ?? []) {
+        if (isSpotImplementation(handler.spotType, spotType)) {
+            registry.addPacket(handler.handlerType, handler.packetName);
+        }
+    }
+    for (const handler of registrations.subscriptionHandlers ?? []) {
+        if (isSpotImplementation(handler.spotType, spotType)) {
+            registry.addSubscribe(handler.handlerType, handler.channelName, handler.topic);
+        }
+    }
+}
+function isSpotImplementation(registeredType, implementation) {
+    return registeredType === implementation
+        || implementation.prototype instanceof registeredType;
+}

package/dist/runtime/spots/spot-lifecycle-metrics.d.ts

@@ -0,0 +1,8 @@
+import type { ZLinkRuntimeMetrics } from '../diagnostics';
+export type ZLinkSpotMetricKind = 'entry' | 'user';
+export declare class ZLinkSpotLifecycleMetrics {
+    private readonly metrics?;
+    constructor(metrics?: ZLinkRuntimeMetrics | undefined);
+    opened(kind: ZLinkSpotMetricKind): void;
+    closed(kind: ZLinkSpotMetricKind): void;
+}

package/dist/runtime/spots/spot-lifecycle-metrics.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotLifecycleMetrics = void 0;
+class ZLinkSpotLifecycleMetrics {
+    metrics;
+    constructor(metrics) {
+        this.metrics = metrics;
+    }
+    opened(kind) {
+        this.metrics?.change('zlink.spot.count', 1, { kind });
+    }
+    closed(kind) {
+        this.metrics?.change('zlink.spot.count', -1, { kind });
+    }
+}
+exports.ZLinkSpotLifecycleMetrics = ZLinkSpotLifecycleMetrics;

package/dist/runtime/spots/spot-location-claim.d.ts

@@ -0,0 +1,25 @@
+import type { RoutingId } from '../../contracts';
+import type { ZLinkLocationLifecycle } from '../locations';
+interface ZLinkSpotLocationClaimOptions {
+    readonly lifecycle?: ZLinkLocationLifecycle;
+    readonly nodeRid?: RoutingId;
+    readonly nodeRidProvider?: (meshName: string) => RoutingId | undefined;
+    readonly nodeGenerationProvider?: (meshName: string) => bigint | undefined;
+}
+export type ZLinkSpotLocationClaimResult = {
+    readonly claimed: true;
+    readonly meshName: string;
+} | {
+    readonly claimed: false;
+    readonly state: 'existing';
+    readonly meshName: string;
+};
+export declare class ZLinkSpotLocationClaim {
+    private readonly options;
+    constructor(options: ZLinkSpotLocationClaimOptions);
+    claimUserSpot(meshName: string, spotId: RoutingId, spotTypeName: string, spotGeneration: bigint): Promise<ZLinkSpotLocationClaimResult>;
+    get enabled(): boolean;
+    release(meshName: string, spotId: RoutingId): Promise<void>;
+    private requireNodeRid;
+}
+export {};