@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-node-runtime-manager.js

@@ -0,0 +1,1111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotNodeRuntimeManager = void 0;
+exports.createFrameworkEntrySpotId = createFrameworkEntrySpotId;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const node_crypto_1 = require("node:crypto");
+const Locations_1 = require("../../contracts/Locations");
+const contracts_1 = require("../../contracts");
+const submission_result_1 = require("../messaging/submission-result");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const runtime_values_1 = require("../backend/runtime-values");
+const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
+const configuration_1 = require("../configuration");
+const mesh_dispatch_pump_1 = require("../backend/mesh-dispatch-pump");
+const execution_1 = require("../execution");
+const flow_context_1 = require("../diagnostics/flow-context");
+const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const channel_envelope_1 = require("../channels/channel-envelope");
+const locations_1 = require("../locations");
+const spot_entry_activation_1 = require("./spot-entry-activation");
+const spot_node_autoconnect_1 = require("./spot-node-autoconnect");
+const routing_id_1 = require("../routing-id");
+const abort_1 = require("../abort");
+const application_job_queue_1 = require("../host/application-job-queue");
+const ZLINK_SEND_DONT_WAIT = 1;
+//  Shared default for the dominant no-metadata call; avoids a Map allocation
+//  per outbound operation.
+const EMPTY_SPOT_METADATA = new Map();
+class ZLinkSpotNodeRuntimeManager {
+    options;
+    meshNodes = new Map();
+    meshPumps = new Map();
+    meshCompletions = new Map();
+    entryActivations = new Map();
+    entryActivationStarts = new Map();
+    publishers = new Map();
+    activePublishes = new Set();
+    publishSlotWaiters = new Map();
+    disposed = false;
+    autoConnectLoops = [];
+    publishedMeshNodeDescriptors = new Map();
+    // Keep the revision source separate from the cached Store row. A new owner
+    // lease may require a NewClaim against an empty Store, while peers still
+    // retain the monotonic revision from this MeshNode lifecycle.
+    descriptorRevisionByMesh = new Map();
+    publishedOwnerToken;
+    runtimePlacementWeights = new Map();
+    runtimeChannelWeights = new Map();
+    entrySpotIds = new Map();
+    runtimeWeightPublication = Promise.resolve();
+    statePublication = Promise.resolve();
+    locationAutoConnect;
+    applicationJobQueue;
+    constructor(options) {
+        this.options = options;
+        this.applicationJobQueue = options.applicationJobQueue
+            ?? new application_job_queue_1.ApplicationJobQueue((0, application_job_queue_1.resolveApplicationJobQueueConfiguration)());
+    }
+    createReceived() {
+        return this.options.backendAdapterFactory.createReceived();
+    }
+    createTopicMessage() {
+        return this.options.backendAdapterFactory.createTopicMessage();
+    }
+    configureLocationAutoConnect(runtime, stores, options, events) {
+        this.locationAutoConnect = (0, spot_node_autoconnect_1.createSpotNodeLocationAutoConnectContext)(runtime, stores, options, events);
+    }
+    async startLocationAutoConnect(signal) {
+        const location = this.locationAutoConnect;
+        if (location === undefined || this.autoConnectLoops.length > 0) {
+            return;
+        }
+        try {
+            for (const [spotNodeName, spotNode] of this.options.registration.spotNodes.entries()) {
+                const node = this.meshNodes.get(spotNodeName);
+                if (node === undefined) {
+                    continue;
+                }
+                const capability = (0, spot_node_autoconnect_1.spotNodeAutoConnectCapability)(spotNodeName, spotNode, node);
+                if (capability === undefined)
+                    continue;
+                const reconciler = new locations_1.ZLinkAutoConnectReconciler({
+                    local: capability.local,
+                    localRow: capability.localRow,
+                    runtime: location.runtime,
+                    peerResolver: location.resolver,
+                    executor: capability.executor,
+                    events: location.events,
+                    options: location.options
+                });
+                const loop = new locations_1.ZLinkAutoConnectLoop({
+                    reconciler,
+                    local: capability.local,
+                    options: location.options,
+                    changeStampStore: location.changeStampStore,
+                    leaseTracker: location.leaseTracker
+                });
+                await loop.start(signal);
+                this.autoConnectLoops.push(loop);
+            }
+        }
+        catch (error) {
+            await Promise.allSettled(this.autoConnectLoops.map((loop) => loop.stop(signal)));
+            this.autoConnectLoops.length = 0;
+            throw error;
+        }
+    }
+    /**
+     * Fences transport connections that were created under an owner token which
+     * is no longer valid. The loops are discarded so a later owner renewal can
+     * build them again with the current lifecycle descriptor.
+     */
+    async fenceLocationAutoConnect() {
+        const loops = [...this.autoConnectLoops];
+        this.autoConnectLoops.length = 0;
+        await Promise.allSettled(loops.map((loop) => loop.prepareTransportShutdown()));
+        for (const node of this.meshNodes.values()) {
+            for (const peer of node.peers()) {
+                if (peer.routingId !== null) {
+                    node.disconnectPeer(peer.routingId, peer.lifecycleGeneration);
+                }
+            }
+        }
+    }
+    async start() {
+        if (this.options.registration.spotNodes.size === 0) {
+            return;
+        }
+        const meshAdapter = this.options.backendAdapterFactory.createMeshAdapter();
+        for (const [spotNodeName, spotNode] of this.options.registration.spotNodes.entries()) {
+            const routingId = spotNode.routingId
+                ?? spotNode.router?.routingId
+                ?? spotNode.pubSub?.routingId
+                ?? `${spotNode.routingIdPrefix ?? spotNodeName}-${(0, node_crypto_1.randomUUID)()}`;
+            const bind = spotNode.router?.bind;
+            if (bind === undefined) {
+                throw new configuration_1.ZLinkConfigurationException(`MeshNode '${spotNodeName}' requires a routing id and ROUTER bind endpoint.`);
+            }
+            const node = meshAdapter.createMeshNode(this.options.context, {
+                meshName: spotNodeName,
+                routingId,
+                applicationJobQueue: this.applicationJobQueue,
+                applicationJobReceiveFlowFailureSink: this.options.applicationJobReceiveFlowFailureSink,
+                peerAdmissionSealed: () => this.options.peerAdmissionSealed?.(spotNodeName) ?? false
+            });
+            node.setMailboxRecordDroppedHandler?.((record) => this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel,
+                messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget,
+                action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                channelName: spotNodeName,
+                error: new Error(`MeshNode '${spotNodeName}' no longer accepts ${record.kind} for '${record.owner}'.`)
+            }));
+            node.setProtocolErrorHandler?.((record) => this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel,
+                messageKind: record.request
+                    ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request
+                    : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame,
+                action: record.replied
+                    ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError
+                    : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                channelName: spotNodeName,
+                sourceRid: record.sourceNodeRid,
+                error: new Error(`MeshNode '${spotNodeName}' rejected an invalid service wire record from '${record.sourceNodeRid}'`
+                    + (record.command === undefined ? '.' : ` (command ${record.command}).`))
+            }));
+            let pump;
+            const completions = new mesh_completion_table_1.ZLinkMeshCompletionTable();
+            try {
+                node.setBind(bind);
+                if (spotNode.router?.advertiseHost !== undefined) {
+                    node.setAdvertiseHost(spotNode.router.advertiseHost);
+                }
+                const stableTypes = [
+                    ...Object.keys(spotNode.spotFactoryRegistrations ?? {}),
+                    ...Object.keys(spotNode.instanceSpotFactoryRegistrations ?? {}),
+                    ...Object.keys(spotNode.actorFactoryRegistrations ?? {})
+                ];
+                const instanceSpotTypes = Object.keys(spotNode.instanceSpotFactoryRegistrations ?? {});
+                const hasLegacyObjectFactories = (spotNode.spotFactories?.length ?? 0) > 0
+                    || Object.keys(spotNode.instanceSpotFactories ?? {}).length > 0
+                    || (spotNode.actorFactories instanceof Map
+                        ? spotNode.actorFactories.size
+                        : Object.keys(spotNode.actorFactories ?? {}).length) > 0;
+                node.configureObjectPlacement({
+                    role: spotNode.objectRole
+                        ?? (hasLegacyObjectFactories ? 'server' : 'none'),
+                    placementWeight: spotNode.placementWeight ?? 100,
+                    activeCapacityLimit: aggregatePlacementCapacity(spotNode.actorLimit ?? 0, spotNode.spotLimit ?? 0),
+                    pendingCapacityLimit: spotNode.activationConcurrencyLimit ?? 128,
+                    objectCapabilities: [
+                        ...stableTypes.map(type => `object-type:${type}`),
+                        ...instanceSpotTypes.map(type => `instance-spot-type:${type}`)
+                    ],
+                    ...(this.options.registration.maintenanceWave === undefined
+                        ? {}
+                        : { maintenanceWave: this.options.registration.maintenanceWave })
+                });
+                for (const [channelName, channel] of this.serverChannels(spotNodeName)) {
+                    node.addChannelName(channelName);
+                    if (channel.weight !== undefined) {
+                        await node.setChannelWeight(channelName, channel.weight);
+                    }
+                }
+                node.setMessageFollowHandler?.((record) => this.options.messageFollowReceiver?.(record));
+                node.start();
+                this.publishers.set(spotNodeName, node.createPublisher());
+                for (const endpoint of spotNode.router?.manualConnections ?? []) {
+                    await node.connectPeer({ endpoint });
+                }
+                for (const peer of spotNode.router?.manualPeerConnections ?? []) {
+                    await node.connectPeer({
+                        endpoint: peer.endpoint,
+                        expectedRid: (0, routing_id_1.toBackendRoutingId)(peer.peerRid)
+                    });
+                }
+                pump = new mesh_dispatch_pump_1.ZLinkMeshDispatchPump(node, {
+                    applicationJobQueue: this.applicationJobQueue,
+                    dispatch: (owner, record) => this.dispatchMeshRecord(spotNodeName, owner, record),
+                    reportError: (error, context) => this.options.dispatchErrors?.report({
+                        surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Node,
+                        messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Control,
+                        reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+                        action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                        meshName: spotNodeName,
+                        packetName: context?.packetName,
+                        sourceRid: context?.sourceNodeRid,
+                        commandId: context?.commandId,
+                        error
+                    })
+                });
+                pump.start();
+                this.meshNodes.set(spotNodeName, node);
+                this.meshPumps.set(spotNodeName, pump);
+                this.meshCompletions.set(spotNodeName, completions);
+            }
+            catch (error) {
+                this.entryActivations.delete(spotNodeName);
+                this.publishers.get(spotNodeName)?.close();
+                this.publishers.delete(spotNodeName);
+                this.meshCompletions.delete(spotNodeName);
+                this.meshPumps.delete(spotNodeName);
+                this.meshNodes.delete(spotNodeName);
+                completions.dispose(error);
+                await pump?.dispose();
+                node.close();
+                throw error;
+            }
+        }
+    }
+    async publishMeshNodeState(state, signal, selectedMeshName) {
+        const previous = this.statePublication;
+        let release;
+        this.statePublication = new Promise((resolve) => { release = resolve; });
+        await previous;
+        try {
+            await this.publishMeshNodeStateCore(state, signal, selectedMeshName);
+        }
+        finally {
+            release();
+        }
+    }
+    async publishMeshNodeStateCore(state, signal, selectedMeshName) {
+        const location = this.locationAutoConnect;
+        const owner = location?.runtime.currentOwnerToken;
+        if (location === undefined || owner === undefined)
+            return;
+        const ownerChanged = this.publishedOwnerToken !== undefined
+            && !sameOwnerToken(this.publishedOwnerToken, owner);
+        if (ownerChanged) {
+            // A new owner token can refer to an empty or replaced Store. The cached
+            // descriptor was written under the previous lease and must not force a
+            // Renew against a row that no longer exists.
+            this.publishedMeshNodeDescriptors.clear();
+        }
+        for (const [meshName, registration] of this.options.registration.spotNodes) {
+            if (selectedMeshName !== undefined && meshName !== selectedMeshName)
+                continue;
+            const node = this.meshNodes.get(meshName);
+            if (node === undefined)
+                continue;
+            const status = node.status();
+            const userSpots = effectiveUserSpotRegistrations(registration);
+            const instanceSpots = effectiveInstanceSpotRegistrations(registration);
+            const actors = effectiveActorRegistrations(registration);
+            const capabilities = [
+                ...userSpots.map(([stableType, factory]) => objectCapability('user_spot', stableType, factory)),
+                ...instanceSpots.map(([stableType, factory]) => objectCapability('instance_spot', stableType, factory)),
+                ...actors.map(([stableType, factory]) => objectCapability('actor', stableType, factory))
+            ].sort((left, right) => {
+                const kindOrder = left.objectKind.localeCompare(right.objectKind);
+                return kindOrder !== 0
+                    ? kindOrder
+                    : left.stableType.localeCompare(right.stableType);
+            });
+            const current = this.publishedMeshNodeDescriptors.get(meshName);
+            const previousRevision = this.descriptorRevisionByMesh.get(meshName) ?? 0n;
+            const descriptor = {
+                meshName,
+                rid: status.routingId,
+                lifecycleGeneration: status.lifecycleGeneration,
+                descriptorRevision: maxBigInt(previousRevision, current?.descriptorRevision ?? 0n) + 1n,
+                // The raw MeshNode resolves port zero and applies AdvertiseHost once.
+                // Discovery and RouteMesh hello must publish that same public identity.
+                endpoint: status.localEndpoint,
+                objectRole: effectiveObjectRole(registration),
+                entrySpotId: this.entrySpotId(meshName, registration),
+                placementWeight: this.placementWeight(meshName),
+                populationCapacity: {
+                    actors: {
+                        active: current?.populationCapacity.actors.active ?? 0,
+                        reserved: current?.populationCapacity.actors.reserved ?? 0,
+                        limit: registration.actorLimit ?? 0
+                    },
+                    spots: {
+                        active: current?.populationCapacity.spots.active ?? 0,
+                        reserved: current?.populationCapacity.spots.reserved ?? 0,
+                        limit: registration.spotLimit ?? 0
+                    },
+                    spotTypes: capabilities
+                        .filter(capability => capability.objectKind !== 'actor')
+                        .map(capability => {
+                        const previous = current?.populationCapacity.spotTypes.find(candidate => candidate.objectKind === capability.objectKind
+                            && candidate.stableType === capability.stableType);
+                        return {
+                            objectKind: capability.objectKind,
+                            stableType: capability.stableType,
+                            active: previous?.active ?? 0,
+                            reserved: previous?.reserved ?? 0,
+                            limit: capability.limit
+                        };
+                    })
+                },
+                activationConcurrency: {
+                    active: this.options.instanceActivationConcurrencyProvider?.(meshName).active
+                        ?? current?.activationConcurrency.active
+                        ?? 0,
+                    limit: this.options.instanceActivationConcurrencyProvider?.(meshName).limit
+                        ?? registration.activationConcurrencyLimit
+                        ?? 128
+                },
+                channelWeights: Object.fromEntries(this.serverChannels(meshName)
+                    .map(([channelName, channel]) => [
+                    channelName,
+                    state === contracts_1.ZLinkFrameworkRuntimeState.Draining
+                        ? 0
+                        : this.effectiveChannelWeight(meshName, channelName, channel.weight ?? 100)
+                ])),
+                applicationVersion: this.options.registration.applicationVersion,
+                maintenanceWave: this.options.registration.maintenanceWave,
+                spotTypes: [
+                    ...userSpots.map(([stableType]) => stableType),
+                    ...instanceSpots.map(([stableType]) => stableType),
+                    ...(registration.entrySpotType === undefined
+                        ? []
+                        : [registration.entrySpotType.name])
+                ]
+                    .sort(),
+                objectCapabilities: capabilities,
+                state,
+                securityIdentity: 'default',
+            };
+            const result = await location.runtime.writeMeshNode(descriptor, ownerChanged
+                ? Locations_1.ZLinkLocationWriteIntent.Renew
+                : current === undefined
+                    ? Locations_1.ZLinkLocationWriteIntent.NewClaim
+                    : Locations_1.ZLinkLocationWriteIntent.Renew, signal);
+            if (result.status !== Locations_1.ZLinkLocationWriteStatus.Stored) {
+                throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' descriptor publication failed: ${result.status}.`);
+            }
+            this.publishedMeshNodeDescriptors.set(meshName, {
+                ...descriptor,
+                ownerId: location.runtime.currentOwnerToken.ownerId,
+                leaseGeneration: location.runtime.currentOwnerToken.leaseGeneration,
+                updatedAt: result.updatedAt
+            });
+            this.descriptorRevisionByMesh.set(meshName, descriptor.descriptorRevision);
+        }
+        this.publishedOwnerToken = owner;
+    }
+    async reconcileAndPublishMeshNodeState(state, meshName, signal) {
+        const location = this.locationAutoConnect;
+        const node = this.meshNodes.get(meshName);
+        if (location === undefined || node === undefined)
+            return;
+        const status = node.status();
+        const owner = location.runtime.currentOwnerToken;
+        if (owner === undefined)
+            return;
+        const current = (await location.runtime.listLiveMeshNodes(meshName, signal))
+            .find((descriptor) => String(descriptor.rid) === String(status.routingId)
+            && descriptor.lifecycleGeneration === status.lifecycleGeneration
+            && descriptor.ownerId === owner.ownerId
+            && descriptor.leaseGeneration === owner.leaseGeneration);
+        if (current !== undefined) {
+            this.publishedMeshNodeDescriptors.set(meshName, current);
+            this.descriptorRevisionByMesh.set(meshName, maxBigInt(this.descriptorRevisionByMesh.get(meshName) ?? 0n, current.descriptorRevision));
+            this.publishedOwnerToken = owner;
+        }
+        await this.publishMeshNodeState(state, signal, meshName);
+    }
+    entrySpotId(meshName, registration) {
+        if (effectiveObjectRole(registration) !== contracts_1.ZLinkObjectRole.Server
+            || registration.entrySpotType === undefined) {
+            return undefined;
+        }
+        let entrySpotId = this.entrySpotIds.get(meshName);
+        if (entrySpotId !== undefined)
+            return entrySpotId;
+        const prefix = registration.routingIdPrefix ?? meshName;
+        entrySpotId = createFrameworkEntrySpotId(prefix);
+        this.entrySpotIds.set(meshName, entrySpotId);
+        return entrySpotId;
+    }
+    get meshNodesByName() {
+        return this.meshNodes;
+    }
+    meshNode(meshName) {
+        return this.meshNodes.get(meshName);
+    }
+    async sendMessageFollowNotification(sourceNodeRid, targetNodeRid, record) {
+        for (const node of this.meshNodes.values()) {
+            if (!(0, routing_id_1.routingIdsEqual)(node.status().routingId, sourceNodeRid))
+                continue;
+            if (node.sendMessageFollowNotification === undefined)
+                return false;
+            return await node.sendMessageFollowNotification(targetNodeRid, record);
+        }
+        return false;
+    }
+    entrySpotIdForMesh(meshName) {
+        const registration = this.options.registration.spotNodes.get(meshName);
+        return registration === undefined
+            ? undefined
+            : this.entrySpotId(meshName, registration);
+    }
+    meshNodeDescriptor(meshName) {
+        return this.publishedMeshNodeDescriptors.get(meshName);
+    }
+    placementWeight(meshName) {
+        const registration = this.options.registration.spotNodes.get(meshName);
+        if (registration === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Mesh '${meshName}' is not registered.`);
+        }
+        return this.runtimePlacementWeights.get(meshName)
+            ?? registration.placementWeight
+            ?? 100;
+    }
+    channelWeight(channelName) {
+        const match = this.resolveChannel(channelName);
+        return this.effectiveChannelWeight(match.meshName, channelName, match.configuredWeight);
+    }
+    setRuntimePlacementWeight(meshName, weight) {
+        const node = this.meshNodes.get(meshName);
+        if (node === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Mesh '${meshName}' runtime placement weight requires a started MeshNode.`);
+        }
+        const validated = requirePublicRuntimeWeight(weight, 'Placement weight');
+        if (this.placementWeight(meshName) === validated)
+            return;
+        this.runtimePlacementWeights.set(meshName, validated);
+        this.scheduleRuntimeWeightPublication(meshName, async () => {
+            await node.setPlacementWeight(validated);
+        });
+    }
+    setRuntimeChannelWeight(channelName, weight) {
+        const match = this.resolveChannel(channelName);
+        const node = this.meshNodes.get(match.meshName);
+        if (node === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Channel '${channelName}' runtime weight requires a started MeshNode.`);
+        }
+        const validated = requirePublicRuntimeWeight(weight, 'Channel weight');
+        if (this.effectiveChannelWeight(match.meshName, channelName, match.configuredWeight) === validated)
+            return;
+        let weights = this.runtimeChannelWeights.get(match.meshName);
+        if (weights === undefined) {
+            weights = new Map();
+            this.runtimeChannelWeights.set(match.meshName, weights);
+        }
+        weights.set(channelName, validated);
+        this.scheduleRuntimeWeightPublication(match.meshName, async () => {
+            await node.setChannelWeight(channelName, validated);
+        });
+    }
+    waitForRuntimeWeightPublication() {
+        return this.runtimeWeightPublication;
+    }
+    meshCompletionTable(meshName) {
+        return this.meshCompletions.get(meshName);
+    }
+    get primaryMeshNode() {
+        return this.options.primaryMeshName === undefined
+            ? this.meshNodes.values().next().value
+            : this.meshNodes.get(this.options.primaryMeshName);
+    }
+    effectiveChannelWeight(meshName, channelName, configuredWeight) {
+        return this.runtimeChannelWeights.get(meshName)?.get(channelName) ?? configuredWeight;
+    }
+    resolveChannel(channelName) {
+        const matches = [...this.options.registration.spotNodes]
+            .flatMap(([meshName, registration]) => {
+            const channel = registration.meshChannels?.[channelName];
+            return channel === undefined
+                ? []
+                : [{ meshName, configuredWeight: channel.weight ?? 100 }];
+        });
+        if (matches.length === 0) {
+            throw new configuration_1.ZLinkConfigurationException(`RouteMesh channel '${channelName}' is not registered.`);
+        }
+        if (matches.length > 1) {
+            throw new configuration_1.ZLinkConfigurationException(`RouteMesh channel '${channelName}' is registered in more than one Mesh.`);
+        }
+        return matches[0];
+    }
+    scheduleRuntimeWeightPublication(meshName, applyWeight) {
+        const publish = this.runtimeWeightPublication.catch(() => undefined).then(async () => {
+            await applyWeight();
+            const state = this.publishedMeshNodeDescriptors.get(meshName)?.state
+                ?? contracts_1.ZLinkFrameworkRuntimeState.Serving;
+            await this.publishMeshNodeState(state, undefined, meshName);
+        });
+        this.runtimeWeightPublication = publish;
+        if (this.options.detachedTaskRunner !== undefined) {
+            this.options.detachedTaskRunner.runDetached(`RouteMesh '${meshName}' runtime weight publication`, async () => await publish);
+        }
+        else {
+            void publish.catch(() => undefined);
+        }
+    }
+    get primaryMeshCompletions() {
+        const meshName = this.options.primaryMeshName ?? this.meshNodes.keys().next().value;
+        return meshName === undefined ? undefined : this.meshCompletions.get(meshName);
+    }
+    async notifyEntrySpotActorCreated(nodeRid, actor, createRequest, signal) {
+        let activation = [...this.entryActivations.values()].find((entryActivation) => (0, routing_id_1.routingIdsEqual)(entryActivation.nodeRid, nodeRid));
+        if (activation === undefined) {
+            for (const [meshName, node] of this.meshNodes) {
+                if (!(0, routing_id_1.routingIdsEqual)(node.status().routingId, nodeRid))
+                    continue;
+                if (this.options.registration.spotNodes.get(meshName)?.entrySpotType === undefined)
+                    continue;
+                await this.ensureEntryActivation(meshName);
+                activation = this.entryActivations.get(meshName);
+                break;
+            }
+        }
+        return activation?.notifyCreateActor(actor, createRequest, signal);
+    }
+    notifyPrimaryEntrySpotActorJoined(actor, signal) {
+        const activation = this.primaryEntryActivation();
+        return activation?.notifyJoinActor(actor, signal) ?? Promise.resolve();
+    }
+    notifyPrimaryEntrySpotActorLeft(actor, signal, actorRef, membershipEpoch) {
+        const activation = this.primaryEntryActivation();
+        return activation?.notifyLeaveActor(actor, signal, actorRef, membershipEpoch) ?? Promise.resolve();
+    }
+    notifyPrimaryEntrySpotActorDisconnected(actor, signal) {
+        const activation = this.primaryEntryActivation();
+        return activation?.notifyDisconnectActor(actor, signal) ?? Promise.resolve();
+    }
+    async notifyEntrySpotActorDisconnected(meshName, actor, signal) {
+        await this.ensureEntryActivation(meshName);
+        await this.entryActivations.get(meshName)?.notifyDisconnectActor(actor, signal);
+    }
+    serverChannels(meshName) {
+        return Object.entries(this.options.registration.spotNodes.get(meshName)?.meshChannels ?? {})
+            .filter(([, channel]) => channel.server === true);
+    }
+    async dispose(signal, deadline) {
+        this.disposed = true;
+        const autoConnectLoops = [...this.autoConnectLoops];
+        const entryActivations = [...this.entryActivations.values()];
+        const meshPumps = [...this.meshPumps.values()];
+        const meshNodes = [...this.meshNodes.values()];
+        const meshCompletions = [...this.meshCompletions.values()];
+        this.entryActivations.clear();
+        this.autoConnectLoops.length = 0;
+        this.meshPumps.clear();
+        const publishers = [...this.publishers.values()];
+        this.publishers.clear();
+        this.rejectPublishSlotWaiters(runtimeShutdownError());
+        const errors = [];
+        const settle = async (operations) => {
+            const results = await Promise.allSettled(operations);
+            errors.push(...results
+                .filter((result) => result.status === 'rejected')
+                .map((result) => result.reason));
+        };
+        await settle(publishers.map(async (publisher) => publisher.close()));
+        await settle(autoConnectLoops.map((loop) => loop.prepareTransportShutdown()));
+        await settle(entryActivations.reverse().map((activation) => activation.dispose(deadline)));
+        await settle(meshPumps.reverse().map((pump) => pump.dispose()));
+        await settle(meshNodes.reverse().map(async (node) => {
+            node.shutdown(1000);
+            node.close();
+        }));
+        for (const completions of meshCompletions) {
+            completions.dispose();
+        }
+        this.meshNodes.clear();
+        this.meshCompletions.clear();
+        await settle(autoConnectLoops.map((loop) => loop.finishTransportShutdown(signal)));
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, 'SPOT node runtime cleanup failed.');
+    }
+    async dispatchMeshRecord(meshName, owner, record) {
+        if (record.kind === service_runtime_contracts_1.ReceiveKind.Completion) {
+            (0, execution_1.requireZLinkInfrastructureExecutionArea)();
+            const completions = this.meshCompletions.get(meshName);
+            if (completions === undefined) {
+                throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' received a completion before its completion table was registered.`);
+            }
+            completions.complete(record);
+            return;
+        }
+        const node = this.meshNodes.get(meshName);
+        const targetsEntrySpot = owner.spotId === null
+            || (node !== undefined && (0, routing_id_1.routingIdsEqual)(owner.spotId, String(node.status().routingId)));
+        if (targetsEntrySpot && (record.kind === service_runtime_contracts_1.ReceiveKind.ActorSend
+            || record.kind === service_runtime_contracts_1.ReceiveKind.ActorRequest
+            || record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend
+            || record.kind === service_runtime_contracts_1.ReceiveKind.SpotRequest
+            || record.kind === service_runtime_contracts_1.ReceiveKind.SpotMulticast)) {
+            await this.ensureEntryActivation(meshName);
+        }
+        const dispatcher = this.options.meshRecordDispatcher;
+        if (dispatcher === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' received a record before its framework dispatcher was registered.`);
+        }
+        await dispatcher(meshName, owner, record);
+    }
+    async dispatchEntrySpotRecord(meshName, owner, record) {
+        if (record.kind !== service_runtime_contracts_1.ReceiveKind.SpotSend
+            && record.kind !== service_runtime_contracts_1.ReceiveKind.SpotRequest
+            && record.kind !== service_runtime_contracts_1.ReceiveKind.SpotMulticast) {
+            return false;
+        }
+        await this.ensureEntryActivation(meshName);
+        const activation = this.entryActivations.get(meshName);
+        if (activation === undefined
+            || owner.spotId === null
+            || activation.spotId !== owner.spotId) {
+            return false;
+        }
+        if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotMulticast) {
+            if (record.topic === null || record.topic.length === 0) {
+                throw new configuration_1.ZLinkConfigurationException('MeshNode Entry Spot multicast record is missing its topic.');
+            }
+            await activation.dispatchSubscriptionRecord(record.topic, record.parts, record.sourceNodeRid);
+            return true;
+        }
+        const envelope = (0, channel_envelope_1.decodeChannelEnvelope)(record.parts, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        const codecs = { serializers: this.options.registration.messageSerializers };
+        const decodePayload = () => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
+        const context = {
+            channelName: envelope.header.channelName,
+            contentType: envelope.header.contentType
+        };
+        if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend) {
+            await activation.dispatchPacketEncoded(envelope.packetName, decodePayload, context, false);
+            return true;
+        }
+        try {
+            const response = await activation.dispatchPacketEncoded(envelope.packetName, decodePayload, context, true);
+            requireEntrySpotReply(record.reply((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+        }
+        catch (error) {
+            requireEntrySpotReply(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error)));
+        }
+        return true;
+    }
+    async ensureEntryActivation(spotNodeName) {
+        if (this.entryActivations.has(spotNodeName)) {
+            return;
+        }
+        const pending = this.entryActivationStarts.get(spotNodeName);
+        if (pending !== undefined) {
+            await pending;
+            return;
+        }
+        const spotNode = this.options.registration.spotNodes.get(spotNodeName);
+        const node = this.meshNodes.get(spotNodeName);
+        if (spotNode === undefined || node === undefined || spotNode.entrySpotType === undefined) {
+            return;
+        }
+        const start = this.initializeEntrySpot(spotNodeName, node, spotNode);
+        this.entryActivationStarts.set(spotNodeName, start);
+        try {
+            await start;
+        }
+        finally {
+            if (this.entryActivationStarts.get(spotNodeName) === start) {
+                this.entryActivationStarts.delete(spotNodeName);
+            }
+        }
+    }
+    async initializeEntrySpot(spotNodeName, node, spotNode) {
+        if (spotNode.entrySpotType === undefined) {
+            return;
+        }
+        const activation = new spot_entry_activation_1.ZLinkEntrySpotActivation({
+            entrySpotType: spotNode.entrySpotType,
+            nativeSpot: node.entrySpot(),
+            nativeNode: node,
+            createReceived: () => this.options.backendAdapterFactory.createReceived(),
+            createTopicMessage: () => this.options.backendAdapterFactory.createTopicMessage(),
+            nodeRid: String(node.status().routingId),
+            spotNodeName,
+            providerResolver: this.options.providerResolver,
+            channelClient: this.options.channelClient,
+            fanoutClient: this.options.fanoutClient,
+            spotPublisherClient: this.options.spotPublisherClient,
+            routedTransport: this.options.routedTransport,
+            spotRouterChannelIdForMesh: this.options.spotRouterChannelIdForMesh,
+            channelMeshNameForChannel: (channelName) => resolveChannelMeshName(this.options.registration, channelName),
+            timerHandlers: spotNode.entrySpotTimerHandlers,
+            packetHandlers: spotNode.entrySpotPacketHandlers,
+            subscriptionHandlers: spotNode.entrySpotSubscriptionHandlers,
+            actorSendHandlers: spotNode.entrySpotActorSendHandlers,
+            actorRequestHandlers: spotNode.entrySpotActorRequestHandlers,
+            messageSerializers: this.options.registration.messageSerializers,
+            entryActorRuntime: this.options.entryActorRuntime,
+            actorTransferRuntime: this.options.actorTransferRuntime,
+            boundSessionRuntime: this.options.boundSessionRuntime,
+            actorHandoffRuntime: this.options.actorHandoffRuntime,
+            detachedTaskRunner: this.options.detachedTaskRunner,
+            dispatchErrors: this.options.dispatchErrors,
+            runtimeEventPublisher: this.options.runtimeEventPublisher,
+            metrics: this.options.metrics
+        });
+        try {
+            await activation.create();
+            await activation.configure();
+            await activation.initialize();
+            this.entryActivations.set(spotNodeName, activation);
+        }
+        catch (error) {
+            try {
+                await activation.dispose();
+            }
+            catch (disposeError) {
+                throw new AggregateError([error, disposeError], `Entry Spot '${spotNodeName}' materialization cleanup failed.`);
+            }
+            throw error;
+        }
+    }
+    primaryEntryActivation() {
+        return this.entryActivations.values().next().value;
+    }
+    async dispatchEntryActorPacket(actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        let activation = this.primaryEntryActivation();
+        if (activation === undefined) {
+            const candidates = this.options.primaryMeshName === undefined
+                ? this.options.registration.spotNodes
+                : new Map([[this.options.primaryMeshName, this.options.registration.spotNodes.get(this.options.primaryMeshName)]]);
+            for (const [spotNodeName, spotNode] of candidates) {
+                if (spotNode === undefined) {
+                    continue;
+                }
+                if (spotNode.entrySpotType === undefined) {
+                    continue;
+                }
+                await this.ensureEntryActivation(spotNodeName);
+                activation = this.entryActivations.get(spotNodeName);
+                if (activation !== undefined) {
+                    break;
+                }
+            }
+        }
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Entry Spot actor packet dispatch requires an Entry Spot.');
+        }
+        return await activation.dispatchActorPacket({
+            actorId,
+            parts,
+            returnResponse,
+            remoteBoundSessionTarget,
+            fallbackActorRef,
+            requestTerminal,
+            messageFollowOrigin
+        });
+    }
+    async dispatchEntryActorJoin(meshName, actor, handoffBacklog = []) {
+        await this.ensureEntryActivation(meshName);
+        const activation = this.entryActivations.get(meshName);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Entry Spot actor join requires an Entry Spot for MeshNode '${meshName}'.`);
+        }
+        await activation.commitServiceActorJoin(actor, handoffBacklog);
+    }
+    publish(meshName, channelName, topic, packetName, event, signal, metadata = EMPTY_SPOT_METADATA) {
+        if (this.disposed) {
+            return Promise.reject(runtimeShutdownError());
+        }
+        if (signal?.aborted === true) {
+            return Promise.reject(signal.reason ?? (0, abort_1.createAbortError)());
+        }
+        const publisher = this.publishers.get(meshName);
+        if (publisher === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`RouteMesh '${meshName}' publisher is not started.`);
+        }
+        const sendTimeoutMs = this.options.registration.spotNodes
+            .get(meshName)?.publisherConfig?.sendTimeoutMs ?? 1000;
+        const slot = this.acquirePublishSlot(meshName, sendTimeoutMs, signal);
+        if (slot === false) {
+            // The bounded executor-admission tokens are exhausted. Do not retain the
+            // payload, cancellation state, or a timer for this hard-overload call.
+            return Promise.resolve(this.publishTimedOut());
+        }
+        if (slot === true) {
+            return this.executePublish(publisher, meshName, channelName, topic, packetName, event, metadata);
+        }
+        return slot.then((acquired) => acquired
+            ? this.executePublish(publisher, meshName, channelName, topic, packetName, event, metadata)
+            : this.publishTimedOut());
+    }
+    async executePublish(publisher, meshName, channelName, topic, packetName, event, metadata) {
+        // The slot is the source-local admission boundary. Once publishAsync takes
+        // the owned frames, target processing cannot change the caller terminal.
+        // Call-scoped flow (spec 27 §4): the fanout envelope flow pair does not
+        // outlive this publish call.
+        try {
+            const parts = (0, flow_context_1.runWithOutboundFlow)(this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, () => (0, channel_envelope_1.encodeChannelPublishEnvelopeParts)(channelName, topic, packetName, event, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, metadata));
+            const processing = publisher.publishAsync(channelName, topic, parts, undefined, undefined);
+            void Promise.resolve(processing).catch(() => undefined);
+            return Promise.resolve({ status: submission_result_1.ZLinkSubmitStatus.Submitted });
+        }
+        finally {
+            this.releasePublishSlot(meshName);
+        }
+    }
+    tryPublish(meshName, channelName, topic, packetName, event, metadata = EMPTY_SPOT_METADATA) {
+        return this.publishWithFlags(meshName, channelName, topic, packetName, event, ZLINK_SEND_DONT_WAIT, metadata);
+    }
+    publishWithFlags(meshName, channelName, topic, packetName, event, flags, metadata) {
+        if (this.disposed) {
+            throw runtimeShutdownError();
+        }
+        const publisher = this.publishers.get(meshName);
+        if (publisher === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`RouteMesh '${meshName}' publisher is not started.`);
+        }
+        const parts = (0, flow_context_1.runWithOutboundFlow)(this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, () => (0, channel_envelope_1.encodeChannelPublishEnvelopeParts)(channelName, topic, packetName, event, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, metadata));
+        try {
+            publisher.publish(channelName, topic, parts, { flags });
+            return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+        }
+        catch (error) {
+            if ((0, runtime_values_1.isZLinkBackendResultError)(error) && error.operation === 'submit') {
+                return { status: mapPublishSubmitStatus(error.result) };
+            }
+            throw error;
+        }
+    }
+    acquirePublishSlot(meshName, timeoutMs, signal) {
+        if (!this.activePublishes.has(meshName)) {
+            this.activePublishes.add(meshName);
+            return true;
+        }
+        const waiterCapacity = Math.max(1, this.options.registration.spotNodes
+            .get(meshName)?.publisherConfig?.sendHighWaterMark ?? 1);
+        const queue = this.publishSlotWaiters.get(meshName) ?? {
+            waiters: [],
+            head: 0,
+            count: 0
+        };
+        if (queue.count >= waiterCapacity) {
+            // This call has no bounded executor-admission token. Fail without
+            // retaining its payload in a pending work queue.
+            return false;
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                reject,
+                signal,
+                settled: false
+            };
+            if (timeoutMs !== -1) {
+                waiter.deadlineMs = performance.now() + Math.max(0, timeoutMs);
+            }
+            queue.waiters.push(waiter);
+            queue.count += 1;
+            this.publishSlotWaiters.set(meshName, queue);
+            if (timeoutMs !== -1) {
+                waiter.timeout = setTimeout(() => this.settlePublishSlotWaiter(meshName, waiter, false), Math.max(0, timeoutMs));
+            }
+            if (signal !== undefined) {
+                waiter.abortHandler = () => this.rejectPublishSlotWaiter(meshName, waiter, signal.reason ?? (0, abort_1.createAbortError)());
+                signal.addEventListener('abort', waiter.abortHandler, { once: true });
+            }
+        });
+    }
+    publishTimedOut() {
+        return { status: submission_result_1.ZLinkSubmitStatus.TimedOut };
+    }
+    releasePublishSlot(meshName) {
+        const queue = this.publishSlotWaiters.get(meshName);
+        while (queue !== undefined && queue.count > 0) {
+            const waiter = this.takePublishSlotWaiter(queue);
+            if (waiter === undefined)
+                continue;
+            if (waiter.settled)
+                continue;
+            if (waiter.deadlineMs !== undefined && performance.now() >= waiter.deadlineMs) {
+                this.cleanupPublishSlotWaiter(waiter);
+                waiter.settled = true;
+                waiter.resolve(false);
+                continue;
+            }
+            this.cleanupPublishSlotWaiter(waiter);
+            waiter.settled = true;
+            waiter.resolve(true);
+            if (queue.count === 0)
+                this.publishSlotWaiters.delete(meshName);
+            return;
+        }
+        this.publishSlotWaiters.delete(meshName);
+        this.activePublishes.delete(meshName);
+    }
+    settlePublishSlotWaiter(meshName, waiter, acquired) {
+        if (waiter.settled)
+            return;
+        waiter.settled = true;
+        this.removePublishSlotWaiter(meshName, waiter);
+        this.cleanupPublishSlotWaiter(waiter);
+        waiter.resolve(acquired);
+    }
+    rejectPublishSlotWaiter(meshName, waiter, error) {
+        if (waiter.settled)
+            return;
+        waiter.settled = true;
+        this.removePublishSlotWaiter(meshName, waiter);
+        this.cleanupPublishSlotWaiter(waiter);
+        waiter.reject(error);
+    }
+    removePublishSlotWaiter(meshName, waiter) {
+        const queue = this.publishSlotWaiters.get(meshName);
+        if (queue === undefined)
+            return;
+        const index = queue.waiters.indexOf(waiter, queue.head);
+        if (index >= 0) {
+            queue.waiters[index] = undefined;
+            queue.count -= 1;
+            this.compactPublishSlotWaiters(queue);
+        }
+        if (queue.count === 0)
+            this.publishSlotWaiters.delete(meshName);
+    }
+    cleanupPublishSlotWaiter(waiter) {
+        if (waiter.timeout !== undefined)
+            clearTimeout(waiter.timeout);
+        if (waiter.abortHandler !== undefined) {
+            waiter.signal?.removeEventListener('abort', waiter.abortHandler);
+        }
+    }
+    rejectPublishSlotWaiters(error) {
+        for (const [meshName, queue] of this.publishSlotWaiters) {
+            let waiter;
+            while ((waiter = this.takePublishSlotWaiter(queue)) !== undefined) {
+                this.rejectPublishSlotWaiter(meshName, waiter, error);
+            }
+            this.publishSlotWaiters.delete(meshName);
+        }
+        this.activePublishes.clear();
+    }
+    takePublishSlotWaiter(queue) {
+        while (queue.head < queue.waiters.length && queue.waiters[queue.head] === undefined) {
+            queue.head += 1;
+        }
+        const waiter = queue.waiters[queue.head];
+        if (waiter === undefined)
+            return undefined;
+        queue.waiters[queue.head] = undefined;
+        queue.head += 1;
+        queue.count -= 1;
+        this.compactPublishSlotWaiters(queue);
+        return waiter;
+    }
+    compactPublishSlotWaiters(queue) {
+        if (queue.count === 0) {
+            queue.waiters.length = 0;
+            queue.head = 0;
+        }
+        else if (queue.head >= 1024 && queue.head * 2 >= queue.waiters.length) {
+            queue.waiters.splice(0, queue.head);
+            queue.head = 0;
+        }
+    }
+}
+exports.ZLinkSpotNodeRuntimeManager = ZLinkSpotNodeRuntimeManager;
+function runtimeShutdownError() {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown, 'SPOT publisher runtime is shutting down.');
+}
+function createFrameworkEntrySpotId(prefix) {
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(prefix)) {
+        throw new configuration_1.ZLinkConfigurationException('Entry Spot diagnostic prefix must contain 1..64 ASCII letters, digits, dot, underscore, or hyphen.');
+    }
+    return `${prefix}-entry-${(0, node_crypto_1.randomUUID)()}`;
+}
+function resolveChannelMeshName(registration, channelName) {
+    const matches = [...registration.spotNodes.entries()]
+        .filter(([, node]) => Object.prototype.hasOwnProperty.call(node.meshChannels ?? {}, channelName))
+        .map(([meshName]) => meshName);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function mapPublishSubmitStatus(result) {
+    switch (result) {
+        case runtime_values_1.SubmitResult.Ok:
+            return submission_result_1.ZLinkSubmitStatus.Submitted;
+        case runtime_values_1.SubmitResult.Backpressured:
+        case runtime_values_1.SubmitResult.NotAdmitted:
+            return submission_result_1.ZLinkSubmitStatus.Backpressured;
+        case runtime_values_1.SubmitResult.NotFound:
+            // A publish with no matching subscriber is a successful zero-recipient
+            // operation, not an operation-specific not-found failure.
+            return submission_result_1.ZLinkSubmitStatus.Submitted;
+        case runtime_values_1.SubmitResult.NotConnected:
+            return submission_result_1.ZLinkSubmitStatus.RouteNotConnected;
+        case runtime_values_1.SubmitResult.Terminated:
+        case runtime_values_1.SubmitResult.InvalidHandle:
+            return submission_result_1.ZLinkSubmitStatus.Shutdown;
+        default:
+            throw new configuration_1.ZLinkConfigurationException(`Logical Multicast failed with submit result '${result}'.`);
+    }
+}
+function requireEntrySpotReply(result) {
+    if (result !== runtime_values_1.SubmitResult.Ok) {
+        throw new configuration_1.ZLinkConfigurationException(`MeshNode Entry Spot reply was not accepted (submit result ${result}).`);
+    }
+}
+function requirePublicRuntimeWeight(value, label) {
+    if (!Number.isInteger(value) || value < 0 || value > 10_000) {
+        throw new configuration_1.ZLinkConfigurationException(`${label} must be an integer in 0..10000.`);
+    }
+    return value;
+}
+function effectiveUserSpotRegistrations(registration) {
+    const registrations = new Map(Object.entries(registration.spotFactoryRegistrations ?? {}));
+    const explicitImplementations = new Set(Object.values(registration.spotFactoryRegistrations ?? {})
+        .map(({ implementation }) => implementation));
+    for (const implementation of registration.spotFactories ?? []) {
+        // `spotFactories` is also retained as the runtime implementation set.
+        // When the caller supplied an explicit stable type, the implementation
+        // must not be projected a second time under its JavaScript class name.
+        // That legacy alias advertises a different public placement type and can
+        // make location routing disagree with the configured factory.
+        if (!explicitImplementations.has(implementation) && !registrations.has(implementation.name)) {
+            registrations.set(implementation.name, {});
+        }
+    }
+    return [...registrations];
+}
+function effectiveInstanceSpotRegistrations(registration) {
+    const registrations = new Map(Object.entries(registration.instanceSpotFactoryRegistrations ?? {}));
+    for (const stableType of Object.keys(registration.instanceSpotFactories ?? {})) {
+        if (!registrations.has(stableType))
+            registrations.set(stableType, {});
+    }
+    return [...registrations];
+}
+function effectiveActorRegistrations(registration) {
+    const registrations = new Map(Object.entries(registration.actorFactoryRegistrations ?? {}));
+    const legacy = registration.actorFactories instanceof Map
+        ? registration.actorFactories.keys()
+        : Object.keys(registration.actorFactories ?? {});
+    for (const stableType of legacy) {
+        if (!registrations.has(stableType))
+            registrations.set(stableType, {});
+    }
+    return [...registrations];
+}
+function effectiveObjectRole(registration) {
+    if (registration.objectRole === 'server')
+        return contracts_1.ZLinkObjectRole.Server;
+    if (registration.objectRole === 'client')
+        return contracts_1.ZLinkObjectRole.Client;
+    return effectiveUserSpotRegistrations(registration).length > 0
+        || effectiveInstanceSpotRegistrations(registration).length > 0
+        || effectiveActorRegistrations(registration).length > 0
+        ? contracts_1.ZLinkObjectRole.Server
+        : contracts_1.ZLinkObjectRole.None;
+}
+function objectCapability(objectKind, stableType, factory) {
+    const policy = factory.relocation?.kind ?? 'disabled';
+    return {
+        objectKind,
+        stableType,
+        policy,
+        hasSnapshotAdapter: policy === 'snapshot',
+        limit: objectKind === 'actor'
+            ? 0
+            : factory.options?.stableTypeLimit ?? 0
+    };
+}
+function aggregatePlacementCapacity(actorLimit, spotLimit) {
+    const unlimited = 0x7fff_ffff;
+    const actors = actorLimit === 0 ? unlimited : actorLimit;
+    const spots = spotLimit === 0 ? unlimited : spotLimit;
+    return Math.min(unlimited, actors + spots);
+}
+function maxBigInt(left, right) {
+    return left > right ? left : right;
+}
+function sameOwnerToken(left, right) {
+    return left.ownerId === right.ownerId
+        && left.leaseGeneration === right.leaseGeneration;
+}